@jokerized/decksmith 0.1.0

package/dist/server/upload.js

@@ -0,0 +1,232 @@
+import { posix, sep } from "node:path";
+import { unzipSync } from "fflate";
+const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+const ZIP_LIMITS = {
+  maxEntries: 500,
+  maxTotalBytes: 200 * 1024 * 1024,
+  maxEntryBytes: 64 * 1024 * 1024
+};
+const MARKDOWN_EXTS = [".md", ".markdown", ".txt"];
+class UploadError extends Error {
+  hint;
+  status;
+  constructor(message, hint, status = 400) {
+    super(message);
+    this.name = "UploadError";
+    this.hint = hint;
+    this.status = status;
+  }
+}
+const GRACE = 4;
+function readBody(req, limit = MAX_UPLOAD_BYTES) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let refused = false;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (refused) {
+        if (size > limit * GRACE) req.destroy();
+        return;
+      }
+      if (size > limit) {
+        refused = true;
+        chunks.length = 0;
+        reject(
+          new UploadError(
+            `Upload is larger than ${Math.round(limit / 1024 / 1024)} MB.`,
+            "Send the markdown on its own, or a zip holding only the document and the figures it cites.",
+            413
+          )
+        );
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (!refused) resolve(Buffer.concat(chunks));
+    });
+    req.on("error", (err) => {
+      if (!refused) reject(err);
+    });
+  });
+}
+async function parseMultipart(body, contentType) {
+  if (!/^multipart\/form-data\s*;/i.test(contentType)) {
+    throw new UploadError(
+      "This endpoint takes a multipart/form-data upload.",
+      'Post a form with a "file" part holding the document, e.g. `curl -F file=@paper.md`.',
+      415
+    );
+  }
+  let form;
+  try {
+    const view = new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    form = await new Response(view, { headers: { "content-type": contentType } }).formData();
+  } catch {
+    throw new UploadError(
+      "The multipart body could not be parsed.",
+      "Let your HTTP client set the Content-Type and boundary rather than writing them by hand."
+    );
+  }
+  const fields = {};
+  let file;
+  form.forEach((value, key) => {
+    if (typeof value === "string") {
+      fields[key] = value;
+      return;
+    }
+    if (key === "file") file = value;
+  });
+  if (!file) {
+    throw new UploadError(
+      'The upload has no "file" part.',
+      'Name the document part "file" \u2014 .md, .markdown, .txt, or a .zip containing one.'
+    );
+  }
+  if (file.size === 0) {
+    throw new UploadError(
+      `"${file.name || "the uploaded file"}" is empty.`,
+      "Check the path you gave your client; an empty part usually means the file was not found."
+    );
+  }
+  return {
+    filename: file.name || "upload",
+    bytes: new Uint8Array(await file.arrayBuffer()),
+    fields
+  };
+}
+function looksLikeZip(bytes) {
+  return bytes.length >= 4 && bytes[0] === 80 && bytes[1] === 75;
+}
+function safeEntryPath(name) {
+  if (name.includes("\0")) return null;
+  const segments = name.replace(/\\/g, "/").split("/");
+  if (/^[a-zA-Z]:/.test(name) || name.startsWith("/") || name.startsWith("\\")) return null;
+  const kept = [];
+  for (const segment of segments) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") return null;
+    kept.push(segment);
+  }
+  if (kept.length === 0) return null;
+  const path = kept.join("/");
+  if (path.length > 512 || kept.some((s) => s.length > 200)) return null;
+  return path;
+}
+function insideRoot(root, joined) {
+  return joined === root || joined.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+function readZip(bytes, limits = ZIP_LIMITS) {
+  const seen = [];
+  try {
+    unzipSync(bytes, {
+      filter: (f) => {
+        seen.push({ name: f.name, originalSize: f.originalSize });
+        return false;
+      }
+    });
+  } catch {
+    throw new UploadError(
+      "That file starts like a zip but could not be read as one.",
+      "Re-create the archive \u2014 a truncated download and a renamed .rar both look like this."
+    );
+  }
+  const warnings = [];
+  const approved = /* @__PURE__ */ new Map();
+  let total = 0;
+  for (const entry of seen) {
+    if (entry.name.endsWith("/")) continue;
+    if (isNoise(entry.name)) continue;
+    const safe = safeEntryPath(entry.name);
+    if (safe === null) {
+      throw new UploadError(
+        `The archive contains an entry that tries to escape its directory: "${entry.name}".`,
+        "Re-zip from inside the folder so every path is relative and none of them start with / or contain .."
+      );
+    }
+    if (entry.originalSize > limits.maxEntryBytes) {
+      throw new UploadError(
+        `"${entry.name}" unpacks to ${mb(entry.originalSize)}, over the ${mb(limits.maxEntryBytes)} per-file limit.`,
+        "Leave the large file out; a deck reads the document and its figures, not the dataset."
+      );
+    }
+    total += entry.originalSize;
+    if (total > limits.maxTotalBytes) {
+      throw new UploadError(
+        `The archive unpacks to more than ${mb(limits.maxTotalBytes)}.`,
+        "Send only the document and the figures it cites."
+      );
+    }
+    if (approved.size >= limits.maxEntries) {
+      throw new UploadError(
+        `The archive holds more than ${limits.maxEntries} files.`,
+        "Send only the document and the figures it cites."
+      );
+    }
+    approved.set(entry.name, safe);
+  }
+  if (approved.size === 0) {
+    throw new UploadError(
+      "The archive is empty.",
+      "Zip the folder that holds your markdown, not an empty one."
+    );
+  }
+  const raw = unzipSync(bytes, { filter: (f) => approved.has(f.name) });
+  const files = {};
+  let actual = 0;
+  for (const [name, safe] of approved) {
+    const data = raw[name];
+    if (!data) continue;
+    actual += data.length;
+    if (actual > limits.maxTotalBytes) {
+      throw new UploadError(
+        `The archive unpacks to more than ${mb(limits.maxTotalBytes)}.`,
+        "Send only the document and the figures it cites."
+      );
+    }
+    if (files[safe]) warnings.push(`two entries both unpack to ${safe}; kept the last`);
+    files[safe] = data;
+  }
+  return { files, warnings };
+}
+function pickMarkdown(files) {
+  const candidates = Object.keys(files).filter(
+    (p) => MARKDOWN_EXTS.includes(posix.extname(p).toLowerCase())
+  );
+  if (candidates.length === 0) {
+    throw new UploadError(
+      `The archive has no ${MARKDOWN_EXTS.join(", ")} file in it.`,
+      "DeckSmith reads a markdown document. Add the .md next to your figures and zip the folder again."
+    );
+  }
+  const rank = (p) => {
+    const base = posix.basename(p).toLowerCase();
+    const named = /^(readme|index|main|paper|analysis)\./.test(base) ? 0 : 1;
+    return [p.split("/").length, named, p];
+  };
+  return candidates.sort((a, b) => {
+    const [da, na, pa] = rank(a);
+    const [db, nb, pb] = rank(b);
+    return da - db || na - nb || pa.localeCompare(pb);
+  })[0];
+}
+function isNoise(name) {
+  return name.startsWith("__MACOSX/") || name.includes("/__MACOSX/") || posix.basename(name) === ".DS_Store" || posix.basename(name) === "Thumbs.db";
+}
+function mb(bytes) {
+  return `${Math.round(bytes / 1024 / 1024)} MB`;
+}
+export {
+  MARKDOWN_EXTS,
+  MAX_UPLOAD_BYTES,
+  UploadError,
+  ZIP_LIMITS,
+  insideRoot,
+  looksLikeZip,
+  parseMultipart,
+  pickMarkdown,
+  readBody,
+  readZip,
+  safeEntryPath
+};

package/dist/types/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/deck/runtime.d.ts

@@ -0,0 +1,59 @@
+/** One entry of the slideshow island's `slides` array. */
+export interface SlideSpec {
+    sceneId: string;
+    /** Absolute seconds. Present when the island lives outside the composition. */
+    startTime?: number;
+    endTime?: number;
+    /** Absolute positions on the deck timeline, inside this slide's window. */
+    fragments?: number[];
+    notes?: string;
+}
+export interface Stop {
+    /** Absolute position on the deck timeline, in seconds. */
+    t: number;
+    /** 0-based, over the slides that could be placed. */
+    slide: number;
+    /** 0 is the slide itself; 1..n are its fragments in time order. */
+    fragment: number;
+    notes: string;
+    /**
+     * The scene this stop belongs to. Carried through because it is the only id
+     * shared with the narration island — `slide` is a position over the slides we
+     * could place, which shifts the moment one of them is unplaceable.
+     */
+    sceneId: string;
+}
+export interface Pos {
+    slide: number;
+    fragment: number;
+}
+/**
+ * Flatten the island into the ordered list of positions a presenter steps
+ * through: each slide's start, then each of its fragments.
+ *
+ * Placement comes from the island alone. This code only ever runs in the wrapper
+ * page, where the scene divs are inside the player's iframe and unreachable — so
+ * `emitIsland` always writes `startTime`/`endTime`, and there is nothing to
+ * scrape from the DOM.
+ */
+export declare function buildStops(slides: readonly SlideSpec[]): Stop[];
+export interface TransitionPlan {
+    animate: boolean;
+    /** Wall-clock milliseconds to spend. 0 whenever `animate` is false. */
+    durationMs: number;
+}
+/**
+ * Decide whether a step plays or cuts. Pure, so the policy is testable without
+ * a DOM; the rAF loop that obeys it is not.
+ */
+export declare function planTransition(fromT: number, toT: number, opts?: {
+    reducedMotion?: boolean;
+}): TransitionPlan;
+/** `#3` is slide 3; `#3.2` is slide 3, second fragment. Both 1-based. */
+export declare function formatHash(pos: Pos): string;
+export declare function parseHash(hash: string): Pos | null;
+/**
+ * Index of `pos` in the stop list. A deep link that names a fragment we no
+ * longer emit falls back to its slide rather than to nothing.
+ */
+export declare function findStop(stops: readonly Stop[], pos: Pos): number;

package/dist/types/deck/subtitles.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The narration island, and the two questions the presented deck asks of it.
+ *
+ * A narrated deck carries a second JSON island beside the slideshow one: same
+ * page, same shape of thing, different reader. It is separate rather than folded
+ * into the slideshow manifest because that manifest is HyperFrames' format, not
+ * ours — adding a key to it is a bet on a schema someone else owns.
+ *
+ * Everything here is pure, and deliberately so. Playback is untestable without a
+ * browser; "which cue is on screen at t" and "which segment belongs to this
+ * stop" are the parts that can actually be wrong, so they live apart from the
+ * audio element and are tested directly.
+ *
+ * Read defensively throughout. A deck built before narration existed has no
+ * island at all, and a deck built by a newer emitter may carry fields this
+ * reader has never heard of; neither may do anything worse than fall silent.
+ */
+/** Selector for the island. Not `+json` alone — the slideshow one is that too. */
+export declare const NARRATION_ISLAND = "script[type=\"application/decksmith-narration+json\"]";
+/** One subtitle line, in seconds from the start of its own segment's audio. */
+export interface Cue {
+    start: number;
+    end: number;
+    text: string;
+}
+/**
+ * What is spoken at one stop.
+ *
+ * `stop` matches `Stop.fragment`: 0 is the slide's landing, 1..n its reveals.
+ * The contract's `seconds` is not read here — the audio element's own clock is
+ * the authority, and a measured number we then ignore is a number that can drift
+ * out of agreement with the file without anything noticing.
+ */
+export interface Segment {
+    stop: number;
+    /** Resolved against `Narration.dir`; see `audioSrc`. */
+    audio: string;
+    cues: Cue[];
+}
+export interface Narration {
+    voice: string;
+    /** Directory the segment paths hang off, relative to the deck page. May be "". */
+    dir: string;
+    /** Keyed by scene id — `s1`, `s2` — the same ids the slideshow island carries. */
+    scenes: Record<string, Segment[]>;
+}
+/**
+ * The longest cue we will put on screen at once: two lines of about 42
+ * characters, which is broadcast practice and roughly what the band's width
+ * gives at its clamped font size.
+ *
+ * edge-tts emits one cue per SENTENCE, and a long sentence produces a long cue —
+ * 121 characters on a single wrapped block was measured on the demo deck. That
+ * is three lines, and three lines is a band tall enough to cover the bottom of
+ * the slide however much room the composition reserves. Capping here rather than
+ * at synthesis time means a deck built before this existed is fixed by reloading
+ * it, without re-narrating anything.
+ */
+export declare const CUE_MAX_CHARS = 84;
+/**
+ * One cue, wrapped to at most `max` characters a piece, with the original
+ * duration divided between the pieces in proportion to their length.
+ *
+ * Proportional rather than equal because the reading time a chunk needs tracks
+ * its length, and because the speech under it does too — the split lands close
+ * to where the voice actually is. A word longer than `max` becomes its own
+ * piece rather than being broken mid-word.
+ *
+ * EVEN, not greedy. Packing straight to `max` fills the first piece and dumps
+ * whatever is left into the last one, and the duration split is proportional,
+ * so a 90-character cue came out as an 84-character caption followed by a
+ * SINGLE WORD on screen for 0.3 seconds. Six of the demo deck's forty-nine cues
+ * flashed a one-word caption that way — under every broadcast minimum, and
+ * clearly wrong the moment anyone watched the video. So the piece COUNT is
+ * decided first, from `max`, and then the narrowest width that still fits in
+ * that many pieces does the packing: same number of captions, no orphan.
+ */
+export declare function splitCue(cue: Cue, max?: number): Cue[];
+/**
+ * Parse the island's text. Anything malformed reads as "no narration", which is
+ * the deck we shipped yesterday and is always a safe answer.
+ */
+export declare function parseNarration(text: string | null | undefined): Narration | null;
+/**
+ * The cue on screen at `t`, or null in a gap.
+ *
+ * Half-open: `[start, end)`. A cue ending exactly where the next begins must
+ * hand over cleanly, and closing both ends would put two lines on screen for one
+ * frame at every sentence boundary — which is every boundary edge-tts emits.
+ */
+export declare function activeCue(cues: readonly Cue[], t: number): Cue | null;
+/** The segment spoken at one stop, or null where the deck is silent. */
+export declare function segmentFor(narration: Narration | null, sceneId: string, stop: number): Segment | null;
+/**
+ * Where the segment's audio actually lives, relative to the deck page.
+ *
+ * `dir` is a convenience so the emitter can write bare filenames; a segment path
+ * that is already absolute or already a URL is left exactly as it is, because
+ * prefixing one would break a deck whose audio is hosted rather than baked.
+ */
+export declare function audioSrc(narration: Narration, segment: Segment): string;

package/dist/types/emit/archetypes/annotated-figure.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The source's own figure, with the explanation drawn onto it.
+ *
+ * `claim-figure` parks a screenshot beside a sentence and leaves the viewer to
+ * find the part being talked about. This archetype removes that search: each
+ * note is a dot on the exact pixel, a leader out to the nearest margin, and a
+ * label sitting on a coloured rule — revealed one at a time, so the figure is
+ * read in the order the argument needs rather than all at once.
+ *
+ * `notes[].x/y` are fractions of the figure, never pixels, so the overlay is
+ * solved in the figure's own space and stays correct at any layout size. That is
+ * only true if the displayed image box is known exactly, which is why the `<img>`
+ * gets explicit pixel dimensions derived here rather than `max-width:100%`: a box
+ * the browser chooses is a box this file cannot annotate.
+ *
+ * Margins either side of the figure is a landscape idea. In portrait two of them
+ * cost two thirds of an 860px stage, and the demo's figure came out 232px wide —
+ * a postage stamp in a tall black frame, which is the one thing a slide whose
+ * whole subject is a figure may not be. So portrait puts the figure across the
+ * full width and stacks the labels underneath it in two columns instead. The
+ * device is unchanged either way: a dot on the pixel, a leader out to a rule, and
+ * the label sitting on it. Only which way "out" points has moved.
+ */
+import type { Format } from "../../types.js";
+import type { Emitter } from "../kit.js";
+import type { Box, Pt } from "../svg.js";
+export interface FigureNote {
+    x: number;
+    y: number;
+    text: string;
+}
+export interface NoteBox {
+    /** Which margin this label was given. */
+    side: "l" | "r";
+    lines: string[];
+    /**
+     * Stage-space x of the rule's inner end — the one the leader arrives at, with
+     * the label running outward from it.
+     *
+     * Solved here rather than in the emitter because it is the one number the two
+     * arrangements disagree about: beside the plate in landscape, either side of
+     * the centre channel under the figure in portrait.
+     */
+    inner: number;
+    /** Widest line — also the length of the rule the label sits on. */
+    w: number;
+    h: number;
+    /** Stage-space top of the text block. */
+    top: number;
+    /** Stage-space y of the rule, where the leader arrives from the dot. */
+    ruleY: number;
+    /** The annotated point, in stage space. */
+    at: Pt;
+    clipped: boolean;
+}
+export interface FigureLayout {
+    /** The image box in stage space. The plate is this grown by `PLATE` a side. */
+    img: Box;
+    /** Width available to a label in either margin. */
+    col: number;
+    /**
+     * What the stage actually needs, which is at most the budget it was solved
+     * against. A 4:1 strip uses 230px of a 726px budget, and a stage left at the
+     * budget puts a 250px dead band above and below the only thing on the slide.
+     */
+    height: number;
+    boxes: NoteBox[];
+    /** False when a label had to be clipped or a stack had to overlap. */
+    ok: boolean;
+}
+/**
+ * Size the figure and place its labels.
+ *
+ * Exported because this is the one thing here that can be wrong without looking
+ * wrong in a diff: a label half a pixel past the stage, or two overlapping in a
+ * stack, is a property worth asserting directly rather than through rendered SVG.
+ */
+export declare function planFigure(stageW: number, notes: FigureNote[], fig: {
+    width: number;
+    height: number;
+}, stageH: number, tall?: boolean): FigureLayout;
+/**
+ * Height the stage may spend, once the chrome and the caption have taken theirs.
+ * A budget, not a size — `planFigure` gives back only what it used.
+ *
+ * TAKES THE HEADLINE, because the chrome's height is a fact about the headline.
+ * This charged a flat `HEAD_H` — one line — however many the headline wrapped to,
+ * so a three-line headline went 174px unaccounted and pushed the stage down
+ * until the caption rendered 81px BELOW the canvas and a note's second line 41px
+ * below. `chromeHeight` is the same measurement every other archetype makes.
+ *
+ * AND IT NO LONGER FLOORS AT 360, which was the same fix half-made. Charging the
+ * headline correctly stopped the caption falling off the canvas and left it
+ * being CRUSHED instead: under a three-line headline the honest remainder is
+ * 299px, the floor handed back 360, the stage took 345 of it, and `.af-cap` —
+ * a flex child that may shrink — was squeezed to a 1.7px box with
+ * `-webkit-line-clamp` quietly eating the text. `clipped_text` and
+ * `text_box_overflow`, on a slide whose provenance line is invisible. A floor
+ * that reports more room than exists does not create room; it only moves which
+ * gate notices.
+ */
+export declare function stageBudget(format: Format, eyebrow: string | undefined, headline: string, caption: string): number;
+export declare const annotatedFigure: Emitter<"annotated-figure">;

package/dist/types/emit/archetypes/bar-compare.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Magnitudes, drawn.
+ *
+ * A table of figures makes the viewer do arithmetic: "1.592 against 0.930" is two
+ * numbers and a subtraction. The same pair as two bars is one glance. So nothing
+ * here is decoration — the bar lengths carry the entire claim, which is why the
+ * scale is derived from the data and anchored at zero. A bar chart whose baseline
+ * is not zero is a chart that asserts a ratio the numbers do not support, and it
+ * would pass every gate we have.
+ *
+ * Three decisions worth knowing before changing anything:
+ *
+ * 1. Every bar sits in a full-width rail. The rail is what makes a dwarfed bar
+ *    legible (see MIN_LEN) — the eye reads "almost none of the extent" rather
+ *    than "nothing was drawn".
+ * 2. Values count up rather than fade in, and they count on the same decimal grid
+ *    their printed string is on, so the number GSAP lands on is byte-identical to
+ *    the one in the static SVG.
+ * 3. The bars are one reveal, not N. Holding on bar 3 of 8 asks the viewer to
+ *    compare it against bars that have not been drawn yet.
+ *
+ * A label gutter beside the rails is a landscape idea. At 9:16 the demo's five
+ * names took 340px of an 860px box, so 40% of the width was spent naming bars
+ * that then had 60% left to differ in. Portrait puts the label on its own line
+ * above the rail instead and hands the whole width to the comparison — which is
+ * also where the height it needs comes from, since portrait has height to spare
+ * and width it does not.
+ */
+import type { Emitter } from "../kit.js";
+export declare const barCompare: Emitter<"bar-compare">;

package/dist/types/emit/archetypes/callout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Labelled panels side by side — the archetype for the things a paper does not
+ * put in a figure: a contradiction between two tables, a caveat, a limit on what
+ * was actually tested. Panels appear one at a time so each can be spoken to.
+ */
+import type { Emitter } from "../kit.js";
+export declare const callout: Emitter<"callout">;

package/dist/types/emit/archetypes/claim-figure.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A claim from the source, shown next to the figure that backs it.
+ *
+ * The layout is chosen from the figure's own aspect ratio rather than being a
+ * parameter: EXPERIMENT-002 full-bled a 1.98-aspect figure and pushed its
+ * caption 200px off-canvas. Only a genuine strip earns the full width.
+ */
+import type { Emitter } from "../kit.js";
+export declare const claimFigure: Emitter<"claim-figure">;

package/dist/types/emit/archetypes/data-table.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A table from the source, revealed row by row, then read for the viewer: the
+ * highlighted rows light up in the order the argument needs them.
+ *
+ * Nothing here invents numbers, and nothing here drops them either: every row of
+ * the named table is drawn, at 40px or above, or the beat is refused. The type
+ * is solved from the WIDTH — upwards from the 40px floor, capped — and the height
+ * rule then asks whether those rows, drawn at that size, fit on the canvas. The
+ * one lever the height rule owns is the row padding, and it is already shut to
+ * `PAD_Y_MIN` whenever this refuses, so "will not fit" is a measurement of this
+ * slide rather than a preference about it.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: buy rows by taking the type back down toward
+ * 40. That would be legal — invariant 5 is a floor, not a fixed size, and a table
+ * declined here at 52px would often fit at 40 — but it makes `cell` solve two
+ * constraints at once, and the width solve is the one that has been measured. So
+ * the refusal names the size it refused AT, and the choice stays visible to
+ * whoever reads the error instead of being buried in this file.
+ */
+import type { Emitter } from "../kit.js";
+export declare const dataTable: Emitter<"data-table">;

package/dist/types/emit/archetypes/equation-walk.d.ts

@@ -0,0 +1,2 @@
+import type { Emitter } from "../kit.js";
+export declare const equationWalk: Emitter<"equation-walk">;

package/dist/types/emit/archetypes/grid.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A field, and the windows that move over it.
+ *
+ * Attention spans, receptive fields, patches, pooling kernels, token sequences —
+ * every paper draws these as a rectangle over a lattice, and every slide deck
+ * then writes "8x8 shifted windows" in a bullet and calls it explained. The
+ * content of the idea is *which cells* and *how many of them*, and a sentence
+ * cannot show that; a lattice with the rectangle lit on it shows nothing else.
+ *
+ * Everything here is solved from the box that is actually free after the chrome
+ * and the note, so a 24x16 feature map and a 2x1 pair of patches are the same
+ * code. A constant cell size would be right for one grid and wrong for the other
+ * twenty-three, and nobody would ever find out which.
+ */
+import type { Emitter } from "../kit.js";
+export declare const grid: Emitter<"grid">;

package/dist/types/emit/archetypes/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The explanatory vocabulary, indexed by archetype.
+ *
+ * The mapped type is the point: adding an archetype to `Beat` without an emitter
+ * beside it fails to compile, which is the only guarantee that keeps the union in
+ * `types.ts` honest.
+ */
+import type { Archetype, Beat } from "../../types.js";
+import type { EmitContext, Emitter, Scene } from "../kit.js";
+export declare const emitters: {
+    [A in Archetype]: Emitter<A>;
+};
+/**
+ * Dispatch a beat to its emitter. The cast is the one place the pairing is taken
+ * on trust: `emitters[beat.archetype]` is a union of twelve emitters and TypeScript
+ * will not narrow the key and the beat together. The table above already proves
+ * every archetype has exactly one emitter of the right shape.
+ */
+export declare function emitScene(beat: Beat, ctx: EmitContext): Scene;

package/dist/types/emit/archetypes/line-chart.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A chart the source never drew.
+ *
+ * Papers report sweeps as tables and leave the shape of the curve to the reader.
+ * Drawing it is the whole point of this archetype, so everything here is derived
+ * from the data — the scale especially. A hardcoded axis is how a chart ends up
+ * asserting something the numbers do not.
+ */
+import type { Emitter } from "../kit.js";
+export interface Scale {
+    min: number;
+    max: number;
+    step: number;
+    decimals: number;
+}
+/**
+ * A round-numbered scale that provably contains every value. Exported because
+ * "the axis spans the data" is the one property a chart must never get wrong,
+ * and it is worth asserting directly rather than through rendered SVG.
+ */
+export declare function chartScale(values: number[]): Scale;
+export declare const lineChart: Emitter<"line-chart">;