@kestack/kabuki 0.0.0-stage → 0.0.1

package/dist/core/snapshot/tree.d.ts

@@ -0,0 +1,26 @@
+import type { ActorDefinition } from '../actor/index.ts';
+import type { Instance, Snapshot } from './snapshot.ts';
+export declare const childId: (parent: string, slot: string, key: string | undefined, generation: number) => string;
+/** What the parent counts its Invocations of a Child under. */
+export declare const counterOf: (slot: string, key: string | undefined) => string;
+/** Whether `id` is `ancestor` or below it. */
+export declare const within: (ancestor: string, id: string) => boolean;
+/** The slot under `parent` on the way down to `id`, if `id` is below it. */
+export declare const slotToward: (parent: string, id: string) => string | undefined;
+/** Tells a keyed Child slot from a fixed one in an Instance's Children. */
+export declare const isMany: (held: Instance | ReadonlyArray<Instance>) => held is ReadonlyArray<Instance>;
+/** One Instance on the way down, with its Actor and the slot it sits in. */
+export interface Step {
+    readonly instance: Instance;
+    readonly definition: ActorDefinition;
+    readonly slot: string;
+}
+/** The Instances from the root down to `id`, with their Actors; none if it is gone. */
+export declare const pathTo: (root: ActorDefinition, snapshot: Snapshot, id: string) => ReadonlyArray<Step> | undefined;
+/** The Snapshot with the last Instance of `path` replaced by `after`. Every Instance off the path stays the same object. */
+export declare const replace: (path: ReadonlyArray<Step>, after: Instance) => Snapshot;
+/** The Instance with this ID, if it is in the Snapshot. */
+export declare const instanceAt: (snapshot: Snapshot, id: string) => Instance | undefined;
+/** The Actor of the Instance with this ID, if it is in the Snapshot. */
+export declare const actorAt: (root: ActorDefinition, snapshot: Snapshot, id: string) => ActorDefinition | undefined;
+//# sourceMappingURL=tree.d.ts.map

package/dist/core/snapshot/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../../src/core/snapshot/tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAcxD,eAAO,MAAM,OAAO,WACV,MAAM,QACR,MAAM,OACP,MAAM,GAAG,SAAS,cACX,MAAM,KACjB,MAC0F,CAAC;AAE9F,+DAA+D;AAC/D,eAAO,MAAM,SAAS,SAAU,MAAM,OAAO,MAAM,GAAG,SAAS,KAAG,MACA,CAAC;AAEnE,8CAA8C;AAC9C,eAAO,MAAM,MAAM,aAAc,MAAM,MAAM,MAAM,KAAG,OACJ,CAAC;AAEnD,4EAA4E;AAC5E,eAAO,MAAM,UAAU,WAAY,MAAM,MAAM,MAAM,KAAG,MAAM,GAAG,SAKhE,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,MAAM,SACX,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC,KACvC,IAAI,IAAI,aAAa,CAAC,QAAQ,CAAwB,CAAC;AAE1D,4EAA4E;AAC5E,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,uFAAuF;AACvF,eAAO,MAAM,MAAM,SACX,eAAe,YACX,QAAQ,MACd,MAAM,KACT,aAAa,CAAC,IAAI,CAAC,GAAG,SAexB,CAAC;AAEF,4HAA4H;AAC5H,eAAO,MAAM,OAAO,SAAU,aAAa,CAAC,IAAI,CAAC,SAAS,QAAQ,KAAG,QAa1D,CAAC;AAEZ,2DAA2D;AAC3D,eAAO,MAAM,UAAU,aACX,QAAQ,MACd,MAAM,KACT,QAAQ,GAAG,SAQb,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,OAAO,SACZ,eAAe,YACX,QAAQ,MACd,MAAM,KACT,eAAe,GAAG,SAC2B,CAAC"}

package/dist/core/snapshot/tree.js

@@ -0,0 +1,77 @@
+/*
+ * The tree: where each Instance sits. An Instance's ID is its path from the
+ * root: its parent's ID, the Child's name, its key if it has one, and how
+ * many times the parent has Invoked that Child. So the same Messages always
+ * give the same IDs, an Instance Invoked again gets a new one, and finding
+ * an Instance walks straight down to it.
+ *
+ *   Auth                  the root, named after its Actor
+ *   Auth/api#2            the second `api` Auth Invoked
+ *   Auth/api#2/rows[a]#1  the first `rows` keyed `a` under it
+ */
+export const childId = (parent, slot, key, generation) => `${parent}/${slot}${key === undefined ? '' : `[${encodeURIComponent(key)}]`}#${generation}`;
+/** What the parent counts its Invocations of a Child under. */
+export const counterOf = (slot, key) => key === undefined ? slot : `${slot}[${encodeURIComponent(key)}]`;
+/** Whether `id` is `ancestor` or below it. */
+export const within = (ancestor, id) => id === ancestor || id.startsWith(`${ancestor}/`);
+/** The slot under `parent` on the way down to `id`, if `id` is below it. */
+export const slotToward = (parent, id) => {
+    if (!id.startsWith(`${parent}/`))
+        return undefined;
+    const rest = id.slice(parent.length + 1);
+    const end = rest.search(/[[#]/);
+    return end < 0 ? undefined : rest.slice(0, end);
+};
+/** Tells a keyed Child slot from a fixed one in an Instance's Children. */
+export const isMany = (held) => Array.isArray(held);
+/** The Instances from the root down to `id`, with their Actors; none if it is gone. */
+export const pathTo = (root, snapshot, id) => {
+    const path = [
+        { instance: snapshot, definition: root, slot: '' },
+    ];
+    for (let step = path[0]; step.instance.id !== id;) {
+        const slot = slotToward(step.instance.id, id);
+        if (slot === undefined)
+            return undefined;
+        const definition = step.definition.children[step.instance.state._tag]?.[slot]?.definition;
+        const child = childToward(step.instance.children[slot], id);
+        if (!definition || !child)
+            return undefined;
+        step = { instance: child, definition, slot };
+        path.push(step);
+    }
+    return path;
+};
+/** The Snapshot with the last Instance of `path` replaced by `after`. Every Instance off the path stays the same object. */
+export const replace = (path, after) => path.slice(0, -1).reduceRight((child, { instance }, index) => {
+    const { slot } = path[index + 1];
+    const held = instance.children[slot];
+    return {
+        ...instance,
+        children: {
+            ...instance.children,
+            [slot]: isMany(held)
+                ? held.map((kept) => (kept.id === child.id ? child : kept))
+                : child,
+        },
+    };
+}, after);
+/** The Instance with this ID, if it is in the Snapshot. */
+export const instanceAt = (snapshot, id) => {
+    let instance = snapshot;
+    while (instance && instance.id !== id) {
+        const slot = slotToward(instance.id, id);
+        instance =
+            slot === undefined ? undefined : childToward(instance.children[slot], id);
+    }
+    return instance;
+};
+/** The Actor of the Instance with this ID, if it is in the Snapshot. */
+export const actorAt = (root, snapshot, id) => pathTo(root, snapshot, id)?.at(-1)?.definition;
+const childToward = (held, id) => held === undefined
+    ? undefined
+    : isMany(held)
+        ? held.find((child) => within(child.id, id))
+        : within(held.id, id)
+            ? held
+            : undefined;

package/dist/react/app.d.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+import { Cause } from 'effect';
+import type { Layer } from 'effect';
+import { History } from '../core/index.ts';
+import type { AnyActor, Entry, Needs, SavedHistory, WorkerStatus } from '../core/index.ts';
+import type { ViewOf } from './view.tsx';
+type Unmet<A, Provided> = [Exclude<Needs<A>, Provided>] extends [never] ? [] : [unmet: {
+    readonly missingCapabilities: Exclude<Needs<A>, Provided>;
+}];
+/** A Step: right after an entry, or right after init. */
+type Step = number | 'init';
+export interface AppOptions {
+    /**
+     * What the app is called: the History its last mount leaves is picked up
+     * by the next mount of an app with this name, after a hot reload too. By
+     * default the root Actor's name.
+     */
+    readonly name?: string;
+    /** A History saved before: the app is first drawn at its Head, and its Runtime carries on from there. */
+    readonly saved?: SavedHistory;
+}
+/** The running app, for code outside the tree: a timeline, a devtool. */
+export interface AppRuntime<A = AnyActor> {
+    readonly history: History<A>;
+    /** The current Branch: every entry from the first to the Head. */
+    readonly branch: ReadonlyArray<Entry>;
+    readonly head: number | null;
+    readonly running: boolean;
+    /** The Step the Views show, or `null` for live. */
+    readonly shown: Step | null;
+    readonly show: (step: Step | null) => void;
+    /** Start at the Head, or at an entry (`null`: init), growing a new Branch from it. */
+    readonly start: (from?: number | null) => void;
+    readonly stop: () => void;
+    /** Forget the whole History and go live from init. */
+    readonly clear: () => void;
+    /** What an Instance's Workers are doing now. Empty while stopped. */
+    readonly workers: (instance: string) => ReadonlyArray<WorkerStatus>;
+    /** Why the last start, stop or clear failed, also logged; `null` once one succeeds. */
+    readonly failure: Cause.Cause<unknown> | null;
+}
+export declare const toReact: <A extends AnyActor, Provided>(actor: A, view: ViewOf<A>, layer: Layer.Layer<Provided, never, never>, options?: AppOptions, ..._unmet: Unmet<A, Provided>) => (({ fallback }: {
+    readonly fallback?: ReactNode;
+}) => import("react").JSX.Element) & {
+    displayName: string;
+    useRuntime: () => AppRuntime<A>;
+};
+export {};
+//# sourceMappingURL=app.d.ts.map

package/dist/react/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/react/app.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAAE,KAAK,EAA8B,MAAM,QAAQ,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,OAAO,EAAW,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EACV,QAAQ,EACR,KAAK,EACL,KAAK,EAEL,YAAY,EAEZ,YAAY,EACb,MAAM,kBAAkB,CAAC;AAI1B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAkBzC,KAAK,KAAK,CAAC,CAAC,EAAE,QAAQ,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,GACnE,EAAE,GACF,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;CAAE,CAAC,CAAC;AAE3E,yDAAyD;AACzD,KAAK,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE5B,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yGAAyG;IACzG,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAC/B;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,QAAQ;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3C,sFAAsF;IACtF,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,aAAa,CAAC,YAAY,CAAC,CAAC;IACpE,uFAAuF;IACvF,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;CAC/C;AAID,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,QAAQ,EAAE,QAAQ,SAC3C,CAAC,QACF,MAAM,CAAC,CAAC,CAAC,SACR,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,YACjC,UAAU,aACR,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,qBAoMK;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE;;sBAWjD,UAAU,CAAC,CAAC,CAAC;CAqBhC,CAAC"}

package/dist/react/app.js

@@ -0,0 +1,214 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// oxlint-disable-next-line no-restricted-imports -- the app's one mount effect: counting mounts starts and stops the Runtime, which lives outside React.
+import { Suspense, use, useEffect, useSyncExternalStore } from 'react';
+import { Cause, Effect, Exit, Fiber, Scope } from 'effect';
+import { History, Runtime } from '../core/index.js';
+import { makeDrawn } from './drawn.js';
+import { registry } from './registry.js';
+import { AppContext } from './view.js';
+const NO_WORKERS = [];
+export const toReact = (actor, view, layer, options = {}, ..._unmet) => {
+    const RootView = view;
+    const name = options.name ?? actor.definition.name;
+    const root = { id: actor.definition.name };
+    const app = {};
+    const own = () => options.saved ? History.load(actor, options.saved) : History.make(actor);
+    /** The History an app of this name holds or left, read with this code, else its own. */
+    const adopt = () => {
+        const left = registry.history(name);
+        return left ? History.load(actor, left.save()) : own();
+    };
+    let history;
+    let first;
+    let runtime;
+    let shown = null;
+    let past;
+    let failure = null;
+    const listeners = new Set();
+    let seen;
+    const changed = () => {
+        seen = undefined;
+        for (const listener of listeners)
+            listener();
+    };
+    let unwatch = () => { };
+    const take = (next) => {
+        unwatch();
+        history = next;
+        first = undefined;
+        unwatch = next.subscribe(changed);
+        return next;
+    };
+    const historyOf = () => history ?? take(adopt());
+    /** What came of a start, stop or clear: an interruption is a newer one taking over, not a failure. */
+    const settled = (what) => (exit) => {
+        if (Exit.isSuccess(exit)) {
+            if (failure === null)
+                return;
+            failure = null;
+        }
+        else {
+            if (Cause.hasInterruptsOnly(exit.cause))
+                return;
+            console.error(`[@kestack/kabuki] ${name} could not ${what}:\n${Cause.pretty(exit.cause)}`);
+            failure = exit.cause;
+        }
+        changed();
+    };
+    // 1. Draw
+    /** Start replaying the History to its Head, once: what the app draws before its Runtime starts. */
+    const firstDraw = () => {
+        if (first)
+            return first;
+        const from = historyOf();
+        const draw = { snapshot: undefined, replaying: undefined };
+        draw.replaying =
+            from.head() === null
+                ? fulfilled((draw.snapshot = from.snapshotAt(null)))
+                : tracked(Effect.runPromise(from.seek()).then((snapshot) => {
+                    draw.snapshot = snapshot;
+                    changed();
+                    return snapshot;
+                }));
+        return (first = draw);
+    };
+    /** Before the Runtime starts, wait for the first Snapshot: React shows the fallback until it is replayed. */
+    const waitForFirstDraw = () => {
+        const { snapshot, replaying } = firstDraw();
+        if (!snapshot)
+            use(replaying);
+    };
+    const snapshot = () => shown === null ? (runtime?.snapshot() ?? first?.snapshot) : past;
+    const drawn = makeDrawn(snapshot, () => first?.snapshot, (id, message) => {
+        if (shown === null)
+            runtime?.send(id, message, { kind: 'view', instance: id });
+    }, (listener) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+    });
+    // 2. Mount
+    let mounts = 0;
+    let close = () => { };
+    let unsubscribe = () => { };
+    const mount = () => {
+        if (mounts++ === 0) {
+            if (!registry.claim(name, app, historyOf())) {
+                console.error(`[@kestack/kabuki] two apps named ${name} are mounted at once; they cannot share a History`);
+                take(own());
+                changed();
+            }
+            let open = true;
+            close = () => {
+                open = false;
+            };
+            firstDraw().replaying.then(() => {
+                if (!open)
+                    return;
+                close = host(historyOf(), layer, (exit) => {
+                    if (Exit.isSuccess(exit)) {
+                        unsubscribe();
+                        runtime = exit.value;
+                        unsubscribe = exit.value.subscribe(changed);
+                        changed();
+                    }
+                    settled('start')(exit);
+                });
+            }, (error) => {
+                console.error(`[@kestack/kabuki] ${name} could not be drawn, so its Runtime did not start`, error);
+            });
+        }
+        return () => {
+            if (--mounts === 0) {
+                registry.release(name, app);
+                close();
+            }
+        };
+    };
+    // 3. Show
+    let showing;
+    const show = (step) => {
+        showing?.interruptUnsafe();
+        if (step === null) {
+            shown = null;
+            past = undefined;
+            return changed();
+        }
+        showing = Effect.runFork(historyOf()
+            .seek(step === 'init' ? null : step)
+            .pipe(Effect.map((snapshot) => {
+            past = snapshot;
+            shown = step;
+            changed();
+        })));
+    };
+    const control = (what, effect) => {
+        if (effect)
+            Effect.runFork(effect).addObserver(settled(what));
+    };
+    const start = (from) => control('start', runtime?.start(from));
+    const stop = () => control('stop', runtime?.stop());
+    const clear = () => control('clear its History', Effect.gen(function* () {
+        yield* runtime?.stop() ?? Effect.void;
+        historyOf().clear();
+        yield* runtime?.start() ?? Effect.void;
+    }));
+    const read = () => (seen ??= {
+        head: historyOf().head(),
+        running: runtime?.running() ?? false,
+        shown,
+        failure,
+    });
+    const Drawn = () => {
+        if (!runtime)
+            waitForFirstDraw();
+        return (_jsx(AppContext, { value: drawn, children: _jsx(RootView, { instance: root }) }));
+    };
+    const App = ({ fallback = null }) => {
+        useEffect(mount, []);
+        return (_jsx(Suspense, { fallback: fallback, children: _jsx(Drawn, {}) }));
+    };
+    return Object.assign(App, {
+        displayName: name,
+        useRuntime: () => {
+            const { head, running, shown, failure } = useSyncExternalStore(drawn.subscribe, read, read);
+            return {
+                history: historyOf(),
+                branch: historyOf().branch(head),
+                head,
+                running,
+                shown,
+                show,
+                start,
+                stop,
+                clear,
+                workers: (instance) => runtime?.workers(instance) ?? NO_WORKERS,
+                failure,
+            };
+        },
+    });
+};
+const fulfilled = (value) => Object.assign(Promise.resolve(value), { status: 'fulfilled', value });
+const tracked = (promise) => {
+    const thenable = Object.assign(promise, { status: 'pending' });
+    promise.then((value) => Object.assign(thenable, { status: 'fulfilled', value }), (reason) => Object.assign(thenable, { status: 'rejected', reason }));
+    return thenable;
+};
+/**
+ * Start the Runtime under one Scope, and say how the start went; a failed
+ * one closes the Scope. Returns a function that closes the Scope: every
+ * Command and Worker ends, then the Layer.
+ */
+const host = (history, layer, onSettled) => {
+    const scope = Scope.makeUnsafe();
+    const starting = Effect.runFork(Runtime.start(history, ...[layer]).pipe(Scope.provide(scope)));
+    starting.addObserver((exit) => {
+        if (Exit.isFailure(exit))
+            void Effect.runPromise(Scope.close(scope, exit));
+        onSettled(exit);
+    });
+    // A start still under way is interrupted first, so nothing is built into a
+    // closed Scope (React StrictMode unmounts right after the first mount).
+    return () => {
+        void Effect.runPromise(Fiber.interrupt(starting).pipe(Effect.andThen(Scope.close(scope, Exit.void))));
+    };
+};

package/dist/react/child.d.ts

@@ -0,0 +1,32 @@
+import type { Handle, ViewProps } from './view.tsx';
+/**
+ * What a parent View can read of one Child: what the Child's own View draws
+ * from, but not its Children and nothing to Send with. Reading never changes
+ * the app, and it reaches one level down only.
+ */
+export type ChildData<A> = ViewProps<A> extends infer P ? P extends unknown ? Omit<P, 'children' | 'send' | 'root'> : never : never;
+interface UseChild {
+    <A>(handle: Handle<A>): ChildData<A> | undefined;
+    <A, S>(handle: Handle<A>, select: (child: ChildData<A>) => S): S | undefined;
+}
+/**
+ * Reads one fixed Child from its parent's View: its Model, State and Props,
+ * at the Step drawn; `undefined` once the Child has stopped. The component
+ * re-renders when they change, or, given a selector, only when what it picks
+ * changes. An escape hatch for drawing only: what a parent must act on, it
+ * owns.
+ */
+export declare const useChild: UseChild;
+interface UseChildren {
+    <A>(handles: ReadonlyArray<Handle<A>>): ReadonlyArray<ChildData<A>>;
+    <A, S>(handles: ReadonlyArray<Handle<A>>, select: (child: ChildData<A>) => S): ReadonlyArray<S>;
+}
+/**
+ * Reads a slot of keyed Children from their parent's View, in the slot's
+ * order, leaving out any that stopped. The component re-renders when one of
+ * them changes or the list does, or, given a selector, only when what it
+ * picks from one of them changes or the list does.
+ */
+export declare const useChildren: UseChildren;
+export {};
+//# sourceMappingURL=child.d.ts.map

package/dist/react/child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child.d.ts","sourceRoot":"","sources":["../../src/react/child.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAsB,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAExE;;;;GAIG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IACrB,SAAS,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,GACxB,CAAC,SAAS,OAAO,GACf,IAAI,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC,GACrC,KAAK,GACP,KAAK,CAAC;AA6CZ,UAAU,QAAQ;IAChB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IACjD,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CAC9E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,EAAE,QAiBtB,CAAC;AAEF,UAAU,WAAW;IACnB,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC,CAAC,EAAE,CAAC,EACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EACjC,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,GACjC,aAAa,CAAC,CAAC,CAAC,CAAC;CACrB;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,EAAE,WAyBzB,CAAC"}

package/dist/react/child.js

@@ -0,0 +1,80 @@
+import { use, useRef, useSyncExternalStore } from 'react';
+import { AppContext } from './view.js';
+// One read-only copy per drawn Instance, so it stays the same object while
+// the Instance does.
+const reads = new WeakMap();
+const readOf = (drawn) => {
+    if (!drawn)
+        return undefined;
+    let read = reads.get(drawn);
+    if (!read) {
+        const { _tag, id, model, state, props } = drawn;
+        reads.set(drawn, (read = { _tag, id, model, state, props }));
+    }
+    return read;
+};
+const useDrawn = (hook) => {
+    const drawn = use(AppContext);
+    if (!drawn)
+        throw new Error(`[@kestack/kabuki] ${hook} is used outside its app`);
+    return drawn;
+};
+/**
+ * What a selector picked from each Child, kept per Child read, so a Child
+ * that did not change is not picked from again. A new selector, as an inline
+ * one is on every render, starts over.
+ */
+const usePicked = (select) => {
+    const memo = useRef(undefined);
+    if (!memo.current || memo.current.select !== select)
+        memo.current = { select, picked: new WeakMap() };
+    const { picked } = memo.current;
+    return (read) => {
+        if (!select)
+            return read;
+        if (!picked.has(read))
+            picked.set(read, select(read));
+        return picked.get(read);
+    };
+};
+/**
+ * Reads one fixed Child from its parent's View: its Model, State and Props,
+ * at the Step drawn; `undefined` once the Child has stopped. The component
+ * re-renders when they change, or, given a selector, only when what it picks
+ * changes. An escape hatch for drawing only: what a parent must act on, it
+ * owns.
+ */
+export const useChild = (handle, select) => {
+    const drawn = useDrawn('useChild');
+    const pick = usePicked(select);
+    const last = useRef(undefined);
+    const from = (read) => () => {
+        const child = readOf(read(handle.id));
+        const next = child && pick(child);
+        return Object.is(next, last.current) ? last.current : (last.current = next);
+    };
+    return useSyncExternalStore(drawn.subscribe, from(drawn.instance), from(drawn.served));
+};
+/**
+ * Reads a slot of keyed Children from their parent's View, in the slot's
+ * order, leaving out any that stopped. The component re-renders when one of
+ * them changes or the list does, or, given a selector, only when what it
+ * picks from one of them changes or the list does.
+ */
+export const useChildren = (handles, select) => {
+    const drawn = useDrawn('useChildren');
+    const pick = usePicked(select);
+    const last = useRef([]);
+    const from = (read) => () => {
+        const next = handles.flatMap((handle) => {
+            const child = readOf(read(handle.id));
+            return child ? [pick(child)] : [];
+        });
+        const was = last.current;
+        if (next.length === was.length &&
+            next.every((value, index) => Object.is(value, was[index])))
+            return was;
+        return (last.current = next);
+    };
+    return useSyncExternalStore(drawn.subscribe, from(drawn.instance), from(drawn.served));
+};

package/dist/react/drawn.d.ts

@@ -0,0 +1,4 @@
+import type { Snapshot, Tagged } from '../core/index.ts';
+import type { DrawnApp } from './view.tsx';
+export declare const makeDrawn: (drawn: () => Snapshot | undefined, served: () => Snapshot | undefined, deliver: (id: string, message: Tagged) => void, subscribe: DrawnApp['subscribe']) => DrawnApp;
+//# sourceMappingURL=drawn.d.ts.map

package/dist/react/drawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drawn.d.ts","sourceRoot":"","sources":["../../src/react/drawn.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAsB,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAY,QAAQ,EAAU,MAAM,YAAY,CAAC;AAW7D,eAAO,MAAM,SAAS,UACb,MAAM,QAAQ,GAAG,SAAS,UACzB,MAAM,QAAQ,GAAG,SAAS,WACzB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,aACnC,QAAQ,CAAC,WAAW,CAAC,KAC/B,QA0FF,CAAC"}

package/dist/react/drawn.js

@@ -0,0 +1,118 @@
+import { instanceAt, isMany } from '../core/index.js';
+/*
+ * What Views read: what any Instance is drawn from, out of the Snapshot drawn
+ * now. It stays the same object while the Instance's Model, State, Props and
+ * Children's IDs stay the same, so a View re-renders only when its own
+ * Instance changes.
+ * A View of the past, of a stopped app, or of an app whose Runtime has not
+ * started cannot Send. What it keeps for an Instance is let go once the
+ * Instance is in neither Snapshot.
+ */
+export const makeDrawn = (drawn, served, deliver, subscribe) => {
+    const handles = new Map();
+    const sends = new Map();
+    const cache = new Map();
+    const handleOf = ({ id, key }) => {
+        let handle = handles.get(id);
+        if (!handle)
+            handles.set(id, (handle = key === undefined ? { id } : { id, key }));
+        return handle;
+    };
+    const sendTo = (id) => {
+        let send = sends.get(id);
+        if (!send)
+            sends.set(id, (send = (message) => {
+                deliver(id, message);
+            }));
+        return send;
+    };
+    const propsIn = (cache, snapshot, id) => {
+        const instance = snapshot && instanceAt(snapshot, id);
+        const hit = cache.get(id);
+        if (!instance) {
+            cache.delete(id);
+            return undefined;
+        }
+        if (hit && (hit.instance === instance || same(hit.instance, instance))) {
+            hit.instance = instance;
+            return hit.props;
+        }
+        const next = {
+            _tag: instance.state._tag,
+            id,
+            model: instance.model,
+            state: instance.state,
+            props: instance.props,
+            // The same object while the Children's IDs stay the same, so a memoized
+            // component or a `useMemo` given them sees no change.
+            children: hit && sameIds(hit.instance, instance)
+                ? hit.props.children
+                : Object.fromEntries(Object.entries(instance.children).map(([slot, held]) => [
+                    slot,
+                    isMany(held) ? held.map(handleOf) : handleOf(held),
+                ])),
+            send: sendTo(id),
+        };
+        cache.set(id, { instance, props: next });
+        return next;
+    };
+    const onServer = new Map();
+    /** Forget every Instance in neither Snapshot, once per new Snapshot drawn, so keyed Children coming and going leave nothing behind. */
+    let pruned;
+    const prune = () => {
+        const now = drawn();
+        if (now === pruned)
+            return;
+        pruned = now;
+        const live = new Set();
+        idsIn(now, live);
+        idsIn(served(), live);
+        for (const kept of [handles, sends, cache, onServer])
+            for (const id of kept.keys())
+                if (!live.has(id))
+                    kept.delete(id);
+    };
+    return {
+        subscribe,
+        instance: (id) => {
+            prune();
+            return propsIn(cache, drawn(), id);
+        },
+        served: (id) => {
+            prune();
+            const snapshot = served();
+            return snapshot === drawn()
+                ? propsIn(cache, snapshot, id)
+                : propsIn(onServer, snapshot, id);
+        },
+    };
+};
+const idsIn = (instance, ids) => {
+    if (!instance)
+        return;
+    ids.add(instance.id);
+    for (const held of Object.values(instance.children))
+        for (const child of isMany(held) ? held : [held])
+            idsIn(child, ids);
+};
+const same = (a, b) => a.model === b.model &&
+    a.state === b.state &&
+    a.props === b.props &&
+    sameIds(a, b);
+const sameIds = (a, b) => {
+    if (a.children === b.children)
+        return true;
+    const slots = Object.keys(b.children);
+    if (slots.length !== Object.keys(a.children).length)
+        return false;
+    return slots.every((slot) => {
+        const was = a.children[slot];
+        const is = b.children[slot];
+        if (!was)
+            return false;
+        if (!isMany(is) || !isMany(was))
+            return !isMany(is) && !isMany(was) && is.id === was.id;
+        return (is.length === was.length &&
+            is.every((kid, index) => kid.id === was[index].id));
+    });
+};

package/dist/react/index.d.ts

@@ -0,0 +1,7 @@
+export { toReact } from './app.tsx';
+export { View } from './view.tsx';
+export { useChild, useChildren } from './child.ts';
+export type { Handle, Root, ViewOf, ViewProps } from './view.tsx';
+export type { ChildData } from './child.ts';
+export type { AppOptions, AppRuntime } from './app.tsx';
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,3 @@
+export { toReact } from './app.js';
+export { View } from './view.js';
+export { useChild, useChildren } from './child.js';

package/dist/react/registry.d.ts

@@ -0,0 +1,12 @@
+import type { History } from '../core/index.ts';
+export declare const registry: {
+    /** The History of the app mounted under this name, else the one its last mount left. */
+    history: (name: string) => History | undefined;
+    /** Note that `app` is mounted with its History; false if another app of that name already is. */
+    claim: (name: string, app: object, history: History) => boolean;
+    /** Leave the History as the app closes. */
+    release: (name: string, app: object) => void;
+    /** Forget every app: for tests. */
+    clear: () => void;
+};
+//# sourceMappingURL=registry.d.ts.map

package/dist/react/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/react/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAyBhD,eAAO,MAAM,QAAQ;IACnB,wFAAwF;IACxF,OAAO,SAAS,MAAM,KAAG,OAAO,GAAG,SAAS;IAC5C,iGAAiG;IACjG,KAAK,SAAS,MAAM,OAAO,MAAM,WAAW,OAAO,KAAG,OAAO;IAM7D,2CAA2C;IAC3C,OAAO,SAAS,MAAM,OAAO,MAAM;IAInC,mCAAmC;IACnC,KAAK;CACN,CAAC"}