n.siegfried/Project-SDE-WP-Suite
3
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

T7.1 prep - measure the iframe boundary before dissolving it

Browse Source 
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>
This commit is contained in:
Nick Siegfried
2026-08-17 00:28:25 -05:00
parent 7e33a3cbfd
commit d092db3920
1 changed files with 148 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
docs/reference/creator-frame.md Normal file
View File

@@ -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.