Map Admin Notes to admin URL and apply admin page template - PR_26158_048-admin-notes-template-route

Author: ToolboxAid

docs_build/dev/reports/admin-notes-template-route-report.md

@@ -0,0 +1,59 @@
+# PR_26158_048 Admin Notes Template Route Report
+
+## Summary
+
+PR_26158_048 keeps the Admin Notes source page under `src/dev-runtime/admin/admin-notes.html`, adds local routing for `/admin/admin-notes.html`, and updates the local Admin menu to use the admin-style route. The viewer now uses the shared Theme V2 header/footer partial structure used by admin pages while preserving dev-only directory reading.
+
+## Implementation
+
+| File | Change |
+| --- | --- |
+| `src/dev-runtime/admin/admin-notes.html` | Added `<base href="/">`, shared header/footer partial slots, Theme V2 partial script, and a root-based external viewer script path. |
+| `src/dev-runtime/admin/admin-notes-viewer.js` | Updated generated viewer links to use `/admin/admin-notes.html`. |
+| `src/dev-runtime/admin/admin-notes-menu.mjs` | Updated local menu route constant to `/admin/admin-notes.html` while preserving the source-file path as a separate constant for validation. |
+| `src/dev-runtime/admin/header-nav.local.html` | Updated the Admin Notes menu item to `href="/admin/admin-notes.html"`. |
+| `src/dev-runtime/server/local-api-server.mjs` | Added local route mapping from `/admin/admin-notes.html` to `/src/dev-runtime/admin/admin-notes.html`. |
+| `tests/helpers/playwrightRepoServer.mjs` | Mirrored the local route mapping for targeted Playwright validation. |
+| `tests/dev-runtime/AdminNotesBoundary.test.mjs` | Added checks for shared header/footer partial slots, local menu route, and production-clean boundaries. |
+| `tests/playwright/tools/AdminNotesLocalViewer.spec.mjs` | Validates `/admin/admin-notes.html`, direct source route compatibility, shared header/footer rendering, and note loading. |
+| `tests/playwright/tools/LoginSessionMode.spec.mjs` | Validates Admin menu click-through to `/admin/admin-notes.html`, including fixed-port `5501` login. |
+
+## Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Read `docs_build/dev/PROJECT_INSTRUCTIONS.md` first. | PASS | Read before implementation. |
+| Keep Admin Notes implementation file at `src/dev-runtime/admin/admin-notes.html`. | PASS | Source file remains in place; no `admin/admin-notes.html` file was created. |
+| Add local dev URL routing so `/admin/admin-notes.html` maps to `src/dev-runtime/admin/admin-notes.html`. | PASS | `local-api-server.mjs` and Playwright helper route `/admin/admin-notes.html` to the dev-runtime source. |
+| Update the Admin menu link to use `/admin/admin-notes.html`. | PASS | `src/dev-runtime/admin/header-nav.local.html` uses `href="/admin/admin-notes.html"`; Playwright validates it. |
+| Make Admin Notes use the same Theme V2 page template/header/footer structure as admin pages. | PASS | Viewer now has shared header/footer partial slots, Theme V2 partial script, Theme V2 stylesheet, and no inline script/style/event handlers. |
+| Preserve dev-only Admin Notes behavior and directory reading. | PASS | AdminNotesLocalViewer Playwright loads `index.txt`, lists folders/files, opens `quick-reference.txt`, and opens `other/index.txt`. |
+| Do not move the source file. | PASS | `src/dev-runtime/admin/admin-notes.html` remains the implementation file. |
+| Do not expose Admin Notes in UAT/PROD. | PASS | Public exposure and dev-runtime admin import audits returned no matches in production-facing paths; production admin note paths do not exist. |
+| Do not modify `start_of_day` folders. | PASS | `git diff --name-only \| rg "(^|/)start_of_day(/|$)"` returned no matches. |
+
+## Validation
+
+| Validation | Status | Evidence |
+| --- | --- | --- |
+| Changed-file syntax checks. | PASS | `node --check` passed for changed JS/MJS/test files; AdminNotesBoundary passed 5/5. |
+| AdminNotesLocalViewer Playwright. | PASS | Targeted run passed viewer route and direct source route checks. |
+| Admin menu Playwright proving `/admin/admin-notes.html` opens and renders. | PASS | LoginSessionMode tests validate random-port and fixed `5501` Admin menu click-through. |
+| Verify direct `/src/dev-runtime/admin/admin-notes.html` still works. | PASS | Dedicated Playwright test validates the direct source route still renders the viewer. |
+| Verify UAT/PROD paths do not expose `src/dev-runtime/admin/`. | PASS | Static audit returned no matches in production-facing path set. |
+
+## Rerun Notes
+
+- The first fixed-port Playwright attempt failed because an older `node ./scripts/start-local-api-server.mjs` process was already listening on `127.0.0.1:5501` and serving stale header markup.
+- Stopped that stale local process and reran the targeted lane. The final run passed 4/4.
+
+## Skipped Lanes
+
+| Lane | Decision | Reason |
+| --- | --- | --- |
+| Full samples smoke | SKIP | No sample loader/framework, sample data, or game runtime changed. |
+| Full Playwright suite | SKIP | Targeted Admin Notes and Admin menu lanes validate every requested behavior. |
+
+## Result
+
+PASS. All requested PR_26158_048 requirements are implemented and validated.

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -8,6 +8,7 @@ Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 Changed runtime JS files considered:
 (0%) src/dev-runtime/admin/admin-notes-menu.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/server/local-api-server.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(96%) src/dev-runtime/admin/admin-notes-viewer.js - executed lines 501/501; executed functions 47/49
 
 Guardrail warnings:
 (0%) src/dev-runtime/admin/admin-notes-menu.mjs - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -14,18 +14,19 @@ Note: coverage entries are aggregated across every page/tool where coverageRepor
 Exercised tool entry points detected:
 (0%) Toolbox Index - not exercised by this Playwright run
 (0%) Tool Template V2 - not exercised by this Playwright run
-(68%) Theme V2 Shared JS - exercised 2 runtime JS files
+(70%) Theme V2 Shared JS - exercised 2 runtime JS files
 
 Changed runtime JS files covered:
 (0%) src/dev-runtime/admin/admin-notes-menu.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/server/local-api-server.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
+(96%) src/dev-runtime/admin/admin-notes-viewer.js - executed lines 501/501; executed functions 47/49
 
 Files with executed line/function counts where available:
 (20%) src/engine/api/mock-db-api-client.js - executed lines 19/19; executed functions 1/5
 (29%) src/engine/api/server-api-client.js - executed lines 159/159; executed functions 4/14
 (62%) assets/theme-v2/js/login-session.js - executed lines 357/357; executed functions 16/26
 (63%) src/engine/api/session-api-client.js - executed lines 34/34; executed functions 5/8
-(73%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 441/441; executed functions 29/40
+(75%) assets/theme-v2/js/gamefoundry-partials.js - executed lines 441/441; executed functions 30/40
 (96%) src/dev-runtime/admin/admin-notes-viewer.js - executed lines 501/501; executed functions 47/49
 
 Uncovered or low-coverage changed JS files:
@@ -37,4 +38,6 @@ Changed JS files considered:
 (0%) src/dev-runtime/server/local-api-server.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/dev-runtime/AdminNotesBoundary.test.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/helpers/playwrightRepoServer.mjs - changed JS file not collected as browser runtime coverage
+(0%) tests/playwright/tools/AdminNotesLocalViewer.spec.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/playwright/tools/LoginSessionMode.spec.mjs - changed JS file not collected as browser runtime coverage
+(96%) src/dev-runtime/admin/admin-notes-viewer.js - changed JS file with browser V8 coverage

docs_build/dev/reports/testing_lane_execution_report.md

@@ -1,13 +1,13 @@
-# PR_26158_047 Testing Lane Execution Report
+# PR_26158_048 Testing Lane Execution Report
 
 ## Lanes Run
 
 | Lane | Command | Result |
 | --- | --- | --- |
-| Changed-file syntax checks | `node --check src/dev-runtime/admin/admin-notes-menu.mjs`; `node --check src/dev-runtime/server/local-api-server.mjs`; `node --check tests/helpers/playwrightRepoServer.mjs`; `node --check tests/dev-runtime/AdminNotesBoundary.test.mjs`; `node --check tests/playwright/tools/LoginSessionMode.spec.mjs`; `node --test tests/dev-runtime/AdminNotesBoundary.test.mjs` | PASS, AdminNotesBoundary 5/5 |
-| AdminNotesLocalViewer Playwright | `npx playwright test tests/playwright/tools/AdminNotesLocalViewer.spec.mjs tests/playwright/tools/LoginSessionMode.spec.mjs --grep "Admin Notes local viewer loads\|API-backed 5501 login page shows" --workers=1` | PASS, 2/2 |
-| Production header partial clean check | `Select-String -Path assets/theme-v2/partials/header-nav.html -Pattern "Admin Notes\|data-admin-notes-local-menu\|admin-notes\|docs_build/dev/admin-notes"`; `Test-Path admin/notes.html` | PASS, no header matches; `admin/notes.html` returned `False` |
-| Public navigation exposure audit | `rg -n "docs_build/dev/admin-notes\|docs_build\\dev\\admin-notes\|admin-notes-dev\|data-admin-notes-local-menu\|Admin Notes" account admin assets toolbox src/engine src/shared --glob '!archive/v1-v2/**' --glob '!tmp/**'` | PASS, no matches |
+| Changed-file syntax checks | `node --check src/dev-runtime/admin/admin-notes-menu.mjs`; `node --check src/dev-runtime/admin/admin-notes-viewer.js`; `node --check src/dev-runtime/server/local-api-server.mjs`; `node --check tests/helpers/playwrightRepoServer.mjs`; `node --check tests/dev-runtime/AdminNotesBoundary.test.mjs`; `node --check tests/playwright/tools/AdminNotesLocalViewer.spec.mjs`; `node --check tests/playwright/tools/LoginSessionMode.spec.mjs`; `node --test tests/dev-runtime/AdminNotesBoundary.test.mjs` | PASS, AdminNotesBoundary 5/5 |
+| AdminNotesLocalViewer Playwright | `npx playwright test tests/playwright/tools/AdminNotesLocalViewer.spec.mjs tests/playwright/tools/LoginSessionMode.spec.mjs --grep "Admin Notes local viewer loads\|Admin Notes direct dev-runtime\|Local users unlock\|API-backed 5501 login page shows" --workers=1` | PASS, 4/4 after restarting stale local server |
+| Production header partial clean check | `Select-String -Path assets/theme-v2/partials/header-nav.html -Pattern "Admin Notes\|data-admin-notes-local-menu\|admin-notes\|docs_build/dev/admin-notes"`; `Test-Path admin/admin-notes.html`; `Test-Path admin/notes.html` | PASS, no header matches; both production admin note paths returned `False` |
+| Public navigation exposure audit | `rg -n "docs_build/dev/admin-notes\|docs_build\\dev\\admin-notes\|data-admin-notes-local-menu\|Admin Notes" account admin assets toolbox src/engine src/shared --glob '!archive/v1-v2/**' --glob '!tmp/**'` | PASS, no matches |
 | UAT/PROD dev-runtime admin import audit | `rg -n "src/dev-runtime/admin\|src\\dev-runtime\\admin" account admin assets toolbox src/engine src/shared --glob '!archive/v1-v2/**' --glob '!tmp/**'` | PASS, no matches |
 | Changed-file whitespace/static validation | `git diff --check` | PASS, Git line-ending warnings only |
 | start_of_day protection check | `git diff --name-only \| rg "(^|/)start_of_day(/|$)"` | PASS, no matches |
@@ -16,27 +16,27 @@
 
 | Check | Evidence | Result |
 | --- | --- | --- |
-| Admin Notes local viewer works. | AdminNotesLocalViewer Playwright opened `/src/dev-runtime/admin/admin-notes.html`, loaded `index.txt`, listed folders/files, and opened notes. | PASS |
-| Admin Notes appears from `http://127.0.0.1:5501/login.html`. | LoginSessionMode Playwright opened the exact fixed-port URL, selected the Admin session, hovered Admin, and found `Admin Notes (Local Dev)`. | PASS |
-| Admin Notes opens the dev viewer route. | The fixed-port Playwright test clicked the menu item and verified `/src/dev-runtime/admin/admin-notes.html`, the `Admin Notes` heading, and loaded `index.txt` status. | PASS |
-| Dedicated local header partial replaces fragile string replacement. | `node --test tests/dev-runtime/AdminNotesBoundary.test.mjs` verifies the server maps the normal header partial path to `src/dev-runtime/admin/header-nav.local.html` and leaves the production partial unchanged. | PASS |
-| Production/public header remains clean. | Static partial check and public exposure audit returned no matches. | PASS |
+| `/admin/admin-notes.html` opens and renders the viewer. | AdminNotesLocalViewer Playwright opens the route, validates header/footer, viewer title, loaded `index.txt`, folder/file links, and note content. | PASS |
+| Direct `/src/dev-runtime/admin/admin-notes.html` still works. | AdminNotesLocalViewer Playwright opens the direct source route and validates the viewer, header/footer, and loaded `index.txt` status. | PASS |
+| Admin menu opens `/admin/admin-notes.html`. | LoginSessionMode Playwright hovers Admin, validates `Admin Notes (Local Dev)` link `href="/admin/admin-notes.html"`, clicks it, and validates the viewer. | PASS |
+| Fixed local API-backed path works from `http://127.0.0.1:5501/login.html`. | LoginSessionMode Playwright opens the exact fixed-port login URL and clicks through to `http://127.0.0.1:5501/admin/admin-notes.html`. | PASS |
+| Viewer uses the Theme V2 admin page shell. | Boundary and Playwright checks validate shared header/footer partial slots, Theme V2 partial wiring, and no inline script/style/event handlers. | PASS |
+| Production/public header remains clean. | Static partial and public exposure checks returned no matches. | PASS |
 | UAT/PROD-facing paths do not expose Admin Notes implementation. | Static import audit returned no matches under public/admin/account/toolbox/engine/shared paths. | PASS |
 
 ## Rerun Notes
 
 | Attempt | Result | Resolution |
 | --- | --- | --- |
-| First targeted Playwright attempt | FAIL | `127.0.0.1:5501` was already in use. The fixed-port test harness now uses an existing API-backed local server when one is already running, while still validating the exact 5501 URL. |
-| Second targeted Playwright attempt | FAIL | Test expected the resolved absolute URL in the raw `href` attribute. The assertion was corrected to expect `/src/dev-runtime/admin/admin-notes.html`, and click-through still validates the full 5501 URL. |
-| Final targeted Playwright attempt | PASS | AdminNotesLocalViewer and fixed-port Admin menu tests passed 2/2. |
+| First targeted Playwright attempt | FAIL | PID `71976` was a stale `node ./scripts/start-local-api-server.mjs` instance serving the previous `/src/dev-runtime/admin/admin-notes.html` menu link on port 5501. |
+| Final targeted Playwright attempt | PASS | Stopped the stale local server process, reran the targeted lane, and validated `/admin/admin-notes.html` from the fixed 5501 login URL. |
 
 ## Skipped Lanes
 
 | Lane | Decision | Reason |
 | --- | --- | --- |
-| Full samples smoke | SKIP | No samples, sample loader/framework, or game runtime changed. |
-| Full Playwright suite | SKIP | Scope is limited to local API-backed Admin Notes menu routing and the existing Admin Notes local viewer; targeted lanes cover the changed behavior. |
+| Full samples smoke | SKIP | No sample loader/framework, sample data, or game runtime changed. |
+| Full Playwright suite | SKIP | Targeted Admin Notes viewer and Admin menu lanes cover the local route/template behavior requested. |
 
 ## Notes
 

src/dev-runtime/admin/admin-notes-menu.mjs

@@ -1,6 +1,7 @@
 import path from "node:path";
 
-export const ADMIN_NOTES_LOCAL_VIEWER_PATH = "/src/dev-runtime/admin/admin-notes.html";
+export const ADMIN_NOTES_LOCAL_VIEWER_PATH = "/admin/admin-notes.html";
+export const ADMIN_NOTES_LOCAL_SOURCE_PATH = "/src/dev-runtime/admin/admin-notes.html";
 export const ADMIN_NOTES_LOCAL_MENU_LABEL = "Admin Notes (Local Dev)";
 
 const HEADER_PARTIAL_PATH = "assets/theme-v2/partials/header-nav.html";

src/dev-runtime/admin/admin-notes-viewer.js

@@ -1,7 +1,7 @@
 // Dev-runtime only: do not import this viewer from production-facing pages or bundles.
 const NOTES_DIRECTORY = "docs_build/dev/admin-notes";
 const DEFAULT_NOTE = "index";
-const VIEWER_PATH = "/src/dev-runtime/admin/admin-notes.html";
+const VIEWER_PATH = "/admin/admin-notes.html";
 const LINK_CLASS = "btn btn--compact primary";
 const NOTE_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
 const STATUS_ICON_PATTERN = /^\[([ xX.!?-])\]\s*(.*)$/;

src/dev-runtime/admin/admin-notes.html

@@ -2,14 +2,16 @@
 <html lang="en">
 <head>
     <meta charset="utf-8">
+    <base href="/">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>Admin Notes Local Viewer - GameFoundryStudio</title>
     <meta name="description" content="Local development viewer for Admin Notes under docs_build/dev/admin-notes.">
     <link rel="icon" href="/favicon.svg">
-    <link rel="stylesheet" href="../../../assets/theme-v2/css/theme.css">
+    <link rel="stylesheet" href="assets/theme-v2/css/theme.css">
 </head>
 <body>
-    <main data-admin-notes-viewer>
+    <div data-partial="header-nav"></div>
+    <main data-admin-only="true" data-admin-notes-viewer>
         <section class="page-title">
             <div class="container">
                 <div class="kicker">Local Dev Admin</div>
@@ -53,6 +55,8 @@ <h3>Status Legend</h3>
             </div>
         </section>
     </main>
-    <script type="module" src="./admin-notes-viewer.js"></script>
+    <div data-partial="footer"></div>
+    <script src="assets/theme-v2/js/gamefoundry-partials.js" defer></script>
+    <script type="module" src="src/dev-runtime/admin/admin-notes-viewer.js"></script>
 </body>
 </html>

src/dev-runtime/admin/header-nav.local.html

@@ -110,7 +110,7 @@
       <div class="nav-item">
         <a data-nav-link data-route="admin" href="admin/site-settings.html">Admin &#9662;</a>
         <div class="sub-menu">
-          <a data-nav-link data-admin-notes-local-menu href="/src/dev-runtime/admin/admin-notes.html">Admin Notes (Local Dev)</a>
+          <a data-nav-link data-admin-notes-local-menu href="/admin/admin-notes.html">Admin Notes (Local Dev)</a>
           <a data-nav-link data-route="admin-analytics" href="admin/analytics.html">Analytics</a>
           <a data-nav-link data-route="admin-branding" href="admin/branding.html">Branding</a>
           <a data-nav-link data-route="admin-controls" href="admin/controls.html">Controls</a>

src/dev-runtime/server/local-api-server.mjs

@@ -31,6 +31,9 @@ function resolveBrowserRoutePath(decodedPath) {
   if (webPath === "/tools" || webPath.startsWith("/tools/")) {
     return `/toolbox${webPath.slice("/tools".length)}`;
   }
+  if (webPath === "/admin/admin-notes.html") {
+    return "/src/dev-runtime/admin/admin-notes.html";
+  }
   return normalizedPath;
 }