@unifedev/thread-pages 0.3.2 → 1.1.0

package/src/runtime/shared/protocol.ts

@@ -0,0 +1,125 @@
+/**
+ * What crosses the one MessagePort between the kernel (inside the sandboxed
+ * document) and the shell (trusted chrome), and the configuration each side
+ * receives from the server. Shared so neither side can drift. spec R2.3, R3.8
+ */
+import { BRIDGE_ERROR_CODES, type BridgeErrorCode } from "../../domain/errors.ts";
+
+export const HANDSHAKE_VERSION = 1 as const;
+export const BRIDGE_VERSION = 1 as const;
+
+export interface BridgeRequestMessage {
+  v: 1;
+  id: string;
+  method: string;
+  params: unknown;
+  pageRevision: string;
+}
+
+export type BridgeResponseMessage =
+  | { v: 1; id: string; ok: true; result: unknown }
+  | { v: 1; id: string; ok: false; error: { code: BridgeErrorCode; message: string } };
+
+export interface SubmitFile {
+  field: string;
+  file: File;
+}
+
+export interface SubmitAnswer {
+  name: string;
+  label: string;
+  value: string | string[] | boolean;
+}
+
+export type KernelMessage =
+  | { kind: "thread-page:dirty" }
+  | { kind: "thread-page:clean" }
+  | { kind: "thread-page:submit"; submissionId: string; title: string; answers: SubmitAnswer[]; files: SubmitFile[] }
+  | BridgeRequestMessage;
+
+export type ShellMessage =
+  | { kind: "thread-page:source-state"; stale: boolean }
+  | { kind: "thread-page:submit-progress"; submissionId: string; message: string }
+  | { kind: "thread-page:submit-result"; submissionId: string; ok: boolean; message?: string; error?: string }
+  | BridgeResponseMessage;
+
+/** Carried in the kernel script's `data-config` attribute. */
+export interface KernelConfig {
+  pageRevision: string;
+  stale: boolean;
+}
+
+/** Carried in the shell script's `data-config` attribute. */
+export interface ShellConfig {
+  actionToken: string;
+  pageRevision: string;
+  expiresAt: number;
+  documentUrl: string;
+  submitUrl: string;
+  uploadUrl: string;
+  bridgeUrl: string;
+  workingLabel: string;
+  stale: boolean;
+  pollMs: number;
+  maxUploadBytes: number;
+  maxUploads: number;
+}
+
+const ERROR_CODES: ReadonlySet<string> = new Set(BRIDGE_ERROR_CODES);
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,95}$/;
+const METHOD_PATTERN = /^[a-z][a-zA-Z0-9]*(?:\.[a-z][a-zA-Z0-9]*)+$/;
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const own = Object.keys(value);
+  return own.length === keys.length && keys.every((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+
+export function isValidRequestId(value: unknown): value is string {
+  return typeof value === "string" && ID_PATTERN.test(value);
+}
+
+/** The shell checks every request before it leaves the reader's browser. */
+export function isBridgeRequest(value: unknown, pageRevision: string): value is BridgeRequestMessage {
+  return (
+    isRecord(value) &&
+    hasExactKeys(value, ["v", "id", "method", "params", "pageRevision"]) &&
+    value.v === BRIDGE_VERSION &&
+    isValidRequestId(value.id) &&
+    typeof value.method === "string" &&
+    value.method.length >= 3 &&
+    value.method.length <= 96 &&
+    METHOD_PATTERN.test(value.method) &&
+    value.pageRevision === pageRevision
+  );
+}
+
+/** Both sides check every response; an unexpected shape is `invalid_response`. spec R4.32 */
+export function isBridgeResponse(value: unknown, expectedId?: string): value is BridgeResponseMessage {
+  if (!isRecord(value) || value.v !== BRIDGE_VERSION || typeof value.id !== "string" || typeof value.ok !== "boolean") return false;
+  if (expectedId !== undefined && value.id !== expectedId) return false;
+  if (value.ok === true) return hasExactKeys(value, ["v", "id", "ok", "result"]);
+  if (!hasExactKeys(value, ["v", "id", "ok", "error"]) || !isRecord(value.error)) return false;
+  const error = value.error;
+  return (
+    hasExactKeys(error, ["code", "message"]) &&
+    typeof error.code === "string" &&
+    ERROR_CODES.has(error.code) &&
+    typeof error.message === "string" &&
+    error.message.length > 0 &&
+    error.message.length <= 512
+  );
+}
+
+export function makeFailure(id: unknown, code: BridgeErrorCode, message: string): BridgeResponseMessage {
+  return { v: 1, id: isValidRequestId(id) ? id : "invalid", ok: false, error: { code, message: message.slice(0, 512) || "Request failed" } };
+}
+
+export function readConfig<T>(script: Element | null): T {
+  const raw = script?.getAttribute("data-config");
+  if (!raw) throw new Error("Thread Page runtime: configuration is missing");
+  return JSON.parse(raw) as T;
+}

package/src/runtime/shell/confirm.ts

@@ -0,0 +1,70 @@
+/**
+ * The confirmation dialog: rendered in trusted chrome the sandboxed page
+ * cannot draw over, click or reword. The summary comes from the host, never
+ * from the page. spec R2.19, R3.22
+ *
+ * Resolution is driven by button clicks rather than the dialog's `close`
+ * event, which never fires in headless browsers (spec 09 §Testing note).
+ */
+export interface Confirmer {
+  confirm(summary: string, onConfirmGesture?: () => void): Promise<boolean>;
+}
+
+export function createConfirmer(dialog: HTMLDialogElement): Confirmer {
+  const text = dialog.querySelector("p");
+  const cancel = dialog.querySelector<HTMLButtonElement>('button[value="cancel"]');
+  const confirm = dialog.querySelector<HTMLButtonElement>('button[value="confirm"]');
+  let active: ((approved: boolean) => void) | null = null;
+  let gesture: (() => void) | undefined;
+
+  function settle(approved: boolean): void {
+    const current = active;
+    active = null;
+    if (approved && gesture) {
+      try {
+        gesture();
+      } catch {
+        // A refused popup is handled by the caller's fallback.
+      }
+    }
+    gesture = undefined;
+    if (dialog.open) dialog.close();
+    current?.(approved);
+  }
+
+  cancel?.addEventListener("click", (event) => {
+    event.preventDefault();
+    settle(false);
+  });
+  confirm?.addEventListener("click", (event) => {
+    event.preventDefault();
+    settle(true);
+  });
+  dialog.addEventListener("cancel", (event) => {
+    event.preventDefault();
+    settle(false);
+  });
+  dialog.addEventListener("close", () => {
+    if (active) settle(false);
+  });
+
+  return {
+    confirm(summary, onConfirmGesture) {
+      return new Promise((resolve) => {
+        if (active) settle(false);
+        if (text) text.textContent = summary;
+        active = resolve;
+        gesture = onConfirmGesture;
+        if (typeof dialog.showModal === "function") {
+          try {
+            dialog.showModal();
+          } catch {
+            settle(false);
+          }
+        } else {
+          settle(false);
+        }
+      });
+    },
+  };
+}

package/src/runtime/shell/install.ts

@@ -0,0 +1,79 @@
+import { HANDSHAKE_VERSION, isRecord, type ShellConfig } from "../shared/protocol.ts";
+import { createConfirmer } from "./confirm.ts";
+import { createNavigator } from "./navigate.ts";
+import { createPoller, type Poller } from "./poll.ts";
+import { createRelay } from "./relay.ts";
+
+/**
+ * Wires the shell: loads the document into the sandboxed frame, hands it one
+ * MessagePort once it reports ready, relays its messages, polls for a new
+ * revision, and owns the chrome. spec 02 §The shell
+ */
+export interface ShellElements {
+  frame: HTMLIFrameElement;
+  status: HTMLElement;
+  work: HTMLElement;
+  reload: HTMLButtonElement;
+  dialog: HTMLDialogElement;
+}
+
+export interface ShellHandle {
+  poller: Poller;
+}
+
+export function installShell(win: Window & typeof globalThis, config: ShellConfig, elements: ShellElements, fetchImpl?: typeof fetch): ShellHandle {
+  const { frame, status, work, reload, dialog } = elements;
+  let framePort: MessagePort | null = null;
+  let awaitingReady = true;
+  let lastStale = config.stale;
+
+  const view = {
+    setStatus(text: string, warn: boolean) {
+      status.textContent = text;
+      status.dataset.tone = warn ? "warn" : "";
+    },
+    setWorking(working: boolean) {
+      work.dataset.visible = working && config.workingLabel ? "true" : "false";
+    },
+    showReload(visible: boolean) {
+      reload.dataset.visible = visible ? "true" : "false";
+    },
+    onStaleChanged(stale: boolean) {
+      lastStale = stale;
+      framePort?.postMessage({ kind: "thread-page:source-state", stale });
+    },
+    reloadView() {
+      win.location.reload();
+    },
+  };
+
+  const poller = createPoller(win, config, view, fetchImpl);
+  const navigator = createNavigator(win);
+  const confirmer = createConfirmer(dialog);
+  const relay = createRelay({ config, confirmer, navigator, onDirty: (dirty) => poller.setDirty(dirty), ...(fetchImpl ? { fetchImpl } : {}) });
+
+  function connectFrame(): void {
+    const channel = new win.MessageChannel();
+    const port = channel.port1;
+    framePort = port;
+    port.onmessage = (event) => relay.handle(port, event.data);
+    port.start?.();
+    frame.contentWindow?.postMessage({ kind: "thread-page:connect", version: HANDSHAKE_VERSION }, "*", [channel.port2]);
+    port.postMessage({ kind: "thread-page:source-state", stale: lastStale });
+  }
+
+  win.addEventListener("message", (event) => {
+    // Only the frame's opaque origin, only once, only the handshake.
+    if (!awaitingReady || event.origin !== "null" || event.source !== frame.contentWindow) return;
+    const data = event.data as unknown;
+    if (!isRecord(data) || data.kind !== "thread-page:ready" || data.version !== HANDSHAKE_VERSION) return;
+    awaitingReady = false;
+    connectFrame();
+  });
+
+  reload.addEventListener("click", () => win.location.reload());
+
+  frame.src = config.documentUrl;
+  poller.start();
+  return { poller };
+}

package/src/runtime/shell/main.ts

@@ -0,0 +1,12 @@
+import { readConfig, type ShellConfig } from "../shared/protocol.ts";
+import { installShell } from "./install.ts";
+
+// Entry for the bundled shell runtime.
+const config = readConfig<ShellConfig>(document.currentScript);
+const frame = document.querySelector("iframe");
+const status = document.querySelector<HTMLElement>("[data-shell-status]");
+const work = document.querySelector<HTMLElement>("[data-shell-working]");
+const reload = document.querySelector<HTMLButtonElement>("[data-shell-reload]");
+const dialog = document.querySelector("dialog");
+if (!frame || !status || !work || !reload || !dialog) throw new Error("Thread Page shell: chrome is incomplete");
+installShell(window, config, { frame, status, work, reload, dialog });

package/src/runtime/shell/navigate.ts

@@ -0,0 +1,64 @@
+/**
+ * Navigation belongs to the trusted shell. Destinations arrive from the host,
+ * already validated; the shell never builds one from page-supplied text.
+ * spec R5.29–R5.34
+ */
+export interface Navigator {
+  /** Same-origin destinations navigate the reader's view in place. */
+  inPlace(url: string): void;
+  /** Claims a window during a user gesture so a later navigation is not a blocked popup. */
+  reserveWindow(): void;
+  /** Sends the reserved window (or, failing that, this view) to an external URL. */
+  external(url: string): void;
+  /** Releases a reserved window that will not be used. */
+  release(): void;
+}
+
+export function createNavigator(win: Window): Navigator {
+  let reserved: Window | null = null;
+  return {
+    inPlace(url) {
+      win.location.assign(url);
+    },
+    reserveWindow() {
+      try {
+        reserved = win.open("", "_blank");
+        if (reserved) {
+          try {
+            reserved.opener = null;
+          } catch {
+            // Some browsers refuse; the navigation below still uses noreferrer semantics.
+          }
+        }
+      } catch {
+        reserved = null;
+      }
+    },
+    external(url) {
+      const target = reserved;
+      reserved = null;
+      if (target && !target.closed) {
+        try {
+          target.location.href = url;
+          return;
+        } catch {
+          try {
+            target.close();
+          } catch {
+            // ignore
+          }
+        }
+      }
+      win.location.assign(url);
+    },
+    release() {
+      const target = reserved;
+      reserved = null;
+      try {
+        target?.close();
+      } catch {
+        // ignore
+      }
+    },
+  };
+}

package/src/runtime/shell/poll.ts

@@ -0,0 +1,125 @@
+import type { ShellConfig } from "../shared/protocol.ts";
+
+/**
+ * The revision poll: a conditional GET of the document every few seconds
+ * while the tab is visible. It carries the working indicator and the
+ * source state, so no second channel exists. spec R2.17–R2.26
+ */
+export interface PollView {
+  setStatus(text: string, warn: boolean): void;
+  setWorking(working: boolean): void;
+  showReload(visible: boolean): void;
+  onStaleChanged(stale: boolean): void;
+  reloadView(): void;
+}
+
+export interface Poller {
+  start(): void;
+  setDirty(dirty: boolean): void;
+  /** For tests: run one poll now. */
+  pollNow(): Promise<void>;
+  isStopped(): boolean;
+}
+
+export function createPoller(win: Window, config: ShellConfig, view: PollView, fetchImpl: typeof fetch = win.fetch.bind(win)): Poller {
+  let etag = `"${config.pageRevision}"`;
+  let dirty = false;
+  let stopped = false;
+  let polling = false;
+  let lastStale = config.stale;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let controller: AbortController | null = null;
+
+  function schedule(delay: number): void {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    if (stopped || win.document.visibilityState !== "visible") return;
+    timer = setTimeout(() => {
+      timer = null;
+      void poll();
+    }, delay);
+  }
+
+  function pause(): void {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    controller?.abort();
+    controller = null;
+  }
+
+  function newVersion(): void {
+    if (dirty) {
+      view.setStatus("Page changed — reload when ready", true);
+      view.showReload(true);
+    } else {
+      view.reloadView();
+    }
+  }
+
+  async function poll(): Promise<void> {
+    if (stopped || polling || win.document.visibilityState !== "visible") return;
+    if (Date.now() >= config.expiresAt - 30_000) {
+      stopped = true;
+      if (dirty) {
+        view.setStatus("Session expiring — reload when ready", true);
+        view.showReload(true);
+      } else {
+        view.reloadView();
+      }
+      return;
+    }
+    polling = true;
+    controller = new AbortController();
+    try {
+      const response = await fetchImpl(config.documentUrl, {
+        method: "GET",
+        credentials: "same-origin",
+        cache: "no-store",
+        headers: { "if-none-match": etag },
+        signal: controller.signal,
+      });
+      if (response.status === 401 || response.status === 403) {
+        stopped = true;
+        view.setStatus("Session expired — reload this page", true);
+        view.showReload(true);
+        return;
+      }
+      if (!response.ok && response.status !== 304) {
+        view.setStatus("Page unavailable", true);
+        return;
+      }
+      const stale = response.headers.get("x-thread-page-stale") === "true";
+      view.setWorking(response.headers.get("x-thread-page-activity") === "working");
+      if (stale !== lastStale) {
+        lastStale = stale;
+        view.onStaleChanged(stale);
+      }
+      view.setStatus(stale ? "Offline copy — read-only" : "", stale);
+      const next = response.headers.get("etag");
+      if (next && next !== etag) {
+        etag = next;
+        newVersion();
+      }
+    } catch (error) {
+      if (!(error instanceof DOMException && error.name === "AbortError")) view.setStatus("Cannot check for updates", true);
+    } finally {
+      controller = null;
+      polling = false;
+      schedule(config.pollMs);
+    }
+  }
+
+  win.document.addEventListener("visibilitychange", () => {
+    if (win.document.visibilityState === "visible") schedule(0);
+    else pause();
+  });
+
+  return {
+    start: () => schedule(config.pollMs),
+    setDirty: (next) => {
+      dirty = next;
+    },
+    pollNow: () => poll(),
+    isStopped: () => stopped,
+  };
+}

package/src/runtime/shell/relay.ts

@@ -0,0 +1,185 @@
+import { isBridgeRequest, isBridgeResponse, isRecord, makeFailure, type BridgeRequestMessage, type ShellConfig, type ShellMessage, type SubmitFile } from "../shared/protocol.ts";
+import type { Confirmer } from "./confirm.ts";
+import type { Navigator } from "./navigate.ts";
+
+/**
+ * The shell's side of the port: it validates every message from the frame,
+ * carries bridge calls and submissions to the host with the action token,
+ * shows host-authored confirmations, and executes host-validated navigation.
+ * spec R3.5–R3.7, R3.17
+ */
+export interface RelayDeps {
+  config: ShellConfig;
+  confirmer: Confirmer;
+  navigator: Navigator;
+  onDirty(dirty: boolean): void;
+  fetchImpl?: typeof fetch;
+}
+
+export interface Relay {
+  handle(port: MessagePort, data: unknown): void;
+}
+
+type Directive = { kind: "page" | "host" | "external"; url: string };
+
+export function createRelay(deps: RelayDeps): Relay {
+  const { config, confirmer, navigator } = deps;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+
+  function reply(port: MessagePort, message: ShellMessage): void {
+    port.postMessage(message);
+  }
+
+  async function postBridge(body: unknown): Promise<unknown> {
+    const response = await fetchImpl(config.bridgeUrl, {
+      method: "POST",
+      credentials: "same-origin",
+      cache: "no-store",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    return response.json().catch(() => null);
+  }
+
+  function directiveOf(value: unknown): Directive | null {
+    if (!isRecord(value)) return null;
+    if ((value.kind !== "page" && value.kind !== "host" && value.kind !== "external") || typeof value.url !== "string") return null;
+    if (value.kind === "external" && !/^https?:\/\//i.test(value.url)) return null;
+    if (value.kind !== "external" && !value.url.startsWith("/")) return null;
+    return { kind: value.kind, url: value.url };
+  }
+
+  function deliver(port: MessagePort, request: BridgeRequestMessage, body: unknown): void {
+    if (!isRecord(body) || !isBridgeResponse(body.response, request.id)) {
+      reply(port, makeFailure(request.id, "invalid_response", "The Thread Page bridge returned an invalid response"));
+      return;
+    }
+    const directive = body.navigate === undefined ? null : directiveOf(body.navigate);
+    if (body.response.ok && directive) {
+      reply(port, body.response);
+      if (directive.kind === "external") navigator.external(directive.url);
+      else navigator.inPlace(directive.url);
+      return;
+    }
+    navigator.release();
+    reply(port, body.response);
+  }
+
+  async function relayBridge(port: MessagePort, request: BridgeRequestMessage): Promise<void> {
+    try {
+      const first = await postBridge({ actionToken: config.actionToken, request });
+      if (isRecord(first) && isRecord(first.confirm)) {
+        const confirm = first.confirm;
+        if (typeof confirm.challenge !== "string" || typeof confirm.summary !== "string" || confirm.requestId !== request.id) {
+          reply(port, makeFailure(request.id, "invalid_response", "The Thread Page bridge returned an invalid confirmation"));
+          return;
+        }
+        const external = request.method === "navigation.openExternal";
+        const approved = await confirmer.confirm(confirm.summary, external ? () => navigator.reserveWindow() : undefined);
+        if (!approved) {
+          reply(port, makeFailure(request.id, "cancelled", "You declined this action"));
+          return;
+        }
+        const second = await postBridge({ actionToken: config.actionToken, request, confirmation: confirm.challenge });
+        deliver(port, request, second);
+        return;
+      }
+      deliver(port, request, first);
+    } catch (error) {
+      navigator.release();
+      reply(port, makeFailure(request.id, "unavailable", error instanceof Error ? error.message : "The Thread Page bridge is unavailable"));
+    }
+  }
+
+  async function uploadOne(entry: SubmitFile): Promise<{ field: string; name: string; path: string; sizeBytes: number }> {
+    const file = entry.file;
+    if (!file || typeof file.size !== "number") throw new Error("Attachment is not a file");
+    const label = file.name || "file";
+    if (file.size <= 0) throw new Error(`Attachment ${label} is empty`);
+    if (file.size > config.maxUploadBytes) throw new Error(`Attachment ${label} is larger than ${Math.round(config.maxUploadBytes / (1024 * 1024))} MiB`);
+    const content = await encodeBase64(file);
+    const response = await fetchImpl(config.uploadUrl, {
+      method: "POST",
+      credentials: "same-origin",
+      cache: "no-store",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ actionToken: config.actionToken, pageRevision: config.pageRevision, name: label, content }),
+    });
+    const body = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+    if (!response.ok || !body || body.ok !== true || typeof body.name !== "string" || typeof body.path !== "string" || typeof body.sizeBytes !== "number") {
+      throw new Error((body && typeof body.message === "string" && body.message) || `Upload failed (${response.status})`);
+    }
+    return { field: String(entry.field || "file").slice(0, 128), name: body.name, path: body.path, sizeBytes: body.sizeBytes };
+  }
+
+  async function relaySubmit(port: MessagePort, data: Record<string, unknown>): Promise<void> {
+    const submissionId = typeof data.submissionId === "string" ? data.submissionId : "";
+    try {
+      const entries = (Array.isArray(data.files) ? data.files : []).slice(0, config.maxUploads) as SubmitFile[];
+      const files = [];
+      for (let index = 0; index < entries.length; index += 1) {
+        reply(port, { kind: "thread-page:submit-progress", submissionId, message: `Uploading ${index + 1} of ${entries.length}…` });
+        files.push(await uploadOne(entries[index] as SubmitFile));
+      }
+      if (files.length > 0) reply(port, { kind: "thread-page:submit-progress", submissionId, message: "Sending…" });
+      const response = await fetchImpl(config.submitUrl, {
+        method: "POST",
+        credentials: "same-origin",
+        cache: "no-store",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          actionToken: config.actionToken,
+          submissionId,
+          pageRevision: config.pageRevision,
+          title: data.title,
+          answers: data.answers,
+          files,
+        }),
+      });
+      const body = (await response.json().catch(() => ({ ok: false, message: "Invalid server response" }))) as Record<string, unknown>;
+      const ok = response.ok && body.ok === true;
+      reply(port, {
+        kind: "thread-page:submit-result",
+        submissionId,
+        ok,
+        message: typeof body.delivery === "string" ? `Sent (${body.delivery})` : "Sent",
+        error: typeof body.message === "string" ? body.message : `Request failed (${response.status})`,
+      });
+    } catch (error) {
+      reply(port, { kind: "thread-page:submit-result", submissionId, ok: false, error: error instanceof Error ? error.message : "Request failed" });
+    }
+  }
+
+  return {
+    handle(port, data) {
+      if (!isRecord(data)) return;
+      if (data.kind === "thread-page:dirty") {
+        deps.onDirty(true);
+        return;
+      }
+      if (data.kind === "thread-page:clean") {
+        deps.onDirty(false);
+        return;
+      }
+      if (data.kind === "thread-page:submit") {
+        void relaySubmit(port, data);
+        return;
+      }
+      if (!isBridgeRequest(data, config.pageRevision)) {
+        reply(port, makeFailure(data.id, "invalid_request", "Invalid Thread Page bridge request"));
+        return;
+      }
+      void relayBridge(port, data);
+    },
+  };
+}
+
+async function encodeBase64(file: Blob): Promise<string> {
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  let binary = "";
+  const chunk = 0x8000;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode.apply(null, Array.from(bytes.subarray(index, index + chunk)));
+  }
+  return btoa(binary);
+}