cortico 0.1.0

package/src/web/client/theme/studio.ts

@@ -0,0 +1,366 @@
+/** 管理当前颜色方案、明暗模式、自定义方案与未保存预览。首屏由 applyStoredTheme 同步应用；订阅者接收变化，图表据此重绘。 */
+
+import { toDisposable, type Disposable } from '../../shared/client-panel.ts';
+import {
+  THEME_MODES,
+  builtinSchemes,
+  clonePalette,
+  cloneScheme,
+  defaultStoredTheme,
+  fallbackPalette,
+  normalizePalette,
+  resolveDefaultSchemeId,
+  schemeSwatches,
+  schemeText,
+  type InjectedTheme,
+  type StoredTheme,
+  type ThemeAppearance,
+  type ThemeMode,
+  type ThemePalette,
+  type ThemeScheme,
+} from './registry.ts';
+import { applyPalette } from './palette.ts';
+import { readInjectedTheme, readLegacyLocalTheme, saveDeploymentTheme } from './storage.ts';
+import { S } from './strings.ts';
+
+/** 方案的元信息（不含调色板本身）。 */
+export interface ThemeSchemeInfo {
+  id: string;
+  name: string;
+  note: string;
+  builtin: boolean;
+  custom: boolean;
+}
+
+/** 方案卡：元信息 + 一条四格色带。 */
+export interface ThemeSchemeCard extends ThemeSchemeInfo {
+  swatches: string[];
+}
+
+export interface ThemeSnapshot {
+  selectedId: string;
+  /** 用户选的挡位（可能是 `system`） */
+  mode: ThemeMode;
+  /** 解析之后真正生效的明暗 */
+  appearance: ThemeAppearance;
+  scheme: ThemeSchemeInfo;
+  schemes: ThemeSchemeCard[];
+  /** 当前生效的调色板；预览期间是那份草稿。 */
+  palette: ThemePalette;
+  /** 最近一次回写部署的失败原因；成功后为 null。当前选择在本页仍然生效。 */
+  saveError: string | null;
+}
+
+export interface ThemeChange {
+  readonly snapshot: ThemeSnapshot;
+  /** 是否为未保存的预览变化；订阅者可据此决定是否重绘。 */
+  readonly preview: boolean;
+}
+
+export type ThemeChangeListener = (change: ThemeChange) => void;
+
+/** `matchMedia('(prefers-color-scheme: dark)')` 的最小面。 */
+export interface MediaQueryLike {
+  readonly matches: boolean;
+  addEventListener(type: 'change', listener: () => void): void;
+  removeEventListener(type: 'change', listener: () => void): void;
+}
+
+export interface ThemeStudioDeps {
+  doc: Document;
+  /** 不给则读服务端注入的那段 JSON。 */
+  injected?: InjectedTheme;
+  /** 部署没有记录时可迁移的本机旧记录；不给则读 localStorage。 */
+  legacy?: StoredTheme | null;
+  /** 回写部署的主题记录；不给则 POST `/api/theme`。 */
+  save?(state: StoredTheme): Promise<void>;
+  /** 不给则取 `doc.defaultView.matchMedia(...)`；显式给 `null` = 系统挡位当浅色。 */
+  media?: MediaQueryLike | null;
+  /** 订阅方回调里抛的错落这儿。默认吞掉——一张图重画失败不该拖垮换肤本身。 */
+  onError?(err: unknown): void;
+}
+
+/** 系统深色偏好。拿不到（老浏览器、假文档）就是 `null`，一律当浅色。 */
+function systemDarkQuery(doc: Document): MediaQueryLike | null {
+  try {
+    return doc.defaultView?.matchMedia('(prefers-color-scheme: dark)') ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export class ThemeStudio {
+  private readonly doc: Document;
+  private readonly save: (state: StoredTheme) => Promise<void>;
+  private readonly media: MediaQueryLike | null;
+  private readonly onError: (err: unknown) => void;
+  /** 记录里没有可用选择时选哪个方案；删掉自定义方案后也回到它。 */
+  private readonly defaultSchemeId: string;
+  private readonly listeners = new Set<ThemeChangeListener>();
+  private state: StoredTheme;
+  private previewPalette: ThemePalette | null = null;
+  private saveError: string | null = null;
+  private closed = false;
+
+  /** 系统挡位下跟着系统走。方法引用存下来，`dispose()` 才摘得掉。 */
+  private readonly onMediaChange = (): void => {
+    if (this.state.mode === 'system') this.apply();
+  };
+
+  constructor(deps: ThemeStudioDeps) {
+    this.doc = deps.doc;
+    this.save = deps.save ?? saveDeploymentTheme;
+    this.media = deps.media === undefined ? systemDarkQuery(deps.doc) : deps.media;
+    this.onError = deps.onError ?? ((): void => {});
+    const injected = deps.injected ?? readInjectedTheme(deps.doc);
+    this.defaultSchemeId = resolveDefaultSchemeId(injected.defaultScheme);
+    if (injected.theme) {
+      this.state = injected.theme;
+    } else {
+      // 部署还没有记录:把这台机器上的旧记录交上去,此后它归部署。
+      const legacy = deps.legacy === undefined ? readLegacyLocalTheme(deps.doc) : deps.legacy;
+      this.state = legacy ?? { ...defaultStoredTheme(), selectedId: this.defaultSchemeId };
+      if (legacy) this.persist();
+    }
+    this.media?.addEventListener('change', this.onMediaChange);
+  }
+
+  // ── 读 ──────────────────────────────────────────────────────────────
+
+  /** 内置在前、自定义在后。每次现算，调用方拿到的是副本。 */
+  schemes(): ThemeScheme[] {
+    return [...builtinSchemes(), ...this.state.custom.map((s) => ({ ...cloneScheme(s), custom: true }))];
+  }
+
+  /** 当前方案。记录指向的 id 不存在（方案在别处被删了）就退回部署默认方案。 */
+  currentScheme(): ThemeScheme {
+    const all = this.schemes();
+    return all.find((s) => s.id === this.state.selectedId)
+      ?? all.find((s) => s.id === this.defaultSchemeId)
+      ?? all[0];
+  }
+
+  get appearance(): ThemeAppearance {
+    if (this.state.mode !== 'system') return this.state.mode;
+    return this.media?.matches ? 'dark' : 'light';
+  }
+
+  get mode(): ThemeMode {
+    return this.state.mode;
+  }
+
+  snapshot(): ThemeSnapshot {
+    const scheme = this.currentScheme();
+    const appearance = this.appearance;
+    return {
+      selectedId: scheme.id,
+      mode: this.state.mode,
+      appearance,
+      scheme: info(scheme),
+      schemes: this.schemes().map((item) => ({ ...info(item), swatches: schemeSwatches(item, appearance) })),
+      palette: clonePalette(this.previewPalette ?? scheme.palettes[appearance]),
+      saveError: this.saveError,
+    };
+  }
+
+  // ── 写 ──────────────────────────────────────────────────────────────
+
+  /** 应用保存的选择；首屏传 notify=false，不发变化通知。 */
+  apply(notify = true): void {
+    this.previewPalette = null;
+    const scheme = this.currentScheme();
+    // 选中的方案没了（记录里指向一个已删的自定义方案）→ 把纠正结果落回部署
+    if (scheme.id !== this.state.selectedId) {
+      this.state.selectedId = scheme.id;
+      this.persist();
+    }
+    const appearance = this.appearance;
+    applyPalette(
+      this.doc,
+      normalizePalette(scheme.palettes[appearance], fallbackPalette(appearance)),
+      { appearance, schemeId: scheme.id },
+    );
+    if (notify) this.emit(false);
+  }
+
+  select(id: string): boolean {
+    if (!this.schemes().some((s) => s.id === id)) return false;
+    this.state.selectedId = id;
+    this.persist();
+    this.apply();
+    return true;
+  }
+
+  setMode(mode: ThemeMode): boolean {
+    if (!THEME_MODES.includes(mode)) return false;
+    this.state.mode = mode;
+    this.persist();
+    this.apply();
+    return true;
+  }
+
+  /** 试色：刷到文档但**不回写部署**。离开这一页或调 `resetPreview()` 就没了。 */
+  preview(palette: ThemePalette): void {
+    const scheme = this.currentScheme();
+    const appearance = this.appearance;
+    this.previewPalette = normalizePalette(palette, scheme.palettes[appearance]);
+    applyPalette(this.doc, this.previewPalette, { appearance, schemeId: scheme.id });
+    this.emit(true);
+  }
+
+  resetPreview(): void {
+    this.apply();
+  }
+
+  /**
+   * 另存为新的自定义方案并切过去。
+   *
+   * **只覆盖当前明暗变体**，另一半从源方案原样拷过来：用户在浅色下调完色，黑夜
+   * 变体不该跟着变成一份浅色配色的暗抄本。
+   */
+  saveAs(name: string | null | undefined, palette: ThemePalette): string {
+    const source = this.currentScheme();
+    const appearance = this.appearance;
+    const copy: ThemeScheme = {
+      id: `custom-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+      name: String(name ?? '').trim().slice(0, 40) || S.copyOf(source.name),
+      note: S.customNote,
+      palettes: cloneScheme(source).palettes,
+      custom: true,
+    };
+    copy.palettes[appearance] = normalizePalette(palette, source.palettes[appearance]);
+    this.state.custom.push(copy);
+    this.state.selectedId = copy.id;
+    this.persist();
+    this.apply();
+    return copy.id;
+  }
+
+  /** 覆盖当前自定义方案。选中的是内置方案时返回 `false`（内置不可写）。 */
+  saveCurrent(name: string | null | undefined, palette: ThemePalette): boolean {
+    const scheme = this.state.custom.find((s) => s.id === this.state.selectedId);
+    if (!scheme) return false;
+    const appearance = this.appearance;
+    scheme.name = String(name ?? '').trim().slice(0, 40) || scheme.name;
+    scheme.palettes[appearance] = normalizePalette(palette, scheme.palettes[appearance]);
+    this.persist();
+    this.apply();
+    return true;
+  }
+
+  /** 删掉当前自定义方案并切回默认方案。选中内置方案时返回 `false`。 */
+  removeCurrent(): boolean {
+    const before = this.state.custom.length;
+    this.state.custom = this.state.custom.filter((s) => s.id !== this.state.selectedId);
+    if (this.state.custom.length === before) return false;
+    this.state.selectedId = this.defaultSchemeId;
+    this.persist();
+    this.apply();
+    return true;
+  }
+
+  // ── 订阅 ────────────────────────────────────────────────────────────
+
+  /**
+   * 订阅主题变化。返回的 `Disposable` 一 `dispose()` 就退订——页面把它交给自己的
+   * `lifecycle` 即可，不必记得在卸载时手动摘。
+   *
+   * 重复登记同一个函数只算一次（`Set` 语义）；回调里再登记/退订不影响本轮派发。
+   */
+  onChange(listener: ThemeChangeListener): Disposable {
+    this.listeners.add(listener);
+    return toDisposable(() => {
+      this.listeners.delete(listener);
+    });
+  }
+
+  /** 摘掉系统深色监听并清空订阅。进程级实例通常活到页面关闭，测试与热重载用。 */
+  dispose(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.media?.removeEventListener('change', this.onMediaChange);
+    this.listeners.clear();
+  }
+
+  /** 回写部署。失败记在快照里,由外观页呈现;当前选择在本页仍然生效。 */
+  private persist(): void {
+    const sending = JSON.parse(JSON.stringify(this.state)) as StoredTheme;
+    void this.save(sending).then(
+      () => {
+        if (this.saveError === null) return;
+        this.saveError = null;
+        this.emit(false);
+      },
+      (err: unknown) => {
+        this.saveError = err instanceof Error ? err.message : String(err);
+        this.emit(false);
+      },
+    );
+  }
+
+  /** 逐个通知订阅者；单个回调失败不阻止其他回调。 */
+  private emit(preview: boolean): void {
+    if (this.listeners.size === 0) return;
+    const change: ThemeChange = { snapshot: this.snapshot(), preview };
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(change);
+      } catch (err) {
+        this.onError(err);
+      }
+    }
+  }
+}
+
+function info(scheme: ThemeScheme): ThemeSchemeInfo {
+  const text = schemeText(scheme);
+  return {
+    id: scheme.id,
+    name: text.name,
+    note: text.note,
+    builtin: !!scheme.builtin,
+    custom: !!scheme.custom,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 进程级实例
+// ---------------------------------------------------------------------------
+
+let shared: ThemeStudio | null = null;
+
+/**
+ * 取（必要时新建）那个唯一的实例。
+ *
+ * `deps` 只在**第一次**（真正新建的那次）生效；之后再传会被忽略，因为半路换回写
+ * 目标或换文档只会让两份状态对不上。测试要换一套 deps，先 `disposeThemeStudio()`。
+ */
+export function getThemeStudio(deps?: Partial<ThemeStudioDeps>): ThemeStudio {
+  if (shared) return shared;
+  const doc = deps?.doc ?? (typeof document === 'undefined' ? null : document);
+  if (!doc) throw new Error('主题需要一个 Document');
+  shared = new ThemeStudio({ ...deps, doc });
+  return shared;
+}
+
+/**
+ * **首屏第一件事**：读服务端注入的部署主题记录、把颜色刷到 `documentElement`。
+ *
+ * 同步执行、不等任何路由，所以内核入口可以在第一行直接调它。部署还没有记录且这台
+ * 机器存过旧记录时，构造函数会把旧记录回写一次。
+ * 返回当前快照（想据此做点别的判断时用），不需要就丢掉。
+ */
+export function applyStoredTheme(
+  doc?: Document,
+  deps?: Omit<Partial<ThemeStudioDeps>, 'doc'>,
+): ThemeSnapshot {
+  const studio = getThemeStudio(doc ? { ...deps, doc } : deps);
+  studio.apply(false);
+  return studio.snapshot();
+}
+
+/** 丢掉进程级实例（测试与热重载）。生产代码里没有它的用处。 */
+export function disposeThemeStudio(): void {
+  shared?.dispose();
+  shared = null;
+}

package/src/web/client/ui/actions.ts

@@ -0,0 +1,109 @@
+/** 操作期间禁用控件，以及复制文本并报告结果。 */
+
+import type {
+  ConsoleCopyOptions,
+  ConsoleDisablable,
+  Disposable,
+} from '../../shared/client-panel.ts';
+import { toDisposable } from '../../shared/client-panel.ts';
+import { h } from './dom.ts';
+import { button } from './sheet.ts';
+import type { OverlayEnv } from './overlay.ts';
+import { drawer } from './overlay.ts';
+import { S } from './strings.ts';
+
+/** 临时禁用控件；dispose 恢复各自原值。重复控件只记录第一次的值。 */
+export function disable(els: readonly ConsoleDisablable[]): Disposable {
+  const saved: { el: { disabled: boolean }; was: boolean }[] = [];
+  const seen = new Set<object>();
+  for (const el of els) {
+    if (!el || seen.has(el)) continue;
+    seen.add(el);
+    saved.push({ el, was: el.disabled });
+    el.disabled = true;
+  }
+  // toDisposable 自带幂等标志,重复 dispose 不会二次写回
+  return toDisposable(() => {
+    for (const s of saved) s.el.disabled = s.was;
+  });
+}
+
+/**
+ * 剪贴板从哪儿取。
+ *
+ * 先问文档自己的 `defaultView`、再退到全局：这个模块不许在顶层引用 `window`
+ * （测试跑在 node 里，未来还可能是离屏文档 / iframe——那时候 `globalThis` 上的
+ * 那个根本不是这份文档的窗口）。
+ */
+function navigatorOf(doc: Document): Navigator | null {
+  return doc.defaultView?.navigator ?? (globalThis as { navigator?: Navigator }).navigator ?? null;
+}
+
+/** Clipboard API 不可用或失败时，使用可聚焦的离屏 textarea 与 execCommand 复制。 */
+function execCopy(env: OverlayEnv, value: string): boolean {
+  const doc = env.doc as Document & { execCommand?: (cmd: string) => boolean };
+  if (typeof doc.execCommand !== 'function') return false;
+  const ta = h(doc, 'textarea');
+  ta.value = value;
+  // 必须真的在 DOM 里、且可聚焦,才选得中;挪到屏外并透明化是为了不闪一下
+  ta.setAttribute('style', 'position:fixed;top:0;left:-9999px;opacity:0');
+  env.host.appendChild(ta);
+  try {
+    ta.focus();
+    ta.select();
+    return doc.execCommand('copy') === true;
+  } catch {
+    return false;
+  } finally {
+    ta.remove();
+  }
+}
+
+/** 两条路依次试。都不通给 false，由调用方去出声。 */
+async function writeClipboard(env: OverlayEnv, value: string): Promise<boolean> {
+  const nav = navigatorOf(env.doc);
+  const clip = nav?.clipboard as Clipboard | undefined;
+  if (typeof clip?.writeText === 'function') {
+    try {
+      await clip.writeText(value);
+      return true;
+    } catch {
+      // 权限被拒 / 文档没聚焦:掉到降级路线,别在这儿就放弃
+    }
+  }
+  return execCopy(env, value);
+}
+
+/** 函数形式的文本在点击时读取；show 使用所属 UI 实例的单条 toast。 */
+export function copyButton(
+  env: OverlayEnv,
+  show: (text: string, tone?: 'ok' | 'bad') => void,
+  text: string | (() => string),
+  opts?: ConsoleCopyOptions,
+): HTMLButtonElement {
+  const o = opts ?? {};
+  const label = o.label ?? S.copy;
+  const run = async (): Promise<void> => {
+    let value: string;
+    try {
+      value = typeof text === 'function' ? text() : text;
+    } catch {
+      // 惰性取值自己炸了(那串值背后的对象已经没了):照样出声,别静默
+      show(S.copyNothing, 'bad');
+      return;
+    }
+    if (await writeClipboard(env, value)) {
+      show(o.okText ?? S.copied, 'ok');
+      return;
+    }
+    // 两种复制方式均失败时展示文本，供手动选取。
+    show(S.copyFailed, 'bad');
+    drawer(env, label, value);
+  };
+
+  return button(env.doc, env.signal, label, {
+    size: o.size ?? 'sm',
+    variant: o.variant,
+    onClick: () => void run(),
+  });
+}

package/src/web/client/ui/data.ts

@@ -0,0 +1,185 @@
+/**
+ * 数据表、键值表与概览读数复用现存 .tablewrap、table.data、table.kvtable、.statgrid 样式。table 返回 clear/addRow 句柄供增量刷新，单元格使用 textContent，不把名称或正文解析为 HTML。
+ */
+
+import type {
+  ConsoleCell,
+  ConsoleKvRow,
+  ConsoleProgress,
+  ConsoleProgressOptions,
+  ConsoleStat,
+  ConsoleTable,
+  ConsoleTableOptions,
+} from '../../shared/client-panel.ts';
+import { h } from './dom.ts';
+import { consoleFormat } from './format.ts';
+
+/** 一格 → `<td>`。 */
+function cell(doc: Document, spec: ConsoleCell): HTMLTableCellElement {
+  const td = h(doc, 'td');
+  if (spec == null) return td;
+  if (typeof spec === 'string' || typeof spec === 'number') {
+    td.textContent = String(spec);
+    return td;
+  }
+  // 节点直接放进去(pill / 按钮 / 链接这类)
+  if (!isCellSpec(spec)) {
+    td.appendChild(spec);
+    return td;
+  }
+  if (spec.cls) td.className = spec.cls;
+  if (spec.el) td.appendChild(spec.el);
+  else if (spec.text != null) td.textContent = String(spec.text);
+  return td;
+}
+
+/**
+ * 分辨"描述对象"与"现成节点"。
+ *
+ * 不用 `instanceof HTMLElement`：这个模块在 node 里被测（没有那个全局），而且未来若
+ * 换到离屏文档/iframe，跨 realm 的 `instanceof` 本来就会假阴性。改按结构判断——
+ * 描述对象是纯字面量，不会有 `nodeType`。
+ */
+function isCellSpec(
+  v: HTMLElement | { text?: string | number | null; el?: HTMLElement; cls?: string },
+): v is { text?: string | number | null; el?: HTMLElement; cls?: string } {
+  return (v as { nodeType?: number }).nodeType === undefined;
+}
+
+/** 数据表。 */
+export function table(doc: Document, opts?: ConsoleTableOptions): ConsoleTable {
+  const head = opts?.head ?? [];
+  const el = h(doc, 'div', 'tablewrap');
+  // 外框限高才会滚,表头的 position:sticky 也才有意义;不给就让它自然铺开
+  if (opts?.maxHeight) el.setAttribute('style', 'max-height:' + opts.maxHeight + ';overflow:auto');
+  const tbl = h(doc, 'table', 'data');
+  if (head.length) {
+    const thead = h(doc, 'thead');
+    const tr = h(doc, 'tr');
+    for (const t of head) tr.appendChild(h(doc, 'th', null, t));
+    thead.appendChild(tr);
+    tbl.appendChild(thead);
+  }
+  const body = h(doc, 'tbody');
+  tbl.appendChild(body);
+  el.appendChild(tbl);
+
+  return {
+    el,
+    body,
+    addRow(cells) {
+      const tr = h(doc, 'tr');
+      for (const c of cells) tr.appendChild(cell(doc, c));
+      body.appendChild(tr);
+      return tr;
+    },
+    clear(empty) {
+      while (body.children.length) body.children[0].remove();
+      if (empty == null) return;
+      const tr = h(doc, 'tr');
+      const td = h(doc, 'td', 'placeholder');
+      td.colSpan = Math.max(1, head.length);
+      td.textContent = empty;
+      tr.appendChild(td);
+      body.appendChild(tr);
+    },
+  };
+}
+
+/** 键值表无表头；tr 直接挂在 table 下。 */
+export function kv(doc: Document, rows: readonly ConsoleKvRow[]): HTMLTableElement {
+  const el = h(doc, 'table', 'kvtable');
+  for (const row of rows) {
+    const tr = h(doc, 'tr');
+    tr.appendChild(h(doc, 'td', null, row.k));
+    const td = h(doc, 'td');
+    const v = row.v;
+    if (v == null) td.textContent = '';
+    else if (typeof v === 'string' || typeof v === 'number') td.textContent = String(v);
+    else td.appendChild(v);
+    tr.appendChild(td);
+    el.appendChild(tr);
+  }
+  return el;
+}
+
+/** 概览读数。`.k` 小标题 + `.v` 大数字（`unit` 落成 `.v` 里的 `<small>`）。 */
+export function stat(doc: Document, item: ConsoleStat): HTMLDivElement {
+  const el = h(doc, 'div', item.accent ? 'stat accent' : 'stat');
+  el.appendChild(h(doc, 'div', 'k', item.k));
+  const v = h(doc, 'div', 'v');
+  if (typeof item.v === 'string' || typeof item.v === 'number') v.textContent = String(item.v);
+  else v.appendChild(item.v);
+  if (item.unit) v.appendChild(h(doc, 'small', null, item.unit));
+  el.appendChild(v);
+  return el;
+}
+
+/** 读数网格。`items` 可以不给（先建空网格，之后自己往里 append）。 */
+export function statgrid(doc: Document, items?: readonly ConsoleStat[]): HTMLDivElement {
+  const el = h(doc, 'div', 'statgrid');
+  for (const it of items ?? []) el.appendChild(stat(doc, it));
+  return el;
+}
+
+/**
+ * 满值归一。0 与非有限数一律当 1——除数是 0 的话读数会印成 `NaN%`，
+ * 而"总量还不知道"恰恰是进度条最常见的初始状态。
+ */
+function normMax(m: number | undefined): number {
+  return typeof m === 'number' && Number.isFinite(m) && m > 0 ? m : 1;
+}
+
+/** 填充比例，夹在 0..1。读数用的是原始 value，只有条的宽度被夹。 */
+function fillRatio(value: number, max: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value / max));
+}
+
+/** 占比条通过 role=progressbar 与 aria-value* 提供无障碍读数。 */
+export function progress(doc: Document, opts?: ConsoleProgressOptions): ConsoleProgress {
+  const o = opts ?? {};
+  const cls =
+    o.tone === 'warn' ? 'progress warnc' : o.tone === 'accent' ? 'progress dreamc' : 'progress';
+  const el = h(doc, 'div', cls);
+  el.setAttribute('role', 'progressbar');
+  const head = h(doc, 'div', 'progresshead');
+  const label = h(doc, 'span', 'progresslabel', o.label ?? '');
+  const num = h(doc, 'span', 'progressnum');
+  head.append(label, num);
+  const track = h(doc, 'div', 'progresstrack');
+  const fill = h(doc, 'div', 'progressfill');
+  track.appendChild(fill);
+  el.append(head, track);
+
+  let max = normMax(o.max);
+  let value = Number.isFinite(o.value) ? (o.value as number) : 0;
+  const fmt = o.format ?? ((v: number, m: number): string => consoleFormat.percent(v / m));
+
+  const paint = (): void => {
+    fill.setAttribute('style', 'width:' + (fillRatio(value, max) * 100).toFixed(1) + '%');
+    num.textContent = fmt(value, max);
+    el.setAttribute('aria-valuemin', '0');
+    el.setAttribute('aria-valuemax', String(max));
+    el.setAttribute('aria-valuenow', String(value));
+  };
+  paint();
+
+  return {
+    el,
+    get value(): number {
+      return value;
+    },
+    get max(): number {
+      return max;
+    },
+    setValue(v: number, m?: number): void {
+      if (m !== undefined) max = normMax(m);
+      value = Number.isFinite(v) ? v : 0;
+      paint();
+    },
+    setLabel(text: string): void {
+      label.textContent = text;
+    },
+  };
+}

package/src/web/client/ui/dom.ts

@@ -0,0 +1,23 @@
+/** DOM 节点构造与 HTML 转义；调用方提供 document，节点与字符串分别处理。 */
+
+/** `h(doc, 'div', 'sheet', '文本')` */
+export function h<K extends keyof HTMLElementTagNameMap>(
+  doc: Document,
+  tag: K,
+  cls?: string | null,
+  text?: string | null,
+): HTMLElementTagNameMap[K] {
+  const el = doc.createElement(tag);
+  if (cls) el.className = cls;
+  if (text != null) el.textContent = text;
+  return el;
+}
+
+/** HTML 转义。只转 `&<>"'` 五个字符。 */
+export function esc(s: unknown): string {
+  return String(s ?? '').replace(
+    /[&<>"']/g,
+    (c) =>
+      ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string,
+  );
+}