entangled-worlds-orbiters-shared 2.9.0 → 2.10.0

package/dist/capabilities/schema.js

@@ -0,0 +1,139 @@
+/**
+ * Tiny JSON-Schema-subset validator (shared machinery, TypeScript).
+ *
+ * The ONE validator both registries use (supersedes the duplicated
+ * `studio/capabilities/schema.js` + `core/edit/capabilities/schema.ts`). Deliberately NOT a
+ * dependency (no zod/ajv) — the app is bundle-weight sensitive and the house style is
+ * lightweight guard clauses. Each capability carries an `inputSchema` literal in this subset;
+ * the SAME literal is what the future agent layer hands the model as a tool definition, so
+ * there is no second schema language to keep in sync.
+ *
+ * Supported keywords (a pragmatic subset of JSON Schema draft-07):
+ *   type        'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null'
+ *               (or an array of those — value matches if it satisfies any)
+ *   properties  per-key subschemas (objects)
+ *   required    array of keys that must be present and not undefined (objects)
+ *   items       subschema applied to every array element
+ *   enum        value must be one of the listed values
+ *   const       value must deep-equal the given value
+ *   nullable    when true, null always passes regardless of type
+ *   minimum / maximum                 numbers
+ *   minLength / maxLength             strings
+ *   minItems / maxItems               arrays
+ *   pattern     string regex source (tested with RegExp)
+ *
+ * A schema with no `type` accepts any value (still honouring enum/const/properties if set).
+ * Unknown keywords are ignored — forward-compatible, never throws on shape it doesn't know.
+ */
+import { ValidationError } from './errors.js';
+const TYPE_CHECKS = {
+    object: (v) => v !== null && typeof v === 'object' && !Array.isArray(v),
+    array: (v) => Array.isArray(v),
+    string: (v) => typeof v === 'string',
+    number: (v) => typeof v === 'number' && Number.isFinite(v),
+    integer: (v) => typeof v === 'number' && Number.isInteger(v),
+    boolean: (v) => typeof v === 'boolean',
+    null: (v) => v === null,
+};
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object')
+        return false;
+    const ka = Object.keys(a);
+    const kb = Object.keys(b);
+    if (ka.length !== kb.length)
+        return false;
+    return ka.every((k) => deepEqual(a[k], b[k]));
+}
+function checkType(schema, value) {
+    if (schema.type == null)
+        return true;
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    return types.some((t) => (TYPE_CHECKS[t] ? TYPE_CHECKS[t](value) : true));
+}
+function describeType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function validateNode(schema, value, path, issues) {
+    if (!schema || typeof schema !== 'object')
+        return;
+    const at = path || '(root)';
+    if (schema.nullable && value === null)
+        return;
+    if (!checkType(schema, value)) {
+        const want = Array.isArray(schema.type) ? schema.type.join('|') : schema.type;
+        issues.push({ path: at, message: `expected type ${want}, got ${describeType(value)}` });
+        return; // type is the gate; downstream checks would be noise
+    }
+    if ('const' in schema && !deepEqual(value, schema.const)) {
+        issues.push({ path: at, message: `must equal ${JSON.stringify(schema.const)}` });
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some((e) => deepEqual(e, value))) {
+        issues.push({ path: at, message: `must be one of ${JSON.stringify(schema.enum)}` });
+    }
+    if (typeof value === 'number') {
+        if (typeof schema.minimum === 'number' && value < schema.minimum) {
+            issues.push({ path: at, message: `must be >= ${schema.minimum}` });
+        }
+        if (typeof schema.maximum === 'number' && value > schema.maximum) {
+            issues.push({ path: at, message: `must be <= ${schema.maximum}` });
+        }
+    }
+    if (typeof value === 'string') {
+        if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+            issues.push({ path: at, message: `must be at least ${schema.minLength} chars` });
+        }
+        if (typeof schema.maxLength === 'number' && value.length > schema.maxLength) {
+            issues.push({ path: at, message: `must be at most ${schema.maxLength} chars` });
+        }
+        if (typeof schema.pattern === 'string' && !new RegExp(schema.pattern).test(value)) {
+            issues.push({ path: at, message: `must match /${schema.pattern}/` });
+        }
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+            issues.push({ path: at, message: `must have at least ${schema.minItems} items` });
+        }
+        if (typeof schema.maxItems === 'number' && value.length > schema.maxItems) {
+            issues.push({ path: at, message: `must have at most ${schema.maxItems} items` });
+        }
+        if (schema.items) {
+            value.forEach((el, i) => validateNode(schema.items, el, `${path}[${i}]`, issues));
+        }
+    }
+    if (TYPE_CHECKS.object(value)) {
+        const obj = value;
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (obj[key] === undefined)
+                    issues.push({ path: path ? `${path}.${key}` : key, message: 'is required' });
+            }
+        }
+        if (schema.properties) {
+            for (const [key, sub] of Object.entries(schema.properties)) {
+                if (obj[key] !== undefined)
+                    validateNode(sub, obj[key], path ? `${path}.${key}` : key, issues);
+            }
+        }
+    }
+}
+/** Returns { ok, issues }. Never throws. */
+export function validate(schema, value) {
+    const issues = [];
+    validateNode(schema ?? {}, value, '', issues);
+    return { ok: issues.length === 0, issues };
+}
+/** Throws ValidationError when invalid; returns the value otherwise. Used by the registry. */
+export function assertValid(schema, value, capability = null) {
+    const { ok, issues } = validate(schema, value);
+    if (!ok) {
+        const summary = issues.map((i) => `${i.path}: ${i.message}`).join('; ');
+        throw new ValidationError(`Invalid input${capability ? ` for "${capability}"` : ''}: ${summary}`, { capability, issues });
+    }
+    return value;
+}

package/dist/studio/autosaveSession.d.ts

@@ -0,0 +1,56 @@
+export type AutosaveTone = 'default' | 'busy' | 'warn' | 'ok' | 'error';
+export interface AutosaveState {
+    ready: boolean;
+    timer: ReturnType<typeof setTimeout> | null;
+    dirty: boolean;
+    inFlight: boolean;
+    queued: boolean;
+    lastSavedDraftKey: string;
+    pendingHostDraftKey: string;
+    pendingHostDraftManual: boolean;
+}
+export interface AutosaveCtrl {
+    autosave: AutosaveState;
+}
+export interface AutosaveDeps {
+    flushAutosave?: () => unknown;
+    setHeaderStatus?: (arg: {
+        tone: AutosaveTone;
+    } | null) => void;
+    shouldDefer?: () => boolean;
+}
+export interface AutosaveSession {
+    markDirty(): void;
+    schedule(opts?: {
+        delayMs?: number;
+    }): void;
+    clearTimer(): void;
+    syncStatus(): void;
+    setStatus(text?: string, tone?: AutosaveTone): void;
+    arm(baselineKey: string): void;
+    tryBegin(opts: {
+        manual: boolean;
+    }): boolean;
+    checkDedupAndBegin(opts: {
+        manual: boolean;
+        currentDraftKey: string;
+    }): {
+        proceed: boolean;
+        result: boolean;
+    };
+    markSaved(draftKey: string): void;
+    beginHostAck(opts: {
+        manual: boolean;
+        currentDraftKey: string;
+    }): void;
+    settleAfterApi(opts: {
+        manual: boolean;
+    }): void;
+    resolveHostAck(opts: {
+        ok: boolean;
+    }): {
+        wasManual: boolean;
+    };
+    settleHostAck(): void;
+}
+export declare function createAutosaveSession(ctrl: AutosaveCtrl, deps?: AutosaveDeps): AutosaveSession;

package/dist/studio/autosaveSession.js

@@ -0,0 +1,138 @@
+// AutosaveSession — the single owner of a studio's autosave state slice.
+//
+// Owns STATE TRANSITIONS only: the debounce timer and the
+// dirty/inFlight/queued/lastSavedDraftKey/pendingHost* transitions. The real I/O (building the
+// draft, the API call, the host postMessage, toasts, analytics) stays in the app's host bridge,
+// which drives this session through methods and never writes the slice directly. No DOM: the
+// header save-status dot is rendered through the injected `setHeaderStatus` callback.
+//
+// Convention: a `*Session` owns a mutable state slice (no DOM); `createX(holder, deps)`.
+export function createAutosaveSession(ctrl, deps = {}) {
+    ctrl.autosave = {
+        ready: false,
+        timer: null,
+        dirty: false,
+        inFlight: false,
+        queued: false,
+        lastSavedDraftKey: '',
+        pendingHostDraftKey: '',
+        pendingHostDraftManual: false,
+    };
+    const state = ctrl.autosave;
+    const api = {
+        setStatus(text = '', tone = 'default') {
+            deps.setHeaderStatus?.(text ? { tone } : null);
+        },
+        syncStatus() {
+            if (state.inFlight) {
+                api.setStatus('Saving...', 'busy');
+                return;
+            }
+            if (state.dirty) {
+                api.setStatus('Unsaved changes', 'warn');
+                return;
+            }
+            if (state.lastSavedDraftKey) {
+                api.setStatus('All changes saved', 'ok');
+                return;
+            }
+            api.setStatus('');
+        },
+        clearTimer() {
+            if (!state.timer)
+                return;
+            clearTimeout(state.timer);
+            state.timer = null;
+        },
+        schedule({ delayMs = 2000 } = {}) {
+            if (!state.ready)
+                return;
+            api.clearTimer();
+            if (!state.dirty) {
+                api.syncStatus();
+                return;
+            }
+            api.syncStatus();
+            state.timer = setTimeout(() => {
+                state.timer = null;
+                // Reschedule (don't flush) while the app says a save would be rejected.
+                if (deps.shouldDefer?.()) {
+                    api.schedule({ delayMs: 2000 });
+                    return;
+                }
+                void deps.flushAutosave?.();
+            }, delayMs);
+        },
+        markDirty() {
+            if (!state.ready)
+                return;
+            state.dirty = true;
+            if (state.inFlight) {
+                state.queued = true;
+                api.syncStatus();
+                return;
+            }
+            api.schedule();
+        },
+        arm(baselineKey) {
+            state.lastSavedDraftKey = baselineKey;
+            state.ready = true;
+        },
+        tryBegin({ manual }) {
+            api.clearTimer();
+            if (!manual && (!state.ready || !state.dirty))
+                return false;
+            if (state.inFlight) {
+                state.queued = true;
+                api.syncStatus();
+                return false;
+            }
+            return true;
+        },
+        checkDedupAndBegin({ manual, currentDraftKey }) {
+            if (!manual && currentDraftKey && currentDraftKey === state.lastSavedDraftKey) {
+                state.dirty = false;
+                api.syncStatus();
+                return { proceed: false, result: true };
+            }
+            state.inFlight = true;
+            api.syncStatus();
+            return { proceed: true, result: false };
+        },
+        markSaved(draftKey) {
+            // An edit that landed while this save was in flight is queued and NOT in what was saved —
+            // stay dirty so the queued reschedule writes it.
+            state.dirty = state.queued;
+            state.lastSavedDraftKey = draftKey;
+        },
+        beginHostAck({ manual, currentDraftKey }) {
+            state.pendingHostDraftKey = currentDraftKey;
+            state.pendingHostDraftManual = manual === true;
+        },
+        settleAfterApi({ manual }) {
+            state.inFlight = false;
+            api.syncStatus();
+            if (state.queued) {
+                state.queued = false;
+                api.schedule({ delayMs: manual ? 300 : 1200 });
+            }
+        },
+        resolveHostAck({ ok }) {
+            const wasManual = state.pendingHostDraftManual === true;
+            if (ok)
+                api.markSaved(state.pendingHostDraftKey || state.lastSavedDraftKey);
+            return { wasManual };
+        },
+        settleHostAck() {
+            state.pendingHostDraftKey = '';
+            state.pendingHostDraftManual = false;
+            state.inFlight = false;
+            api.syncStatus();
+            if (state.queued) {
+                state.queued = false;
+                api.schedule({ delayMs: 1200 });
+            }
+        },
+    };
+    return api;
+}

package/dist/studio/headerBroadcast.d.ts

@@ -0,0 +1,9 @@
+type Setter = (arg: never) => void;
+/** A header sink implements any subset of the setters. */
+export type HeaderSinkOf<K extends string> = Partial<Record<K, Setter>>;
+export type HeaderBroadcast<Shell extends object, K extends string> = Shell & {
+    /** Push the last value of every header setter into a freshly registered sink. */
+    replayInto(sink: HeaderSinkOf<K> | null | undefined): void;
+};
+export declare function makeHeaderBroadcast<Shell extends object, K extends string>(shell: Shell, getSink: () => HeaderSinkOf<K> | null | undefined, setters: readonly K[]): HeaderBroadcast<Shell, K>;
+export {};

package/dist/studio/headerBroadcast.js

@@ -0,0 +1,37 @@
+// Header-protocol broadcast (the "header sink" seam).
+//
+// A studio controller drives its header imperatively (`shell.setUndoRedoState(...)`,
+// `shell.setHeaderStatus(...)`, …). When a React header mounts over the stage it must show the
+// SAME state, driven by the SAME controller logic — no duplicated per-step rules, one source of
+// truth.
+//
+// `makeHeaderBroadcast` wraps the shell so every listed header setter ALSO fans out to a sink
+// (read live through `getSink`, so a late registration is picked up) and retains its last value,
+// so a sink that registers after the shell was driven can be replayed race-free via `replayInto`.
+// Every other member of the shell passes through untouched.
+export function makeHeaderBroadcast(shell, getSink, setters) {
+    // One slot per setter (all single-arg, last write wins) is the full retained header model.
+    const lastArg = new Map();
+    const call = (fn, self, arg) => {
+        if (typeof fn === 'function')
+            fn.call(self, arg);
+    };
+    // Spread carries the shell's own members (data props and non-header methods). Shell methods
+    // are expected to be closures (no `this`), so copying the references is safe.
+    const wrapper = { ...shell };
+    for (const key of setters) {
+        const original = shell[key];
+        wrapper[key] = (arg) => {
+            call(original, shell, arg);
+            lastArg.set(key, arg);
+            call(getSink()?.[key], undefined, arg);
+        };
+    }
+    wrapper.replayInto = (sink) => {
+        if (!sink)
+            return;
+        for (const [key, arg] of lastArg)
+            call(sink[key], undefined, arg);
+    };
+    return wrapper;
+}

package/dist/studio/history.d.ts

@@ -0,0 +1,37 @@
+export interface HistoryStacks<S> {
+    undo: S[];
+    redo: S[];
+}
+export type HistoryAction = 'push' | 'undo' | 'redo' | 'clear';
+export interface HistoryState {
+    canUndo: boolean;
+    canRedo: boolean;
+}
+export interface HistoryDeps<S> {
+    /** Capture the current editable state. Must return a detached copy (deep clone). */
+    snapshot: () => S;
+    /** Put a previously captured snapshot back as the current state. */
+    restore: (snapshot: S) => void;
+    /** Return false to skip a push (e.g. nothing is loaded yet). */
+    canPush?: () => boolean;
+    /** Oldest entries drop off beyond this many undo steps. */
+    maxHistory?: number;
+    /** Reuse existing stacks instead of fresh ones. */
+    stacks?: HistoryStacks<S>;
+    /** Fires after every change of the stacks, with the action that caused it. */
+    onChange?: (state: HistoryState, action: HistoryAction) => void;
+}
+export interface StudioHistory<S> {
+    readonly stacks: HistoryStacks<S>;
+    /** Record the current state as an undo step. Call BEFORE applying a reversible edit. */
+    push(): void;
+    undo(): boolean;
+    redo(): boolean;
+    clear(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getState(): HistoryState;
+}
+export declare function createHistory<S>(deps: HistoryDeps<S>): StudioHistory<S>;
+/** Deep clone for JSON-shaped studio state — the usual `snapshot()` building block. */
+export declare function cloneJson<T>(value: T): T;

package/dist/studio/history.js

@@ -0,0 +1,50 @@
+// Snapshot-based undo/redo for a studio.
+//
+// The history knows nothing about what it stores: the app injects `snapshot()` (capture the
+// editable state, deep-cloned) and `restore(s)` (put a snapshot back). `onChange` fires after every
+// push/undo/redo/clear so the app can mark its draft dirty, rebuild derived views, and refresh the
+// header's undo/redo buttons. The stacks can be supplied by the caller so an existing controller
+// that already exposes `history.undo` / `history.redo` arrays keeps reading the same arrays.
+export function createHistory(deps) {
+    const { snapshot, restore, canPush, maxHistory = 60, onChange } = deps;
+    const stacks = deps.stacks ?? { undo: [], redo: [] };
+    const getState = () => ({
+        canUndo: stacks.undo.length > 0,
+        canRedo: stacks.redo.length > 0,
+    });
+    const notify = (action) => onChange?.(getState(), action);
+    function step(from, to, action) {
+        if (!from.length)
+            return false;
+        to.push(snapshot());
+        restore(from.pop());
+        notify(action);
+        return true;
+    }
+    return {
+        stacks,
+        push() {
+            if (canPush && !canPush())
+                return;
+            stacks.undo.push(snapshot());
+            if (stacks.undo.length > maxHistory)
+                stacks.undo.shift();
+            stacks.redo.length = 0;
+            notify('push');
+        },
+        undo: () => step(stacks.undo, stacks.redo, 'undo'),
+        redo: () => step(stacks.redo, stacks.undo, 'redo'),
+        clear() {
+            stacks.undo.length = 0;
+            stacks.redo.length = 0;
+            notify('clear');
+        },
+        canUndo: () => stacks.undo.length > 0,
+        canRedo: () => stacks.redo.length > 0,
+        getState,
+    };
+}
+/** Deep clone for JSON-shaped studio state — the usual `snapshot()` building block. */
+export function cloneJson(value) {
+    return value == null ? value : JSON.parse(JSON.stringify(value));
+}

package/dist/studio/hostTransport.d.ts

@@ -0,0 +1,20 @@
+interface WindowLike {
+    location: {
+        origin: string;
+    };
+    parent: WindowLike | null;
+    postMessage(message: unknown, targetOrigin: string, transfer?: Transferable[]): void;
+}
+/**
+ * True for the studio's own origin, a local dev host, or an https plantasia.space origin
+ * (apex or any subdomain).
+ */
+export declare function isTrustedHostOrigin(origin: string | null | undefined, win?: WindowLike | null): boolean;
+/** True when running inside a parent frame. */
+export declare function isEmbedded(win?: WindowLike | null): boolean;
+/**
+ * Post to the parent frame. Returns false (and sends nothing) when there is no recorded host
+ * origin or no parent — never falls back to a '*' broadcast for payloads.
+ */
+export declare function postToHost(message: unknown, targetOrigin: string | null | undefined, transfer?: Transferable[], win?: WindowLike | null): boolean;
+export {};

package/dist/studio/hostTransport.js

@@ -0,0 +1,61 @@
+// The generic half of a studio's host bridge: who may act as the host, and how to talk to it.
+//
+// A studio runs embedded in an iframe of the platform dashboard (or a local dev server). Drafts
+// and captured media are posted back to whichever origin claims the host role, so an arbitrary
+// embedding page must never pass the trust gate, and nothing is ever broadcast to '*' except the
+// initial "ready" ping (which carries no payload).
+//
+// The app-specific half — what a draft looks like, which API saves it, which message types exist
+// — stays in each app and drives an AutosaveSession.
+const TRUSTED_DEV_HOSTNAMES = new Set(['localhost', '127.0.0.1']);
+const TRUSTED_DOMAIN = 'plantasia.space';
+const currentWindow = () => typeof window === 'undefined' ? null : window;
+/**
+ * True for the studio's own origin, a local dev host, or an https plantasia.space origin
+ * (apex or any subdomain).
+ */
+export function isTrustedHostOrigin(origin, win = currentWindow()) {
+    if (!origin || origin === 'null')
+        return false;
+    let url;
+    try {
+        url = new URL(origin);
+    }
+    catch {
+        return false;
+    }
+    if (win && url.origin === win.location.origin)
+        return true;
+    const hostname = url.hostname.toLowerCase();
+    if (TRUSTED_DEV_HOSTNAMES.has(hostname))
+        return true;
+    return url.protocol === 'https:' && (hostname === TRUSTED_DOMAIN || hostname.endsWith(`.${TRUSTED_DOMAIN}`));
+}
+/** True when running inside a parent frame. */
+export function isEmbedded(win = currentWindow()) {
+    try {
+        return Boolean(win?.parent && win.parent !== win);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Post to the parent frame. Returns false (and sends nothing) when there is no recorded host
+ * origin or no parent — never falls back to a '*' broadcast for payloads.
+ */
+export function postToHost(message, targetOrigin, transfer = [], win = currentWindow()) {
+    try {
+        if (!targetOrigin || !win)
+            return false;
+        if (isEmbedded(win)) {
+            ;
+            win.parent.postMessage(message, targetOrigin, transfer);
+            return true;
+        }
+    }
+    catch (err) {
+        console.warn('[Studio] postMessage to host failed', err);
+    }
+    return false;
+}

package/dist/studio/index.d.ts

@@ -0,0 +1,6 @@
+export { createHistory, cloneJson, type StudioHistory, type HistoryDeps, type HistoryStacks, type HistoryState, type HistoryAction, } from './history.js';
+export { createAutosaveSession, type AutosaveSession, type AutosaveState, type AutosaveCtrl, type AutosaveDeps, type AutosaveTone, } from './autosaveSession.js';
+export { createPatchStore, type PatchStore } from './patchStore.js';
+export { makeHeaderBroadcast, type HeaderBroadcast, type HeaderSinkOf } from './headerBroadcast.js';
+export { createStatusChannel, type StatusChannel, type StatusSink, type StatusShowOptions, } from './statusChannel.js';
+export { isTrustedHostOrigin, isEmbedded, postToHost } from './hostTransport.js';

package/dist/studio/index.js

@@ -0,0 +1,9 @@
+// Studio session machinery shared by the Entangled World and Orbiter studios: undo/redo, the
+// autosave state machine, the header mirror (patch store + broadcast/replay), the status line
+// seam, and the host-frame transport. Framework-free: no React, no DOM beyond postMessage.
+export { createHistory, cloneJson, } from './history.js';
+export { createAutosaveSession, } from './autosaveSession.js';
+export { createPatchStore } from './patchStore.js';
+export { makeHeaderBroadcast } from './headerBroadcast.js';
+export { createStatusChannel, } from './statusChannel.js';
+export { isTrustedHostOrigin, isEmbedded, postToHost } from './hostTransport.js';

package/dist/studio/patchStore.d.ts

@@ -0,0 +1,7 @@
+export interface PatchStore<T extends object> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): T;
+    /** Shallow-merge `next` into a new snapshot and notify. No-op when nothing changes. */
+    patch(next: Partial<T>): void;
+}
+export declare function createPatchStore<T extends object>(initial: T): PatchStore<T>;

package/dist/studio/patchStore.js

@@ -0,0 +1,30 @@
+// A tiny external store: an immutable snapshot that is patched and broadcast. Compatible with
+// React's `useSyncExternalStore(store.subscribe, store.getSnapshot)` without importing React.
+// A studio's header store is one of these plus named setters — the mirror of controller state,
+// never its source.
+export function createPatchStore(initial) {
+    let state = initial;
+    const listeners = new Set();
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot: () => state,
+        patch(next) {
+            let changed = false;
+            for (const key of Object.keys(next)) {
+                if (!Object.is(state[key], next[key])) {
+                    changed = true;
+                    break;
+                }
+            }
+            if (!changed)
+                return;
+            state = { ...state, ...next };
+            listeners.forEach((l) => l());
+        },
+    };
+}

package/dist/studio/statusChannel.d.ts

@@ -0,0 +1,12 @@
+export interface StatusShowOptions {
+    /** Hide after this many ms; 0 keeps it until replaced. */
+    autoHideMs?: number;
+}
+export interface StatusSink {
+    show(text: string, opts: Required<StatusShowOptions>): void;
+}
+export interface StatusChannel {
+    setSink(sink: StatusSink | null | undefined): void;
+    show(text: unknown, opts?: StatusShowOptions): void;
+}
+export declare function createStatusChannel(): StatusChannel;

package/dist/studio/statusChannel.js

@@ -0,0 +1,14 @@
+// Studio status line ("Saving…", "Saved", errors). Studio core boots before its UI, so it stays
+// UI-free: it calls `show()`, and the UI layer (a toaster) registers itself as the sink on mount.
+// Calls made while no sink is registered are dropped — status is transient by nature.
+export function createStatusChannel() {
+    let sink = null;
+    return {
+        setSink(next) {
+            sink = next || null;
+        },
+        show(text, { autoHideMs = 0 } = {}) {
+            sink?.show(String(text ?? ''), { autoHideMs });
+        },
+    };
+}