From d76ee0595699a8ee39c44697458b31a146da01b0 Mon Sep 17 00:00:00 2001
From: mwiegand <martin.wiegand@seibert.group>
Date: Sun, 17 May 2026 15:02:21 +0200
Subject: [PATCH] =?UTF-8?q?docs(files):=20errata=20=E2=80=94=20script=20ta?=
 =?UTF-8?q?g=20lives=20in=20overlay=5Fdetail.html,=20not=20base.html?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

files-overlay.js is loaded from overlay_detail.html:285 (with defer),
not base.html — the JS activates only when .files-manager exists,
which is only on overlay detail for files-type overlays. Loading from
base.html would pull it onto every page. The plan's first draft had
this wrong in four places (step 1, step 4, step 10, critical files
table). Following the plan verbatim would have moved the script tag
to the wrong template — exactly the failure mode that
feedback_validate_before_implementing memory warns about.

Added an Errata section at the bottom of the plan documenting this.
Also clarified that all new module script tags should use defer to
match the existing pattern (the modules query the DOM at load and
need the body parsed first).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../plans/2026-05-17-files-overlay-rewrite.md        | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/superpowers/plans/2026-05-17-files-overlay-rewrite.md b/docs/superpowers/plans/2026-05-17-files-overlay-rewrite.md
index fb7c02e..324d8fc 100644
--- a/docs/superpowers/plans/2026-05-17-files-overlay-rewrite.md
+++ b/docs/superpowers/plans/2026-05-17-files-overlay-rewrite.md
@@ -45,7 +45,7 @@ Direct-bind escape hatches (places we keep direct binding deliberately):
 
 Create the new directory. Move helpers (lines ~40-170 of the current file: `postJson`, `postForm`, `scheduleRefresh`, `parentOf`, `joinPath`, byte-count utility, manager-element detection, CSRF read). Add the file-row click delegation that currently lives at line 1054 — same selector match, but instead of switch-casing into local handlers, dispatch through a registry `window.__filesOverlay.handleAction(action, path, actionEl)` that feature modules register handlers into. Old `files-overlay.js` still has its own handlers for now — `core.js` dispatch is unused until subsequent steps wire features into it.
 
-base.html: add `<script src="files-overlay/core.js">` BEFORE `files-overlay.js` (so the registry exists when the old file runs).
+`overlay_detail.html` (NOT base.html): add `<script src="files-overlay/core.js" defer>` BEFORE the existing `files-overlay.js` script tag (currently at `overlay_detail.html:285`, also `defer`). The script tag lives in `overlay_detail.html` because `files-overlay.js` activates only when `.files-manager` exists (line 23-24 of the current file) — loading from `base.html` would pull the JS onto every page unnecessarily. **All new module script tags use `defer`** to match the existing pattern (the modules query the DOM at load time and need the body parsed first).
 
 Verification: existing functionality still works (click any file row → opens editor, +new-file → opens editor, +new-folder → opens new-folder modal, zip download works).
 
@@ -89,7 +89,7 @@ Convert upload-row cancel buttons (currently direct-bound at row creation, line
 
 Register file-row action handlers (`zip`) into `core.js` dispatch registry. (`zip` is just a navigation — could live in `core.js` directly; pick whichever reads cleaner.)
 
-Delete remaining migrated handlers from old `files-overlay.js`. After this step the old file is empty or near-empty. Replace with `<script src="files-overlay/uploads.js">` etc. in base.html (or delete the old `<script>` tag entirely if the file is empty). Initially leave the old file in place to avoid stretching this step further.
+Delete remaining migrated handlers from old `files-overlay.js`. After this step the old file is empty or near-empty. Add `<script src="files-overlay/uploads.js" defer>` etc. to `overlay_detail.html` alongside the (now-empty) `files-overlay.js` script tag (or delete the old `<script>` tag entirely if the file is empty). Initially leave the old file in place to avoid stretching this step further.
 
 Verification: drop a single file onto tree → uploads + appears; drop a folder onto tree → multiple uploads with progress; cancel in-flight upload → stops, row shows cancelled; click Clear → done rows removed; drag a file row to another folder → moves.
 
@@ -177,7 +177,7 @@ Verification: overlay detail page renders without the legacy dialog (DOM inspect
 
 **Step 10: delete `files-overlay.js` stub + update base.html**
 
-If `files-overlay.js` is empty or just an IIFE shell, delete it. Update `base.html` to load only the 4 new modules (`core.js`, `editor.js`, `dialogs.js`, `uploads.js`). Order doesn't strictly matter (each is an independent IIFE), but `core.js` first makes the registry-of-handlers pattern explicit.
+If `files-overlay.js` is empty or just an IIFE shell, delete it. Update `overlay_detail.html` (NOT base.html) to load only the 4 new modules (`core.js`, `editor.js`, `dialogs.js`, `uploads.js`), all with `defer`. Order doesn't strictly matter for execution (each is an independent IIFE), but `core.js` first makes the registry-of-handlers pattern explicit.
 
 Verification: full re-run of the URL-addressable-modals spec's verification matrix (10 checks); 4 new modules' features all work (editor text + binary + create-new; new-folder; conflict; delete-confirm; drag-drop; uploads cancel + clear).
 
@@ -224,7 +224,7 @@ End of Phase C: `routes/files_routes.py` ~450 lines (vs 640), no dead endpoints,
 | `l4d2web/l4d2web/static/js/files-overlay/dialogs.js` | A | New file |
 | `l4d2web/l4d2web/static/js/files-overlay/uploads.js` | A | New file |
 | `l4d2web/l4d2web/static/js/files-overlay.js` | A → B | Shrinks each step; deleted in step 10 |
-| `l4d2web/l4d2web/templates/base.html` | A, B | Script tag updates each phase end |
+| `l4d2web/l4d2web/templates/overlay_detail.html` | A, B | Script tag updates each phase end (currently loads files-overlay.js at line 285 with `defer`) |
 | `l4d2web/l4d2web/templates/overlay_file_editor.html` | B | Add new-file + binary-replace branches |
 | `l4d2web/l4d2web/templates/overlay_detail.html` | B | Delete legacy `<dialog id="files-editor-modal">` (step 9) |
 | `l4d2web/l4d2web/routes/files_routes.py` | B, C | Add `/files/new` route (step 5); extend `/files/edit` for binary (step 7); extract helpers (step 11); delete `/files/content` (step 12) |
@@ -259,6 +259,10 @@ After **each** commit, the working tree is in a known-good Chromium-verified sta
 
 Natural pause points: end of Phase A, end of Phase B, end of Phase C. Each phase delivers value independently — Phase A alone is a useful cleanup if the user doesn't want to do B and C.
 
+## Errata (pre-execution)
+
+- **Script tag location:** the plan's first draft incorrectly referenced `base.html` for the script tag updates. The actual location is `overlay_detail.html:285` (with `defer`). `files-overlay.js` and its replacement modules are page-scoped to overlay detail — loading from `base.html` would pull the JS onto every page when the `.files-manager` element only exists on overlay detail. All script tag references in this plan now correctly say `overlay_detail.html`. This errata is itself an example of the `feedback_validate_before_implementing` memory: probe the live state before trusting a plan claim.
+
 ## Out of scope
 
 - Adding a JS test framework (no JS tests in the project today; verification stays Chromium-driven).