@plannotator/ui 0.54.0 → 0.56.0

package/components/chat/chatMarkdown.ts

@@ -0,0 +1,436 @@
+import DOMPurify from 'dompurify';
+import { Lexer, Marked, type MarkedExtension, type Token, type Tokens } from 'marked';
+
+import { CHAT_SANITIZE_CONFIG } from '../../utils/aiChatFormat';
+
+/** The characters HTML gives meaning to, as text. */
+function escapeHtml(text: string): string {
+  return text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+/** Each line break is an element, so a text of nothing but line ends must not
+ * draw one per line. Past this they read as spaces. */
+const MAX_PLAIN_BREAKS = 20_000;
+
+/**
+ * Layout has two costs no limit on length sees, both from text that changes script
+ * or direction all the time.
+ *
+ * Each change starts a new run, and a browser goes back over a block's runs for
+ * each line it wraps, so a block draws in about the square of its changes: 250 KB
+ * of `سa` takes 13 s as one block and a third of a second as blocks of 2 KB. A line
+ * break does not help, because a block is laid out whole, so what counts is the
+ * block. ASCII is one run, so every change takes a character past ASCII, and those
+ * are what is counted. That leaves a long line of code at no cost, and these
+ * limits are several pages of Chinese in one paragraph.
+ *
+ * WebKit also searches a word with no place to break again for each line, so the
+ * same text with no spaces is far worse there: 16 KB of it took three minutes.
+ * `withBreaks` gives such a word a place to break, which took that to 130 ms.
+ */
+const MAX_NON_ASCII_IN_BLOCK = 10_000;
+/** While a text streams, because that is paid on every delta, and in plain text. */
+const MAX_NON_ASCII_IN_SMALL_BLOCK = 2_000;
+const MAX_UNBROKEN_CHARS = 256;
+
+const SPACE = 32;
+const LAST_ASCII = 126;
+
+function nonAsciiIn(text: string): number {
+  let count = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    if (text.charCodeAt(index) > LAST_ASCII) count += 1;
+  }
+  return count;
+}
+
+const isHighSurrogate = (code: number): boolean => code >= 0xd800 && code <= 0xdbff;
+
+/**
+ * The text escaped, with a `<wbr>` in each word past the limit, or null if it has
+ * none and can go out as usual. A `<wbr>` adds no character, so a word copies whole.
+ */
+function withBreaks(text: string): string | null {
+  let html = '';
+  let from = 0;
+  let unbroken = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    unbroken = code <= SPACE ? 0 : unbroken + 1;
+    if (unbroken >= MAX_UNBROKEN_CHARS && !isHighSurrogate(code)) {
+      html += `${escapeHtml(text.slice(from, index + 1))}<wbr>`;
+      from = index + 1;
+      unbroken = 0;
+    }
+  }
+  return from === 0 ? null : html + escapeHtml(text.slice(from));
+}
+
+const PLAIN_PIECE = /\r\n?|\n|[^\r\n]{1,2000}/gu;
+
+/** The one safe answer when markdown or the sanitizer cannot be trusted: the
+ * source as plain text, keeping its lines. */
+function asPlainText(source: string): string {
+  let breaks = 0;
+  let nonAscii = 0;
+  const blocks = source.replace(PLAIN_PIECE, (piece) => {
+    if (piece[0] === '\r' || piece[0] === '\n') {
+      breaks += 1;
+      return breaks > MAX_PLAIN_BREAKS ? piece : '<br>';
+    }
+    const text = withBreaks(piece) ?? escapeHtml(piece);
+    nonAscii += nonAsciiIn(piece);
+    if (nonAscii < MAX_NON_ASCII_IN_SMALL_BLOCK) return text;
+    nonAscii = 0;
+    return `${text}</p><p>`;
+  });
+  return `<p>${blocks}</p>`;
+}
+
+/**
+ * Tags from the Ask AI panel's list: no scripts, no handlers, no images, so
+ * this text cannot load a remote address. Attributes are tighter than that
+ * list, because this HTML lands inside a host's page: `class` would hand it the
+ * host's own stylesheet (a full-page `fixed` link), and `data-*` or `aria-*`
+ * would let it pose as the anchors hosts read off a text part.
+ *
+ * Read when the sanitizer is built, not on load, so this file and the one that
+ * holds the list can import each other.
+ */
+function chatPurifyConfig() {
+  return {
+    ALLOWED_TAGS: [...CHAT_SANITIZE_CONFIG.ALLOWED_TAGS, 'wbr'],
+    ALLOWED_ATTR: ['href', 'align'],
+    ALLOW_DATA_ATTR: false,
+    ALLOW_ARIA_ATTR: false,
+  };
+}
+
+/** Everything the sanitizer must take out. It proves itself on this before any
+ * real text, because `isSupported` is not proof: a partial DOM reports true and
+ * lets scripts through. */
+const PROOF_INPUT =
+  '<a href="javascript:alert(1)" class="c" data-c="1" onclick="alert(2)">kept</a>' +
+  '<img src="x" onerror="alert(3)"><script>alert(4)</script>';
+const PROOF_FAILED = /javascript:|class=|data-c|onclick|onerror|<img|<script/i;
+
+type Sanitize = (html: string) => string;
+
+function buildSanitizer(): Sanitize | null {
+  if (typeof window === 'undefined') return null;
+  // A private instance: a hook on the shared one would reach every other caller.
+  const purifier = DOMPurify(window);
+  // Links open in a new tab: a host must not lose its page to a link in a
+  // message. Set after the allowlist has run, so only this code writes them.
+  purifier.addHook('afterSanitizeAttributes', (node) => {
+    if (node.nodeName !== 'A') return;
+    node.setAttribute('target', '_blank');
+    node.setAttribute('rel', 'noopener noreferrer');
+  });
+  const config = chatPurifyConfig();
+  const proof = purifier.sanitize(PROOF_INPUT, config);
+  if (PROOF_FAILED.test(proof) || !proof.includes('kept')) return null;
+  return (html) => purifier.sanitize(html, config);
+}
+
+let provenSanitizer: Sanitize | null | undefined;
+
+/** The sanitizer, once it has shown it works here. Null: nothing may go out as HTML. */
+function sanitizerThatWorks(): Sanitize | null {
+  if (provenSanitizer === undefined) {
+    try {
+      provenSanitizer = buildSanitizer();
+    } catch {
+      provenSanitizer = null;
+    }
+  }
+  return provenSanitizer;
+}
+
+/**
+ * `marked` has inputs that overflow the stack, inputs that take minutes and
+ * inputs that build a page's worth of nodes, and running out of memory kills
+ * the tab with nothing to catch. So the work is bounded at each step it can
+ * grow, and a text past a limit draws as plain text:
+ *
+ * - Before `marked`: the text's length.
+ * - Inside `marked`: a time budget, checked at each token, each run of inline
+ *   text and each link drawn. It is a check, not a wall: one tokenizer call can
+ *   overrun it, so `chatTextRenderer` stops a stream paying for that again.
+ * - After `marked`: the length of the HTML, lower while a text streams. Raw HTML
+ *   goes out escaped on both of `marked`'s ways out, the `html` and `text`
+ *   renderers, so what is left is `marked`'s own well-formed output and its length
+ *   is its size in the DOM. That is what bounds sanitizing and drawing: a short
+ *   string of unclosed tags can parse into a million nodes.
+ * - For layout: the characters past ASCII in each block, as `checkBlock` counts
+ *   them. A text past that draws as plain text in smaller blocks.
+ *
+ * Two limits are local. A table past the cell limit is left as the text it is,
+ * and a run of inline text that `tooMuchInline` refuses draws as literal text,
+ * because those costs sit where no budget check reaches. The rest of the message
+ * stays formatted, and both are asked where `marked` itself would do the work, so
+ * a code block never counts.
+ *
+ * The budget is wall-clock, so a text close to it can draw either way.
+ */
+const MARKDOWN_BUDGET_MS = 250;
+const MAX_TEXT_CHARS = 256_000;
+const MAX_TABLE_CELLS = 100_000;
+const MAX_HTML_CHARS = 1_000_000;
+const MAX_STREAMED_HTML_CHARS = 250_000;
+const MAX_WORD_CHARS = 8_000;
+const MAX_SPACE_RUN = 1_000;
+/** About a tenth of a second of copying on a laptop. */
+const MAX_MASKING_WORK = 1_000_000_000;
+
+/** What opens a masked run: `<`, `[`, a backslash and a backtick. */
+const MASKED_MARKS = new Set([60, 91, 92, 96]);
+
+const TABLE_DELIMITER = /^[ :|-]+$/;
+
+/**
+ * Would a table starting here pad past the cell limit? Every row is padded to
+ * the header's width inside one tokenizer call, which no check inside `marked`
+ * can interrupt and which can run the tab out of memory. A table's width is its
+ * delimiter row, the second line, and its rows end by the next blank line at the
+ * latest.
+ */
+function tableTooBig(src: string): boolean {
+  const delimiterAt = src.indexOf('\n') + 1;
+  if (delimiterAt === 0) return false;
+  const lineEnd = src.indexOf('\n', delimiterAt);
+  const delimiter = src.slice(delimiterAt, lineEnd === -1 ? src.length : lineEnd);
+  if (!TABLE_DELIMITER.test(delimiter)) return false;
+  const columns = delimiter.split('|').length;
+  let rows = 0;
+  let at = lineEnd;
+  while (at !== -1 && src[at + 1] !== '\n' && columns * rows <= MAX_TABLE_CELLS) {
+    rows += 1;
+    at = src.indexOf('\n', at + 1);
+  }
+  return columns * rows > MAX_TABLE_CELLS;
+}
+
+/**
+ * Is this run of inline text past what `marked` can do between budget checks?
+ *
+ * A word: only ASCII adds to one, because `marked`'s inline expressions stop at
+ * anything else, so a paragraph of Chinese with no spaces is not one long word.
+ * Other letters do not end a word either, or they could split a hostile run.
+ *
+ * A run of spaces: with `breaks: true` that is quadratic inside one expression.
+ *
+ * Masking: before its first token `marked` copies the whole run once for each
+ * code span, tag, link or escape in it, so marks times length is what it costs.
+ */
+function tooMuchInline(text: string): boolean {
+  let word = 0;
+  let spaces = 0;
+  let marks = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    spaces = code === SPACE ? spaces + 1 : 0;
+    if (spaces > MAX_SPACE_RUN) return true;
+    if (code <= SPACE) {
+      word = 0;
+    } else if (code <= LAST_ASCII) {
+      word += 1;
+      if (word > MAX_WORD_CHARS) return true;
+      if (MASKED_MARKS.has(code)) marks += 1;
+    }
+  }
+  return marks * text.length > MAX_MASKING_WORK;
+}
+
+let deadline = 0;
+let blockLimit = MAX_NON_ASCII_IN_BLOCK;
+
+/** A tokenizer that matches nothing: `marked` asks it before every token. */
+function checkBudget(): undefined {
+  if (Date.now() > deadline) throw new Error('markdown budget spent');
+  return undefined;
+}
+
+/** Called with all the text of one block: a run of inline text, a code block or a
+ * block of raw HTML. Past the limit the whole message draws as plain text. */
+function checkBlock(text: string): void {
+  if (nonAsciiIn(text) > blockLimit) throw new Error('block too costly to lay out');
+}
+
+const budgetExtension: MarkedExtension = {
+  extensions: [
+    { name: 'chatBudgetBlock', level: 'block', tokenizer: checkBudget },
+    { name: 'chatBudgetInline', level: 'inline', tokenizer: checkBudget },
+  ],
+  tokenizer: {
+    // `marked` asks this only where a table can start, never inside a code
+    // block. Undefined: not a table. False: go on and try one.
+    table(src) {
+      return tableTooBig(src) ? undefined : false;
+    },
+  },
+  // A reference link repeats its whole address at every use, and that is drawn
+  // after the tokens are done. False: draw it the usual way.
+  renderer: {
+    // After a raw `<code>`, `<kbd>`, `<pre>` or `<script>`, `marked` flags the text
+    // that follows as already escaped, up to the closing tag, and writes it out as
+    // it stands. Nothing here is escaped yet: escaping is this renderer's job.
+    text(token) {
+      if ('escaped' in token) token.escaped = false;
+      if ('tokens' in token && token.tokens) return false;
+      return withBreaks(token.text) ?? false;
+    },
+    codespan({ text }) {
+      const html = withBreaks(text);
+      return html === null ? false : `<code>${html}</code>`;
+    },
+    code({ text }) {
+      checkBlock(text);
+      return false;
+    },
+    link() {
+      checkBudget();
+      return false;
+    },
+    image() {
+      checkBudget();
+      return false;
+    },
+  },
+};
+
+/** Sees every run of inline text, nested ones too, before `marked`'s own passes
+ * over it. A code block is never one, so these limits do not reach it. */
+class BoundedLexer extends Lexer {
+  override inlineTokens(src: string, tokens: Token[] = []): Token[] {
+    checkBudget();
+    checkBlock(src);
+    if (tooMuchInline(src)) {
+      tokens.push({ type: 'text', raw: src, text: src });
+      return tokens;
+    }
+    return super.inlineTokens(src, tokens);
+  }
+}
+
+const LINE_BREAK_TAG = /^<br\s*\/?>\s*$/i;
+
+/** Raw HTML as the text it is. A block of it keeps its own `<p>`, or blocks in a
+ * row would run together into one for layout. */
+function rawHtmlAsText(token: Tokens.HTML | Tokens.Tag): string {
+  checkBlock(token.text);
+  const text = withBreaks(token.text) ?? escapeHtml(token.text);
+  return 'block' in token && token.block ? `<p>${text}</p>` : text;
+}
+
+/**
+ * Raw HTML never reaches an HTML parser here: it goes out escaped, by this
+ * renderer and by the `text` one in `budgetExtension`. A browser rebuilds every
+ * open formatting tag in each new paragraph, so 27 KB of unclosed tags makes a
+ * million nodes inside the sanitizer, where no limit reaches. An answer is
+ * markdown. The one tag kept is a line break, because agents write it in table
+ * cells; it is written fresh here, so nothing of the source gets through.
+ */
+const agentMarkdown = new Marked(
+  {
+    gfm: true,
+    breaks: false,
+    renderer: {
+      html(token) {
+        return LINE_BREAK_TAG.test(token.text) ? '<br>' : rawHtmlAsText(token);
+      },
+    },
+  },
+  budgetExtension,
+);
+
+/** A person's HTML, every tag of it, stays the literal text they typed. */
+const personMarkdown = new Marked(
+  {
+    gfm: true,
+    breaks: false,
+    renderer: {
+      html(token) {
+        return rawHtmlAsText(token);
+      },
+    },
+  },
+  budgetExtension,
+);
+
+function parseMarkdown(markdown: Marked, source: string, streaming = false): string {
+  deadline = Date.now() + MARKDOWN_BUDGET_MS;
+  blockLimit = streaming ? MAX_NON_ASCII_IN_SMALL_BLOCK : MAX_NON_ASCII_IN_BLOCK;
+  return markdown.parser(new BoundedLexer(markdown.defaults).lex(source));
+}
+
+interface RenderedMessage {
+  readonly html: string;
+  /** Too costly to draw again on every delta of a stream. */
+  readonly spent: boolean;
+}
+
+/** The one way out to the DOM. It never throws: a render that throws would take
+ * the host's whole React root with it. */
+function renderMessage(markdown: Marked, source: string, streaming: boolean): RenderedMessage {
+  const sanitize = sanitizerThatWorks();
+  if (sanitize === null || source.length > MAX_TEXT_CHARS) {
+    return { html: asPlainText(source), spent: true };
+  }
+  try {
+    const html = parseMarkdown(markdown, source, streaming);
+    const limit = streaming ? MAX_STREAMED_HTML_CHARS : MAX_HTML_CHARS;
+    if (html.length > limit) return { html: asPlainText(source), spent: true };
+    const clean = sanitize(html);
+    return { html: clean, spent: Date.now() > deadline };
+  } catch {
+    return { html: asPlainText(source), spent: true };
+  }
+}
+
+/** An agent's text as sanitized HTML. */
+export function chatMarkdownHtml(markdown: string): string {
+  return renderMessage(agentMarkdown, markdown, false).html;
+}
+
+/** A held text redraws once it has grown by an eighth. */
+const HELD_TEXT_GROWTH = 1.125;
+
+/**
+ * The render for one text as it streams. Every delta re-renders the whole text,
+ * so a text too costly for that is held: plain, and redrawn only as it grows by a
+ * fixed share, so what a stream pays per delta stops growing with its length. A
+ * text is held once it spends its budget or passes a streaming limit, on its HTML
+ * or on a block. Call with `streaming` false when the stream ends: that always renders in full,
+ * so an honest message held for a moment comes back whole and formatted.
+ */
+export function chatTextRenderer(literalHtml: boolean): (text: string, streaming: boolean) => string {
+  const markdown = literalHtml ? personMarkdown : agentMarkdown;
+  let held: { readonly text: string; readonly html: string } | null = null;
+  return (text, streaming) => {
+    if (streaming && held !== null && text.startsWith(held.text)) {
+      if (text.length < held.text.length * HELD_TEXT_GROWTH) return held.html;
+      held = { text, html: asPlainText(text) };
+      return held.html;
+    }
+    const { html, spent } = renderMessage(markdown, text, streaming);
+    held = streaming && spent ? { text, html } : null;
+    return html;
+  };
+}
+
+/** The markdown step of {@link personMarkdownHtml}, before sanitizing. */
+export function personMarkdownToHtml(markdown: string): string {
+  return parseMarkdown(personMarkdown, markdown);
+}
+
+/** A person's message: markdown, but HTML they typed stays the literal text
+ * they typed. The sanitizer still runs after, as for every message. */
+export function personMarkdownHtml(markdown: string): string {
+  return renderMessage(personMarkdown, markdown, false).html;
+}

package/components/chat/chatRecipes.tsx

@@ -0,0 +1,39 @@
+import { cn } from '../../lib/utils';
+
+// A .tsx on purpose, with no JSX: the apps' Tailwind `@source` globs take
+// `packages/ui/components/**/*.tsx`, so classes in a .ts here get no rule.
+
+/** The one focus spelling in this folder: a 1 px accent border and a soft halo. */
+export const FOCUS_RING =
+  'outline-none focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring-soft';
+
+/** The bordered floating surface the window wears. */
+export const floatingDialogChrome =
+  'bg-popover text-popover-foreground rounded-dialog border border-border shadow-dialog';
+
+/** A control is at least 44 px on a phone, whatever it draws at. */
+const PHONE_TARGET = 'max-md:min-h-11 max-md:min-w-11';
+
+/** `Button` ghost and icon, narrowed to the window's 28 px control and quiet
+ * hover. The `after:` box keeps a 36 px target around the 28 px one. */
+export const CHAT_ICON_BUTTON = cn(
+  'relative size-7 border border-transparent text-muted-foreground after:absolute after:-inset-1',
+  '[@media(hover:hover)_and_(pointer:fine)]:hover:bg-surface-hover',
+  '[@media(hover:hover)_and_(pointer:fine)]:hover:text-foreground',
+  PHONE_TARGET,
+  FOCUS_RING,
+);
+
+/** The composer's 32 px Send and Stop, with no resting shadow. */
+export const CHAT_SEND_BUTTON = cn(
+  'size-8 border border-transparent shadow-none',
+  PHONE_TARGET,
+  FOCUS_RING,
+);
+
+/** Stop's quiet fill on top of `CHAT_SEND_BUTTON`. */
+export const CHAT_STOP_BUTTON = cn(
+  CHAT_SEND_BUTTON,
+  'bg-soft-quiet-fill',
+  '[@media(hover:hover)_and_(pointer:fine)]:hover:bg-soft-quiet-fill-hover',
+);

package/components/chat/chatWindowStore.ts

@@ -0,0 +1,196 @@
+/**
+ * The floating chat window's own state: minimized, fullscreen, size and the
+ * docked or floating position. A plain external store that knows nothing about
+ * conversations or the server, so ChatFrame can render from it alone.
+ *
+ * Geometry: default 420x560, min 360x420, max the frame it floats in minus
+ * margins, anchored by its bottom-right offsets so the top-left resize grip
+ * grows the window without moving its anchor.
+ *
+ * The store holds what the person chose. What is drawn is `fitChatWindow` of
+ * that against the measured frame, worked out at render, so a frame that
+ * narrows for a moment changes the picture and never the choice.
+ *
+ * Saved geometry belongs to the host. A saved value comes in through
+ * `initialGeometry` (or `restore`), every change the person makes goes out
+ * through `onGeometryChange`, and this module never reads or writes storage
+ * itself. Minimized and fullscreen are runtime state: a page load starts
+ * minimized.
+ */
+
+export const CHAT_WINDOW_DEFAULT = { width: 420, height: 560, right: 16, bottom: 16 } as const;
+export const CHAT_WINDOW_MIN = { width: 360, height: 420 } as const;
+/** Margin the window keeps from its frame at maximum size. */
+export const CHAT_WINDOW_FRAME_MARGIN = 16;
+
+/** The shape a host saves and hands back. */
+export interface ChatWindowGeometry {
+  readonly w: number;
+  readonly h: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+/** Clamp a saved dimension into [min, max]; anything non-finite falls back. */
+function clampDimension(value: unknown, min: number, max: number, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(value)));
+}
+
+/**
+ * A saved geometry made usable, with no regard to this screen: a corrupted
+ * value falls back and a size under the minimum is raised. A window sized on a
+ * big monitor keeps that size here, and `fitChatWindow` draws it to fit a
+ * laptop. Takes `unknown` because a saved value can be corrupted.
+ */
+function parseSavedGeometry(saved: unknown): ChatWindowGeometry {
+  const raw = (typeof saved === 'object' && saved !== null ? saved : {}) as Record<string, unknown>;
+  const limit = Number.POSITIVE_INFINITY;
+  return {
+    w: clampDimension(raw.w, CHAT_WINDOW_MIN.width, limit, CHAT_WINDOW_DEFAULT.width),
+    h: clampDimension(raw.h, CHAT_WINDOW_MIN.height, limit, CHAT_WINDOW_DEFAULT.height),
+    right: clampDimension(raw.right, 0, limit, CHAT_WINDOW_DEFAULT.right),
+    bottom: clampDimension(raw.bottom, 0, limit, CHAT_WINDOW_DEFAULT.bottom),
+  };
+}
+
+/**
+ * What a chosen geometry draws as in a measured frame: as large as the frame
+ * minus its margins, never under the minimum, and never off the frame. This is
+ * for the picture only: its result is not a choice, so it is neither stored
+ * nor reported.
+ */
+export function fitChatWindow(
+  wanted: ChatWindowGeometry,
+  frame: { readonly width: number; readonly height: number },
+): ChatWindowGeometry {
+  const w = Math.min(wanted.w, Math.max(CHAT_WINDOW_MIN.width, frame.width - CHAT_WINDOW_FRAME_MARGIN * 2));
+  const h = Math.min(wanted.h, Math.max(CHAT_WINDOW_MIN.height, frame.height - CHAT_WINDOW_FRAME_MARGIN * 2));
+  return {
+    w,
+    h,
+    right: Math.max(0, Math.min(wanted.right, frame.width - w)),
+    bottom: Math.max(0, Math.min(wanted.bottom, frame.height - h)),
+  };
+}
+
+export interface ChatWindowStoreOptions {
+  /** The host's saved geometry. Absent: the default dock. */
+  readonly initialGeometry?: unknown;
+  /** Runs on every change the person makes, drag and resize steps included, so
+   * a host that saves it should debounce and flush on unload. Not called for
+   * `initialGeometry`, for `restore`, or when the frame changes size. */
+  readonly onGeometryChange?: (geometry: ChatWindowGeometry) => void;
+  /** Runs whenever a minimized window opens, before listeners hear of it. */
+  readonly onOpen?: () => void;
+}
+
+export class ChatWindowStore {
+  minimized = true;
+  fullscreen = false;
+  winW: number = CHAT_WINDOW_DEFAULT.width;
+  winH: number = CHAT_WINDOW_DEFAULT.height;
+  winRight: number = CHAT_WINDOW_DEFAULT.right;
+  winBottom: number = CHAT_WINDOW_DEFAULT.bottom;
+  /** True once this window opened in this page's lifetime. */
+  openedOnce = false;
+
+  private readonly onOpen: (() => void) | null;
+  private readonly onGeometryChange: ((geometry: ChatWindowGeometry) => void) | null;
+  private listeners = new Set<() => void>();
+  private version = 0;
+
+  constructor(options: ChatWindowStoreOptions = {}) {
+    this.onOpen = options.onOpen ?? null;
+    this.onGeometryChange = options.onGeometryChange ?? null;
+    if (options.initialGeometry !== undefined) this.restore(options.initialGeometry);
+  }
+
+  // The useSyncExternalStore seam.
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  getVersion = (): number => this.version;
+  private emit(): void {
+    this.version += 1;
+    for (const listener of this.listeners) listener();
+  }
+
+  /** Every geometry write ends here: an unchanged value reports nothing. */
+  private commitGeometry(next: ChatWindowGeometry): void {
+    if (
+      next.w === this.winW &&
+      next.h === this.winH &&
+      next.right === this.winRight &&
+      next.bottom === this.winBottom
+    ) {
+      return;
+    }
+    this.winW = next.w;
+    this.winH = next.h;
+    this.winRight = next.right;
+    this.winBottom = next.bottom;
+    this.emit();
+    this.onGeometryChange?.(next);
+  }
+
+  /** Take a saved geometry. An open window redraws; no report, because the
+   * value is the host's own. */
+  restore(saved: unknown): void {
+    const restored = parseSavedGeometry(saved);
+    this.winW = restored.w;
+    this.winH = restored.h;
+    this.winRight = restored.right;
+    this.winBottom = restored.bottom;
+    this.emit();
+  }
+
+  /** The chosen geometry, in the shape `initialGeometry` takes back. */
+  geometry(): ChatWindowGeometry {
+    return { w: this.winW, h: this.winH, right: this.winRight, bottom: this.winBottom };
+  }
+
+  private open(): void {
+    this.minimized = false;
+    this.openedOnce = true;
+    this.onOpen?.();
+  }
+
+  setMinimized(minimized: boolean): void {
+    if (minimized) this.minimized = true;
+    else this.open();
+    this.emit();
+  }
+
+  /** The toggle, on an open window. On a minimized one this is the summon into
+   * fullscreen, so it always lands fullscreen. */
+  toggleFullscreen(): void {
+    if (this.minimized) {
+      this.fullscreen = true;
+      this.open();
+    } else {
+      this.fullscreen = !this.fullscreen;
+    }
+    this.emit();
+  }
+
+  /** Committed by the resize grip, already clamped against the frame. */
+  setWindowSize(width: number, height: number): void {
+    this.commitGeometry({ ...this.geometry(), w: Math.round(width), h: Math.round(height) });
+  }
+
+  /** Committed by the header drag: the bottom-right offsets within the frame. */
+  setWindowOffsets(right: number, bottom: number): void {
+    this.commitGeometry({ ...this.geometry(), right: Math.round(right), bottom: Math.round(bottom) });
+  }
+
+  /** Double-click on the header: back to the default bottom-right dock. */
+  resetWindowDock(): void {
+    this.commitGeometry({
+      ...this.geometry(),
+      right: CHAT_WINDOW_DEFAULT.right,
+      bottom: CHAT_WINDOW_DEFAULT.bottom,
+    });
+  }
+}