@contraagent/elements 0.0.0-stage → 0.2.0

package/src/code/highlight.ts

@@ -0,0 +1,378 @@
+// Syntax highlighting: a small tokenizer for a fixed set of languages, no library.
+// Each language is a few regular expressions and its words; a token is a piece of
+// the text and what it is. `highlight` returns escaped HTML: every token is escaped
+// before it is wrapped, so no input can inject markup.
+import { esc } from '../core/format.js';
+
+/** What a token is; '' for text of no colour. */
+export type TokenType =
+  | 'comment'
+  | 'doc'
+  | 'string'
+  | 'number'
+  | 'keyword'
+  | 'constant'
+  | 'builtin'
+  | 'type'
+  | 'function'
+  | 'class'
+  | 'decorator'
+  | 'key'
+  | 'tag'
+  | 'attribute'
+  | 'inserted'
+  | 'deleted'
+  | 'meta'
+  | '';
+
+/** A piece of the text and what it is. */
+export interface CodeToken {
+  text: string;
+  type: TokenType;
+}
+
+/** The languages highlighted, by name; `languageOf` reads their other names and file extensions. */
+export const LANGUAGES = ['python', 'json', 'javascript', 'typescript', 'c', 'cpp', 'java', 'go', 'rust', 'shell', 'toml', 'yaml', 'sql', 'xml', 'diff'] as const;
+export type Language = (typeof LANGUAGES)[number];
+
+interface Grammar {
+  /** The patterns, tried in order at each place: a token type and a regular expression with no capturing group. */
+  rules: readonly (readonly [TokenType, string])[];
+  keywords?: ReadonlySet<string>;
+  constants?: ReadonlySet<string>;
+  builtins?: ReadonlySet<string>;
+  /** The words after which a name is a function's or a type's own name. */
+  defines?: Readonly<Record<string, 'function' | 'class'>>;
+  /** A capitalized name (`Path`) is a type. */
+  types?: boolean;
+  /** The words compare in any case (SQL). */
+  caseless?: boolean;
+  /** A name; none: the words outside the rules have no colour. */
+  name?: string | null;
+}
+
+const words = (s: string): ReadonlySet<string> => new Set(s.split(' '));
+
+const LINE_C = ['comment', '//[^\\n]*|/\\*[\\s\\S]*?\\*/'] as const;
+const DQ = '"(?:[^"\\\\\\n]|\\\\.)*"';
+const SQ = "'(?:[^'\\\\\\n]|\\\\.)*'";
+const CHAR = "'(?:[^'\\\\\\n]|\\\\.)'";
+const NUMBER = ['number', "\\b(?:0[xX][\\da-fA-F_']+|0[bB][01_]+|\\d[\\d_']*(?:\\.\\d+)?(?:[eE][+-]?\\d+)?)[uUlLfFn]*\\b"] as const;
+const NAME = '[A-Za-z_$][\\w$]*';
+
+const JS_KW =
+  'break case catch class const continue debugger default delete do else export extends finally for from function if import in instanceof let new of return static super switch throw try typeof var void while with yield async await as';
+const C_KW =
+  'auto break case char const continue default do double else enum extern float for goto if inline int long register restrict return short signed sizeof static struct switch typedef union unsigned void volatile while bool';
+const C_DEFINES = { struct: 'class', class: 'class', enum: 'class', union: 'class' } as const;
+
+const GRAMMARS: Record<Language, Grammar> = {
+  python: {
+    rules: [
+      ['comment', '#[^\\n]*'],
+      ['doc', '(?:[rRbBfFuU]{0,2})(?:"""[\\s\\S]*?"""|\'\'\'[\\s\\S]*?\'\'\')'],
+      ['string', `(?:[rRbBfFuU]{0,2})(?:${DQ}|${SQ})`],
+      ['decorator', '@[A-Za-z_][\\w.]*'],
+      ['number', '\\b\\d[\\d_]*(?:\\.\\d+)?(?:[eE][+-]?\\d+)?\\b'],
+    ],
+    keywords: words(
+      '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 match case',
+    ),
+    constants: words('None True False self cls'),
+    builtins: words('str int float bool list dict set tuple bytes object type len range print isinstance super Optional Literal Any Union Path'),
+    defines: { def: 'function', class: 'class' },
+    types: true,
+    name: '[A-Za-z_]\\w*',
+  },
+  json: {
+    rules: [
+      ['key', `${DQ}(?=\\s*:)`],
+      ['string', DQ],
+      ['comment', '//[^\\n]*|/\\*[\\s\\S]*?\\*/'],
+      ['number', '-?\\b\\d+(?:\\.\\d+)?(?:[eE][+-]?\\d+)?\\b'],
+    ],
+    constants: words('true false null'),
+    name: '[A-Za-z_]\\w*',
+  },
+  javascript: {
+    rules: [LINE_C, ['string', `${DQ}|${SQ}|\`(?:[^\`\\\\]|\\\\.)*\``], ['decorator', '@[A-Za-z_$][\\w$.]*'], NUMBER],
+    keywords: words(JS_KW),
+    constants: words('true false null undefined this NaN Infinity'),
+    builtins: words('console Math JSON Promise Array Object String Number Boolean Map Set WeakMap Symbol Error Date RegExp BigInt globalThis window document'),
+    defines: { function: 'function', class: 'class' },
+    types: true,
+  },
+  typescript: {
+    rules: [LINE_C, ['string', `${DQ}|${SQ}|\`(?:[^\`\\\\]|\\\\.)*\``], ['decorator', '@[A-Za-z_$][\\w$.]*'], NUMBER],
+    keywords: words(
+      `${JS_KW} interface type enum implements namespace declare abstract private protected public readonly keyof infer is satisfies module override`,
+    ),
+    constants: words('true false null undefined this NaN Infinity'),
+    builtins: words(
+      'console Math JSON Promise Array Object String Number Boolean Map Set WeakMap Symbol Error Date RegExp BigInt globalThis string number boolean unknown never any void Record Partial Readonly',
+    ),
+    defines: { function: 'function', class: 'class', interface: 'class', type: 'class', enum: 'class' },
+    types: true,
+  },
+  c: {
+    rules: [['meta', '^[ \\t]*#[ \\t]*\\w+'], LINE_C, ['string', `${DQ}|${CHAR}`], NUMBER],
+    keywords: words(C_KW),
+    constants: words('NULL true false'),
+    builtins: words('printf fprintf malloc calloc realloc free size_t memcpy memset strlen strcmp FILE'),
+    defines: C_DEFINES,
+    types: true,
+  },
+  cpp: {
+    rules: [['meta', '^[ \\t]*#[ \\t]*\\w+'], LINE_C, ['string', `${DQ}|${CHAR}`], NUMBER],
+    keywords: words(
+      `${C_KW} alignas alignof catch class constexpr consteval const_cast decltype delete dynamic_cast explicit export friend mutable namespace new noexcept operator private protected public reinterpret_cast static_assert static_cast template this thread_local throw try typeid typename using virtual co_await co_return co_yield concept requires override final`,
+    ),
+    constants: words('nullptr NULL true false'),
+    builtins: words('std string vector map set unordered_map array optional cout cerr endl unique_ptr shared_ptr make_unique make_shared size_t'),
+    defines: C_DEFINES,
+    types: true,
+  },
+  java: {
+    rules: [LINE_C, ['string', `"""[\\s\\S]*?"""|${DQ}|${CHAR}`], ['decorator', '@[A-Za-z_][\\w.]*'], NUMBER],
+    keywords: words(
+      'abstract assert boolean break byte case catch char class continue default do double else enum extends final finally float for if implements import instanceof int interface long native new package private protected public return short static strictfp super switch synchronized this throw throws transient try void volatile while var record yield sealed permits',
+    ),
+    constants: words('true false null'),
+    builtins: words('String System Object Integer Long Double Boolean List Map Set Optional Exception RuntimeException'),
+    defines: { class: 'class', interface: 'class', enum: 'class', record: 'class' },
+    types: true,
+  },
+  go: {
+    rules: [LINE_C, ['string', `${DQ}|\`[^\`]*\`|${CHAR}`], NUMBER],
+    keywords: words(
+      'break case chan const continue default defer else fallthrough for func go goto if import interface map package range return select struct switch type var',
+    ),
+    constants: words('true false nil iota'),
+    builtins: words(
+      'append cap close complex copy delete imag len make new panic print println real recover string int int8 int16 int32 int64 uint uint8 uint16 uint32 uint64 byte rune error bool float32 float64 any',
+    ),
+    defines: { func: 'function', type: 'class' },
+    types: true,
+  },
+  rust: {
+    rules: [
+      LINE_C,
+      ['string', 'b?r#*"[\\s\\S]*?"#*|b?"(?:[^"\\\\]|\\\\.)*"'],
+      ['string', `b?${CHAR}`],
+      ['type', "'[A-Za-z_]\\w*\\b(?!')"],
+      ['decorator', '#!?\\[[^\\]\\n]*\\]'],
+      ['builtin', '\\b[A-Za-z_]\\w*!(?=\\s*[\\[({])'],
+      NUMBER,
+    ],
+    keywords: words(
+      'as async await break const continue crate dyn else enum extern fn for if impl in let loop match mod move mut pub ref return self Self static struct super trait type unsafe use where while',
+    ),
+    constants: words('true false None Some Ok Err'),
+    builtins: words('Vec String Option Result Box Rc Arc HashMap str usize isize u8 u16 u32 u64 i8 i16 i32 i64 f32 f64 bool char'),
+    defines: { fn: 'function', struct: 'class', enum: 'class', trait: 'class', type: 'class' },
+    types: true,
+  },
+  shell: {
+    rules: [
+      ['comment', '(?:^|(?<=\\s))#[^\\n]*'],
+      ['string', `"(?:[^"\\\\]|\\\\.)*"|'[^']*'`],
+      ['builtin', '\\$(?:\\{[^}\\n]*\\}|\\w+|[@*#?$!0-9-])'],
+      ['number', '\\b\\d+\\b'],
+    ],
+    keywords: words('if then else elif fi for while until do done case esac in function select return local export readonly declare set unset shift break continue exit source alias'),
+    builtins: words('echo cd printf read test eval exec trap pwd'),
+    name: '[A-Za-z_][\\w-]*',
+  },
+  toml: {
+    rules: [
+      ['comment', '#[^\\n]*'],
+      ['class', '^[ \\t]*\\[\\[?[^\\]\\n]*\\]\\]?'],
+      ['key', '^[ \\t]*[A-Za-z0-9_.\\-"\']+(?=[ \\t]*=)'],
+      ['string', `"""[\\s\\S]*?"""|'''[\\s\\S]*?'''|${DQ}|'[^'\\n]*'`],
+      ['number', '\\d{4}-\\d{2}-\\d{2}(?:[T ]\\d{2}:\\d{2}(?::\\d{2}(?:\\.\\d+)?)?(?:Z|[+-]\\d{2}:\\d{2})?)?'],
+      ['number', '[+-]?\\b\\d[\\d_]*(?:\\.\\d+)?(?:[eE][+-]?\\d+)?\\b'],
+    ],
+    constants: words('true false inf nan'),
+    name: '[A-Za-z_]\\w*',
+  },
+  yaml: {
+    rules: [
+      ['comment', '(?:^|(?<=\\s))#[^\\n]*'],
+      ['meta', '^(?:---|\\.\\.\\.)(?=\\s|$)'],
+      ['key', '[A-Za-z0-9_.\\-/]+(?=:(?:[ \\t]|$))'],
+      ['string', `${DQ}|'(?:[^'\\n]|'')*'`],
+      ['decorator', '[&*][\\w-]+'],
+      ['number', '[+-]?\\b\\d[\\d_]*(?:\\.\\d+)?(?:[eE][+-]?\\d+)?\\b'],
+    ],
+    constants: words('true false null yes no on off True False Null'),
+    name: '[A-Za-z_]\\w*',
+  },
+  sql: {
+    rules: [['comment', '--[^\\n]*|/\\*[\\s\\S]*?\\*/'], ['string', "'(?:[^']|'')*'"], ['key', '"(?:[^"]|"")*"'], ['number', '\\b\\d+(?:\\.\\d+)?\\b']],
+    keywords: words(
+      'select from where and or not insert into values update set delete create table drop alter add column index primary key foreign references join left right inner outer full cross on as group by order having limit offset union all distinct case when then else end is in exists between like returning with view default unique constraint if begin commit rollback transaction asc desc',
+    ),
+    constants: words('true false null'),
+    builtins: words('count sum avg min max coalesce cast lower upper now integer int text varchar char boolean date timestamp real numeric bigint serial float double'),
+    caseless: true,
+    name: '[A-Za-z_]\\w*',
+  },
+  xml: {
+    rules: [
+      ['comment', '<!--[\\s\\S]*?-->'],
+      ['meta', '<\\?[\\s\\S]*?\\?>|<!\\[CDATA\\[[\\s\\S]*?\\]\\]>|<![A-Za-z][^>]*>'],
+      ['tag', '</?[A-Za-z_][\\w:.-]*|/?>'],
+      ['attribute', '[A-Za-z_:][\\w:.-]*(?=\\s*=\\s*["\'])'],
+      ['string', '(?<==\\s*)(?:"[^"]*"|\'[^\']*\')'],
+      ['constant', '&#?\\w+;'],
+    ],
+    name: null,
+  },
+  diff: {
+    rules: [
+      ['meta', '^(?:diff |index |--- |\\+\\+\\+ |@@)[^\\n]*'],
+      ['inserted', '^\\+[^\\n]*'],
+      ['deleted', '^-[^\\n]*'],
+    ],
+    name: null,
+  },
+};
+
+/** The other names and the file extensions of each language. */
+const ALIASES: Record<string, Language> = {
+  py: 'python', python3: 'python', pyi: 'python', pyw: 'python',
+  jsonc: 'json', jsonl: 'json', json5: 'json', geojson: 'json',
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript', node: 'javascript',
+  ts: 'typescript', tsx: 'typescript', mts: 'typescript', cts: 'typescript',
+  h: 'c',
+  'c++': 'cpp', cc: 'cpp', cxx: 'cpp', hpp: 'cpp', hh: 'cpp', hxx: 'cpp',
+  golang: 'go',
+  rs: 'rust',
+  sh: 'shell', bash: 'shell', zsh: 'shell', ksh: 'shell', shellscript: 'shell',
+  ini: 'toml', cfg: 'toml',
+  yml: 'yaml',
+  html: 'xml', htm: 'xml', xhtml: 'xml', svg: 'xml', plist: 'xml', xsd: 'xml', xsl: 'xml',
+  patch: 'diff',
+};
+
+/** The language `hint` names: a language's name, another name of it, a file name or its extension; '' for any other. */
+export function languageOf(hint: string | null | undefined): Language | '' {
+  const h = String(hint || '').trim().toLowerCase().replace(/^.*\//, '');
+  const known = (s: string): Language | '' => ((LANGUAGES as readonly string[]).includes(s) ? (s as Language) : (ALIASES[s] ?? ''));
+  return known(h) || (h.includes('.') ? known(h.replace(/^.*\./, '')) : '');
+}
+
+const compiled = new Map<Language, RegExp>();
+
+function patternOf(lang: Language): RegExp {
+  let re = compiled.get(lang);
+  if (!re) {
+    const g = GRAMMARS[lang];
+    const parts = g.rules.map(([, src]) => `(${src})`);
+    const name = g.name === undefined ? NAME : g.name;
+    if (name) parts.push(`(${name})`);
+    re = new RegExp(parts.join('|'), 'gm');
+    compiled.set(lang, re);
+  }
+  return re;
+}
+
+/** The type of a name: a keyword, a constant, a function's or a type's own name, a built-in or a type; '' for any other. */
+function nameType(g: Grammar, word: string, prev: string): TokenType {
+  const w = g.caseless ? word.toLowerCase() : word;
+  if (g.keywords?.has(w)) return 'keyword';
+  if (g.constants?.has(w)) return 'constant';
+  const defined = g.defines?.[prev];
+  if (defined) return defined;
+  if (g.builtins?.has(w)) return 'builtin';
+  if (g.types && /^[A-Z]\w*$/.test(word) && word.length > 1 && /[a-z]/.test(word)) return 'type';
+  return '';
+}
+
+/** `code` as tokens of `hint`'s language (`languageOf`); the whole text as one plain token for any other. */
+export function tokenize(code: string, hint?: string | null): CodeToken[] {
+  const lang = languageOf(hint);
+  if (!lang || !code) return code ? [{ text: code, type: '' }] : [];
+  const g = GRAMMARS[lang];
+  const re = patternOf(lang);
+  const out: CodeToken[] = [];
+  const push = (text: string, type: TokenType) => {
+    if (!text) return;
+    const last = out[out.length - 1];
+    if (last && last.type === type) last.text += text;
+    else out.push({ text, type });
+  };
+  let at = 0;
+  let prev = '';
+  re.lastIndex = 0;
+  for (let m = re.exec(code); m; m = re.exec(code)) {
+    if (!m[0]) {
+      re.lastIndex++;
+      continue;
+    }
+    const gap = code.slice(at, m.index);
+    if (/\S/.test(gap)) prev = '';
+    push(gap, '');
+    at = re.lastIndex;
+    const rule = m.findIndex((x, i) => i > 0 && x !== undefined) - 1;
+    if (rule < g.rules.length) {
+      push(m[0], g.rules[rule]![0]);
+      prev = '';
+    } else {
+      push(m[0], nameType(g, m[0], prev));
+      prev = m[0];
+    }
+  }
+  push(code.slice(at), '');
+  return out;
+}
+
+/** The classes of a token's type in the markup (`prose` colours them). */
+const CLASS: Record<Exclude<TokenType, ''>, string> = {
+  comment: 'hl-c',
+  doc: 'hl-s hl-doc',
+  string: 'hl-s',
+  number: 'hl-n',
+  keyword: 'hl-k',
+  constant: 'hl-k hl-const',
+  builtin: 'hl-b',
+  type: 'hl-t',
+  function: 'hl-f',
+  class: 'hl-cls',
+  decorator: 'hl-d',
+  key: 'hl-key',
+  tag: 'hl-tag',
+  attribute: 'hl-attr',
+  inserted: 'hl-ins',
+  deleted: 'hl-del',
+  meta: 'hl-meta',
+};
+
+/** Tokens as escaped HTML, each but plain text in a `<span>` of its type's class. */
+export function tokensHtml(tokens: readonly CodeToken[]): string {
+  return tokens.map((t) => (t.type ? `<span class="${CLASS[t.type]}">${esc(t.text)}</span>` : esc(t.text))).join('');
+}
+
+/** Tokens split into lines at each line break: a token across lines becomes one piece per line. */
+export function tokenLines(tokens: readonly CodeToken[]): CodeToken[][] {
+  const lines: CodeToken[][] = [[]];
+  for (const t of tokens) {
+    const parts = t.text.split('\n');
+    parts.forEach((text, i) => {
+      if (i > 0) lines.push([]);
+      if (text) lines[lines.length - 1]!.push({ text, type: t.type });
+    });
+  }
+  return lines;
+}
+
+/** Highlighted, escaped HTML. `hint` is a language (`python`), another name of it, or a file name (`schema.py`); anything unknown is plain. */
+export function highlight(code: string, hint?: string | null): string {
+  return tokensHtml(tokenize(code, hint));
+}
+
+/** Python as highlighted, escaped HTML. */
+export const hlPython = (src: string): string => highlight(src, 'python');
+
+/** JSON as highlighted, escaped HTML. */
+export const hlJson = (src: string): string => highlight(src, 'json');

package/src/code/index.ts

@@ -0,0 +1,4 @@
+// `@contraagent/elements/code`: a text as highlighted code, the tokenizer it is drawn
+// with, and the languages it reads; `…/code/define` registers the element.
+export * from './highlight.js';
+export * from './code.js';

package/src/core/clock.ts

@@ -0,0 +1,46 @@
+// One shared once-a-second tick for every element that shows a running clock.
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+
+const hosts = new Set<ReactiveControllerHost>();
+let timer: ReturnType<typeof setInterval> | null = null;
+
+function tick(): void {
+  for (const h of hosts) h.requestUpdate();
+}
+
+/** Re-renders its host every second while it is connected. */
+export class ClockController implements ReactiveController {
+  constructor(private readonly host: ReactiveControllerHost) {
+    host.addController(this);
+  }
+  hostConnected(): void {
+    hosts.add(this.host);
+    timer ??= setInterval(tick, 1000);
+  }
+  hostDisconnected(): void {
+    hosts.delete(this.host);
+    if (!hosts.size && timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+}
+
+/**
+ * Start times that stay put. A process reports its age in whole seconds, so
+ * `now - age` jitters by a second between updates; the first value seen for an
+ * id is kept while later ones stay within a few seconds of it.
+ */
+export class StableStarts {
+  private readonly seen = new Map<string, number>();
+  at(id: string, ageS: number, now = Date.now()): number {
+    const t0 = Math.round(now - ageS * 1000);
+    const prev = this.seen.get(id);
+    if (prev !== undefined && Math.abs(prev - t0) < 5000) return prev;
+    this.seen.set(id, t0);
+    return t0;
+  }
+}
+
+/** Shared by every view, so the same process shows the same start everywhere. */
+export const starts = new StableStarts();

package/src/core/define.ts

@@ -0,0 +1,7 @@
+// Registration. The element classes are plain classes: a `define/` module (or
+// the host, under a tag name of its own) registers them.
+
+/** Registers `cls` as `tag`, unless the tag is already registered. */
+export function defineElement(tag: string, cls: CustomElementConstructor): void {
+  if (!customElements.get(tag)) customElements.define(tag, cls);
+}

package/src/core/events.ts

@@ -0,0 +1,89 @@
+// The events the generic elements send. Each bubbles and crosses shadow roots
+// (`composed`), so a host listens on any ancestor. An element states what the
+// reader did; its host decides what happens.
+
+/** A control's value changed (a segmented control). */
+export interface ChangeDetail {
+  value: string;
+}
+
+/** An item, by its id (a row's key). */
+export interface ItemDetail {
+  id: string;
+}
+
+/** An item opened (`open`) or closed. */
+export interface ToggleDetail {
+  id: string;
+  open: boolean;
+}
+
+/** The item chosen as the selection; null when the selection was cleared. */
+export interface SelectDetail {
+  id: string | null;
+}
+
+/** A column to order the items by, and the direction. */
+export interface SortDetail {
+  id: string;
+  direction: 'asc' | 'desc';
+}
+
+/** A view of the same data: a drawing, or a table. */
+export interface ViewDetail {
+  view: 'graph' | 'table';
+}
+
+/** A named action of an item (a tile's link): the item's id and the action's id. */
+export interface ActionDetail {
+  id: string;
+  action: string;
+}
+
+/** A section of a list of sections (a transcript's), by its 0-based index; null: the latest. */
+export interface SectionDetail {
+  index: number | null;
+}
+
+/** Every `cae-*` event and its detail. */
+export interface CaeEventMap {
+  'cae-change': ChangeDetail;
+  /** The item's primary action (a click or Enter on an item that has one). */
+  'cae-activate': ItemDetail;
+  'cae-select': SelectDetail;
+  'cae-sort': SortDetail;
+  'cae-action': ActionDetail;
+  /** Enter an item's inner view (a cluster, a node or a mark that has one). */
+  'cae-drill': ItemDetail;
+  /** The reader opened or closed an item (`open`: it is to be drawn open). */
+  'cae-toggle': ToggleDetail;
+  /** The reader chose another view. */
+  'cae-view-change': ViewDetail;
+  /** The reader picked a section (null: follow the latest). */
+  'cae-section-change': SectionDetail;
+  /** The section on screen changed (-1: none). */
+  'cae-section-shown': { index: number };
+  /** The reader asked for the content before what is loaded. */
+  'cae-load-earlier': Record<string, never>;
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    'cae-change': CustomEvent<ChangeDetail>;
+    'cae-activate': CustomEvent<ItemDetail>;
+    'cae-select': CustomEvent<SelectDetail>;
+    'cae-sort': CustomEvent<SortDetail>;
+    'cae-action': CustomEvent<ActionDetail>;
+    'cae-drill': CustomEvent<ItemDetail>;
+    'cae-toggle': CustomEvent<ToggleDetail>;
+    'cae-view-change': CustomEvent<ViewDetail>;
+    'cae-section-change': CustomEvent<SectionDetail>;
+    'cae-section-shown': CustomEvent<{ index: number }>;
+    'cae-load-earlier': CustomEvent<Record<string, never>>;
+  }
+}
+
+/** Sends a `cae-*` event from `el`: bubbling and composed. */
+export function emit<K extends keyof CaeEventMap>(el: EventTarget, name: K, detail: CaeEventMap[K]): boolean {
+  return el.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));
+}

package/src/core/format.ts

@@ -0,0 +1,25 @@
+// Formats that read the same in every language: a duration, and HTML escaping
+// for the few places that build markup as a string.
+
+/**
+ * A duration in seconds, in one format: `<0.1s`, `4.2s`, `37s`, `2m 05s`,
+ * `1h 02m`; '—' when unknown.
+ */
+export function fmtDur(s: number | null | undefined): string {
+  if (s === null || s === undefined || Number.isNaN(s)) return '—';
+  const v = Math.max(0, s);
+  if (v < 0.05) return '<0.1s';
+  if (v < 9.95) return `${v.toFixed(1)}s`;
+  const r = Math.round(v);
+  if (r < 60) return `${r}s`;
+  if (r < 3600) return `${Math.floor(r / 60)}m ${String(r % 60).padStart(2, '0')}s`;
+  return `${Math.floor(r / 3600)}h ${String(Math.floor((r % 3600) / 60)).padStart(2, '0')}m`;
+}
+
+/** HTML-escape a text for the few places that build markup as a string (markdown, highlighting). */
+export const esc = (s: string | number | null | undefined): string =>
+  String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');

package/src/core/frame.ts

@@ -0,0 +1,5 @@
+// The frame a drawing is shown in: how tall it may grow.
+
+/** A frame is at most this share of the window's height, and at least `FRAME_MIN` px. */
+export const FRAME_SHARE = 0.7;
+export const FRAME_MIN = 360;

package/src/core/strings.ts

@@ -0,0 +1,11 @@
+// An element's visible words. Each element takes `strings: Partial<XStrings>`
+// and falls back to its English defaults (`DEFAULT_X_STRINGS`) for a word it is
+// not given; a word with a number is a function, so plural rules and word order
+// belong to the host.
+
+/** `given` over `defaults`: a word left out (or undefined) keeps its default. */
+export function withDefaults<T extends object>(defaults: Readonly<T>, given: Partial<T> | null | undefined): T {
+  const out = { ...defaults };
+  if (given) for (const [k, v] of Object.entries(given)) if (v !== undefined) (out as Record<string, unknown>)[k] = v;
+  return out;
+}

package/src/core/tone.ts

@@ -0,0 +1,14 @@
+// A tone: the status colour a value takes. The names are the token names
+// (`--ca-status-<tone>`); `neutral` is the text colour, with no `data-tone`.
+// An element shows a tone as `data-tone` (styles/status.ts draws it).
+import { nothing } from 'lit';
+
+/** A status colour, or `neutral` for the text colour. */
+export type Tone = 'failed' | 'attention' | 'done' | 'running' | 'muted' | 'neutral';
+
+/** Every tone with a status colour (a `data-tone` value): each but `neutral`. */
+export const TONES: readonly Exclude<Tone, 'neutral'>[] = ['failed', 'attention', 'done', 'running', 'muted'];
+
+/** The `data-tone` attribute of a tone: none for `neutral` (or no tone). */
+export const toneAttr = (tone: Tone | null | undefined): Exclude<Tone, 'neutral'> | typeof nothing =>
+  tone && tone !== 'neutral' ? tone : nothing;

package/src/count/count.ts

@@ -0,0 +1,54 @@
+import { LitElement, type PropertyValues } from 'lit';
+import { property, state } from 'lit/decorators.js';
+
+const reducedMotion = () => globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+
+/**
+ * A number that counts up (or down) to its new value when it changes; at once
+ * for a reader who asks for reduced motion.
+ *
+ * @tagname cae-count
+ */
+export class CaeCount extends LitElement {
+  @property({ type: Number }) value = 0;
+  @state() private shown = 0;
+  private frame = 0;
+
+  protected override createRenderRoot() {
+    return this;
+  }
+
+  protected override willUpdate(changed: PropertyValues<this>): void {
+    if (!changed.has('value')) return;
+    const from = this.shown;
+    const to = this.value;
+    cancelAnimationFrame(this.frame);
+    if (reducedMotion() || from === to || !Number.isFinite(to) || !this.isConnected) {
+      this.shown = to;
+      return;
+    }
+    const t0 = performance.now();
+    const tick = (now: number) => {
+      const k = Math.min(1, (now - t0) / 700);
+      this.shown = Math.round(from + (to - from) * (1 - Math.pow(1 - k, 3)));
+      if (k < 1) this.frame = requestAnimationFrame(tick);
+    };
+    this.frame = requestAnimationFrame(tick);
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    cancelAnimationFrame(this.frame);
+    this.shown = this.value;
+  }
+
+  override render() {
+    return String(this.shown);
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-count': CaeCount;
+  }
+}

package/src/count/elapsed.ts

@@ -0,0 +1,33 @@
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { ClockController } from '../core/clock.js';
+import { fmtDur } from '../core/format.js';
+
+/**
+ * Time since `since` (epoch ms), ticking every second: `42s`, `3m 05s`, `1h 02m`.
+ *
+ * @tagname cae-elapsed
+ */
+export class CaeElapsed extends LitElement {
+  @property({ type: Number }) since = 0;
+
+  constructor() {
+    super();
+    new ClockController(this);
+  }
+
+  // Plain text in the light DOM: it takes the font and colour of where it is put.
+  protected override createRenderRoot() {
+    return this;
+  }
+
+  override render() {
+    return this.since ? fmtDur((Date.now() - this.since) / 1000) : '';
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-elapsed': CaeElapsed;
+  }
+}