@swirls/looms 0.0.1

package/dist/react/react.js

@@ -0,0 +1,187 @@
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useRef, useSyncExternalStore, } from 'react';
+import { threadTree, toThreadTree } from '@swirls/looms/core';
+import { createFold, foldEvents } from './derived.js';
+import { createLoomsStore, } from './store.js';
+const LoomsContext = createContext({ endpoint: '' });
+const GRACE_MS = 5_000;
+const registry = new Map();
+function registryKey(endpoint, runId) {
+    return `${endpoint}\0${runId}`;
+}
+function disposeEntry(key) {
+    const entry = registry.get(key);
+    if (!entry || entry.refs > 0) {
+        return;
+    }
+    entry.store.dispose();
+    registry.delete(key);
+}
+function peekStore(runId, endpoint, reconnectDelayMs, coalesce) {
+    const key = registryKey(endpoint, runId);
+    const existing = registry.get(key);
+    if (existing) {
+        // SAFETY: registry stores share the app-registered event catalog.
+        return existing.store;
+    }
+    const store = createLoomsStore({
+        storeId: runId,
+        endpoint,
+        reconnectDelayMs,
+        coalesce,
+    });
+    registry.set(key, {
+        // SAFETY: store is created with TEvent which defaults to RegisteredEvent.
+        store: store,
+        refs: 0,
+        timer: setTimeout(() => disposeEntry(key), GRACE_MS),
+    });
+    return store;
+}
+function retainStore(runId, endpoint, reconnectDelayMs, coalesce) {
+    const key = registryKey(endpoint, runId);
+    peekStore(runId, endpoint, reconnectDelayMs, coalesce);
+    const entry = registry.get(key);
+    if (!entry) {
+        return;
+    }
+    entry.refs += 1;
+    if (entry.timer !== undefined) {
+        clearTimeout(entry.timer);
+        entry.timer = undefined;
+    }
+}
+function releaseStore(runId, endpoint) {
+    const key = registryKey(endpoint, runId);
+    const entry = registry.get(key);
+    if (!entry) {
+        return;
+    }
+    entry.refs = Math.max(0, entry.refs - 1);
+    if (entry.refs === 0 && entry.timer === undefined) {
+        entry.timer = setTimeout(() => disposeEntry(key), GRACE_MS);
+    }
+}
+/** Root provider that supplies the Looms host endpoint to run stores. */
+export function LoomsProvider({ children, endpoint = '', coalesce }) {
+    const value = useMemo(() => ({ endpoint, coalesce }), [endpoint, coalesce]);
+    return createElement(LoomsContext.Provider, { value, children });
+}
+/**
+ * Acquires a non-subscribing handle to the run store.
+ * Retains the store in memory while mounted; does NOT trigger component re-renders.
+ * Use data hooks (`useRunEvents`, `useProjection`, `useRunSummary`, etc.) to subscribe.
+ */
+export function useRunStore(runId, options) {
+    const context = useContext(LoomsContext);
+    const endpoint = options?.endpoint ?? context.endpoint;
+    const reconnectDelayMs = options?.reconnectDelayMs;
+    const coalesce = options?.coalesce ?? context.coalesce;
+    const store = peekStore(runId, endpoint, reconnectDelayMs, coalesce);
+    useEffect(() => {
+        retainStore(runId, endpoint, reconnectDelayMs, coalesce);
+        return () => releaseStore(runId, endpoint);
+    }, [runId, endpoint, reconnectDelayMs, coalesce]);
+    return store;
+}
+function useStoreSnapshot(store, getSnapshot) {
+    const subscribe = useCallback((onChange) => store.subscribe(onChange), [store]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+function identitySelector(value) {
+    return value;
+}
+export function useProjection(store, definition, selector, isEqual = Object.is) {
+    const lastSelected = useRef(undefined);
+    const lastState = useRef(undefined);
+    // SAFETY: When selector is undefined, Selected equals S so identitySelector satisfies the signature.
+    const select = selector ?? identitySelector;
+    const getSnapshot = useCallback(() => {
+        const state = store.project(definition);
+        if (lastState.current === state && lastSelected.current !== undefined) {
+            return lastSelected.current;
+        }
+        const nextSelected = select(state);
+        lastState.current = state;
+        if (lastSelected.current !== undefined && isEqual(lastSelected.current, nextSelected)) {
+            return lastSelected.current;
+        }
+        lastSelected.current = nextSelected;
+        return nextSelected;
+    }, [store, definition, select, isEqual]);
+    return useStoreSnapshot(store, getSnapshot);
+}
+/** Subscribe to arbitrary store derivations with an equality check. */
+export function useRunSelector(store, selector, isEqual = Object.is) {
+    const lastSelected = useRef(undefined);
+    const lastVersion = useRef(-1);
+    const getSnapshot = useCallback(() => {
+        const version = store.version();
+        if (lastVersion.current === version && lastSelected.current !== undefined) {
+            return lastSelected.current;
+        }
+        lastVersion.current = version;
+        const nextSelected = selector(store);
+        if (lastSelected.current !== undefined && isEqual(lastSelected.current, nextSelected)) {
+            return lastSelected.current;
+        }
+        lastSelected.current = nextSelected;
+        return nextSelected;
+    }, [store, selector, isEqual]);
+    return useStoreSnapshot(store, getSnapshot);
+}
+function shallowEqualSummary(a, b) {
+    return (a.status === b.status &&
+        a.kind === b.kind &&
+        a.definitionName === b.definitionName &&
+        a.rootThreadId === b.rootThreadId &&
+        a.startedAt === b.startedAt &&
+        a.connection === b.connection);
+}
+/** Lightweight subscription to top-level run metadata and connection status. */
+export function useRunSummary(store) {
+    const selector = useCallback((s) => {
+        const run = s.getState().runs.get(s.storeId);
+        return {
+            status: run?.status ?? 'running',
+            kind: run?.kind ?? undefined,
+            definitionName: run?.definitionName ?? undefined,
+            rootThreadId: run?.rootThreadId ?? undefined,
+            startedAt: s.query.startedAt(),
+            connection: s.status(),
+        };
+    }, []);
+    return useRunSelector(store, selector, shallowEqualSummary);
+}
+/** Subscribe to the event log, optionally scoped to a single thread. */
+export function useRunEvents(store, options) {
+    const threadId = options?.threadId;
+    const getSnapshot = useCallback(() => store.events({ threadId }), [store, threadId]);
+    return useStoreSnapshot(store, getSnapshot);
+}
+/** Subscribe to the thread hierarchy tree. */
+export function useThreadTree(store) {
+    const treeState = useProjection(store, threadTree);
+    return useMemo(() => toThreadTree(treeState), [treeState]);
+}
+/** Subscribe to event count per thread. */
+export function useEventCounts(store) {
+    const getSnapshot = useCallback(() => store.query.counts(), [store]);
+    return useStoreSnapshot(store, getSnapshot);
+}
+/** Subscribe to a single event by its sequence number. */
+export function useEventBySeq(store, seq) {
+    const selector = useCallback((s) => (seq !== undefined ? s.query.bySeq(seq) : undefined), [seq]);
+    return useRunSelector(store, selector);
+}
+/** Subscribe to the latest event of a given type. */
+export function useLatestEvent(store, type) {
+    const selector = useCallback((s) => s.query.latest(type), [type]);
+    return useRunSelector(store, selector);
+}
+/** Subscribe to a custom incremental fold. */
+export function useEventFold(store, fold) {
+    const getSnapshot = useCallback(() => store.fold(fold), [store, fold]);
+    return useStoreSnapshot(store, getSnapshot);
+}
+export { createLoomsStore };
+export { createFold, foldEvents };

package/dist/react/register.d.ts

@@ -0,0 +1,31 @@
+import type { EventEnvelope, EventsOf } from '@swirls/looms/core';
+/** Looser event bound so catalog-inferred payloads (including Schema.Type) are accepted. */
+export type AnyEventEnvelope = EventEnvelope<string, any>;
+/**
+ * Application-level type registry for Looms React/client stores.
+ *
+ * Augment this interface in your app to bind the event catalog used by
+ * `useRunEvents`, `createLoomsStore`, and related hooks:
+ *
+ * ```ts
+ * declare module '@swirls/looms/react' {
+ *   interface LoomsRegister {
+ *     modules: typeof demoModules
+ *   }
+ * }
+ * ```
+ *
+ * You may register either:
+ * - `events`: an explicit event union
+ * - `modules`: a module array / creator function (via `EventsOf`)
+ * - `catalog`: an event catalog or catalog array (via `EventsOf`)
+ */
+export interface LoomsRegister {
+}
+export type RegisteredEvent = LoomsRegister extends {
+    events: infer E;
+} ? E & AnyEventEnvelope : LoomsRegister extends {
+    modules: infer M;
+} ? EventsOf<M> & AnyEventEnvelope : LoomsRegister extends {
+    catalog: infer C;
+} ? EventsOf<C> & AnyEventEnvelope : EventEnvelope;

package/dist/react/register.js

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

package/dist/react/sse.d.ts

@@ -0,0 +1 @@
+export { consumeSseStream, delay, eventsFromSseData, parseSseFrame, type SseFrame, } from '@swirls/looms/client';

package/dist/react/sse.js

@@ -0,0 +1 @@
+export { consumeSseStream, delay, eventsFromSseData, parseSseFrame, } from '@swirls/looms/client';

package/dist/react/store.d.ts

@@ -0,0 +1,56 @@
+import { type EventInput, type ProjectionDefinition } from '@swirls/looms/core';
+import { type EventFoldDefinition } from './derived';
+import { type CoalesceOption } from './notify';
+import type { AnyEventEnvelope, RegisteredEvent } from './register';
+import { type MaterializedTables } from './tables';
+export type { CoalesceOption } from './notify';
+/** Fired after the store version bumps. Re-read via `events()` / `getState()` / `query`. */
+export type StoreListener = () => void;
+export type LoomsConnectionStatus = 'connecting' | 'live' | 'reconnecting';
+export interface LoomsClientStoreOptions {
+    /** Run id for this client store. */
+    storeId: string;
+    /**
+     * Base URL of the Looms host (e.g. http://127.0.0.1:8787).
+     * Opens `${endpoint}/api/events?runId=&live=true` as an SSE stream.
+     */
+    endpoint: string;
+    /** Backoff between SSE reconnects. */
+    reconnectDelayMs?: number;
+    fetch?: typeof fetch;
+    coalesce?: CoalesceOption;
+}
+export interface LoomsStoreQuery<TEvent extends AnyEventEnvelope = RegisteredEvent> {
+    events: (options?: {
+        threadId?: string;
+    }) => readonly TEvent[];
+    runs: () => MaterializedTables['runs'];
+    threads: () => MaterializedTables['threads'];
+    counts: () => ReadonlyMap<string, number>;
+    bySeq: (seq: number) => TEvent | undefined;
+    startedAt: () => number | undefined;
+    latest: (type: string) => TEvent | undefined;
+    fold: <S>(def: EventFoldDefinition<S, TEvent>) => S;
+}
+export interface LoomsClientStore<TEvent extends AnyEventEnvelope = RegisteredEvent> {
+    storeId: string;
+    version: () => number;
+    status: () => LoomsConnectionStatus;
+    getState: () => MaterializedTables;
+    events: (options?: {
+        threadId?: string;
+    }) => readonly TEvent[];
+    query: LoomsStoreQuery<TEvent>;
+    subscribe: (listener: StoreListener) => () => void;
+    project<S>(definition: ProjectionDefinition<S>): S;
+    fold<S>(definition: EventFoldDefinition<S, TEvent>): S;
+    flush: () => void;
+    commit: (event: EventInput) => Promise<void>;
+    sync: () => Promise<void>;
+    dispose: () => void;
+}
+/**
+ * In-memory client store that follows a run's event log over SSE and
+ * materializes generic `runs` / `threads` tables.
+ */
+export declare function createLoomsStore<TEvent extends AnyEventEnvelope = RegisteredEvent>(options: LoomsClientStoreOptions): LoomsClientStore<TEvent>;

package/dist/react/store.js

@@ -0,0 +1,340 @@
+import { Predicate } from 'effect';
+import { decodeLoomsEvent, } from '@swirls/looms/core';
+import { EventIndex, ProjectionCache } from './derived.js';
+import { materializeEvents } from './materialize.js';
+import { createNotifyScheduler } from './notify.js';
+import { consumeSseStream, delay, eventsFromSseData } from './sse.js';
+import { emptyTables } from './tables.js';
+function eventSourceCtor() {
+    if (typeof EventSource === 'undefined') {
+        return undefined;
+    }
+    return EventSource;
+}
+/**
+ * In-memory client store that follows a run's event log over SSE and
+ * materializes generic `runs` / `threads` tables.
+ */
+export function createLoomsStore(options) {
+    const endpoint = options.endpoint.replace(/\/$/, '');
+    const fetchFn = options.fetch ?? fetch;
+    const reconnectDelayMs = options.reconnectDelayMs ?? 1_000;
+    const coalesce = options.coalesce ?? 'adaptive';
+    const listeners = new Set();
+    const events = [];
+    const seenIds = new Set();
+    const projectionCache = new ProjectionCache();
+    const eventIndex = new EventIndex();
+    let eventsSnapshot = Object.freeze([]);
+    let eventsSnapshotDirty = false;
+    let version = 0;
+    let status = 'connecting';
+    let tables = emptyTables();
+    let fromSeq = 1;
+    let disposed = false;
+    let live = false;
+    let liveStarted = false;
+    let liveAbort;
+    let eventSource;
+    let reconnectTimer;
+    let syncing = null;
+    const publishedEvents = () => {
+        if (!eventsSnapshotDirty) {
+            return eventsSnapshot;
+        }
+        // SAFETY: events array only contains TEvent values pushed from applyBatch.
+        eventsSnapshot = Object.freeze(events.slice());
+        eventsSnapshotDirty = false;
+        return eventsSnapshot;
+    };
+    const notify = createNotifyScheduler(coalesce, () => {
+        publishedEvents();
+        for (const listener of listeners) {
+            listener();
+        }
+    });
+    const setStatus = (next) => {
+        if (status === next) {
+            return;
+        }
+        status = next;
+        version += 1;
+        notify.schedule();
+    };
+    const applyBatch = (batch) => {
+        const fresh = [];
+        for (const event of batch) {
+            if (event.seq < fromSeq || seenIds.has(event.id)) {
+                continue;
+            }
+            seenIds.add(event.id);
+            // SAFETY: wire events match the app-registered TEvent catalog at the type boundary.
+            fresh.push(event);
+            fromSeq = Math.max(fromSeq, event.seq + 1);
+        }
+        if (fresh.length === 0) {
+            return;
+        }
+        tables = materializeEvents(fresh, tables);
+        for (const event of fresh) {
+            events.push(event);
+        }
+        eventsSnapshotDirty = true;
+        eventIndex.append(fresh);
+        version += 1;
+        notify.schedule();
+    };
+    const applyEncoded = (data) => {
+        applyBatch(eventsFromSseData(data, options.storeId));
+    };
+    const liveUrl = () => {
+        const cursor = Math.max(0, fromSeq - 1);
+        return `${endpoint}/api/events?runId=${encodeURIComponent(options.storeId)}&live=true&cursor=${cursor}`;
+    };
+    const pull = async () => {
+        try {
+            const cursor = Math.max(0, fromSeq - 1);
+            const url = `${endpoint}/api/events?runId=${encodeURIComponent(options.storeId)}&cursor=${cursor}`;
+            const res = await fetchFn(url);
+            if (!res.ok) {
+                if (res.status === 404 || res.status === 416) {
+                    return;
+                }
+                const text = await res.text();
+                if (text.includes('out of range') || text.includes('Range not satisfiable')) {
+                    return;
+                }
+                throw new Error(`event pull failed: ${res.status}`);
+            }
+            const body = await res.json();
+            if (!Predicate.isReadonlyObject(body)) {
+                return;
+            }
+            const batch = 'batch' in body && Array.isArray(body.batch) ? body.batch : [];
+            applyBatch(batch.map((raw) => decodeLoomsEvent(
+            // SAFETY: host pull batch items are encoded Looms event envelopes.
+            raw, options.storeId)));
+            const head = 'head' in body && Predicate.isNumber(body.head) ? body.head : undefined;
+            if (head !== undefined) {
+                fromSeq = Math.max(fromSeq, head + 1);
+            }
+        }
+        catch (err) {
+            if (disposed) {
+                return;
+            }
+            // When offline or host is restarting, suppress connection refused/fetch errors during sync
+            if (err instanceof Error &&
+                (err.message.includes('fetch failed') ||
+                    err.message.includes('ConnectionRefused') ||
+                    err.message.includes('Unable to connect'))) {
+                return;
+            }
+            throw err;
+        }
+    };
+    const sync = async () => {
+        if (disposed) {
+            return;
+        }
+        if (syncing) {
+            return syncing;
+        }
+        syncing = (async () => {
+            try {
+                await pull();
+            }
+            finally {
+                syncing = null;
+            }
+        })();
+        return syncing;
+    };
+    const scheduleReconnect = (Ctor) => {
+        if (disposed || !liveStarted || reconnectTimer !== undefined) {
+            return;
+        }
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = undefined;
+            if (disposed || !liveStarted) {
+                return;
+            }
+            void sync()
+                .catch(() => { })
+                .finally(() => {
+                if (!disposed && liveStarted) {
+                    startEventSource(Ctor);
+                }
+            });
+        }, reconnectDelayMs);
+    };
+    const startEventSource = (Ctor) => {
+        if (disposed || !liveStarted) {
+            return;
+        }
+        const es = new Ctor(liveUrl());
+        eventSource = es;
+        es.addEventListener('open', () => {
+            live = true;
+            setStatus('live');
+        });
+        es.addEventListener('message', (msg) => {
+            applyEncoded(msg.data);
+        });
+        es.addEventListener('error', () => {
+            live = es.readyState === Ctor.OPEN;
+            if (es.readyState === Ctor.CLOSED && !disposed && liveStarted) {
+                setStatus('reconnecting');
+                // EventSource entered CLOSED state (e.g. server error or socket closed abruptly).
+                // Standard EventSource will NOT automatically reconnect on CLOSED, so we must
+                // clean up the dead instance and re-establish the connection.
+                es.close();
+                if (eventSource === es) {
+                    eventSource = undefined;
+                }
+                scheduleReconnect(Ctor);
+            }
+            else if (!live) {
+                setStatus('reconnecting');
+            }
+        });
+    };
+    const startFetchStream = async () => {
+        while (true) {
+            if (disposed) {
+                break;
+            }
+            const controller = new AbortController();
+            liveAbort = controller;
+            try {
+                const headers = new Headers({ accept: 'text/event-stream' });
+                const cursor = Math.max(0, fromSeq - 1);
+                if (cursor > 0) {
+                    headers.set('last-event-id', String(cursor));
+                }
+                const res = await fetchFn(liveUrl(), { headers, signal: controller.signal });
+                if (!res.ok) {
+                    throw new Error(`event stream failed: ${res.status}`);
+                }
+                if (!res.body) {
+                    throw new Error('event stream missing body');
+                }
+                live = true;
+                setStatus('live');
+                await consumeSseStream(res.body, (frame) => {
+                    applyEncoded(frame.data);
+                }, controller.signal);
+            }
+            catch {
+                live = false;
+                if (disposed) {
+                    return;
+                }
+                setStatus('reconnecting');
+            }
+            live = false;
+            if (disposed) {
+                return;
+            }
+            await delay(reconnectDelayMs, controller.signal);
+        }
+    };
+    const startLive = () => {
+        if (!options.storeId || (liveStarted && !disposed)) {
+            return;
+        }
+        liveStarted = true;
+        disposed = false;
+        const ctor = options.fetch === undefined ? eventSourceCtor() : undefined;
+        if (ctor) {
+            startEventSource(ctor);
+        }
+        else {
+            void startFetchStream();
+        }
+    };
+    const stopLive = () => {
+        liveStarted = false;
+        live = false;
+        if (reconnectTimer !== undefined) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = undefined;
+        }
+        eventSource?.close();
+        eventSource = undefined;
+        liveAbort?.abort();
+        liveAbort = undefined;
+    };
+    if (options.storeId) {
+        startLive();
+    }
+    const readEvents = (filterOptions) => {
+        if (filterOptions?.threadId) {
+            return eventIndex.getByThread(filterOptions.threadId);
+        }
+        return publishedEvents();
+    };
+    const store = {
+        storeId: options.storeId,
+        version: () => version,
+        status: () => status,
+        /**
+         * Live mutable materialized tables. Re-read after each version bump;
+         * do not hold Map/array references across notifies.
+         */
+        getState: () => tables,
+        events: readEvents,
+        query: {
+            events: readEvents,
+            runs: () => tables.runs,
+            threads: () => tables.threads,
+            counts: () => eventIndex.getCounts(),
+            bySeq: (seq) => eventIndex.getBySeq(seq),
+            startedAt: () => eventIndex.getStartedAt(),
+            latest: (type) => eventIndex.getLatest(type),
+            fold: (def) => projectionCache.fold(def, publishedEvents()),
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            listener();
+            if (disposed) {
+                startLive();
+            }
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        project: (definition) => projectionCache.project(definition, publishedEvents()),
+        fold: (definition) => projectionCache.fold(definition, publishedEvents()),
+        flush: notify.flush,
+        sync: async () => {
+            const res = await sync();
+            notify.flush();
+            return res;
+        },
+        commit: async (event) => {
+            const res = await fetchFn(`${endpoint}/runs/${encodeURIComponent(options.storeId)}/events`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(event),
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                throw new Error(`run signal failed: ${res.status} ${text}`);
+            }
+            if (!live) {
+                await sync();
+            }
+            notify.flush();
+        },
+        dispose: () => {
+            disposed = true;
+            notify.cancel();
+            stopLive();
+            listeners.clear();
+            projectionCache.clear();
+            eventIndex.clear();
+        },
+    };
+    return store;
+}

package/dist/react/tables.d.ts

@@ -0,0 +1,21 @@
+export interface RunRow {
+    runId: string;
+    status: string;
+    rootThreadId: string | null;
+    kind: string | null;
+    definitionName: string | null;
+}
+export interface ThreadRow {
+    threadId: string;
+    runId: string;
+    kind: string;
+    definitionName: string;
+    parentThreadId: string | null;
+    status: string;
+}
+/** Materialized run/thread rows. Event log lives only in `store.events()` / EventIndex. */
+export interface MaterializedTables {
+    runs: Map<string, RunRow>;
+    threads: Map<string, ThreadRow>;
+}
+export declare function emptyTables(): MaterializedTables;

package/dist/react/tables.js

@@ -0,0 +1,6 @@
+export function emptyTables() {
+    return {
+        runs: new Map(),
+        threads: new Map(),
+    };
+}

package/dist/runtime/dispatch-effect.d.ts

@@ -0,0 +1,3 @@
+import { Effect, type Layer } from 'effect';
+import { type ComposedRegistry, type EffectContext, type EventInput, type RegisteredDefinition, type RuntimeEffect } from '@swirls/looms/core';
+export declare function dispatchEffect(registry: ComposedRegistry, services: Layer.Layer<any>, definitions: ReadonlyMap<string, RegisteredDefinition>, effect: RuntimeEffect, ctx: EffectContext): Effect.Effect<ReadonlyArray<EventInput>, Error>;