From 093b1d3e77e9250781c2400b883a7b5ecd7e015b Mon Sep 17 00:00:00 2001 From: Eva Date: Tue, 26 May 2026 02:49:51 +0700 Subject: [PATCH 1/2] docs(openworlds): add fidelity contract --- docs/OPENWORLDS_DESIGN_ASSET_POLICY.md | 99 ++++++++++++++++++++ docs/OPENWORLDS_FIDELITY_PLAN.md | 122 +++++++++++++++++++++++++ 2 files changed, 221 insertions(+) create mode 100644 docs/OPENWORLDS_DESIGN_ASSET_POLICY.md create mode 100644 docs/OPENWORLDS_FIDELITY_PLAN.md diff --git a/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md b/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md new file mode 100644 index 00000000..a704171d --- /dev/null +++ b/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md @@ -0,0 +1,99 @@ +# 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 + +Primary visual/reference contract: + +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/Open Worlds.html` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/styles.css` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/app.jsx` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/chrome.jsx` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/screen-*.jsx` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/camp-sidebar.jsx` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/toast.jsx` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/tooltip.jsx` + +Prototype/demo data requiring rewrite: + +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/data.js` + +Open Design or tweak-host code to remove from production routes: + +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/tweaks-panel.jsx` + +Secondary reference only: + +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/uploads/dndforever/index.html` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/uploads/dndforever/DESIGN-HANDOFF.md` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/uploads/dndforever/DESIGN-MANIFEST.json` + +Reference-only assets: + +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/screenshots/*` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/uploads/*.png` +- `/Users/lume/Downloads/OpenWorlds.zip` + +The reference-only assets must not be committed unless a follow-up PR documents +clear provenance and licensing. + +## 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..2613ba04 --- /dev/null +++ b/docs/OPENWORLDS_FIDELITY_PLAN.md @@ -0,0 +1,122 @@ +# 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: + +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/Open Worlds.html` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/styles.css` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/app.jsx` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/chrome.jsx` +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/screen-*.jsx` + +Prototype/demo data requiring rewrite or explicit non-canonical labeling: + +- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/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 +#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. From cbe63240dbaaa927bf31f7abe1de0163c6485bee Mon Sep 17 00:00:00 2001 From: Eva Date: Tue, 26 May 2026 02:53:42 +0700 Subject: [PATCH 2/2] docs(openworlds): tighten source provenance --- docs/OPENWORLDS_DESIGN_ASSET_POLICY.md | 45 +++++++++++++++++--------- docs/OPENWORLDS_FIDELITY_PLAN.md | 19 +++++------ 2 files changed, 39 insertions(+), 25 deletions(-) diff --git a/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md b/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md index a704171d..2b9def75 100644 --- a/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md +++ b/docs/OPENWORLDS_DESIGN_ASSET_POLICY.md @@ -7,40 +7,53 @@ 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: -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/Open Worlds.html` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/styles.css` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/app.jsx` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/chrome.jsx` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/screen-*.jsx` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/camp-sidebar.jsx` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/toast.jsx` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/tooltip.jsx` +- `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: -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/data.js` +- `openworlds/data.js` Open Design or tweak-host code to remove from production routes: -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/tweaks-panel.jsx` +- `openworlds/tweaks-panel.jsx` Secondary reference only: -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/uploads/dndforever/index.html` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/uploads/dndforever/DESIGN-HANDOFF.md` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/uploads/dndforever/DESIGN-MANIFEST.json` +- `uploads/dndforever/index.html` +- `uploads/dndforever/DESIGN-HANDOFF.md` +- `uploads/dndforever/DESIGN-MANIFEST.json` Reference-only assets: -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/screenshots/*` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/uploads/*.png` -- `/Users/lume/Downloads/OpenWorlds.zip` +- `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 diff --git a/docs/OPENWORLDS_FIDELITY_PLAN.md b/docs/OPENWORLDS_FIDELITY_PLAN.md index 2613ba04..4bd9fff0 100644 --- a/docs/OPENWORLDS_FIDELITY_PLAN.md +++ b/docs/OPENWORLDS_FIDELITY_PLAN.md @@ -11,17 +11,18 @@ 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: +Primary visual/reference source files inside source artifact `OpenWorlds.zip` +SHA256 `8e9e2b885764fd3492b74b2d02eda5db9827eb087121054e8ca52e9ace10fd0a`: -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/Open Worlds.html` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/styles.css` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/app.jsx` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/chrome.jsx` -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/screen-*.jsx` +- `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: -- `/Volumes/LEXAR/Codex/openworlds-design-2026-05-25/openworlds/data.js` +- `openworlds/data.js` ## Architecture @@ -81,8 +82,8 @@ Prototype/demo data requiring rewrite or explicit non-canonical labeling: ## PR #123 Disposition PR #123 must remain unmerged. After this plan lands, add a final PR comment on -#123 linking to the fidelity contract PR and close #123 as superseded once the -first viewer-hosted OpenWorlds surface PR is open. +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