feat(layout): add experimental cache-independent native preview scenes

[airmang]

The native desktop renderer needs a cache-independent scene API in the current core package. Add experimental body/document scenes with injected glyph metrics, supported table/picture/page-story geometry, detached session caches, and fail-closed unsupported results. Existing core source modules and default dependencies remain intact.

The document dispatcher parses through the guarded HWPX reader once. A synthetic table fixture exercises all four cells, cache poisoning/removal equivalence, detached cache results, missing-font failure, invalid modes, and the single-parse boundary. Invalid cache mode/capacity now raise structured HwpxValueError codes and context while remaining ValueError-compatible. The two modules have explicit core ownership rationales, both gradual type gates include them, and the generated coverage/documentation records are synchronized.

Validation at fd89cd8: all 13 latest-head PR checks passed. Python 3.10–3.14 each passed 6,739 tests with 89% coverage; the push runs also passed. Targeted local CI-fix tests passed 399 checks, with two existing skips and the existing Windows metadata-newline assertion excluded. Full configured mypy (123 files), Pyright, Ruff, coverage-ledger check, public hygiene and wheel build passed. Full Windows-library-suite success is not claimed.

Companion source PRs: airmang/python-hwpx-automation#171 and airmang/hwpx-plugins#60. The relocated Windows runtime passed real packaged MCP tests and retained 31-page PNG parity.

The Mac product build, installed-runtime checks and remote native file-click gate have passed. This remains a draft for the coordinated package release. No release versions change here. The existing 6.8.0 public wheel must not be assumed to contain the new scene API.

Mac product-build update: #467 (comment)
The optional component is now 0.1.9/v7 at 2ce7993 to distinguish its install cache from the prototype. Core/automation development code was used together. Public release versions and the native-preview dependency floor still need coordinated assignment; this PR remains draft.

Native remote-client follow-up (2026-10-15): user-confirmed table display is matched to the actual Mac-host 0.1.9 executable, displayed PNG and package hashes. The Mac product native gate is complete for this SSH-connected environment. Release versions/floors and publication remain pending; draft status is unchanged.

[airmang]

Core-specific result: 75 scene/cache/layout tests passed at fd89cd8.

Mac product-build validation update (Apple Silicon, macOS 26.5.1):

• Installed the coordinated development core/automation sources; the frozen archive contains the new core scene modules and hwpx_automation.preview_runtime, rather than the prototype's top-level runtime.
• Native component 0.1.9 uses a distinct cache and v7 UI resource (v2–v6 aliases retained), in plugin commit 2ce7993. All 222 installed files match the assembled package hashes; renderer, server and UI differ from the old 0.1.8 artifacts.
• Source/package/installed MCP checks each pass 7 tests, including Unicode/spaced paths, three independent leases, saved-file updates, incomplete-save recovery, authorization denial, PNG delivery and close. The table PNG matches the previous Mac baseline.
• Real installed frozen-worker checks pass cancellation, forced RSS-budget enforcement, last-good-page retention and worker shutdown. Last-lease closure removes the renderer process and owned temporary directories. A clean /usr/bin:/bin environment renders a synthetic two-page document. The controlled browser passes default-CSP PNG display and image-retry recovery.
• Public wheel audits contain the new scene/runtime modules and viewer HTML, no fonts or native executables, and only the already tracked built-in templates. No private/user documents were added to public source.

Native remote-client file-click gate passed on 2026-10-15: the user, connected from another machine to the Mac chat through SSH, confirmed the table is visible. The active chat now reads 0.1.9/v7. OS observation and the owned renderer status bind the requested synthetic file to the actual 0.1.9 Node server and frozen executable; its displayed PNG is 2480×3508 and byte-identical to the verified Mac baseline. The renderer/server hashes match the new installed package, so the 0.1.8 prototype cache was not reused. No app/daemon restart or unrelated termination was performed. The remote client OS/version was not supplied; local-Mac frontend and broader client compatibility are not claimed. The initial archive-view cause was not established.

Release sequence is documented in the component's RELEASE.md: proposed core 6.9.0 → canonical automation 7.4.0 → compatibility shell 7.4.0 → per-platform optional component 0.1.9. The native-preview extra must move to the actual new core floor before publication. Default plugin 2.4.0 remains unchanged; a later coordinated pin update would need a separate release (proposed 2.5.0). These are planned coordinates, not published releases. Keep the PR draft; signed/notarized binary distribution and arbitrary-document fidelity remain outside this validation.

Single-plugin delivery update (2026-10-15): the normal Codex hwpx-plugin now includes the preview MCP server and automatically prepares a pinned OS helper. Users do not install a separate preview plugin, Node or Python; the existing uv prerequisite remains. Implementation is airmang/hwpx-plugins#60 at 1376714 (bootstrap 84f6941). Local plugin tests: 249 passed. Latest plugin CI: all 16 check-rollup entries passed. Isolated one-plugin install, helper cold start, verified-cache reuse without the helper archive, save/partial-save recovery and simultaneous document editing/preview passed.

The new linked fixture displayed in the actual app, but process inspection showed the old standalone server handled it. The integrated candidate therefore still requires native file-click validation in a fresh app session, plus a Windows integrated build. An additional Mac editing-workflow run timed out in continue_workflow at 90 seconds; it is recorded separately and not counted as a pass. Public helper assets and coordinated package versions remain unreleased; draft status stays unchanged. No existing app/process was stopped.

[airmang]

Windows single-plugin integration follow-up: a fresh frozen helper built from core fd89cd8 and automation aa9bdc9 renders the same synthetic-table PNG as the prior Windows baseline. The scene development branch was installed explicitly; the published core wheel was not substituted. Core remains unchanged and its 13 CI checks pass. Plugin-side Windows fixes are in #60 (45aba82); automation font-path handling is in python-hwpx-automation#171. Fresh integrated native app-click confirmation is still pending, so old standalone confirmations are not counted. No merge or release performed.

[airmang]

Windows fresh-session native file-click validation now passes. The first user-visible table had been served by standalone 0.1.8 and was excluded. After disabling only that legacy plugin entry (retaining its cache and existing processes), the user reported the integrated routing fixture working. Live inspection identifies the target-file renderer and its parent Node inside the content-addressed default-plugin helper cache; both executable hashes, the actual rendered table PNG hash, source hash, and all 76 installed plugin-file hashes match the candidate receipts.

This is candidate 2.5.0-dev.win.7 with the coordinated core/automation development sources documented in the private handoff. An initial connection error occurred during the transition, then the same fixture worked without code/binary changes; its cause is not determined and is retained as a separate observation. Mac single-plugin native validation and its earlier expanded-workflow timeout remain incomplete. CI remains core 13 / automation 15 / plugin 16 passing. No release or merge was performed; all three PRs remain draft and the public helper matrix is still unreleased/empty.