@north-light/crouter 0.3.154

package/dist/web/runtime.js

@@ -0,0 +1,232 @@
+// runtime.tsx — the framework-agnostic dispatch-loop STORE for a dual-target
+// view. It is what <ViewPane>/useViewCore (ViewPane.tsx) are built from.
+//
+// createViewStore() seeds state from core.init, builds the IntentCtx
+// (set/resolve/execute/signal/dispatch/connect) over the HTTP transport, runs
+// the dispatch loop with the busy-guarded refreshMs auto-poll, and exposes a
+// tiny external-store surface (subscribe/getVersion) the React layer binds via
+// useSyncExternalStore. The core it drives is byte-identical to the TUI's; only
+// the injected Transport differs.
+import { initialChrome } from '../core/view/chrome.js';
+import { createHttpTransport } from './transport-http.js';
+/** Build the running store for one view (its core + the HTTP transport). The
+ *  React layer (useViewCore) owns lifecycle (start on mount, stop on unmount)
+ *  and re-renders off subscribe/getVersion; this factory is React-free. */
+export function createViewStore(core, opts = {}) {
+    const transport = createHttpTransport(opts.endpoint);
+    const initOptions = Object.freeze({ ...(opts.options ?? {}) });
+    let state = core.init(initOptions);
+    let chrome = initialChrome();
+    let onIntentTap = opts.onIntent;
+    // External store: a version counter the React tree subscribes to. state and
+    // chrome are read via the getters on each render; bumping `version` re-renders.
+    let version = 0;
+    const listeners = new Set();
+    const emit = () => { version += 1; for (const l of listeners)
+        l(); };
+    const subscribe = (l) => { listeners.add(l); return () => { listeners.delete(l); }; };
+    const setChrome = (patch) => { chrome = { ...chrome, ...patch }; emit(); };
+    const signal = {
+        setStatus: (msg) => setChrome({ status: msg }),
+        setBanner: (msg, level) => setChrome({ banner: { msg, level } }),
+        clearBanner: () => setChrome({ banner: null }),
+        setSubtitle: (s) => setChrome({ subtitle: s }),
+        setMode: (mode) => setChrome({ mode }),
+        // Web has no pane to leave; closing the tab is up to the user. No-op.
+        quit: () => { },
+    };
+    const streams = new Set();
+    let generation = 0;
+    let started = false;
+    let timer = null;
+    let busyDepth = 0;
+    let drainingQueue = false;
+    let dispatchQueue = [];
+    const makeCtx = () => ({
+        get state() { return state; },
+        set(next) {
+            state = typeof next === 'function' ? next(state) : next;
+            emit();
+        },
+        async resolve(source, args) {
+            const raw = await transport.send(source.request(args));
+            return source.parse(raw);
+        },
+        async execute(command, args) {
+            const raw = await transport.send(command.request(args));
+            return command.parse(raw);
+        },
+        connect(source, args) {
+            const capturedGeneration = generation;
+            let channel;
+            channel = transport.open(source.request(args), {
+                onFrame(frame) {
+                    if (capturedGeneration !== generation)
+                        return;
+                    void enqueueDispatch(source.onFrame, frame);
+                },
+                onClose(reason) {
+                    if (capturedGeneration !== generation)
+                        return;
+                    streams.delete(channel);
+                    if (source.onClose)
+                        void enqueueDispatch(source.onClose, { reason, channelId: channel.id });
+                },
+                onError(err) {
+                    if (capturedGeneration !== generation)
+                        return;
+                    setChrome({ banner: { msg: err.display.headline, level: err.display.level } });
+                },
+            });
+            streams.add(channel);
+            if (source.onOpen)
+                void enqueueDispatch(source.onOpen, channel);
+            return channel;
+        },
+        signal,
+        dispatch(intent, payload) {
+            return runIntent(intent, payload);
+        },
+    });
+    function scheduleDrain() {
+        if (drainingQueue)
+            return;
+        drainingQueue = true;
+        void drainQueue();
+    }
+    async function drainQueue() {
+        try {
+            while (started && dispatchQueue.length > 0) {
+                if (busyDepth > 0)
+                    return;
+                const job = dispatchQueue.shift();
+                try {
+                    await runIntent(job.intent, job.payload);
+                    job.resolve();
+                }
+                catch (err) {
+                    job.reject(err);
+                }
+            }
+        }
+        finally {
+            drainingQueue = false;
+            if (started && dispatchQueue.length > 0 && busyDepth === 0)
+                scheduleDrain();
+        }
+    }
+    function enqueueDispatch(intent, payload) {
+        if (!started)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            dispatchQueue.push({ intent, payload, resolve, reject });
+            scheduleDrain();
+        });
+    }
+    function settleAfterIntent(intentName) {
+        if (intentName === 'refresh') {
+            chrome = { ...chrome, busy: busyDepth > 0, loaded: true, lastRefresh: Date.now() };
+            emit();
+            return;
+        }
+        chrome = { ...chrome, busy: busyDepth > 0 };
+        emit();
+    }
+    async function runIntent(intent, payload) {
+        if (!started) {
+            // The store is stopped; ignore stray external work.
+            return;
+        }
+        onIntentTap?.(intent, payload, state);
+        const fn = core.intents[intent];
+        if (!fn) {
+            // eslint-disable-next-line no-console
+            console.warn(`[crtr view] unknown intent: ${intent}`);
+            return;
+        }
+        let result;
+        try {
+            result = fn(makeCtx(), payload);
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.warn(`[crtr view] intent ${intent} threw:`, e);
+            throw e;
+        }
+        if (result instanceof Promise) {
+            const wasBusy = busyDepth > 0;
+            busyDepth += 1;
+            if (!wasBusy)
+                setChrome({ busy: true });
+            try {
+                await result;
+            }
+            finally {
+                busyDepth -= 1;
+                chrome = { ...chrome, busy: busyDepth > 0, loaded: chrome.loaded || intent === 'refresh', lastRefresh: Date.now() };
+                emit();
+                if (busyDepth === 0 && started && dispatchQueue.length > 0)
+                    scheduleDrain();
+            }
+            return;
+        }
+        settleAfterIntent(intent);
+    }
+    const refresh = () => {
+        if (busyDepth === 0)
+            void enqueueDispatch('refresh');
+    };
+    function start() {
+        if (started)
+            return;
+        started = true;
+        generation += 1;
+        state = core.init(initOptions);
+        chrome = initialChrome();
+        dispatchQueue = [];
+        drainingQueue = false;
+        void enqueueDispatch('refresh');
+        const cadence = core.manifest.refreshMs;
+        if (typeof cadence === 'number' && cadence > 0)
+            timer = setInterval(refresh, cadence);
+    }
+    function stop() {
+        if (!started)
+            return;
+        started = false;
+        generation += 1;
+        const openChannels = Array.from(streams);
+        for (const channel of openChannels) {
+            try {
+                channel.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        streams.clear();
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+        if (dispatchQueue.length > 0) {
+            const err = new Error('view stopped');
+            for (const job of dispatchQueue)
+                job.reject(err);
+            dispatchQueue = [];
+        }
+        drainingQueue = false;
+    }
+    return {
+        getState: () => state,
+        getChrome: () => chrome,
+        dispatch: enqueueDispatch,
+        refresh,
+        subscribe,
+        getVersion: () => version,
+        start,
+        stop,
+        get onIntent() { return onIntentTap; },
+        set onIntent(v) { onIntentTap = v; },
+    };
+}

package/dist/web/states.d.ts

@@ -0,0 +1,24 @@
+import type { JSX } from 'react';
+/** Initial load, before the first source resolves. */
+export declare function Loading({ label }: {
+    label?: string;
+}): JSX.Element;
+/** Resolved, but nothing to show. */
+export declare function Empty({ label }: {
+    label?: string;
+}): JSX.Element;
+/** A non-blocking-or-blocking failure — renders a SourceError.display verbatim. */
+export declare function ErrorState({ headline, explanation, nextStep, onRetry }: {
+    headline: string;
+    explanation?: string;
+    nextStep?: string;
+    onRetry?: () => void;
+}): JSX.Element;
+/** A precondition isn't met (e.g. not a repo / unauthed) — same shape as
+ *  ErrorState but named for the "not ready to run here" case. */
+export declare function NotReady({ headline, explanation, nextStep, onRetry }: {
+    headline?: string;
+    explanation?: string;
+    nextStep?: string;
+    onRetry?: () => void;
+}): JSX.Element;

package/dist/web/states.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function Center({ children }) {
+    return (_jsx("div", { className: "flex min-h-[40vh] flex-col items-center justify-center gap-2 p-8 text-center font-mono text-sm text-slate-600", children: children }));
+}
+/** Initial load, before the first source resolves. */
+export function Loading({ label = 'Loading…' }) {
+    return (_jsxs(Center, { children: [_jsx("span", { className: "inline-block h-3 w-3 animate-spin rounded-full border-2 border-slate-300 border-t-slate-600" }), _jsx("span", { children: label })] }));
+}
+/** Resolved, but nothing to show. */
+export function Empty({ label = 'Nothing here yet.' }) {
+    return (_jsx(Center, { children: _jsx("span", { className: "text-slate-400", children: label }) }));
+}
+/** A non-blocking-or-blocking failure — renders a SourceError.display verbatim. */
+export function ErrorState({ headline, explanation, nextStep, onRetry }) {
+    return (_jsxs(Center, { children: [_jsx("div", { className: "font-semibold text-red-700", children: headline }), explanation ? _jsx("div", { className: "text-slate-600", children: explanation }) : null, nextStep ? _jsx("div", { className: "text-slate-500", children: nextStep }) : null, onRetry ? _jsx(RetryButton, { onRetry: onRetry }) : null] }));
+}
+/** A precondition isn't met (e.g. not a repo / unauthed) — same shape as
+ *  ErrorState but named for the "not ready to run here" case. */
+export function NotReady({ headline = 'Not ready', explanation, nextStep, onRetry }) {
+    return (_jsxs(Center, { children: [_jsx("div", { className: "font-semibold text-amber-700", children: headline }), explanation ? _jsx("div", { className: "text-slate-600", children: explanation }) : null, nextStep ? _jsx("div", { className: "text-slate-500", children: nextStep }) : null, onRetry ? _jsx(RetryButton, { onRetry: onRetry }) : null] }));
+}
+function RetryButton({ onRetry }) {
+    return (_jsx("button", { type: "button", onClick: onRetry, className: "mt-2 rounded border border-slate-300 px-3 py-1 text-slate-700 hover:bg-slate-100", children: "Retry" }));
+}

package/dist/web/transport-http.d.ts

@@ -0,0 +1,5 @@
+import type { Transport } from '../core/view/transport.js';
+/** Browser Transport → POST <endpoint> {SourceRequest} → RawResponse. Never
+ *  throws: a network/bridge failure becomes a transport-level RawResponse
+ *  (ok:false + stderr), exactly like the local transport's spawn failures. */
+export declare function createHttpTransport(endpoint?: string): Transport;

package/dist/web/transport-http.js

@@ -0,0 +1,34 @@
+// transport-http.ts — the browser-side Transport. send() posts declarative
+// SourceRequests to the local bridge server (`crtr view serve`'s /__crtr/source)
+// and open() connects browser stream requests to the same-origin WS relay.
+//
+// P2 DEFERRAL (Stage-C, plan C-1/C-5): the browser data plane still rides
+// `/__crtr/source` (the dev-shell bridge), NOT crtrd `/v1`. Moving the SPA onto
+// the crtrd API is a settled P2 deferral, not a P1 defect — leave as-is.
+import { openBrowserStream } from './transport-stream.js';
+/** Browser Transport → POST <endpoint> {SourceRequest} → RawResponse. Never
+ *  throws: a network/bridge failure becomes a transport-level RawResponse
+ *  (ok:false + stderr), exactly like the local transport's spawn failures. */
+export function createHttpTransport(endpoint = '/__crtr/source') {
+    return {
+        async send(req) {
+            try {
+                const res = await fetch(endpoint, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify(req),
+                });
+                if (!res.ok) {
+                    return { ok: false, stdout: '', stderr: `bridge ${res.status} ${res.statusText}` };
+                }
+                return (await res.json());
+            }
+            catch (e) {
+                return { ok: false, stdout: '', stderr: e instanceof Error ? e.message : String(e) };
+            }
+        },
+        open(req, handlers) {
+            return openBrowserStream(req, handlers);
+        },
+    };
+}

package/dist/web/transport-stream.d.ts

@@ -0,0 +1,3 @@
+import type { StreamRequest, StreamChannel } from '../core/view/contract.js';
+import type { StreamHandlers } from '../core/view/transport.js';
+export declare function openBrowserStream(req: StreamRequest, handlers: StreamHandlers): StreamChannel;

package/dist/web/transport-stream.js

@@ -0,0 +1,204 @@
+import { classify } from '../core/fault-classifier.js';
+function streamUrl(target) {
+    const url = new URL(`/node/${encodeURIComponent(target)}`, window.location.href);
+    url.protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const token = new URLSearchParams(window.location.search).get('token');
+    if (token !== null && token !== '')
+        url.searchParams.set('token', token);
+    return url;
+}
+function classifyClose(ev) {
+    const classification = classify('browser↔relay', { code: ev.code, reason: ev.reason });
+    if (ev.code === 1008 || classification.kind === 'protocol')
+        return 'invalid';
+    if (ev.code === 1011 && /^no node /.test(ev.reason))
+        return 'no-node';
+    if (ev.code === 1011 && /^no running broker/.test(ev.reason))
+        return 'no-broker';
+    return 'transient';
+}
+function makeNoBrokerError(target) {
+    return {
+        kind: 'browser-stream-no-broker',
+        display: {
+            headline: `node ${target} is asleep or has no running broker`,
+            explanation: 'This browser stream connects only to an already-running local broker.',
+            nextStep: `Run crtr surface node focus ${target} or crtr node lifecycle revive ${target}, then reconnect.`,
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+function makeNoNodeError(target) {
+    return {
+        kind: 'browser-stream-no-node',
+        display: {
+            headline: `node ${target} does not exist`,
+            explanation: 'The browser relay could not find a live node with that id.',
+            nextStep: 'Choose a valid node id, then reconnect.',
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+function makeInvalidError(target) {
+    return {
+        kind: 'browser-stream-invalid',
+        display: {
+            headline: `node ${target} was rejected by the relay`,
+            explanation: 'The browser relay closed the stream because the request was not valid.',
+            nextStep: 'Fix the node id or connection parameters, then reconnect.',
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+export function openBrowserStream(req, handlers) {
+    const channelId = globalThis.crypto.randomUUID();
+    let socket = null;
+    let closedByView = false;
+    let closeReported = false;
+    let reconnectTimer = null;
+    let reconnectDelayMs = 200;
+    const clearReconnectTimer = () => {
+        if (reconnectTimer !== null) {
+            window.clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+    };
+    const reportTerminalClose = (reason, error) => {
+        if (closeReported)
+            return;
+        closeReported = true;
+        clearReconnectTimer();
+        socket = null;
+        if (error !== undefined) {
+            try {
+                handlers.onError(error);
+            }
+            catch {
+                /* ignore handler failures */
+            }
+        }
+        try {
+            handlers.onClose(reason);
+        }
+        catch {
+            /* ignore handler failures */
+        }
+    };
+    const scheduleReconnect = () => {
+        if (closedByView || closeReported)
+            return;
+        clearReconnectTimer();
+        reconnectTimer = window.setTimeout(() => {
+            reconnectTimer = null;
+            if (!closedByView && !closeReported)
+                connect();
+        }, reconnectDelayMs);
+        reconnectDelayMs = Math.min(reconnectDelayMs * 2, 1000);
+    };
+    const connect = () => {
+        if (closedByView || closeReported)
+            return;
+        const url = streamUrl(req.target);
+        let ws;
+        try {
+            ws = new WebSocket(url);
+        }
+        catch {
+            scheduleReconnect();
+            return;
+        }
+        socket = ws;
+        ws.onopen = () => {
+            if (closedByView || closeReported)
+                return;
+            reconnectDelayMs = 200;
+            try {
+                ws.send(JSON.stringify({ type: 'hello', role: req.role ?? 'controller', client_id: channelId }));
+            }
+            catch {
+                /* ignore send failures; close will report if needed */
+            }
+        };
+        ws.onmessage = (ev) => {
+            if (typeof ev.data !== 'string')
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(ev.data);
+            }
+            catch {
+                return;
+            }
+            try {
+                handlers.onFrame(frame);
+            }
+            catch {
+                /* ignore handler failures */
+            }
+        };
+        ws.onclose = (ev) => {
+            if (socket === ws)
+                socket = null;
+            const reason = ev.reason || `closed (${ev.code})`;
+            if (closedByView) {
+                reportTerminalClose(reason);
+                return;
+            }
+            const kind = classifyClose(ev);
+            if (kind === 'transient') {
+                scheduleReconnect();
+                return;
+            }
+            if (kind === 'no-broker') {
+                reportTerminalClose(reason, makeNoBrokerError(req.target));
+                return;
+            }
+            if (kind === 'no-node') {
+                reportTerminalClose(reason, makeNoNodeError(req.target));
+                return;
+            }
+            reportTerminalClose(reason, makeInvalidError(req.target));
+        };
+        ws.onerror = () => {
+            /* onclose does the actual reporting */
+        };
+    };
+    const channel = {
+        id: channelId,
+        send(frame) {
+            const ws = socket;
+            if (ws === null || ws.readyState !== WebSocket.OPEN)
+                return;
+            try {
+                ws.send(JSON.stringify(frame));
+            }
+            catch {
+                /* ignore dead socket */
+            }
+        },
+        close() {
+            closedByView = true;
+            clearReconnectTimer();
+            const ws = socket;
+            if (ws === null) {
+                reportTerminalClose('closed by view');
+                return;
+            }
+            if (ws.readyState === WebSocket.CLOSED) {
+                reportTerminalClose('closed by view');
+                return;
+            }
+            try {
+                ws.close();
+            }
+            catch {
+                reportTerminalClose('closed by view');
+            }
+        },
+    };
+    connect();
+    return channel;
+}