Project-SDE-WP-Suite/docs/reference/creator-frame.md

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.

---

5. What T7.1 actually did — August 18, 2026

The measurement above assumed one shape of answer: merge the creator's markup and scripts into work-package-suite.html, and pay the 21 selector collisions and 9 global collisions to do it. That is not what shipped, and the reason is in this document's own numbers.

The creator became a top-level page instead of moving into the parent one. The tab strip is drawn by both documents, and the two tabs that used to swap a frame are now links. That satisfies every done-when in the wave file — no iframe, no cross-frame messaging, F4 resolved structurally, CR-006 toggles propagating with no special-casing, browser back and forward intact — while the wave file's prose ("renders in the parent document") describes the other route. Stated as a deviation, not smuggled: the boundary is dissolved by making the creator its own document rather than by dissolving it into another one.

Why, against the counts:

	Merging into the parent	Making it a page
Selector collisions to resolve	21	0
Script global collisions to resolve	9	0
Cross-frame call sites to remove	28	28
Probe call sites needing rework	~29	2

The collisions were never a cost of dissolving the boundary. They were a cost of merging two documents, which is a separate change that the boundary happened to be hiding. §2c called zero markup-id collisions "the single largest piece of good news"; the larger one turned out to be that 29 probe entry points address wp-creation-index.html directly, and a route that keeps that address keeps them all.

What the two duplications mean now:

• The sequence editor (9 of the 21 selectors) stays two components, which is what was confirmed on August 18 — authored in the SOP, adjustable per package. The duplication is real and stays visible as BL-015.
• Analytics and the feedback panel (all 9 globals) are still implemented twice. They are in two documents, so nothing collides, but T7.10 deletes one copy of analytics regardless. showAnalytics is the one §2b said to check first, and it was right: the wizard's copy still has no caller.

The three questions §4 said no count could answer

1. The creator got the app bar. It was the only page in html/ loading neither wp-chrome.css nor wp-chrome.js, because wp-chrome.js returned early inside an iframe. Both are loaded now, the header was reshaped into the .header-left / .header-right pair the suite page uses so the switcher lands in the same place on both, and the wizard's layout arithmetic — chromeHeight(), --wp-chrome-h, embed-full — was deleted rather than adjusted, because there is no frame to size.
2. Two sequence components, scoped rather than merged. See above.
3. body.embedded is gone, and with it .embed-hide. The header it hid was replaced by the app bar; the sample-data controls are visible in a new package toolbar (D1); the analytics button is visible there too until T7.10 moves it. The Dashboard button in that row became a tab, which is the one place the "fold the toolbar into the tab row" in B7 actually happened.

What was checked

tests/frame_check.py, 39 checks. Beyond the obvious ones it pins three things this document could not have predicted:

• Every old address still resolves. ?tab=wp, ?view=dashboard and ?wp=<id> are in bookmarks, in wp-sidenav's link map, and they are the shape the CR-011 and CR-014 emails were specified against (X1). The wizard forwards them with replace(), so Back does not bounce. Breaking these silently was the one regression this task could have shipped that nobody would notice for weeks.
• Both documents parse. A const shadowing a function parameter is a SyntaxError, and during this task it stopped work-package-suite-app.js parsing at all. Four checks in another probe went red and not one of them said "the script did not load". Asserting a page's own entry points exist costs nothing and says exactly that.
• The behaviour that changed. The live cross-frame hand-off of a section toggle showed the creator a toggle that had not been saved: flip it, look, reload, and the section came back. What the creator shows now is the SOP that is stored. sections_check.py 5b pins both halves — an unsaved toggle does not travel, a saved one does.

BL-020 is the one thing that got worse: a tab switch is a page exit now, so leaving the wizard with unsaved SOP edits fires T4.3's unsaved-work guard. Nothing is lost — the guard writes the draft first and T4.3 recovers it — but it is friction that did not exist, and suppressing a deliberate guard is a decision with its own downside, so it is logged rather than quietly handled inside a structural task.