efficient-easel 0.101.1 → 0.103.0

package/dist/screen/lib/admin-bridge.d.ts

@@ -0,0 +1,105 @@
+import { RefObject } from 'react';
+import { EaselSession } from './session.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 './host-chrome.js';
+import './links/link-filters.js';
+import '../../LinkPicker-W2Rtxetz.js';
+import './document-contract.js';
+import './document-hooks.js';
+import './section-template-types.js';
+import './puck/content-tree.js';
+
+/** The `storefront-editor:auth` payload the admin portal bridges in. */
+interface AuthMessage {
+    type?: string;
+    token?: string;
+    /**
+     * The WEBSITE this editor is working on, as a real `StorefrontSite` id — the
+     * admin's answer to "where does an upload from this editor belong?" (its own
+     * page target's site, else the website the operator has open). OPTIONAL by
+     * design: an admin build that predates it sends nothing, and "the admin cannot
+     * tell you" is a real answer that must not be turned into a default.
+     *
+     * A SEPARATE IDENTITY FROM `brandId` — a brand is a wheel manufacturer, a site
+     * is a storefront. They are never interchangeable, so neither is ever used as a
+     * fallback for the other.
+     */
+    siteId?: string;
+    /**
+     * The BRAND being edited, the legacy upload scope. Kept exactly as it was:
+     * still read, still stored, still the only thing that can produce a `?brand=`
+     * upload. Untouched by the site bridge above.
+     */
+    brandId?: string;
+    theme?: string;
+    /** Operator capabilities the CONSOLE has resolved. See {@link BridgedCapabilities}. */
+    can?: unknown;
+}
+/**
+ * Capabilities the editor may not decide for itself.
+ *
+ * `canCreatePlatformTemplate` is the operator bar for "Save site as platform
+ * template". The editor CANNOT derive it: being on localhost, holding a token,
+ * having no tenant info, a URL parameter, something in localStorage and the mere
+ * presence of a siteId are all things a page can arrange for itself. Only the
+ * authenticated Admin Console knows whether this user is a platform operator, so
+ * it says so explicitly on the already origin-gated auth message.
+ *
+ * This is a UI affordance ONLY. The backend re-checks `IsPlatformOperator` on
+ * every call, so a forged flag buys a hidden button and a 403.
+ *
+ * Optional with a safe default of `false`: the shop and admin images deploy
+ * independently, so an editor build that REQUIRED this field would break against
+ * any console still on the previous build.
+ */
+type BridgedCapabilities = {
+    canCreatePlatformTemplate: boolean;
+};
+declare const NO_BRIDGED_CAPABILITIES: BridgedCapabilities;
+/**
+ * Apply one accepted auth grant — the whole effect of a trusted
+ * `storefront-editor:auth`, minus the React state the hook owns.
+ *
+ * Split out of the listener so the grant's CONTRACT can be exercised without a
+ * DOM and a mounted editor (see scripts/test-editor-site-bridge.ts): the listener
+ * decides whether to trust a message, this decides what a trusted one does.
+ *
+ * The two things it writes are deliberately separate concerns, both kept on the
+ * editor SESSION (lib/session — the one the grant was delivered to):
+ *   • the JWT + the legacy brand (read through lib/editor-auth) — the existing
+ *     contract, set with exactly the values it always was;
+ *   • the website scope (read through lib/editor-site), which the document
+ *     context also writes to. See that module for why they don't share a slot.
+ *
+ * Unconditional in both cases: a grant with no `siteId` CLEARS the bridged scope
+ * rather than leaving the last website standing, so a refresh after the operator
+ * moved on can't file the next upload against where they used to be.
+ */
+declare function applyAuthGrant(d: AuthMessage & {
+    token: string;
+}, opts?: {
+    stampChromeTheme?: boolean;
+    session?: EaselSession;
+}): void;
+interface AdminBridge {
+    /** The bridged admin JWT — null until the handshake completes. */
+    token: string | null;
+    /** Live ref to the same token, for stable callbacks that must not re-bind. */
+    tokenRef: RefObject<string | null>;
+    /** What the CONSOLE says this operator may do. All false until it says so. */
+    capabilities: BridgedCapabilities;
+}
+declare function useAdminBridge(handlers?: {
+    /** Called after each auth grant is applied. `hadToken` distinguishes a
+     *  refresh (e.g. after an auth-expired save — retry it) from the first grant. */
+    onAuth?: (hadToken: boolean) => void;
+    /** Every OTHER message from a trusted admin origin (already origin-gated). */
+    onMessage?: (data: unknown) => void;
+}): AdminBridge;
+
+export { type AdminBridge, type AuthMessage, type BridgedCapabilities, NO_BRIDGED_CAPABILITIES, applyAuthGrant, useAdminBridge };

package/dist/screen/lib/admin-bridge.js

@@ -0,0 +1 @@
+export{NO_BRIDGED_CAPABILITIES,applyAuthGrant,useAdminBridge}from"../../chunk-Q3SQBNJB.js";import"../../chunk-3WSPDAK2.js";import"../../chunk-R5ZVNJLJ.js";import"../../chunk-6TZTKAB5.js";import"../../chunk-AJBJ74ME.js";

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

@@ -0,0 +1,106 @@
+import { SaveConflict, LockHolder } from '../../edit-lock/index.js';
+
+/**
+ * lib/backend-error.ts — why an editor's backend call failed, in the
+ * editor's own terms, and how the host says what its own failures mean.
+ *
+ * Moved from lib/web-backend (which re-exports all of it) so the editor's screen
+ * can classify a failure — a document that would not load, a save refused —
+ * without importing the website's backend interfaces, and can move into
+ * efficient-easel with the screen (doc/adr/0004). Nothing here names a page or
+ * a site.
+ */
+
+/** Why a backend call failed, in the editor's own terms. */
+type WebsiteBackendErrorKind = 
+/** The session is not (or no longer) authorised. The editor tells its host
+ *  (`storefront-editor:auth-expired`) and treats the call as failed. */
+"unauthorized"
+/** A save was refused: the stored page moved on since this copy was loaded.
+ *  Carries `conflict`. */
+ | "changed-elsewhere"
+/** Somebody else holds the page (a claim), or took it from this tab (a save).
+ *  Carries `holder`. */
+ | "lock-taken"
+/** There is no such page, site or template. */
+ | "not-found"
+/** The backend understood the request and refused it as wrong. */
+ | "invalid"
+/** No answer: offline, timed out, the backend itself failing. */
+ | "unavailable";
+/**
+ * The one error a backend rejects with.
+ *
+ * `message` is shown to the operator where the editor has nowhere better to
+ * read from (a document that would not load), so write it for a person.
+ */
+declare class WebsiteBackendError extends Error {
+    readonly kind: WebsiteBackendErrorKind;
+    /** `changed-elsewhere`: who saved, and whether it was this person's own tab. */
+    readonly conflict?: SaveConflict;
+    /** `lock-taken`: who holds the page. */
+    readonly holder?: LockHolder;
+    /** `invalid`: the inputs that were refused, by name, each with the reason —
+     *  when the backend can say which. The editor shows it beside that input. */
+    readonly fields?: Readonly<Record<string, string>>;
+    constructor(kind: WebsiteBackendErrorKind, message?: string, detail?: {
+        conflict?: SaveConflict;
+        holder?: LockHolder;
+        fields?: Readonly<Record<string, string>>;
+        cause?: unknown;
+    });
+}
+/**
+ * Whether `err` is a backend failure — optionally of one kind.
+ *
+ * By NAME and shape, not `instanceof`: an embedder's bundle and this package
+ * may each carry their own copy of the class (two module graphs), and an error
+ * thrown by one must still be read by the other.
+ */
+declare function isBackendError(err: unknown, kind?: WebsiteBackendErrorKind): err is WebsiteBackendError;
+/** The status the editor gives a call that got no answer at all. */
+declare const STATUS_UNREACHABLE = 0;
+/**
+ * A failure of the HOST'S OWN HTTP client, as the two things the editor's
+ * shared rules read off one: a status and the response body.
+ *
+ * Not every call goes through a `WebsiteBackend` yet (doc/adr/0002: the groups
+ * that have not crossed), and a call that does not rejects with the host's own
+ * error class — EFFICIENT's `ApiError`. The edit lock, the refused-save notice
+ * and the "could not open this page" message all have to read such an error,
+ * and until this they imported that class to do it. The host tells the editor
+ * how to read its errors instead ({@link provideHostFailures}); the editor
+ * imports none of them.
+ */
+interface HostFailure {
+    /** HTTP-style: 401, 404, 409, 5xx — or {@link STATUS_UNREACHABLE}. */
+    status: number;
+    /** The response body, or null. */
+    data: unknown;
+    message: string;
+}
+interface HostFailures {
+    /** A host client error as a {@link HostFailure}; null for anything else. */
+    read(err: unknown): HostFailure | null;
+    /** What the host says when its server cannot be reached at all. */
+    unreachableMessage: string;
+    /** The host's whole sentence for a document it REFUSED to open — a correct
+     *  outcome of its own, not a failed call; null for everything else. */
+    loadRefusal?(err: unknown, document: {
+        slug: string;
+    }): string | null;
+}
+/** Tell the editor how to read the host client's own errors. Called once, by
+ *  the host's backend module as it loads (EFFICIENT's: `lib/efficient-backend`). */
+declare function provideHostFailures(failures: HostFailures): void;
+/** `err` as the host's client failure it is, or null when it is not one (or no
+ *  host has said how to read its errors). */
+declare function readHostFailure(err: unknown): HostFailure | null;
+/** The host's sentence for a document it refused to open, or null. */
+declare function hostLoadRefusalOf(err: unknown, document: {
+    slug: string;
+}): string | null;
+/** The host's own "server cannot be reached" sentence, or a plain one. */
+declare function hostUnreachableMessage(): string;
+
+export { type HostFailure, STATUS_UNREACHABLE, WebsiteBackendError, type WebsiteBackendErrorKind, hostLoadRefusalOf, hostUnreachableMessage, isBackendError, provideHostFailures, readHostFailure };

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

@@ -0,0 +1 @@
+export{STATUS_UNREACHABLE,WebsiteBackendError,hostLoadRefusalOf,hostUnreachableMessage,isBackendError,provideHostFailures,readHostFailure}from"../../chunk-KDYIMJTZ.js";

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

@@ -0,0 +1,21 @@
+/**
+ * Editor chrome theme bridge — the embedded editor is deliberately LIGHT-ONLY.
+ *
+ * The admin portal bridges its resolved efficient-shell theme in the
+ * `storefront-editor:auth` message (see efficient-admin-portal's
+ * PageBlockEditor). Every editor entry point — the page/template editor AND the
+ * standalone section editor — still hands that value here so the call site stays
+ * uniform, but the editor no longer mirrors the admin's dark palette: per owner
+ * directive the storefront editor renders in the light base regardless of the
+ * bridged theme. This function stamps `data-editor-theme="light"` unconditionally;
+ * the CSS (components/storefront-editor.css) carries only the light `--sf-*` base,
+ * so the editor chrome is always light.
+ */
+/**
+ * Reflect the (light-only) editor chrome theme onto the editor document.
+ * The bridged admin theme is intentionally ignored — the editor is always light.
+ * No-op server-side.
+ */
+declare function applyEaselChromeTheme(theme: string | null | undefined): void;
+
+export { applyEaselChromeTheme };

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

@@ -0,0 +1 @@
+export{applyEaselChromeTheme}from"../../chunk-3WSPDAK2.js";

package/dist/screen/lib/client-only.d.ts

@@ -0,0 +1,24 @@
+import { ComponentType } from 'react';
+
+/**
+ * lib/client-only.tsx — a component that is drawn in the browser only: what
+ * `next/dynamic` with `{ ssr: false }` did for the editor's screen.
+ *
+ * The editor never needs a server render: it draws only after a client-side
+ * sign-in. The screen used `next/dynamic` for that, which is a Next.js import,
+ * and the screen moved into efficient-easel, whose only peers are react and
+ * react-dom (efficient-web-builder doc/adr/0004). This is the same thing in
+ * React's own terms: nothing on the server, nothing on the client's first
+ * render (so hydration matches), then the component.
+ *
+ * The component is IMPORTED, not loaded with `import()`. Every module of the
+ * screen imports with no DOM (tests/screen-one-graph.test.ts), so nothing here
+ * needs keeping out of a server's module graph; and a dynamic `import()` of a
+ * file of this package is a second instance of it in a host that loads the
+ * package through `require` (a CommonJS test runner), with a second copy of
+ * every context the screen provides, so the provider above it and the chrome
+ * below it would not meet.
+ */
+declare function clientOnly<P extends object>(Component: ComponentType<P>): ComponentType<P>;
+
+export { clientOnly };

package/dist/screen/lib/client-only.js

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

package/dist/screen/lib/content/view-tiers.d.ts

@@ -0,0 +1,25 @@
+/**
+ * View tiers — the desktop / tablet / mobile split that every PER-VIEW section
+ * setting is authored against.
+ *
+ * A merchant does not set one number for all screens: they pick a view in the
+ * editor chrome's top bar and set THAT view. Three separate places have to agree
+ * on what "tablet" means for that to work — the top-bar switcher
+ * (PreviewDeviceContext), the field the merchant edits, and the live grid that
+ * renders the result — so the tier vocabulary lives here, once, rather than
+ * being restated by each feature that grows a per-view control.
+ *
+ * The Footer's columns-per-line and logo-fill toggles were the first callers;
+ * the Alloy Wheels Listing's wheels-per-row (lib/wheels/plp-grid) is the second.
+ */
+type ViewTier = "desktop" | "tablet" | "mobile";
+/** Order the tiers surface in the UI (widest → narrowest). */
+declare const VIEW_TIERS: ViewTier[];
+/** Human label per tier (control hints, a11y). */
+declare const VIEW_TIER_LABEL: Record<ViewTier, string>;
+declare const VIEW_TABLET_MIN = 720;
+declare const VIEW_DESKTOP_MIN = 1100;
+/** Which tier a viewport width falls in. */
+declare function viewTierForWidth(width: number): ViewTier;
+
+export { VIEW_DESKTOP_MIN, VIEW_TABLET_MIN, VIEW_TIERS, VIEW_TIER_LABEL, type ViewTier, viewTierForWidth };

package/dist/screen/lib/content/view-tiers.js

@@ -0,0 +1 @@
+var e=["desktop","tablet","mobile"],t={desktop:"Desktop",tablet:"Tablet",mobile:"Mobile"},o=720,b=1100;function l(e){return e>=1100?"desktop":e>=720?"tablet":"mobile"}export{b as VIEW_DESKTOP_MIN,o as VIEW_TABLET_MIN,e as VIEW_TIERS,t as VIEW_TIER_LABEL,l as viewTierForWidth};

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

@@ -0,0 +1,20 @@
+export { A as AnyDocumentAddressing, a as DocumentAddressing, N as NO_DOCUMENT_ADDRESSING } from '../../host-DJ8Gzsx7.js';
+import './document-contract.js';
+import './session.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-switch.js';
+import '../../engine-DBxp_v6B.js';
+import '../../edit-lock/index.js';
+import './admin-bridge.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';

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

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

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

@@ -0,0 +1,237 @@
+/**
+ * lib/document-contract.ts — WHAT STORES A DOCUMENT, as the provider
+ * that loads and saves one asks it (components/ScreenDocumentContext): a
+ * resolved document, the adapter that reads and writes it, and the
+ * capabilities the one chrome consults.
+ *
+ * The contract and nothing that keeps it. The two adapters there are — a
+ * website's pages, a website template's pages — are the website's, and stand
+ * where they always have (lib/editor-document-adapter, whose account of why
+ * the capabilities exist is the one to read, and which still hands these
+ * types on). They are here because the provider is a file of the editor's
+ * screen, which imports no website (doc/adr/0003, seam W5): it is handed its
+ * adapter (lib/document-addressing) and needs only the shape of one.
+ *
+ * The capabilities keep the names the chrome and the panels have always read,
+ * most of them in a website's words. Which of them any editor has, and under
+ * what name, is settled when the screen moves to efficient-easel.
+ *
+ * So do the four shapes an adapter hands back besides a document — a row of the
+ * page list, the edit lock, the site record and what is written of it. They are
+ * declared HERE and not with the backend's contract (lib/web-backend, which
+ * names them in its own groups and hands them on): this module moves into
+ * efficient-easel with the screen (doc/adr/0004), and the website's backend
+ * does not. The record and its patch are a website's, as most capabilities'
+ * names are: the screen reads neither and hands them through to the layer's
+ * own chrome, and whether the contract keeps them is settled with the names.
+ */
+/** One row of the editor's page list. Rows arrive in display order. */
+type EaselPageRow = {
+    id: string;
+    slug: string;
+    /** What the list calls the page. */
+    label: string;
+    /** Header text of the row's group (null / absent = top level). */
+    group?: string | null;
+    /** Stable key of that group — two groups may share a header text. */
+    groupKey?: string;
+    /** Not published yet (drives the "draft" tag). False where pages never publish. */
+    draft: boolean;
+    /** Page kind, where the backend has kinds (`dynamic`, `lightbox`, …). */
+    kind?: string | null;
+};
+/** The advisory "somebody is editing this page" lock. */
+interface WebsiteEditLock {
+    /**
+     * Claim the page, refresh the claim (the heartbeat) or — `takeover` — take it
+     * from whoever holds it. Resolves once this tab holds the page; rejects
+     * `lock-taken` (with `holder`) while somebody else does.
+     */
+    claim(id: string, clientId: string, takeover: boolean): Promise<{
+        heartbeatSeconds: number;
+    }>;
+    /** Hand the page back. Best-effort: a lock expires by itself. */
+    release(id: string, clientId: string): Promise<void>;
+}
+/** What the editor reads of the website itself. */
+interface SiteRecord {
+    /** The website's display name. */
+    name: string;
+    /** Its public slug, where it has one. */
+    slug?: string | null;
+    /** The site-wide Google Maps browser key the canvas's map blocks draw with. */
+    mapsApiKey?: string | null;
+    /** The site-wide Google Maps cloud style. */
+    mapsMapId?: string | null;
+}
+/** The part of the site record the editor writes. */
+type SiteRecordPatch = {
+    mapsApiKey?: string;
+};
+/** What the pointed-at document supports — its record type, and the backend
+ *  behind it. The editor renders ONE chrome and consults these to include the
+ *  few genuinely mode-specific controls. */
+type EaselCapabilities = {
+    /** Publish/unpublish + draft state exist (site pages on a backend that
+     *  publishes). A template page has no public URL — its documents save, never
+     *  publish — and neither does a page whose backend has no `pages.publish`. */
+    canPublish: boolean;
+    /** Site-wide panels apply: SEO/sitemap, site settings, maps keys, chat,
+     *  favicon — anything that reads or writes the WEBSITE, not the document.
+     *  These rows are EFFICIENT's (`/api/storefront/*`, still read by their own
+     *  callers), so this is false for a template AND for a page on an embedder's
+     *  own backend. */
+    hasSiteSettings: boolean;
+    /** The styles tab (site theme/fonts) reads StorefrontThemeSettings; a
+     *  template's theme rides inside its own document instead. */
+    hasSiteTheme: boolean;
+    /** Placeholder frames are on: the canvas renders every MEDIA slot as its
+     *  built-in placeholder hint (template authoring — a template never previews
+     *  media; its text and structure always render as authored). */
+    placeholderFrames: boolean;
+    /** Media may be picked/uploaded onto this document. False for templates —
+     *  a template never owns, stores or selects media (the backend strips it on
+     *  every template write), so every upload/picker affordance is hidden. */
+    mediaEditing: boolean;
+    /** Pages are created through the HOST's New Page form (the admin console's —
+     *  title, URL handle, SEO and the template-library picker live there). When
+     *  false — the backend has `pages.create` — the switcher offers its own
+     *  lightweight inline "Add page". */
+    pageCreationInAdminForm: boolean;
+    /** Pages may be deleted inline from the switcher (the backend has
+     *  `pages.remove`; an EFFICIENT site page's delete lives in the admin Pages
+     *  list with its guards). */
+    canDeletePagesInline: boolean;
+    /** An advisory "somebody is editing this" lock exists for the document
+     *  (`WebsiteBackend.lock`, site pages). Without one the editor is writable
+     *  from the start and the version check alone guards a save. */
+    hasEditLock: boolean;
+    /** The "somebody else is editing" and "your save was refused" notices apply:
+     *  a website's page, whose saves are versioned and may be locked. A template
+     *  page is neither, so the notices have nothing to say there. */
+    hasEditGuard: boolean;
+    /** The document carries the storefront's PINNED chrome — the Header marker
+     *  and the Footer the chrome seeds and heals. EFFICIENT's own furniture: a
+     *  page on an embedder's backend is its sections and nothing else. The Header
+     *  is a commerce block and the Footer a service one, so it also needs both of
+     *  those sets offered — seeding either would write a withheld block. */
+    hasPinnedChrome: boolean;
+    /** Website-scoped controls (Appearance, Header, Live chat) stay in view as
+     *  explained placeholders — a website TEMPLATE, where each website made from
+     *  it sets its own. False where they exist for real (a site page) and where
+     *  the backend has none of them at all (an embedder's own): there the chrome
+     *  offers no entry to a panel that could only apologise. */
+    explainsSiteSettings: boolean;
+    /** The website's own record can be read (`site.get`): its name, its Maps
+     *  key. False for a template, and for an EFFICIENT page opened without a
+     *  site id — a site row IS its id. */
+    hasSiteRecord: boolean;
+    /** …and its Maps key written (`site.update`). */
+    canEditSiteRecord: boolean;
+    /** The top bar's Preview link has an address: `preview.href`, or the
+     *  storefront's own rule under the EFFICIENT backend. */
+    hasPreviewLink: boolean;
+    /** The product catalog is read into the canvas (the wheels page's seed, the
+     *  listing's live rows). EFFICIENT's, until the catalog joins the backend
+     *  contract — and only where the commerce blocks it fills are offered. */
+    hasCatalog: boolean;
+    /** The website's forms can be listed, built and edited (the Form section's
+     *  picker, and the host's form builder behind it). EFFICIENT's, until forms
+     *  join the backend contract: under any other backend — or where the service
+     *  blocks are not offered — the picker offers nothing to choose, build or
+     *  retry. */
+    hasForms: boolean;
+    /** The website's blog can be listed (`backend.blog`): a section's optional
+     *  "Blog post source" offers its posts, and a link has a "Blog post" target.
+     *  Needs the backend's blog AND the service blocks offered — EFFICIENT's
+     *  backend always has one, so there it is `offersService` exactly. Without
+     *  it a block that is already linked to a post says so and can only be
+     *  unlinked, and the link picker lists no post. */
+    hasBlog: boolean;
+    /** The COMMERCE set of blocks is offered (lib/editor-blocks). Without it a
+     *  link has no "Product" target and no product-type row: nothing on the page
+     *  could be a product listing. True unless the host chose its sets. */
+    offersCommerce: boolean;
+    /** The SERVICE set of blocks is offered. Without it a link has no "Blog post"
+     *  target, and a section's optional "Blog post source" is not drawn. True
+     *  unless the host chose its sets. */
+    offersService: boolean;
+};
+/** A resolved, editable document. */
+type EaselDocument = {
+    id: string;
+    layout: unknown;
+    /** Page kind (`dynamic` drives product binding) — site pages only. */
+    kind?: string | null;
+    /** VERSION of the document as loaded — what a save says it is replacing, so a
+     *  second editor's autosave is refused instead of erasing this one's work.
+     *  `null` for a record type with no version check (a template page). */
+    version?: string | null;
+    /** Why this document may NEVER be written, in words for the operator — "Read-only
+     *  — this campaign is sent": a record that is the account of something that
+     *  already happened (0.103.0). Carried, the editor holds the document
+     *  read-only for good: its saves are refused, its edit lock is never claimed,
+     *  and the save pill's place says this. Absent (every website document), it
+     *  is writable as it always was. */
+    readOnlyReason?: string;
+};
+interface EaselDocumentAdapter {
+    capabilities: EaselCapabilities;
+    /** Resolve the document for `slug`, or null when it doesn't exist. Template
+     *  mode may CREATE the missing home page (a fresh template opens on
+     *  something, mirroring backend migration 0021). */
+    resolve(slug: string): Promise<EaselDocument | null>;
+    /** Persist a document's working layout; answers with the version it now has.
+     *
+     *  `version` is what `resolve` returned (refreshed from each save's answer):
+     *  the version this write replaces. A record type with a version check REFUSES
+     *  a null — writing a document blind is the bug this parameter exists for, so
+     *  it fails loudly rather than quietly saving unguarded. A record type without
+     *  one ignores it.
+     *
+     *  `clientId` is this editor tab, the id its edit-lock claim sends. A record
+     *  type with a lock sends it, and the backend then refuses the write as
+     *  `lock-taken` once somebody else has taken the document from this tab.
+     *  A record type without a lock ignores it. */
+    saveLayout(id: string, layout: Record<string, unknown>, version: string | null, clientId?: string): Promise<{
+        version: string | null;
+    }>;
+    /** Re-read the CURRENT stored version of one document, without its layout.
+     *
+     *  Only a record type with a version check has one. It exists for the single
+     *  case where this editor is refused by its own earlier save from another
+     *  session: the operator asked for one editor, not a question, so the write is
+     *  re-based on what is stored and sent again — see
+     *  `ScreenDocumentContext.persistLayout`. A record type without a version
+     *  check never conflicts, so it does not implement this. */
+    rereadVersion?(id: string): Promise<string | null>;
+    /** Make the stored working copy the public one (`capabilities.canPublish`). */
+    publish?(id: string, version?: string): Promise<{
+        version: string | null;
+    }>;
+    /** The document's advisory edit lock (`capabilities.hasEditLock`). */
+    lock?: WebsiteEditLock;
+    /** The rows the page switcher navigates between. */
+    listPages(): Promise<EaselPageRow[]>;
+    /** Inline page creation (absent when the host's form owns it). */
+    createPage?(input: {
+        slug: string;
+        title: string;
+        layout: Record<string, unknown>;
+    }): Promise<EaselPageRow>;
+    /** Inline page deletion. */
+    deletePage?(id: string): Promise<void>;
+    /** The website's record (`capabilities.hasSiteRecord`). */
+    site?(): Promise<SiteRecord>;
+    /** Save the website's Maps key (`capabilities.canEditSiteRecord`). */
+    updateSite?(patch: SiteRecordPatch): Promise<SiteRecord>;
+    /** The name of the template this document is a page of (template mode) —
+     *  the canvas header's wordmark while it is edited. */
+    templateName?(): Promise<string>;
+    /** The top bar's Preview link for a page, when the BACKEND names it
+     *  (`preview.href`). Absent under the EFFICIENT backend, whose link is the
+     *  storefront's own rule (components/usePreviewHref). */
+    previewHref?(slug: string): string;
+}
+
+export type { EaselCapabilities, EaselDocument, EaselDocumentAdapter, EaselPageRow, SiteRecord, SiteRecordPatch, WebsiteEditLock };

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

@@ -0,0 +1 @@
+import"../../chunk-GZO72N3Q.js";

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

@@ -0,0 +1,71 @@
+import { Data } from '../../blocks/index.js';
+import { EaselCapabilities } from './document-contract.js';
+import 'react';
+import '../../types-E3HrTPg2.js';
+import '../../data/index.js';
+import '../../types-41704JE4.js';
+import '../../resolve-D68pb3Bx.js';
+import '../../plan-DChbUXdS.js';
+
+/**
+ * WHAT A HOST DOES TO A DOCUMENT AS IT OPENS AND AS IT IS STORED.
+ *
+ * The editor loads a page's layout and hands it to the canvas; every edit goes
+ * back through the autosave. Between those two a HOST may have work of its own
+ * that is not the editor's to know (doc/adr/0002, doc/adr/0004): the storefront
+ * seeds a fresh wheels page with its catalogue sections and gives the canvas
+ * the live catalogue a listing block draws on a published page — and takes
+ * that catalogue back out of every edit, so it is never saved.
+ *
+ * That used to be written into the editor's document context, which therefore
+ * imported the shop's catalogue. It is the host's now, handed over on the
+ * editor's session beside its registry and its chrome (`documentHooks`,
+ * lib/session; the storefront's: lib/storefront-document). An editor
+ * given none opens a document as it is stored and stores it as it is edited.
+ *
+ * The hooks are the host's; their SHAPE is the session's, so this module moves
+ * into efficient-easel with the screen (doc/adr/0004), and it reads the
+ * capabilities off the document's contract (lib/document-contract)
+ * rather than off the website's adapters that hand them on.
+ */
+
+/** What the editor knows of the document it is about to open. */
+interface OpeningDocument {
+    /** The page's slug (a template's page too). */
+    slug: string;
+    /** Whether it is a page of a template, which has no website of its own. */
+    isTemplate: boolean;
+    /** What the backend in force supports — a host's hooks gate on these, as the
+     *  editor's own panels do. */
+    capabilities: EaselCapabilities;
+}
+interface EaselDocumentHooks {
+    /**
+     * Called as a document's load STARTS, so a host can fetch what it needs
+     * while the layout is still on its way. The function it answers with is
+     * handed the stored layout and resolves to the layout the canvas opens on.
+     *
+     * INITIAL data only — the canvas reads it once — and best effort: it must
+     * resolve (to the layout it was given, when the host's own read failed), for
+     * a rejection here is a document that does not open.
+     */
+    opening?(document: OpeningDocument): (layout: Data) => Promise<Data>;
+    /**
+     * Every edit on its way to the autosave, and the layout Publish sends: take
+     * back out whatever {@link opening} put in for display only. Synchronous,
+     * and the SAME object back when there is nothing to take out.
+     */
+    stored?(layout: Data): Data;
+    /**
+     * The same taking-out for ONE node that is leaving this document for
+     * another — a section copied onto another page is saved there directly, and
+     * never passes through {@link stored}. The same node back when there is
+     * nothing to take out.
+     */
+    storedNode?<T extends {
+        type: string;
+        props?: Record<string, unknown>;
+    }>(node: T): T;
+}
+
+export type { EaselDocumentHooks, OpeningDocument };