@hachej/boring-ui-kit 0.1.111 → 0.2.1

package/dist/canvas.js

@@ -0,0 +1,264 @@
+import { applyCanvasEdits, canvasMediaType, parseCanvasDocument, parseCanvasEdits } from './canvas-document.js';
+import { parseCanvasRecords } from './canvas-records.js';
+import { loadSnapshot } from '@tldraw/editor';
+import { Store } from '@tldraw/store';
+import { randomUUID } from '@hachej/boring-files/platform';
+import { createTextBuffer, freeze, sameBase } from './text-buffer.js';
+export { canvasMediaType } from './canvas-document.js';
+function documentText(document) {
+    return JSON.stringify({ schema: document.schema, store: document.store });
+}
+function documentFrom(value, owner) {
+    const records = parseCanvasRecords(value, owner.schema);
+    const scratch = new Store({ schema: owner.schema, props: owner.props });
+    try {
+        scratch.loadStoreSnapshot(records);
+        return parseCanvasDocument(scratch.getStoreSnapshot('document'), owner.schema);
+    }
+    finally {
+        scratch.dispose();
+    }
+}
+/** Revision-checked document publication over a borrowed native tldraw store. */
+export function createCanvasController(options) {
+    const { store } = options;
+    let loading = false, disposed = false, adopting = false;
+    let proposals = [];
+    let problem = null;
+    const readText = (snapshot) => {
+        if (snapshot.mediaType !== canvasMediaType)
+            throw new TypeError('Expected a tldraw document media type');
+        const input = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(snapshot.bytes));
+        return documentText(documentFrom(parseCanvasDocument(input, store.schema), store));
+    };
+    const emptyText = documentText(documentFrom({ schema: store.schema.serialize(), store: {} }, store));
+    const initialText = options.source.kind === 'saved' ? readText(options.source.snapshot)
+        : documentText(documentFrom(store.getStoreSnapshot('document'), store));
+    const existing = store.getStoreSnapshot('document');
+    if (options.source.kind === 'saved' && Object.keys(existing.store).length > 0
+        && documentText(documentFrom(existing, store)) !== initialText)
+        throw new Error('Borrowed canvas store differs from the saved source; select an empty store or explicitly discard before mounting');
+    let captured = initialText;
+    const replaceText = (text) => {
+        const input = JSON.parse(text);
+        const document = documentFrom(input, store);
+        loading = true;
+        try {
+            loadSnapshot(store, { document });
+            captured = documentText(document);
+            problem = null;
+        }
+        finally {
+            loading = false;
+        }
+    };
+    const { drafts, ...bufferOptions } = options;
+    const buffer = createTextBuffer({ ...bufferOptions, ...(drafts ? { drafts: { ...drafts, format: 'canvas/v1', validateText: (text) => { documentFrom(parseCanvasDocument(JSON.parse(text), store.schema), store); } } } : {}), source: options.source.kind === 'new' ? { ...options.source, text: initialText } : options.source,
+        mediaType: canvasMediaType, emptyText, readText, replaceText, sync: () => capture() });
+    replaceText(initialText);
+    function snapshot() {
+        const { text: _text, ...state } = buffer.getSnapshot();
+        return freeze({ ...state, document: structuredClone(store.getStoreSnapshot('document')), problem, proposals });
+    }
+    let state = snapshot();
+    const listeners = new Set();
+    const notify = () => {
+        state = snapshot();
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch (error) {
+                queueMicrotask(() => { if (options.onListenerError)
+                    options.onListenerError(error);
+                else
+                    throw error; });
+            }
+        }
+    };
+    const unsubscribe = buffer.subscribe(notify);
+    const capture = () => {
+        if (disposed || loading)
+            return;
+        const document = store.getStoreSnapshot('document'), text = documentText(document);
+        if (text === captured)
+            return;
+        try {
+            parseCanvasDocument(document, store.schema);
+            problem = null;
+        }
+        catch (error) {
+            problem = error instanceof Error ? error.message : 'Canvas document is invalid';
+        }
+        captured = text;
+        buffer.observe(text);
+    };
+    const cleanup = Object.values(store.schema.types).filter(type => type.scope === 'document').flatMap(type => [
+        store.sideEffects.registerAfterCreateHandler(type.typeName, capture),
+        store.sideEffects.registerAfterChangeHandler(type.typeName, capture),
+        store.sideEffects.registerAfterDeleteHandler(type.typeName, capture),
+    ]);
+    cleanup.push(store.listen(capture, { scope: 'document', source: 'all' }));
+    const selected = (value) => {
+        const current = buffer.selection().target, supplied = value.target;
+        return current.instanceId === supplied.instanceId && current.epoch === supplied.epoch
+            && current.subject.scopeId === supplied.subject.scopeId && current.subject.bufferVersion === supplied.subject.bufferVersion
+            && sameBase(current.subject.base, supplied.subject.base);
+    };
+    const conflict = () => ({ kind: 'conflict', current: state.base.kind === 'revision' ? [state.base.target] : [], reason: 'Proposal base changed or the proposal was already adopted' });
+    function propose(base, input, summary = '', command) {
+        const expected = structuredClone(base);
+        capture();
+        if (disposed)
+            return { kind: 'unavailable', reason: 'Viewer is disposed' };
+        if (loading || adopting)
+            return { kind: 'unavailable', reason: 'Canvas document is being updated' };
+        if (state.readOnly)
+            return { kind: 'denied', reason: 'Viewer is read-only' };
+        if (problem)
+            return { kind: 'denied', reason: problem };
+        if (!selected(expected))
+            return { kind: 'stale', reason: 'Proposal target has changed' };
+        if (typeof summary !== 'string')
+            throw new TypeError('Proposal summary must be text');
+        const before = structuredClone(state.document), edits = parseCanvasEdits(input, store.schema);
+        const result = applyCanvasEdits(before, edits, store.schema);
+        if (result.kind === 'rejected')
+            return { kind: 'denied', reason: result.reason };
+        capture();
+        if (disposed)
+            return { kind: 'unavailable', reason: 'Viewer is disposed' };
+        if (command?.signal?.aborted)
+            return { kind: 'denied', reason: 'Command was cancelled' };
+        if (command && command.expiresAt <= Date.now())
+            return { kind: 'stale', reason: 'Command expired' };
+        if (!selected(expected))
+            return { kind: 'stale', reason: 'Proposal target changed during validation' };
+        const proposal = freeze({ id: randomUUID(), base: expected, before, after: result.document, edits, summary, adopted: false });
+        proposals = [...proposals, proposal];
+        notify();
+        return { kind: 'proposed', proposalId: proposal.id, base: proposal.base.target };
+    }
+    function accept(proposalId) {
+        capture();
+        if (disposed)
+            return Promise.resolve({ kind: 'unavailable', reason: 'Viewer is disposed' });
+        if (loading || adopting)
+            return Promise.resolve({ kind: 'unavailable', reason: 'Canvas document is being updated' });
+        if (state.readOnly)
+            return Promise.resolve({ kind: 'denied', reason: 'Viewer is read-only' });
+        if (problem)
+            return Promise.resolve({ kind: 'denied', reason: problem });
+        const pending = state.save.kind === 'pending' ? state.save.operationId
+            : state.save.kind === 'settled' && state.save.result.kind === 'unknown' ? state.save.result.operationId : undefined;
+        if (pending !== undefined)
+            return Promise.resolve({ kind: 'unknown', operationId: pending, reason: 'Reconcile or await the earlier save before accepting a proposal' });
+        const proposal = proposals.find(value => value.id === proposalId);
+        if (!proposal || proposal.adopted || !selected(proposal.base))
+            return Promise.resolve(conflict());
+        adopting = true;
+        try {
+            proposals = proposals.map(value => value.id === proposal.id ? freeze({ ...value, adopted: true }) : value);
+            loading = true;
+            try {
+                loadSnapshot(store, { document: structuredClone(proposal.after) });
+            }
+            finally {
+                loading = false;
+            }
+            capture();
+            if (state.proposals !== proposals)
+                notify();
+            capture();
+            if (disposed)
+                return Promise.resolve({ kind: 'unavailable', reason: 'Viewer is disposed' });
+            if (problem)
+                return Promise.resolve({ kind: 'denied', reason: problem });
+            if (documentText(store.getStoreSnapshot('document')) !== documentText(proposal.after))
+                return Promise.resolve(conflict());
+            return buffer.flush(buffer.selection());
+        }
+        finally {
+            adopting = false;
+        }
+    }
+    function commandInput(value) {
+        if (!value || typeof value !== 'object' || !('expiresAt' in value) || typeof value.expiresAt !== 'number' || !Number.isSafeInteger(value.expiresAt))
+            throw new TypeError('Command expiry is required');
+        return { expiresAt: value.expiresAt };
+    }
+    function proposalInput(value) {
+        const expiry = commandInput(value);
+        if (!value || typeof value !== 'object' || !('edits' in value) || !('summary' in value) || typeof value.summary !== 'string')
+            throw new TypeError('Expected edits and summary');
+        return { ...expiry, edits: parseCanvasEdits(value.edits, store.schema), summary: value.summary };
+    }
+    const tools = {
+        inspect: {
+            name: 'inspect_canvas_buffer', input: { jsonSchema: { type: 'object', properties: { expiresAt: { type: 'integer' } }, required: ['expiresAt'] }, parse: commandInput },
+            invoke: async (target, input, signal) => {
+                const base = structuredClone({ target }), expiry = commandInput(input);
+                capture();
+                if (disposed || loading)
+                    return { kind: 'unavailable', reason: 'Canvas document is unavailable' };
+                if (signal?.aborted)
+                    return { kind: 'denied', reason: 'Command was cancelled' };
+                if (expiry.expiresAt <= Date.now() || !selected(base))
+                    return { kind: 'stale', reason: 'Command expired or its target changed' };
+                if (problem)
+                    return { kind: 'unavailable', reason: problem };
+                return { kind: 'applied', value: freeze({ selection: buffer.selection(), document: structuredClone(state.document), dirty: state.dirty }) };
+            },
+        },
+        propose: {
+            name: 'propose_canvas_edits', input: {
+                jsonSchema: { type: 'object', properties: { expiresAt: { type: 'integer' }, summary: { type: 'string' }, edits: { type: 'array', minItems: 1, items: { oneOf: [
+                                    { type: 'object', properties: { kind: { enum: ['create', 'update'] }, record: { type: 'object', description: 'Complete native TLShape or TLBinding record validated by the selected schema' } }, required: ['kind', 'record'], additionalProperties: false },
+                                    { type: 'object', properties: { kind: { const: 'remove' }, id: { type: 'string' } }, required: ['kind', 'id'], additionalProperties: false },
+                                ] } } }, required: ['expiresAt', 'summary', 'edits'] }, parse: proposalInput,
+            },
+            invoke: async (target, input, signal) => {
+                const base = structuredClone({ target }), parsed = proposalInput(input);
+                if (signal?.aborted)
+                    return { kind: 'denied', reason: 'Command was cancelled' };
+                if (parsed.expiresAt <= Date.now())
+                    return { kind: 'stale', reason: 'Command expired' };
+                return propose(base, parsed.edits, parsed.summary, { expiresAt: parsed.expiresAt, ...(signal ? { signal } : {}) });
+            },
+        },
+    };
+    return {
+        store,
+        getSnapshot: () => state,
+        subscribe: (listener) => { if (disposed)
+            return () => { }; listeners.add(listener); return () => { listeners.delete(listener); }; },
+        actions: {
+            selection: () => { capture(); if (problem)
+                throw new Error(problem); return buffer.selection(); },
+            refresh: () => { capture(); return buffer.refresh(false); },
+            discardToRemote: () => { capture(); return buffer.refresh(true); },
+            reconcile: buffer.reconcile, abandon: buffer.abandon,
+            checkDrafts: buffer.checkDrafts, checkpointDraft: buffer.checkpointDraft, restoreDraft: buffer.restoreDraft, discardDraft: buffer.discardDraft,
+            propose: (base, edits, summary) => propose(base, edits, summary), accept,
+            reject: (proposalId) => { if (!disposed) {
+                proposals = proposals.filter(value => value.id !== proposalId);
+                notify();
+            } },
+        },
+        tools: Object.freeze(tools),
+        flush: (selection, signal) => {
+            capture();
+            return problem ? Promise.resolve({ kind: 'denied', reason: problem }) : buffer.flush(selection, signal);
+        },
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const remove of cleanup)
+                remove();
+            buffer.dispose();
+            unsubscribe();
+            listeners.clear();
+        },
+    };
+}

package/dist/contracts.d.ts

@@ -0,0 +1,125 @@
+/** Headless presentation contracts; no Pi, files, agent or React imports.
+ * Services are closed over by the host. An interface does not install code or
+ * confer authority, and a feature preserves its concrete controller type.
+ */
+export interface ValueSchema<Value> {
+    readonly jsonSchema: Readonly<Record<string, unknown>>;
+    readonly parse: (value: unknown) => Value;
+}
+export interface ViewerDescriptor {
+    readonly kind: string;
+    readonly version: number;
+    readonly title?: string;
+}
+export interface ViewerController<State, Actions, Tools = unknown> {
+    /** Pure cached snapshot. Without a change, return the same value/object.
+     * Do not mutate an already published snapshot or perform I/O while reading.
+     */
+    readonly getSnapshot: () => State;
+    /** Synchronous subscription and unsubscription. Change notification occurs
+     * after snapshot publication. This callback is not an async execution queue.
+     */
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly actions: Actions;
+    readonly tools: Tools;
+    /** Explicit owner teardown can be asynchronous. Await/handle its result.
+     * Releasing this controller must not dispose a borrowed provider or task.
+     * React unsubscription stays synchronous; owner teardown is a separate step.
+     */
+    readonly dispose: () => void | Promise<void>;
+}
+/** Preserve the whole concrete controller, including flush, custom methods,
+ * server-rendering snapshots and other host extensions. Do not reconstruct a
+ * base controller from State/Actions/Tools and silently erase its capabilities.
+ */
+export interface ViewerFeature<Descriptor extends ViewerDescriptor, Controller extends ViewerController<unknown, unknown, unknown>> {
+    readonly kind: Descriptor['kind'];
+    readonly version: Descriptor['version'];
+    readonly descriptor: ValueSchema<Descriptor>;
+    readonly createController: (descriptor: Descriptor) => Controller;
+}
+export type ViewerRenderer<Controller, Rendered> = (controller: Controller) => Rendered;
+export interface ViewerTarget<Subject = unknown> {
+    readonly instanceId: string;
+    readonly epoch: string;
+    readonly subject: Subject;
+}
+export type PresentationResult<Output, Subject = unknown> = {
+    readonly kind: 'applied';
+    readonly value: Output;
+} | {
+    readonly kind: 'proposed';
+    readonly proposalId: string;
+    readonly base: ViewerTarget<Subject>;
+} | {
+    readonly kind: 'stale' | 'conflict' | 'denied' | 'unavailable';
+    readonly reason: string;
+} | {
+    readonly kind: 'unknown';
+    readonly reason: string;
+};
+/** Function properties retain strict input/target variance. Native tool
+ * adapters bind this metadata through Pi; this is not another tool engine.
+ */
+export interface PresentationCommand<Input, Output, Subject = unknown> {
+    readonly name: string;
+    readonly input: ValueSchema<Input>;
+    readonly invoke: (target: ViewerTarget<Subject>, input: Input, signal?: AbortSignal) => Promise<PresentationResult<Output, Subject>>;
+}
+/** Anchors: data a feature keeps to point into a viewer's subject (FEEDBACK.md).
+ * `kind` is `<viewer>.<type>@<version>`; `fallback` is a human-readable
+ * description that never needs the viewer. Type-only: a viewer implements the
+ * two halves below without importing any feature that stores anchors.
+ */
+export interface Anchor {
+    readonly kind: `${string}.${string}@${number}`;
+    readonly fallback: string;
+}
+/** Where an anchor lands in one explicit snapshot. `evaluated` names that
+ * snapshot. Only `exact` and `moved` are unique matches; `ambiguous` needs a
+ * person's choice even with one candidate.
+ */
+export type Placement<Range> = {
+    readonly kind: 'exact' | 'moved';
+    readonly range: Range;
+    readonly evaluated: string;
+} | {
+    readonly kind: 'ambiguous';
+    readonly candidates: readonly Range[];
+    readonly evaluated: string;
+} | {
+    readonly kind: 'partial';
+    readonly range: Range;
+    readonly missing: readonly string[];
+    readonly evaluated: string;
+} | {
+    readonly kind: 'missing' | 'unsupported';
+    readonly evaluated: string;
+};
+/** Pure half: no DOM, no I/O, a function of the anchor and one snapshot. */
+export interface AnchorResolution<A extends Anchor, Snapshot, Range> {
+    readonly kind: A['kind'];
+    readonly schema: ValueSchema<A>;
+    readonly resolve: (anchor: A, snapshot: Snapshot, evaluated: string) => Placement<Range>;
+    readonly fallback: (anchor: A) => string;
+}
+/** Mounted half: browser only, bound to a live viewer. */
+export interface AnchorCapture<A extends Anchor, Selection, Subject = unknown> {
+    readonly anchorOf: (selection: Selection) => {
+        readonly kind: 'captured';
+        readonly anchor: A;
+    } | {
+        readonly kind: 'refused';
+        readonly reason: string;
+    };
+    readonly reveal: PresentationCommand<{
+        readonly anchor: A;
+        readonly range: unknown;
+    }, void, Subject>;
+}
+/** Declared beside a viewer feature; no registry and no required member. */
+export interface ViewerAnchors<A extends Anchor, Snapshot, Range, Selection, Subject = unknown> {
+    readonly resolution: AnchorResolution<A, Snapshot, Range>;
+    readonly capture?: AnchorCapture<A, Selection, Subject>;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/experience-catalog.d.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+export declare const experienceIdentifier: z.ZodString;
+export declare const layoutProps: {
+    'boring/stack': z.ZodObject<{
+        gap: z.ZodDefault<z.ZodEnum<{
+            small: "small";
+            medium: "medium";
+            large: "large";
+        }>>;
+    }, z.core.$strict>;
+    'boring/row': z.ZodObject<{
+        gap: z.ZodDefault<z.ZodEnum<{
+            small: "small";
+            medium: "medium";
+            large: "large";
+        }>>;
+    }, z.core.$strict>;
+    'boring/grid': z.ZodObject<{
+        columns: z.ZodNumber;
+        gap: z.ZodDefault<z.ZodEnum<{
+            small: "small";
+            medium: "medium";
+            large: "large";
+        }>>;
+    }, z.core.$strict>;
+    'boring/cell': z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>;
+    'boring/generated': z.ZodObject<{
+        region: z.ZodString;
+        candidates: z.ZodArray<z.ZodString>;
+        kinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxElements: z.ZodDefault<z.ZodNumber>;
+        minWidth: z.ZodDefault<z.ZodNumber>;
+        regenerate: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            open: "open";
+            phase: "phase";
+            request: "request";
+        }>>>;
+        prompt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+};
+export declare const experienceCatalog: import("@json-render/core").Catalog<{
+    spec: import("@json-render/core").SchemaType<"object", {
+        root: import("@json-render/core").SchemaType<"string", unknown>;
+        elements: import("@json-render/core").SchemaType<"record", import("@json-render/core").SchemaType<"object", {
+            type: import("@json-render/core").SchemaType<"ref", string>;
+            props: import("@json-render/core").SchemaType<"propsOf", string>;
+            children: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
+            slots: {
+                optional: true;
+                kind: "record";
+                inner?: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>> | undefined;
+            };
+            visible: {
+                optional: true;
+                kind: "any";
+                inner?: unknown;
+            };
+            repeat: {
+                optional: true;
+                kind: "any";
+                inner?: unknown;
+            };
+        }>>;
+    }>;
+    catalog: import("@json-render/core").SchemaType<"object", {
+        components: import("@json-render/core").SchemaType<"map", {
+            props: import("@json-render/core").SchemaType<"zod", unknown>;
+            slots: import("@json-render/core").SchemaType<"array", import("@json-render/core").SchemaType<"string", unknown>>;
+            description: import("@json-render/core").SchemaType<"string", unknown>;
+            example: import("@json-render/core").SchemaType<"any", unknown>;
+        }>;
+        actions: import("@json-render/core").SchemaType<"map", {
+            params: import("@json-render/core").SchemaType<"zod", unknown>;
+            description: import("@json-render/core").SchemaType<"string", unknown>;
+        }>;
+    }>;
+}, {
+    components: {
+        'boring/stack': {
+            props: z.ZodObject<{
+                gap: z.ZodDefault<z.ZodEnum<{
+                    small: "small";
+                    medium: "medium";
+                    large: "large";
+                }>>;
+            }, z.core.$strict>;
+            slots: string[];
+            description: string;
+        };
+        'boring/row': {
+            props: z.ZodObject<{
+                gap: z.ZodDefault<z.ZodEnum<{
+                    small: "small";
+                    medium: "medium";
+                    large: "large";
+                }>>;
+            }, z.core.$strict>;
+            slots: string[];
+            description: string;
+        };
+        'boring/grid': {
+            props: z.ZodObject<{
+                columns: z.ZodNumber;
+                gap: z.ZodDefault<z.ZodEnum<{
+                    small: "small";
+                    medium: "medium";
+                    large: "large";
+                }>>;
+            }, z.core.$strict>;
+            slots: string[];
+            description: string;
+        };
+        'boring/cell': {
+            props: z.ZodObject<{
+                ref: z.ZodString;
+            }, z.core.$strict>;
+            slots: never[];
+            description: string;
+        };
+        'boring/generated': {
+            props: z.ZodObject<{
+                region: z.ZodString;
+                candidates: z.ZodArray<z.ZodString>;
+                kinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                maxElements: z.ZodDefault<z.ZodNumber>;
+                minWidth: z.ZodDefault<z.ZodNumber>;
+                regenerate: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                    open: "open";
+                    phase: "phase";
+                    request: "request";
+                }>>>;
+                prompt: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            slots: string[];
+            description: string;
+        };
+    };
+    actions: {};
+}>;
+//# sourceMappingURL=experience-catalog.d.ts.map

package/dist/experience-catalog.js

@@ -0,0 +1,25 @@
+import { defineCatalog } from '@json-render/core';
+import { schema } from '@json-render/react/schema';
+import { z } from 'zod';
+export const experienceIdentifier = z.string().regex(/^[a-zA-Z0-9_-]+$/).max(80).refine(value => !Object.hasOwn(Object.prototype, value), 'Reserved element identifier');
+export const layoutProps = {
+    'boring/stack': z.strictObject({ gap: z.enum(['small', 'medium', 'large']).default('medium') }),
+    'boring/row': z.strictObject({ gap: z.enum(['small', 'medium', 'large']).default('medium') }),
+    'boring/grid': z.strictObject({ columns: z.number().int().min(1).max(4), gap: z.enum(['small', 'medium', 'large']).default('medium') }),
+    'boring/cell': z.strictObject({ ref: z.string().regex(/^[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+$/).max(160) }),
+    'boring/generated': z.strictObject({ region: experienceIdentifier, candidates: z.array(z.string().min(1).max(160)).max(128),
+        kinds: z.array(z.string().min(1).max(160)).max(128).optional(), maxElements: z.number().int().min(1).max(200).default(64),
+        minWidth: z.number().int().min(0).max(4096).default(0), regenerate: z.array(z.enum(['open', 'phase', 'request'])).max(3).default(['request']),
+        prompt: z.string().min(1).max(1200).optional(),
+    }),
+};
+export const experienceCatalog = defineCatalog(schema, {
+    components: {
+        'boring/stack': { props: layoutProps['boring/stack'], slots: ['default'], description: 'Vertical layout' },
+        'boring/row': { props: layoutProps['boring/row'], slots: ['default'], description: 'Wrapping horizontal layout' },
+        'boring/grid': { props: layoutProps['boring/grid'], slots: ['default'], description: 'Bounded column layout' },
+        'boring/cell': { props: layoutProps['boring/cell'], slots: [], description: 'Host-owned cell reference' },
+        'boring/generated': { props: layoutProps['boring/generated'], slots: ['default'], description: 'Bounded generated region with saved defaults' },
+    },
+    actions: {},
+});

package/dist/experience-compose.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import type { Experimental_CompositionEvaluator } from '@json-render/core';
+declare const descriptor: z.ZodObject<{
+    format: z.ZodLiteral<"boring.experience">;
+    version: z.ZodLiteral<1>;
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    source: z.ZodEnum<{
+        fixed: "fixed";
+        derived: "derived";
+        generated: "generated";
+    }>;
+    kinds: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    root: z.ZodString;
+    elements: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            "boring/stack": "boring/stack";
+            "boring/row": "boring/row";
+            "boring/grid": "boring/grid";
+            "boring/cell": "boring/cell";
+            "boring/generated": "boring/generated";
+        }>;
+        props: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        children: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ExperienceDescriptor = z.infer<typeof descriptor>;
+export interface ExperienceCell {
+    readonly ref: string;
+    readonly kind: string;
+    readonly version: number;
+    readonly maxUses?: number;
+}
+export interface ExperienceAccess {
+    readonly cells: readonly ExperienceCell[];
+    readonly canView: (ref: string) => boolean;
+}
+export declare function validateExperience(value: unknown, access: ExperienceAccess): ExperienceDescriptor;
+export interface ExperienceCompositionKind {
+    readonly kind: string;
+    readonly description: string;
+    readonly metadata: Readonly<Record<string, readonly string[]>>;
+}
+export interface ExperienceCompositionDefinition {
+    readonly name: string;
+    readonly title?: string;
+    readonly intents: Readonly<Record<string, string>>;
+    readonly kinds: readonly ExperienceCompositionKind[];
+}
+export interface ExperienceCompositionCandidate {
+    readonly ref: string;
+    readonly metadata: Readonly<Record<string, string>>;
+    readonly root?: boolean;
+    readonly resource?: string;
+}
+export interface ExperienceCompositionOptions extends ExperienceAccess {
+    readonly definition: ExperienceCompositionDefinition;
+    readonly candidates: readonly ExperienceCompositionCandidate[];
+    readonly intent: string;
+    readonly layouts?: readonly ('boring/stack' | 'boring/row' | 'boring/grid')[];
+    readonly fallback: unknown;
+    readonly evaluate: Experimental_CompositionEvaluator;
+    readonly signal: AbortSignal;
+    readonly limits: {
+        readonly maxElements: number;
+        readonly maxDepth: number;
+        readonly maxEvaluations: number;
+    };
+}
+export type ExperienceCompositionSnapshot = {
+    readonly compositionId: string;
+    readonly sequence: number;
+} & ({
+    readonly kind: 'partial' | 'final';
+    readonly descriptor: ExperienceDescriptor;
+} | {
+    readonly kind: 'default';
+    readonly descriptor: ExperienceDescriptor | null;
+    readonly reason: 'pending' | 'unavailable' | 'cancelled' | 'limit';
+});
+export declare function composeExperience(options: ExperienceCompositionOptions): AsyncGenerator<ExperienceCompositionSnapshot>;
+export {};
+//# sourceMappingURL=experience-compose.d.ts.map