@volter/teams 0.2.16 → 0.2.17

package/browser-channel.d.ts

@@ -82,3 +82,15 @@ export interface BrowserPane extends ChannelEvents {
 }
 
 export function attachBrowserPane(channel: BrowserChannel, options: { pane: string; mode?: 'observe' | 'control'; cols?: number; rows?: number }): Promise<BrowserPane>;
+
+/** This machine through its app door (`supercode app-door on`), with the pairing from `app-door link`. */
+export function openBrowserLocalMachine(target: { door: string; token: string }, options?: ChannelOptions): Promise<BrowserChannel>;
+/** The app door's pairing from a page's address (`#supercode=…`), or null. */
+export function readAppDoorPairing(hash?: string): { door: string; token: string } | null;
+/** A harness SDK transport over a browser channel's `harness` stream. */
+export function browserHarnessTransport(channel: BrowserChannel | (() => BrowserChannel | Promise<BrowserChannel>)): {
+  readonly running: boolean;
+  start(handlers: { onLine(line: string): void; onExit(code: number | null, reason: string | null): void; onStderr?(text: string): void; onWriteError?(error: Error): void }): Promise<void>;
+  write(line: string): void;
+  close(): Promise<void>;
+};

package/browser-channel.mjs

@@ -167,6 +167,81 @@ export function openBrowserSession({ origin, teamId, sessionId, token }, { WebSo
   return connectBrowserChannel(socket, channel, `could not reach session ${sessionId} through ${origin}`, 'the server closed the session channel');
 }
 
+/**
+ * This machine, through its app door (the daemon's loopback WebSocket for web apps, off until the
+ * person turns it on: `supercode app-door on`). `door` and `token` come from the link the
+ * person opened the app with (`app-door link`); see readAppDoorPairing.
+ */
+export function openBrowserLocalMachine({ door, token }, { WebSocketImpl = globalThis.WebSocket } = {}) {
+  const socket = new WebSocketImpl(door, [CHANNEL_PROTOCOL, `bearer.${token}`]);
+  const channel = new BrowserChannel(socket);
+  return connectBrowserChannel(socket, channel, `could not reach this machine's app door at ${door}: is it on? (supercode app-door status)`, 'the machine closed the app door\'s channel');
+}
+
+/**
+ * The app door's pairing from a page's address (`#supercode=<base64url JSON { door, token }>`, as
+ * `app-door link` writes it), or null. The caller keeps it and removes it from the address.
+ */
+export function readAppDoorPairing(hash = globalThis.location?.hash ?? '') {
+  const match = /(?:^#|&)supercode=([A-Za-z0-9_-]+)/.exec(hash);
+  if (!match) return null;
+  try {
+    const padded = match[1].replace(/-/g, '+').replace(/_/g, '/');
+    const value = JSON.parse(decoder.decode(Uint8Array.from(atob(padded + '='.repeat((4 - (padded.length % 4)) % 4)), (c) => c.charCodeAt(0))));
+    // Only this machine's own door: a link naming any other address would hand the person's work to it.
+    const door = typeof value?.door === 'string' ? new URL(value.door) : null;
+    const local = door && door.protocol === 'ws:' && ['127.0.0.1', 'localhost', '[::1]'].includes(door.hostname);
+    return local && typeof value.token === 'string' && value.token ? { door: door.href, token: value.token } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A harness SDK transport (`ClientOptions.transport`) over a browser machine channel's `harness`
+ * stream: harness.v1 JSON lines to the machine's harness service. `channel` is a channel, or a function
+ * that opens one, called again after the stream closes so a restarted daemon costs one reconnect.
+ */
+export function browserHarnessTransport(channel) {
+  const owned = typeof channel === 'function';
+  const source = owned ? channel : () => channel;
+  let stream = null;
+  let opened = null;
+  return {
+    get running() { return stream !== null && !stream.closed; },
+    async start(handlers) {
+      // A channel this transport opened is its own to close when it opens the next.
+      if (owned && opened && !opened.closed) opened.close();
+      opened = await source();
+      const current = await opened.open('harness');
+      stream = current;
+      const text = new TextDecoder();
+      let pending = '';
+      current.on('data', (chunk) => {
+        pending += typeof chunk === 'string' ? chunk : text.decode(chunk, { stream: true });
+        let end;
+        while ((end = pending.indexOf('\n')) >= 0) {
+          const line = pending.slice(0, end).replace(/\r$/, '');
+          pending = pending.slice(end + 1);
+          if (line) handlers.onLine(line);
+        }
+      });
+      // Only the current stream's end is the transport's: an earlier one closing late is not.
+      current.on('close', (reason) => { if (stream !== current) return; stream = null; handlers.onExit(null, reason ?? null); });
+    },
+    write(line) {
+      if (!stream || stream.closed) throw new Error('the harness stream is not open');
+      stream.write(line.endsWith('\n') ? line : line + '\n');
+    },
+    async close() {
+      stream?.close();
+      stream = null;
+      if (owned) opened?.close();
+      opened = null;
+    },
+  };
+}
+
 /** A turn was accepted by its stream, but its delivery receipt was not obtained. */
 export class TurnDeliveryUnconfirmedError extends Error {
   constructor(message) { super(message); this.name = 'TurnDeliveryUnconfirmedError'; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "type": "module",
   "description": "Volter Teams, the neutral team plane: machine identity and daemon core, the local door and server link, admission from machine grants, product doors, and the Teams server's neutral routes (company RFC 0008).",
   "license": "MIT",