@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/web/runtime.js

@@ -2,22 +2,11 @@
 // 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) over the HTTP transport (→ the local
-// bridge), 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.
-//
-// THE TAP: dispatch calls `onIntent(name, payload, state)` BEFORE delegating to
-// core.intents[name]. This is the host-level pre-dispatch hook the shell uses to
-// observe/intercept semantic intents (e.g. canvas `activate` → open a
-// conversation). When onIntent is undefined the loop is byte-identical to the
-// pre-shell behavior — a view in a ViewPane is unaware it is in a shell.
-//
-// THE SEAM (Wave 3): store.refresh() forces an immediate, busy-guarded refresh.
-// It is both the auto-poll callback AND the entry point the shell calls when an
-// SSE `/__crtr/events` invalidation arrives — event-driven refresh with no
-// contract change (the view still just runs its `refresh` intent).
+// (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
@@ -25,7 +14,8 @@ import { createHttpTransport } from './transport-http.js';
  *  and re-renders off subscribe/getVersion; this factory is React-free. */
 export function createViewStore(core, opts = {}) {
     const transport = createHttpTransport(opts.endpoint);
-    let state = core.init(Object.freeze({ ...(opts.options ?? {}) }));
+    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
@@ -45,6 +35,13 @@ export function createViewStore(core, opts = {}) {
         // 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) {
@@ -59,20 +56,87 @@ export function createViewStore(core, opts = {}) {
             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,
+        dispatch(intent, payload) {
+            return runIntent(intent, payload);
+        },
     });
-    // busyDepth counts in-flight async intents — it drives the "working" chip /
-    // spinner. It is NOT itself the single-flight lane; the auto-poll guards on it
-    // (refresh() below) so a bridge slower than refreshMs can never stack
-    // overlapping refreshes that race on ctx.set. The first completed *refresh*
-    // marks the view loaded (ready vs idle in deriveState) — a non-refresh async
-    // intent before that must not flip the chip to ready.
-    let busyDepth = 0;
-    async function dispatch(intent, payload) {
-        // THE TAP — the shell observes (and may act on) every intent against a
-        // snapshot of state BEFORE the view's own handler runs. Standalone (no tap)
-        // this is a no-op and the loop is byte-identical to the pre-shell behavior.
+    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) {
@@ -80,48 +144,83 @@ export function createViewStore(core, opts = {}) {
             console.warn(`[crtr view] unknown intent: ${intent}`);
             return;
         }
-        const result = fn(makeCtx(), payload);
+        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;
-            setChrome({ busy: true });
+            if (!wasBusy)
+                setChrome({ busy: true });
             try {
                 await result;
             }
             finally {
                 busyDepth -= 1;
-                const loaded = chrome.loaded || intent === 'refresh';
-                chrome = { ...chrome, busy: busyDepth > 0, loaded, lastRefresh: Date.now() };
+                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);
     }
-    // Auto-poll cadence guard AND the shell's invalidate seam: skip while any
-    // async intent is still in flight so refreshes never stack.
-    const refresh = () => { if (busyDepth === 0)
-        void dispatch('refresh'); };
-    let started = false;
-    let timer = null;
+    const refresh = () => {
+        if (busyDepth === 0)
+            void enqueueDispatch('refresh');
+    };
     function start() {
         if (started)
             return;
         started = true;
-        // init → render (the React layer) → first refresh, then optional auto-poll.
-        void dispatch('refresh');
+        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,
+        dispatch: enqueueDispatch,
         refresh,
         subscribe,
         getVersion: () => version,

package/dist/web/transport-http.js

@@ -1,8 +1,7 @@
-// transport-http.ts — the browser-side Transport. Posts a view's declarative
-// SourceRequest to the local bridge server (`crtr view serve`'s /__crtr/source)
-// and returns the RawResponse the bridge ran on its behalf. This is the ONE
-// seam a cloud deploy swaps: point the endpoint at a real backend and the same
-// browser bundle resolves sources against it, no core change.
+// 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.
+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. */
@@ -24,5 +23,8 @@ export function createHttpTransport(endpoint = '/__crtr/source') {
                 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 node focus ${target} or crtr canvas 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;
+}