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.