@contraagent/elements 0.0.0-stage → 0.1.0

package/src/lanes/lanes.ts

@@ -0,0 +1,143 @@
+import { LitElement, html, nothing, type PropertyValues, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import { repeat } from 'lit/directives/repeat.js';
+import { withDefaults } from '../core/strings.js';
+import { legend, legendStyles, type LegendItem } from '../primitives/legend.js';
+import { base } from '../styles/index.js';
+import { barBox, fitRange, stack } from './stack.js';
+import { lanesStyles } from './styles.js';
+import { DEFAULT_LANES_STRINGS, type Lane, type LaneStyle, type LanesStrings, type TimeRange } from './types.js';
+
+/** A span shorter than this shows seconds on its axis (else every tick reads the same minute). */
+const SECONDS_BELOW_MS = 10 * 60e3;
+
+/**
+ * Bars on a time axis, a lane per group: each bar as long as it took, the
+ * overlapping bars of a lane stacked, a running bar (`end` null) growing until
+ * now and a line at now. A bar's look is its style in `barStyles`, whose
+ * labels are the legend (a row per `group`). The bars grow in when they are
+ * first drawn.
+ *
+ * Its look: `--cae-lanes-label-width` (the lanes' labels; 112px, 78px on a
+ * narrow screen) and the parts.
+ *
+ * @tagname cae-lanes
+ * @csspart axis - the times above the lanes
+ * @csspart lane - each lane
+ * @csspart lane-label - a lane's label
+ * @csspart track - the area of a lane's bars
+ * @csspart bar - each bar
+ * @csspart now - the line at now, while a bar runs
+ * @csspart legend - each row of the legend
+ * @csspart empty - what the element shows with no bars
+ * @slot empty - what the element shows with no bars, instead of `strings.empty`
+ */
+export class CaeLanes extends LitElement {
+  static override styles = [base, legendStyles, lanesStyles];
+
+  @property({ attribute: false }) lanes: readonly Lane[] = [];
+  /** A look per style key of the bars, in legend order. */
+  @property({ attribute: false }) barStyles: Readonly<Record<string, LaneStyle>> = {};
+  /** The time the axis spans; null fits the bars (`fitRange`). */
+  @property({ attribute: false }) range: TimeRange | null = null;
+  /** Draws again every second, so the running bars and the line at now move. */
+  @property({ type: Boolean }) live = false;
+  /** Bars the host left out, as a note after the legend. */
+  @property({ type: Number }) omitted = 0;
+  /** The language of the axis' times; by default the page's (`lang`). */
+  @property() locale = '';
+  @property({ attribute: false }) strings: Partial<LanesStrings> = {};
+
+  private timer: ReturnType<typeof setInterval> | null = null;
+  /** The bars have been drawn once: later bars do not grow in. */
+  private drawn = false;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.tick(this.live);
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.tick(false);
+  }
+
+  protected override updated(changed: PropertyValues<this>): void {
+    if (changed.has('live')) this.tick(this.live);
+  }
+
+  private tick(on: boolean): void {
+    if (on && !this.timer) this.timer = setInterval(() => this.requestUpdate(), 1000);
+    if (!on && this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private time(t: number, seconds: boolean): string {
+    const locale = this.locale || document.documentElement.lang || undefined;
+    return new Date(t).toLocaleTimeString(locale, { hour: '2-digit', minute: '2-digit', ...(seconds ? { second: '2-digit' } : {}), hourCycle: 'h23' });
+  }
+
+  override render() {
+    const s = withDefaults(DEFAULT_LANES_STRINGS, this.strings);
+    const now = Date.now();
+    const range = this.range ?? fitRange(this.lanes, now);
+    if (!range) return html`<div part="empty"><slot name="empty">${s.empty}</slot></div>`;
+    const animate = !this.drawn;
+    this.drawn = true;
+    const span = Math.max(1, range.end - range.start);
+    const running = this.lanes.some((l) => l.bars.some((b) => b.end === null));
+    const seconds = span < SECONDS_BELOW_MS;
+    const nowAt = Math.min(1, (now - range.start) / span);
+    return html`<div class="lanes ${animate ? 'anim' : ''}">
+        <div class="axis" part="axis">${[0, 0.25, 0.5, 0.75, 1].map((k) => html`<span>${this.time(range.start + span * k, seconds)}</span>`)}</div>
+        ${repeat(this.lanes, (l) => l.id, (l) => this.lane(l, range, now))}
+        ${running
+          ? html`<span class="now" part="now" style="left:calc(var(--label) + 8px + (100% - var(--label) - 8px) * ${nowAt.toFixed(4)})"></span>`
+          : nothing}
+      </div>
+      ${this.legends(s)}`;
+  }
+
+  private lane(l: Lane, range: TimeRange, now: number): TemplateResult {
+    const placed = stack(l.bars);
+    const rows = Math.max(1, ...placed.map((p) => p.row + 1));
+    return html`<div class="lane" part="lane">
+      <span class="name" part="lane-label" title=${l.label}>${l.label}</span>
+      <div class="track" part="track" style="--rows:${rows}">
+        ${placed.map(({ bar, row }) => {
+          const box = barBox(bar, range, now);
+          const look = this.barStyles[bar.style];
+          return html`<span class="bar ${bar.end === null ? 'running' : ''}" part="bar" data-style=${bar.style}
+            data-pattern=${look?.pattern ?? 'solid'} title=${bar.label}
+            style="--bar:${look?.color ?? 'var(--line2)'};--row:${row};left:min(${box.left.toFixed(3)}%, 100% - max(3px, ${box.width.toFixed(3)}%));width:${box.width.toFixed(3)}%"></span>`;
+        })}
+      </div>
+    </div>`;
+  }
+
+  /** A legend row per group of styles, in key order; the note of omitted bars ends the last. */
+  private legends(s: LanesStrings): TemplateResult[] {
+    const groups: LegendItem[][] = [];
+    for (const look of Object.values(this.barStyles)) {
+      const g = look.group ?? 0;
+      (groups[g] ??= []).push({
+        label: look.label,
+        icon: html`<i data-pattern=${look.pattern ?? 'solid'} style="--bar:${look.color}"></i>`,
+      });
+    }
+    const rows = groups.filter(Boolean);
+    if (this.omitted) {
+      if (!rows.length) rows.push([]);
+      rows[rows.length - 1]!.push({ label: s.omitted(this.omitted) });
+    }
+    return rows.map((items) => legend(items));
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-lanes': CaeLanes;
+  }
+}

package/src/lanes/stack.ts

@@ -0,0 +1,51 @@
+// Where the bars of `<cae-lanes>` go: their row in a lane, their box on the
+// axis, and the axis when the host does not set one. Pure.
+import type { Lane, TimeRange } from './types.js';
+
+interface Span {
+  start: number;
+  end: number | null;
+}
+
+/**
+ * The bars of a lane in order of start, each on the first row whose last bar
+ * has ended, so overlapping bars do not hide each other. A running bar (`end`
+ * null) keeps its row.
+ */
+export function stack<B extends Span>(bars: readonly B[]): { bar: B; row: number }[] {
+  const ends: number[] = [];
+  return [...bars]
+    .sort((a, b) => a.start - b.start)
+    .map((bar) => {
+      const end = bar.end ?? Infinity;
+      let row = ends.findIndex((e) => e <= bar.start);
+      if (row < 0) row = ends.push(end) - 1;
+      else ends[row] = end;
+      return { bar, row };
+    });
+}
+
+/** A running bar extends the axis to now plus this margin, rounded up to `STEP_MS`. */
+const MARGIN_MS = 20e3;
+const STEP_MS = 60e3;
+
+/**
+ * The axis that fits the bars: from the first start to the last end; with a
+ * running bar, to `now` plus 20 seconds, rounded up to the minute. Null with no bars.
+ */
+export function fitRange(lanes: readonly Lane[], now: number): TimeRange | null {
+  const bars = lanes.flatMap((l) => l.bars);
+  if (!bars.length) return null;
+  const start = Math.min(...bars.map((b) => b.start));
+  const running = bars.some((b) => b.end === null);
+  const end = running ? start + Math.ceil((now - start + MARGIN_MS) / STEP_MS) * STEP_MS : Math.max(...bars.map((b) => b.end ?? now));
+  return { start, end };
+}
+
+/** A bar's left edge and width, in percent of the range; a running bar grows to `now`, within the range. */
+export function barBox(b: Span, range: TimeRange, now: number): { left: number; width: number } {
+  const span = Math.max(1, range.end - range.start);
+  const left = ((b.start - range.start) / span) * 100;
+  const w = (((b.end ?? now) - b.start) / span) * 100;
+  return { left, width: Math.max(0.4, b.end === null ? Math.min(100 - left, w) : w) };
+}

package/src/lanes/styles.ts

@@ -0,0 +1,30 @@
+// The look of `<cae-lanes>`: a label column, then a track per lane with its
+// bars; a bar's look is its colour (`--bar`) and its pattern (`data-pattern`),
+// the same on the bar and on its swatch in the legend.
+import { css } from 'lit';
+
+export const lanesStyles = css`
+  :host { display: block; container-type: inline-size; --label: var(--cae-lanes-label-width, 112px); }
+  /* narrow (the host is a container): a narrower label column, and the axis' first, middle and last times only */
+  @container (max-width: 760px) { .lanes { --label: var(--cae-lanes-label-width, 78px); } }
+  @container (max-width: 480px) { .axis span:nth-child(even) { display: none; } }
+  .lanes { position: relative; }
+  .axis { display: flex; justify-content: space-between; font-family: var(--mono); font-size: 10px; color: var(--text-muted); margin: 0 0 6px calc(var(--label) + 8px); }
+  .lane { display: grid; grid-template-columns: var(--label) minmax(0, 1fr); gap: 8px; align-items: center; min-height: 24px; padding: 4px 0; }
+  .name { font-size: 11.5px; color: var(--text-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .track { position: relative; height: calc(var(--rows, 1) * 14px + 2px); border-radius: 4px;
+    background: repeating-linear-gradient(90deg, color-mix(in srgb, var(--text) 5%, transparent) 0 1px, transparent 1px 10%); }
+  .bar { position: absolute; top: calc(var(--row, 0) * 14px + 2px); height: 12px; border-radius: 4px; min-width: 3px; cursor: default;
+    transform-origin: left center; transition: width 1s linear; }
+  .anim .bar:not(.running) { animation: growx 0.6s var(--ease) both; }
+  :is(.bar, .legend i)[data-pattern] { background: var(--bar); }
+  :is(.bar, .legend i)[data-pattern='hatched'] { background: repeating-linear-gradient(135deg, var(--bar) 0 3px, color-mix(in srgb, var(--bar) 55%, var(--bg)) 3px 5px); }
+  :is(.bar, .legend i)[data-pattern='outline'] { background: none; box-shadow: inset 0 0 0 1.5px var(--bar); }
+  :is(.bar, .legend i)[data-pattern='striped'] { background: repeating-linear-gradient(45deg, var(--bar) 0 6px, color-mix(in srgb, var(--bar) 60%, var(--bg)) 6px 12px);
+    background-size: 17px 17px; }
+  .bar[data-pattern='striped'] { animation: stripes 0.8s linear infinite; box-shadow: 0 0 12px color-mix(in srgb, var(--bar) 45%, transparent); }
+  .bar:hover { filter: brightness(1.2); }
+  .now { position: absolute; top: -4px; bottom: -4px; width: 2px; background: var(--status-running); border-radius: 2px; box-shadow: 0 0 10px var(--status-running); }
+  .legend { margin-top: 10px; }
+  .legend + .legend { margin-top: 4px; }
+`;

package/src/lanes/types.ts

@@ -0,0 +1,51 @@
+// What `<cae-lanes>` shows: bars on a time axis, a lane per group.
+
+/** Something that took time: from `start` to `end` (epoch ms); `end` null while it runs. */
+export interface LaneBar {
+  id: string;
+  start: number;
+  /** Null: running, the bar grows to now. */
+  end: number | null;
+  /** The key of its look in the element's `barStyles`. */
+  style: string;
+  /** The bar's tooltip: one item per line. */
+  label: string;
+}
+
+/** A row of bars; overlapping bars of a lane are stacked (`stack`). */
+export interface Lane {
+  id: string;
+  label: string;
+  bars: readonly LaneBar[];
+}
+
+/** How a bar is filled: its colour, hatched, moving stripes, or only an outline. */
+export type LanePattern = 'solid' | 'hatched' | 'striped' | 'outline';
+
+/** A look of bars, and its entry in the legend. */
+export interface LaneStyle {
+  label: string;
+  /** A CSS colour or `var(...)`. */
+  color: string;
+  pattern?: LanePattern;
+  /** The legend row of its entry (0, the first, by default). */
+  group?: number;
+}
+
+export interface LanesStrings {
+  /** The note after the legend: bars the host left out. */
+  omitted: (n: number) => string;
+  /** No bars. */
+  empty: string;
+}
+
+export const DEFAULT_LANES_STRINGS: LanesStrings = {
+  omitted: (n) => (n === 1 ? '1 bar not shown' : `${n} bars not shown`),
+  empty: 'No bars',
+};
+
+/** The time the axis spans, epoch ms. */
+export interface TimeRange {
+  start: number;
+  end: number;
+}

package/src/markdown/cae-markdown.ts

@@ -0,0 +1,64 @@
+import { LitElement, css, html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { withDefaults } from '../core/strings.js';
+import { base, prose } from '../styles/index.js';
+import { mdFile } from './markdown.js';
+
+export interface MarkdownStrings {
+  /** The button that shows the text rendered. */
+  showRendered: string;
+  /** The button that shows the text as it is. */
+  showSource: string;
+}
+
+export const DEFAULT_MARKDOWN_STRINGS: Readonly<MarkdownStrings> = { showRendered: 'Show rendered', showSource: 'Show source' };
+
+/**
+ * A markdown text with a rendered/source switch. `split` may take a leading line
+ * off the text, shown apart above the rendered body; the source is the text as
+ * it is.
+ *
+ * @tagname cae-markdown
+ * @csspart toggle - the rendered/source button
+ */
+export class CaeMarkdown extends LitElement {
+  static override styles = [
+    base,
+    prose,
+    css`
+      :host { display: block; }
+      /* A path or a URL has no break opportunity; it wraps inside the box instead of widening it. */
+      .md-p, .md-h, .md-li, .md-q { overflow-wrap: anywhere; }
+      .bar { display: flex; justify-content: flex-end; margin-bottom: 4px; }
+    `,
+  ];
+
+  @property() text = '';
+  /** Takes a leading line off the text (`head`), shown apart above the rendered `body`. */
+  @property({ attribute: false }) split?: (text: string) => { head: string; body: string };
+  /** Marks up the rendered (escaped) HTML further, as `mdFile`'s `mark`. */
+  @property({ attribute: false }) transform?: (html: string) => string;
+  /** The visible words; English by default. */
+  @property({ attribute: false }) strings: Partial<MarkdownStrings> = {};
+  @state() private source = false;
+
+  override render() {
+    const s = withDefaults(DEFAULT_MARKDOWN_STRINGS, this.strings);
+    const { head, body } = this.split?.(this.text) ?? { head: '', body: this.text };
+    const rendered = mdFile(body, this.transform);
+    return html`<div class="bar">
+        <button type="button" class="df-tog" part="toggle" @click=${() => (this.source = !this.source)}>
+          ${this.source ? s.showRendered : s.showSource}</button>
+      </div>
+      ${this.source
+        ? html`<pre class="df-text">${this.text}</pre>`
+        : html`${head ? html`<div class="md-tele jmono">${head}</div>` : nothing}${unsafeHTML(rendered)}`}`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-markdown': CaeMarkdown;
+  }
+}

package/src/markdown/highlight.ts

@@ -0,0 +1,94 @@
+// Syntax highlighting: a small tokenizer for what plugins and contracts contain
+// (Python, JSON), no library. Returns escaped HTML: every token is escaped
+// before it is wrapped, so no input can inject markup.
+import { esc } from '../core/format.js';
+
+const PY_KW = new Set(
+  'and as assert async await break class continue def del elif else except finally for from global if import in is lambda nonlocal not or pass raise return try while with yield'.split(
+    ' ',
+  ),
+);
+const PY_CONST = new Set(['None', 'True', 'False', 'self', 'cls']);
+const PY_BUILTIN = new Set(
+  'str int float bool list dict set tuple bytes object type len range print isinstance super Optional Literal Any Union Path'.split(' '),
+);
+const PY_TOKEN = new RegExp(
+  [
+    '(#[^\\n]*)', // 1 comment
+    '((?:[rRbBfFuU]{0,2})(?:"""[\\s\\S]*?"""|\'\'\'[\\s\\S]*?\'\'\'))', // 2 triple-quoted string (docstrings)
+    '((?:[rRbBfFuU]{0,2})(?:"(?:[^"\\\\\\n]|\\\\.)*"|\'(?:[^\'\\\\\\n]|\\\\.)*\'))', // 3 string
+    '(@[A-Za-z_][\\w.]*)', // 4 decorator
+    '(\\b\\d[\\d_]*(?:\\.\\d+)?(?:[eE][+-]?\\d+)?\\b)', // 5 number
+    '([A-Za-z_]\\w*)', // 6 name
+  ].join('|'),
+  'g',
+);
+
+export function hlPython(src: string): string {
+  let out = '';
+  let last = 0;
+  let prevWord = '';
+  PY_TOKEN.lastIndex = 0;
+  for (let m = PY_TOKEN.exec(src); m; m = PY_TOKEN.exec(src)) {
+    out += esc(src.slice(last, m.index));
+    last = PY_TOKEN.lastIndex;
+    const [tok, com, tri, str, dec, num, name] = m;
+    if (com) out += `<span class="hl-c">${esc(tok)}</span>`;
+    else if (tri) out += `<span class="hl-s hl-doc">${esc(tok)}</span>`;
+    else if (str) out += `<span class="hl-s">${esc(tok)}</span>`;
+    else if (dec) out += `<span class="hl-d">${esc(tok)}</span>`;
+    else if (num) out += `<span class="hl-n">${esc(tok)}</span>`;
+    else if (name) {
+      const cls = PY_KW.has(name)
+        ? 'hl-k'
+        : PY_CONST.has(name)
+          ? 'hl-k hl-const'
+          : prevWord === 'class'
+            ? 'hl-cls'
+            : prevWord === 'def'
+              ? 'hl-f'
+              : PY_BUILTIN.has(name)
+                ? 'hl-b'
+                : /^[A-Z]\w*$/.test(name) && name.length > 1 && /[a-z]/.test(name)
+                  ? 'hl-t'
+                  : '';
+      out += cls ? `<span class="${cls}">${esc(name)}</span>` : esc(name);
+      prevWord = name;
+      continue;
+    }
+    if (!/^\s*$/.test(tok)) prevWord = '';
+  }
+  return out + esc(src.slice(last));
+}
+
+export function hlJson(src: string): string {
+  const re = /("(?:[^"\\\n]|\\.)*")(\s*:)?|\b(true|false|null)\b|(-?\b\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\b)/g;
+  let out = '';
+  let last = 0;
+  for (let m = re.exec(src); m; m = re.exec(src)) {
+    out += esc(src.slice(last, m.index));
+    last = re.lastIndex;
+    const [, str, colon, kw, num] = m;
+    out += str
+      ? colon
+        ? `<span class="hl-key">${esc(str)}</span>${esc(colon)}`
+        : `<span class="hl-s">${esc(str)}</span>`
+      : kw
+        ? `<span class="hl-k hl-const">${kw}</span>`
+        : `<span class="hl-n">${num ?? ''}</span>`;
+  }
+  return out + esc(src.slice(last));
+}
+
+const LANG_OF: Record<string, 'python' | 'json'> = { py: 'python', python: 'python', json: 'json', jsonc: 'json' };
+
+function langOf(hint: string | null | undefined): 'python' | 'json' | '' {
+  const h = String(hint || '').toLowerCase();
+  return LANG_OF[h.replace(/^.*\./, '')] || LANG_OF[h] || '';
+}
+
+/** Highlighted, escaped HTML. `hint` is a fence language ("python") or a file name ("schema.py"); anything unknown is plain. */
+export function highlight(code: string, hint?: string | null): string {
+  const lang = langOf(hint);
+  return lang === 'python' ? hlPython(code) : lang === 'json' ? hlJson(code) : esc(code);
+}

package/src/markdown/index.ts

@@ -0,0 +1,5 @@
+// `@contraagent/elements/markdown`: markdown and code as escaped HTML, and the
+// element that shows it; `…/markdown/define` registers the element.
+export * from './markdown.js';
+export * from './highlight.js';
+export * from './cae-markdown.js';

package/src/markdown/markdown.ts

@@ -0,0 +1,110 @@
+// Markdown: what model output and text files actually use. Everything is
+// escaped first, so nothing the text holds can inject markup; links keep only
+// http(s) targets. Returns HTML for `unsafeHTML`.
+import { esc } from '../core/format.js';
+import { highlight } from './highlight.js';
+
+function mdInline(t: string): string {
+  return t
+    .replace(/`([^`\n]+)`/g, '<code>$1</code>')
+    .replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>')
+    .replace(/(^|[^*\w])\*([^*\n]+)\*(?!\w)/g, '$1<i>$2</i>')
+    .replace(/\[([^\]\n]+)\]\((https?:\/\/[^)\s]+)\)/g, '<a class="lnk" href="$2" target="_blank" rel="noopener">$1</a>');
+}
+
+interface Segment {
+  t: 'text' | 'code';
+  s: string;
+  lang?: string;
+}
+
+/** Text and fenced code; an unclosed fence (a live stream) runs to the end. */
+function mdSplit(text: string): Segment[] {
+  const out: Segment[] = [];
+  let pos = 0;
+  for (;;) {
+    const open = text.indexOf('```', pos);
+    if (open < 0) {
+      out.push({ t: 'text', s: text.slice(pos) });
+      return out;
+    }
+    out.push({ t: 'text', s: text.slice(pos, open) });
+    const nl = text.indexOf('\n', open + 3);
+    const lang = text.slice(open + 3, nl < 0 ? text.length : nl).trim();
+    const start = nl < 0 ? text.length : nl + 1;
+    const close = text.indexOf('```', start);
+    if (close < 0) {
+      out.push({ t: 'code', s: text.slice(start), lang });
+      return out;
+    }
+    out.push({ t: 'code', s: text.slice(start, close), lang });
+    pos = close + 3;
+  }
+}
+
+const TABLE_ROW = /^\s*\|.*\|\s*$/;
+
+export function md(text: string | null | undefined): string {
+  return mdSplit(String(text || ''))
+    .map((seg) => {
+      if (seg.t === 'code') return `<pre><code class="hl">${highlight(seg.s, seg.lang)}</code></pre>`;
+      const lines = esc(seg.s).split('\n');
+      const out: string[] = [];
+      for (let k = 0; k < lines.length; k++) {
+        const line = lines[k] ?? '';
+        let m: RegExpMatchArray | null;
+        if ((m = line.match(/^(#{1,6})\s+(.*)$/))) {
+          out.push(`<div class="md-h md-h${Math.min(m[1]!.length, 4)}">${mdInline(m[2]!)}</div>`);
+        } else if (/^\s*(-{3,}|\*{3,})\s*$/.test(line)) {
+          out.push('<hr class="md-hr">');
+        } else if ((m = line.match(/^\s*&gt;\s?(.*)$/))) {
+          out.push(`<div class="md-q">${mdInline(m[1]!)}</div>`);
+        } else if ((m = line.match(/^\s*[-*]\s+(.*)$/))) {
+          out.push(`<div class="md-li">${mdInline(m[1]!)}</div>`);
+        } else if ((m = line.match(/^\s*(\d+)[.)]\s+(.*)$/))) {
+          out.push(`<div class="md-li md-ol"><span class="md-n">${m[1]}.</span>${mdInline(m[2]!)}</div>`);
+        } else if (TABLE_ROW.test(line) && /^\s*\|[\s:|-]+\|\s*$/.test(lines[k + 1] ?? '')) {
+          const cells = (l: string) =>
+            l
+              .trim()
+              .replace(/^\||\|$/g, '')
+              .split('|')
+              .map((c) => mdInline(c.trim()));
+          const head = cells(line);
+          k += 2;
+          const rows: string[][] = [];
+          while (k < lines.length && TABLE_ROW.test(lines[k] ?? '')) rows.push(cells(lines[k++] ?? ''));
+          k--;
+          out.push(
+            `<table class="md-t"><tr>${head.map((c) => `<th>${c}</th>`).join('')}</tr>` +
+              rows.map((r) => `<tr>${r.map((c) => `<td>${c}</td>`).join('')}</tr>`).join('') +
+              '</table>',
+          );
+        } else {
+          out.push(line.trim() === '' ? '<div class="md-gap"></div>' : `<div class="md-p">${mdInline(line)}</div>`);
+        }
+      }
+      return out.join('');
+    })
+    .join('');
+}
+
+/** A markdown file as a person reads it: its `---` front matter as a small table, then the body. */
+export function mdFile(text: string | null | undefined, mark?: (html: string) => string): string {
+  const src = String(text || '');
+  const m = src.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  let front = '';
+  let body = src;
+  if (m) {
+    body = m[2] ?? '';
+    const rows = (m[1] ?? '')
+      .split('\n')
+      .map((l) => l.match(/^([\w-]+):\s*(.*)$/))
+      .filter((x): x is RegExpMatchArray => !!x)
+      .map(([, k, v]) => `<tr><td class="jmono">${esc(k)}</td><td>${esc(v)}</td></tr>`)
+      .join('');
+    front = rows ? `<table class="md-front">${rows}</table>` : '';
+  }
+  const html = md(body);
+  return `<div class="md-doc">${front}${mark ? mark(html) : html}</div>`;
+}

package/src/matrix/grid-step.ts

@@ -0,0 +1,58 @@
+// Moving across a grid of marks with the keys: the marks of a table of rows and columns.
+
+/**
+ * Where a key moves in a grid of marks (`has[r][c]`: a mark there), from (`r`, `c`):
+ * left and right to the next mark in the row, up and down to the nearest row with a
+ * mark in the column, Home and End to the row's first and last, with Ctrl to the
+ * first and last row's, PageUp and PageDown `page` rows. Null when it does not move.
+ */
+export function gridStep(has: readonly (readonly boolean[])[], r: number, c: number, key: string, ctrl = false, page = 10): [number, number] | null {
+  const at = (i: number, j: number) => has[i]?.[j] === true;
+  const first = (i: number) => (has[i] ?? []).findIndex(Boolean);
+  const last = (i: number) => (has[i] ?? []).lastIndexOf(true);
+  const rowWith = (from: number, step: number, col: number): number => {
+    for (let i = from; i >= 0 && i < has.length; i += step) if (at(i, col)) return i;
+    return -1;
+  };
+  const near = (i: number): [number, number] | null => {
+    // The mark of row i nearest to column c.
+    const row = has[i] ?? [];
+    let best = -1;
+    row.forEach((x, j) => x && (best < 0 || Math.abs(j - c) < Math.abs(best - c)) && (best = j));
+    return best < 0 ? null : [i, best];
+  };
+  switch (key) {
+    case 'ArrowRight':
+    case 'ArrowLeft': {
+      const s = key === 'ArrowRight' ? 1 : -1;
+      for (let j = c + s; j >= 0 && j < (has[r]?.length ?? 0); j += s) if (at(r, j)) return [r, j];
+      return null;
+    }
+    case 'ArrowDown':
+    case 'ArrowUp': {
+      const s = key === 'ArrowDown' ? 1 : -1;
+      const i = rowWith(r + s, s, c);
+      if (i >= 0) return [i, c];
+      for (let k = r + s; k >= 0 && k < has.length; k += s) if (first(k) >= 0) return near(k);
+      return null;
+    }
+    case 'Home': {
+      const i = ctrl ? has.findIndex((row) => row.some(Boolean)) : r;
+      return i < 0 || first(i) < 0 ? null : [i, first(i)];
+    }
+    case 'End': {
+      let i = r;
+      if (ctrl) for (i = has.length - 1; i >= 0 && last(i) < 0; i--);
+      return i < 0 || last(i) < 0 ? null : [i, last(i)];
+    }
+    case 'PageDown':
+    case 'PageUp': {
+      const s = key === 'PageDown' ? 1 : -1;
+      const target = Math.max(0, Math.min(has.length - 1, r + s * page));
+      for (let k = target; k !== r; k -= s) if (first(k) >= 0) return near(k);
+      return null;
+    }
+    default:
+      return null;
+  }
+}

package/src/matrix/index.ts

@@ -0,0 +1,6 @@
+// A table of marks: `@contraagent/elements/matrix`. `CaeMarkMatrix` is registered
+// by `@contraagent/elements/matrix/define`.
+export * from './types.js';
+export * from './grid-step.js';
+export * from './styles.js';
+export * from './mark-matrix.js';