efficient-easel 21.0.0 → 21.1.0

package/dist/screen/lib/document/content-tree.d.ts

@@ -0,0 +1,222 @@
+type TreeItem = {
+    type: string;
+    props: {
+        id: string;
+        [key: string]: unknown;
+    };
+};
+type SlotConfigView = {
+    components?: Record<string, unknown>;
+};
+/**
+ * Which of a component type's props are SLOTS — the prop names that hold child
+ * Blocks, read off the config's field map.
+ *
+ * Puck 0.20 stores slot children INLINE on the parent's props
+ * (`props.<slotName> = [{type,props}, …]`), NOT in `data.zones` — so a walker
+ * that wants a section's children has to know which prop names to look under.
+ * That set is per-component and lives in exactly one place, `config.components`:
+ * `Grid`/`Flex` call theirs `content`, but `Hero` calls it `slides`,
+ * `Collections` `cards`, `GalleryB` `items`, `ProductGrid` `products` and
+ * `Footer`/`FooterGroup` `blocks`.
+ *
+ * This is the ONE reader of that set. Hard-coding `"content"` instead is how the
+ * heading/SEO audit came to be blind to every heading nested in a Hero slide
+ * (card 66067): the walker recursed on a prop name only two of the eight slots
+ * happen to use, so a page with two H1s reported as fine. A type the config does
+ * not know has no slots — and cannot render either, so there is nothing to walk.
+ */
+declare function slotFieldsOf(config: SlotConfigView, type: string): string[];
+/**
+ * What a component type's config ALLOWS of the two actions that make another
+ * node or take one away (0.103.0): its `permissions.duplicate` and
+ * `permissions.delete`, each true unless the config says false — the reading
+ * Puck gave a config that carried none. The campaign designer's Product keeps
+ * its Price line this way (`{ delete: false, duplicate: false }`).
+ *
+ * The screen's tree rows, its menu and the inspector head it hands this to
+ * (`ScreenInspectorPanelProps.nodeActions`) all ask HERE, so the three cannot
+ * come to disagree about one block. Only the config's own, never the
+ * easel-wide permissions the edit lock sets: a document somebody else holds is
+ * refused at the writes, as it always was, and draws the rows it drew.
+ *
+ * A type the config does not know allows both, as one with no `permissions`.
+ */
+declare function blockNodeActions(config: SlotConfigView, type: string): {
+    duplicate: boolean;
+    delete: boolean;
+};
+/**
+ * A slot child, addressed the way the Layers tree selects it: the node, the
+ * compound zone key "<parentId>:<slotName>" Puck's ops take, and its index in
+ * that slot.
+ */
+type SlotChild = {
+    child: TreeItem;
+    zone: string;
+    index: number;
+};
+/**
+ * Every slot child of `item`, across EVERY slot field its type declares — so a
+ * type with two slots reports both, and nesting is general: the result's `child`
+ * is itself an item this function accepts.
+ *
+ * Puck 0.20 stores slot children INLINE on the parent's props, so this reads the
+ * arrays rather than `data.zones` (which stays empty for slots).
+ */
+declare function childSlotsOf(config: SlotConfigView, item: TreeItem): SlotChild[];
+/**
+ * The children of ONE slot of `item`, addressed as {@link childSlotsOf}
+ * addresses them (0.105.0): what the Layers tree draws under a slot it draws
+ * as a row of its own (`ScreenBlockRules.slotsOf`). A slot the node holds
+ * nothing in, or no array in, has none.
+ */
+declare function slotChildrenIn(item: TreeItem, slot: string): SlotChild[];
+/**
+ * WHERE a node sits in the document — the node itself, the zone key its own
+ * array is addressed by, and its index in that array. Exactly the three
+ * arguments a Puck `replace` / `remove` / `reorder` op takes.
+ */
+type NodeLocation = {
+    item: TreeItem;
+    zone: string;
+    index: number;
+};
+/**
+ * Find a node by id and say WHERE IT IS, anywhere in the document — the root
+ * list or any slot at any depth.
+ *
+ * ── WHY A PANEL NEEDS THIS ──────────────────────────────────────────────────
+ * `useEasel((s) => s)` hands a field the SELECTED node and, in `ui.itemSelector`, the
+ * zone and index of that node. A control that has to rewrite the node's PARENT
+ * — "Apply to all cards" writes the whole Collections node once, so one press is
+ * one undo step — gets only half of what it needs: the selector's zone is the
+ * compound `"<parentId>:cards"`, which names the parent but says nothing about
+ * where the PARENT itself lives. Without that, the write has nowhere to go.
+ *
+ * ⚠️ IT IS NOT `enclosingSectionProps`, AND THE DIFFERENCE IS NOT COSMETIC.
+ * That one answers "which TOP-LEVEL section is this inside", returns props, and
+ * deliberately returns `null` for the immediate parent when the parent is not a
+ * root section. This one answers "where is THIS node", returns an address, and
+ * is happy to name a node nested inside a Box inside a Box. Its own docblock
+ * asks for a third question to be a third function rather than a third shape
+ * returned by the same walker; this is that function.
+ *
+ * ⚠️ AND IT IS NOT `childSlotsOf` WITH A FILTER. That lists one node's children;
+ * this searches a whole document. It is BUILT on `childSlotsOf` so the set of
+ * slot prop names stays read in exactly one place — hard-coding `"content"`
+ * instead is how the heading audit went blind to every heading nested in a Hero
+ * slide (card 66067), and the reason is written out on `slotFieldsOf`.
+ *
+ * ⚠️ THE CHROME ALREADY ANSWERS THIS, AND THAT IS NOT A DUPLICATE OF THIS.
+ * `ScreenChrome` memoises a Map of EVERY node's address (plus each
+ * zone's whole sibling list) and hands the lookup to the context menu as
+ * `locate`. That map is built once per document for a surface that needs all of
+ * it; this finds ONE node and is reachable from a Puck field, which the map is
+ * not — it lives in a component's closure and rides no context. What must not
+ * be two things is the set of SLOT PROP NAMES, and it is not: both walk through
+ * `childSlotsOf`, so an address here and an address there cannot disagree.
+ * Puck's own `getSelectorForId` is a third reader of the same fact, and the one
+ * a live store already offers — it is a hook-bound function, so a guard cannot
+ * call it, which is the whole reason this one is written pure.
+ *
+ * PURE, and takes the config as an argument, so a guard can assert against it
+ * without a Puck store, a React tree or a hook.
+ *
+ * `null` when no node carries the id — the honest answer for a stale selection,
+ * and every caller treats it as "there is nothing to write".
+ */
+declare function locateNode(config: SlotConfigView, content: ReadonlyArray<TreeItem>, id: string): NodeLocation | null;
+/**
+ * How many levels of slot children the Layers tree draws below a top-level row.
+ *
+ * The tree is a ~288px panel that already scrolls and each level costs 10px of
+ * indent (`.sf-subtree`'s `padding-left`, storefront-editor.css — it was 25px
+ * until card 66199 took the drag grip out of the flow and moved the caret to the
+ * row's right end), so the depth is capped rather than unbounded: `Grid.content`
+ * is an open slot that accepts a Grid, so a document CAN nest without limit and a
+ * tree that followed it would run out of width.
+ *
+ * ⚠️ 3 SINCE CARD 66273, and the level it buys is the one a merchant was stuck
+ * on. A hero group's blocks are the THIRD level — Hero → slide → group → blocks
+ * — and at 2 a group row was a LEAF: no `.sf-subtree` was rendered under it, so
+ * the "Add block" row that lives inside that subtree had nowhere to go, and a
+ * merchant who made a group in the tree could not put anything into it. The
+ * number was 2 because the Footer's chain (Footer → blocks → Group → blocks) was
+ * the only one that existed when the cap was named; the hero's is one level
+ * deeper.
+ *
+ * The Footer is unaffected, measured rather than hoped: `FooterGroup.blocks`
+ * allows FooterText / FooterEmailSignup / FooterMenu / FooterDivider and none of
+ * those owns a slot, so no footer row grows a third level. What DOES gain one is
+ * a container nested inside a container (a Box in a Box) —
+ * blocks a merchant can already build and could not see.
+ */
+declare const TREE_MAX_DEPTH = 6;
+/**
+ * Does the Layers tree draw a subtree under a node of `type` sitting at `depth`?
+ * True only when the type owns at least one slot AND the level is inside the cap.
+ * `depth` is 1 for a section's own children (the first `.sf-subtree`).
+ *
+ * The ONE place the cap is decided — both tree renderers and the "collapse all"
+ * gather read it here, so a row that folds and a row that draws children can
+ * never disagree about which rows those are.
+ */
+declare function nestsInTree(config: SlotConfigView, type: string, depth: number): boolean;
+declare const newNodeId: (type: string) => string;
+declare const HEADER_TYPE = "Header";
+declare const FOOTER_TYPE = "Footer";
+declare const ROOT_ZONE = "root:default-zone";
+/**
+ * Indices of the DUPLICATE pinned chrome sections in a top-level content array —
+ * every Header/Footer node PAST the first of its type, in ascending order. Empty
+ * when the array already holds at most one of each (the healthy case), so a caller
+ * can skip the rewrite. Keeping the FIRST of each type matches exactly what the
+ * Sections tree shows (footerIndex/findIndex), so healing never surprises the
+ * author by dropping the copy they were looking at. Accepts a loose node shape so
+ * both the editor's `TreeItem[]` and the published render's untyped content pass.
+ */
+declare function pinnedDuplicateIndices(content: ReadonlyArray<{
+    type?: string;
+}>): number[];
+/**
+ * Ids of the DUPLICATE pinned chrome sections — the id-anchored counterpart of
+ * pinnedDuplicateIndices, derived FROM it so the two can never disagree about
+ * which copy is the keeper (the first of each type).
+ *
+ * A LIVE store must be edited by identity, never by position: an index computed
+ * from a render snapshot addresses whatever has since shifted into that slot,
+ * which is how the old editor heal deleted real sections. Ids survive that skew
+ * — the worst a stale read can do is name a node that is no longer there. A
+ * duplicate carrying no id is skipped (it cannot be named in a remove); the
+ * published render's index-based dedupe still drops it.
+ */
+declare function pinnedDuplicateIds(content: ReadonlyArray<{
+    type?: string;
+    props?: {
+        id?: unknown;
+    };
+}>): string[];
+/**
+ * Which pinned chrome types a document is MISSING, and a load-time seed must
+ * therefore create. A type counts as missing only when it is absent from BOTH:
+ *
+ *   - `live` — the editor's Puck store, read at the moment of the write; and
+ *   - `persisted` — the document exactly as it was LOADED from the backend.
+ *
+ * Requiring both is what makes seeding idempotent, and neither check can be
+ * dropped. Trusting `live` alone was the duplicate-Header bug: a remount re-armed
+ * the seed's per-mount guard while a snapshot that lagged the store reported "no
+ * Header", so a second one was appended next to the first. Trusting `persisted`
+ * alone would re-seed a node this session has already inserted but not yet saved.
+ *
+ * Returned in no particular order — the CALLER owns the insert order, because
+ * only it knows that the Footer is pinned last and the Header first.
+ */
+declare function missingPinnedTypes(live: ReadonlyArray<{
+    type?: string;
+}>, persisted: ReadonlyArray<{
+    type?: string;
+}>): string[];
+
+export { FOOTER_TYPE, HEADER_TYPE, type NodeLocation, ROOT_ZONE, type SlotChild, type SlotConfigView, TREE_MAX_DEPTH, type TreeItem, blockNodeActions, childSlotsOf, locateNode, missingPinnedTypes, nestsInTree, newNodeId, pinnedDuplicateIds, pinnedDuplicateIndices, slotChildrenIn, slotFieldsOf };

package/dist/screen/lib/document/content-tree.js

@@ -0,0 +1 @@
+export{FOOTER_TYPE,HEADER_TYPE,ROOT_ZONE,TREE_MAX_DEPTH,blockNodeActions,childSlotsOf,locateNode,missingPinnedTypes,nestsInTree,newNodeId,pinnedDuplicateIds,pinnedDuplicateIndices,slotChildrenIn,slotFieldsOf}from"../../../chunk-TCAAOYQY.js";

package/dist/screen/lib/document/device-fields.d.ts

@@ -0,0 +1,128 @@
+import { ReactElement } from 'react';
+import { PreviewDevice } from '../../components/PreviewDeviceContext.js';
+import '../content/view-tiers.js';
+
+/**
+ * lib/document/device-fields.tsx — show the setting for the device the merchant is
+ * currently looking at, and only that one.
+ *
+ * THE PROBLEM. A section that can be sized differently on a phone stores TWO
+ * props and the panel drew BOTH, side by side, told apart only by a "(desktop)"
+ * / "(mobile)" suffix on the label. The canvas already knows which device is on
+ * screen; the panel ignored it, so the merchant read labels to find the control
+ * that matched what they were looking at.
+ *
+ * THE MECHANISM, and why this one. A Puck `resolveFields` cannot do it: in this
+ * Puck version the fields slice re-resolves only when the selected node's DATA
+ * changes (`useRegisterFieldsSlice` subscribes to `state.indexes.nodes[id]`), and
+ * switching device changes no data — the panel would keep whatever field set the
+ * last edit produced. So the decision is made where it can re-render freely: in
+ * the FIELD ITSELF, off the React context the editor chrome already publishes
+ * (`components/PreviewDeviceContext`, which the per-view Footer controls read
+ * for the same reason). One context, no prop threaded anywhere, and every house
+ * control is already a `type: "custom"` render, so wrapping one costs nothing.
+ *
+ * ⚠️ HIDDEN IS NOT DELETED. {@link deviceField} returns the SAME field object
+ * with the same markers (`__media`, `__text`, …) and the same key; only its
+ * paint is gated. Both props keep existing, keep their keys, keep their values
+ * and keep their `defaultProps`. Switch to Phone, type a size, switch back — the
+ * desktop size is exactly where it was, because nothing ever wrote to it.
+ * `scripts/test-device-fields.tsx` pins that round trip.
+ *
+ * TABLET (owner ruling, card 66066). There are no tablet-specific stored values
+ * today, and inventing them would mean a new stored prop on every section — a
+ * different card. So tablet shows the DESKTOP values and the panel SAYS SO
+ * ({@link DEVICE_NOTE}); it never presents desktop values as if they were
+ * tablet's. {@link shownTier} is the single place that ruling is written down.
+ *
+ * WHY THE HIDDEN FIELD LEAVES NO GAP. Puck wraps every top-level field in its
+ * own padded `_PuckFields-field_` box before it calls `render`, so a field that
+ * renders nothing would still cost ~37px of empty panel. The gate instead paints
+ * a zero-size marker and this package's `screen.css` collapses the
+ * wrapper that contains one — the same "reach the wrapper Puck owns" trick the
+ * fold reflow in `controls.tsx` already relies on, expressed as one CSS rule
+ * instead of a second DOM pass (so it cannot race the fold's).
+ */
+
+/** The two tiers a stored value can belong to. Tablet is not one — see
+ *  {@link shownTier}. */
+type DeviceTier = "desktop" | "mobile";
+/**
+ * Which tier's stored values the panel shows for a given preview device.
+ *
+ * The owner ruling in one expression: phone shows the phone values, everything
+ * else — desktop AND tablet — shows the desktop values.
+ */
+declare function shownTier(device: PreviewDevice): DeviceTier;
+/**
+ * The quiet line the panel puts above a section's settings, so a merchant can
+ * always tell WHICH device's value they are editing without reading the canvas.
+ *
+ * Desktop says nothing: it is the resting state, and a banner that is always
+ * there is a banner nobody reads. Tablet says the ruling out loud rather than
+ * letting the desktop values pass for tablet's own.
+ */
+declare const DEVICE_NOTE: Readonly<Record<PreviewDevice, string | null>>;
+/** The attribute the stylesheet looks for to collapse a gated-off field's Puck
+ *  wrapper. Declared here, matched once in this package's `screen.css`, which
+ *  every host that mounts the screen loads (it sat in the website's sheet until
+ *  0.103.0, so a second host's hidden rows kept their space). */
+declare const DEVICE_HIDDEN_ATTR = "data-sf-device-hidden";
+/** A house control's render, seen from outside: the builders in `controls.tsx`
+ *  each type their own props, so the gate takes the widest shape that can be
+ *  passed straight back through. */
+type FieldRender = (props: Record<string, unknown>) => ReactElement;
+/** Any house control — every one of them is a `type: "custom"` field whose
+ *  `render` is a plain function of its props. */
+type AnyCustomField = {
+    type: "custom";
+    render: FieldRender;
+};
+/** Marker carried by every gated field, in the same style as
+ *  {@link import("./controls").FOLD_FIELD_MARKER}: the tier and the field it
+ *  wraps live ON the field object, never only inside the render closure. Without
+ *  it a gated control is opaque to every static walk — and the fold guard in
+ *  `scripts/test-section-groups.ts` genuinely needs to see the header underneath
+ *  to check its label against what it draws. Puck ignores extra keys. */
+declare const DEVICE_FIELD_MARKER: "__device";
+/** The payload on {@link DEVICE_FIELD_MARKER}. */
+type DeviceFieldMeta = {
+    tier: DeviceTier;
+    inner: unknown;
+};
+/** Read a field's device payload, or null when it is not gated. The ONE place
+ *  that knows the marker's shape. */
+declare function deviceMetaOf(field: unknown): DeviceFieldMeta | null;
+/** The field a gate wraps, or the field itself when it wraps nothing — what a
+ *  static walk wants to look at. */
+declare function withoutDeviceGate(field: unknown): unknown;
+/**
+ * Paint `field` only while the canvas is showing `tier`.
+ *
+ * Everything else about the field is preserved by identity-spread — its `type`,
+ * its manifest markers, its data keys — so the media and neutralization walks,
+ * the field-key census and every stored prop see exactly what they saw before.
+ */
+declare function deviceField<F extends {
+    type: "custom";
+    render: (p: never) => ReactElement;
+}>(tier: DeviceTier, field: F): F;
+/**
+ * The panel's device indicator — one quiet line, and only when there is
+ * something to say (see {@link DEVICE_NOTE}).
+ *
+ * Declared as a FIELD rather than painted by the chrome so it sits inside the
+ * settings panel it describes, above the first group, and so a section that has
+ * no device-varying control never shows it. It edits nothing: like `group()` /
+ * `section()` it is a header, with no prop behind it.
+ *
+ * …WHICH IS WHY IT SAYS SO ON THE FIELD (card 66201). A note is not a control, so
+ * a heading with nothing but this under it is a heading over nothing — and it is
+ * the whole reason the Hero's Content tab was empty: `_dDevice` is the section's
+ * first field, so it opened the implicit leading Content run and gave the panel a
+ * Content tab with only a banner in it, while the hero's actual copy is edited in
+ * the Text sub-panel.
+ */
+declare function deviceNote(): AnyCustomField;
+
+export { DEVICE_FIELD_MARKER, DEVICE_HIDDEN_ATTR, DEVICE_NOTE, type DeviceFieldMeta, type DeviceTier, deviceField, deviceMetaOf, deviceNote, shownTier, withoutDeviceGate };

package/dist/screen/lib/document/device-fields.js

@@ -0,0 +1 @@
+export{DEVICE_FIELD_MARKER,DEVICE_HIDDEN_ATTR,DEVICE_NOTE,deviceField,deviceMetaOf,deviceNote,shownTier,withoutDeviceGate}from"../../../chunk-KWLHKKZO.js";import"../../../chunk-INRERJU4.js";import"../../../chunk-EB6NI2VK.js";import"../../../chunk-MFIRYGHW.js";import"../../../chunk-BSPCSC45.js";

package/dist/screen/lib/document/field-buckets.d.ts

@@ -0,0 +1,36 @@
+import { S as SettingsBucket, D as DesignGroup } from '../../../buckets-Sw94ll9I.js';
+
+/**
+ * lib/document/field-buckets.ts — the two settings buckets a section's fields are
+ * sorted into (Design, Animation: owner 2026-10-08, final 2026-10-10), the
+ * field key each bucket's header is emitted under, and the field key of each
+ * Design group's heading.
+ *
+ * Moved out of lib/document/field-groups (which re-exports both) so the editor's
+ * screen can read a header's key — the style clipboard copies a look by the
+ * groups it sits in — without importing the field builders that sort a
+ * section's fields (doc/adr/0004). The reasoning behind the buckets themselves
+ * stays in field-groups, beside the pass that applies them.
+ */
+
+type Bucket = SettingsBucket;
+/**
+ * The field key each bucket's header is emitted under. `_s*` because these are
+ * level-1 headers (`section()`), matching the `_s*` convention the sections that
+ * already carry level-1 headers use (`_sText`, `_sImage`, `_sSetup`, …).
+ */
+declare const BUCKET_KEY: Record<Bucket, string>;
+/**
+ * The field key of each Design group's heading, inside the Design bucket. The
+ * HOST emits them, in `DESIGN_GROUPS` order, one for each group it has; a row
+ * belongs to the heading above it. `_dContent` is a marker that draws no
+ * heading (the Content part has none), and the rows before the first group
+ * heading of Design are Content too. `_d*` for Design's own headings, apart
+ * from the `_s*` bucket headers and the `_g*` group headers a section draws.
+ * Only these six keys are group headings: `_dDevice` (the device note,
+ * ./device-fields) shares the prefix and is not one, so never read a group off
+ * the prefix.
+ */
+declare const DESIGN_GROUP_KEY: Record<DesignGroup, string>;
+
+export { BUCKET_KEY, type Bucket, DESIGN_GROUP_KEY };

package/dist/screen/lib/document/field-buckets.js

@@ -0,0 +1 @@
+export{BUCKET_KEY,DESIGN_GROUP_KEY}from"../../../chunk-3QB2ZQXK.js";

package/dist/screen/lib/document/field-markers.d.ts

@@ -0,0 +1,205 @@
+import { TextControlKind } from './text-control-kinds.js';
+
+/**
+ * field-markers — what a field DECLARES about itself, readable without the
+ * inspector.
+ *
+ * A control factory in `lib/document/controls` stamps a marker on the field object
+ * it returns: this prop holds authored copy, this one a link, this row array
+ * draws these scaffold rows while it is empty. Two kinds of code read those
+ * stamps. The inspector does, and so does the RENDER side — the part walk that
+ * makes a headline clickable (`lib/document/text-parts`), the typing bridge
+ * (`lib/document/part-text`, `lib/document/part-rows`) — and a section's own option
+ * module may be typed by a control's vocabulary (`lib/sections/ticker-scroll`
+ * names the pad cell each direction sits in).
+ *
+ * ⚠️ WHY THIS IS ITS OWN FILE. The markers were born in `controls.tsx` beside
+ * the factories that stamp them, and `controls.tsx` is the inspector: React, the
+ * editor shell, the link picker, the form picker, and through them the API
+ * client and the cart. A render-side module that only wanted the string
+ * `"__text"` imported all of it, which is what kept a general section from being
+ * drawn anywhere the inspector cannot go (doc/adr/0002). The same split, for the
+ * same reason, that `lib/document/hidable` and `lib/document/text-control-kinds` already
+ * made.
+ *
+ * This file imports nothing but that kinds leaf. `controls.tsx` re-exports
+ * every name, so an inspector-side import site is unchanged; a render-side
+ * module imports from HERE. `scripts/test-general-sections-import-boundary.ts`
+ * fails when one goes back to `controls`.
+ */
+
+/** Marker carried by every AUTHORED-TEXT field object, mirroring
+ *  {@link MEDIA_FIELD_MARKER} below. The neutralization manifest
+ *  GENERATOR (`scripts/gen-neutralization-manifest.ts`) walks the built config
+ *  looking for it, so the text factories are the single source of truth for
+ *  "this prop holds customer-authored copy" — a new text field is covered the
+ *  moment it is declared, with no list to maintain anywhere (Puck ignores extra
+ *  keys).
+ *
+ *  Unlike the media marker this carries a PAYLOAD, because the neutralizer needs
+ *  more than a boolean: the declared `placeholder` IS the neutral replacement
+ *  copy (the greyed hint the designer already wrote for an empty field), and
+ *  `control` says which value shape the prop stores — `text`/`textarea` persist
+ *  `{ text, hidden }` once edited, the `plain*` variants stay bare strings, and
+ *  `textList` stores `{ text }[]`. A neutralizer that assumed "string" would
+ *  silently skip most EDITED copy. */
+declare const TEXT_FIELD_MARKER: "__text";
+/** Marker carried by every LINK-DESTINATION field. A destination is not authored
+ *  prose — it is a tenant-specific target (an internal path, an absolute URL, a
+ *  `mailto:`/`tel:`, or an in-page `#anchor`) — so it neutralizes by its own rule
+ *  rather than to placeholder copy. Kept separate from {@link TEXT_FIELD_MARKER}
+ *  so the two can never be conflated. */
+declare const LINK_FIELD_MARKER: "__link";
+/**
+ * Marker carrying the rows a ROW-ARRAY field draws in the editor preview while
+ * its stored value is still empty — the `phRows` scaffold, declared on the field
+ * instead of only at the render call.
+ *
+ * WHY IT HAS TO BE ON THE FIELD. A scalar text control already declares its own
+ * greyed hint (`placeholder` above), and everything that asks "what does this
+ * prop put on screen?" — the neutralizer, the part walk — reads it there. A row
+ * array had no equivalent: `config.tsx` passes the scaffold constant straight
+ * into `phRows(value, SCAFFOLD, puck)` inside the render, where nothing outside
+ * the component can see it. So a freshly-dropped section drew three grey rows of
+ * scaffold copy that `lib/document/text-parts` could not name, and clicking that copy
+ * opened the whole section instead of the one control behind it (card 66072).
+ *
+ * It is the SAME constant the render passes — `withScaffold` (in
+ * `lib/document/controls`) takes it as an argument rather than copying it — so the
+ * preview and the walk cannot drift. Puck ignores extra keys on a field, exactly
+ * as it does for the two markers above.
+ */
+declare const SCAFFOLD_FIELD_MARKER: "__scaffold";
+/**
+ * How the SECTION consuming a `textList` draws each row — and therefore whether
+ * the list may offer a formatting bar at all.
+ *
+ * This is the `COPY_FIELD_TOOLS` rule (`lib/markup.ts`) applied one level up. Upstream, the
+ * button set is derived from the grammar so a tool whose output the parser cannot
+ * read back can never appear. Here the same question is asked of the CONSUMER: a
+ * `"markup"` list is one whose rows go through `renderGold`, so every mark the
+ * grammar writes is drawn; a `"verbatim"` list is printed as-is (an Integrations
+ * chip, a ContactRouting meta line, a Mockup kanban card), where `**bold**` would
+ * reach the shopper as four literal asterisks. A mark stored where nothing renders
+ * it is a bug, not a feature — so a verbatim list gets no bar.
+ *
+ * DELIBERATELY REQUIRED, with no default. The two facts — what a field offers and
+ * what its section renders — sit in different files, and a default would let them
+ * agree by luck: whichever way it pointed, the next `textList` would inherit an
+ * answer nobody checked. Stating it at the call site puts the question in front of
+ * whoever adds the field, next to the render that answers it.
+ */
+type TextListRendering = 
+/** Rows render through `renderGold` — the shared grammar parses them back. */
+"markup"
+/** Rows are printed exactly as stored; a delimiter would reach the shopper. */
+ | "verbatim";
+/** The payload on {@link TEXT_FIELD_MARKER}: what a text field says about the
+ *  copy it holds. The `with…` wrappers that set its optional facts, and the
+ *  readers that pair with them, are in `lib/document/controls`. */
+type TextFieldMeta = {
+    control: TextControlKind;
+    /** The control's inspector label — a classification signal when a field
+     *  declares no placeholder (labels read "Heading …", "Body …", "Alt text"). */
+    label: string;
+    /** The declared greyed hint. PRIMARY source of the neutral replacement copy. */
+    placeholder?: string;
+    /** The one-line caption UNDER the box, where the field carries one. Recorded
+     *  here for the same reason the two above are: it is merchant-facing copy, so
+     *  the walks that ask "what words does this panel show?" — the neutralizer,
+     *  `test-accent-syntax-taught`, `test-panel-plain-words` — must be able to see
+     *  it without rendering. It is NOT a neutralization source: a hint explains
+     *  the control and belongs to the product, not to the tenant's content. */
+    hint?: string;
+    /**
+     * DECLARED: these words never reach a shopper (card 66280). Set only by
+     * `withOffPage`, and only on a prop whose copy no render puts on the
+     * storefront — a join key, a tab reference, a tree label. The section screen's
+     * entry row then says so instead of previewing the value.
+     *
+     * ABSENT MEANS ON THE PAGE, and that default is the point. It cannot be
+     * derived: the walk that builds the entry rows reads fields, and only a
+     * component's RENDER knows whether a prop reaches a shopper. The costs of
+     * being wrong are not symmetric either — a field wrongly marked hides a
+     * merchant's own words behind a note, while a field wrongly left unmarked
+     * merely previews its stored value, which is true. So the default takes the
+     * harmless side and the exception is typed.
+     */
+    offPage?: true;
+    /**
+     * DECLARED: this row NAMES the thing rather than saying anything to a shopper
+     * — a slide's own name, a box's name in the Layers tree, a card's display
+     * override. The Text entry list draws these in a folded group of their own, so
+     * a panel opens on the words a merchant is writing and not on the labels the
+     * editor needs (owner 2026-09-04, pointing at a Hero Slide's `Slide name` and
+     * `Category tag`: "every panel carries this, I think it is wrong").
+     *
+     * ⚠️ IT IS NOT {@link offPage}, AND THE TWO ARE INDEPENDENT. `offPage` answers
+     * "do the words reach a shopper"; this answers "is the row a name or is it
+     * copy". Three of the four fields that carry this ARE on the page — a slide
+     * name is printed in the reel rail — so deriving one from the other would have
+     * folded away a merchant's published copy. `Box name` is the only one that is
+     * both, and it is the coincidence that makes the pair look derivable.
+     *
+     * FOLDED, NOT DROPPED, and that is the whole design. The entry list is the
+     * ONLY way back into a part with no clickable words on the canvas
+     * (`components/SectionTextEntries.tsx`), and an EMPTY field never has any: an
+     * unset `Alt name` draws the category's name, not its own, so a row that
+     * vanished once hidden would stand the merchant up with no way to set one.
+     * A fold keeps every row reachable in one press and still answers the owner.
+     */
+    identifier?: true;
+    /** For `textList`, the key each row stores its copy under. */
+    itemKey?: string;
+    /** For `textList`, whether its rows go through `renderGold` — the same answer
+     *  {@link TextListRendering} makes the call site state, recorded here so a
+     *  ROW opened on its own (card 66090) offers the formatting bar exactly when
+     *  the whole list does. Without it the row control would have to guess, and a
+     *  bar on a `verbatim` list writes markers the shopper reads as asterisks. */
+    rendering?: TextListRendering;
+};
+/** Which of an edge pad's four live squares an answer sits in — the cell a
+ *  direction option names beside its value (`lib/sections/ticker-scroll`), and
+ *  the one the pad in `lib/document/controls` lights. */
+type EdgeCell = "top" | "right" | "bottom" | "left";
+/** Marker carried by every media field object. The manifest GENERATOR walks the
+ *  built config looking for it, so the factory below is the single source of
+ *  truth for "this prop holds media" — a new media field is covered the moment
+ *  it is declared, with no list to maintain anywhere (Puck ignores extra keys). */
+declare const MEDIA_FIELD_MARKER: "__media";
+/** Marker carried by every heading {@link group} / {@link section} builds — and
+ *  by every bucket header {@link bucketHeader} builds, whose "heading" a
+ *  merchant reads as a TAB. Same style as {@link TEXT_FIELD_MARKER} / {@link LINK_FIELD_MARKER}:
+ *  the label and the level ON the field object, not only inside the render
+ *  closure. Without it a header's label is unreadable at runtime — the closure
+ *  is all there is — and the four-bucket pass (`lib/document/field-groups.ts`) would
+ *  have to re-derive it by parsing `config.tsx`, i.e. a second source of truth
+ *  for something the field already knows. Puck ignores extra keys, and the
+ *  neutralization walk classifies by its own markers / `type` / prop name, so a
+ *  header stays exactly as invisible to it as it was (see
+ *  `scripts/gen-neutralization-manifest.ts`). */
+declare const FOLD_FIELD_MARKER: "__fold";
+type FoldFieldMeta = {
+    label: string;
+    level: 1 | 2;
+};
+/** Read a field's fold-header payload, or null when it is not a header. The ONE
+ *  place that knows the marker's shape. */
+declare function foldMetaOf(field: unknown): FoldFieldMeta | null;
+/**
+ * Does this field DECLARE itself a name rather than copy? The read that pairs
+ * with {@link withIdentifier}'s write, so the one fact has one reader — the same
+ * shape as {@link textFieldOffPage}, and false for anything that is not a text
+ * field at all rather than throwing.
+ */
+declare function textFieldIdentifier(field: unknown): boolean;
+/**
+ * The keys `anchorFields()` (lib/document/controls) declares: the anchor's group
+ * header and its name row. The style clipboard leaves them out of a copied
+ * look — an anchor is the section's address, not its style — and reads them
+ * here rather than calling the builder, so it needs nothing of the inspector's
+ * field builders. scripts/test-anchor-field-keys.ts holds the two equal.
+ */
+declare const ANCHOR_FIELD_KEYS: readonly ["_gAnchor", "anchor"];
+
+export { ANCHOR_FIELD_KEYS, type EdgeCell, FOLD_FIELD_MARKER, type FoldFieldMeta, LINK_FIELD_MARKER, MEDIA_FIELD_MARKER, SCAFFOLD_FIELD_MARKER, TEXT_FIELD_MARKER, type TextFieldMeta, type TextListRendering, foldMetaOf, textFieldIdentifier };

package/dist/screen/lib/document/field-markers.js

@@ -0,0 +1 @@
+export{ANCHOR_FIELD_KEYS,FOLD_FIELD_MARKER,LINK_FIELD_MARKER,MEDIA_FIELD_MARKER,SCAFFOLD_FIELD_MARKER,TEXT_FIELD_MARKER,foldMetaOf,textFieldIdentifier}from"../../../chunk-ANPOR6EY.js";

package/dist/screen/lib/document/hidable.d.ts

@@ -0,0 +1,44 @@
+/**
+ * hidable — the ONE reader for the shape a hideable copy row stores.
+ *
+ * Every authored-text row in the editor is one of five controls
+ * (`lib/document/text-control-kinds`), and two of them — `text()` and `textarea()` —
+ * carry the eye that takes an element off the page while keeping the words. Those
+ * two persist `{ text, hidden }`; the other three persist a bare string, and so
+ * does every page published before the eye existed. A prop's stored value is
+ * therefore an OBJECT OR A STRING, and which one it is depends on whether a
+ * merchant has touched that row — not on anything a reader can see in the code.
+ *
+ * ⚠️ WHY THIS IS ITS OWN FILE. `readHidable` was born in `lib/document/controls.tsx`
+ * beside the field that writes the shape, and `controls.tsx` is React: it imports
+ * the editor shell, the markup toolbar and 30 components. So a PURE module that
+ * needs to read a stored heading could not use the one reader without dragging
+ * the whole editor in — and `lib/document/heading-outline.ts` is exactly that module
+ * (its own header promises no React and no config import, so the audit can be
+ * walked in a test without mounting the editor). It called `String(...)` on the
+ * prop instead, and printed the literal words `[object Object]` into the outline
+ * a merchant reads. Splitting the ~6 lines out costs nothing and removes the
+ * reason anyone would ever write a second unwrapper. `controls.tsx` re-exports
+ * both names, so every existing import site is unchanged.
+ *
+ * There is exactly one definition. Do not add a second way to unwrap this value.
+ */
+/** A hideable row's stored value: the object, a bare string (a `plainText()` row
+ *  or legacy data), or nothing at all. */
+type HidableValue = {
+    text?: string;
+    hidden?: boolean;
+} | string | undefined;
+declare function readHidable(v: HidableValue): {
+    text: string;
+    hidden: boolean;
+};
+/**
+ * Plain-text view of a hidable field value — a `{ text, hidden }` object (a
+ * `text()`/`textarea()` row) OR a bare string (a `plainText()` row / legacy data).
+ * Funnels through here at read sites that need a string (e.g. a section's
+ * `imageLabel`, a link `href`) so a stored object can never reach a React child.
+ */
+declare function hidableText(v: HidableValue): string;
+
+export { type HidableValue, hidableText, readHidable };

package/dist/screen/lib/document/hidable.js

@@ -0,0 +1 @@
+export{hidableText,readHidable}from"../../../chunk-6UAEFOJ4.js";