cthulhu/docs/testing/browser-ticking-pages.md

Ticking-page (incremental game) navigation

Perpetually updating pages recreate their accessible text leaves on a timer. The maintainer's 2026-11-03 debug log showed the same failure on three incremental games, which made arrow-key reading useless while focus (link/button) navigation still worked:

• Exotic Matter Dimensions: every Down paid a full recapture and re-spoke the first line (14 repeats of one counter line, moved=true), ending in "Could not find current location."
• Ordinal Pringles: 16 Downs re-spoke a single-letter fragment, then the focused anchor itself was destroyed and six consecutive moves reported "Could not find current location." until Tab supplied a new anchor. Moving among buttons was 1 ms; crossing the ticking static region cost a 20–25 ms recapture per key on a 129-node document.
• Prestige Tree: ~20 accessible-name events per second while idle. Speech coalescing already handled these; no change was needed there.

Root causes were positional, not per-game: the saved browse position was an AT-SPI object identity that Chromium retires on every tick, the generation-checked sibling boundaries retired with it, recovery restarted at the surviving parent's first line, and capture was keyed on the destroyed focus anchor so recapture itself failed with ErrObjectNotFound forever.

Changes

• Replacement recovery (internal/review/document_replacement.go) now also retains the child's index and the text parent's child count. When every saved sibling reference has retired but the same generation-checked parent still has the same child count, the child at the same index is the same navigation line (replaced-text-child-index in diagnostics). A changed count, or any saved sibling that still lives (reorder, single replaced neighbor), stays ambiguous and falls back to the surviving parent, as before. Activation never uses either recovery.
• Document capture for moves (captureDocumentForMove) falls back to the cursor's saved document when capture keyed on the focus anchor returns ErrObjectNotFound, so the existing anchor-recovery path can rebind focus within the same document generation.
• Down after structural navigation to a heading no longer descends into the heading's embedded link and repeats its title as a new line (internal/review/document_caret_line.go). The structural target's own first text range keeps the previous within-object line logic.
• Identical structural moves queued while the worker is busy coalesce into one batch (one sync, capture cycle, placement and result, full step count). Caret steps are excluded: queued character/word/line steps keep their own ordered results.

Caret validation on ticking text

A follow-up log showed residual traps at dense counter lines (Exotic Matter's "Progress to Luck Shards" repeated nine times, three location losses). Attempt errors were all identity/text/children invalidation — no stale-geometry errors — so this was not Xorg/Wayland degradation; the AT-SPI tree mutates identically under either backend. The trap: caret moves validated captured text/geometry freshness for every traversed node before committing, while the move's whole retry budget (one attempt plus two captures) races a game tick that re-invalidates text several times per second. Recovery succeeded on every attempt and still lost.

Caret validation (ValidateDocumentCaretRange) now tolerates text, geometry, and child-order staleness, because caret moves read text and line bounds live and generation-check every endpoint; identity, semantic snapshots (names are spoken from the snapshot), and hypertext embedded-object ranges stay strict. This deliberately changes the older contracts in TestDocumentCaretDefersUnrelatedUpdatesUntilTraversed and the children case of TestDocumentCaretKeepsOffsetAfterDocumentRefresh: dirty target text and changed child order no longer force a recapture before a caret move commits, and the tests now prove the live provider text is what the move reports. Structural navigation keeps strict validation everywhere. Capture root selection also learned to resolve a focus identity from retained document sources (a document root after a load may have no focus-event history). A dead browse focus recovers only through the root of the capture that retained that source; other tabs on the same application bus cannot supply its recovery anchor. Provider-side stalls remain possible: one log ends with two 15 s capture deadlines from an unresponsive game tab, which no validation change can fix.

Graph-guided follow-ups (Orca comparison)

A later comparison against knowledge graphs of Orca and at-spi2-core (verified in source) produced two more changes. First, index-based recovery now also covers recreated non-text children such as button rows (replaced-child / replaced-child-index), under the same bounded evidence as text leaves and without widening their stricter rules — Orca recovers removed children from parent plus removed index in the same spirit. Second, a bus whose document capture just missed its deadline is marked hung for a two-second cooldown (ErrProviderHung, announced as "Application is not responding."), so a frozen tab fails fast instead of stalling every following keypress; Orca likewise remembers hung objects briefly and propagates the mark to the application. The gate covers all document operations (reads, placement, activation, context), not just captures — a live freeze on switching to the Exotic Matter tab showed reads re-entering the stuck provider after the capture deadline — and speculative warm-up captures are capped at three seconds. One in-flight capture can still occupy the provider thread for its full deadline; the gates keep everything after it responsive.

Tab/workspace-switch retention

Returning to a browser tab or workspace used to pay a cold whole-document capture (2.9 s for a 4226-node YouTube page in the 2026-11-03 log) before the first keypress worked. Three causes stacked: load/tab resets bumped the document epoch and discarded the browse cursor, the adapter kept a single document tree slot so any other tab's capture evicted it, and with the root changed nativeRefresh had nothing to reuse.

Now the adapter retains a bounded LRU of per-root document trees, text trees, and native sources (rotateDocumentSlots, active plus three stashed), events keep invalidating stashed trees while inactive, and the worker retains a browse cursor per retained tree. A move first trials retained cursors (cheap in-memory syncs) before capturing, so an unchanged document resumes with no capture at all and a changed one recaptures warm (only dirty nodes re-read). Failed trials preserve the original cursor for recapture, including when its focused child was removed. Restoring the oldest retained slot at capacity removes it before stashing the active document, so restoration cannot evict its own target. Tab switches suspend instead of hard-resetting documents; page loads still hard-reset, and requests carry a load epoch so a cursor captured before a same-path load is never reused afterwards (TestWorkerDocumentLoadRetiresOutstandingResult still guards this). Load-complete and tab-select also enqueue a best-effort warm-up capture so even a first visit starts capturing before the first keypress.

Still deferred: subtree-scoped capture. The first-ever capture of a huge document remains whole-document (now usually hidden by warm-up), and a document that changed a lot while away still re-reads its dirty nodes over a full walk. The validation invariant (dirty traversed objects and ancestors must refresh before a move may skip them) is deliberate and covered by the replacement/generated-link fixtures. Revisit subtree capture only if large ticking documents still feel unresponsive after retention.

Automated checks (2026-11-03)

• New Go regressions, each observed failing before its fix: TestDocumentCaretRecoversRecreatedTextSiblings, TestDocumentCaretRecapturesThroughDocumentWhenFocusAnchorDies, TestDocumentCaretContinuesFromStructuralLinkedHeading, TestWorkerCoalescesQueuedIdenticalDocumentMoves, TestDocumentSlotsRetainTreesAcrossRoots, TestWorkerRetainsDocumentCursorsAcrossSwitches, TestWorkerWarmDocumentPreparesFirstMove, TestValidateDocumentCaretRangeToleratesTextAndGeometryStaleness, and TestDocumentCaretMoveCrossesTextInvalidatedLines.
• go test ./... -count=1 and go vet ./... pass. One sandbox-only exception: internal/speech unix-socket tests fail inside the restricted sandbox ("socket: operation not permitted") and pass outside it.
• go test -race ./internal/review/ ./internal/atspi/ ./internal/app/ -count=1 passes in the private native session.
• BenchmarkDocument* (200 ms, -benchmem) matches the medians in browser-navigation-performance.md (heading pair ≈ 0.036 ms, snapshot ≈ 5.9 ms, line assembly ≈ 3.5 ms at 10,000 nodes). Informational only.
• New native proof ticking (TestNativeBrowserTickingNavigation, plus tests/browser-ticking.html for manual runs) is registered in tests/native_browser.py and passes: Down moves visit rebuilt lines 1, 2, 3 in order across ticks, then reach the following button. The guarding proofs linkedheadings, dynamic, replacement, replaced-feed, generatedlinks, and document also pass. Getting there required a harness fix first: inside the private D-Bus session, AT-SPI activation delegated to a systemd user unit (org.freedesktop.systemd1 ... unit failed), which cannot work with a disposable runtime dir and must not be required on non-systemd systems. tests/native_browser.py now launches at-spi-bus-launcher --launch-immediately and at-spi2-registryd directly inside its private Xvfb/D-Bus session. The host session (compositor, buses, AT-SPI) is never touched. Observed but not addressed: empty fragment stops between the fixture's <br>-separated spans, a pre-existing line-assembly quirk.

Retention boundaries have focused regressions: TestDocumentSlotsRestoreOldestAtCapacity, TestRetainedCursorTrialKeepsDeadFocusInOriginalDocument, and TestRetainedDocumentRootDoesNotCrossTabsOnSameBus. The browser harness waits for daemon bus-name ownership without activating services, bounds each readiness query, and joins both daemons on startup failure. Run its startup checks with python3 tests/test_native_browser.py -v.

Live acceptance (pending, maintainer)

Do not replace the running reader without approval; build to a side path (e.g. /tmp/cthulhu-ticking) or rebuild through the usual switcher after review. With a fresh debug log:

1. Exotic Matter Dimensions and Ordinal Pringles: traverse the previously stuck regions by Down/Up only, reach a button, and activate it. Expect progressing distinct lines, no repeated counter line, and no "Could not find current location." Diagnostics should show replaced-text-child-index recoveries.
2. Prestige Tree: H/Down through the main view; idle name churn stays silent except for the focused control.
3. YouTube: H onto a video heading, then one Down. Expect the channel/meta line, not the title again as a link. Mash H three times during a slow load; expect one landing three headings on. Note your heading position, switch to another tab/workspace and back, then press H: expect to continue from the noted heading promptly, with no multi-second stall, instead of restarting from the top after a cold capture.
4. Compare log counters against the 2026-11-03 log: duplicate consecutive document-caret lines, location losses, recaptures per 100 commands.
5. Report audible speech and physical Braille separately from the automated results above.