@hachej/boring-ui-kit 0.1.111 → 0.2.0

package/dist/experience-compose.js

@@ -0,0 +1,218 @@
+import { z } from 'zod';
+import { experimental_composeSpec } from '@json-render/core';
+import { compositionDefinition, compositionCandidate, compositionLimits, compositionId as newCompositionId } from './experience-composition-schema.js';
+import { experienceCatalog, layoutProps, experienceIdentifier } from './experience-catalog.js';
+const id = experienceIdentifier;
+const element = z.strictObject({ type: z.enum(['boring/stack', 'boring/row', 'boring/grid', 'boring/cell', 'boring/generated']), props: z.record(z.string(), z.unknown()), children: z.array(id).max(200).default([]) });
+const descriptor = z.strictObject({
+    format: z.literal('boring.experience'), version: z.literal(1), name: id,
+    title: z.string().max(120).optional(), source: z.enum(['fixed', 'derived', 'generated']),
+    kinds: z.record(z.string().max(160), z.number().int().min(1).max(10000)),
+    root: id, elements: z.record(id, element),
+});
+export function validateExperience(value, access) {
+    const parsed = descriptor.parse(value);
+    const names = Object.keys(parsed.elements);
+    if (names.length === 0 || names.length > 200 || Object.keys(parsed.kinds).length > 200)
+        throw new TypeError('Experience exceeds its element or kind limits');
+    for (const node of Object.values(parsed.elements))
+        node.props = layoutProps[node.type].parse(node.props);
+    const cells = new Map();
+    const installed = new Map(Object.keys(layoutProps).map(kind => [kind, 1]));
+    for (const cell of access.cells) {
+        layoutProps['boring/cell'].parse({ ref: cell.ref });
+        if (cells.has(cell.ref) || !/^[a-zA-Z0-9_/-]{1,160}$/.test(cell.kind) || cell.kind.startsWith('boring/') || !Number.isSafeInteger(cell.version) || cell.version < 1
+            || cell.maxUses !== undefined && (!Number.isSafeInteger(cell.maxUses) || cell.maxUses < 1))
+            throw new TypeError('Invalid cell registration');
+        const version = installed.get(cell.kind);
+        if (version !== undefined && version !== cell.version)
+            throw new TypeError('Conflicting installed kind versions');
+        cells.set(cell.ref, cell);
+        installed.set(cell.kind, cell.version);
+    }
+    for (const [kind, version] of Object.entries(parsed.kinds))
+        if (installed.get(kind) !== version)
+            throw new TypeError('Unknown or incompatible experience kind');
+    const seen = new Set(), uses = new Map(), regions = new Set();
+    const visit = (key, depth, ancestors = []) => {
+        if (depth > 24 || seen.has(key))
+            throw new TypeError('Experience must be a bounded tree');
+        const current = parsed.elements[key];
+        if (!current || parsed.kinds[current.type] !== 1)
+            throw new TypeError('Missing element or kind version');
+        seen.add(key);
+        for (const region of ancestors)
+            if (region.kinds && !region.kinds.includes(current.type))
+                throw new TypeError('Region kind is not allowed');
+        let childrenRegions = ancestors;
+        const before = seen.size;
+        if (current.type === 'boring/generated') {
+            const region = layoutProps['boring/generated'].parse(current.props);
+            if (regions.has(region.region) || new Set(region.candidates).size !== region.candidates.length || new Set(region.regenerate).size !== region.regenerate.length || region.kinds && new Set(region.kinds).size !== region.kinds.length)
+                throw new TypeError('Invalid region registration');
+            if (region.kinds?.some(kind => !Object.hasOwn(parsed.kinds, kind)))
+                throw new TypeError('Undeclared region kind');
+            regions.add(region.region);
+            childrenRegions = [...ancestors, region];
+        }
+        if (current.type === 'boring/cell') {
+            const { ref } = layoutProps['boring/cell'].parse(current.props);
+            const cell = cells.get(ref);
+            if (!cell || parsed.kinds[cell.kind] !== cell.version || access.canView(ref) !== true)
+                throw new TypeError('Cell unavailable');
+            for (const region of ancestors)
+                if (!region.candidates.includes(ref) && !region.candidates.includes(cell.kind)
+                    || region.kinds && !region.kinds.includes(cell.kind))
+                    throw new TypeError('Region cell is not allowed');
+            const count = (uses.get(ref) ?? 0) + 1;
+            uses.set(ref, count);
+            if (current.children.length || count > (cell.maxUses ?? 1))
+                throw new TypeError('Cell placement exceeds its registration');
+        }
+        for (const child of current.children)
+            visit(child, depth + 1, childrenRegions);
+        if (current.type === 'boring/generated' && seen.size - before > layoutProps['boring/generated'].parse(current.props).maxElements)
+            throw new TypeError('Region exceeds its element budget');
+        for (const value of Object.values(current.props))
+            if (Array.isArray(value))
+                Object.freeze(value);
+        Object.freeze(current.props);
+        Object.freeze(current.children);
+        Object.freeze(current);
+    };
+    visit(parsed.root, 0);
+    if (seen.size !== names.length || !experienceCatalog.validate({ root: parsed.root, elements: parsed.elements }).success)
+        throw new TypeError('Invalid experience structure');
+    Object.freeze(parsed.kinds);
+    Object.freeze(parsed.elements);
+    return Object.freeze(parsed);
+}
+function prepareComposition(options, access) {
+    const definition = compositionDefinition.parse(options.definition), limits = compositionLimits.parse(options.limits);
+    if (!Object.hasOwn(definition.intents, options.intent) || options.candidates.length > 128)
+        throw new TypeError('Invalid composition input');
+    const prompt = definition.intents[options.intent];
+    if (!prompt)
+        throw new TypeError('Composition intent is required');
+    const inputs = z.array(compositionCandidate).max(128).parse(options.candidates);
+    const installed = new Map(access.cells.map(cell => [cell.ref, cell]));
+    const metadata = new Map(definition.kinds.map(kind => [kind.kind, kind]));
+    if (metadata.size !== definition.kinds.length)
+        throw new TypeError('Duplicate composition kind');
+    const layouts = z.array(z.enum(['boring/stack', 'boring/row', 'boring/grid'])).max(3).parse(options.layouts ?? ['boring/stack', 'boring/row', 'boring/grid']);
+    if (new Set(layouts).size !== layouts.length)
+        throw new TypeError('Duplicate layout kind');
+    const markers = new Map(), resources = new Map(), refs = new Set();
+    const candidates = [
+        { id: 'layout_stack', description: 'Vertical layout', element: { type: 'boring/stack', props: { gap: 'medium' } }, maxUses: limits.maxElements },
+        { id: 'layout_row', description: 'Wrapping horizontal layout', element: { type: 'boring/row', props: { gap: 'medium' } }, maxUses: limits.maxElements },
+        { id: 'layout_grid', description: 'Two-column layout', element: { type: 'boring/grid', props: { gap: 'medium', columns: 2 } }, maxUses: limits.maxElements },
+    ];
+    candidates.splice(0, candidates.length, ...candidates.filter(candidate => layouts.some(kind => kind === candidate.element.type)));
+    for (const [index, candidate] of inputs.entries()) {
+        const cell = installed.get(candidate.ref);
+        const registration = cell && metadata.get(cell.kind);
+        if (!cell || !registration || refs.has(cell.ref) || access.canView(cell.ref) !== true)
+            throw new TypeError('Composition cell unavailable');
+        refs.add(cell.ref);
+        const flags = [];
+        for (const [key, value] of Object.entries(candidate.metadata)) {
+            if (!Object.hasOwn(registration.metadata, key) || !registration.metadata[key]?.includes(value))
+                throw new TypeError('Unregistered composition metadata');
+            flags.push(`${key}: ${value}`);
+        }
+        const marker = `composition/c${index}`;
+        markers.set(marker, cell);
+        let resource;
+        if (candidate.resource !== undefined) {
+            resource = resources.get(candidate.resource) ?? `resource_${resources.size}`;
+            resources.set(candidate.resource, resource);
+        }
+        candidates.push({ id: `candidate_${index}`, description: [registration.description, ...flags].join('; '),
+            element: { type: 'boring/cell', props: { ref: marker } }, root: candidate.root ?? false,
+            maxUses: Math.min(cell.maxUses ?? 1, limits.maxElements), ...(resource === undefined ? {} : { resource }),
+        });
+    }
+    if (!candidates.some(candidate => candidate.root !== false))
+        throw new TypeError('Composition has no root candidate');
+    validateExperience({ format: 'boring.experience', version: 1, name: definition.name, source: 'generated',
+        kinds: { 'boring/stack': 1 }, root: 'root', elements: { root: { type: 'boring/stack', props: {}, children: [] } },
+    }, access);
+    return { definition, limits, prompt, candidates, markers, access };
+}
+function rebindComposition(spec, prepared) {
+    const kinds = new Map(), elements = new Map();
+    for (const [key, value] of Object.entries(spec.elements)) {
+        const parsed = element.parse(value);
+        kinds.set(parsed.type, 1);
+        if (parsed.type === 'boring/cell') {
+            const marker = layoutProps['boring/cell'].parse(parsed.props).ref, cell = prepared.markers.get(marker);
+            if (!cell)
+                throw new TypeError('Unknown composition marker');
+            kinds.set(cell.kind, cell.version);
+            parsed.props = { ref: cell.ref };
+        }
+        elements.set(key, parsed);
+    }
+    return validateExperience({ format: 'boring.experience', version: 1, name: prepared.definition.name,
+        ...(prepared.definition.title === undefined ? {} : { title: prepared.definition.title }),
+        source: 'generated', kinds: Object.fromEntries(kinds), root: spec.root, elements: Object.fromEntries(elements),
+    }, prepared.access);
+}
+export async function* composeExperience(options) {
+    const compositionId = newCompositionId();
+    const { signal, evaluate, canView } = options;
+    const access = { cells: options.cells.map(cell => ({ ...cell })), canView };
+    const initial = descriptor.safeParse(options.fallback);
+    let sequence = 0;
+    const fallback = () => {
+        try {
+            return initial.success ? validateExperience(initial.data, access) : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    let prepared;
+    try {
+        signal.throwIfAborted();
+        prepared = prepareComposition(options, access);
+    }
+    catch {
+        prepared = undefined;
+    }
+    yield Object.freeze({ compositionId, sequence: sequence++, kind: 'default', descriptor: fallback(), reason: 'pending' });
+    if (!prepared) {
+        yield Object.freeze({ compositionId, sequence: sequence++, kind: 'default', descriptor: fallback(), reason: signal.aborted ? 'cancelled' : 'unavailable' });
+        return;
+    }
+    try {
+        signal.throwIfAborted();
+        const evaluateVisible = request => {
+            signal.throwIfAborted();
+            for (const cell of prepared.markers.values())
+                if (canView(cell.ref) !== true)
+                    throw new TypeError('Composition cell unavailable');
+            signal.throwIfAborted();
+            return evaluate(request);
+        };
+        for await (const event of experimental_composeSpec({ catalog: experienceCatalog, candidates: prepared.candidates, prompt: prepared.prompt,
+            evaluate: evaluateVisible, signal, maxElements: prepared.limits.maxElements,
+            maxDepth: prepared.limits.maxDepth, maxSteps: prepared.limits.maxEvaluations,
+        })) {
+            signal.throwIfAborted();
+            if (event.type === 'complete' && (event.stopReason !== 'finish' || !event.spec)) {
+                yield Object.freeze({ compositionId, sequence: sequence++, kind: 'default', descriptor: fallback(), reason: event.stopReason === 'limit' ? 'limit' : 'unavailable' });
+                return;
+            }
+            if (!event.spec)
+                throw new TypeError('Missing composed descriptor');
+            const descriptor = rebindComposition(event.spec, prepared);
+            signal.throwIfAborted();
+            yield Object.freeze({ compositionId, sequence: sequence++, kind: event.type === 'complete' ? 'final' : 'partial', descriptor });
+        }
+    }
+    catch {
+        yield Object.freeze({ compositionId, sequence: sequence++, kind: 'default', descriptor: fallback(), reason: signal.aborted ? 'cancelled' : 'unavailable' });
+    }
+}

package/dist/experience-composition-schema.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/**
+ * Opaque per-composition id (32 hex characters). The headless experience entries must load without `@hachej/boring-files`
+ * (README, `npm run test:experience-consumer`), so they do not import `randomUUID` from `@hachej/boring-files/platform`;
+ * `crypto.getRandomValues` exists in every context, including plain-HTTP origins, so no secure-context fallback is needed.
+ */
+export declare function compositionId(): string;
+export declare const compositionDefinition: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    intents: z.ZodRecord<z.ZodString, z.ZodString>;
+    kinds: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        description: z.ZodString;
+        metadata: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const compositionCandidate: z.ZodObject<{
+    ref: z.ZodString;
+    metadata: z.ZodRecord<z.ZodString, z.ZodString>;
+    root: z.ZodOptional<z.ZodBoolean>;
+    resource: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const compositionLimits: z.ZodObject<{
+    maxElements: z.ZodNumber;
+    maxDepth: z.ZodNumber;
+    maxEvaluations: z.ZodNumber;
+}, z.core.$strip>;
+//# sourceMappingURL=experience-composition-schema.d.ts.map

package/dist/experience-composition-schema.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { layoutProps, experienceIdentifier as id } from './experience-catalog.js';
+/**
+ * Opaque per-composition id (32 hex characters). The headless experience entries must load without `@hachej/boring-files`
+ * (README, `npm run test:experience-consumer`), so they do not import `randomUUID` from `@hachej/boring-files/platform`;
+ * `crypto.getRandomValues` exists in every context, including plain-HTTP origins, so no secure-context fallback is needed.
+ */
+export function compositionId() {
+    return Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), byte => byte.toString(16).padStart(2, '0')).join('');
+}
+const boundedRecord = (value, limit) => z.record(id, value).refine(record => Object.keys(record).length <= limit);
+export const compositionDefinition = z.object({
+    name: id, title: z.string().max(120).optional(), intents: boundedRecord(z.string().min(1).max(1200), 32),
+    kinds: z.array(z.object({ kind: z.string().min(1).max(160), description: z.string().min(1).max(500),
+        metadata: boundedRecord(z.array(z.string().min(1).max(80)).min(1).max(32), 16),
+    })).max(128),
+});
+export const compositionCandidate = z.object({
+    ref: layoutProps['boring/cell'].shape.ref, metadata: boundedRecord(z.string().max(80), 16),
+    root: z.boolean().optional(), resource: z.string().min(1).max(512).optional(),
+});
+export const compositionLimits = z.object({ maxElements: z.number().int().min(1).max(200), maxDepth: z.number().int().min(1).max(24), maxEvaluations: z.number().int().min(1).max(32) });

package/dist/experience-document-viewer.d.ts

@@ -0,0 +1,13 @@
+import type { RenderedExperienceCell } from './experience-renderer.js';
+import type { ExperienceAccess } from './experience-compose.js';
+import type { ExperienceDocumentController, ExperienceRegionRequest } from './experience-document.js';
+export interface ExperienceDocumentProps {
+    readonly controller: ExperienceDocumentController;
+    readonly cells: readonly RenderedExperienceCell[];
+    readonly canView: ExperienceAccess['canView'];
+    readonly onRegenerate?: (request: ExperienceRegionRequest) => void | Promise<void>;
+    readonly title?: string;
+    readonly className?: string;
+}
+export declare function ExperienceDocument(props: ExperienceDocumentProps): import("react").JSX.Element;
+//# sourceMappingURL=experience-document-viewer.d.ts.map

package/dist/experience-document-viewer.js

@@ -0,0 +1,54 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { TextDraftControls } from './text-draft-controls.js';
+import { useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { ExperienceRenderer } from './experience-renderer.js';
+import { layoutProps } from './experience-catalog.js';
+function MountedDocument({ controller, cells, canView, onRegenerate, title = 'Experience layout', className }) {
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const [error, setError] = useState();
+    const active = useRef(true);
+    useLayoutEffect(() => { active.current = true; return () => { active.current = false; }; }, []);
+    const pending = state.save.kind === 'pending';
+    const unknown = state.save.kind === 'settled' && state.save.result.kind === 'unknown';
+    const disposed = state.lifecycle === 'disposed';
+    const proposal = state.proposal;
+    const regions = Object.values(state.descriptor?.elements ?? {}).flatMap(element => element.type === 'boring/generated'
+        ? [layoutProps['boring/generated'].parse(element.props)] : []);
+    const perform = (action) => {
+        setError(undefined);
+        void Promise.resolve().then(action).then(result => {
+            if (active.current && (result.kind === 'denied' || result.kind === 'unavailable'))
+                setError(result.reason);
+        }).catch(() => { if (active.current)
+            setError('The layout operation failed. The draft has been retained.'); });
+    };
+    const status = disposed ? 'Viewer disposed' : state.readOnly ? 'Read only' : pending ? 'Keeping selected layout' : unknown ? 'Keep unconfirmed. Reconcile before keeping again.'
+        : state.save.kind === 'settled' && state.save.result.kind !== 'saved' ? state.save.result.kind === 'partial' ? 'Keep unconfirmed' : state.save.result.reason
+            : state.dirty ? 'Layout not kept' : 'Layout kept';
+    return _jsxs("section", { "data-boring": "experience-document", className: className, "aria-label": title, children: [_jsxs("header", { children: [_jsx("strong", { children: title }), _jsx("span", { role: "status", children: status })] }), _jsxs("div", { role: "toolbar", "aria-label": "Layout document controls", children: [_jsx("button", { type: "button", disabled: disposed || state.readOnly || !state.dirty || !state.descriptor || pending || unknown, onClick: () => { const selection = controller.actions.selection(); perform(() => controller.flush(selection)); }, children: "Keep this layout" }), _jsx("button", { type: "button", disabled: disposed || pending || unknown, onClick: () => perform(controller.actions.refresh), children: "Refresh layout" }), _jsx("button", { type: "button", disabled: disposed || !unknown, onClick: () => perform(controller.actions.reconcile), children: "Reconcile keep" }), _jsx("button", { type: "button", disabled: disposed || pending || unknown || state.remote === null, onClick: () => perform(controller.actions.discardToRemote), children: "Discard local layout" }), state.pin && _jsx("button", { type: "button", disabled: disposed || state.readOnly || pending || unknown, onClick: () => {
+                            const pin = state.pin;
+                            if (pin)
+                                perform(() => controller.actions.pin(pin.selection));
+                        }, children: "Pin this region" }), regions.filter(region => region.regenerate.includes('request')).map(region => _jsxs("button", { type: "button", disabled: disposed || state.readOnly || !onRegenerate, onClick: () => {
+                            const result = controller.actions.beginRegion(controller.actions.selection(), region.region, 'request');
+                            if (result.kind !== 'applied') {
+                                setError('reason' in result ? result.reason : 'Region request was not started');
+                                return;
+                            }
+                            setError(undefined);
+                            void Promise.resolve().then(() => onRegenerate?.(result.value)).catch(() => {
+                                if (active.current)
+                                    setError('The region could not be regenerated. The current layout has been retained.');
+                            });
+                        }, children: ["Regenerate ", region.region] }, region.region))] }), _jsx(TextDraftControls, { recovery: state.recovery, actions: controller.actions, readOnly: state.readOnly, blocked: state.lifecycle !== 'active' || state.save.kind === 'pending' || (state.save.kind === 'settled' && state.save.result.kind === 'unknown') }), proposal && _jsxs("div", { role: "group", "aria-label": proposal.kind === 'region' ? 'Proposed region' : 'Proposed layout', children: [_jsx("button", { type: "button", disabled: disposed || state.readOnly, onClick: () => {
+                            const result = controller.actions.adopt(proposal.id);
+                            setError(result.kind === 'applied' ? undefined : 'reason' in result ? result.reason : 'Layout was not adopted');
+                        }, children: proposal.kind === 'region' ? 'Use proposed region' : 'Use proposed layout' }), _jsx("button", { type: "button", disabled: disposed, onClick: () => { controller.actions.reject(proposal.id); setError(undefined); }, children: proposal.kind === 'region' ? 'Dismiss proposed region' : 'Dismiss proposed layout' })] }), (error || state.problem) && _jsx("p", { role: "alert", children: error ?? state.problem }), state.descriptor ? _jsx("section", { "data-boring": "experience", "aria-label": state.descriptor.title ?? state.descriptor.name, children: _jsx(ExperienceRenderer, { descriptor: state.descriptor, cells: cells, canView: canView }) }) : _jsx("p", { children: "No layout selected" })] });
+}
+export function ExperienceDocument(props) {
+    const [mount, setMount] = useState({ controller: props.controller, sequence: 0 });
+    if (mount.controller !== props.controller)
+        setMount({ controller: props.controller, sequence: mount.sequence + 1 });
+    return _jsx(MountedDocument, { ...props }, mount.sequence);
+}

package/dist/experience-document.d.ts

@@ -0,0 +1,64 @@
+import type { ReadResult, ResourceLocator, ResourceSnapshot } from '@hachej/boring-files';
+import type { PresentationResult } from './contracts.js';
+import type { EditableViewerController, SaveResult, SaveSelection } from './resources.js';
+import type { TextBufferOptions, TextBufferState } from './text-buffer.js';
+import type { ExperienceAccess, ExperienceDescriptor } from './experience-compose.js';
+import type { ExperienceRegionTrigger } from './experience-regions.js';
+import type { TextDraftActions, TextDraftOptions } from './text-draft-types.js';
+export type ExperienceDocumentSource = {
+    readonly kind: 'saved';
+    readonly snapshot: ResourceSnapshot;
+} | {
+    readonly kind: 'new';
+    readonly target: ResourceLocator;
+    readonly descriptor?: unknown;
+};
+export interface ExperienceDocumentOptions extends Pick<TextBufferOptions, 'identity' | 'instanceId' | 'epoch' | 'client' | 'readOnly' | 'onListenerError'>, ExperienceAccess {
+    readonly source: ExperienceDocumentSource;
+    readonly drafts?: TextDraftOptions;
+    readonly validateDocument?: (descriptor: Readonly<ExperienceDescriptor>) => void;
+}
+interface Proposal {
+    readonly id: string;
+    readonly base: SaveSelection;
+    readonly descriptor: ExperienceDescriptor;
+}
+export type ExperienceProposal = Proposal & ({
+    readonly kind: 'layout';
+} | {
+    readonly kind: 'region';
+    readonly region: string;
+    readonly requestId: string;
+});
+export interface ExperienceRegionRequest {
+    readonly id: string;
+    readonly region: string;
+    readonly trigger: ExperienceRegionTrigger;
+    readonly base: SaveSelection;
+}
+export interface ExperienceDocumentState extends TextBufferState {
+    readonly descriptor: ExperienceDescriptor | null;
+    readonly problem: string | null;
+    readonly proposal: ExperienceProposal | null;
+    readonly pin: {
+        readonly region: string;
+        readonly selection: SaveSelection;
+    } | null;
+}
+type Subject = SaveSelection['target']['subject'];
+export interface ExperienceDocumentActions extends TextDraftActions {
+    readonly selection: () => SaveSelection;
+    readonly propose: (base: SaveSelection, descriptor: unknown) => PresentationResult<void, Subject>;
+    readonly beginRegion: (base: SaveSelection, region: string, trigger: ExperienceRegionTrigger) => PresentationResult<ExperienceRegionRequest, Subject>;
+    readonly proposeRegion: (request: ExperienceRegionRequest, descriptor: unknown) => PresentationResult<void, Subject>;
+    readonly pin: (selection: SaveSelection, signal?: AbortSignal) => Promise<SaveResult>;
+    readonly adopt: (proposalId: string) => PresentationResult<SaveSelection, Subject>;
+    readonly reject: (proposalId: string) => void;
+    readonly refresh: () => Promise<ReadResult>;
+    readonly discardToRemote: () => Promise<ReadResult>;
+    readonly reconcile: () => Promise<SaveResult>;
+}
+export type ExperienceDocumentController = EditableViewerController<ExperienceDocumentState, ExperienceDocumentActions, undefined>;
+export declare function createExperienceDocumentController(options: ExperienceDocumentOptions): ExperienceDocumentController;
+export {};
+//# sourceMappingURL=experience-document.d.ts.map

package/dist/experience-document.js

@@ -0,0 +1,234 @@
+import { createTextBuffer, freeze, sameBase } from './text-buffer.js';
+import { validateExperience } from './experience-compose.js';
+import { experienceRegion, assertRegionReplacement } from './experience-region-tree.js';
+import { replaceRegionText } from './experience-region-text.js';
+import { randomUUID } from '@hachej/boring-files/platform';
+export function createExperienceDocumentController(options) {
+    const parse = (text) => {
+        const descriptor = validateExperience(JSON.parse(text), options);
+        if (descriptor.source !== 'fixed')
+            throw new TypeError('Saved experience must be fixed');
+        options.validateDocument?.(freeze(descriptor));
+        return descriptor;
+    };
+    const fixedText = (descriptor) => JSON.stringify({ ...descriptor, source: 'fixed' }) + '\n';
+    const source = options.source.kind === 'saved' ? options.source : {
+        kind: 'new', target: options.source.target,
+        text: options.source.descriptor === undefined ? '' : fixedText(validateExperience(options.source.descriptor, options)),
+    };
+    const { drafts, ...bufferOptions } = options;
+    const buffer = createTextBuffer({ ...bufferOptions, ...(drafts ? { drafts: { ...drafts, format: 'experience/v1', validateText: (text) => { parse(text); } } } : {}), source, mediaType: 'application/json',
+        readText: snapshot => {
+            if (snapshot.mediaType !== 'application/json')
+                throw new TypeError('Expected an experience JSON document');
+            const text = new TextDecoder('utf-8', { fatal: true }).decode(snapshot.bytes);
+            parse(text);
+            return text;
+        } });
+    const decoded = (text) => {
+        if (!text)
+            return { descriptor: null, problem: null };
+        try {
+            return { descriptor: parse(text), problem: null };
+        }
+        catch {
+            return { descriptor: null, problem: 'The selected layout is unavailable.' };
+        }
+    };
+    let state = freeze({ ...buffer.getSnapshot(), ...decoded(buffer.getSnapshot().text), proposal: null, pin: null });
+    let pinOrigin = null;
+    let requestSequence = 0;
+    const requests = new Map();
+    const listeners = new Set();
+    const update = (next) => {
+        state = freeze(next);
+        for (const listener of [...listeners]) {
+            try {
+                listener();
+            }
+            catch (error) {
+                queueMicrotask(() => { if (options.onListenerError)
+                    options.onListenerError(error);
+                else
+                    throw error; });
+            }
+        }
+    };
+    const unsubscribe = buffer.subscribe(() => {
+        const next = buffer.getSnapshot();
+        const view = next.text === state.text ? { descriptor: state.descriptor, problem: state.problem } : decoded(next.text);
+        if (buffer.getSnapshot() === next)
+            update({ ...next, ...view, proposal: state.proposal,
+                pin: pinOrigin?.version === next.bufferVersion && next.dirty && next.lifecycle === 'active' ? { region: pinOrigin.region, selection: buffer.selection() } : null });
+    });
+    const selected = (selection) => {
+        const current = buffer.selection().target, supplied = selection.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 propose = (supplied, value) => {
+        const base = freeze(structuredClone(supplied));
+        if (state.lifecycle === 'disposed')
+            return { kind: 'unavailable', reason: 'Viewer is disposed' };
+        if (state.readOnly)
+            return { kind: 'denied', reason: 'Layout document is read-only' };
+        if (!selected(base))
+            return { kind: 'stale', reason: 'Proposal base has changed' };
+        const descriptor = validateExperience(value, options);
+        if (!selected(base) || buffer.getSnapshot().lifecycle === 'disposed')
+            return { kind: 'stale', reason: 'Proposal base changed during validation' };
+        const proposal = freeze({ kind: 'layout', id: randomUUID(), base: structuredClone(base), descriptor });
+        update({ ...state, proposal });
+        return { kind: 'proposed', proposalId: proposal.id, base: proposal.base.target };
+    };
+    const currentRequest = (request) => {
+        const stored = requests.get(request.region);
+        return stored?.id === request.id && stored.trigger === request.trigger && selected(stored.base) && selected(request.base);
+    };
+    const beginRegion = (base, region, trigger) => {
+        if (state.lifecycle === 'disposed')
+            return { kind: 'unavailable', reason: 'Viewer is disposed' };
+        if (state.readOnly)
+            return { kind: 'denied', reason: 'Layout document is read-only' };
+        if (!selected(base))
+            return { kind: 'stale', reason: 'Region base has changed' };
+        const request = freeze({ id: randomUUID(), base: structuredClone(base), region, trigger });
+        const sequence = ++requestSequence;
+        try {
+            const descriptor = parse(buffer.getSnapshot().text), found = experienceRegion(descriptor, region);
+            if (!found.props.regenerate.includes(trigger))
+                return { kind: 'denied', reason: 'Region trigger is not enabled' };
+        }
+        catch {
+            return { kind: 'denied', reason: 'Region is unavailable' };
+        }
+        if (sequence !== requestSequence || !selected(request.base) || buffer.getSnapshot().lifecycle === 'disposed')
+            return { kind: 'stale', reason: 'Region changed during validation' };
+        for (const [name, previous] of requests)
+            if (!selected(previous.base))
+                requests.delete(name);
+        requests.set(region, request);
+        update({ ...state, proposal: state.proposal?.kind === 'region' && state.proposal.region === region ? null : state.proposal });
+        return { kind: 'applied', value: request };
+    };
+    const proposeRegion = (supplied, value) => {
+        if (state.lifecycle === 'disposed')
+            return { kind: 'unavailable', reason: 'Viewer is disposed' };
+        if (state.readOnly)
+            return { kind: 'denied', reason: 'Layout document is read-only' };
+        if (!currentRequest(supplied))
+            return { kind: 'stale', reason: 'Region request or base has changed' };
+        const request = requests.get(supplied.region);
+        if (!request)
+            return { kind: 'stale', reason: 'Region request has changed' };
+        let descriptor;
+        try {
+            const base = parse(buffer.getSnapshot().text);
+            descriptor = validateExperience(value, options);
+            assertRegionReplacement(base, descriptor, request.region);
+        }
+        catch {
+            return { kind: 'denied', reason: 'Proposed region is unavailable' };
+        }
+        if (!currentRequest(request) || buffer.getSnapshot().lifecycle === 'disposed')
+            return { kind: 'stale', reason: 'Region changed during validation' };
+        const proposal = freeze({ kind: 'region', id: randomUUID(), base: structuredClone(request.base), descriptor, region: request.region, requestId: request.id });
+        update({ ...state, proposal });
+        return { kind: 'proposed', proposalId: proposal.id, base: proposal.base.target };
+    };
+    const adopt = proposalId => {
+        if (state.lifecycle === 'disposed')
+            return { kind: 'unavailable', reason: 'Viewer is disposed' };
+        if (state.readOnly)
+            return { kind: 'denied', reason: 'Layout document is read-only' };
+        const proposal = state.proposal;
+        if (!proposal || proposal.id !== proposalId || !selected(proposal.base)
+            || proposal.kind === 'region' && requests.get(proposal.region)?.id !== proposal.requestId)
+            return { kind: 'stale', reason: 'Offered layout or its base has changed' };
+        let text;
+        const before = buffer.getSnapshot();
+        try {
+            const descriptor = validateExperience(proposal.descriptor, options);
+            text = proposal.kind === 'region' ? replaceRegionText(before.text, parse(before.text), descriptor, proposal.region) : fixedText(descriptor);
+            if (proposal.kind === 'region')
+                JSON.parse(text);
+        }
+        catch {
+            return { kind: 'denied', reason: 'Offered layout is no longer available' };
+        }
+        if (!selected(proposal.base) || state.proposal?.id !== proposalId || buffer.getSnapshot().lifecycle === 'disposed'
+            || proposal.kind === 'region' && requests.get(proposal.region)?.id !== proposal.requestId)
+            return { kind: 'stale', reason: 'Offered layout changed during validation' };
+        const selection = freeze({ target: { ...proposal.base.target, subject: { ...proposal.base.target.subject, bufferVersion: proposal.base.target.subject.bufferVersion + 1 } } });
+        pinOrigin = proposal.kind === 'region' && (!before.dirty || pinOrigin?.region === proposal.region && pinOrigin.version === before.bufferVersion)
+            ? { region: proposal.region, version: selection.target.subject.bufferVersion } : null;
+        state = freeze({ ...state, proposal: null });
+        buffer.edit(text, true);
+        return { kind: 'applied', value: selection };
+    };
+    const flush = (supplied, signal) => {
+        const selection = freeze(structuredClone(supplied));
+        const before = buffer.getSnapshot();
+        if (before.lifecycle === 'disposed' || before.readOnly || !selected(selection) || before.save.kind === 'pending'
+            || before.save.kind === 'settled' && before.save.result.kind === 'unknown')
+            return buffer.flush(selection, signal);
+        try {
+            parse(before.text);
+        }
+        catch {
+            if (buffer.getSnapshot() !== before)
+                return buffer.flush(selection, signal);
+            return Promise.resolve({ kind: 'denied', reason: 'The selected layout is unavailable for keeping' });
+        }
+        return buffer.flush(selection, signal);
+    };
+    const pin = (selection, signal) => {
+        const current = buffer.getSnapshot();
+        if (current.lifecycle === 'disposed' || current.readOnly || !selected(selection) || current.save.kind === 'pending'
+            || current.save.kind === 'settled' && current.save.result.kind === 'unknown')
+            return buffer.flush(selection, signal);
+        if (!state.pin || pinOrigin?.version !== current.bufferVersion)
+            return Promise.resolve({ kind: 'denied', reason: 'Pin requires a draft containing only this region change' });
+        return flush(selection, signal);
+    };
+    const refresh = async (discard) => {
+        const result = await buffer.refresh(discard);
+        if (result.kind === 'available' && state.problem && state.lifecycle !== 'disposed') {
+            const current = buffer.getSnapshot(), view = decoded(current.text);
+            if (buffer.getSnapshot() === current)
+                update({ ...current, ...view, proposal: state.proposal, pin: state.pin });
+        }
+        return result;
+    };
+    return {
+        getSnapshot: () => state,
+        subscribe: listener => { if (state.lifecycle === 'disposed')
+            return () => { }; listeners.add(listener); return () => { listeners.delete(listener); }; },
+        actions: {
+            selection: buffer.selection, propose, adopt, beginRegion, proposeRegion, pin,
+            checkDrafts: buffer.checkDrafts, checkpointDraft: buffer.checkpointDraft, discardDraft: buffer.discardDraft,
+            restoreDraft: async (choice) => {
+                const proposal = state.proposal, origin = pinOrigin, sequence = requestSequence;
+                const priorRequests = new Map(requests);
+                const result = await buffer.restoreDraft(choice);
+                if (result.kind === 'restored') {
+                    if (pinOrigin === origin)
+                        pinOrigin = null;
+                    for (const [id, request] of priorRequests)
+                        if (requests.get(id) === request)
+                            requests.delete(id);
+                    if (requestSequence === sequence)
+                        requestSequence++;
+                    update({ ...state, proposal: state.proposal === proposal ? null : state.proposal, pin: pinOrigin ? state.pin : null });
+                }
+                return result;
+            },
+            reject: id => { if (state.lifecycle !== 'disposed' && state.proposal?.id === id)
+                update({ ...state, proposal: null }); },
+            refresh: () => refresh(false), discardToRemote: () => refresh(true), reconcile: buffer.reconcile,
+        },
+        tools: undefined, flush,
+        dispose: () => { buffer.dispose(); unsubscribe(); listeners.clear(); requests.clear(); },
+    };
+}

package/dist/experience-region-text.d.ts

@@ -0,0 +1,3 @@
+import type { ExperienceDescriptor } from './experience-compose.js';
+export declare function replaceRegionText(text: string, base: ExperienceDescriptor, next: ExperienceDescriptor, name: string): string;
+//# sourceMappingURL=experience-region-text.d.ts.map