From d092db3920e9c28d1c4a3af6f3b23fab3772d3d8 Mon Sep 17 00:00:00 2001
From: "n.siegfried" <n.siegfried@prime-controls.com>
Date: Mon, 17 Aug 2026 00:28:25 -0500
Subject: [PATCH] T7.1 prep - measure the iframe boundary before dissolving it

Wave 7 opens with the largest engineering item in the plan, and the wave file is
explicit that it ships alone. This is the measurement that should precede it -
the same role tokens.md played for T3.2, produced for the same reason: the
estimate in the plan came from a read of the symptom, not a count of the work.

Four numbers, and where they come from:

  page-stylesheet selectors colliding   21   (9 of them the sequence editor)
  script top-level names colliding       9   (all of them one feature done twice)
  markup ids colliding                   0
  cross-frame call sites                28   across 8 scripts and 1 page

The zero is the largest piece of good news available: 96 and 127 ids and not one
shared, so every getElementById in both files survives the merge untouched.

The nine script collisions are misleading in the other direction. They are not
nine names for nine things - they are usage analytics and the feedback panel,
each implemented twice. The merge is a de-duplication, not a rename, and behind
nine names sit two parallel implementations.

Also recorded: every cross-frame call added by waves 5 and 6 is a shim over the
boundary, is commented as such, and is DELETED by T7.1 rather than migrated.
T5.5 already proved the SOP-borne propagation path needs no boundary crossing at
all, which is X4 resolved rather than outstanding.

And three questions no count can answer, which T7.1 has to settle: whether the
creator gets an app bar back, whether the sequence editor becomes one component
or two, and what happens to body.embedded when "framed" stops being a state.

Wave 7's implementation is NOT started. This commit is measurement only, and
nothing in html/ or server/ changed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/reference/creator-frame.md | 148 ++++++++++++++++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 docs/reference/creator-frame.md

diff --git a/docs/reference/creator-frame.md b/docs/reference/creator-frame.md
new file mode 100644
index 0000000..c654354
--- /dev/null
+++ b/docs/reference/creator-frame.md
@@ -0,0 +1,148 @@
+# The creator's iframe boundary — what `T7.1` has to untangle
+
+**Produced for:** `T7.1` (`B7`) · **Measured:** August 17, 2026 · **Branch:** `feat/wp-suite-r2-implementation`
+**Read by:** `T7.1`, and every task from `T7.2` down, since all of them depend on it
+
+`T7.1` is described in the plan as the largest engineering item in it, and the wave file is
+explicit that it ships as its own change with no feature work attached. This document is the
+measurement that should precede it — the same role `docs/reference/tokens.md` played for
+`T3.2`, and produced for the same reason: the estimate in the plan came from a read of the
+symptom, not a count of the work.
+
+**Nothing here is a decision.** It is four numbers and where they come from.
+
+---
+
+## 1. What the boundary actually is
+
+`work-package-suite.html` declares `<iframe id="wp-frame">` with no `src`.
+`work-package-suite-app.js` sets it at runtime to
+`wp-creation-index.html?embedded=1&project=<id>`.
+
+The creator is the only page in `html/` that loads **neither `wp-chrome.css` nor
+`wp-chrome.js`** — that is why it has no app bar of its own and why it reads as part of the
+wizard rather than as a page. Dissolving the frame means deciding whether it gets that chrome
+back or deliberately does not; the wave file leaves that open and it is the one design
+question inside an otherwise mechanical task.
+
+---
+
+## 2. The four collisions, counted
+
+Merging two documents means merging four namespaces. Three of the four are far smaller than
+they look, and the fourth is zero.
+
+| Namespace | Wizard | Creator | Colliding |
+|---|--:|--:|--:|
+| Page-stylesheet class/id selectors | 104 | 307 | **21** |
+| Script top-level names | 156 | 299 | **9** |
+| Markup `id` attributes | 96 | 127 | **0** |
+| Cross-frame call sites | — | — | **28**, across 8 scripts and 1 page |
+
+### 2a. The 21 colliding selectors
+
+```
+active  add-btn  col1  drag-over  dragging  field  field-grid  field-hint
+gate  header  header-title  is-current  modal  notice  seq-arrow
+seq-gate-badge  seq-handle  seq-label  seq-num  seq-step  sub-heading
+```
+
+`file-map.md` §2 predicted exactly this and said not to assume it stays harmless: *"They are
+mutually exclusive per page today … so nothing currently breaks — wave 3 must not assume that
+stays true once chrome is unified."* It is now the thing that breaks.
+
+Nine of the twenty-one are the **sequence editor** (`seq-*`, `drag-over`, `dragging`, `gate`),
+which exists in both because the wizard authors the sequence and the creator renders it. Those
+are the same component drawn twice, and merging them is a real question rather than a rename.
+
+The other twelve are generic layout names — `field`, `notice`, `modal`, `header` — where the
+two sheets simply disagree about padding and type. Those are a rename or a scope, not a
+design decision.
+
+### 2b. The 9 colliding script names
+
+```
+ANALYTICS_KEY  analyticsLoad  analyticsSave  downloadAnalytics  showAnalytics
+exportComments  importComments  toggleComments  track
+```
+
+Every one of them is **the same feature implemented twice** — usage analytics and the feedback
+panel. None is a genuine name clash between two different things. That means the merge is a
+de-duplication rather than a rename, and it makes the count misleadingly small in the other
+direction: nine names, but two parallel implementations of two features behind them.
+
+`showAnalytics` is the one to check first — `T5.8` recorded that the wizard's copy has **no
+caller in the wizard's markup**, because the "Usage data" button lives on the creator and calls
+the creator's own.
+
+### 2c. Markup ids: zero collisions
+
+96 and 127 ids, none shared. That is luck rather than design, and it is the single largest
+piece of good news in this document: every `getElementById` in both files keeps working.
+
+### 2d. The 28 cross-frame call sites
+
+Spread across `auth-guard.js`, `help.js`, `project-data.js`, `sw.js`,
+`work-package-suite-app.js`, `wp-chrome.js`, `wp-creation-app.js`, `wp-sidenav.js` and
+`work-package-suite.html`.
+
+Three scripts branch on `window.top !== window.self` and change behaviour when the frame goes:
+
+| Script | Framed behaviour today |
+|---|---|
+| `auth-guard.js` | redirects `window.top` to `login.html` |
+| `wp-chrome.js` | returns early, renders no chrome |
+| `help.js` | suppresses the Help FAB in the child |
+
+And the parent reaches **into** the child at four call sites, all added or touched by waves 5
+and 6, all commented as `T7.1` removes them:
+
+| Call | Added by | Purpose |
+|---|---|---|
+| `cw.openWpById(id)` | before wave 5 | open a deep-linked package |
+| `cw.showDashboard()` / `cw.showForm()` | before wave 5 | switch view |
+| `cw.dashApplyFlag(flag)` | `T5.3` | carry the pipeline strip's filter across |
+| `cw.applySopSections(sections, fields)` | `T5.5` / `T5.6` | carry a section toggle across |
+
+The last two are the ones `X4` is about. **Both become unnecessary** when the frame goes —
+they exist only because the two documents cannot share a variable.
+
+---
+
+## 3. What wave 5 and 6 already did to shrink this
+
+Recorded so `T7.1` does not redo it:
+
+- **`T5.5` proved the SOP-borne path works.** Section toggles reach the creator through the
+  SOP it reads at its own boot, with nothing crossing the boundary. The live hand-off is the
+  *second* path and is the only part `T7.1` deletes. `X4`'s concern was resolved in wave 5 and
+  is not outstanding.
+- **`T5.3`'s dashboard filter is URL state.** The creator reads `?flag=` at boot. The
+  hand-off exists only for the already-loaded frame, and goes the same way.
+- **`T6.3`'s location dropdowns fetch from the server**, not from the parent. Nothing new
+  crosses the boundary.
+
+Every cross-frame call added since wave 4 is a *shim over the boundary*, is commented as such,
+and is deleted rather than migrated.
+
+---
+
+## 4. What this does not tell you
+
+Three things `T7.1` has to settle that no count can answer:
+
+1. **Does the creator get the app bar back?** It is the only page without one. Giving it one
+   changes the wizard's layout maths (`chromeHeight()`, `--wp-chrome-h`, the `embed-full`
+   sizing); not giving it one leaves a page that is not a page.
+2. **One sequence component or two?** Nine of the twenty-one selector collisions are the
+   sequence editor. Merging it is a genuine consolidation; scoping it is a rename that leaves
+   the duplication in place for wave 9 to find again.
+3. **What happens to `body.embedded`?** `wp-creation-styles.css` opens with
+   `body.embedded .embed-hide { display: none }` — the creator hides its own header, its own
+   sample-data controls and its own analytics button when framed. Dissolved, "framed" stops
+   being a state and those controls need a home or a deletion.
+
+`BL-001`, `BL-006`, `BL-007` and `BL-013` are all logged against `T7.1` and all live in
+`wp-creation-styles.css`. If that sheet is being scoped or rewritten anyway, they are cheaper
+now than they will ever be again — but they are separate items and `T7.1` says to bundle
+nothing.