@zq-silk/yui 2.2.0 → 2.4.0

package/dist/web/assets/client/{dom.js → lib/dom.js}

@@ -1,4 +1,4 @@
-import { ICON_PATHS } from "../icons.js";
+import { ICON_PATHS } from "../../shared/icons.js";
 export const DOM_SCRIPT = String.raw `
 // Dependency-free DOM helpers shared by every client module.
 const ICONS = ${JSON.stringify(ICON_PATHS)};
@@ -23,21 +23,20 @@ export function h(spec, attrs) {
     children.unshift(attrs);
     attrs = null;
   }
-  if (attrs) {
-    Object.keys(attrs).forEach(function (key) {
-      const value = attrs[key];
-      if (value === undefined || value === null || value === false) return;
-      if (key === "class") element.className = (element.className ? element.className + " " : "") + value;
-      else if (key === "dataset") Object.assign(element.dataset, value);
-      else if (key.startsWith("on") && typeof value === "function") element.addEventListener(key.slice(2), value);
-      else if (key in element && typeof value !== "string") element[key] = value;
-      else element.setAttribute(key, value === true ? "" : String(value));
-    });
-  }
+  if (attrs) Object.keys(attrs).forEach(function (key) { applyAttribute(element, key, attrs[key]); });
   append(element, children);
   return element;
 }
 
+function applyAttribute(element, key, value) {
+  if (value === undefined || value === null || value === false) return;
+  if (key === "class") element.className = (element.className ? element.className + " " : "") + value;
+  else if (key === "dataset") Object.assign(element.dataset, value);
+  else if (key.startsWith("on") && typeof value === "function") element.addEventListener(key.slice(2), value);
+  else if (key in element && typeof value !== "string") element[key] = value;
+  else element.setAttribute(key, value === true ? "" : String(value));
+}
+
 function append(element, children) {
   children.forEach(function (child) {
     if (child === undefined || child === null || child === false) return;
@@ -63,4 +62,17 @@ export function icon(name, className) {
 export function clear(element) {
   element.replaceChildren();
 }
+
+// Mark the selected members of a group (pressed chips, checked radios,
+// selected tabs) with one ARIA state, e.g. markSelected(buttons, "aria-pressed", isCurrent).
+export function markSelected(elements, attribute, isSelected) {
+  Array.prototype.forEach.call(elements, function (element) {
+    element.setAttribute(attribute, String(!!isSelected(element)));
+  });
+}
+
+// True while the user is typing into a control; shortcuts and polling yield.
+export function isEditing(element) {
+  return !!element && (["INPUT", "SELECT", "TEXTAREA"].includes(element.tagName) || element.isContentEditable);
+}
 `;

package/dist/web/assets/client/{format.js → lib/format.js}

@@ -33,6 +33,13 @@ export function formatBytes(value) {
   return (value / 1024 / 1024).toFixed(1) + " MB";
 }
 
+// Fill "{name}" placeholders of a translated template; unknown names stay.
+export function fill(template, values) {
+  return String(template).replace(/\{(\w+)\}/g, function (match, key) {
+    return Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : match;
+  });
+}
+
 export function byNewest(left, right) {
   return Date.parse(right.updatedAt || right.createdAt) - Date.parse(left.updatedAt || left.createdAt);
 }

package/dist/web/assets/client/lib/i18n.js

@@ -0,0 +1,54 @@
+import { EN } from "../i18n/en.js";
+import { ZH_CN } from "../i18n/zh-CN.js";
+export const I18N_SCRIPT = String.raw `
+// Translation runtime. Static shell markup opts in with data-i18n (text) and
+// data-i18n-placeholder / -aria-label / -title (attributes). A missing zh-CN
+// key falls back to en, then to the caller's fallback, then to the key.
+import { readPreference, writePreference } from "/assets/js/lib/prefs.js";
+
+const messages = ${JSON.stringify({ en: EN, "zh-CN": ZH_CN })};
+export const SUPPORTED_LOCALES = Object.freeze(Object.keys(messages));
+const TRANSLATED_ATTRIBUTES = ["placeholder", "aria-label", "title"];
+
+function preferredLocale() {
+  const saved = readPreference("yui.locale", null);
+  if (SUPPORTED_LOCALES.includes(saved)) return saved;
+  const languages = navigator.languages || [navigator.language];
+  return languages.some(function (language) { return String(language).toLowerCase().startsWith("zh"); }) ? "zh-CN" : "en";
+}
+
+export function createI18n(select) {
+  let locale = preferredLocale();
+  const subscribers = new Set();
+  function t(key, fallback) {
+    const value = messages[locale][key] || messages.en[key];
+    return value !== undefined ? value : fallback !== undefined ? fallback : key;
+  }
+  function apply() {
+    document.documentElement.lang = locale;
+    document.title = t("app.title");
+    document.querySelectorAll("[data-i18n]").forEach(function (element) { element.textContent = t(element.dataset.i18n); });
+    TRANSLATED_ATTRIBUTES.forEach(function (attribute) {
+      document.querySelectorAll("[data-i18n-" + attribute + "]").forEach(function (element) {
+        element.setAttribute(attribute, t(element.getAttribute("data-i18n-" + attribute)));
+      });
+    });
+    if (select) select.value = locale;
+  }
+  function setLocale(next) {
+    if (!SUPPORTED_LOCALES.includes(next) || next === locale) return;
+    locale = next;
+    writePreference("yui.locale", locale);
+    apply();
+    subscribers.forEach(function (subscriber) { subscriber(locale); });
+  }
+  if (select) select.addEventListener("change", function () { setLocale(select.value); });
+  apply();
+  return {
+    t: t,
+    getLocale: function () { return locale; },
+    setLocale: setLocale,
+    subscribe: function (subscriber) { subscribers.add(subscriber); }
+  };
+}
+`;

package/dist/web/assets/client/lib/markdown.js

@@ -0,0 +1,167 @@
+export const MARKDOWN_SCRIPT = String.raw `
+// Parse raw text and escape leaves once. Generated markup is never re-parsed.
+// Images stay inert unless a trusted caller supplies a placeholder factory.
+export function escapeHtml(text) {
+  return String(text).replace(/&/g, "&amp;").replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+export function resolveMarkdownImage(sourcePath, target) {
+  let value;
+  try { value = decodeURIComponent(target); } catch { throw new Error("Invalid image path encoding."); }
+  if (!value || /^[\/\\]/.test(value) || /[:\\?#\x00-\x1f]/.test(value)) {
+    throw new Error("Only relative images in this fixed artifact version are supported.");
+  }
+  const parts = sourcePath.split("/").slice(0, -1);
+  value.split("/").forEach(function (part) {
+    if (part === ".") return;
+    if (part === "..") {
+      if (!parts.length) throw new Error("Image path escapes the artifact repository.");
+      parts.pop();
+    } else {
+      if (!part || part.trim() !== part || [".git", "__proto__", "prototype", "constructor"].includes(part.toLowerCase())
+        || /[*[\]]/.test(part)) throw new Error("Invalid artifact image path.");
+      parts.push(part);
+    }
+  });
+  if (!parts.length || parts.join("/").length > 512) throw new Error("Invalid artifact image path.");
+  return parts.join("/");
+}
+
+function safeLink(value) {
+  return /^(https?:\/\/|mailto:)/i.test(value) && !/[\x00-\x20]/.test(value);
+}
+
+function inline(text, options, depth) {
+  if (depth > 6) return escapeHtml(text);
+  const token = /(\x60{1,32})([^\n]*?)\1|(!?)\[([^[\]\n]*)\]\((<[^<>\n]+>|[^\s\n()[\]]+)(?:\s+"[^"\n]*")?\)|(!?)\[([^[\]\n]+)\]\[([^[\]\n]*)\]|\*\*([^*\n]+)\*\*|__([^_\n]+)__|~~([^~\n]+)~~|\*([^*\n]+)\*|_([^_\n]+)_|<((?:https?:\/\/|mailto:)[^<>\n]+)>|(https?:\/\/[^\s<>]+)|\\([\\\x60*_[\]{}()#+.!|>~-])/g;
+  let result = "", start = 0, match;
+  while ((match = token.exec(text))) {
+    result += escapeHtml(text.slice(start, match.index));
+    start = token.lastIndex;
+    if (match[1]) { result += "<code>" + escapeHtml(match[2]) + "</code>"; continue; }
+    if (match[3] !== undefined || match[6] !== undefined) {
+      const isReference = match[6] !== undefined;
+      const label = isReference ? match[7] : match[4];
+      const destination = isReference ? options.references.get((match[8] || label).toLowerCase())
+        : match[5].replace(/^<|>$/g, "");
+      const image = isReference ? match[6] : match[3];
+      if (!destination) result += escapeHtml(match[0]);
+      else if (image) result += options.image ? options.image(label, destination)
+        : '<span class="md-image-placeholder">' + escapeHtml(label + " [" + destination + "]") + "</span>";
+      else if (safeLink(destination)) result += '<a href="' + escapeHtml(destination)
+        + '" target="_blank" rel="noopener noreferrer">' + inline(label, options, depth + 1) + "</a>";
+      else result += escapeHtml(label + " (" + destination + ")");
+      continue;
+    }
+    const emphasis = match[9] || match[10] || match[11] || match[12] || match[13];
+    if (emphasis) {
+      const tag = match[9] || match[10] ? "strong" : match[11] ? "del" : "em";
+      result += "<" + tag + ">" + inline(emphasis, options, depth + 1) + "</" + tag + ">";
+    } else if (match[14] || match[15]) {
+      const url = match[14] || match[15];
+      result += '<a href="' + escapeHtml(url) + '" target="_blank" rel="noopener noreferrer">' + escapeHtml(url) + "</a>";
+    } else result += escapeHtml(match[16]);
+  }
+  return result + escapeHtml(text.slice(start));
+}
+
+const fence = /^ {0,3}(\x60{3,}|~{3,})(.*)$/;
+const item = /^( *)([-+*•]|\d+[.)])\s+(.*)$/;
+const rule = /^ {0,3}(?:(?:\*\s*){3,}|(?:-\s*){3,}|(?:_\s*){3,})$/;
+function cells(line) {
+  return line.trim().replace(/^\|/, "").replace(/\|$/, "").split(/(?<!\\)\|/).map(function (cell) { return cell.trim(); });
+}
+function tableDivider(line) {
+  return line.includes("|") && cells(line).every(function (cell) { return /^:?-{3,}:?$/.test(cell); });
+}
+
+export function renderMarkdown(text, supplied) {
+  const options = { ...supplied, references: new Map() };
+  const lines = String(text).replace(/\x00/g, "").replace(/\r\n?/g, "\n").split("\n");
+  let code = null;
+  lines.forEach(function (line, index) {
+    const mark = line.match(fence);
+    if (mark) {
+      if (!code) code = mark[1];
+      else if (mark[1][0] === code[0] && mark[1].length >= code.length && !mark[2].trim()) code = null;
+    }
+    if (code) return;
+    const ref = line.match(/^ {0,3}\[([^\]]+)\]:\s*(<[^>]+>|\S+)(?:\s+.*)?$/);
+    if (ref) { options.references.set(ref[1].toLowerCase(), ref[2].replace(/^<|>$/g, "")); lines[index] = ""; }
+  });
+  return blocks(lines, options, 0);
+}
+
+function blocks(lines, options, depth) {
+  if (depth > 8) return "<pre>" + escapeHtml(lines.join("\n")) + "</pre>";
+  const html = [];
+  for (let index = 0; index < lines.length;) {
+    const line = lines[index];
+    if (!line.trim()) { index++; continue; }
+    const mark = line.match(fence);
+    if (mark) {
+      const code = []; index++;
+      while (index < lines.length) {
+        const end = lines[index].match(fence);
+        if (end && end[1][0] === mark[1][0] && end[1].length >= mark[1].length && !end[2].trim()) { index++; break; }
+        code.push(lines[index++]);
+      }
+      html.push("<pre><code>" + escapeHtml(code.join("\n")) + "</code></pre>"); continue;
+    }
+    const heading = line.match(/^ {0,3}(#{1,6})\s+(.*)$/);
+    if (heading) {
+      const level = Math.min(heading[1].length + 3, 6);
+      html.push("<h" + level + ">" + inline(heading[2].replace(/\s+#+\s*$/, ""), options, 0) + "</h" + level + ">");
+      index++; continue;
+    }
+    if (rule.test(line)) { html.push("<hr>"); index++; continue; }
+    if (/^ {0,3}>/.test(line)) {
+      const quote = [];
+      while (index < lines.length && /^ {0,3}>/.test(lines[index])) quote.push(lines[index++].replace(/^ {0,3}> ?/, ""));
+      html.push("<blockquote>" + blocks(quote, options, depth + 1) + "</blockquote>"); continue;
+    }
+    if (index + 1 < lines.length && line.includes("|") && tableDivider(lines[index + 1])) {
+      const headers = cells(line);
+      if (headers.length <= 32) {
+        html.push('<div class="md-table" tabindex="0"><table><thead><tr>' + headers.map(function (value) {
+          return "<th>" + inline(value, options, 0) + "</th>";
+        }).join("") + "</tr></thead><tbody>");
+        index += 2;
+        while (index < lines.length && lines[index].includes("|") && lines[index].trim()) {
+          const row = cells(lines[index++]);
+          html.push("<tr>" + headers.map(function (_, col) { return "<td>" + inline(row[col] || "", options, 0) + "</td>"; }).join("") + "</tr>");
+        }
+        html.push("</tbody></table></div>"); continue;
+      }
+    }
+    const first = line.match(item);
+    if (first) {
+      const ordered = /^\d/.test(first[2]), indent = first[1].length;
+      const tag = ordered ? "ol" : "ul";
+      html.push("<" + tag + (ordered ? ' start="' + Math.min(parseInt(first[2], 10), 1000000) + '"' : "") + ">");
+      while (index < lines.length) {
+        const entry = lines[index].match(item);
+        if (!entry || entry[1].length !== indent || /^\d/.test(entry[2]) !== ordered) break;
+        const body = [entry[3]], contentIndent = entry[0].length - entry[3].length;
+        index++;
+        while (index < lines.length && lines[index].trim() && /^ */.exec(lines[index])[0].length > indent) {
+          const continuation = lines[index++];
+          body.push(continuation.slice(Math.min(contentIndent, /^ */.exec(continuation)[0].length)));
+        }
+        const task = body[0].match(/^\[([ xX])\]\s+(.*)$/);
+        if (task) body[0] = task[2];
+        html.push("<li>" + (task ? '<input type="checkbox" disabled aria-label="' + (task[1] === " " ? "Incomplete" : "Complete") + '"' + (task[1] === " " ? "" : " checked") + ">" : "")
+          + (body.length === 1 ? inline(body[0], options, 0) : blocks(body, options, depth + 1)) + "</li>");
+      }
+      html.push("</" + tag + ">"); continue;
+    }
+    const paragraph = [line]; index++;
+    while (index < lines.length && lines[index].trim() && !fence.test(lines[index]) && !item.test(lines[index])
+      && !/^ {0,3}(?:#{1,6}\s|>)/.test(lines[index]) && !rule.test(lines[index])
+      && !(index + 1 < lines.length && tableDivider(lines[index + 1]))) paragraph.push(lines[index++]);
+    html.push("<p>" + paragraph.map(function (value) { return inline(value, options, 0); }).join("<br>") + "</p>");
+  }
+  return html.join("");
+}
+`;

package/dist/web/assets/client/lib/prefs.js

@@ -0,0 +1,28 @@
+export const PREFS_SCRIPT = String.raw `
+// Browser-local view preferences (theme, locale, layout). Storage may be
+// unavailable (private mode, policy); reads use a fallback and mutations
+// report failure instead of throwing.
+export function readPreference(key, fallback) {
+  try { return localStorage.getItem(key) || fallback; } catch { return fallback; }
+}
+
+export function writePreference(key, value) {
+  try { localStorage.setItem(key, value); return true; } catch { return false; }
+}
+
+export function clearPreference(key) {
+  try { localStorage.removeItem(key); return true; } catch { return false; }
+}
+
+// Shared with session access consumers: no server configuration or live
+// Session is changed by this browser-local preference.
+export function readSessionAccessMode() {
+  const value = readPreference("yui.session.accessMode", "native");
+  return value === "structured" ? "structured" : "native";
+}
+
+export function writeSessionAccessMode(value) {
+  if (value !== "native" && value !== "structured") throw new Error("Invalid session access mode.");
+  return writePreference("yui.session.accessMode", value);
+}
+`;

package/dist/web/assets/client/lib/theme.js

@@ -0,0 +1,68 @@
+import { DEFAULT_DARK_THEME, DEFAULT_LIGHT_THEME, THEME_OPTIONS } from "../../shared/themes.js";
+export const THEME_SCRIPT = String.raw `
+// Theme preference. "system" follows prefers-color-scheme and resolves to the
+// default dark or light theme; the resolved id is stamped on <html> so its
+// token block applies. Options and swatches come from shared/themes.ts.
+import { h, markSelected } from "/assets/js/lib/dom.js";
+import { readPreference, writePreference } from "/assets/js/lib/prefs.js";
+
+const THEMES = Object.freeze(${JSON.stringify(THEME_OPTIONS)});
+const IDS = THEMES.map(function (theme) { return theme.id; });
+const DEFAULT_DARK = ${JSON.stringify(DEFAULT_DARK_THEME.id)};
+const DEFAULT_LIGHT = ${JSON.stringify(DEFAULT_LIGHT_THEME.id)};
+
+function storedPreference() {
+  const saved = readPreference("yui.theme", "system");
+  return IDS.includes(saved) ? saved : "system";
+}
+
+function themeOption(theme, t, onPick) {
+  const swatch = h("span.theme-swatch", { "aria-hidden": "true" }, theme.swatch.map(function (color, index) {
+    const part = h("i");
+    part.style.background = color;
+    part.dataset.part = String(index);
+    return part;
+  }));
+  return h("button.theme-option", {
+    type: "button",
+    dataset: { themeOption: theme.id },
+    onclick: function () { onPick(theme.id); }
+  }, swatch, h("span", null, t("theme." + theme.id)));
+}
+
+export function createThemeController(container, t) {
+  const media = window.matchMedia("(prefers-color-scheme: light)");
+  let preference = storedPreference();
+  const listeners = new Set();
+
+  function resolved() {
+    return preference === "system" ? (media.matches ? DEFAULT_LIGHT : DEFAULT_DARK) : preference;
+  }
+  function apply() {
+    document.documentElement.dataset.theme = resolved();
+    if (container) markSelected(container.querySelectorAll("[data-theme-option]"), "aria-pressed", function (button) {
+      return button.dataset.themeOption === preference;
+    });
+    listeners.forEach(function (listener) { listener(resolved()); });
+  }
+  function render() {
+    if (!container) return;
+    container.replaceChildren.apply(container, THEMES.map(function (theme) { return themeOption(theme, t, set); }));
+    apply();
+  }
+  function set(next) {
+    if (!IDS.includes(next)) return;
+    preference = next;
+    writePreference("yui.theme", next);
+    apply();
+  }
+  media.addEventListener("change", function () { if (preference === "system") apply(); });
+  render();
+  return {
+    resolved: resolved,
+    render: render,
+    set: set,
+    subscribe: function (listener) { listeners.add(listener); }
+  };
+}
+`;

package/dist/web/assets/client/ui/containers.js

@@ -0,0 +1,101 @@
+export const CONTAINERS_SCRIPT = String.raw `
+// Panels of the single reading column. A card has a heading (icon tile,
+// title, count and hint) with optional actions, then its body; a list card's
+// body is a .row-stack whose rows are divided by hairlines, not nested boxes.
+import { h, icon, markSelected } from "/assets/js/lib/dom.js";
+import { fill } from "/assets/js/lib/format.js";
+import { button, jsonBlock } from "/assets/js/ui/primitives.js";
+
+export function card(options) {
+  const opts = options || {};
+  const element = h("section.card" + (opts.className ? "." + opts.className.split(" ").join(".") : ""));
+  if (opts.id) element.id = opts.id;
+  if (opts.title || opts.actions) element.append(cardHead(opts));
+  const body = h("div.card-body");
+  element.append(body);
+  element.body = body;
+  return element;
+}
+
+function cardHead(opts) {
+  const heading = h("div.card-heading", null,
+    h("h3.card-title", null, opts.icon ? h("span.card-icon", null, icon(opts.icon)) : null, h("span", null, opts.title),
+      opts.count !== undefined && opts.count !== null ? h("span.count", null, String(opts.count)) : null),
+    opts.hint ? h("p.card-hint", null, opts.hint) : null);
+  return h("header.card-head", null, heading, opts.actions ? h("div.card-actions", null, opts.actions) : null);
+}
+
+export function listCard(options) {
+  const element = card({ ...options, className: "list-card" + (options.className ? " " + options.className : "") });
+  element.list = h("div.row-stack");
+  element.body.append(element.list);
+  return element;
+}
+
+// Update a card heading count after a later read; null removes it.
+export function setCardCount(element, value) {
+  const title = element.querySelector(".card-title");
+  let count = title && title.querySelector(".count");
+  if (value === undefined || value === null) { if (count) count.remove(); return; }
+  if (!title) return;
+  if (!count) { count = h("span.count"); title.append(count); }
+  count.textContent = String(value);
+}
+
+export function disclosure(title, viewKey, options) {
+  const opts = options || {};
+  const element = h("details.disclosure" + (opts.className ? "." + opts.className : ""));
+  if (viewKey) element.dataset.viewKey = viewKey;
+  const summary = h("summary", null, icon("chevron", "disclosure-chevron"), h("span.disclosure-title", null, title));
+  if (opts.meta) summary.append(h("span.disclosure-meta", null, opts.meta));
+  element.append(summary);
+  const body = h("div.disclosure-body");
+  element.append(body);
+  element.body = body;
+  return element;
+}
+
+// A top-level section that stays closed until asked (control, diagnostics…).
+export function cardDisclosure(id, title, viewKey, meta) {
+  const element = disclosure(title, viewKey, { className: "card-disclosure", meta: meta });
+  element.id = id;
+  return element;
+}
+
+// The exact record behind a rich rendering, one click away.
+export function rawDisclosure(t, value) {
+  const raw = disclosure(t("record.raw"), null);
+  raw.body.append(jsonBlock(value));
+  return raw;
+}
+
+// Local filter chips; selecting one redraws the list in place.
+export function filterChips(ariaLabel, options, selected, onSelect) {
+  const row = h("div.chip-tabs", { role: "group", "aria-label": ariaLabel });
+  options.forEach(function (option) {
+    row.append(h("button.chip-tab", {
+      type: "button", "aria-pressed": String(option.value === selected), dataset: { filter: option.value },
+      onclick: function () {
+        markSelected(row.querySelectorAll(".chip-tab"), "aria-pressed", function (b) { return b.dataset.filter === option.value; });
+        onSelect(option.value);
+      }
+    }, option.label, option.count === undefined || option.count === null ? null : h("span.count", null, String(option.count))));
+  });
+  return row;
+}
+
+// Paged list footers: how much is loaded, and a button for the next page
+// that disables itself until the caller redraws.
+export function loadedNote(t, shown, total) {
+  return h("span.faint.small", null, fill(t("history.loaded"), { shown: shown, total: total }));
+}
+
+export function moreButton(t, onMore) {
+  const more = button(t("history.more"), { icon: "chevron", variant: "ghost" });
+  more.addEventListener("click", function () {
+    more.disabled = true;
+    onMore();
+  });
+  return more;
+}
+`;

package/dist/web/assets/client/ui/controls.js

@@ -0,0 +1,51 @@
+export const CONTROLS_SCRIPT = String.raw `
+// Selection controls: the segmented radio group and the scrollable tab row.
+import { h, markSelected } from "/assets/js/lib/dom.js";
+
+export function segmented(name, options, value, onChange) {
+  const group = h("div.seg.seg-sm", { role: "radiogroup" });
+  options.forEach(function (option) {
+    const item = h("button.seg-btn", {
+      type: "button", role: "radio", title: option.title || null,
+      "aria-checked": String(option.value === value),
+      dataset: { value: option.value },
+      onclick: function () {
+        markSelected(group.querySelectorAll(".seg-btn"), "aria-checked", function (other) { return other === item; });
+        onChange(option.value);
+      }
+    }, option.label);
+    group.append(item);
+  });
+  group.dataset.name = name;
+  return group;
+}
+
+// A tab row that keeps its horizontal scroll position across updates. When
+// it is too narrow for every tab, the clipped edge fades out (data-fade), the
+// wheel scrolls it sideways and revealTab() brings a tab into view.
+export function scrollableTabRow(row) {
+  row.addEventListener("scroll", function () { syncTabsOverflow(row); }, { passive: true });
+  row.addEventListener("wheel", function (event) {
+    if (Math.abs(event.deltaY) <= Math.abs(event.deltaX) || row.scrollWidth <= row.clientWidth) return;
+    event.preventDefault();
+    row.scrollLeft += event.deltaY;
+  }, { passive: false });
+  new ResizeObserver(function () { syncTabsOverflow(row); }).observe(row);
+  return row;
+}
+
+export function syncTabsOverflow(row) {
+  const max = row.scrollWidth - row.clientWidth;
+  const before = row.scrollLeft > 1;
+  const after = row.scrollLeft < max - 1;
+  row.dataset.fade = before && after ? "both" : after ? "end" : before ? "start" : "none";
+}
+
+export function revealTab(row, tab) {
+  const margin = 28;
+  const left = tab.offsetLeft - margin;
+  const right = tab.offsetLeft + tab.offsetWidth + margin;
+  if (left < row.scrollLeft) row.scrollLeft = Math.max(0, left);
+  else if (right > row.scrollLeft + row.clientWidth) row.scrollLeft = right - row.clientWidth;
+}
+`;

package/dist/web/assets/client/ui/forms.js

@@ -0,0 +1,48 @@
+export const FORMS_SCRIPT = String.raw `
+// Write plumbing shared by every form. A submission carries a fresh
+// requestId, marks its form unsent until a receipt settles, and reports an
+// unknown outcome as unknown: nothing here ever replays a write.
+import { h } from "/assets/js/lib/dom.js";
+
+export function field(text, control, hint) {
+  return h("label.field", null, h("span", null, text), control, hint ? h("small.faint", null, hint) : null);
+}
+
+export function receiptLine(text, state) {
+  const line = h("p.receipt", { role: "status" }, text);
+  if (state) line.dataset.state = state;
+  return line;
+}
+
+export function setReceipt(line, text, state) {
+  line.textContent = text;
+  line.dataset.state = state || "";
+}
+
+// options: control (disabled while in flight), receipt, t, send(requestId),
+// saved(result) → true to keep the control blocked, rejectedKey (prefix of
+// a not-submitted error), unknownKey, and the optional form and afterWrite.
+// A rejected submission re-enables the control; an unknown one keeps it
+// disabled so the same write cannot be sent twice.
+export async function submitWrite(options) {
+  const t = options.t;
+  options.control.disabled = true;
+  if (options.form) options.form.dataset.unsent = "true";
+  const requestId = crypto.randomUUID();
+  setReceipt(options.receipt, t("receipt.waiting") + " · " + requestId, "pending");
+  try {
+    const result = await options.send(requestId);
+    const blocked = !!options.saved(result);
+    if (options.form) options.form.dataset.unsent = "false";
+    options.control.disabled = blocked;
+    if (options.afterWrite) options.afterWrite();
+  } catch (error) {
+    if (error.disposition === "not-submitted") {
+      setReceipt(options.receipt, (options.rejectedKey ? t(options.rejectedKey) + " " : "") + error.message, "bad");
+      options.control.disabled = false;
+      return;
+    }
+    setReceipt(options.receipt, t(options.unknownKey) + " · " + requestId + " · " + error.message, "warn");
+  }
+}
+`;