@unifedev/thread-pages 0.3.2 → 1.1.0

package/src/runtime/kernel/api.ts

@@ -0,0 +1,15 @@
+/**
+ * `window.threadPage`: the complete page-facing API, frozen, non-writable and
+ * non-configurable so one script cannot shim it for another. spec R4.3, R4.28–R4.33
+ */
+export interface ThreadPageApi {
+  readonly version: 1;
+  invoke(method: string, params?: unknown): Promise<unknown>;
+  watch(method: string, params: unknown, listener: (value: unknown, error: unknown) => void, options?: { intervalMs?: number }): () => void;
+  setDirty(dirty: boolean): void;
+}
+
+export function installApi(target: Window, api: ThreadPageApi): void {
+  const frozen = Object.freeze({ version: 1 as const, invoke: api.invoke, watch: api.watch, setDirty: api.setDirty });
+  Object.defineProperty(target, "threadPage", { value: frozen, writable: false, configurable: false, enumerable: true });
+}

package/src/runtime/kernel/bridge-client.ts

@@ -0,0 +1,148 @@
+import { LIMITS } from "../../domain/limits.ts";
+import { BRIDGE_VERSION, isBridgeResponse, type BridgeRequestMessage, type BridgeResponseMessage } from "../shared/protocol.ts";
+import type { BridgeErrorCode } from "../../domain/errors.ts";
+
+/**
+ * `invoke` and `watch` as a page sees them. Calls made before the port is
+ * ready are queued; every response is checked before it is trusted; a
+ * failure rejects with an Error carrying a `code`. spec R4.28–R4.32
+ */
+export interface BridgeClient {
+  invoke(method: string, params?: unknown): Promise<unknown>;
+  watch(method: string, params: unknown, listener: (value: unknown, error: unknown) => void, options?: { intervalMs?: number }): () => void;
+  /** Called by the kernel once the shell hands over the port. */
+  attach(post: (message: BridgeRequestMessage) => void): void;
+  /** Called by the kernel for every port message; returns true when consumed. */
+  receive(message: unknown): boolean;
+}
+
+export class ThreadPageError extends Error {
+  readonly code: BridgeErrorCode;
+  constructor(code: BridgeErrorCode, message: string) {
+    super(message);
+    this.name = "ThreadPageError";
+    this.code = code;
+    Object.defineProperty(this, "code", { value: code, enumerable: true, writable: false });
+  }
+}
+
+interface Pending {
+  request: BridgeRequestMessage;
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+}
+
+export function createBridgeClient(pageRevision: string, doc: Document): BridgeClient {
+  const pending = new Map<string, Pending>();
+  const queued: string[] = [];
+  let post: ((message: BridgeRequestMessage) => void) | null = null;
+  let sequence = 0;
+
+  function nextId(): string {
+    sequence += 1;
+    const random = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `${Date.now()}-${sequence}`;
+    return `tp-${random}`;
+  }
+
+  function send(id: string): void {
+    const entry = pending.get(id);
+    if (!entry || !post) return;
+    try {
+      post(entry.request);
+    } catch (error) {
+      pending.delete(id);
+      entry.reject(new ThreadPageError("invalid_request", error instanceof Error ? error.message : "The request could not be sent"));
+    }
+  }
+
+  function invoke(method: string, params?: unknown): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      if (typeof method !== "string") {
+        reject(new ThreadPageError("invalid_request", "A method name is required"));
+        return;
+      }
+      const id = nextId();
+      const request: BridgeRequestMessage = { v: BRIDGE_VERSION, id, method, params: params === undefined ? null : params, pageRevision };
+      pending.set(id, { request, resolve, reject });
+      if (post) send(id);
+      else queued.push(id);
+    });
+  }
+
+  function watch(method: string, params: unknown, listener: (value: unknown, error: unknown) => void, options?: { intervalMs?: number }): () => void {
+    if (typeof listener !== "function") throw new TypeError("Thread Page watch needs a listener");
+    const requested = options?.intervalMs;
+    const interval = typeof requested === "number" && Number.isFinite(requested)
+      ? Math.max(LIMITS.watchMinMs, Math.min(LIMITS.watchMaxMs, Math.round(requested)))
+      : LIMITS.watchDefaultMs;
+    let stopped = false;
+    let running = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    function schedule(delay: number): void {
+      if (stopped) return;
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(tick, delay);
+    }
+    async function tick(): Promise<void> {
+      timer = null;
+      if (stopped || running || doc.visibilityState === "hidden") return;
+      running = true;
+      try {
+        const value = await invoke(method, params);
+        if (!stopped) listener(value, null);
+      } catch (error) {
+        if (!stopped) listener(undefined, error);
+      } finally {
+        running = false;
+        if (!stopped) schedule(interval);
+      }
+    }
+    function onVisibility(): void {
+      if (stopped) return;
+      if (doc.visibilityState === "hidden") {
+        if (timer !== null) clearTimeout(timer);
+        timer = null;
+      } else {
+        schedule(0);
+      }
+    }
+    doc.addEventListener("visibilitychange", onVisibility);
+    schedule(0);
+    return () => {
+      if (stopped) return;
+      stopped = true;
+      if (timer !== null) clearTimeout(timer);
+      timer = null;
+      doc.removeEventListener("visibilitychange", onVisibility);
+    };
+  }
+
+  return {
+    invoke,
+    watch,
+    attach(poster) {
+      post = poster;
+      while (queued.length > 0) {
+        const id = queued.shift();
+        if (id) send(id);
+      }
+    },
+    receive(message) {
+      if (typeof message !== "object" || message === null) return false;
+      const id = (message as { id?: unknown }).id;
+      if (typeof id !== "string") return false;
+      const entry = pending.get(id);
+      if (!entry) return false;
+      pending.delete(id);
+      if (!isBridgeResponse(message, id)) {
+        entry.reject(new ThreadPageError("invalid_response", "The Thread Page bridge returned an invalid response"));
+        return true;
+      }
+      const response = message as BridgeResponseMessage;
+      if (response.ok) entry.resolve(response.result);
+      else entry.reject(new ThreadPageError(response.error.code, response.error.message));
+      return true;
+    },
+  };
+}

package/src/runtime/kernel/dirty.ts

@@ -0,0 +1,51 @@
+/**
+ * The dirty flag: typing into a captured form, or a page's explicit
+ * `setDirty(true)`, tells the shell not to reload under the reader.
+ * spec R2.21–R2.23
+ */
+export interface DirtyTracker {
+  /** Current combined state. */
+  isDirty(): boolean;
+  /** Marks a form dirty; returns the version recorded for it. */
+  markForm(form: HTMLFormElement): number;
+  /** The version a form was last marked with, if any. */
+  versionOf(form: HTMLFormElement): number | undefined;
+  /** Clears a form's dirt only if nothing touched it since `version`. */
+  clearForm(form: HTMLFormElement, version: number | undefined): void;
+  setCustom(dirty: boolean): void;
+}
+
+export function createDirtyTracker(onChange: (dirty: boolean) => void): DirtyTracker {
+  const versions = new Map<HTMLFormElement, number>();
+  let sequence = 0;
+  let custom = false;
+  let last = false;
+
+  function sync(): void {
+    const next = custom || versions.size > 0;
+    if (next === last) return;
+    last = next;
+    onChange(next);
+  }
+
+  return {
+    isDirty: () => last,
+    markForm(form) {
+      sequence += 1;
+      versions.set(form, sequence);
+      sync();
+      return sequence;
+    },
+    versionOf: (form) => versions.get(form),
+    clearForm(form, version) {
+      if (version !== undefined && versions.get(form) === version) {
+        versions.delete(form);
+        sync();
+      }
+    },
+    setCustom(dirty) {
+      custom = dirty === true;
+      sync();
+    },
+  };
+}

package/src/runtime/kernel/forms.ts

@@ -0,0 +1,114 @@
+import { LIMITS } from "../../domain/limits.ts";
+import type { SubmitFile } from "../shared/protocol.ts";
+import { collectAnswers } from "./labels.ts";
+
+/**
+ * Automatic form capture. spec R4.5–R4.9
+ *
+ * Every `<form>` without `data-thread-page-manual` is captured: native
+ * validation is suppressed (blank is an answer), a status line is kept per
+ * form, ranges get a live readout, and while a submission is in flight the
+ * form's controls are disabled and restored afterwards.
+ */
+export const MANUAL_ATTRIBUTE = "data-thread-page-manual";
+export const STATUS_ATTRIBUTE = "data-thread-page-status";
+const RANGE_ATTRIBUTE = "data-thread-page-range";
+
+export interface SubmitIntent {
+  submissionId: string;
+  form: HTMLFormElement;
+  title: string;
+  answers: ReturnType<typeof collectAnswers>;
+  files: SubmitFile[];
+}
+
+export function isManualForm(form: Element): boolean {
+  return form.hasAttribute(MANUAL_ATTRIBUTE);
+}
+
+export function capturedForms(root: ParentNode | Element): HTMLFormElement[] {
+  const forms: HTMLFormElement[] = [];
+  if ("tagName" in root && (root as Element).tagName.toLowerCase() === "form") forms.push(root as HTMLFormElement);
+  if ("querySelectorAll" in root) forms.push(...Array.from(root.querySelectorAll("form")));
+  return forms.filter((form) => !isManualForm(form));
+}
+
+export function statusLine(form: HTMLFormElement): HTMLElement {
+  let node = form.querySelector<HTMLElement>(`[${STATUS_ATTRIBUTE}]`);
+  if (!node) {
+    node = form.ownerDocument.createElement("p");
+    node.setAttribute(STATUS_ATTRIBUTE, "");
+    node.setAttribute("role", "status");
+    form.appendChild(node);
+  }
+  return node;
+}
+
+const preparedRanges = new WeakSet<HTMLInputElement>();
+
+export function prepareForm(form: HTMLFormElement): void {
+  form.noValidate = true;
+  for (const input of Array.from(form.querySelectorAll<HTMLInputElement>('input[type="range"]'))) {
+    if (preparedRanges.has(input)) continue;
+    preparedRanges.add(input);
+    const output = form.ownerDocument.createElement("output");
+    output.setAttribute(RANGE_ATTRIBUTE, "");
+    const sync = () => {
+      output.textContent = String(input.value);
+    };
+    input.addEventListener("input", sync);
+    sync();
+    input.insertAdjacentElement("afterend", output);
+  }
+}
+
+export type FormControl = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLButtonElement | HTMLFieldSetElement;
+
+export function controlsOf(form: HTMLFormElement): FormControl[] {
+  return Array.from(form.querySelectorAll<FormControl>("input,textarea,select,button,fieldset"));
+}
+
+export function filesOf(form: HTMLFormElement): SubmitFile[] {
+  const out: SubmitFile[] = [];
+  for (const input of Array.from(form.querySelectorAll<HTMLInputElement>('input[type="file"]'))) {
+    if (input.disabled) continue;
+    for (const file of Array.from(input.files ?? [])) {
+      if (out.length >= LIMITS.uploadsPerForm) return out;
+      out.push({ field: input.name || "file", file });
+    }
+  }
+  return out;
+}
+
+export interface PendingForm {
+  form: HTMLFormElement;
+  disabled: FormControl[];
+  dirtyVersion: number | undefined;
+}
+
+/** Disables the controls that were enabled, remembering them for restore. spec R4.8 */
+export function lockForm(form: HTMLFormElement): FormControl[] {
+  const disabled: FormControl[] = [];
+  for (const control of controlsOf(form)) {
+    if (!control.disabled) {
+      control.disabled = true;
+      disabled.push(control);
+    }
+  }
+  return disabled;
+}
+
+export function unlockForm(disabled: FormControl[]): void {
+  for (const control of disabled) control.disabled = false;
+}
+
+export function titleOf(form: HTMLFormElement): string {
+  const explicit = form.getAttribute("data-title");
+  if (explicit && explicit.trim()) return explicit.trim().slice(0, 300);
+  const heading = form.ownerDocument.querySelector("h1");
+  return (heading?.textContent || "").trim().slice(0, 300) || "Thread Page";
+}
+
+export function buildIntent(form: HTMLFormElement, submitter: HTMLElement | null, submissionId: string): SubmitIntent {
+  return { submissionId, form, title: titleOf(form), answers: collectAnswers(form, submitter), files: filesOf(form) };
+}

package/src/runtime/kernel/install.ts

@@ -0,0 +1,156 @@
+import { HANDSHAKE_VERSION, isRecord, type KernelConfig, type KernelMessage, type ShellMessage } from "../shared/protocol.ts";
+import { installAnchorInterception } from "./anchors.ts";
+import { installApi } from "./api.ts";
+import { createBridgeClient } from "./bridge-client.ts";
+import { createDirtyTracker } from "./dirty.ts";
+import { buildIntent, capturedForms, isManualForm, lockForm, prepareForm, statusLine, unlockForm, type PendingForm } from "./forms.ts";
+import { createReadOnlyController } from "./readonly.ts";
+
+/**
+ * Wires the kernel into a document. Exported separately from `main.ts` so
+ * tests can install it into a jsdom window with a fake port.
+ */
+export interface KernelHandle {
+  /** For tests: deliver a shell message as if it arrived on the port. */
+  deliver(message: ShellMessage): void;
+  /** For tests: connect a port-like object the way the handshake would. */
+  connect(port: Pick<MessagePort, "postMessage"> & Partial<Pick<MessagePort, "start" | "onmessage">>): void;
+}
+
+export function installKernel(win: Window & typeof globalThis, config: KernelConfig): KernelHandle {
+  const doc = win.document;
+  let port: MessagePort | null = null;
+  const pendingForms = new Map<string, PendingForm>();
+  const pendingByForm = new WeakSet<HTMLFormElement>();
+
+  function post(message: KernelMessage): boolean {
+    if (!port) return false;
+    try {
+      port.postMessage(message);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  const dirty = createDirtyTracker((isDirty) => {
+    post({ kind: isDirty ? "thread-page:dirty" : "thread-page:clean" });
+  });
+  const bridge = createBridgeClient(config.pageRevision, doc);
+  const readOnly = createReadOnlyController(doc, config.stale);
+
+  installApi(win, {
+    version: 1,
+    invoke: (method, params) => bridge.invoke(method, params),
+    watch: (method, params, listener, options) => bridge.watch(method, params, listener, options),
+    setDirty: (value) => dirty.setCustom(value !== false),
+  });
+
+  function prepare(root: ParentNode): void {
+    for (const form of capturedForms(root)) prepareForm(form);
+    readOnly.prepare(root);
+  }
+
+  prepare(doc);
+  if (doc.readyState === "loading") doc.addEventListener("DOMContentLoaded", () => prepare(doc), { once: true });
+  if (typeof win.MutationObserver === "function" && doc.documentElement) {
+    const observer = new win.MutationObserver((records) => {
+      for (const record of records) {
+        for (const node of Array.from(record.addedNodes)) {
+          if (node.nodeType === 1) prepare(node as Element);
+        }
+      }
+    });
+    observer.observe(doc.documentElement, { childList: true, subtree: true });
+  }
+
+  function markDirty(event: Event): void {
+    const target = event.target as Element | null;
+    const form = target?.closest?.("form");
+    if (!form || isManualForm(form)) return;
+    dirty.markForm(form);
+  }
+  doc.addEventListener("input", markDirty, true);
+  doc.addEventListener("change", markDirty, true);
+
+  doc.addEventListener(
+    "submit",
+    (event) => {
+      const form = event.target as Element | null;
+      if (!form || form.tagName?.toLowerCase() !== "form" || isManualForm(form)) return;
+      event.preventDefault();
+      if (readOnly.isReadOnly() || pendingByForm.has(form as HTMLFormElement)) return;
+      const submissionId = `sub-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+      const target = form as HTMLFormElement;
+      const intent = buildIntent(target, (event as SubmitEvent).submitter ?? null, submissionId);
+      const pending: PendingForm = { form: target, disabled: [], dirtyVersion: dirty.versionOf(target) };
+      pendingForms.set(submissionId, pending);
+      pendingByForm.add(target);
+      statusLine(target).textContent = intent.files.length > 0 ? "Uploading…" : "Sending…";
+      pending.disabled = lockForm(target);
+      const sent = post({ kind: "thread-page:submit", submissionId, title: intent.title, answers: intent.answers, files: intent.files });
+      if (!sent) {
+        pendingForms.delete(submissionId);
+        pendingByForm.delete(target);
+        unlockForm(pending.disabled);
+        statusLine(target).textContent = "Page connection is not ready; try again in a moment.";
+      }
+    },
+    true,
+  );
+
+  installAnchorInterception(doc, (url, label) => {
+    void bridge.invoke("navigation.openExternal", label ? { url, label } : { url }).catch(() => undefined);
+  });
+
+  function onShellMessage(data: unknown): void {
+    if (!isRecord(data)) return;
+    if (data.kind === "thread-page:source-state") {
+      readOnly.apply(data.stale === true);
+      return;
+    }
+    if (data.kind === "thread-page:submit-progress") {
+      const pending = typeof data.submissionId === "string" ? pendingForms.get(data.submissionId) : undefined;
+      if (pending) statusLine(pending.form).textContent = String(data.message ?? "Working…").slice(0, 160);
+      return;
+    }
+    if (data.kind === "thread-page:submit-result") {
+      const pending = typeof data.submissionId === "string" ? pendingForms.get(data.submissionId) : undefined;
+      if (!pending) return;
+      pendingForms.delete(data.submissionId as string);
+      pendingByForm.delete(pending.form);
+      const ok = data.ok === true;
+      statusLine(pending.form).textContent = ok ? String(data.message ?? "Sent").slice(0, 160) : String(data.error ?? "Could not send").slice(0, 160);
+      unlockForm(pending.disabled);
+      if (readOnly.isReadOnly()) readOnly.apply(true);
+      if (ok) dirty.clearForm(pending.form, pending.dirtyVersion);
+      return;
+    }
+    bridge.receive(data);
+  }
+
+  function connect(next: MessagePort): void {
+    port = next;
+    next.onmessage = (message) => onShellMessage(message.data);
+    next.start?.();
+    bridge.attach((request) => {
+      next.postMessage(request);
+    });
+    if (dirty.isDirty()) post({ kind: "thread-page:dirty" });
+  }
+
+  function acceptPort(event: MessageEvent): void {
+    if (port || event.source !== win.parent) return;
+    const data = event.data as unknown;
+    if (!isRecord(data) || data.kind !== "thread-page:connect" || data.version !== HANDSHAKE_VERSION || !event.ports || event.ports.length !== 1) return;
+    event.stopImmediatePropagation();
+    const next = event.ports[0];
+    if (next) connect(next);
+  }
+  win.addEventListener("message", acceptPort, true);
+
+  if (config.stale) readOnly.apply(true);
+  win.parent.postMessage({ kind: "thread-page:ready", version: HANDSHAKE_VERSION }, "*");
+
+  return { deliver: (message) => onShellMessage(message), connect: (fake) => connect(fake as MessagePort) };
+}

package/src/runtime/kernel/labels.ts

@@ -0,0 +1,98 @@
+import type { SubmitAnswer } from "../shared/protocol.ts";
+
+/**
+ * Answer naming and group collapsing. spec R4.10–R4.12
+ *
+ * The reader sees labels, not field names, so a delivered answer carries the
+ * label. Order: explicit `data-label`; the nearest fieldset's legend; the
+ * control's `aria-label`; the text of a wrapping `<label>`; the text of a
+ * `<label for>`; the raw name. Derived text excludes nested controls, option
+ * text, hints and host-injected nodes.
+ */
+const EXCLUDED_FROM_TEXT = "input,textarea,select,button,option,small,output,[data-thread-page-range],[data-thread-page-status]";
+
+export type FormControl = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | HTMLButtonElement;
+
+export function labelText(node: Element | null): string {
+  if (!node) return "";
+  const clone = node.cloneNode(true) as Element;
+  for (const child of Array.from(clone.querySelectorAll(EXCLUDED_FROM_TEXT))) child.remove();
+  return (clone.textContent || "").replace(/\s+/g, " ").trim();
+}
+
+export function labelFor(form: HTMLFormElement, control: FormControl): string {
+  const explicit = control.getAttribute("data-label");
+  if (explicit && explicit.trim()) return explicit.trim();
+  const fieldset = control.closest("fieldset");
+  if (fieldset) {
+    const legend = labelText(fieldset.querySelector("legend"));
+    if (legend) return legend;
+  }
+  const aria = control.getAttribute("aria-label");
+  if (aria && aria.trim()) return aria.trim();
+  const wrapping = control.closest("label");
+  if (wrapping) {
+    const text = labelText(wrapping);
+    if (text) return text;
+  }
+  if (control.id) {
+    const doc = form.ownerDocument;
+    const referenced = Array.from(doc.querySelectorAll("label[for]")).find((label) => (label as HTMLLabelElement).htmlFor === control.id);
+    const text = labelText(referenced ?? null);
+    if (text) return text;
+  }
+  return control.name;
+}
+
+const SKIPPED_TYPES = new Set(["button", "submit", "reset", "image", "file"]);
+
+export function namedControls(form: HTMLFormElement): FormControl[] {
+  return Array.from(form.elements).filter((element): element is FormControl => {
+    const control = element as FormControl;
+    return typeof control.name === "string" && control.name.length > 0 && !control.disabled && "type" in control;
+  });
+}
+
+/** Collects answers in document order; the submitter leads as the chosen action. spec R2.36 */
+export function collectAnswers(form: HTMLFormElement, submitter: HTMLElement | null): SubmitAnswer[] {
+  const controls = namedControls(form);
+  const answers: SubmitAnswer[] = [];
+  const seen = new Set<string>();
+  if (submitter && (tagOf(submitter) === "button" || tagOf(submitter) === "input")) {
+    const control = submitter as HTMLButtonElement | HTMLInputElement;
+    const value = control.value || (control.textContent || "").trim();
+    answers.push({ name: control.name || "action", label: "Action", value });
+    if (control.name) seen.add(control.name);
+  }
+  for (const control of controls) {
+    const name = control.name;
+    const type = String(control.type || "").toLowerCase();
+    if (seen.has(name) || SKIPPED_TYPES.has(type)) continue;
+    seen.add(name);
+    const group = controls.filter((item) => item.name === name);
+    answers.push({ name, label: labelFor(form, control), value: collapse(control, group, type) });
+  }
+  return answers;
+}
+
+/** Tag checks rather than `instanceof`, so the kernel works across realms and with custom elements. */
+export function tagOf(element: Element): string {
+  return element.tagName.toLowerCase();
+}
+
+function collapse(control: FormControl, group: FormControl[], type: string): string | string[] | boolean {
+  if (type === "checkbox") {
+    const boxes = group.filter((item): item is HTMLInputElement => tagOf(item) === "input");
+    if (boxes.length === 1) return boxes[0]?.checked === true;
+    return boxes.filter((item) => item.checked).map((item) => item.value);
+  }
+  if (type === "radio") {
+    const checked = group.find((item) => tagOf(item) === "input" && (item as HTMLInputElement).checked) as HTMLInputElement | undefined;
+    return checked ? checked.value : "";
+  }
+  if (tagOf(control) === "select" && (control as HTMLSelectElement).multiple) {
+    return Array.from((control as HTMLSelectElement).selectedOptions).map((option) => option.value);
+  }
+  if (group.length > 1) return group.map((item) => String((item as HTMLInputElement).value ?? ""));
+  return String((control as HTMLInputElement).value ?? "");
+}

package/src/runtime/kernel/main.ts

@@ -0,0 +1,6 @@
+import { readConfig, type KernelConfig } from "../shared/protocol.ts";
+import { installKernel } from "./install.ts";
+
+// Entry for the bundled kernel: runs before any authored script (spec R4.1)
+// and reads its configuration from its own script element.
+installKernel(window, readConfig<KernelConfig>(document.currentScript));

package/src/runtime/kernel/readonly.ts

@@ -0,0 +1,75 @@
+import { capturedForms, controlsOf, statusLine, type FormControl } from "./forms.ts";
+
+/**
+ * Read-only mode for an offline copy: disable the captured-form controls the
+ * host finds enabled, show a status line per form and a banner the page
+ * cannot suppress; on reconnection restore only what was disabled here.
+ * spec R2.28, R4.34, R4.35
+ */
+export const OFFLINE_ATTRIBUTE = "data-thread-page-offline";
+export const OFFLINE_STATUS = "Offline copy — responses are disabled until the source host reconnects.";
+
+export interface ReadOnlyController {
+  isReadOnly(): boolean;
+  apply(readOnly: boolean): void;
+  /** Applies the current state to newly added content. */
+  prepare(root: ParentNode): void;
+}
+
+export function createReadOnlyController(doc: Document, initial: boolean): ReadOnlyController {
+  const disabledByHost = new Set<FormControl>();
+  let readOnly = initial;
+
+  function banner(): void {
+    if (!doc.body) return;
+    let node = doc.querySelector<HTMLElement>(`[${OFFLINE_ATTRIBUTE}="host"]`);
+    if (readOnly && !node) {
+      node = doc.createElement("aside");
+      node.setAttribute(OFFLINE_ATTRIBUTE, "host");
+      node.setAttribute("role", "status");
+      node.setAttribute(
+        "style",
+        "position:relative;z-index:2147483647;margin:0;padding:.75rem 1rem;border-bottom:1px solid currentColor;font:600 14px/1.4 system-ui,sans-serif;background:Canvas;color:CanvasText",
+      );
+      node.textContent = OFFLINE_STATUS;
+      doc.body.insertBefore(node, doc.body.firstChild);
+    } else if (!readOnly && node) {
+      node.remove();
+    }
+  }
+
+  function lock(root: ParentNode): void {
+    for (const form of capturedForms(root)) {
+      for (const control of controlsOf(form)) {
+        if (!control.disabled) {
+          control.disabled = true;
+          disabledByHost.add(control);
+        }
+      }
+      statusLine(form).textContent = OFFLINE_STATUS;
+    }
+  }
+
+  function unlock(): void {
+    for (const control of disabledByHost) control.disabled = false;
+    disabledByHost.clear();
+    for (const form of capturedForms(doc)) {
+      const status = statusLine(form);
+      if (status.textContent === OFFLINE_STATUS) status.textContent = "";
+    }
+  }
+
+  return {
+    isReadOnly: () => readOnly,
+    apply(next) {
+      readOnly = next;
+      if (next) lock(doc);
+      else unlock();
+      banner();
+    },
+    prepare(root) {
+      if (readOnly) lock(root);
+      banner();
+    },
+  };
+}