@hajimism/dek 0.1.0

package/src/core/cue.ts

@@ -0,0 +1,187 @@
+import type { Deck } from "./schema.ts";
+import type { Position } from "./step.ts";
+
+export type VoiceDict = Record<string, { kana: string; accent?: number }>;
+
+export type Cue = {
+  position: Position;
+  slug: string;
+  line: number;
+  paragraphs: string[];
+};
+
+const FENCE_RE = /^\s*```/;
+const BLOCKQUOTE_RE = /^\s*>/;
+const LIST_RE = /^\s*(?:[-*+]|\d+\.)\s/;
+const TABLE_RE = /^\s*\|/;
+const ASCII_WORD_RE = /[A-Za-z][A-Za-z0-9+.#-]*/g;
+
+export function spokenParagraphs(markdown: string): string[] {
+  const paragraphs: string[] = [];
+  let current: string[] = [];
+  let inFence = false;
+
+  const flush = (): void => {
+    if (current.length === 0) {
+      return;
+    }
+    const text = normalizeSpoken(unwrapInline(current.join("\n")));
+    if (text) {
+      paragraphs.push(text);
+    }
+    current = [];
+  };
+
+  for (const line of markdown.split(/\r?\n/)) {
+    if (FENCE_RE.test(line)) {
+      if (!inFence) {
+        flush();
+      }
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      continue;
+    }
+    if (
+      BLOCKQUOTE_RE.test(line) ||
+      LIST_RE.test(line) ||
+      TABLE_RE.test(line) ||
+      line.trim() === ""
+    ) {
+      flush();
+      continue;
+    }
+    current.push(line);
+  }
+  flush();
+  return paragraphs;
+}
+
+export function applyDict(text: string, dict: VoiceDict): string {
+  const keys = Object.keys(dict).sort((a, b) => b.length - a.length);
+  if (keys.length === 0) {
+    return text;
+  }
+  const pattern = keys.map(dictKeyPattern).join("|");
+  return text.replace(new RegExp(pattern, "g"), (match) => dict[match]?.kana ?? match);
+}
+
+export function unknownAsciiWords(text: string, dict: VoiceDict): string[] {
+  const found: string[] = [];
+  const seen = new Set<string>();
+  for (const match of text.matchAll(ASCII_WORD_RE)) {
+    const word = match[0];
+    if (word.length < 2 || Object.hasOwn(dict, word) || seen.has(word)) {
+      continue;
+    }
+    seen.add(word);
+    found.push(word);
+  }
+  return found;
+}
+
+type CueSource = {
+  position: Position;
+  slug: string;
+  line: number;
+  markdown: string;
+};
+
+/**
+ * One entry per cue: the slide's arrival, spoken from the paragraphs before its first `###`,
+ * then each beat.
+ */
+function cueSources(deck: Deck): CueSource[] {
+  const sources: CueSource[] = [];
+  for (const [slideIndex, section] of deck.sections.entries()) {
+    sources.push({
+      position: { slideIndex, beatIndex: 0 },
+      slug: section.slug,
+      line: section.line,
+      markdown: section.body,
+    });
+    for (const [index, beat] of section.beats.entries()) {
+      sources.push({
+        position: { slideIndex, beatIndex: index + 1 },
+        slug: section.slug,
+        line: beat.line,
+        markdown: beat.body,
+      });
+    }
+  }
+  return sources;
+}
+
+export function cuesFromDeck(deck: Deck, dict: VoiceDict = {}): Cue[] {
+  return cueSources(deck).map((source) => ({
+    position: source.position,
+    slug: source.slug,
+    line: source.line,
+    paragraphs: spokenParagraphs(source.markdown).map((paragraph) => applyDict(paragraph, dict)),
+  }));
+}
+
+export type SilentCue = Pick<CueSource, "position" | "slug" | "line">;
+
+/**
+ * Cues that show something (list, code, table) but say nothing. An empty or
+ * blockquote-only beat is a deliberate pause and is not reported.
+ */
+export function silentCues(deck: Deck): SilentCue[] {
+  return cueSources(deck)
+    .filter(
+      (source) => spokenParagraphs(source.markdown).length === 0 && hasVisibleBody(source.markdown),
+    )
+    .map(({ position, slug, line }) => ({ position, slug, line }));
+}
+
+function hasVisibleBody(markdown: string): boolean {
+  return markdown.split(/\r?\n/).some((line) => line.trim() !== "" && !BLOCKQUOTE_RE.test(line));
+}
+
+function unwrapInline(text: string): string {
+  return text
+    .replace(/!\[[^\]]*]\([^)]*\)/g, "")
+    .replace(/\[([^\]]+)]\([^)]*\)/g, "$1")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/__([^_]+)__/g, "$1")
+    .replace(/(?<![A-Za-z0-9_])\*([^*]+)\*(?![A-Za-z0-9_])/g, "$1")
+    .replace(/(?<![A-Za-z0-9_])_([^_]+)_(?![A-Za-z0-9_])/g, "$1");
+}
+
+function normalizeSpoken(text: string): string {
+  return text
+    .replace(/[ \t]+/g, " ")
+    .replace(/ *\n */g, "\n")
+    .trim();
+}
+
+function dictKeyPattern(key: string): string {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (/^[A-Za-z]/.test(key)) {
+    return `(?<![A-Za-z0-9])${escaped}(?![A-Za-z0-9])`;
+  }
+  return escaped;
+}
+
+const SENTENCE_RE = /(?<=[。！？!?．])\s*|(?<=\.)(?=\s|$)\s*|\n+/;
+const ABBREV_END = /(?:^| )[A-Za-z]{1,3}\.$/;
+
+export function splitSentences(paragraph: string): string[] {
+  const parts = paragraph
+    .split(SENTENCE_RE)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  const merged: string[] = [];
+  for (const part of parts) {
+    const prev = merged.at(-1);
+    if (prev && ABBREV_END.test(prev)) {
+      merged[merged.length - 1] = `${prev} ${part}`;
+    } else {
+      merged.push(part);
+    }
+  }
+  return merged;
+}

package/src/core/deck-paths.ts

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+
+/** The extensions a file under `slides/` can have: the slide, its sidecars, and its build. */
+type SlideExt = ".html" | ".css" | ".ts" | ".js";
+
+/** Where each file a deck is made of lives, named once instead of joined at every read. */
+export type DeckPaths = {
+  dir: string;
+  script: string;
+  theme: string;
+  slides: string;
+  assets: string;
+  voice: string;
+  voiceToml: string;
+  voiceDict: string;
+  /** `slides/<slug><ext>`. */
+  slide(slug: string, ext: SlideExt): string;
+};
+
+export function deckPaths(deckDir: string): DeckPaths {
+  const slides = join(deckDir, "slides");
+  const voice = join(deckDir, "voice");
+  return {
+    dir: deckDir,
+    script: join(deckDir, "script.md"),
+    theme: join(deckDir, "theme.css"),
+    slides,
+    assets: join(deckDir, "assets"),
+    voice,
+    voiceToml: join(voice, "voice.toml"),
+    voiceDict: join(voice, "dict.toml"),
+    slide: (slug, ext) => join(slides, `${slug}${ext}`),
+  };
+}

package/src/core/diagnostic.ts

@@ -0,0 +1,114 @@
+/** An error means the deck is not done; a warning is worth a look but does not fail lint. */
+export type Severity = "error" | "warning";
+
+/**
+ * What a finding is about. A slide finding names its slide (`slug`), and `dekc check <slug>`
+ * reports exactly those; a deck finding is about a file the slides share, such as theme.css
+ * or the frontmatter; a project finding is about dek.toml, one per project however many decks.
+ * `dekc lint` reports all three.
+ */
+export type Scope = "project" | "deck" | "slide";
+
+/**
+ * The rule table: every diagnostic dek itself emits, with its severity and the scopes it is
+ * found in. A rule that reads a shared file and a slide's own, like DEK014 on theme.css and on
+ * slides/<slug>.css, has both. Voice and timing rules are warnings: a live-only deck is done
+ * without them. So are the findings about input dek ignores (DEK008) or reads another way
+ * (DEK044), an empty heading (DEK024), which a slide script may fill, and a step bound by
+ * position where the beat has an id (DEK025), which is right until a beat is inserted, and a
+ * style several slides repeat (DEK026), which works but belongs in the theme. Text under
+ * aria-hidden (DEK029) is right on a sample the talk shows as unreadable.
+ */
+export const RULES = {
+  DEK001: { severity: "error", scopes: ["slide"] },
+  DEK002: { severity: "error", scopes: ["slide"] },
+  DEK003: { severity: "error", scopes: ["slide"] },
+  DEK004: { severity: "error", scopes: ["slide"] },
+  DEK005: { severity: "error", scopes: ["slide"] },
+  DEK006: { severity: "error", scopes: ["slide"] },
+  DEK007: { severity: "error", scopes: ["slide"] },
+  DEK008: { severity: "warning", scopes: ["project", "deck"] },
+  DEK009: { severity: "error", scopes: ["slide"] },
+  DEK010: { severity: "error", scopes: ["slide"] },
+  DEK011: { severity: "error", scopes: ["slide"] },
+  DEK012: { severity: "error", scopes: ["deck", "slide"] },
+  DEK013: { severity: "error", scopes: ["deck"] },
+  DEK014: { severity: "error", scopes: ["deck", "slide"] },
+  DEK015: { severity: "error", scopes: ["deck"] },
+  DEK016: { severity: "error", scopes: ["slide"] },
+  DEK017: { severity: "error", scopes: ["slide"] },
+  DEK018: { severity: "error", scopes: ["deck"] },
+  DEK019: { severity: "error", scopes: ["slide"] },
+  DEK020: { severity: "error", scopes: ["deck", "slide"] },
+  DEK021: { severity: "error", scopes: ["deck", "slide"] },
+  DEK022: { severity: "error", scopes: ["deck", "slide"] },
+  DEK023: { severity: "error", scopes: ["deck", "slide"] },
+  DEK024: { severity: "warning", scopes: ["slide"] },
+  DEK025: { severity: "warning", scopes: ["slide"] },
+  DEK026: { severity: "warning", scopes: ["slide"] },
+  DEK027: { severity: "error", scopes: ["deck"] },
+  DEK028: { severity: "warning", scopes: ["slide"] },
+  DEK029: { severity: "warning", scopes: ["slide"] },
+  DEK030: { severity: "error", scopes: ["slide"] },
+  DEK031: { severity: "error", scopes: ["slide"] },
+  DEK032: { severity: "error", scopes: ["slide"] },
+  DEK033: { severity: "error", scopes: ["slide"] },
+  DEK040: { severity: "warning", scopes: ["slide"] },
+  DEK041: { severity: "warning", scopes: ["deck"] },
+  DEK042: { severity: "warning", scopes: ["slide"] },
+  DEK043: { severity: "warning", scopes: ["deck"] },
+  DEK044: { severity: "warning", scopes: ["deck", "slide"] },
+  DEK045: { severity: "warning", scopes: ["deck"] },
+} as const satisfies Record<string, { severity: Severity; scopes: readonly Scope[] }>;
+
+export type RuleId = keyof typeof RULES;
+
+export type Diagnostic = {
+  id: string;
+  severity: Severity;
+  message: string;
+  path?: string;
+  line?: number;
+  /** 1-based, in UTF-16 units as editors count; set when the rule knows where on the line. */
+  column?: number;
+  slug?: string;
+  /** The fix, phrased as what to do next. */
+  hint?: string;
+  /** The values the message names, such as the offending class or the overflow in px, as fields. */
+  data?: { [key: string]: DiagnosticValue };
+};
+
+export type DiagnosticValue =
+  | string
+  | number
+  | boolean
+  | DiagnosticValue[]
+  | { [key: string]: DiagnosticValue };
+
+export type DiagnosticFields = Omit<Diagnostic, "id" | "severity">;
+
+/** A diagnostic of one dek rule; its severity comes from the rule table. */
+export function diag(id: RuleId, fields: DiagnosticFields): Diagnostic {
+  // Severity right after the id, so it reads first in --json.
+  return { id, severity: RULES[id].severity, ...fields };
+}
+
+/** A diagnostic from outside the rule table, such as rumdl's or a crash: always an error. */
+export function errorDiagnostic(id: string, fields: DiagnosticFields): Diagnostic {
+  return { id, severity: "error", ...fields };
+}
+
+export function hasErrors(diagnostics: Diagnostic[]): boolean {
+  return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}
+
+/**
+ * A check a command did not run, so its empty diagnostics are not a pass for it: why it did not
+ * run, and what to do so that it does.
+ */
+export type SkippedCheck = {
+  /** `preview` is a build's link preview image, which needs a URL and Playwright. */
+  check: "lint" | "preview" | "rumdl" | "visual" | "voice";
+  reason: string;
+  hint?: string;
+};

package/src/core/document.ts

@@ -0,0 +1,218 @@
+import { readTheme } from "./assets.ts";
+import { playerChromeCss } from "./chrome.ts";
+import { type DekConfig, loadConfig } from "./config.ts";
+import { escapeAttr, escapeHtml } from "./escape.ts";
+import { collectSlidesHtml, htmlShell } from "./html.ts";
+import { type OgpImage, ogpHead } from "./ogp.ts";
+import { PAGE_ID, type PageMode, pageConfigAttrs } from "./page.ts";
+import {
+  nextPresenterTitle,
+  presenterSlides,
+  presenterState,
+  type ScriptReader,
+} from "./presenter.ts";
+import { RAIL_WIDTH_DEFAULT, RAIL_WIDTH_MAX, RAIL_WIDTH_MIN } from "./rail-width.ts";
+import { type ProjectDeck, resolveDeck } from "./resolve.ts";
+import { logicalSize } from "./size.ts";
+import { readSlideScripts, slideScriptTags } from "./slide-script.ts";
+import { formatClock } from "./timing.ts";
+
+/** Who the page is for; each decides what else the page carries. */
+export type PageTarget =
+  /** The dev server's page: assets by URL, live reload, and the presenter's notes when allowed. */
+  | {
+      kind: "dev";
+      mode: "player" | "presenter";
+      includeNotes: boolean;
+      liveReloadScript: string;
+      /**
+       * What a presenter page sends as `?token=` on its live channels at `/decks/<name>/events`
+       * and `/decks/<name>/ws`: neither an EventSource nor a WebSocket can set a header of its
+       * own. An audience page never carries one.
+       */
+      liveToken?: string;
+    }
+  /** `dekc build`: one file that stands alone, shared as a link. */
+  | {
+      kind: "build";
+      /** Built with `--public`, for anyone who has the link rather than the speaker. */
+      public?: boolean;
+      /** The built page's absolute URL, for og:url. */
+      publicUrl?: string;
+      /** The first slide's picture, for og:image. */
+      previewImage?: OgpImage;
+    }
+  /** `dekc video`: one file that stands alone, every slide and nothing around them. */
+  | { kind: "video" };
+
+/** The deck at `dir`, rendered for `target`. */
+export function renderDeckHtml(
+  dir: string,
+  options: { playerScript: string; target: PageTarget },
+): string {
+  const { project, deck } = resolveDeck(dir);
+  return renderDeckDocument(deck, { ...options, config: loadConfig(project.configPath) });
+}
+
+export function renderDeckDocument(
+  deck: ProjectDeck,
+  options: { config: DekConfig; playerScript: string; target: PageTarget },
+): string {
+  const { target } = options;
+  const mode: PageMode =
+    target.kind === "dev" ? target.mode : target.kind === "build" ? "player" : "video";
+  const live = target.kind === "dev";
+  // A file that stands alone carries its assets and a minified theme; the dev server serves
+  // assets by URL. A build skips a broken slide script, as the dev server does, since lint never
+  // stops a build and its findings name the script. A video has no findings to carry the news, and
+  // hours of rendering would show slides without their motion, so a broken script stops it.
+  const standalone = !live;
+  const strictScripts = target.kind === "video";
+  const includeNotes = target.kind === "dev" ? target.includeNotes : target.kind === "build";
+  const data = presenterSlides(deck, options.config, scriptReader(target)).map((slide) =>
+    includeNotes ? slide : { ...slide, script: "" },
+  );
+  const slidesHtml = collectSlidesHtml(deck, { inline: standalone });
+  const themeCss = readTheme(deck.dir, standalone);
+  const slideScripts = readSlideScripts(deck.dir, { strict: strictScripts });
+  const state = data[0] ? presenterState(data, { slideIndex: 0, beatIndex: 0 }) : undefined;
+  const budget = data[0]?.budgetSeconds !== undefined ? formatClock(data[0].budgetSeconds) : "";
+  const size = logicalSize(deck.deck.ratio);
+  const presenterOpen = mode === "presenter";
+  const hidden = presenterOpen ? "" : " hidden";
+  const nextTitle = state ? nextPresenterTitle(state) : "";
+  const atEnd = Boolean(state) && nextTitle === "" && !state?.next;
+  const page = data.length > 0 ? `1 <span class="dek-page-total">/ ${data.length}</span>` : "";
+  const progress = includeNotes ? `<div id="${PAGE_ID.progress}"${hidden}></div>` : "";
+  const presenter = includeNotes
+    ? `<aside id="${PAGE_ID.presenter}"${hidden}>
+    <section id="${PAGE_ID.nextPanel}">
+      <div class="dek-panel-label">Next</div>
+      <div class="dek-next-body">
+        <div id="${PAGE_ID.nextStage}"></div>
+        <p id="${PAGE_ID.nextEnd}"${atEnd ? "" : " hidden"}>End</p>
+      </div>
+      <p id="${PAGE_ID.next}">${escapeHtml(nextTitle)}</p>
+    </section>
+    <section id="${PAGE_ID.notesPanel}">
+      <ol id="${PAGE_ID.beats}">
+      ${(state?.current.beats ?? [])
+        .map((beat, index) => `<li data-beat-index="${index + 1}">${escapeHtml(beat.title)}</li>`)
+        .join("")}
+    </ol>
+      <pre id="${PAGE_ID.script}">${escapeHtml(state?.script ?? "")}</pre>
+    </section>
+    <footer id="${PAGE_ID.presenterBar}">
+      <span id="${PAGE_ID.page}">${page}</span>
+      <p id="${PAGE_ID.elapsed}">0:00</p>
+      <p id="${PAGE_ID.budget}">${budget}</p>
+      ${target.kind === "dev" ? markButton(deck.deck.lang) : ""}
+      <button id="${PAGE_ID.laserToggle}" type="button" aria-pressed="false" aria-label="${escapeAttr(laserLabel(deck.deck.lang))}" title="${escapeAttr(laserLabel(deck.deck.lang))}"></button>
+    </footer>
+  </aside>`
+    : "";
+  const currentLabel = includeNotes ? `<div class="dek-panel-label">Current</div>` : "";
+  const rail = target.kind === "video" ? "" : renderRailHtml(data);
+  const hint = target.kind === "build" ? renderKeyHintHtml(deck.deck.lang) : "";
+  const railResize = rail
+    ? `<div id="${PAGE_ID.railResize}" role="separator" aria-orientation="vertical" aria-label="Resize slide list" aria-valuemin="${RAIL_WIDTH_MIN}" aria-valuemax="${RAIL_WIDTH_MAX}" aria-valuenow="${RAIL_WIDTH_DEFAULT}" tabindex="0"></div>`
+    : "";
+
+  const ogp =
+    target.kind === "build"
+      ? `${ogpHead({
+          title: deck.deck.title,
+          description: deck.deck.description,
+          event: deck.deck.event,
+          date: deck.deck.date,
+          lang: deck.deck.lang,
+          url: target.publicUrl,
+          image: target.previewImage,
+        })}
+  `
+      : "";
+  const liveToken = target.kind === "dev" ? target.liveToken : undefined;
+
+  return htmlShell({
+    lang: deck.deck.lang,
+    title: deck.deck.title,
+    head: `${ogp}<style>${playerChromeCss({ presenter: includeNotes, ...size })}</style>
+  <style data-dek-theme>${themeCss}</style>`,
+    bodyAttrs: `${presenterOpen ? ' class="is-presenter"' : ""}${pageConfigAttrs({
+      mode,
+      deck: deck.name,
+      live,
+      ...(liveToken ? { liveToken } : {}),
+    })}`,
+    body: `${progress}
+  <div id="${PAGE_ID.shell}">
+    ${rail}
+    <main id="${PAGE_ID.current}">
+      ${currentLabel}
+      <div id="${PAGE_ID.currentStage}"><div id="${PAGE_ID.deck}">${slidesHtml}</div></div>
+    </main>
+    ${presenter}
+  </div>
+  ${railResize}
+  ${hint}
+  <div id="${PAGE_ID.announce}" aria-live="polite"></div>
+  <script type="application/json" id="${PAGE_ID.data}">${jsonForScript(data)}</script>
+  ${slideScriptTags(slideScripts)}
+  <script>${options.playerScript}</script>
+  ${target.kind === "dev" ? `<script>${target.liveReloadScript}</script>` : ""}`,
+  });
+}
+
+/**
+ * A page built with `--public` is for anyone who has the link, so it carries the script as the
+ * audience may read it; any other page is the speaker's own. A URL alone says where the page is
+ * served, not who reads it: the speaker may present from that very page.
+ */
+function scriptReader(target: PageTarget): ScriptReader {
+  return target.kind === "build" && target.public === true ? "audience" : "speaker";
+}
+
+export function renderRailHtml(slides: Array<{ slug: string; title: string }>): string {
+  const items = slides
+    .map((slide, index) => {
+      const n = index + 1;
+      const label = `${n}. ${slide.title}`;
+      return `<a class="dek-thumb" href="#${escapeAttr(slide.slug)}" data-slide-index="${index}" aria-label="${escapeAttr(label)}"><span class="dek-thumb-num">${n}</span><span class="dek-thumb-frame"></span></a>`;
+    })
+    .join("");
+  return `<nav id="${PAGE_ID.rail}" aria-label="Slides">${items}</nav>`;
+}
+
+const KEY_HINT_LABELS = {
+  ja: { rail: "スライド一覧", presenter: "発表者ビュー" },
+  en: { rail: "Slide rail", presenter: "Presenter view" },
+};
+
+/**
+ * The button that marks the beat on screen to rewrite. Only the dev server's page has it: the
+ * marks go to a file of the project's, and a built file has no server to keep them.
+ */
+function markButton(lang: string): string {
+  const label = lang.toLowerCase().startsWith("ja")
+    ? "このビートに直す印を付ける (m)"
+    : "Mark this beat to rewrite (m)";
+  return `<button id="${PAGE_ID.markToggle}" type="button" aria-pressed="false" aria-label="${escapeAttr(label)}" title="${escapeAttr(label)}"></button>`;
+}
+
+/** The laser button's name, with the key that does the same. */
+function laserLabel(lang: string): string {
+  return lang.toLowerCase().startsWith("ja") ? "レーザーポインター (l)" : "Laser pointer (l)";
+}
+
+/**
+ * The keys a viewer of a built file cannot discover by looking: `s` and `p`. Shown once as
+ * the file opens, it fades on its own and goes away at the first key or move.
+ */
+function renderKeyHintHtml(lang: string): string {
+  const labels = lang.toLowerCase().startsWith("ja") ? KEY_HINT_LABELS.ja : KEY_HINT_LABELS.en;
+  return `<div id="${PAGE_ID.hint}" role="status"><span><kbd>s</kbd>${labels.rail}</span><span><kbd>p</kbd>${labels.presenter}</span></div>`;
+}
+
+function jsonForScript(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}

package/src/core/error.ts

@@ -0,0 +1,31 @@
+export class DekError extends Error {
+  readonly line?: number;
+  readonly path?: string;
+  readonly hint?: string;
+
+  constructor(
+    message: string,
+    options?: { line?: number; path?: string; hint?: string; cause?: unknown },
+  ) {
+    super(message, { cause: options?.cause });
+    this.name = "DekError";
+    this.line = options?.line;
+    this.path = options?.path;
+    this.hint = options?.hint;
+  }
+}
+
+/** What a thrown value says, as plain fields: a DekError keeps its location and hint. */
+export type ErrorFields = { message: string; path?: string; line?: number; hint?: string };
+
+export function errorFields(error: unknown): ErrorFields {
+  if (error instanceof DekError) {
+    return {
+      message: error.message,
+      ...(error.path !== undefined ? { path: error.path } : {}),
+      ...(error.line !== undefined ? { line: error.line } : {}),
+      ...(error.hint !== undefined ? { hint: error.hint } : {}),
+    };
+  }
+  return { message: error instanceof Error ? error.message : String(error) };
+}

package/src/core/escape.ts

@@ -0,0 +1,16 @@
+export function escapeHtml(text: string): string {
+  return text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+export function escapeAttr(text: string): string {
+  return escapeHtml(text);
+}
+
+/** `text` matched literally inside a regular expression. */
+export function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}