efficient-easel 0.101.1 → 0.103.0

package/dist/screen/lib/document-switch.d.ts

@@ -0,0 +1,74 @@
+import { A as AutosaveSnapshot } from '../../engine-DBxp_v6B.js';
+import { EditAccess } from '../../edit-lock/index.js';
+
+/**
+ * lib/document-switch.ts — WHERE THE AUTOSAVE STANDS for the open
+ * document, and what a switch to another document clears.
+ *
+ * Any editor that saves by itself and holds an edit lock has both: a status
+ * read off the autosave's state, and a set of per-document facts (the pending
+ * edit, the version token, a refused save, the lock) that are true of the
+ * document being left and of no other. They were written beside the website's
+ * pinned-chrome seed, which defers on that status (lib/puck/pinned-seed-gate —
+ * the account of why the two must not drift is there, and that module still
+ * hands these on), and are here because the document provider reads them and
+ * holds no website.
+ *
+ * All of it is pure: the switch takes its setters as an argument, so a test
+ * can RUN it and read back what it drove.
+ */
+
+/** Where the editor's autosave currently stands for the OPEN document. */
+type SaveStatus = "idle" | "saving" | "saved" | "error";
+/**
+ * The status, read off the autosave's state. "saving" covers an edit waiting
+ * its second as well as one being written: either way the store is ahead of the
+ * server, which is what the seed must not race (#321).
+ */
+declare function saveStatusOf(state: AutosaveSnapshot): SaveStatus;
+/**
+ * The save status a freshly opened document starts from, given the one the
+ * editor was carrying for the document it just left.
+ *
+ * Always "idle": the switch has already dropped that document's pending edit
+ * (the autosave's `reset`), so no status belonging to it is true of the new one
+ * — `saveStatusOf` a reset autosave is exactly this. This mirrors the version token, the save conflict and the edit lock,
+ * which the same switch resets for the same reason.
+ */
+declare function saveStatusForNewDocument(_previous: SaveStatus): SaveStatus;
+/**
+ * The setters a document switch drives. Passed in rather than imported so the
+ * switch itself can be executed in a test — there is no jsdom here, so a rule
+ * that only lives inside a React callback is a rule nothing can check.
+ */
+type DocumentSwitchSetters = {
+    /** Drop the old document's pending edit, failure and refusal — the autosave's
+     *  `reset`, plus any edit the provider held for the lock. What leaves the
+     *  status "idle" and nothing unsaved. */
+    resetAutosave: () => void;
+    setVersion: (version: string | null) => void;
+    setSaveConflict: (conflict: null) => void;
+    setAccess: (access: EditAccess) => void;
+};
+/**
+ * Clear every piece of editor state that belonged to the document being LEFT.
+ *
+ * All of it is per-document and none of it is true of the one being opened: a
+ * stale version token would refuse every save on the new page, a stale conflict
+ * would hold the banner up over a page nobody touched, a stale edit lock would
+ * claim a document this editor has not claimed — and a stale "saving" would
+ * wedge the header seed for good (card 1092).
+ *
+ * The caller has already saved or discarded the outgoing document's edit; this
+ * drops what is left of it, kept together so the next person to add a
+ * per-document field has one obvious place to clear it.
+ *
+ * `hasEditLock` is the NEW document's, not the old one's — see
+ * `accessForNewDocument`. This used to be hardcoded to `checking`, which is the
+ * right answer for a page and a terminal one for a template: nothing claims a
+ * template, so `checking` there refused every write for the rest of the session,
+ * the Header AND Footer seed of the branch above first (card 1096).
+ */
+declare function resetForDocumentSwitch(hasEditLock: boolean, apply: DocumentSwitchSetters): void;
+
+export { type DocumentSwitchSetters, type SaveStatus, resetForDocumentSwitch, saveStatusForNewDocument, saveStatusOf };

package/dist/screen/lib/document-switch.js

@@ -0,0 +1 @@
+export{resetForDocumentSwitch,saveStatusForNewDocument,saveStatusOf}from"../../chunk-OYX47SL7.js";import"../../chunk-JUQ6YJCG.js";import"../../chunk-RE4LP46F.js";

package/dist/screen/lib/failure.d.ts

@@ -0,0 +1,54 @@
+import { EditLockFailure } from '../../edit-lock/index.js';
+
+/**
+ * What a failed editor call WAS, as `{ status, data }` — the shape the shared
+ * edit-lock rules (efficient-easel/edit-lock) read, and the one place a
+ * failure from either source is put into it.
+ *
+ * A call fails in one of two voices:
+ *
+ *   • the HOST'S OWN HTTP client rejects with its own error — EFFICIENT's
+ *     `ApiError`: a status and the response body, as it always has. The host
+ *     says how to read one (lib/backend-error `provideHostFailures`); this module
+ *     imports no host's error class;
+ *   • the editor's BACKEND (lib/backend-error) rejects with a
+ *     `WebsiteBackendError` — a KIND, never a body (doc/adr/0002).
+ *
+ * The shared rules were written for the first, so a kind is translated here:
+ *
+ *   • `changed-elsewhere` → the refused-save body (409, this page's conflict
+ *     code, who saved);
+ *   • `lock-taken`        → the `edit-lock` body (409, the holder), with the
+ *     taken-from-this-tab code a refused SAVE is recognised by. A refused CLAIM
+ *     reads only the holder, so the one body answers both;
+ *   • `unauthorized`      → 401, which is what stops a heartbeat that can only
+ *     be refused.
+ *
+ * An error a backend made out of its client's own error carries that error as
+ * its `cause` and is read from it — the original status and body, nothing
+ * reconstructed.
+ *
+ * `null` for anything that is not a server answer (a dropped socket, a
+ * programming error): every "fails open" branch of the lock leans on that.
+ */
+
+/**
+ * The `code` a refused PAGE save carries in the terms the shared edit-lock
+ * rules read (`createEditLock({ conflictCode })`, lib/page-lock). A
+ * `changed-elsewhere` rejection is given it below; EFFICIENT's backend puts the
+ * same word in its 409 body and names this constant for it
+ * (lib/efficient-backend), so a raw body and a translated kind read alike.
+ */
+declare const PAGE_CONFLICT_CODE = "page_changed_elsewhere";
+declare function readEaselFailure(err: unknown): EditLockFailure | null;
+/**
+ * A call was refused because the SESSION is no longer authorised — the one
+ * failure the editor answers by asking its host for a fresh sign-in.
+ *
+ * A 401, as it always was — and ONLY a 401: the EFFICIENT backend names its 403
+ * `unauthorized` too, and a 403 has never been a reason to re-authenticate. A
+ * backend that speaks only in kinds says `unauthorized`.
+ */
+declare function isExpiredSession(err: unknown): boolean;
+
+export { PAGE_CONFLICT_CODE, isExpiredSession, readEaselFailure };

package/dist/screen/lib/failure.js

@@ -0,0 +1 @@
+export{PAGE_CONFLICT_CODE,isExpiredSession,readEaselFailure}from"../../chunk-HMX55DYT.js";import"../../chunk-KDYIMJTZ.js";import"../../chunk-JUQ6YJCG.js";import"../../chunk-RE4LP46F.js";

package/dist/screen/lib/host-chrome.d.ts

@@ -0,0 +1,181 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, RefObject } from 'react';
+import { LinkPickerPage, LinkFilters } from './links/link-filters.js';
+import '../../LinkPicker-W2Rtxetz.js';
+
+/**
+ * WHAT A HOST STANDS ROUND THE EDITOR — its own furniture, handed over as
+ * components (doc/adr/0004).
+ *
+ * The editor is the builder's; a host's providers, primers and panels are the
+ * host's. The storefront's are the site's currency, its pinned header and
+ * footer, its menus, its cart and checkout previews — and until this module
+ * the editor imported and mounted every one of them, so the builder loaded the
+ * shop. A host fills a SLOT instead, the way it already fills `mediaPanel`,
+ * and the editor mounts what it was handed in the place it has always mounted
+ * such things.
+ *
+ * Read once, with the backend and the registry: the slots ride on the editor's
+ * session (lib/session `chrome`) and are fixed for the life of the mount.
+ *
+ * The slots: the wrapper, the host's panels (its header's settings, and what
+ * it adds to the chrome page's), the Pages panel's rows, and what the host adds
+ * to the Link field — its products as link targets, and its product listing's
+ * filters (ADR 0004).
+ */
+/** Which of the two editors a host's furniture is standing in: the page editor
+ *  (a website's pages, a template's) or the standalone one-section editor. */
+type EaselSurface = "page" | "section";
+/**
+ * What the editor hands a host's settings panel: what its own site-level panels
+ * are handed, and nothing of the editor's internals.
+ */
+interface HostPanelProps {
+    /** The open document has no website of its own (a template): draw the
+     *  panel's placeholder state. */
+    placeholderMode: boolean;
+    /** The console's token, where a token is how the host's calls are authorised. */
+    tokenRef: RefObject<string | null>;
+    /** The website being edited, or null (a template, the one-section editor). */
+    siteId: string | null;
+    websiteName: string | null;
+    /** Open the editor's own Appearance panel. */
+    onOpenWebsiteSettings?: () => void;
+    /** Tell the editor's host that its sign-in was refused. */
+    onAuthExpired: () => void;
+}
+/**
+ * A surface the host serves that is NOT a page of the website — the
+ * storefront's cart, its checkout — offered as a row of the Pages panel.
+ * Pressing the row frames the surface in the canvas (the host's own preview
+ * reads which one off `PreviewSurfaceContext`); the row's link opens it live.
+ */
+interface HostPageRow {
+    /** The surface's name to the host; what the canvas preview is told. */
+    key: string;
+    label: string;
+    /** Where the live surface is, for the row's "open in a new tab". */
+    href: string;
+    icon: ReactNode;
+}
+/**
+ * One of the host's products, as the editor names it in the two places it
+ * holds only a product's handle: the Link field's "Product" targets, and a
+ * tree row whose block carries just the handle.
+ */
+interface HostProduct {
+    /** The product's handle, as a block stores it. */
+    slug: string;
+    name: string;
+    /** Where the product lives on the website — what a link to it is. */
+    href: string;
+}
+/** What the editor hands the host's row under a Link field
+ *  (`linkRow`, deprecated). */
+interface HostLinkRowProps {
+    /** The link as it stands. */
+    value: string;
+    onChange: (url: string) => void;
+    /** The website's pages with their layouts, as the Link field listed them —
+     *  so the host can tell what the linked page holds. */
+    pages: readonly {
+        slug: string;
+        layout?: unknown;
+    }[];
+}
+interface EaselChrome {
+    /**
+     * One component mounted round the canvas and the panels, inside the editor's
+     * document context — so it reads the website being edited and the
+     * capabilities like anything else in the editor (`useScreenDocument`) —
+     * and inside the editor's appearance and footer bridges, which a host's
+     * primer may write into. It must render its `children`.
+     *
+     * It is told which editor it stands in (`surface`): the one-section editor
+     * has no website's page open, and a host stands less round it.
+     *
+     * ONE component, not one per provider: the order among a host's providers is
+     * the host's to keep, and the editor holds no list of them.
+     */
+    wrap?: ComponentType<{
+        surface: EaselSurface;
+        children: ReactNode;
+    }>;
+    /**
+     * Settings panels of the host's own, drawn in the editor's inspector — inside
+     * the editor's panel frame, under the editor's own head — where the editor
+     * has always drawn them. One so far:
+     *
+     *   header   the settings of the host's pinned header, opened by selecting
+     *            the header in the canvas or its row in the tree. Without it the
+     *            inspector has no such panel.
+     *
+     * …and one the host adds to a panel of the editor's:
+     *
+     *   chromePage   drawn under the page settings of the page that STORES the
+     *            site's chrome (its footer page), on a document with a website
+     *            behind it. The storefront's is "Switch to Box header", which
+     *            builds the header group there from the shop's header row. It
+     *            takes no props: it reads the open document like any other part
+     *            of the editor (`useScreenDocument`, `useEasel`).
+     */
+    panels?: {
+        header?: ComponentType<HostPanelProps>;
+        chromePage?: ComponentType;
+    };
+    /**
+     * A group of the host's own rows in the Pages panel, under the host's own
+     * heading (the storefront: "Shop" — Cart, Checkout). Drawn by the editor,
+     * with its own row and group, between the website's pages and its system
+     * pages, and only for a document with a website behind it.
+     */
+    pageRows?: {
+        title: string;
+        rows: readonly HostPageRow[];
+    };
+    /**
+     * The host's products, for the website being edited. Asked for once per
+     * mount of whatever names them; best effort — it must resolve (to an empty
+     * list when the host's read failed). Without it the Link field's "Product"
+     * kind has nothing to pick and a product's tree row reads its handle.
+     */
+    products?: {
+        list(): Promise<readonly HostProduct[]>;
+    };
+    /**
+     * The host's product listing, for the Link field's Filter and Value boxes
+     * ([MERGE] One Link Picker For Both Editors, 2026-10-08). Asked per mount of
+     * a Link field and per site, where the host's commerce blocks are offered, so
+     * the host caches; best effort — it should resolve (to null when the host's
+     * read failed, which draws no Filter; a rejection is read the same). It
+     * resolves to a function of the pages the Link field listed, so the host
+     * reads which of them hold its listing off their documents
+     * (lib/links/link-filters `LinkFilters`).
+     *
+     * Without it the field offers no Filter and a page link is a plain page.
+     * With it, `linkRow` is not drawn: the Filter is what that row was.
+     */
+    linkFilters?: {
+        load(siteId: string | null): Promise<((pages: readonly LinkPickerPage[]) => LinkFilters) | null>;
+    };
+    /**
+     * @deprecated Replaced by `linkFilters`, and IGNORED when a host hands both.
+     * Still drawn for a host that hands only this; removing it is a change to the
+     * builder's host contract and waits for its owner's word.
+     *
+     * A row of the host's own under a Link field whose link is a PAGE link, where
+     * the host's commerce blocks are offered. The host decides whether it applies
+     * to this link and renders nothing when it does not. The storefront's was
+     * "which product type the listing opens on", shown when the linked page holds
+     * its listing.
+     */
+    linkRow?: ComponentType<HostLinkRowProps>;
+}
+/** The host's wrapper round `children`, or `children` bare when it handed none. */
+declare function ChromeWrap({ wrap: Wrap, surface, children, }: {
+    wrap: EaselChrome["wrap"] | undefined;
+    surface: EaselSurface;
+    children: ReactNode;
+}): react.JSX.Element;
+
+export { ChromeWrap, type EaselChrome, type EaselSurface, type HostLinkRowProps, type HostPageRow, type HostPanelProps, type HostProduct };

package/dist/screen/lib/host-chrome.js

@@ -0,0 +1 @@
+import{jsx as r,Fragment as e}from"react/jsx-runtime";function c({wrap:c,surface:n,children:i}){return c?/* @__PURE__ */r(c,{surface:n,children:i}):/* @__PURE__ */r(e,{children:i})}export{c as ChromeWrap};

package/dist/screen/lib/host-inbound.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The host messages EVERY editor surface answers the same way: the replies to a
+ * request the editor made (a media pick). The website's own broadcasts — a
+ * category, a menu or a form changed elsewhere — are lib/website-host-inbound's,
+ * and the website hands them to the screen's mount (`onHostMessage`), so this
+ * module, which moves into efficient-easel with the screen, names none of them
+ * (doc/adr/0004). Returns true when the message was one of
+ * them, so the surface goes on to handle its own kinds (a retarget) only when it
+ * was not.
+ *
+ * One router rather than one per surface: the standalone section editor used to
+ * route only its retarget, so a media pick or a new form started there never
+ * settled — the picker waited on a reply that arrived and was dropped.
+ *
+ * Fields are read defensively: over the iframe transport this is a postMessage
+ * payload, i.e. untrusted data.
+ */
+declare function routeSharedHostMessage(raw: unknown): boolean;
+
+export { routeSharedHostMessage };

package/dist/screen/lib/host-inbound.js

@@ -0,0 +1 @@
+export{routeSharedHostMessage}from"../../chunk-7MU3RJ6S.js";import"../../chunk-6FY3PZS3.js";import"../../chunk-ZZ7VLIHQ.js";

package/dist/screen/lib/host.d.ts

@@ -0,0 +1,20 @@
+import 'react';
+export { D as DETACHED_EASEL_HOST, E as EaselHost, b as EaselHostAddress, c as EaselHostContext, d as EaselHostProvider, e as EaselMessageType, f as EaselToHostMessage, H as HostPickedMedia, g as HostToEaselMessage, I as InboundHostMessage, S as SectionScreenTarget, h as SendToHost, i as createEaselHost, u as useEaselHost } from '../../host-DJ8Gzsx7.js';
+import '../../blocks/index.js';
+import '../../types-E3HrTPg2.js';
+import '../../data/index.js';
+import '../../types-41704JE4.js';
+import '../../resolve-D68pb3Bx.js';
+import '../../plan-DChbUXdS.js';
+import './document-contract.js';
+import './session.js';
+import './host-chrome.js';
+import './links/link-filters.js';
+import '../../LinkPicker-W2Rtxetz.js';
+import './document-hooks.js';
+import './section-template-types.js';
+import './puck/content-tree.js';
+import './document-switch.js';
+import '../../engine-DBxp_v6B.js';
+import '../../edit-lock/index.js';
+import './admin-bridge.js';

package/dist/screen/lib/host.js

@@ -0,0 +1 @@
+export{DETACHED_EASEL_HOST,EaselHostContext,EaselHostProvider,createEaselHost,useEaselHost}from"../../chunk-R5ZVNJLJ.js";

package/dist/screen/lib/key-scope.d.ts

@@ -0,0 +1,23 @@
+import { RefObject } from 'react';
+
+/**
+ * Where the editor listens for its page-wide shortcuts — undo / redo, copy and
+ * paste a style, Escape out of Add.
+ *
+ * On the shop's own `/edit` routes the editor IS the page (`host.ownsDocument`),
+ * so they listen on `document`, as they always have. Mounted inside another
+ * app — the admin portal's native editor window — `document` is the app's: a
+ * ⌘Z typed into a product form in another window would rewind the website, and
+ * the paste would land in a document the merchant is not looking at. There the
+ * editor's own root is the target, so a key reaches it only while focus is
+ * inside the editor. (The canvas frame is its own document and binds its own.)
+ */
+declare function useEaselKeyTarget(rootRef: RefObject<HTMLElement | null>): EventTarget | null;
+/**
+ * Undo / redo on the editor's own root when the editor does not own the page —
+ * the engine's `EaselProvider` binds them to `document`, and is told not to
+ * (`hotkeys={host.ownsDocument}` in ScreenStoreProvider) in exactly this case.
+ */
+declare function useEaselUndoKeys(rootRef: RefObject<HTMLElement | null>): void;
+
+export { useEaselKeyTarget, useEaselUndoKeys };

package/dist/screen/lib/key-scope.js

@@ -0,0 +1 @@
+export{useEaselKeyTarget,useEaselUndoKeys}from"../../chunk-OM67AJQC.js";import"../../chunk-R5ZVNJLJ.js";import"../../chunk-P67FP7PG.js";import"../../chunk-AELNNAFM.js";import"../../chunk-YRLPFZW3.js";import"../../chunk-D2BCHTQR.js";import"../../chunk-MFIRYGHW.js";import"../../chunk-ZNCEOSXO.js";import"../../chunk-KRXQM65X.js";import"../../chunk-NKB3KVAB.js";

package/dist/screen/lib/links/link-filters.d.ts

@@ -0,0 +1,41 @@
+import { L as LinkOption, a as LinkFilterField, b as LinkFilter } from '../../../LinkPicker-W2Rtxetz.js';
+import 'react';
+
+/**
+ * WHAT A HOST HANDS THE LINK FIELD of its own: the pages a link may point at,
+ * as the field lists them, and the host's product listing as the picker needs
+ * it (lib/host-chrome `linkFilters`). Types only.
+ *
+ * They are the host contract's, which is the screen's and moves into
+ * efficient-easel with it (doc/adr/0004), so they are not declared beside the
+ * builder's own half of the picker (lib/links/link-picker-setup, which hands
+ * them on): that module builds a website's kinds out of its pages, posts and
+ * products, and the screen imports none of it.
+ */
+/** One page a link may point at. `docs` = the published document, then the
+ *  draft: anchors (and a host's listing) are read off them in that order. */
+type LinkPickerPage = {
+    slug: string;
+    title: string;
+    docs: readonly unknown[];
+};
+/**
+ * A host's product listing, as the picker needs it: which page paths open a
+ * listing, the filters a link onto one may carry, and how a filter is read off
+ * and written onto a link. The storefront's are built from its catalogue and
+ * its Product Types answers (lib/links/link-rules `storefrontLinkFilters`).
+ */
+type LinkFilters = {
+    /** Every path that opens a listing — a page holding one, or a built-in route. */
+    listingPaths: readonly string[];
+    /** The Page list as the host wants it shown: a listing page's own name, a
+     *  built-in listing route added. Handed the builder's list; returns the list. */
+    pageOptions?: (options: readonly LinkOption[]) => LinkOption[];
+    /** The filters a link onto this listing path may carry, or null. */
+    filtersFor: (target: string) => readonly LinkFilterField[] | null;
+    readFilter: (url: string) => LinkFilter;
+    /** Write (or, with null, clear) the filter on a link. */
+    withFilter: (url: string, filter: LinkFilter) => string;
+};
+
+export type { LinkFilters, LinkPickerPage };

package/dist/screen/lib/load-error.d.ts

@@ -0,0 +1,29 @@
+/** Say what stopped the editor loading a document, in words an operator can
+ *  hand to a developer.
+ *
+ *  The status code is the part that matters: it is what tells a refused token
+ *  (401) apart from a deleted page (404), a broken backend (5xx) and a backend
+ *  that never answered at all — four different jobs for four different people.
+ *  Always carry the number, even inside the friendlier sentences, because the
+ *  screenshot an operator sends is usually all anyone gets.
+ *
+ *  This exists because it did NOT (11131). The editor screen said "Could not
+ *  load the document." for every one of those causes alike, so the storefront
+ *  editor could be down on every site — on a 401, from a portal-audience
+ *  mismatch — and the one thing anybody could report was the one thing that
+ *  narrowed nothing down. It lives in its own module, apart from the React
+ *  provider that shows it, so the wording is pinned by a test rather than
+ *  re-derived by whoever next reads the catch block. */
+declare function describeLoadFailure(e: unknown): string;
+/**
+ * The host's own sentence for a load it REFUSED, or null when this failure is
+ * not one of those. EFFICIENT has one: a slug that more than one website owns,
+ * opened without saying which — refusing to guess between websites is a correct
+ * outcome, not a crash, and it is said whole rather than behind "Could not load
+ * the document". The host says so (lib/backend-error `provideHostFailures`).
+ */
+declare function hostLoadRefusal(e: unknown, document: {
+    slug: string;
+}): string | null;
+
+export { describeLoadFailure, hostLoadRefusal };

package/dist/screen/lib/load-error.js

@@ -0,0 +1 @@
+export{describeLoadFailure,hostLoadRefusal}from"../../chunk-A7ZJII7O.js";import"../../chunk-KDYIMJTZ.js";

package/dist/screen/lib/media-panel.d.ts

@@ -0,0 +1,94 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { H as HostPickedMedia } from '../../host-DJ8Gzsx7.js';
+import '../../blocks/index.js';
+import '../../types-E3HrTPg2.js';
+import '../../data/index.js';
+import '../../types-41704JE4.js';
+import '../../resolve-D68pb3Bx.js';
+import '../../plan-DChbUXdS.js';
+import './document-contract.js';
+import './session.js';
+import './host-chrome.js';
+import './links/link-filters.js';
+import '../../LinkPicker-W2Rtxetz.js';
+import './document-hooks.js';
+import './section-template-types.js';
+import './puck/content-tree.js';
+import './document-switch.js';
+import '../../engine-DBxp_v6B.js';
+import '../../edit-lock/index.js';
+import './admin-bridge.js';
+
+/**
+ * The editor's MEDIA PANEL — the host's media library, drawn in the editor's own
+ * left panel beside Pages, Layers and Site styles.
+ *
+ * The editor owns no media library and never will: the library is the host's
+ * (the admin portal's Media Library, one component wherever it is shown). What
+ * the editor owns is the PLACE it shows — a left-panel view its rail opens — and
+ * the request that turns that view into a chooser for one field.
+ *
+ * It replaces a window. The rail button and every image field used to ask the
+ * host to open a separate "Media library" picker window over the editor
+ * (`storefront-editor:open-media-picker`), which floated beside the host's own
+ * Media Library window under the same name, built from different code, and could
+ * be sent behind the editor while the field that asked waited on it (harness
+ * UI-20, UI-21). A host that supplies a panel gets this instead; a host that
+ * does not keeps the message, so nothing it relies on changes underneath it.
+ *
+ *   • BROWSING — the rail opens the "media" left view. The host's panel shows
+ *     the library to look through, upload to, tidy. `pick` is null.
+ *   • PICKING — a field calls `requestMediaPick` (lib/media-picker). With
+ *     a panel here, that becomes {@link requestPanelPick}: the chrome lays the
+ *     panel over the left panel in pick mode, the host's panel calls `onPick`,
+ *     and the field gets the media. Leaving pick mode any other way (the
+ *     panel's Cancel, a rail button, closing the panel) settles it `null`.
+ *
+ * Module state for the same reason as lib/media-picker: the fields that
+ * ask are Puck custom fields, which no prop reaches.
+ */
+/** What a field asked the panel for. `file` is a file dropped straight on the
+ *  field: the host uploads it and picks it without waiting for a click. */
+interface MediaPickRequest {
+    requestId: string;
+    /** `image/*`, `video/*` or `image/svg+xml` — what the field can hold. */
+    accept: string;
+    /** The field's label, e.g. "Background image". */
+    title: string;
+    file?: File | null;
+}
+/** The props the host's panel component is drawn with. */
+interface MediaPanelProps {
+    /** The field choosing right now, or null while the merchant is browsing. */
+    pick: MediaPickRequest | null;
+    /** Answer the field. Ignored while browsing. */
+    onPick: (media: HostPickedMedia) => void;
+}
+/** The host's media library, as a component the editor draws in its panel. */
+type MediaPanelComponent = ComponentType<MediaPanelProps>;
+/** Supply the host's panel to the editor below. `panel` null keeps the old
+ *  window: fields ask the host with `open-media-picker`. */
+declare function MediaPanelProvider({ panel, children }: {
+    panel: MediaPanelComponent | null;
+    children: ReactNode;
+}): react.JSX.Element;
+/** The host's panel for the editor this renders in, or null. */
+declare function useMediaPanel(): MediaPanelComponent | null;
+/** Whether a field's request goes to the panel rather than to the host. */
+declare function hasMediaPanel(): boolean;
+/**
+ * Open the panel in pick mode for one field; resolves with the media chosen, or
+ * null. A second field asking before the first is answered takes the panel over,
+ * and the first resolves null — one panel answers one field.
+ */
+declare function requestPanelPick(request: MediaPickRequest): Promise<HostPickedMedia | null>;
+/** Answer the field the panel is choosing for (`media` null: no choice). A
+ *  stale id — an answer for a request already superseded — does nothing. */
+declare function settlePanelPick(requestId: string, media: HostPickedMedia | null): void;
+/** Leave pick mode without a choice, whatever is being chosen. */
+declare function cancelPanelPick(): void;
+/** The field the panel is choosing for, or null while nothing is. */
+declare function usePanelPick(): MediaPickRequest | null;
+
+export { type MediaPanelComponent, type MediaPanelProps, MediaPanelProvider, type MediaPickRequest, cancelPanelPick, hasMediaPanel, requestPanelPick, settlePanelPick, useMediaPanel, usePanelPick };

package/dist/screen/lib/media-panel.js

@@ -0,0 +1 @@
+export{MediaPanelProvider,cancelPanelPick,hasMediaPanel,requestPanelPick,settlePanelPick,useMediaPanel,usePanelPick}from"../../chunk-ZZ7VLIHQ.js";

package/dist/screen/lib/media-picker.d.ts

@@ -0,0 +1,68 @@
+import { E as EaselHost } from '../../host-DJ8Gzsx7.js';
+import 'react';
+import '../../blocks/index.js';
+import '../../types-E3HrTPg2.js';
+import '../../data/index.js';
+import '../../types-41704JE4.js';
+import '../../resolve-D68pb3Bx.js';
+import '../../plan-DChbUXdS.js';
+import './document-contract.js';
+import './session.js';
+import './host-chrome.js';
+import './links/link-filters.js';
+import '../../LinkPicker-W2Rtxetz.js';
+import './document-hooks.js';
+import './section-template-types.js';
+import './puck/content-tree.js';
+import './document-switch.js';
+import '../../engine-DBxp_v6B.js';
+import '../../edit-lock/index.js';
+import './admin-bridge.js';
+
+/**
+ * Editor media-picker bridge — the one call every media slot makes to choose an
+ * image or a video, resolving with the chosen media.
+ *
+ * Where the choosing happens depends on the host:
+ *
+ *   • A host that supplies a MEDIA PANEL (lib/media-panel — the admin
+ *     portal, from efficient-web 0.2.0) answers in the editor's own left panel:
+ *     the request opens that panel in pick mode, and nothing leaves the editor.
+ *   • Any other host is asked to open its picker window, over the
+ *     request/response protocol below. The picker UI lives in the host, so
+ *     this module owns the EDITOR half:
+ *
+ *   requestMediaPick({ accept, title, file? })
+ *     → posts `storefront-editor:open-media-picker` { requestId, accept, title, file }
+ *       to the host (lib/host — over postMessage when framed).
+ *   The admin (PageBlockEditor) relays the window's result back down:
+ *     `storefront-editor:media-picked`        { requestId, media:{id,url,kind} } → resolve(media)
+ *     `storefront-editor:media-pick-cancelled`{ requestId }                      → resolve(null)
+ *   resolveMediaPick(requestId, …) is called by the central message listener
+ *   (ScreenDocumentContext) to settle the pending promise, correlated by id.
+ *
+ * Same module-singleton reason as lib/editor-auth / lib/editor-events: Puck
+ * custom fields (the media slots) can't receive the listener as a prop.
+ */
+
+interface PickedMedia {
+    id: string;
+    url: string;
+    kind: "image" | "video";
+}
+/**
+ * Choose media for a slot; resolves with the chosen media, or null if the user
+ * cancelled (or there's no host to ask). `file` is a file dropped straight on
+ * the slot — the host uploads it and picks it immediately.
+ */
+declare function requestMediaPick(host: EaselHost, opts: {
+    accept: string;
+    title: string;
+    file?: File | null;
+}): Promise<PickedMedia | null>;
+/** Settle a pending pick (called by the central message listener on the admin's
+ *  reply). Unknown ids — a stale reply, or a pick meant for another editor
+ *  iframe — no-op. */
+declare function resolveMediaPick(requestId: string, media: PickedMedia | null): void;
+
+export { type PickedMedia, requestMediaPick, resolveMediaPick };

package/dist/screen/lib/media-picker.js

@@ -0,0 +1 @@
+export{requestMediaPick,resolveMediaPick}from"../../chunk-6FY3PZS3.js";import"../../chunk-ZZ7VLIHQ.js";

package/dist/screen/lib/page-lock.d.ts

@@ -0,0 +1,5 @@
+import { EditLock } from '../../edit-lock/index.js';
+
+declare const pageEditLock: EditLock;
+
+export { pageEditLock };

package/dist/screen/lib/page-lock.js

@@ -0,0 +1 @@
+export{pageEditLock}from"../../chunk-AKZWUV5Z.js";import"../../chunk-HMX55DYT.js";import"../../chunk-KDYIMJTZ.js";import"../../chunk-JUQ6YJCG.js";import"../../chunk-RE4LP46F.js";