Keep local HTML previews live across source changes

[yaacovcorcos]

Summary

Fixes local HTML previews that became stale or stopped reopening after their source file was edited, including atomic-save workflows that replace a file without changing its path.

• Watches the selected HTML entry and its inspected local resource graph, then prepares a fresh capability-backed revision when a source changes.
• Atomically swaps only after the new revision loads; a failed refresh leaves the last working page visible with a source-scoped actionable error.
• Keeps one logical tab per source, coalesces rapid saves, preserves the selected tab and focus, and cleans up retired runtimes, sessions, watchers, popups, and grants.
• Makes Reload and Retry re-prepare the source instead of reusing an obsolete inode-bound URL.
• Keeps interactive HTML network-sealed; only fully inspected static documents receive a reviewed external-resource allowlist.
• Binds reviewed-static HTML/XHTML/SVG bytes to SHA-256 and serves them from a post-validated immutable buffer, so concurrent rewrites cannot substitute uninspected executable bytes.

Exact integration state

• Base: 50a784f4825e6cee9a0eb0d8de6a79cd093803e1
• Candidate: 9aa3118cb38752542c872c6260fb42c31fe0b6f8
• Branch: fix/live-html-preview-refresh-20260725
• Current main was merged normally; no rebase or force-push.
• The integration retained the combined live-preview and authorized-Git RPC schemas. Aggregate ordering is intentional because the rightmost RPC group owns duplicate tags.
• Worktree and diff are clean.

Security and reliability closure

All validated P2 findings were fixed before publication of this head:

• Late refreshes cannot steal focus, recreate a closed source, overwrite a newer revision, or leak retired grants/sessions.
• Interactive documents never inherit the static external allowlist.
• Entry and linked active documents are inspected from exact positioned reads; short reads continue and premature EOF fails closed.
• Raw inspected bytes are SHA-256-bound to bigint device/inode/size/mtime/ctime metadata and canonical paths.
• Reviewed-static requests fully read bounded active documents, post-validate fingerprint and digest before headers, close the mutable descriptor, and serve full/range bodies only from immutable bytes.
• Same-inode and atomic replacements before preparation, between preparation and routing, after request fingerprinting, and between requests fail closed or trigger one complete bounded retry without consuming grant capacity.

Verification

Exact candidate 9aa3118cb38752542c872c6260fb42c31fe0b6f8 passed locally:

• bun run scient:upstream-check --intake
• Scient identity, format, lint with zero errors, and all typechecks
• complete bun run test matrix: 12/12 tasks
• desktop/web/CLI builds: 5/5 tasks
• release smoke
• stable Chromium browser suite: 365 passed, 19 skipped
• Linux geometry quarantine: 19 passed, 365 intentionally skipped
• full Inspector and HtmlArtifactPreview regression files: 59/59
• deterministic short-read, premature-EOF, atomic/same-inode mutation, linked active-document, full/range immutable-serving, retry, and no-capacity-leak proofs
• git diff --check; clean worktree; no generated artifacts

Exactly three fresh independent read-only final-head reviews completed after verification:

1. Correctness, reliability, concurrency, lifecycle, performance, regression risk: P0=0, P1=0, P2=0, P3=0.
2. Security, privacy, data loss, sessions, permissions, updater and release safety: P0=0, P1=0, P2=0, P3=0.
3. Architecture, maintainability, ownership, product design, interaction, accessibility and test proof: P0=0, P1=0, P2=0; P3=1 evidence limitation below.

No unresolved P0, P1, or P2 finding remains.

Limitations

• A dependency that did not exist during inspection, or lies beyond the bounded watcher budget, may require manual Reload unless another watched source changes. The entry HTML file is always watched.
• No fresh native screenshot, keyboard-assistive-technology, or screen-reader pass was performed on this final head to avoid disturbing the active desktop. Automated browser semantics, interaction, focus, and geometry coverage passed; the final security-only follow-up does not change UI.
• Cross-repository agent smoke was not run because provider, protocol, agent, approval, and shared runtime contracts are unaffected.

Rollback

Revert this PR's squash commit. There is no schema, data, credential, or migration rollback. Existing capability-backed one-shot preview behavior returns.

[yaacovcorcos]

Final integration refresh (2026-07-25): current main dab9b6d was merged normally into this branch; no rebase or force-push. Exact hosted head: 1ca2061. Focused desktop 17/17, server 18/18, web unit 51/51, and browser 25/25 passed. git diff --check passes and the task worktree is clean. Fresh hosted CI run https://github.com/ScientFactory/scient-desktop/actions/runs/30160244141 completed successfully, including format, lint, typecheck, full bun run test, stable browser, Linux geometry, desktop build/preload, release smoke, Linux and Windows HTML-preview smoke, and Windows process regression. No unresolved review threads remain. Existing documented manual limitations are unchanged and non-blocking. This candidate is integration-ready against main dab9b6d; this is not merge or release authorization.