|
| 1 | +# www Migration Map |
| 2 | + |
| 3 | +Status: Active planning map |
| 4 | +Owner: Owner |
| 5 | +Workstream: Repository Architecture Simplification |
| 6 | +PR: PR_26180_OWNER_006-www-migration-map |
| 7 | + |
| 8 | +## Purpose |
| 9 | + |
| 10 | +Document the current browser-served repository surface and the safe sequence required before moving files into `www/`. |
| 11 | + |
| 12 | +This map is a no-runtime-change governance artifact. It does not move browser files, change package commands, change local server behavior, or update runtime imports. |
| 13 | + |
| 14 | +## Executive Summary |
| 15 | + |
| 16 | +The browser-served application currently depends on repository-root static serving. |
| 17 | + |
| 18 | +Current local runtime, test helpers, and browser pages assume URLs such as `/index.html`, `/toolbox/index.html`, `/assets/theme-v2/css/theme.css`, `/account/sign-in.html`, `/admin/system-health.html`, and `/games/index.html` resolve from the repository root. |
| 19 | + |
| 20 | +Moving browser files into `www/` is feasible, but the move must preserve public route URLs while changing the filesystem lookup root. A direct folder move without route compatibility would break Playwright tests, local API static serving, team-aware bootstrap static serving, Node test root aliases, and browser imports that still reference root-level `src/`, `toolbox/`, and `assets/`. |
| 21 | + |
| 22 | +## Current Browser-Served Surface |
| 23 | + |
| 24 | +Current root-level browser-served entry points and folders include: |
| 25 | + |
| 26 | +| Path | Current role | Files | HTML files | Move target | |
| 27 | +| --- | --- | ---: | ---: | --- | |
| 28 | +| `index.html` | Root marketing/product entry | 1 | 1 | `www/index.html` | |
| 29 | +| `account/` | Account pages | 13 | 11 | `www/account/` | |
| 30 | +| `admin/` | Admin/Owner pages | 18 | 16 | `www/admin/` | |
| 31 | +| `assets/` | Browser assets, Theme V2, tool assets, partials | 328 | 5 | `www/assets/` | |
| 32 | +| `community/` | Community/public pages | 3 | 3 | `www/community/` | |
| 33 | +| `company/` | Company/public pages | 7 | 7 | `www/company/` | |
| 34 | +| `docs/` | Production Docs & Help pages | 5 | 4 | `www/docs/` only when route preservation is ready | |
| 35 | +| `games/` | Public game discovery pages | 12 | 8 | `www/games/` | |
| 36 | +| `learn/` | Learning pages | 11 | 11 | `www/learn/` | |
| 37 | +| `legal/` | Legal pages | 17 | 9 | `www/legal/` | |
| 38 | +| `marketplace/` | Marketplace page | 1 | 1 | `www/marketplace/` | |
| 39 | +| `memberships/` | Membership page | 1 | 1 | `www/memberships/` | |
| 40 | +| `owner/` | Owner governance/admin pages | 8 | 8 | `www/owner/` | |
| 41 | +| `toolbox/` | Creator toolbox pages and legacy sidecars | 57 | 49 | `www/toolbox/` | |
| 42 | + |
| 43 | +No top-level `play/` folder exists in the current tracked repository root. Any existing `play/` string references must be reviewed as route/content references before a future move introduces or preserves a `play/` route. |
| 44 | + |
| 45 | +## Current Reference Inventory |
| 46 | + |
| 47 | +Broad active-reference search across browser roots, `src/`, `dev/scripts/`, and `dev/tests/` found: |
| 48 | + |
| 49 | +| Reference | Approximate active files | Notes | |
| 50 | +| --- | ---: | --- | |
| 51 | +| `assets/` | 230 | Theme CSS/JS, images, tool JS, workers, partials, and test fixtures. | |
| 52 | +| `toolbox/` | 241 | Tool routes, registry routes, tests, validation scripts, and server route compatibility. | |
| 53 | +| `account/` | 43 | Account routes, return URLs, and Playwright coverage. | |
| 54 | +| `legal/` | 13 | Footer/navigation route references and page links. | |
| 55 | +| `learn/` | 9 | Learn route links and navigation. | |
| 56 | +| `play/` | 7 | No root folder exists; review references manually before introducing a route. | |
| 57 | +| `src/` | 451 | Browser imports, server imports, tests, validation aliases, and current runtime/source modules. | |
| 58 | + |
| 59 | +The high `src/` count means the browser migration cannot be treated as static files only. Several browser-facing pages import modules from root-level `src/`, including account/admin/toolbox flows. |
| 60 | + |
| 61 | +## Examples Of References That Must Be Preserved Or Rewritten |
| 62 | + |
| 63 | +### Preserve public route URLs |
| 64 | + |
| 65 | +These URLs should continue working for users and tests during the move: |
| 66 | + |
| 67 | +- `/index.html` |
| 68 | +- `/toolbox/index.html` |
| 69 | +- `/toolbox/{tool}/index.html` |
| 70 | +- `/account/{page}.html` |
| 71 | +- `/admin/{page}.html` |
| 72 | +- `/games/index.html` |
| 73 | +- `/learn/index.html` |
| 74 | +- `/legal/index.html` |
| 75 | +- `/marketplace/index.html` |
| 76 | +- `/memberships/index.html` |
| 77 | + |
| 78 | +### Rewrite filesystem lookup paths |
| 79 | + |
| 80 | +Static servers and test helpers should map public URLs to `www/` filesystem paths after the move: |
| 81 | + |
| 82 | +- `/index.html` -> `www/index.html` |
| 83 | +- `/toolbox/index.html` -> `www/toolbox/index.html` |
| 84 | +- `/assets/theme-v2/css/theme.css` -> `www/assets/theme-v2/css/theme.css` |
| 85 | + |
| 86 | +### Preserve service/API route behavior |
| 87 | + |
| 88 | +API routes must remain API routes and must not be resolved as static browser files: |
| 89 | + |
| 90 | +- `/api/*` |
| 91 | +- `/api/toolbox/*` |
| 92 | +- `/api/session/*` |
| 93 | +- `/api/auth/*` |
| 94 | + |
| 95 | +### Browser import references needing migration review |
| 96 | + |
| 97 | +Examples of current references that depend on root-level path relationships: |
| 98 | + |
| 99 | +- `account/user-controls-page.js` imports from `../src/api/` and `../src/engine/`. |
| 100 | +- `admin/tool-votes.js` imports from `../src/api/` and `../toolbox/tool-registry-api-client.js`. |
| 101 | +- `admin/db-viewer.js` imports from `../src/api/`. |
| 102 | +- `owner/notes.html` loads `../src/dev-runtime/admin/admin-notes-viewer.js`. |
| 103 | +- `toolbox/toolRegistry.js` imports from `../src/shared/toolbox/tool-metadata-inventory.js`. |
| 104 | +- `assets/toolbox/*/js/index.js` imports from `../../../../src/` or `../../../../toolbox/` in several tool flows. |
| 105 | + |
| 106 | +These references can be preserved temporarily by serving compatibility paths from the repository root, but the final architecture should move browser-facing runtime modules into `www/` or an approved deployable browser module surface. |
| 107 | + |
| 108 | +## Current Local Web Server Root Behavior |
| 109 | + |
| 110 | +Three active server/helper surfaces currently resolve static browser paths from the repository root: |
| 111 | + |
| 112 | +| File | Current behavior | |
| 113 | +| --- | --- | |
| 114 | +| `dev/scripts/start-dev.mjs` | Team-aware bootstrap static server resolves requests with `path.resolve(repoRoot, \`.\${normalizedPath}\`)`. `/` maps to `/index.html`; `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. | |
| 115 | +| `src/dev-runtime/server/local-api-server.mjs` | Legacy local API alias serves API routes and falls back to static files from `repoRoot`. `/tools/*` maps to `/toolbox/*`; `/admin/admin-notes.html` maps to `/src/dev-runtime/admin/notes.html`. | |
| 116 | +| `dev/tests/helpers/playwrightRepoServer.mjs` | Playwright test server mirrors repo-root static serving and the `/tools/*` and admin-notes compatibility routes. | |
| 117 | + |
| 118 | +The actual `www/` move must update these filesystem lookup roots or introduce a shared route resolver that can resolve public routes to `www/` while preserving API route ownership. |
| 119 | + |
| 120 | +## Current Test Assumptions |
| 121 | + |
| 122 | +Playwright and runtime tests currently assume root-based public routes and root-relative filesystem paths: |
| 123 | + |
| 124 | +- 96 Playwright/helper/runtime files reference public routes such as `/toolbox`, `/account`, `/admin`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, or `/index.html`. |
| 125 | +- `dev/tests/playwright/tools/ToolNavigationPrevNext.spec.mjs` opens `/toolbox/index.html` and `/toolbox/game-design/index.html`. |
| 126 | +- `dev/tests/playwright/tools/BuildPathProgressSimplification.spec.mjs` opens `/index.html`, `/toolbox/index.html`, and `/admin/tool-votes.html`. |
| 127 | +- `dev/tests/playwright/tools/EnvironmentBannerCoverage.spec.mjs` covers root/home, marketplace, learn, and memberships route families. |
| 128 | +- `dev/tests/runtime/V2*` tests frequently assert `toolbox/{tool}/index.html` filesystem or URL behavior. |
| 129 | +- `dev/scripts/run-node-tests.mjs` and `dev/scripts/run-node-test-files.mjs` register root aliases for `/src/` and `/toolbox/`. |
| 130 | + |
| 131 | +The move PR must update test helpers and route expectations in the same PR that changes the filesystem root. Browser-visible URLs should remain stable unless Owner explicitly approves a public URL change. |
| 132 | + |
| 133 | +## Preserve Versus Rewrite |
| 134 | + |
| 135 | +### Preserve |
| 136 | + |
| 137 | +- Public browser URLs. |
| 138 | +- `/tools/*` compatibility routing to toolbox pages until Owner approves route removal. |
| 139 | +- `/api/*` service contract routes. |
| 140 | +- Theme V2 asset URLs as browser routes, even if filesystem paths move under `www/`. |
| 141 | +- Tool route semantics and Product Owner test flows. |
| 142 | +- Existing package commands until the PR explicitly scoped to command migration. |
| 143 | + |
| 144 | +### Rewrite |
| 145 | + |
| 146 | +- Filesystem path resolution in local static servers and Playwright test helpers. |
| 147 | +- Internal static file lookup roots from repository root to `www/`. |
| 148 | +- Relative links/imports that break because source and target files move together. |
| 149 | +- Validation scripts that inspect browser-served file locations. |
| 150 | +- Coverage mapping that classifies `toolbox/`, `assets/theme-v2/js/`, and browser routes after the move. |
| 151 | + |
| 152 | +### Defer |
| 153 | + |
| 154 | +- Moving server/API code into `api/`. |
| 155 | +- Moving developer bootstrap into `dev/local-runtime/`. |
| 156 | +- Removing legacy root compatibility routes. |
| 157 | +- Changing package commands. |
| 158 | +- Renaming public URLs. |
| 159 | + |
| 160 | +## Compatibility Redirects Or Shims |
| 161 | + |
| 162 | +Temporary compatibility is likely required. |
| 163 | + |
| 164 | +Recommended approach for the actual move PR: |
| 165 | + |
| 166 | +1. Preserve public URLs while changing filesystem roots. |
| 167 | +2. Add a shared route resolution helper or equivalent route table for local runtime/test servers. |
| 168 | +3. Keep `/tools/*` -> `/toolbox/*` compatibility. |
| 169 | +4. Keep root URL families stable: `/account`, `/admin`, `/assets`, `/games`, `/learn`, `/legal`, `/marketplace`, `/memberships`, `/owner`, `/toolbox`. |
| 170 | +5. Do not introduce browser redirects unless a static route cannot be served directly. |
| 171 | +6. Document every temporary shim with removal criteria for the legacy-layout cleanup PR. |
| 172 | + |
| 173 | +## Required Sequence For Safe www Move |
| 174 | + |
| 175 | +1. Freeze the public route contract. |
| 176 | +2. Move `index.html` and browser-served folders into `www/`. |
| 177 | +3. Update local static server filesystem roots to resolve from `www/` for browser routes. |
| 178 | +4. Preserve `/api/*` API routing before static fallback. |
| 179 | +5. Preserve compatibility route aliases such as `/tools/*`. |
| 180 | +6. Update Playwright repo server helper to mirror runtime static route resolution. |
| 181 | +7. Update browser relative imports and links only where the move changes relative depth. |
| 182 | +8. Update validation scripts and coverage prefix mapping for `www/` paths. |
| 183 | +9. Run targeted Playwright lanes for root/home, account/admin, toolbox navigation, environment banner, and impacted tool flows. |
| 184 | +10. Produce a compatibility ledger for any root path still supported temporarily. |
| 185 | + |
| 186 | +## Validation Lanes Required For The Actual Move PR |
| 187 | + |
| 188 | +Minimum validation for the actual `www/` move: |
| 189 | + |
| 190 | +- `git diff --check` |
| 191 | +- `npm run validate:canonical-structure` |
| 192 | +- `node ./dev/scripts/run-platform-validation-suite.mjs` |
| 193 | +- targeted Playwright route lanes touching: |
| 194 | + - root/home |
| 195 | + - account sign-in/session |
| 196 | + - admin owner navigation |
| 197 | + - toolbox navigation |
| 198 | + - Tool Display Mode |
| 199 | + - environment banner coverage |
| 200 | + - games index/discovery |
| 201 | +- targeted runtime tests that assert `toolbox/{tool}/index.html` or filesystem existence. |
| 202 | + |
| 203 | +Fallback validation if targeted routing failures are broad: |
| 204 | + |
| 205 | +- `npm run test:workspace-v2` |
| 206 | +- `npm run test:lane:tool-navigation` |
| 207 | +- `npm run test:lane:tool-display-mode` |
| 208 | +- impacted Playwright specs under `dev/tests/playwright/account/`, `dev/tests/playwright/games/`, and `dev/tests/playwright/tools/`. |
| 209 | + |
| 210 | +## Owner Recommendation |
| 211 | + |
| 212 | +Do not perform the browser move until the actual move PR explicitly owns: |
| 213 | + |
| 214 | +- static server filesystem root migration, |
| 215 | +- Playwright helper root migration, |
| 216 | +- route compatibility ledger, |
| 217 | +- browser relative import/link rewrites, |
| 218 | +- validation script prefix updates, |
| 219 | +- and targeted Playwright execution. |
| 220 | + |
| 221 | +The next implementation PR should be a focused `www/` move PR that preserves public URLs while moving the filesystem root to `www/`. |
0 commit comments