efficient-easel 0.101.1 → 0.102.0

package/dist/screen/lib/puck/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/puck/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/puck/text-parts`), the typing bridge
+ * (`lib/puck/part-text`, `lib/puck/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/puck/hidable` and `lib/puck/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/puck/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/puck/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/puck/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/puck/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/puck/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/puck/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/puck/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-DUVRZ456.js";

package/dist/screen/lib/puck/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/puck/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/puck/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/puck/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/puck/hidable.js

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

package/dist/screen/lib/puck/palette-sections.d.ts

@@ -0,0 +1,96 @@
+import { Config } from '../../../blocks/index.js';
+import 'react';
+import '../../../types-E3HrTPg2.js';
+import '../../../data/index.js';
+import '../../../types-41704JE4.js';
+import '../../../resolve-D68pb3Bx.js';
+import '../../../plan-DChbUXdS.js';
+
+/** One offerable section, with the category it is grouped under. */
+type PaletteSection = {
+    type: string;
+    cat: string;
+    name: string;
+    desc: string;
+    /**
+     * The heading of the category this section sits under, resolved once at build
+     * time — SEARCHED, and already SHOWN as the nav row this card sits beneath.
+     *
+     * ⚠️ IT IS HERE BECAUSE THE NAV AND THE SEARCH DISAGREED. Seven of the
+     * thirteen category names returned NOTHING when typed: "Blog & journal" reads
+     * 5 in the nav, and "blog" found 0, because not one of Issue Header, Featured
+     * Cover, Article Text, Recurring Columns or Latest Posts carries the word. Same
+     * for shop, about, promotions, navigation, legal and layout. A merchant reads
+     * the word off the screen, types it, and is told no section matches.
+     *
+     * Resolved HERE, not in `matchesQuery`, because the label needs the `config`
+     * (`categoryLabel`) and the matcher is given only a section — passing config
+     * into the matcher would make every caller carry it.
+     */
+    catLabel: string;
+    /**
+     * Another word this section is known by, searched but never shown.
+     *
+     * ⚠️ THIS EXISTS FOR ONE NODE AND ONE REASON. `Flex` is offered here as
+     * "Blank section" and is called "Box" everywhere it is nested — so a merchant
+     * who met it in a Layers row, or in last week's handoff, types "box" and must
+     * still find it. Without this they would find NOTHING: the card is pinned out
+     * of its group, so a search that misses it misses it completely.
+     */
+    alias?: string;
+};
+/**
+ * What the layer says of its sections for the palette: the word for a type at
+ * a level, a group's short heading where it has one, and the blurbs. The
+ * screen's `blockLook` is one (lib/screen-parts); so is the website's own
+ * (lib/puck/add-palette).
+ */
+interface PaletteLook {
+    /** What a node of `type` is called at a level, given the label the config
+     *  holds for it. */
+    labelAtLevel: (type: string, level: "section" | "block", base: string) => string;
+    /** A group's short heading, by its key, where the layer has one; undefined,
+     *  and the config's own title is the heading. */
+    categoryLabel: (id: string) => string | undefined;
+    /** The one-line blurb for a section, by type. */
+    descriptions: Record<string, string>;
+}
+/**
+ * Flatten `config.categories` into an ordered section list.
+ *
+ * Grouping and order ARE the category order in the config — which is the
+ * catalog's order — so this adds no opinion of its own. A component listed in a
+ * category but absent from `components` is skipped: a stale catalog row cannot
+ * render and certainly cannot insert, so offering it would be a card that fails
+ * on click.
+ *
+ * Child-only blocks (HeroSlide / CollectionCard / ProductRef) and the four
+ * generic primitives (Heading / Text / ImageBlock / ButtonBlock) sit in NO
+ * category on purpose, so they never appear here — they are added from their
+ * parent's slot instead. See the note above `categories:` in lib/puck/config.tsx.
+ */
+declare function buildPaletteSections(config: Config, look: PaletteLook): PaletteSection[];
+/** A category's display label — the layer's short one where there is one, else the config's title. */
+declare function categoryLabel(config: Config, id: string, shortLabel: (id: string) => string | undefined): string;
+/**
+ * Does a section match a search query?
+ *
+ * The query is matched against the NAME, any ALIAS, the blurb, the component
+ * TYPE and the CATEGORY HEADING — the type because a merchant who knows the
+ * section by the word they saw in a handoff should still find it, the alias
+ * because one node is called something else everywhere it is nested (see
+ * `PaletteSection.alias`), and the category because it is PRINTED IN THE NAV
+ * BESIDE THE RESULTS: seven of thirteen headings used to match nothing at all
+ * (see `PaletteSection.catLabel`). A word a merchant can read off this screen
+ * must find what it is labelling.
+ *
+ * `q` is expected already lower-cased and trimmed; an empty query matches
+ * everything.
+ */
+declare function matchesQuery(s: PaletteSection, q: string): boolean;
+/** The pinned section, or `null` if the layer pins none or the config does not offer it. */
+declare function pinnedSection(sections: PaletteSection[], pinned: string | null): PaletteSection | null;
+/** Every OTHER section — what the grouped grid below the pinned card draws. */
+declare function paletteWithoutPinned(sections: PaletteSection[], pinned: string | null): PaletteSection[];
+
+export { type PaletteLook, type PaletteSection, buildPaletteSections, categoryLabel, matchesQuery, paletteWithoutPinned, pinnedSection };

package/dist/screen/lib/puck/palette-sections.js

@@ -0,0 +1 @@
+export{buildPaletteSections,categoryLabel,matchesQuery,paletteWithoutPinned,pinnedSection}from"../../../chunk-GENAF3P6.js";

package/dist/screen/lib/puck/panel-fields.d.ts

@@ -0,0 +1,47 @@
+/**
+ * THE ROWS A PANEL IS REALLY DRAWING — not the ones its component declares.
+ *
+ * `config.components[type].fields` is a DECLARATION. A component's
+ * `resolveFields` then culls it for the state that node is in: the Booking Form
+ * gives its head rows away to the boxes that own them, Spec Table drops its Rows
+ * array on a linked product, Image & Text Columns takes its text-position row
+ * away once it has Boxes.
+ *
+ * `Puck.Fields` honours all of that. Every list built beside it from the raw
+ * declaration does not — and one of them is the copy list in
+ * `components/SectionEditor`. So a merchant met the SAME heading twice: once in
+ * the panel Puck drew, and once in a list drawn from rows the resolver had
+ * already dropped (owner, 2026-09-10, on a Booking Form's Head box).
+ *
+ * ⚠️ PUCK DOES NOT EXPOSE ITS RESOLVED SET. The store slice that holds it is
+ * internal — `useEasel((s) => s)` and `createUsePuck()` both hand back `PuckApi`, which
+ * has no `fields` on it (checked against 0.20.2's own types, not remembered). So
+ * the resolver is asked here, the same way Puck asks it.
+ *
+ * ⚠️ AND AN ASYNC RESOLVER IS ANSWERED WITH THE DECLARATION. A promise cannot be
+ * read during a render, and a list that waited would flicker rows in and out.
+ * Falling back is the same answer this code gave before, so an async resolver is
+ * no worse off than it was — it simply is not helped either. Stated because a
+ * silent half-fix is the thing worth naming.
+ */
+type PanelFieldMap = Record<string, unknown>;
+interface PanelComponent {
+    fields?: PanelFieldMap;
+    resolveFields?: (data: unknown, params: Record<string, unknown>) => unknown;
+}
+/**
+ * The field map to build a panel-side list from, for one node.
+ *
+ * `parent` is passed as null and `appState` as an empty object because the ONE
+ * caller uses the result for authored-copy rows, which no resolver decides from
+ * either. A caller that needs the width rows — which DO read `parent` — must ask
+ * Puck rather than this.
+ */
+declare function panelFieldsOf(config: {
+    components?: Record<string, PanelComponent>;
+}, node: {
+    type: string;
+    props: Record<string, unknown>;
+} | null | undefined): PanelFieldMap | null;
+
+export { type PanelFieldMap, panelFieldsOf };

package/dist/screen/lib/puck/panel-fields.js

@@ -0,0 +1 @@
+export{panelFieldsOf}from"../../../chunk-ZE7I3PLX.js";

package/dist/screen/lib/puck/panel-no-control-mark.d.ts

@@ -0,0 +1,74 @@
+import { ReactElement } from 'react';
+
+/**
+ * panel-no-control-mark — what a settings field draws when it draws NO CONTROL
+ * on the screen it is on (card 66178).
+ *
+ * WHY A FIELD HAS TO SAY THIS OUT LOUD. Puck lays the inspector out as a FLAT
+ * list and owns the wrapper around every top-level field, and its own stylesheet
+ * rules the gap between two of them:
+ *
+ *   ._PuckFields--wrapFields_ ._PuckFields-field_ + ._PuckFields-field_ {
+ *     border-top: 1px solid var(--puck-color-grey-09); margin-top: 8px; }
+ *
+ * That rule is right — a line between two adjacent rows. But a field whose
+ * `render` returns `null` still gets the wrapper, still takes its `16px 16px
+ * 12px` of padding and still draws the line, so the panel shows a hairline with
+ * nothing on one side of it. Measured on the Collections Content tab before this
+ * card: two 29px-tall wrappers whose whole content was
+ * `<div class="_InputWrapper_"></div>`, and three rules stacked with only blank
+ * space between them. Across the catalogue it was 338 such rows in 74 panels.
+ *
+ * We cannot stop Puck emitting the wrapper, so the wrapper is collapsed from the
+ * outside: the field renders this zero-size marker and ONE declarative rule in
+ * `components/storefront-editor.css` takes the wrapper out of the layout
+ * entirely — `display: none`, so the row leaves the accessibility tree with it
+ * rather than lingering as an unlabelled blank. That is exactly the shape the
+ * bucket boundary markers (`data-sf-bucket`) and the device-gated fields
+ * (`data-sf-device-hidden`) already use, and it is declarative for the same
+ * reason: it cannot race the tab pass.
+ *
+ * IT IS NOT A WAY TO HIDE A SETTING. A field that draws nothing here must still
+ * be reachable somewhere — as an entry row in the section screen's TEXT group,
+ * or through another control on the same panel. `scripts/test-panel-no-empty-rows.tsx`
+ * §2 fails a field that draws no control and has no way back to it, which is how
+ * the lost "Anchor name" box was found.
+ */
+
+/** The attribute the marker carries — the single source, read by the stylesheet
+ *  rule and by the guard that proves the rule is there. */
+declare const NO_CONTROL_ATTR = "data-sf-no-control";
+/** The marker itself. `hidden` as well as the CSS rule, so a field that renders
+ *  it in a context the editor stylesheet has not reached (a test harness, a
+ *  bundled preview) still draws nothing rather than an empty inline box. */
+declare function NoControlMark(): ReactElement;
+/**
+ * …AND THE SAME FACT SAID ON THE FIELD OBJECT (card 66201).
+ *
+ * The attribute above is drawn, so only a render can see it. The pass that drops
+ * a heading standing over nothing runs in `resolveFields`, where there is no DOM
+ * and no React — it has a field list and nothing else. So a field that draws no
+ * control has to say so twice, in the two places the answer is asked, and both
+ * are stamped by the ONE `if` that decides it: see `textField` in
+ * `lib/puck/controls`, which wraps the render and stamps the marker together.
+ *
+ * The two reasons are not the same shape, hence a word rather than a boolean:
+ *   • `"always"` — it draws nothing wherever it appears. A device scope note, a
+ *     key whose one control is a row elsewhere on the same panel.
+ *   • `"authored-copy"` — a scalar copy box card 8819 moved to the DRILL screen.
+ *     It draws nothing on the section screen unless its prop is STRUCTURAL, which
+ *     is the one question `SuppressibleText` also asks at render time.
+ */
+declare const NO_CONTROL_FIELD: "__noControl";
+/** The payload on {@link NO_CONTROL_FIELD}. */
+type NoControlFieldMeta = "always" | "authored-copy";
+/** Read a field's no-control payload, or `null` when it draws a control of its
+ *  own. The ONE place that knows the marker's shape. */
+declare function noControlMetaOf(field: unknown): NoControlFieldMeta | null;
+/** Stamp {@link NO_CONTROL_FIELD} on a field. The cast is here and nowhere else:
+ *  Puck's field types have no slot for a marker, so an object literal carrying
+ *  one trips the excess-property check at every call site otherwise — the same
+ *  reason `group()` and the text/link markers have their own builders. */
+declare function noControlField<F>(field: F, reason: NoControlFieldMeta): F;
+
+export { NO_CONTROL_ATTR, NO_CONTROL_FIELD, type NoControlFieldMeta, NoControlMark, noControlField, noControlMetaOf };

package/dist/screen/lib/puck/panel-no-control-mark.js

@@ -0,0 +1 @@
+export{NO_CONTROL_ATTR,NO_CONTROL_FIELD,NoControlMark,noControlField,noControlMetaOf}from"../../../chunk-7F52SZOI.js";

package/dist/screen/lib/puck/part-id.d.ts

@@ -0,0 +1,23 @@
+/**
+ * lib/puck/part-id.ts — how one PART of a section is named: `"<nodeId>::<propKey>"`.
+ *
+ * A part is one authored text of a node (a heading, a button label) that the
+ * editor's inspector can drill into. Its id is read on both sides of the
+ * preview: the section's render marks each part with it, and the screen's part
+ * bridge (components/usePartBridge) opens the part it names. The codec moved
+ * here from lib/puck/text-parts (which re-exports it) so the screen reads it
+ * without the text walk, and moves into efficient-easel with it (doc/adr/0004).
+ */
+/** Separates the node id from the prop key inside a part id. A doubled colon:
+ *  a Puck node id is `<Type>-<uuid>` and a compound zone is `<parentId>:<slot>`,
+ *  so a single colon is already taken. */
+declare const PART_SEP = "::";
+/** `"<nodeId>::<propKey>"`, or `"<nodeId>::"` for "the whole section". */
+declare function encodePartId(nodeId: string, propKey: string | null): string;
+/** Inverse of {@link encodePartId}. `propKey: null` means the whole section. */
+declare function decodePartId(partId: string): {
+    nodeId: string;
+    propKey: string | null;
+} | null;
+
+export { PART_SEP, decodePartId, encodePartId };

package/dist/screen/lib/puck/part-id.js

@@ -0,0 +1 @@
+export{PART_SEP,decodePartId,encodePartId}from"../../../chunk-IYT6NN2J.js";

package/dist/screen/lib/puck/preview-click.d.ts

@@ -0,0 +1,49 @@
+/**
+ * "Did this come from a click INSIDE the preview?" — the one fact that decides
+ * whether the editor is allowed to scroll its canvas.
+ *
+ * Every in-preview selection bridge (a section's text PARTS, and a Hero's
+ * ticker / Background / Text) shares ONE handler with the matching row in the
+ * Layers tree. The handler ends in `scrollPreviewToSection`, and only one of its
+ * two callers should travel:
+ *
+ *   · from the LAYERS TREE — scroll. A row in a list can name a section that is
+ *     off-screen, and taking the merchant there is the whole point of clicking it.
+ *   · from a CLICK IN THE PREVIEW — do not. The merchant is already looking at
+ *     the thing they clicked, so moving the canvas under them is motion they did
+ *     not ask for (card 66392: "after clicking, the screen moves; cancel this
+ *     sliding motion" — measured at 409px of travel in the phone preview).
+ *
+ * The two callers are told apart HERE rather than at each of the eight call
+ * sites, because the difference is one rule and a rule spelled eight times is a
+ * rule that drifts. `useSelectHandler` (lib/puck/preview-selection-context) is
+ * the single entry point every in-preview click already goes through — it is
+ * invoked from inside the portaled preview iframe — so wrapping it once covers
+ * both editor shells and all four bridges, and the tree keeps calling the same
+ * handlers directly and unchanged.
+ *
+ * ⚠️ AMBIENT, AND DELIBERATELY SO. Threading a "did this come from the preview"
+ * argument through the bridges would mean editing every handler and every one of
+ * its callers — exactly the call-site patching that left the last fix half-done.
+ * The cost is that the fact lives in a module variable, so two things are load-
+ * bearing: the flag is only ever read SYNCHRONOUSLY (see `scrollPreviewToSection`,
+ * which must not defer the check into its `requestAnimationFrame`), and it is
+ * restored in a `finally` so a throwing handler cannot leave the canvas
+ * permanently unable to scroll. Both are pinned by
+ * `scripts/test-preview-click-does-not-scroll.tsx`.
+ *
+ * No imports on purpose: `preview-dom` reads this and `preview-selection-context`
+ * writes it, and the latter is reached from inside the preview iframe — putting
+ * the flag in `preview-dom` would close a cycle back through HeroSection.
+ */
+/**
+ * Run `handler` as work caused by a click INSIDE the preview, so anything it
+ * reaches knows not to move the canvas. Returns whatever `handler` returns; the
+ * fact is restored even if it throws.
+ */
+declare function runAsPreviewClick<T>(handler: () => T): T;
+/** True while a `runAsPreviewClick` handler is on the stack. Read it
+ *  SYNCHRONOUSLY — deferred work runs after the click has already returned. */
+declare function isPreviewClick(): boolean;
+
+export { isPreviewClick, runAsPreviewClick };

package/dist/screen/lib/puck/preview-click.js

@@ -0,0 +1 @@
+export{isPreviewClick,runAsPreviewClick}from"../../../chunk-R5L2E7JX.js";

package/dist/screen/lib/puck/preview-dom.d.ts

@@ -0,0 +1,8 @@
+declare const previewFrame: () => HTMLIFrameElement | null;
+declare function scrollPreviewToSection(id: string): void;
+declare function gotoPreviewSlide(heroId: string, index: number): void;
+declare function scrollPreviewToTop(): void;
+declare function pinPreviewToSection(id: string): () => void;
+declare function pinPreviewToBottom(onPinned?: () => void): () => void;
+
+export { gotoPreviewSlide, pinPreviewToBottom, pinPreviewToSection, previewFrame, scrollPreviewToSection, scrollPreviewToTop };

package/dist/screen/lib/puck/preview-dom.js

@@ -0,0 +1 @@
+export{gotoPreviewSlide,pinPreviewToBottom,pinPreviewToSection,previewFrame,scrollPreviewToSection,scrollPreviewToTop}from"../../../chunk-4ES5JGGX.js";import"../../../chunk-IQ5TA7AM.js";import"../../../chunk-R5L2E7JX.js";

package/dist/screen/lib/puck/preview-events.d.ts

@@ -0,0 +1,25 @@
+/**
+ * lib/puck/preview-events.ts — events the editor's screen sends INTO the preview.
+ *
+ * Moved from components/HeroSection (which re-exports them) so the screen's
+ * preview bridge (lib/puck/preview-dom) can send them without importing a
+ * section, and moves into efficient-easel with the screen (doc/adr/0004). A
+ * section listens for its own; the name is the contract between the two.
+ */
+/**
+ * Event the editor chrome dispatches INTO the preview iframe to jump a Hero's
+ * slider to a slide by index. The chrome (section tree + "Add slide") lives
+ * outside this iframe and can't reach the slider's React state, and Puck's
+ * selection overlay is portaled to the iframe `<body>` (not inside `.hero-track`),
+ * so selection alone can't be observed from here — this is the explicit bridge.
+ * See {@link ScreenChrome} `selectChild` / `addChild`.
+ */
+declare const HERO_SLIDER_GOTO_EVENT = "hero-slider:goto";
+interface HeroSliderGotoDetail {
+    /** Target Hero's stable Puck id (`data-puck-component`); omit to hit all Heroes. */
+    id?: string;
+    /** Zero-based slide index to show. */
+    index: number;
+}
+
+export { HERO_SLIDER_GOTO_EVENT, type HeroSliderGotoDetail };

package/dist/screen/lib/puck/preview-events.js

@@ -0,0 +1 @@
+export{HERO_SLIDER_GOTO_EVENT}from"../../../chunk-IQ5TA7AM.js";