efficient-easel 0.0.0 → 0.96.0

package/dist/autosave/index.d.ts

@@ -0,0 +1,101 @@
+import { A as Autosave, a as AutosaveSnapshot, b as SaveIndicator, c as AutosaveOptions } from '../words-CsRWXkY4.js';
+export { d as AutosaveClock, S as SaveWords, e as createAutosave, s as saveIndicator } from '../words-CsRWXkY4.js';
+import '../types-CuNiSnX6.js';
+import '../types-DNrn_w4V.js';
+import '../wordFit-9B9nqyf3.js';
+import 'react';
+import '../edit-lock/index.js';
+
+type UseAutosaveOptions<T> = Omit<AutosaveOptions<T>, 'save' | 'onFailure'> & {
+    /** Write one document. Read at call time, so it may close over current props. */
+    save: (value: T) => Promise<void>;
+    /** Read at call time, like `save`. */
+    onFailure?: (error: unknown, attempt: number) => void;
+    /** Ask the browser to warn before unloading while an edit is off the server. Default true. */
+    warnBeforeUnload?: boolean;
+};
+type UseAutosave<T> = Omit<Autosave<T>, 'setSave' | 'getSnapshot' | 'subscribe' | 'dispose'> & {
+    state: AutosaveSnapshot;
+    /** The pill's tone and words — `<SaveState {...indicator} />`. */
+    indicator: SaveIndicator;
+};
+declare function useAutosave<T>(options: UseAutosaveOptions<T>): UseAutosave<T>;
+
+/**
+ * Save when the TAB goes away — the case an unmount does not cover.
+ *
+ * React does not unmount an editor when the operator switches tab or window or
+ * locks the screen, so the edit waiting out its second stays in memory; and an
+ * async save cannot be finished during unload, which is why the close-tab
+ * handler only warns. Both editors had these same two listeners of their own
+ * (efficient-admin-portal `src/components/email/autosaveTabAway.ts`,
+ * efficient-shop `components/StorefrontDocumentContext.tsx`).
+ *
+ *  - `visibilitychange` to `hidden` is the one that matters, and an ordinary
+ *    save: the page is alive, so it completes. Guarded on `hidden` because the
+ *    event also fires on the way BACK, when there is nothing to hurry.
+ *  - `pagehide` is the last gasp: the document is being torn down, so the save
+ *    is best-effort — but starting it is more than the warning does.
+ *
+ * Returns the uninstaller, which removes the SAME handlers it added.
+ */
+declare function installTabAwayFlush(flush: () => void, target?: {
+    document: Document;
+    window: Window;
+}): () => void;
+
+/**
+ * How long the autosave waits, and how it backs off — one set of numbers for
+ * every editor (blueprint step 2.5, Lewis's rule of 2026-09-29: "save a second
+ * after you stop, and say nothing").
+ *
+ * Until this module the two editors each carried their own: the campaign
+ * designer waited ten seconds (`AUTOSAVE_DEBOUNCE_MS`, efficient-admin-portal
+ * `src/components/email/autosaveStatus.ts`), the website page editor ten
+ * (`components/StorefrontDocumentContext.tsx`) and its section editor five
+ * (`lib/editor/autosave-status.ts`). Ten seconds was chosen to keep
+ * whole-document writes rare; what it cost was ten seconds of work that lived
+ * only in memory. A one-second save with a single write in flight at a time
+ * (./engine) is at most one write per second while someone is typing, and it
+ * makes the "not saved yet" window small enough that the editor never has to
+ * mention it.
+ */
+/** Save once nobody has edited for this long. */
+declare const AUTOSAVE_DEBOUNCE_MS = 1000;
+/**
+ * …but never wait longer than this after the first unsaved edit, however
+ * steadily someone types.
+ *
+ * A pure debounce never fires while the typing goes on, so a long sentence
+ * would sit unsaved until the last key — and would pass
+ * {@link AUTOSAVE_UNSAVED_AFTER_MS} on the way and put "Unsaved changes" up
+ * while the connection was fine. This cap keeps it under that threshold on a
+ * healthy connection, which is what makes the rule "the top bar does not change
+ * while you type" true (blueprint 2.6).
+ */
+declare const AUTOSAVE_MAX_WAIT_MS = 3000;
+/**
+ * How long an edit may be off the server before the editor says so.
+ *
+ * Measured from the OLDEST edit not yet saved, not the newest, so a stream of
+ * edits over a failing connection is reported five seconds after the first one
+ * and not held off for as long as the typing goes on.
+ */
+declare const AUTOSAVE_UNSAVED_AFTER_MS = 5000;
+/**
+ * The waits before each retry of a failed save. The last one repeats for as
+ * long as saves keep failing: giving up is how a blip becomes lost work, and a
+ * real outage is a thirty-second retry, not a hammer.
+ *
+ * Carried over from the campaign designer's `AUTOSAVE_RETRY_DELAYS_MS`
+ * (efficient-admin-portal `src/components/email/autosaveRetry.ts`).
+ */
+declare const AUTOSAVE_RETRY_DELAYS_MS: readonly number[];
+/**
+ * The wait before retry number `attempt` (0-based). Past the end of the table
+ * it stays on the last entry, so attempt 99 still waits thirty seconds rather
+ * than reading `undefined` and retrying in a hot loop.
+ */
+declare function autosaveRetryDelay(attempt: number, delays?: readonly number[]): number;
+
+export { AUTOSAVE_DEBOUNCE_MS, AUTOSAVE_MAX_WAIT_MS, AUTOSAVE_RETRY_DELAYS_MS, AUTOSAVE_UNSAVED_AFTER_MS, Autosave, AutosaveOptions, AutosaveSnapshot, SaveIndicator, type UseAutosave, type UseAutosaveOptions, autosaveRetryDelay, installTabAwayFlush, useAutosave };

package/dist/autosave/index.js

@@ -0,0 +1 @@
+import{saveIndicator as e}from"../chunk-H6DDIBQ4.js";export{saveIndicator}from"../chunk-H6DDIBQ4.js";import{useRef as n,useEffect as t,useState as u,useSyncExternalStore as r,useMemo as o}from"react";var l=1e3,s=3e3,i=5e3,a=[2e3,5e3,15e3,3e4];function c(e,n=a){const t=n.length-1;return n[Number.isFinite(e)?Math.min(Math.max(Math.trunc(e),0),t):t]}var d={now:()=>Date.now(),setTimeout:(e,n)=>globalThis.setTimeout(e,n),clearTimeout:e=>globalThis.clearTimeout(e)};function f(e={}){const n=e.clock??d,t=e.debounceMs??1e3,u=e.maxWaitMs??3e3,r=e.unsavedAfterMs??5e3,o=e.retryDelays??a;let l=e.save??(()=>Promise.reject(new Error("autosave used before setSave"))),s=null,i=null,f=null,m=0,h=null,v=0,p=!1,w=!1,g=!1,b=!1,y=!1,T=!1,M=0,P=null,S=null;const D=/* @__PURE__ */new Set;let E=L();function L(){return{pending:null!==s,unsaved:T,failed:p,attempt:v,saved:w,paused:g,stopped:b}}function x(){if(y)return;const e=L();if(!Object.keys(e).every(n=>e[n]===E[n])){E=e;for(const e of[...D])e()}}function j(){null!==P&&n.clearTimeout(P),P=null}function k(e){j(),P=n.setTimeout(()=>{P=null,B()},e)}function F(){const e=n.now(),r=Math.min(m+t,(i??e)+u);k(Math.max(0,r-e))}function N(){if(null!==S&&n.clearTimeout(S),S=null,null===i)return void(T=!1);const e=i+r-n.now();T=e<=0,T||(S=n.setTimeout(()=>{S=null,T=!0,x()},e))}function B(){if(h)return h;if(y||b||!s)return Promise.resolve(null===s);j();const t=s,u=M;return f=null,h=Promise.resolve().then(()=>l(t.value)).then(()=>(u!==M||(h=null,w=!0,p=!1,v=0,s===t?(s=null,i=null):i=f??n.now(),f=null,N(),!s||g||b||y||F(),x()),!0),n=>{if(u!==M)return!1;if(h=null,f=null,b||y)return x(),!1;p=!0;const t=v;return v=t+1,e.onFailure?.(n,t),g||k(c(t,o)),x(),!1}),h}async function I(){for(;;){if(y||b)return null===s;if(!h&&!s)return!0;if(!await(h??B()))return!1}}return{setSave(e){l=e},push(e){if(y)return;const t=n.now();s={value:e},m=t,h&&null===f&&(f=t),null===i&&(i=t,N()),g||b||h||p||F(),x()},flush:I,retryNow:()=>(v=0,I()),pause(){y||g||(g=!0,j(),x())},resume:()=>y?Promise.resolve(null===s):(g=!1,x(),I()),stop(){y||(b=!0,j(),x())},reset(){y||(M++,h=null,j(),s=null,i=null,f=null,v=0,p=!1,w=!1,b=!1,N(),x())},hasPending:()=>null!==s,getSnapshot:()=>E,subscribe:e=>(D.add(e),()=>{D.delete(e)}),dispose(){j(),null!==S&&n.clearTimeout(S),S=null,y=!0}}}function m(e,n={document:document,window:window}){const t=n.document,u=n.window,r=()=>{"hidden"===t.visibilityState&&e()},o=()=>e();return t.addEventListener("visibilitychange",r),u.addEventListener("pagehide",o),()=>{t.removeEventListener("visibilitychange",r),u.removeEventListener("pagehide",o)}}function h(e){const n=e.getSnapshot();n.paused||n.stopped||e.flush()}function v(l){const s=n(l);t(()=>{s.current=l});const[i]=u(()=>f({...l,save:e=>s.current.save(e),onFailure:(e,n)=>s.current.onFailure?.(e,n)})),a=r(i.subscribe,i.getSnapshot,i.getSnapshot);t(()=>m(()=>h(i)),[i]);const c=l.warnBeforeUnload??!0;return t(()=>{if(!c)return;const e=e=>{i.hasPending()&&(e.preventDefault(),e.returnValue="")};return window.addEventListener("beforeunload",e),()=>window.removeEventListener("beforeunload",e)},[i,c]),t(()=>()=>h(i),[i]),o(()=>({state:a,indicator:e(a),push:i.push,flush:i.flush,retryNow:i.retryNow,pause:i.pause,resume:i.resume,stop:i.stop,reset:i.reset,hasPending:i.hasPending}),[i,a])}export{l as AUTOSAVE_DEBOUNCE_MS,s as AUTOSAVE_MAX_WAIT_MS,a as AUTOSAVE_RETRY_DELAYS_MS,i as AUTOSAVE_UNSAVED_AFTER_MS,c as autosaveRetryDelay,f as createAutosave,m as installTabAwayFlush,v as useAutosave};

package/dist/blocks/index.d.ts

@@ -0,0 +1,295 @@
+import { ReactElement, FC, CSSProperties, ReactNode, JSX } from 'react';
+import { P as Permissions, A as AppState } from '../types-_Vayx8ov.js';
+import '../data/index.js';
+import '../types-DziKCwsN.js';
+import '../resolve-DpH8YQOA.js';
+import '../plan-DtNw2VuI.js';
+
+/**
+ * efficient-easel/blocks — how a block is WRITTEN: its config, its fields, the
+ * props its `render` receives and the document it lands in.
+ *
+ * Blueprint default #3 keeps Puck's block writing, so the ~119 blocks both apps
+ * wrote move onto the engine without a line changed. Until 6.1 those blocks were
+ * typed by importing Puck's own types, which kept `@measured/puck` in both apps'
+ * dependencies after nothing ran it any more. These are the same shapes, written
+ * here — Puck 0.20's `Config`, `ComponentConfig`, `Fields`, `Field`,
+ * `CustomField`, `ComponentData`, `Data`, `Slot` and `SlotComponent` — so an app
+ * changes the module it imports them from, and nothing else.
+ *
+ * WHAT IS LEFT OUT, ON PURPOSE:
+ *   - the `ConfigParams` form of `Config<{ components, root, fields }>` and the
+ *     user field-type extension it carries (neither app uses it);
+ *   - everything about Puck's own editor — its store, overrides, plugins and
+ *     history. Those are the engine's now (`efficient-easel/editor`).
+ *
+ * The `puck` prop keeps its name: it is what every block's `render` destructures
+ * (`puck.isEditing`, `puck.renderDropZone`), and renaming it is the block rewrite
+ * default #3 rules out. Its type is `BlockContext`.
+ *
+ * TYPES ONLY — nothing here exists at runtime, so a server component, a test
+ * or the backend's tooling can import it freely.
+ */
+
+type Metadata = {
+    [key: string]: any;
+};
+type DefaultComponentProps = {
+    [key: string]: any;
+};
+type DefaultComponents = Record<string, any>;
+type FieldOption = {
+    label: string;
+    value: string | number | boolean | undefined | null | object;
+};
+type FieldOptions = Array<FieldOption> | ReadonlyArray<FieldOption>;
+type BaseField = {
+    label?: string;
+    labelIcon?: ReactElement;
+    metadata?: Metadata;
+    visible?: boolean;
+};
+type TextField = BaseField & {
+    type: 'text';
+    placeholder?: string;
+    contentEditable?: boolean;
+};
+type NumberField = BaseField & {
+    type: 'number';
+    placeholder?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+};
+type TextareaField = BaseField & {
+    type: 'textarea';
+    placeholder?: string;
+    contentEditable?: boolean;
+};
+type SelectField = BaseField & {
+    type: 'select';
+    options: FieldOptions;
+};
+type RadioField = BaseField & {
+    type: 'radio';
+    options: FieldOptions;
+};
+type AnyRecord = {
+    [key: string]: any;
+};
+type ArrayField<Props extends AnyRecord[] = AnyRecord[]> = BaseField & {
+    type: 'array';
+    arrayFields: {
+        [SubPropName in keyof Props[0]]: Field<Props[0][SubPropName]>;
+    };
+    defaultItemProps?: Props[0];
+    getItemSummary?: (item: Props[0], index?: number) => string;
+    max?: number;
+    min?: number;
+};
+type ObjectField<Props = AnyRecord> = BaseField & {
+    type: 'object';
+    objectFields: {
+        [SubPropName in keyof Props]: Field<Props[SubPropName]>;
+    };
+};
+/** A custom field's drawing: called with Puck's six props, as both apps wrote them. */
+type CustomFieldRender<Value> = (props: {
+    field: CustomField<Value>;
+    name: string;
+    id: string;
+    value: Value;
+    onChange: (value: Value) => void;
+    readOnly?: boolean;
+}) => ReactElement;
+type CustomField<Value> = BaseField & {
+    type: 'custom';
+    render: CustomFieldRender<Value>;
+    contentEditable?: boolean;
+};
+type SlotField = BaseField & {
+    type: 'slot';
+    allow?: string[];
+    disallow?: string[];
+};
+/**
+ * Puck's `external` field: a value picked from a list the app fetches. Neither
+ * app has one and the Inspector does not draw it — it is in the union only so
+ * the union is Puck's, and a function that takes `Fields` takes Puck's too.
+ */
+type ExternalField<Props = AnyRecord> = BaseField & {
+    type: 'external';
+    placeholder?: string;
+    fetchList: (params: {
+        query: string;
+        filters: Record<string, unknown>;
+    }) => Promise<unknown[] | null>;
+    mapProp?: (value: any) => Props;
+    mapRow?: (value: any) => Record<string, string | number | ReactElement>;
+    getItemSummary?: (item: NonNullable<Props>, index?: number) => string;
+    showSearch?: boolean;
+    renderFooter?: (props: {
+        items: any[];
+    }) => ReactElement;
+    initialQuery?: string;
+    filterFields?: Record<string, Field>;
+    initialFilters?: Record<string, any>;
+};
+type Adaptor<AdaptorParams = object, TableShape extends AnyRecord = AnyRecord, PropShape = TableShape> = {
+    name: string;
+    fetchList: (adaptorParams?: AdaptorParams) => Promise<TableShape[] | null>;
+    mapProp?: (value: TableShape) => PropShape;
+};
+type ExternalFieldWithAdaptor<Props = AnyRecord> = BaseField & {
+    type: 'external';
+    placeholder?: string;
+    adaptor: Adaptor<any, any, Props>;
+    adaptorParams?: object;
+    getItemSummary: (item: NonNullable<Props>, index?: number) => string;
+};
+type Field<ValueType = any> = TextField | NumberField | TextareaField | SelectField | RadioField | ArrayField<ValueType extends AnyRecord[] ? ValueType : never> | ObjectField<ValueType> | ExternalField<ValueType> | ExternalFieldWithAdaptor<ValueType> | CustomField<ValueType> | SlotField;
+/** A block's fields, one per prop (`editMode` is the editor's, never a field). */
+type Fields<ComponentProps extends DefaultComponentProps = DefaultComponentProps> = {
+    [PropName in keyof Omit<ComponentProps, 'editMode'>]: Field<ComponentProps[PropName]>;
+};
+type BaseData<Props extends AnyRecord = AnyRecord> = {
+    readOnly?: Partial<Record<keyof Props, boolean>>;
+};
+type WithId<Props> = Props & {
+    id: string;
+};
+type ComponentData<Props extends DefaultComponentProps = DefaultComponentProps, Name = string, Components extends Record<string, DefaultComponentProps> = Record<string, DefaultComponentProps>> = {
+    type: Name;
+    props: WithDeepSlots<WithId<Props>, Content<Components>>;
+} & BaseData<Props>;
+type ComponentDataOptionalId<Props extends DefaultComponentProps = DefaultComponentProps, Name = string> = {
+    type: Name;
+    props: Props & {
+        id?: string;
+    };
+} & BaseData<Props>;
+type ComponentDataMap<Components extends DefaultComponents = DefaultComponents> = {
+    [K in keyof Components]: ComponentData<Components[K], K extends string ? K : never, Components>;
+}[keyof Components];
+/** A list of blocks: the top level, or a slot's. */
+type Content<PropsMap extends {
+    [key: string]: DefaultComponentProps;
+} = {
+    [key: string]: DefaultComponentProps;
+}> = ComponentDataMap<PropsMap>[];
+/** A slot prop, as STORED: the blocks in it. Its `render` receives a `SlotComponent` instead. */
+type Slot<Props extends {
+    [key: string]: DefaultComponentProps;
+} = {
+    [key: string]: DefaultComponentProps;
+}> = {
+    [K in keyof Props]: ComponentDataOptionalId<Props[K], K extends string ? K : never>;
+}[keyof Props][];
+type BuiltinTypes = Date | RegExp | Error | Function | symbol | null | undefined;
+/** `T` with every `Slot` in it, however deep, replaced by `SlotType`. */
+type WithDeepSlots<T, SlotType = T> = T extends Slot ? SlotType : T extends (infer U)[] ? Array<WithDeepSlots<U, SlotType>> : T extends BuiltinTypes ? T : T extends object ? {
+    [K in keyof T]: WithDeepSlots<T[K], SlotType>;
+} : T;
+type WithSlotProps<Target extends AnyRecord, Components extends DefaultComponents = DefaultComponents, SlotType extends Content<Components> = Content<Components>> = WithDeepSlots<Target, SlotType>;
+type DefaultRootFieldProps = {
+    title?: string;
+};
+type RootDataWithProps<Props extends DefaultComponentProps = DefaultRootFieldProps> = BaseData<Props> & {
+    props: Props;
+};
+type RootDataWithoutProps<Props extends DefaultComponentProps = DefaultRootFieldProps> = Props;
+/** The root: its props under `props`, or (the older format) held directly. */
+type RootData<Props extends DefaultComponentProps = DefaultRootFieldProps> = Partial<RootDataWithProps<AsFieldProps<Props>>> & Partial<RootDataWithoutProps<Props>>;
+/** A saved campaign or page — Puck 0.20's document, which nothing has migrated off. */
+type Data<Components extends DefaultComponents = DefaultComponents, RootProps extends DefaultComponentProps = DefaultRootFieldProps> = {
+    root: WithDeepSlots<RootData<RootProps>, Content<Components>>;
+    content: Content<Components>;
+    zones?: Record<string, Content<Components>>;
+};
+type DragAxis = 'dynamic' | 'y' | 'x';
+type DropZoneProps = {
+    zone: string;
+    allow?: string[];
+    disallow?: string[];
+    style?: CSSProperties;
+    minEmptyHeight?: number;
+    className?: string;
+    collisionAxis?: DragAxis;
+};
+/** A slot, as a block's `render` receives it: draw it with `<Content />`. */
+type SlotComponent = (props?: Omit<DropZoneProps, 'zone'>) => ReactNode;
+/** The `puck` prop every block's `render` receives. */
+type BlockContext = {
+    renderDropZone: FC<DropZoneProps>;
+    metadata: Metadata;
+    isEditing: boolean;
+    dragRef: ((element: Element | null) => void) | null;
+};
+type WithBlockProps<Props> = Props & {
+    puck: BlockContext;
+    editMode?: boolean;
+};
+type WithChildren<Props> = Props & {
+    children: ReactNode;
+};
+type AsFieldProps<Props> = Omit<Props, 'children' | 'puck' | 'editMode'>;
+/** A block's `render`: its own props with slots as `SlotComponent`s, its id, and `puck`. */
+type BlockComponent<Props> = (props: WithId<WithBlockProps<{
+    [K in keyof Props]: WithDeepSlots<Props[K], SlotComponent>;
+}>>) => JSX.Element;
+type ResolveDataTrigger = 'insert' | 'replace' | 'load' | 'force';
+type Changed<FieldProps> = Partial<Record<keyof FieldProps, boolean> & {
+    id: string;
+}>;
+type WithPartialProps<T, Props extends DefaultComponentProps> = Omit<T, 'props'> & {
+    props?: Partial<Props>;
+};
+type ComponentConfig<RenderProps extends DefaultComponentProps = DefaultComponentProps, FieldProps extends DefaultComponentProps = RenderProps, DataShape = Omit<ComponentData<FieldProps>, 'type'>> = {
+    render: BlockComponent<RenderProps>;
+    label?: string;
+    defaultProps?: FieldProps;
+    fields?: Fields<FieldProps>;
+    permissions?: Partial<Permissions>;
+    inline?: boolean;
+    resolveFields?: (data: DataShape, params: {
+        changed: Changed<FieldProps>;
+        fields: Fields<FieldProps>;
+        lastFields: Fields<FieldProps>;
+        lastData: DataShape | null;
+        appState: AppState;
+        parent: ComponentData | null;
+    }) => Promise<Fields<FieldProps>> | Fields<FieldProps>;
+    resolveData?: (data: DataShape, params: {
+        changed: Changed<FieldProps>;
+        lastData: DataShape | null;
+        metadata: Metadata;
+        trigger: ResolveDataTrigger;
+    }) => Promise<WithPartialProps<DataShape, FieldProps>> | WithPartialProps<DataShape, FieldProps>;
+    resolvePermissions?: (data: DataShape, params: {
+        changed: Changed<FieldProps>;
+        lastPermissions: Partial<Permissions>;
+        permissions: Partial<Permissions>;
+        appState: AppState;
+        lastData: DataShape | null;
+    }) => Promise<Partial<Permissions>> | Partial<Permissions>;
+    metadata?: Metadata;
+};
+type RootConfig<RootProps extends DefaultComponentProps = DefaultComponentProps> = Partial<ComponentConfig<WithChildren<RootProps>, AsFieldProps<RootProps>, RootData<AsFieldProps<RootProps>>>>;
+type Category<ComponentName> = {
+    components?: ComponentName[];
+    title?: string;
+    visible?: boolean;
+    defaultExpanded?: boolean;
+};
+/** A whole editor's blocks: `components` by type, the `root`, and the Add panel's `categories`. */
+type Config<Props extends DefaultComponents = DefaultComponents, RootProps extends DefaultComponentProps = any, CategoryName extends string = string> = {
+    categories?: Record<CategoryName, Category<keyof Props>> & {
+        other?: Category<keyof Props>;
+    };
+    components: {
+        [ComponentName in keyof Props]: ComponentConfig<Props[ComponentName], Props[ComponentName]>;
+    };
+    root?: RootConfig<RootProps>;
+};
+
+export { type Adaptor, AppState, type ArrayField, type AsFieldProps, type BaseData, type BaseField, type BlockComponent, type BlockContext, type Category, type ComponentConfig, type ComponentData, type ComponentDataMap, type ComponentDataOptionalId, type Config, type Content, type CustomField, type CustomFieldRender, type Data, type DefaultComponentProps, type DefaultComponents, type DefaultRootFieldProps, type DragAxis, type DropZoneProps, type ExternalField, type ExternalFieldWithAdaptor, type Field, type FieldOption, type FieldOptions, type Fields, type Metadata, type NumberField, type ObjectField, Permissions, type RadioField, type ResolveDataTrigger, type RootConfig, type RootData, type RootDataWithProps, type RootDataWithoutProps, type SelectField, type Slot, type SlotComponent, type SlotField, type TextField, type TextareaField, type WithBlockProps, type WithChildren, type WithDeepSlots, type WithId, type WithPartialProps, type WithSlotProps };

package/dist/buckets-1vRlQceY.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The settings tab words, in the owner's order (2026-09-11): Content, Style,
+ * Layout, Animation. A panel shows only the tabs that hold a setting — an empty
+ * tab is hidden, never drawn (same day).
+ *
+ * The website editor wrote this list in `efficient-shop/lib/puck/field-groups.ts`
+ * (`BUCKETS`). From 0.43.0 it lives here, so the campaign editor spells its panel
+ * the same four words in the same order instead of keeping a second list.
+ */
+declare const SETTINGS_BUCKETS: readonly ["Content", "Style", "Layout", "Animation"];
+type SettingsBucket = (typeof SETTINGS_BUCKETS)[number];
+
+export { type SettingsBucket as S, SETTINGS_BUCKETS as a };

package/dist/canvas/index.d.ts

@@ -0,0 +1,194 @@
+import { RefObject } from 'react';
+import { C as CanvasTarget, W as WatchOptions } from '../watch-DmasQA61.js';
+export { B as BLOCK_SELECTOR, a as CANVAS_SELECTOR, i as isFrameReady, w as watchCanvasFrame } from '../watch-DmasQA61.js';
+
+/**
+ * The small facts every canvas surface needs, written once — pure DOM, no
+ * React, nothing run at import.
+ *
+ * Each answers a question both editors used to answer for themselves, and
+ * sometimes differently (the blueprint's §2 rows 6–10):
+ *
+ *   isTypingTarget   is this keystroke someone TYPING, so a shortcut must stay out?
+ *   nodeIdAt         which block did this pointer event land on?
+ *   frameScale       how much is the canvas frame scaled (a phone view drawn small)?
+ *   frameRectToHost  where is a box measured INSIDE the frame, on the host page?
+ *   fitCanvas        how wide is the canvas, and at what scale does it fit?
+ *   canvas styles    a stylesheet that lives in the canvas document ONLY.
+ */
+/**
+ * Is the event's target somewhere a person TYPES — a text field, a textarea, a
+ * native select, an editable region? A shortcut (undo, delete, copy style) must
+ * not fire there: the key belongs to the field. Duck-typed rather than
+ * `instanceof`, because a canvas element belongs to the frame's own realm and
+ * is not an instance of the host's `HTMLElement`.
+ */
+declare function isTypingTarget(target: EventTarget | null): boolean;
+/** The attribute on every block the canvas draws (Puck 0.20's name, kept). */
+declare const BLOCK_ATTRIBUTE = "data-puck-component";
+/**
+ * The id of the block a pointer event landed on: the NEAREST ancestor (or the
+ * target itself) carrying `attribute`. `null` on bare canvas.
+ */
+declare function nodeIdAt(target: EventTarget | null, attribute?: string): string | null;
+interface Box {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * How much the frame is drawn scaled on the host page: its on-screen width over
+ * its layout width. The storefront draws tablet and phone at their real widths
+ * and scales the frame down to fit the pane; the campaign designer does not
+ * scale. 1 when the frame has no layout width yet.
+ */
+declare function frameScale(frame: HTMLElement): number;
+/**
+ * A box measured INSIDE the frame (an element's getBoundingClientRect in the
+ * frame's own viewport) as a box on the HOST page, relative to `origin` — the
+ * overlay layer the box will be drawn in — and through the frame's scale. The
+ * scale is the term both apps' own conversions left out on a scaled view.
+ */
+declare function frameRectToHost(frame: HTMLElement, box: Box, origin?: Element | null): Box;
+/**
+ * How much `el` is drawn scaled on screen: its on-screen width over its layout
+ * width. 1 when it is not scaled, or has no layout width yet. An overlay that
+ * shares a scaled ancestor with the frame (the storefront scales the whole
+ * device box, frame and overlay together) is scaled too, and its own CSS pixels
+ * are then that much smaller or larger than the screen's.
+ */
+declare function elementScale(el: Element): number;
+/**
+ * A box measured inside the frame as a box in `layer`'s OWN CSS coordinates —
+ * what an absolutely positioned child of `layer` is placed with. The same as
+ * `frameRectToHost` when the layer is not scaled; when it shares a scaled
+ * ancestor with the frame, every screen distance is divided back into the
+ * layer's pixels, or everything it draws lands the scale's factor away.
+ */
+declare function frameRectToLayer(frame: HTMLElement, box: Box, layer: Element): Box;
+/** A pointer position on the HOST page (clientX/clientY there) in `layer`'s own CSS coordinates. */
+declare function clientPointToLayer(layer: Element, x: number, y: number): {
+    x: number;
+    y: number;
+};
+/** A pointer position inside the frame (clientX/clientY there) on the host page. */
+declare function framePointToHost(frame: HTMLElement, x: number, y: number, origin?: Element | null): {
+    x: number;
+    y: number;
+};
+interface CanvasFit {
+    /** The canvas's layout width — the device's, or the pane's for a fluid view. */
+    width: number;
+    /** The scale that fits `width` into the pane, capped at `maxScale`. */
+    scale: number;
+    /** What the canvas occupies on screen: `width * scale`. */
+    shownWidth: number;
+}
+/**
+ * The canvas width and scale for a pane `available` px wide. A device with no
+ * width of its own (desktop, an email's inbox view) takes the pane's width at
+ * scale 1; a device width that does not fit is scaled down to fit, and one that
+ * does is scaled up no further than `maxScale` (the storefront allows 2; pass 1
+ * for "never enlarge").
+ */
+declare function fitCanvas({ available, width, maxScale, }: {
+    available: number;
+    width?: number | null;
+    maxScale?: number;
+}): CanvasFit;
+/**
+ * Say which CSP nonce the stylesheets this module puts in `doc` must carry —
+ * for a host whose policy allows inline styles by nonce (`style-src
+ * 'nonce-…'`), where a `<style>` without it is refused. Every sheet
+ * `upsertCanvasStyle` / `useCanvasStyle` creates in `doc` afterwards wears it.
+ *
+ * `CanvasFrame` (`efficient-easel/editor`) calls this with its `nonce` prop as
+ * it builds the frame, so a host says it once; a host that builds its own
+ * frame calls it itself. `undefined` (or `''`) forgets it.
+ */
+declare function setCanvasNonce(doc: Document, nonce: string | undefined): void;
+/**
+ * Put `css` in the canvas document's `<head>` under `key`, replacing what that
+ * key held before. It lives in the canvas ONLY — not mirrored from the host
+ * head, so it cannot leak into the host page, and not dependent on anyone
+ * noticing a change to it. Writes nothing when the text is already current.
+ * A new sheet carries the document's nonce, when it was given one
+ * ({@link setCanvasNonce}).
+ */
+declare function upsertCanvasStyle(doc: Document, key: string, css: string): HTMLStyleElement;
+/** Take `key`'s stylesheet out of the canvas document, if it is there. */
+declare function removeCanvasStyle(doc: Document, key: string): void;
+
+/**
+ * efficient-easel/canvas — the one way into the editor's canvas frame.
+ *
+ * Step 2.1 of the engine that replaces Puck (blueprint "Puck From The Ground Up
+ * For Efficient Editor", 2026-09-29). Both editors draw their canvas in an
+ * iframe — Puck's `#preview-frame` today, the engine's own same-origin
+ * CanvasFrame once the editors leave Puck — and each reached into it its own
+ * way: eight polling loops with eight intervals, stylesheets pushed into the
+ * host `<head>` hoping to be mirrored, key listeners re-bound on a one-second
+ * timer, coordinate conversions that forgot the frame's scale. This module is
+ * what they all use instead:
+ *
+ *   useCanvasFrame(rootRef, options)   the frame, its document and window — or null
+ *   useCanvasEvent(canvas, type, fn)   a listener in the canvas that follows a swap
+ *   useCanvasStyle(canvas, key, css)   a stylesheet in the canvas document only
+ *   useCanvasLayout(canvas)            a number that changes whenever anything that
+ *                                      moves the canvas does — re-measure on it
+ *
+ * plus the pure pieces in ./dom (the typing guard, the block under a pointer,
+ * frame→host geometry with scale, the canvas fit) and ./watch (the watcher the
+ * hook wraps, usable without React).
+ *
+ * LEAF DISCIPLINE: React is the only import, nothing touches a browser global
+ * at import time, and there is no `'use client'` — the host's editor chrome is
+ * already the client boundary (tests/canvas-leaf-safety.test.ts).
+ */
+
+/**
+ * The canvas frame under `rootRef` — `{ frame, document, window }` once it is
+ * ready, `null` before then and after it goes. Re-renders only when the frame
+ * or its document actually changes (a Refresh remount, a document swap).
+ */
+declare function useCanvasFrame(rootRef: RefObject<Element | null>, { selector, readySelector }?: WatchOptions): CanvasTarget | null;
+type CanvasEventMap = DocumentEventMap & WindowEventMap;
+/**
+ * Listen for `type` in the canvas — on its document (default) or its window.
+ * Re-binds when the canvas document is replaced, and always calls the LATEST
+ * `handler`, so passing an inline function never re-binds (the storefront's
+ * context menu re-bound on every render because its handler's identity did).
+ */
+declare function useCanvasEvent<K extends keyof CanvasEventMap>(canvas: CanvasTarget | null, type: K, handler: (event: CanvasEventMap[K]) => void, { on, capture }?: {
+    on?: 'document' | 'window';
+    capture?: boolean;
+}): void;
+/**
+ * Keep `css` in the canvas document's `<head>` under `key` while mounted, put it
+ * back in a replacement document, and take it out on unmount. An empty string
+ * removes it. Nothing is written to the host page.
+ *
+ * "Keep" means it comes back if something else takes it out. Puck's AutoFrame
+ * empties the frame's `<head>` once, when the host styles it mirrors have
+ * loaded (`doc.head.innerHTML = ""` in CopyHostStyles), and nothing orders that
+ * after the canvas is published — so a sheet written first would silently go.
+ * The observer watches the head's children only, which change about as often
+ * as a stylesheet is added: never per keystroke.
+ */
+declare function useCanvasStyle(canvas: CanvasTarget | null, key: string, css: string): void;
+/**
+ * A number that changes whenever the canvas may have MOVED — its document
+ * scrolled or resized, its content resized, a block added, removed or moved in
+ * it, the host page scrolled or resized, or the canvas itself replaced — plus
+ * two settle passes after each new canvas (fonts and images land after the
+ * first paint). An overlay re-measures when it
+ * changes, instead of each surface wiring its own listeners and timers.
+ *
+ * Coalesced to one change per animation frame.
+ */
+declare function useCanvasLayout(canvas: CanvasTarget | null, { settle }?: {
+    settle?: readonly number[];
+}): number;
+
+export { BLOCK_ATTRIBUTE, type Box, type CanvasFit, CanvasTarget, WatchOptions, clientPointToLayer, elementScale, fitCanvas, framePointToHost, frameRectToHost, frameRectToLayer, frameScale, isTypingTarget, nodeIdAt, removeCanvasStyle, setCanvasNonce, upsertCanvasStyle, useCanvasEvent, useCanvasFrame, useCanvasLayout, useCanvasStyle };

package/dist/canvas/index.js

@@ -0,0 +1 @@
+export{BLOCK_SELECTOR,CANVAS_SELECTOR,isFrameReady,useCanvasEvent,useCanvasFrame,useCanvasLayout,useCanvasStyle,watchCanvasFrame}from"../chunk-MCLBHENY.js";export{BLOCK_ATTRIBUTE,clientPointToLayer,elementScale,fitCanvas,framePointToHost,frameRectToHost,frameRectToLayer,frameScale,isTypingTarget,nodeIdAt,removeCanvasStyle,setCanvasNonce,upsertCanvasStyle}from"../chunk-ZNCEOSXO.js";