diff --git a/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md b/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md new file mode 100644 index 00000000..2b9def75 --- /dev/null +++ b/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. diff --git a/docs/OPENWORLDS_FIDELITY_PLAN.md b/docs/OPENWORLDS_FIDELITY_PLAN.md new file mode 100644 index 00000000..4bd9fff0 --- /dev/null +++ b/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/`, 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 +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.