docs(openworlds): add fidelity and asset contract

docs/OPENWORLDS_DESIGN_ASSET_POLICY.md

@@ -0,0 +1,112 @@
+# OpenWorlds Design Asset Policy
+
+This policy governs any ClawDnD work derived from the local OpenWorlds design
+bundle. It exists to preserve visual fidelity without accidentally committing
+uncleared reference art, prototype-only dependencies, private content, or
+third-party game UI material.
+
+## Source Buckets
+
+Source artifact:
+
+- `OpenWorlds.zip`
+  - SHA256: `8e9e2b885764fd3492b74b2d02eda5db9827eb087121054e8ca52e9ace10fd0a`
+  - Acquisition date: 2026-05-25 UTC
+  - Local extraction label: `openworlds-design-2026-05-25`
+  - License/provenance status: internal design handoff; not a blanket asset
+    license
+
+Primary visual/reference contract:
+
+- `openworlds/Open Worlds.html`
+- `openworlds/styles.css`
+- `openworlds/app.jsx`
+- `openworlds/chrome.jsx`
+- `openworlds/screen-*.jsx`
+- `openworlds/camp-sidebar.jsx`
+- `openworlds/toast.jsx`
+- `openworlds/tooltip.jsx`
+
+Prototype/demo data requiring rewrite:
+
+- `openworlds/data.js`
+
+Open Design or tweak-host code to remove from production routes:
+
+- `openworlds/tweaks-panel.jsx`
+
+Secondary reference only:
+
+- `uploads/dndforever/index.html`
+- `uploads/dndforever/DESIGN-HANDOFF.md`
+- `uploads/dndforever/DESIGN-MANIFEST.json`
+
+Reference-only assets:
+
+- `openworlds/screenshots/*`
+- `uploads/*.png`
+- `OpenWorlds.zip`
+
+The reference-only assets must not be committed unless a follow-up PR documents
+clear provenance and licensing.
+
+When a later PR copies any source file into the repo, its PR body must map the
+source artifact entry to the new repo-relative path and list the relevant
+license/provenance note.
+
+## Allowed In Repo
+
+- Audited and cleaned HTML/CSS/JS implementation code from the primary
+  OpenWorlds export only after the PR documents provenance, dependency notices,
+  and copied source files.
+- Abstract design tokens, layout structure, component behavior, and interaction
+  patterns ported from the primary export.
+- Locally vendored runtime libraries for the first exact-fidelity sprint, when
+  their license notices are included and no network CDN calls remain.
+- ClawDnD-authored docs that describe source buckets, fidelity requirements,
+  and asset handling.
+
+## Not Allowed In Repo
+
+- `OpenWorlds.zip`.
+- Pasted Owlcat/BG/reference screenshots.
+- Any image from `uploads/*.png` or `openworlds/screenshots/*` without explicit
+  provenance.
+- Open Design sandbox, preview, snapshot, or tweak-host chrome.
+- Live CDN dependencies in the packaged app.
+- Private world seeds, QA transcripts, play-state, secrets, or local runtime
+  artifacts.
+- Browser-side code that directly mutates campaign state.
+
+## Prototype Dependency Policy
+
+The OpenWorlds prototype currently references Google Fonts, React, ReactDOM, and
+Babel through network CDNs. Production ClawDnD builds must not depend on those
+network calls.
+
+The first exact-fidelity PR may use locally vendored React, ReactDOM, and Babel
+to preserve the export quickly. A release-hardening PR must replace runtime
+Babel with a proper bundled build before beta distribution or notarization.
+
+Fonts must be self-hosted with license notices, replaced by system fallbacks with
+explicit visual acceptance, or separately cleared before shipping.
+
+## PR Checklist For Visual Work
+
+Every OpenWorlds visual PR must state:
+
+- Whether any binary/image assets were copied.
+- Whether any third-party or reference assets were copied.
+- Which source files from the primary export were ported.
+- Whether live network dependencies remain.
+- Which screenshot viewports were checked.
+- Whether the browser surface still treats the engine as the sole game-state
+  writer.
+
+The default acceptable statement is:
+
+> No third-party/reference image assets copied. OpenWorlds implementation code
+> was audited against the local primary export before porting. Runtime
+> dependencies are local and documented. Prototype data was rewritten or clearly
+> kept as non-canonical demo data. Engine state remains read-only from the
+> browser except for existing `/move` player-intent posts.

docs/OPENWORLDS_FIDELITY_PLAN.md

@@ -0,0 +1,123 @@
+# OpenWorlds Fidelity Rollout Plan
+
+This document supersedes the SwiftUI repaint direction explored in PR #123.
+OpenWorlds should be integrated as an exact web surface first, then wired to
+ClawDnD read models screen by screen.
+
+## Decision
+
+The OpenWorlds export is the visual contract. The macOS app should supervise
+local services and host the product surface in `WKWebView`; it should not
+recreate the OpenWorlds UI in SwiftUI unless a future native component can meet
+screenshot-level parity.
+
+Primary visual/reference source files inside source artifact `OpenWorlds.zip`
+SHA256 `8e9e2b885764fd3492b74b2d02eda5db9827eb087121054e8ca52e9ace10fd0a`:
+
+- `openworlds/Open Worlds.html`
+- `openworlds/styles.css`
+- `openworlds/app.jsx`
+- `openworlds/chrome.jsx`
+- `openworlds/screen-*.jsx`
+
+Prototype/demo data requiring rewrite or explicit non-canonical labeling:
+
+- `openworlds/data.js`
+
+## Architecture
+
+- SwiftUI owns native process supervision, provider launch/status, settings,
+  logs, dependency checks, diagnostics, and packaging.
+- `viewer/server.py` serves the exact OpenWorlds web surface under
+  `/openworlds/` so the UI and viewer APIs are same-origin.
+- `/dashboard` remains a fallback/debug route until the OpenWorlds surface is
+  stable.
+- The browser may read viewer APIs and post player intent to `/move`.
+- The browser must never write `snapshot.json`, `play-state`, `qa/state`,
+  inventory, quests, XP, world clocks, companion state, or private notes.
+
+## Rollout
+
+1. Fidelity and asset contract.
+   - Add this plan and the asset policy.
+   - Keep PR #123 draft and mark it superseded.
+   - Confirm no reference images or private content are staged.
+
+2. Viewer-hosted exact OpenWorlds surface.
+   - Create a cleaned, audited `viewer/openworlds/` bundle from the primary
+     export.
+   - Normalize `Open Worlds.html` to `index.html`.
+   - Use locally vendored React/ReactDOM/Babel for the first exact-fidelity
+     sprint, with notices.
+   - Remove live CDN calls and Open Design host chrome.
+   - Rewrite or label prototype `data.js` content as non-canonical demo data.
+   - The PR body must list copied source files, dependency license notices,
+     removed CDN calls, removed sandbox/tweak code, and any rewritten prototype
+     copy or data.
+   - Serve `/openworlds/`, `/openworlds/<asset>`, and
+     `/openworlds/config.json`.
+
+3. Native app opens OpenWorlds.
+   - Have the Play surface start the viewer and load `/openworlds/`.
+   - Keep SwiftUI diagnostics and settings available.
+   - Abandon the SwiftUI OpenWorlds repaint from PR #123.
+
+4. Chronicles launcher data binding.
+   - Replace prototype campaign rows with read-only campaign summaries.
+   - Show live/stale status, world, day, location, and provider/run metadata
+     where available.
+
+5. Session/Table read model.
+   - Add filtered `/session-surface`.
+   - Feed the Table screen with scene, party, conditions, quests, recent events,
+     and available actions.
+   - Exclude hidden fields such as `notes`, `dm_notes`, sealed companion agenda,
+     and private lore.
+
+6. Gameplay surfaces.
+   - Combat board, atlas, relations/camp, inventory/merchant/forge, acts, and
+     bestiary/codex proceed as read-model surfaces before adding backed player
+     actions.
+
+## PR #123 Disposition
+
+PR #123 must remain unmerged. After this plan lands, add a final PR comment on
+issue/PR `#123` linking to the fidelity contract PR and close `#123` as
+superseded once the first viewer-hosted OpenWorlds surface PR is open.
+
+If the viewer-hosted web-surface path fails, reopen the architecture decision in
+a new issue or PR. Do not revive the SwiftUI repaint unless it includes
+screenshot-level parity evidence against the exported OpenWorlds reference.
+
+## Visual Gates
+
+Before a visual PR is marked ready:
+
+- Capture exported reference and ClawDnD candidate screenshots at `1366x768`,
+  `1440x900`, and `1920x1080`.
+- Add `1024x768` and mobile-like widths when the PR claims responsive web
+  parity; otherwise record those viewports as deferred.
+- Confirm the candidate preserves the OpenWorlds window frame, nav rail,
+  parchment surface, typography, spacing, hover/active affordances, and screen
+  routing.
+- Reject obvious SwiftUI repaint drift.
+
+## Validation
+
+Focused local checks:
+
+```bash
+cd <repo-root>
+pwd
+python3 -m py_compile viewer/server.py
+python3 -m unittest discover -s viewer/tests -q
+swift build --package-path macos/ClawDnDApp
+./script/build_and_run.sh --verify
+python3 scripts/license_check.py
+git diff --check
+```
+
+Use GitHub CI for broad engine, rules, voice, and license validation. Docs-only
+PRs are expected to run the normal CI and license-check jobs; the macOS Swift
+workflow only runs for macOS, script, or workflow changes unless manually
+dispatched. Use CodeRabbit and read-only adversarial agents before merge.