@rmrdeveloper/sideroom-pi 8.12.0 → 8.13.0

package/assets/visual-context/browser/content.js

@@ -0,0 +1,198 @@
+(() => {
+  const INSPECTOR_KEY = '__sideroomVisualInspector';
+  if (globalThis[INSPECTOR_KEY]) {
+    return;
+  }
+  const MAX_TEXT = 160;
+  const MAX_CLASSES = 32;
+  const MAX_ANCESTORS = 4;
+  const BORDER = '#ffb340';
+  let active = false;
+  let root;
+  let box;
+  let caption;
+  let exitHint = 'Esc to exit';
+
+  function clean(text) {
+    return text
+      .split('')
+      .map((character) =>
+        character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127
+          ? ' '
+          : character,
+      )
+      .join('')
+      .replace(/\s+/gu, ' ')
+      .trim()
+      .slice(0, MAX_TEXT);
+  }
+
+  function describe(element) {
+    return {
+      tag: element.localName,
+      elementId: clean(element.id ?? ''),
+      classes: [...element.classList].slice(0, MAX_CLASSES).map(clean),
+    };
+  }
+
+  function visibleText(element) {
+    if (element.closest('input,textarea,select,[contenteditable]')) {
+      return '';
+    }
+    const clone = element.cloneNode(true);
+    for (const child of clone.querySelectorAll(
+      'script,style,input,textarea,select,[contenteditable],[hidden]',
+    )) {
+      child.remove();
+    }
+    return clean(clone.textContent ?? '');
+  }
+
+  function selectedElement(event) {
+    return event
+      .composedPath()
+      .find((node) => node instanceof Element && node !== root);
+  }
+
+  function highlight(event) {
+    const element = selectedElement(event);
+    if (!active || !element || element === document.documentElement) {
+      return;
+    }
+    const bounds = element.getBoundingClientRect();
+    Object.assign(box.style, {
+      left: `${bounds.left}px`,
+      top: `${bounds.top}px`,
+      width: `${bounds.width}px`,
+      height: `${bounds.height}px`,
+    });
+    caption.textContent = `${element.localName} · click to attach · ${exitHint}`;
+  }
+
+  function intercept(event) {
+    if (active) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    }
+  }
+
+  async function select(event) {
+    if (!active || !event.isTrusted) {
+      return;
+    }
+    intercept(event);
+    const element = selectedElement(event);
+    if (!element || element === root) {
+      return;
+    }
+    const ancestors = [];
+    let parent = element.parentElement;
+    while (parent && ancestors.length < MAX_ANCESTORS) {
+      ancestors.push(describe(parent));
+      parent = parent.parentElement;
+    }
+    const selection = {
+      id: crypto.randomUUID(),
+      page: `${location.origin}${location.pathname}`,
+      element: describe(element),
+      text: visibleText(element),
+      ancestors,
+    };
+    caption.textContent = 'Sending selection to Pi…';
+    try {
+      const response = await chrome.runtime.sendMessage({
+        action: 'selection',
+        selection,
+      });
+      if (!response.ok) {
+        throw new Error(response.message);
+      }
+    } catch (cause) {
+      if (caption) {
+        caption.textContent = cause.message;
+      }
+    }
+  }
+
+  function keydown(event) {
+    if (event.key === 'Escape') {
+      intercept(event);
+      stop();
+      chrome.runtime.sendMessage({ action: 'stopped' }).catch((cause) => {
+        console.error('Sideroom inspector could not report its exit:', cause);
+      });
+    }
+  }
+
+  function start(shortcut) {
+    stop();
+    exitHint = shortcut ? `Esc or ${shortcut} to exit` : 'Esc to exit';
+    active = true;
+    root = document.createElement('div');
+    root.setAttribute('data-sideroom-inspector', '');
+    Object.assign(root.style, {
+      position: 'fixed',
+      inset: '0',
+      zIndex: '2147483647',
+      pointerEvents: 'none',
+    });
+    const shadow = root.attachShadow({ mode: 'closed' });
+    box = document.createElement('div');
+    Object.assign(box.style, {
+      position: 'fixed',
+      boxSizing: 'border-box',
+      border: `2px solid ${BORDER}`,
+      background: 'rgba(255,179,64,.08)',
+    });
+    caption = document.createElement('div');
+    caption.setAttribute('role', 'status');
+    caption.setAttribute('aria-live', 'polite');
+    caption.textContent = `Select an element · ${exitHint}`;
+    Object.assign(caption.style, {
+      position: 'fixed',
+      bottom: '16px',
+      left: '16px',
+      maxWidth: 'calc(100vw - 32px)',
+      padding: '10px 14px',
+      background: '#131211',
+      color: '#f2ede3',
+      border: `1px solid ${BORDER}`,
+      font: '13px ui-monospace, monospace',
+    });
+    shadow.append(box, caption);
+    document.documentElement.append(root);
+    window.addEventListener('pointermove', highlight, true);
+    window.addEventListener('pointerdown', intercept, true);
+    window.addEventListener('mousedown', intercept, true);
+    window.addEventListener('click', select, true);
+    window.addEventListener('keydown', keydown, true);
+    window.addEventListener('pagehide', stop);
+  }
+
+  function stop() {
+    active = false;
+    root?.remove();
+    root = undefined;
+    box = undefined;
+    caption = undefined;
+    window.removeEventListener('pointermove', highlight, true);
+    window.removeEventListener('pointerdown', intercept, true);
+    window.removeEventListener('mousedown', intercept, true);
+    window.removeEventListener('click', select, true);
+    window.removeEventListener('keydown', keydown, true);
+    window.removeEventListener('pagehide', stop);
+  }
+
+  chrome.runtime.onMessage.addListener((message) => {
+    if (message.action === 'start') {
+      start(message.shortcut);
+    }
+    if (message.action === 'stop') {
+      stop();
+    }
+    if (message.action === 'receipt' && caption) {
+      caption.textContent = message.message;
+    }
+  });
+  globalThis[INSPECTOR_KEY] = { stop };
+})();

package/assets/visual-context/browser/icons/README.md

@@ -0,0 +1,9 @@
+# Browser icon
+
+White `S` on opaque black, rendered with **Archivo Variable**, the text family
+in Sideroom's `DESIGN.md` and `site/src/styles/site.css`. Weight: 700. Source:
+`site/node_modules/@fontsource-variable/archivo/files/archivo-latin-wght-normal.woff2`.
+
+The PNGs are 16, 32, 48 and 128 pixels. Each canvas uses `#000000`, a `#ffffff`
+glyph at 86% of canvas size, and centers the glyph's actual ink bounds. These
+are rendered font glyphs; the browser does not need the font installed.

package/assets/visual-context/browser/manifest.json

@@ -0,0 +1,20 @@
+{
+  "manifest_version": 3,
+  "name": "Sideroom Visual Context",
+  "version": "1.1.0",
+  "description": "Select a page element and attach local source candidates to your Pi session.",
+  "minimum_chrome_version": "116",
+  "permissions": ["activeTab", "scripting", "storage", "alarms"],
+  "icons": { "16": "icons/icon-16.png", "32": "icons/icon-32.png", "48": "icons/icon-48.png", "128": "icons/icon-128.png" },
+  "background": { "service_worker": "background.js" },
+  "commands": {
+    "toggle-inspector": {
+      "suggested_key": "Alt+Shift+S",
+      "description": "Start or stop selecting elements for Pi"
+    }
+  },
+  "action": { "default_popup": "popup.html", "default_title": "Select an element for Pi", "default_icon": { "16": "icons/icon-16.png", "32": "icons/icon-32.png", "48": "icons/icon-48.png" } },
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; object-src 'self'; connect-src ws://127.0.0.1:* ws://localhost:*"
+  }
+}

package/assets/visual-context/browser/popup.css

@@ -0,0 +1,19 @@
+:root { color-scheme: dark; font-family: "Helvetica Neue", Arial, sans-serif; color: #f2ede3; background: #131211; }
+* { box-sizing: border-box; }
+body { width: 360px; margin: 0; padding: 24px; }
+header { border-top: 2px solid #f2ede3; padding-top: 16px; }
+header img { display: block; }
+details { margin: 16px 0; }
+summary { cursor: pointer; color: #a49d8f; font-size: 13px; }
+h1 { font-size: 30px; line-height: 1.05; letter-spacing: -.035em; margin: 14px 0 18px; }
+.intro, footer { color: #a49d8f; font-size: 13px; line-height: 1.6; }
+label { display: block; margin: 22px 0 8px; font: 11px ui-monospace, monospace; }
+input, select { width: 100%; background: #0b0a09; border: 1px solid #514b42; border-radius: 0; padding: 11px; color: #f2ede3; font: 12px ui-monospace, monospace; }
+button { display: block; width: 100%; border: 1px solid #f2ede3; border-radius: 0; padding: 12px; margin-top: 10px; background: #f2ede3; color: #131211; font: 600 13px "Helvetica Neue", Arial, sans-serif; cursor: pointer; }
+button:hover { background: #fff; }
+button:disabled { opacity: .4; cursor: default; }
+.secondary { background: transparent; border-color: #514b42; color: #a49d8f; }
+.secondary:hover { background: #1b1917; }
+:focus-visible { outline: 2px solid #ffb340; outline-offset: 3px; }
+#status { min-height: 40px; margin: 18px 0; font: 12px/1.6 ui-monospace, monospace; color: #ffb340; overflow-wrap: anywhere; }
+footer { border-top: 1px solid #514b42; margin-top: 22px; padding-top: 14px; font-size: 11px; }

package/assets/visual-context/browser/popup.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Sideroom — Browser context</title>
+    <link rel="stylesheet" href="popup.css" />
+    <script src="popup.js" defer></script>
+  </head>
+  <body>
+    <header><img src="icons/icon-48.png" width="32" height="32" alt="Sideroom" /><h1>Point to the code.</h1></header>
+    <p class="intro">Select an element in this tab. Its source candidates appear in your Pi session.</p>
+    <details id="pairing-details" open><summary>Authorize Windows or WSL</summary><form id="pairing-form">
+      <label for="address">Pair once · address from Pi (F7)</label>
+      <input id="address" type="text" autocomplete="off" spellcheck="false" placeholder="ws://127.0.0.1:…" required />
+      <button id="connect" type="submit">Connect to Pi</button>
+    </form></details>
+    <p id="status" role="status" aria-live="polite">Checking connection…</p>
+    <label for="destination">Send selections to</label>
+    <select id="destination" disabled><option value="">Waiting for Pi…</option></select>
+    <button id="inspect" type="button" disabled>Select an element</button>
+    <p id="shortcut-hint">Escape exits selection. Change the shortcut in your browser's shortcuts page.</p>
+    <button id="disconnect" class="secondary" type="button" disabled>Disconnect</button>
+    <button id="forget" class="secondary" type="button" disabled>Forget authorizations</button>
+    <footer>Click attaches context. Send your instruction in Pi to begin.</footer>
+  </body>
+</html>

package/assets/visual-context/browser/popup.js

@@ -0,0 +1,141 @@
+const form = document.querySelector('#pairing-form');
+const address = document.querySelector('#address');
+const status = document.querySelector('#status');
+const inspect = document.querySelector('#inspect');
+const disconnect = document.querySelector('#disconnect');
+const forget = document.querySelector('#forget');
+const destination = document.querySelector('#destination');
+const connect = document.querySelector('#connect');
+// Edge keeps the Chromium shortcut page under its own scheme; every other
+// Chromium browser the companion supports answers on chrome://.
+const SHORTCUT_PAGE = navigator.userAgent.includes('Edg/')
+  ? 'edge://extensions/shortcuts'
+  : 'chrome://extensions/shortcuts';
+let busy = false;
+let pairingShown = false;
+
+function showStatus(receipt) {
+  status.textContent = receipt.notice ?? receipt.message;
+  if (receipt.connected !== undefined) {
+    inspect.disabled = !receipt.connected || !receipt.selectedId;
+    disconnect.disabled = !receipt.connected;
+  }
+  if (receipt.address !== undefined) {
+    if (!pairingShown) {
+      document.querySelector('#pairing-details').open = !receipt.address;
+      pairingShown = true;
+    }
+    if (document.activeElement !== address) {
+      address.value = receipt.address;
+    }
+    forget.disabled = !receipt.address;
+  }
+  if (receipt.sessions) {
+    destination.replaceChildren();
+    const placeholder = document.createElement('option');
+    placeholder.value = '';
+    placeholder.textContent = receipt.sessions.length
+      ? 'Choose a Pi session…'
+      : 'Waiting for Pi…';
+    destination.append(placeholder);
+    for (const session of receipt.sessions) {
+      const option = document.createElement('option');
+      option.value = session.id;
+      option.textContent = `${session.environment} · ${session.name} · ${session.project}`;
+      destination.append(option);
+    }
+    destination.value = receipt.selectedId;
+    destination.disabled = !receipt.connected || !receipt.sessions.length;
+  }
+}
+
+async function request(message) {
+  const receipt = await chrome.runtime.sendMessage(message);
+  if (!receipt.ok) {
+    throw new Error(receipt.message);
+  }
+  return receipt;
+}
+
+form.addEventListener('submit', async (event) => {
+  event.preventDefault();
+  busy = true;
+  connect.disabled = true;
+  status.textContent = 'Connecting…';
+  try {
+    showStatus(await request({ action: 'connect', address: address.value }));
+  } catch (cause) {
+    showStatus({ message: cause.message, connected: false });
+  } finally {
+    busy = false;
+    connect.disabled = false;
+  }
+});
+
+destination.addEventListener('change', async () => {
+  busy = true;
+  try {
+    showStatus(await request({ action: 'choose', id: destination.value }));
+  } catch (cause) {
+    showStatus({ message: cause.message });
+  } finally {
+    busy = false;
+  }
+});
+
+inspect.addEventListener('click', async () => {
+  try {
+    await request({ action: 'inspect' });
+    window.close();
+  } catch (cause) {
+    showStatus({ message: cause.message });
+  }
+});
+
+for (const button of [disconnect, forget]) {
+  button.addEventListener('click', async () => {
+    busy = true;
+    try {
+      showStatus(
+        await request({ action: button === forget ? 'forget' : 'disconnect' }),
+      );
+      if (button === forget) {
+        address.value = '';
+        document.querySelector('#pairing-details').open = true;
+      }
+    } catch (cause) {
+      showStatus({ message: cause.message });
+    } finally {
+      busy = false;
+    }
+  });
+}
+
+async function refresh() {
+  if (busy) {
+    return;
+  }
+  try {
+    showStatus(await request({ action: 'status' }));
+  } catch (cause) {
+    showStatus({ message: cause.message, connected: false });
+  }
+}
+async function showShortcut() {
+  const hint = document.querySelector('#shortcut-hint');
+  try {
+    const commands = await chrome.commands.getAll();
+    const shortcut = commands.find(
+      (command) => command.name === 'toggle-inspector',
+    )?.shortcut;
+    hint.textContent = shortcut
+      ? `${shortcut} starts or stops selection. Escape also exits. Change it in ${SHORTCUT_PAGE}.`
+      : `No selection shortcut is assigned. Set one in ${SHORTCUT_PAGE}. Escape exits selection.`;
+  } catch (cause) {
+    hint.textContent = `Could not read the shortcut: ${cause.message}. Check ${SHORTCUT_PAGE}.`;
+  }
+}
+void showShortcut();
+void refresh();
+const poll = setInterval(refresh, 1_000);
+window.addEventListener('pagehide', () => clearInterval(poll));

package/extensions/visual-context/bridge.ts

@@ -0,0 +1,240 @@
+import { WebSocket } from 'ws';
+import { type LocalBroker, startBroker } from './broker.ts';
+import { parseEnvelope, send } from './envelope.ts';
+import {
+  MESSAGE_TYPE,
+  PEER_ROLE,
+  PI_ORIGIN,
+  PROTOCOL_VERSION,
+  parseSelection,
+  type SessionDescriptor,
+  type VisualSelection,
+} from './model.ts';
+import { endpoint, hasCode, type PairingIdentity } from './pairing.ts';
+
+const RECONNECT_MS = 1_000;
+const HEARTBEAT_MS = 20_000;
+const STARTUP_TIMEOUT_MS = 10_000;
+export interface VisualBridge {
+  update(session: SessionDescriptor): void;
+  close(): Promise<void>;
+}
+interface SessionConnectionOptions {
+  readonly identity: PairingIdentity;
+  readonly session: SessionDescriptor;
+  readonly onSelection: (
+    selection: VisualSelection,
+    revision: string,
+  ) => {
+    readonly candidates: number;
+  };
+  readonly onError: (error: Error) => void;
+}
+
+export async function connectSession(
+  options: SessionConnectionOptions,
+): Promise<VisualBridge> {
+  let session = options.session;
+  let broker: LocalBroker | undefined;
+  let socket: WebSocket | undefined;
+  let retry: NodeJS.Timeout | undefined;
+  let heartbeat: NodeJS.Timeout | undefined;
+  let closed = false;
+  let authenticated = false;
+  let registered = false;
+  let resolveStartup: () => void;
+  let rejectStartup: (error: Error) => void;
+  const startup = new Promise<void>((resolve, reject) => {
+    resolveStartup = resolve;
+    rejectStartup = reject;
+  });
+  const report = (cause: unknown): void => {
+    if (closed) {
+      return;
+    }
+    const error =
+      cause instanceof Error
+        ? cause
+        : new Error('Cannot connect the Pi session.', { cause });
+    if (!registered) {
+      rejectStartup(error);
+    } else {
+      options.onError(error);
+    }
+  };
+  const register = (): void => {
+    if (socket && authenticated) {
+      send(socket, { type: MESSAGE_TYPE.register, session });
+    }
+  };
+  async function attach(): Promise<void> {
+    if (closed) {
+      return;
+    }
+    if (!broker) {
+      try {
+        const created = await startBroker({
+          identity: options.identity,
+          onError: options.onError,
+        });
+        if (closed) {
+          await created.close();
+          return;
+        }
+        broker = created;
+      } catch (cause) {
+        if (!hasCode(cause, 'EADDRINUSE')) {
+          report(cause);
+          scheduleRetry();
+          return;
+        }
+      }
+    }
+    if (closed) {
+      return;
+    }
+    const connection = new WebSocket(endpoint(options.identity), {
+      origin: PI_ORIGIN,
+      maxPayload: 32_768,
+    });
+    socket = connection;
+    authenticated = false;
+    const authenticationTimeout = setTimeout(() => {
+      report(new Error('The local browser bridge did not authenticate.'));
+      connection.terminate();
+    }, STARTUP_TIMEOUT_MS);
+    authenticationTimeout.unref();
+    connection.on('open', () =>
+      send(connection, {
+        type: MESSAGE_TYPE.authenticate,
+        role: PEER_ROLE.pi,
+        version: PROTOCOL_VERSION,
+        token: options.identity.token,
+      }),
+    );
+    connection.on('error', report);
+    connection.on('close', () => {
+      clearTimeout(authenticationTimeout);
+      clearInterval(heartbeat);
+      authenticated = false;
+      scheduleRetry();
+    });
+    connection.on('message', (bytes, binary) => {
+      try {
+        const message = parseEnvelope(bytes.toString(), binary);
+        if (
+          message.type === MESSAGE_TYPE.ready &&
+          message.version === PROTOCOL_VERSION
+        ) {
+          clearTimeout(authenticationTimeout);
+          authenticated = true;
+          heartbeat = setInterval(
+            () => send(connection, { type: MESSAGE_TYPE.ping }),
+            HEARTBEAT_MS,
+          );
+          heartbeat.unref();
+          register();
+          return;
+        }
+        if (
+          message.type === MESSAGE_TYPE.register &&
+          message.revision === session.revision
+        ) {
+          registered = true;
+          resolveStartup();
+          return;
+        }
+        if (message.type === MESSAGE_TYPE.error) {
+          report(new Error(String(message.message)));
+          return;
+        }
+        if (message.type !== MESSAGE_TYPE.deliver) {
+          return;
+        }
+        try {
+          if (closed || message.revision !== session.revision) {
+            throw new Error(
+              'The Pi conversation changed. Select the element again.',
+            );
+          }
+          const receipt = options.onSelection(
+            parseSelection(message.selection),
+            session.revision,
+          );
+          send(connection, {
+            type: MESSAGE_TYPE.result,
+            requestId: message.requestId,
+            candidates: receipt.candidates,
+          });
+        } catch (cause) {
+          const error =
+            cause instanceof Error
+              ? cause
+              : new Error('Cannot receive browser selection.', { cause });
+          options.onError(error);
+          send(connection, {
+            type: MESSAGE_TYPE.result,
+            requestId: message.requestId,
+            error: error.message,
+          });
+        }
+      } catch (cause) {
+        report(cause);
+      }
+    });
+  }
+  function scheduleRetry(): void {
+    if (closed || retry) {
+      return;
+    }
+    retry = setTimeout(() => {
+      retry = undefined;
+      void attach().catch(report);
+    }, RECONNECT_MS);
+    retry.unref();
+  }
+  let closing: Promise<void> | undefined;
+  const bridge: VisualBridge = {
+    update(next) {
+      session = next;
+      register();
+    },
+    close() {
+      if (closing) {
+        return closing;
+      }
+      closed = true;
+      clearTimeout(retry);
+      clearInterval(heartbeat);
+      closing = (async () => {
+        if (socket && socket.readyState !== WebSocket.CLOSED) {
+          const disconnected = new Promise<void>((resolve) =>
+            socket?.once('close', resolve),
+          );
+          socket.terminate();
+          await disconnected;
+        }
+        await broker?.close();
+      })();
+      return closing;
+    },
+  };
+  const deadline = setTimeout(
+    () =>
+      rejectStartup(
+        new Error('The Pi session could not join the local browser bridge.'),
+      ),
+    STARTUP_TIMEOUT_MS,
+  );
+  deadline.unref();
+  void attach().catch(report);
+  try {
+    await startup;
+    return bridge;
+  } catch (cause) {
+    await bridge.close();
+    throw cause;
+  } finally {
+    clearTimeout(deadline);
+  }
+}