@north-light/crouter 0.3.154

package/dist/core/view/loader.js

@@ -0,0 +1,188 @@
+// loader.ts — resolve + load dual-target (core.mjs) views across scopes.
+//
+// A view = a directory containing `core.mjs` (the portable core). Up to three
+// presenter files sit beside it: `tui.mjs` (Node), `web.jsx`/`web.tsx` (browser,
+// via Vite — NEVER Node-imported), `text.mjs` (Node, piped path). Targets are
+// derived from which presenter files exist — no manifest field.
+//
+// Resolution order: project → user → builtin, first hit wins (scope.ts
+// viewsDir). Node-side loads are plain `import(pathToFileURL())` — no
+// transpile, no bundle. A directory without a `core.mjs` is not a view.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { viewsDir } from '../scope.js';
+import { InputError } from '../io.js';
+const SCOPE_ORDER = ['project', 'user', 'builtin'];
+function probe(dir, scope, id) {
+    const core = join(dir, 'core.mjs');
+    if (!existsSync(core))
+        return null;
+    const tui = join(dir, 'tui.mjs');
+    const webJsx = join(dir, 'web.jsx');
+    const webTsx = join(dir, 'web.tsx');
+    const text = join(dir, 'text.mjs');
+    return {
+        id, dir, scope, core,
+        tui: existsSync(tui) ? tui : null,
+        web: existsSync(webJsx) ? webJsx : existsSync(webTsx) ? webTsx : null,
+        text: existsSync(text) ? text : null,
+    };
+}
+/** Scope search project→user→builtin; first hit wins. null if no scope holds a
+ *  `<name>/core.mjs`. */
+export function resolveView(name) {
+    for (const scope of SCOPE_ORDER) {
+        const root = viewsDir(scope);
+        if (!root)
+            continue;
+        const r = probe(join(root, name), scope, name);
+        if (r)
+            return r;
+    }
+    return null;
+}
+/** Find a directory named `name` across scopes even when it holds no core.mjs —
+ *  lets a caller distinguish "no such view" from "a dir that isn't a valid view"
+ *  (e.g. a pre-contract `view.mjs`-only dir) and name the contract in the error. */
+export function findViewDir(name) {
+    for (const scope of SCOPE_ORDER) {
+        const root = viewsDir(scope);
+        if (!root)
+            continue;
+        const dir = join(root, name);
+        try {
+            if (statSync(dir).isDirectory())
+                return dir;
+        }
+        catch { /* not here */ }
+    }
+    return null;
+}
+/** Enumerate every resolvable core-shaped view across scopes (first scope wins
+ *  per id). Targets per view are derivable from the tui/web/text fields. */
+export function listViews() {
+    const seen = new Set();
+    const out = [];
+    for (const scope of SCOPE_ORDER) {
+        const root = viewsDir(scope);
+        if (!root || !existsSync(root))
+            continue;
+        let names;
+        try {
+            names = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.sort()) {
+            if (seen.has(name))
+                continue; // first scope wins
+            const dir = join(root, name);
+            let isDir = false;
+            try {
+                isDir = statSync(dir).isDirectory();
+            }
+            catch {
+                isDir = false;
+            }
+            if (!isDir)
+                continue;
+            const r = probe(dir, scope, name);
+            if (!r)
+                continue;
+            seen.add(name);
+            out.push(r);
+        }
+    }
+    return out;
+}
+/** Import + validate the portable core. Throws a guided error if malformed. */
+export async function loadCore(r) {
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(r.core).href));
+    }
+    catch (e) {
+        throw guided(r, 'core.mjs', `failed to import: ${errText(e)}`);
+    }
+    const c = mod['default'];
+    if (!c || typeof c !== 'object')
+        throw guided(r, 'core.mjs', 'no default export that is a ViewCore object');
+    const m = c.manifest;
+    if (!m || typeof m.id !== 'string' || typeof m.title !== 'string') {
+        throw guided(r, 'core.mjs', 'manifest.id and manifest.title must be strings');
+    }
+    if (typeof c.init !== 'function')
+        throw guided(r, 'core.mjs', 'init() is required');
+    if (!c.intents || typeof c.intents !== 'object')
+        throw guided(r, 'core.mjs', 'intents must be an object of intent functions');
+    return c;
+}
+/** Import + validate the TUI presenter. Call requireTui first. */
+export async function loadTui(r) {
+    if (!r.tui)
+        throw notTarget(r, 'tui');
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(r.tui).href));
+    }
+    catch (e) {
+        throw guided(r, 'tui.mjs', `failed to import: ${errText(e)}`);
+    }
+    // Accept named exports { render, keymap } or a default-exported object.
+    const candidate = (typeof mod['render'] === 'function' ? mod : mod['default']);
+    if (!candidate || typeof candidate.render !== 'function')
+        throw guided(r, 'tui.mjs', 'render(state, draw, content) is required');
+    if (!Array.isArray(candidate.keymap))
+        throw guided(r, 'tui.mjs', 'keymap must be an array of key bindings');
+    return candidate;
+}
+/** Import the text presenter if present; null otherwise (the host synthesizes a
+ *  generic one-line dump when a view ships no text.mjs). */
+export async function loadText(r) {
+    if (!r.text)
+        return null;
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(r.text).href));
+    }
+    catch (e) {
+        throw guided(r, 'text.mjs', `failed to import: ${errText(e)}`);
+    }
+    const candidate = (typeof mod['dump'] === 'function' ? mod : mod['default']);
+    if (!candidate || typeof candidate.dump !== 'function')
+        throw guided(r, 'text.mjs', 'dump(state, ctx) is required');
+    return candidate;
+}
+/** Per-host presenter validation: `view run` requires a TUI presenter. */
+export function requireTui(r) {
+    if (!r.tui) {
+        throw new InputError({
+            error: 'view_web_only',
+            message: `'${r.id}' is web-only — it ships no tui.mjs presenter`,
+            next: 'Open it in the browser through the surface web server.',
+        });
+    }
+}
+/** Per-host presenter validation: `view serve` requires a web presenter. */
+export function requireWeb(r) {
+    if (!r.web) {
+        throw new InputError({
+            error: 'view_tui_only',
+            message: `'${r.id}' is tui-only — it ships no web.jsx presenter`,
+            next: 'Open it in a tmux pane with the surface view run leaf.',
+        });
+    }
+}
+function notTarget(r, target) {
+    return new Error(`view "${r.id}" has no ${target} presenter`);
+}
+function guided(r, file, problem) {
+    return new Error(`invalid view "${r.id}" (${r.scope}) at ${join(r.dir, file)}: ${problem}.\n` +
+        'A dual-target view dir holds core.mjs (default export: { manifest: { id, title }, init(), intents }) ' +
+        'plus optional tui.mjs (render + keymap), web.jsx, text.mjs (dump).');
+}
+function errText(e) {
+    return e instanceof Error ? e.message : String(e);
+}

package/dist/core/view/remote-canvas-target.d.ts

@@ -0,0 +1,4 @@
+import type { Scope, RemoteCanvasTarget } from '../../types.js';
+import type { RelayTarget } from '../broker-client/index.js';
+export declare function getRemoteCanvasTarget(name: string, scope?: Scope): RemoteCanvasTarget | undefined;
+export declare function resolveRemoteCanvasTarget(name: string, scope?: Scope): RelayTarget;

package/dist/core/view/remote-canvas-target.js

@@ -0,0 +1,30 @@
+// remote-canvas-target.ts — resolves a named `remoteCanvas.targets.<name>`
+// config entry (see `RemoteCanvasTarget`, `src/types.ts`) into a `RelayTarget`
+// ready for `RelayTransport` (`src/core/broker-client/transport-relay.ts`).
+//
+// The raw bearer token NEVER lives in config.json — only a ref
+// (`relayTokenRef`) into the 0600 secrets store (`src/core/secrets.ts`),
+// resolved here at connect time via `getRelayToken`. Targets are registered
+// and the token stored via `crtr canvas config add` (`--relay-token -` reads
+// it from stdin, the preferred form to keep it out of shell history).
+import { usage } from '../errors.js';
+import { readConfig } from '../config.js';
+import { getRelayToken } from '../secrets.js';
+export function getRemoteCanvasTarget(name, scope = 'user') {
+    return readConfig(scope).remoteCanvas.targets[name];
+}
+export function resolveRemoteCanvasTarget(name, scope = 'user') {
+    const cfg = readConfig(scope);
+    const target = cfg.remoteCanvas.targets[name];
+    if (target === undefined) {
+        const known = Object.keys(cfg.remoteCanvas.targets);
+        throw usage(`no remote canvas target named '${name}'` +
+            (known.length > 0 ? ` — configured: ${known.join(', ')}` : ' — none configured yet') +
+            `. Add one with \`crtr canvas config add ${name} --preview <url> --relay-token -\`.`);
+    }
+    const relayToken = getRelayToken(target.relayTokenRef, scope);
+    if (relayToken === undefined || relayToken === '') {
+        throw usage(`target '${name}' has no stored relay token — add it with \`crtr canvas config add ${name} --relay-token -\`.`);
+    }
+    return { previewEndpoint: target.previewEndpoint, relayToken };
+}

package/dist/core/view/stream-local.d.ts

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

package/dist/core/view/stream-local.js

@@ -0,0 +1,231 @@
+import { randomUUID } from 'node:crypto';
+import { CrtrClient, ApiError } from '../../api/index.js';
+import { BrokerClient, BrokerUnavailableError } from '../broker-client/index.js';
+function makeInvalidTargetError(target) {
+    return {
+        kind: 'invalid-target',
+        display: {
+            headline: `invalid stream target: ${target}`,
+            explanation: 'Stream targets must be plain node ids.',
+            nextStep: 'Use a node id without /, \\, or .., then reconnect.',
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+function makeNoNodeError(target) {
+    return {
+        kind: 'no-node',
+        display: {
+            headline: `node ${target} does not exist`,
+            explanation: 'No node with that id was found in the canvas.',
+            nextStep: 'Check the node id and try again.',
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+function makeNoBrokerError(target) {
+    return {
+        kind: 'broker-unavailable',
+        display: {
+            headline: `node ${target} has no running broker`,
+            explanation: 'The stream transport connects only to an already-running broker.',
+            nextStep: `Run crtr surface node focus ${target} or crtr node lifecycle revive ${target}, then reconnect.`,
+            level: 'error',
+            blocking: false,
+        },
+    };
+}
+function isValidTarget(target) {
+    return target.length > 0 && !target.includes('/') && !target.includes('\\') && !target.includes('..');
+}
+// A local view stream is a pure broker-IPC consumer (view.sock), so the ONE
+// canvas-state fact it needs — does the node exist, and has it reached a terminal
+// status — goes through crtrd's /v1 API (CrtrClient over the local socket), never
+// a direct canvas-db read: a CLI/view leaf must not open the store (V-1). One
+// lazy client; `autostart: false` because merely observing a node must not boot
+// the daemon.
+let sharedApiClient = null;
+function apiClient() {
+    sharedApiClient ??= CrtrClient.forLocalSocket({ autostart: false });
+    return sharedApiClient;
+}
+/** Node presence for the two facts this stream needs, resolved through the API.
+ *  `live` = exists and not terminal (proceed / keep reconnecting); `terminal` =
+ *  done|dead|canceled (give up); `gone` = definitively absent, a 404 (no-node);
+ *  `unknown` = the daemon was unreachable or errored — we can't tell, so we NEVER
+ *  falsely claim absence: the existence check proceeds to the broker path (which
+ *  reports no-broker), and reconnect KEEPS RETRYING (only a confirmed
+ *  `terminal`/`gone` gives up), so a transient daemon blip can't kill a
+ *  recoverable stream. */
+async function nodePresence(target) {
+    try {
+        const status = (await apiClient().getNode(target)).status;
+        if (status === 'done' || status === 'dead' || status === 'canceled')
+            return 'terminal';
+        return 'live';
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return 'gone';
+        return 'unknown';
+    }
+}
+export function openLocalStream(req, handlers) {
+    const channelId = randomUUID();
+    const role = req.role ?? 'controller';
+    let client = null;
+    let closedByView = false;
+    let closeReported = false;
+    let reconnecting = false;
+    let everConnected = false;
+    let initialBrokerUnavailableReported = false;
+    const channel = {
+        id: channelId,
+        send(frame) {
+            client?.send(frame);
+        },
+        close() {
+            closedByView = true;
+            try {
+                client?.close();
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+    };
+    const terminalClose = (reason) => {
+        if (closeReported || closedByView)
+            return;
+        closeReported = true;
+        try {
+            client?.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            handlers.onClose(reason);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+    const reportError = (err) => {
+        if (closeReported || closedByView)
+            return;
+        try {
+            handlers.onError(err);
+        }
+        catch {
+            /* best-effort */
+        }
+    };
+    const deferTerminalFailure = (reason, err) => {
+        queueMicrotask(() => {
+            reportError(err);
+            terminalClose(reason);
+        });
+    };
+    if (!isValidTarget(req.target)) {
+        deferTerminalFailure('invalid stream target', makeInvalidTargetError(req.target));
+        return channel;
+    }
+    const sendHello = () => {
+        client?.send({ type: 'hello', role, client_id: channelId });
+    };
+    const reconnect = async () => {
+        // reconnect only runs after begin() sets `client` and a first connect, so
+        // `client` is non-null here; the guard keeps that a hard invariant.
+        if (closedByView || closeReported || reconnecting || client === null)
+            return;
+        reconnecting = true;
+        let delay = 200;
+        try {
+            while (!closedByView && !closeReported) {
+                try {
+                    await client.redial();
+                    // Reconnected: the broker is serving frames again. Do NOT re-check
+                    // presence here — a slow or `unknown` status call must never tear
+                    // down a stream that has just successfully reconnected.
+                    return;
+                }
+                catch {
+                    if (closedByView || closeReported)
+                        return;
+                    // Redial failed. Give up ONLY when the node is confirmed no longer
+                    // reachable: a terminal status (done|dead|canceled) or a definitive
+                    // 404. `live` and `unknown` (daemon slow/restarting under load) both
+                    // keep retrying — a transient blip must not kill a recoverable stream.
+                    const presence = await nodePresence(req.target);
+                    if (presence === 'terminal' || presence === 'gone') {
+                        terminalClose('broker connection closed');
+                        return;
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    delay = Math.min(delay * 2, 1000);
+                }
+            }
+        }
+        finally {
+            reconnecting = false;
+        }
+    };
+    // The existence check is a canvas-state read routed through the API, so it is
+    // async: the channel is returned synchronously (callers rely on that) while the
+    // node lookup settles on a later tick. A definitively-absent node (404) reports
+    // no-node then closes; a present or indeterminate node proceeds to open the
+    // broker socket (a missing broker then reports no-broker via the error path).
+    const begin = async () => {
+        if (closedByView || closeReported)
+            return;
+        if ((await nodePresence(req.target)) === 'gone') {
+            reportError(makeNoNodeError(req.target));
+            terminalClose('no node');
+            return;
+        }
+        if (closedByView || closeReported)
+            return;
+        client = new BrokerClient(req.target, { emitUnmatchedDataFrames: true });
+        client.on('connect', () => {
+            if (closedByView || closeReported)
+                return;
+            everConnected = true;
+            sendHello();
+        });
+        client.on('frame', (frame) => {
+            if (closedByView || closeReported)
+                return;
+            try {
+                handlers.onFrame(frame);
+            }
+            catch {
+                /* best-effort */
+            }
+        });
+        client.on('error', (err) => {
+            if (closedByView || closeReported)
+                return;
+            if (err instanceof BrokerUnavailableError && !everConnected && !initialBrokerUnavailableReported) {
+                initialBrokerUnavailableReported = true;
+                reportError(makeNoBrokerError(req.target));
+            }
+        });
+        client.on('close', () => {
+            if (closedByView || closeReported)
+                return;
+            if (reconnecting)
+                return;
+            if (!everConnected) {
+                terminalClose('node has no running broker');
+                return;
+            }
+            void reconnect();
+        });
+        client.connect();
+    };
+    void begin();
+    return channel;
+}

package/dist/core/view/transport-cache.d.ts

@@ -0,0 +1,8 @@
+import type { SourceRequest } from './contract.js';
+import type { Transport } from './transport.js';
+export interface BurstCoalescingOptions {
+    ttlMs: number;
+    shouldCache(req: SourceRequest): boolean;
+    now?: () => number;
+}
+export declare function createBurstCoalescingTransport(inner: Transport, opts: BurstCoalescingOptions): Transport;

package/dist/core/view/transport-cache.js

@@ -0,0 +1,38 @@
+// transport-cache.ts — small host-side burst coalescing for expensive reads.
+//
+// The SourceRequest/Transport contract stays unchanged: callers still send the
+// same request and receive the same RawResponse. This decorator only changes the
+// host's scheduling for requests the host explicitly marks cacheable.
+export function createBurstCoalescingTransport(inner, opts) {
+    const now = opts.now ?? Date.now;
+    const inflight = new Map();
+    const cache = new Map();
+    const send = async (req) => {
+        if (!opts.shouldCache(req))
+            return inner.send(req);
+        const key = JSON.stringify(req);
+        const cached = cache.get(key);
+        if (cached !== undefined) {
+            if (cached.expiresAt > now())
+                return cached.response;
+            cache.delete(key);
+        }
+        const pending = inflight.get(key);
+        if (pending !== undefined)
+            return pending;
+        const run = inner.send(req).then((response) => {
+            cache.set(key, { expiresAt: now() + opts.ttlMs, response });
+            return response;
+        }).finally(() => {
+            inflight.delete(key);
+        });
+        inflight.set(key, run);
+        return run;
+    };
+    return {
+        send,
+        open(req, handlers) {
+            return inner.open(req, handlers);
+        },
+    };
+}

package/dist/core/view/transport-local.d.ts

@@ -0,0 +1,7 @@
+import type { Transport } from './transport.js';
+export interface LocalTransportOptions {
+    /** Working directory for `exec` requests that don't carry their own cwd.
+     *  Defaults to process.cwd(). */
+    cwd?: string;
+}
+export declare function createLocalTransport(opts?: LocalTransportOptions): Transport;

package/dist/core/view/transport-local.js

@@ -0,0 +1,83 @@
+// transport-local.ts — the BUILT local transport: fulfills SourceRequests on
+// this machine. exec→execFile (cwd = the view's cwd unless the request says
+// otherwise), file→readFile, http→fetch.
+//
+// Never throws. Transport-level failure (binary missing, file unreadable,
+// network down) ⇒ { ok:false, stderr }. A spawned process exiting non-zero is
+// transport-level SUCCESS (ok:true + exitCode) — classifying that is the
+// source's parse() job.
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { openLocalStream } from './stream-local.js';
+const MAX_BUFFER = 10 * 1024 * 1024;
+export function createLocalTransport(opts = {}) {
+    const baseCwd = opts.cwd ?? process.cwd();
+    return {
+        async send(req) {
+            switch (req.kind) {
+                case 'exec': return sendExec(req, baseCwd);
+                case 'file': return sendFile(req);
+                case 'http': return sendHttp(req);
+            }
+        },
+        open(req, handlers) {
+            return openLocalStream(req, handlers);
+        },
+    };
+}
+function sendExec(req, baseCwd) {
+    return new Promise((resolve) => {
+        const child = execFile(req.bin, req.args, { cwd: req.cwd ?? baseCwd, maxBuffer: MAX_BUFFER, encoding: 'utf8' }, (err, stdout, stderr) => {
+            if (!err) {
+                resolve({ ok: true, exitCode: 0, stdout, stderr });
+                return;
+            }
+            const code = err.code;
+            if (typeof code === 'number') {
+                // Ran but exited non-zero: transport-level success; parse() classifies.
+                resolve({ ok: true, exitCode: code, stdout: stdout ?? '', stderr: stderr ?? '' });
+                return;
+            }
+            const signal = err.signal;
+            if (signal) {
+                // Killed by signal: it ran; surface as a non-zero exit. A SIGKILL with
+                // no stderr at all (the live-incident shape: a guest OOM killer takes
+                // out the child before it ever writes anything) used to come back as
+                // a bare `failed (1)` with nothing to explain it — the signal itself
+                // IS the useful diagnostic here, so surface it when stderr is empty
+                // rather than discarding it.
+                const detail = stderr && stderr.trim() !== ''
+                    ? stderr
+                    : `killed by signal ${signal}${signal === 'SIGKILL' ? ' (often out-of-memory)' : ''}`;
+                resolve({ ok: true, exitCode: 1, stdout: stdout ?? '', stderr: detail });
+                return;
+            }
+            // Spawn-level failure (ENOENT/EACCES/maxBuffer): transport failure.
+            const msg = code === 'ENOENT' ? `${req.bin}: command not found` : err.message;
+            resolve({ ok: false, stdout: stdout ?? '', stderr: msg });
+        });
+        if (req.stdin != null && child.stdin) {
+            child.stdin.write(req.stdin);
+            child.stdin.end();
+        }
+    });
+}
+async function sendFile(req) {
+    try {
+        const text = await readFile(req.path, 'utf8');
+        return { ok: true, stdout: text, stderr: '' };
+    }
+    catch (e) {
+        return { ok: false, stdout: '', stderr: e instanceof Error ? e.message : String(e) };
+    }
+}
+async function sendHttp(req) {
+    try {
+        const res = await fetch(req.url, { method: req.method, headers: req.headers, body: req.body });
+        const body = await res.text();
+        return { ok: true, status: res.status, stdout: body, stderr: res.ok ? '' : res.statusText };
+    }
+    catch (e) {
+        return { ok: false, stdout: '', stderr: e instanceof Error ? e.message : String(e) };
+    }
+}

package/dist/core/view/transport-remote.d.ts

@@ -0,0 +1,2 @@
+import type { RawResponse } from './contract.js';
+export declare function createRemoteExec(previewEndpoint: string, relayToken: string, timeoutMs?: number): (bin: string, args: string[]) => Promise<RawResponse>;

package/dist/core/view/transport-remote.js

@@ -0,0 +1,58 @@
+// transport-remote.ts — the Node-side remote exec transport for a
+// RemoteCanvasSource. POSTs a SourceRequest to a Blaxel preview endpoint's
+// `/__crtr/source` route (the SAME in-guest source-fulfillment endpoint the
+// browser/web transport already speaks), bearer-authed with the relay token.
+//
+// This is the ONLY way RemoteCanvasSource reaches the remote canvas: it never
+// reads a remote SQLite file, and it never invokes an in-guest command that
+// doesn't already exist. Every argv it sends is `crtr --json <existing
+// subcommand>` — read-only.
+//
+// P2 DEFERRAL (Stage-C, plan C-1/C-5): `/__crtr/source` on a preview host is
+// the REMOTE transport, deliberately outside the local crtrd `/v1` boundary.
+// Repointing remote hosts at a crtrd proxy shell is a P2 hand-off; this file is
+// a settled exception, not a P1 defect.
+/** The remote read plane crosses a network boundary — a stalled TCP connection
+ *  or a hung `/__crtr/source` handler must fail closed, not wedge `node
+ *  inspect`/`canvas browse`/attach forever. Low enough that a genuinely hung
+ *  endpoint surfaces as a failed read within one interactive frame, not a
+ *  silent hang. */
+const DEFAULT_TIMEOUT_MS = 5_000;
+export function createRemoteExec(previewEndpoint, relayToken, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    // A malformed stored token (control chars / non-Latin1 bytes) would throw
+    // from the Headers constructor with the invalid value IN the thrown
+    // message — validate up front so that never happens, and fail with a
+    // GENERIC message instead (Phase 3 review Minor 1: no token bytes may ever
+    // reach returned stderr). HTTP header values are ISO-8859-1; reject
+    // anything outside `/^[\x20-\x7e]+$/` (printable ASCII, no CR/LF/control).
+    const tokenValid = /^[\x20-\x7e]+$/.test(relayToken);
+    return async function exec(bin, args) {
+        if (!tokenValid) {
+            return { ok: false, stdout: '', stderr: 'remote source: invalid stored relay token' };
+        }
+        const req = { kind: 'exec', bin, args };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(new URL('/__crtr/source', previewEndpoint), {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', authorization: `Bearer ${relayToken}` },
+                body: JSON.stringify(req),
+                signal: controller.signal,
+            });
+        }
+        catch (e) {
+            if (controller.signal.aborted) {
+                return { ok: false, stdout: '', stderr: `remote source: timeout after ${timeoutMs}ms` };
+            }
+            return { ok: false, stdout: '', stderr: 'remote source: network error' };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok)
+            return { ok: false, stdout: '', stderr: `remote source: HTTP ${res.status} ${res.statusText}` };
+        return (await res.json());
+    };
+}

package/dist/core/view/transport.d.ts

@@ -0,0 +1,10 @@
+import type { SourceRequest, RawResponse, StreamRequest, StreamChannel, SourceError } from './contract.js';
+export interface StreamHandlers {
+    onFrame(frame: unknown): void;
+    onClose(reason: string): void;
+    onError(err: SourceError): void;
+}
+export interface Transport {
+    send(req: SourceRequest): Promise<RawResponse>;
+    open(req: StreamRequest, handlers: StreamHandlers): StreamChannel;
+}