@jokerized/decksmith 0.3.1 → 0.4.0

package/dist/types/deck/player-element.d.ts

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

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

@@ -0,0 +1,37 @@
+/** One stop, as a host sees it. */
+export interface PlayerStop {
+    i: number;
+    label: string;
+    notes?: string;
+}
+export declare class DecksmithPlayer extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    /** Every stop the deck reported, empty until `ds-ready`. */
+    get stops(): PlayerStop[];
+    /** Where the deck is now. */
+    get at(): number;
+    /** Whether the deck answered the handshake. */
+    get connected(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, was: string | null, now: string | null): void;
+    next(): void;
+    prev(): void;
+    go(at: number): void;
+    play(on?: boolean): void;
+}
+/**
+ * Register the element, once.
+ *
+ * GUARDED AND PARAMETERISED because `customElements.define` throws on a
+ * duplicate name, and a host page that imports this twice — two bundlers, or a
+ * hot reload — should get a no-op rather than an exception that takes the page
+ * down. The tag is an argument so a consumer whose page already owns
+ * `decksmith-player` can mount it under another name.
+ *
+ * NOT called at import time. A module with a side effect cannot be imported for
+ * its types, and `player-element.ts` exists precisely so the side-effecting
+ * entry point is a separate file a consumer opts into.
+ */
+export declare function define(tag?: string): void;

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

@@ -0,0 +1,80 @@
+/**
+ * What a host page and a deck say to each other.
+ *
+ * ONE FILE, IMPORTED BY BOTH ENDS, so `tsc` checks the sender against the
+ * receiver. The alternative — a string literal in the runtime and a matching one
+ * in the element — is two copies of a contract that drift the first time a field
+ * is added, and the drift is invisible because `postMessage` takes `any` and a
+ * message nobody understands is simply ignored.
+ *
+ * WHY A BRIDGE AT ALL, rather than hosting the deck in the page. A deck is a
+ * whole document with its own fonts, GSAP, KaTeX, a vendored player and a ready
+ * gate, and `frameOf` in runtime.ts can only reach a SAME-ORIGIN frame — it
+ * returns null otherwise and the runtime merely warns, so a deck served from
+ * another origin would navigate perfectly and paint nothing, silently. Keeping
+ * the frame keeps that same-origin pair inside one directory, where it is always
+ * true, and makes the host link `postMessage`, which does not care about origin.
+ *
+ * VERSION COUPLING IS THE HAZARD. Every deck published before this existed has
+ * no listener, and a deck is a static artifact that outlives the tool that made
+ * it. So silence is a SUPPORTED state, not an error: the element times out, says
+ * so with a distinct code, and leaves the deck usable — it is still a deck in a
+ * frame, and its own keyboard still works.
+ */
+/** The channel name, on every message in both directions. */
+export declare const CHANNEL = "decksmith-deck";
+/** Sent by the host once the frame has loaded, to open the conversation. */
+export interface Hello {
+    channel: typeof CHANNEL;
+    type: "hello";
+}
+/**
+ * The deck's answer, and the only message that establishes the host's origin.
+ *
+ * NOTHING IS POSTED TO "*" AFTER THIS. A stop carries the slide's speaker
+ * notes, and any page on the internet can put a deck in a frame — posting
+ * wildcard would hand an arbitrary framer the presenter's notes. The origin is
+ * taken from the `hello` event and every later message is addressed to it.
+ */
+export interface Ready {
+    channel: typeof CHANNEL;
+    type: "ready";
+    /** Every stop the deck can land on, in order. */
+    stops: {
+        i: number;
+        label: string;
+        notes?: string;
+    }[];
+    /** Where it is now. */
+    at: number;
+}
+/** Where the deck landed, after any move. */
+export interface Stopped {
+    channel: typeof CHANNEL;
+    type: "stop";
+    at: number;
+    total: number;
+    label: string;
+    notes?: string;
+    playing: boolean;
+}
+/** What a host may ask for. Deliberately small: everything else is a deck concern. */
+export type Command = {
+    channel: typeof CHANNEL;
+    type: "next";
+} | {
+    channel: typeof CHANNEL;
+    type: "prev";
+} | {
+    channel: typeof CHANNEL;
+    type: "go";
+    at: number;
+} | {
+    channel: typeof CHANNEL;
+    type: "play";
+    on: boolean;
+};
+export type FromDeck = Ready | Stopped;
+export type ToDeck = Hello | Command;
+/** A message from us, rather than from anything else sharing the window. */
+export declare function isOurs(data: unknown): data is FromDeck | ToDeck;

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

@@ -1,3 +1,4 @@
+import { type Narration } from "./subtitles.js";
 /** One entry of the slideshow island's `slides` array. */
 export interface SlideSpec {
     sceneId: string;
@@ -49,6 +50,32 @@ export interface TransitionPlan {
 export declare function planTransition(fromT: number, toT: number, opts?: {
     reducedMotion?: boolean;
 }): TransitionPlan;
+/**
+ * How long autoplay waits on the stop it is on, or `null` for "do not set a
+ * timer". Pure, for the same reason `planTransition` and `refused` are: the
+ * decision has two callers and lives inside `start`, which no test in this
+ * project can reach.
+ *
+ * `heard` is the whole point of the split. A narrated stop is timed by its own
+ * audio — speech drives the deck, which is this project's entire timing model —
+ * so it waits for `ended` and wants no timer. But `voice.at` answers
+ * synchronously about whether a segment EXISTS, while `play()` rejects a beat
+ * later, so at arrival a stop whose file is missing is indistinguishable from a
+ * working one. Ask again when `play()` settles and the answer can flip either
+ * way: to `false`, and the stop needs the clock after all or autoplay waits
+ * forever for an `ended` that a source which never loaded cannot fire; or back
+ * to `true`, when a gesture retried the segment and it is speaking now, and the
+ * timer armed while it was silent would cut the sentence it just started.
+ *
+ * `gapMs` is the gap the author left before the next stop, the same number the
+ * linear render used, clamped so neither a back-to-back pair nor a long hold
+ * turns into a bad wait.
+ */
+export declare function dwellMs(opts: {
+    playing: boolean;
+    heard: boolean;
+    gapMs: number;
+}): number | null;
 /** `#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;
@@ -57,3 +84,139 @@ export declare function parseHash(hash: string): Pos | null;
  * longer emit falls back to its slide rather than to nothing.
  */
 export declare function findStop(stops: readonly Stop[], pos: Pos): number;
+interface Player extends HTMLElement {
+    ready?: boolean;
+    seek: (t: number) => void;
+    pause?: () => void;
+}
+/** Only what we call on a GSAP timeline. */
+interface Seekable {
+    seek: (t: number) => void;
+}
+interface Frame {
+    doc: Document;
+    timelines: Record<string, Seekable>;
+}
+/**
+ * The composition, reached through the player's iframe.
+ *
+ * Same-origin only, which means a deck must be served over http — opening
+ * `deck.html` from the filesystem gives the iframe an opaque origin and we
+ * cannot drive it. `present()` says so out loud rather than rendering blank.
+ */
+export declare function frameOf(player: Player): Frame | null;
+export interface Voice {
+    /**
+     * Arrive at a stop: cut whatever was speaking, start this stop from zero.
+     * Returns whether this stop has anything to say — autoplay needs to know,
+     * because a silent stop has no `ended` event to wait for and would otherwise
+     * be where playback quietly stops forever.
+     */
+    at: (stop: Stop) => boolean;
+    /**
+     * Stop talking without arriving anywhere. The deck has ONE audio track and
+     * `claim-figure` already spends it on narration — see its `muted` note — so
+     * anything else that wants to make a sound has to take it first.
+     */
+    hush: () => void;
+    toggleMute: () => void;
+    toggleSubtitles: () => void;
+    /** Called when the segment for the CURRENT stop finishes of its own accord. */
+    onEnded: (fn: () => void) => void;
+    /**
+     * Called when the CURRENT stop's `play()` settles, with whether there is going
+     * to be a sound. Autoplay needs it because `at` answers one beat too early:
+     * `at` says a segment EXISTS, and `play()` says whether it can be heard.
+     *
+     * BOTH answers matter. False means no `ended` will ever fire, so a deck
+     * playing itself must fall back to its own clock or sit on that slide forever
+     * with the button lit. True is how it gives that clock back — a segment
+     * retried after a dropped connection is speaking now, and a timer armed while
+     * it was silent would cut the sentence it just started.
+     */
+    onSettled: (fn: (heard: boolean) => void) => void;
+    /**
+     * A real gesture: retry the segment for the stop we are on. Covers the
+     * autoplay policy, which is what it was written for, and a file that failed to
+     * load — see `refused` for why the second one is never retried unasked.
+     */
+    unlock: () => void;
+}
+/**
+ * Was that `play()` rejection the autoplay policy, or an audio file we will
+ * never be able to play? Pure, so the classification is testable without a
+ * browser; the element that produces the rejection is not.
+ *
+ * The two need telling apart because they are not the same failure and must not
+ * be reported as one. The policy is recoverable by construction: the first
+ * gesture retries the segment and it speaks, so "press any key for sound" is
+ * simply true. A file that did not load MIGHT be — a two-second wifi drop and a
+ * one-off 503 look exactly like this from here — but it is just as likely a deck
+ * whose audio directory never got copied, and telling THAT viewer to press a key
+ * names the wrong culprit and goes on being wrong every time they try.
+ *
+ * So this split decides what the strip says, and whether anything retries
+ * unasked. It does NOT decide whether a person may retry: a gesture re-arms
+ * either failure (see `unlock`), because someone asking is not the same as us
+ * guessing. And no gate here can see any of it — nothing in the suite opens
+ * deck.html or plays a sound.
+ *
+ * `NotSupportedError` is the unplayable one — observed rather than taken from
+ * the spec: a source that cannot be fetched at all rejects `play()` with
+ * `NotSupportedError` and leaves `audio.error.code` at 4
+ * (`MEDIA_ERR_SRC_NOT_SUPPORTED`), and so does one that is fetched but is not
+ * media.
+ *
+ * Be honest about what that is worth. It is ONE run, on this machine, in a
+ * headless browser whose engine and version nobody wrote down, and that run
+ * could not show the other side of the split at all: the build played an
+ * ungestured sound even under
+ * `--autoplay-policy=document-user-activation-required`, so no `NotAllowedError`
+ * ever arrived to compare against. Nothing here has watched the two failures
+ * come out of the same browser. Treat "a missing segment reads as missing on the
+ * first attempt" as what that one run did, not as a cross-engine guarantee.
+ *
+ * Everything else FAILS SAFE to the policy, `NotAllowedError` included, and that
+ * is exactly what makes such thin evidence affordable: rejection names are
+ * per-engine, and an unknown one degrading to what ships today is the smaller
+ * mistake — "press any key" over a file we could have played still recovers on
+ * the first gesture, whereas the other way round leaves a recoverable deck
+ * permanently silent.
+ */
+export declare function refused(err: unknown): boolean;
+/**
+ * Speech and subtitles for one presented deck.
+ *
+ * Two rules earn their own object. First, leaving a stop must silence it
+ * immediately by every route — arrow, click, Home/End, hashchange — so all of
+ * them funnel through `at`, which stops before it starts; two sentences talking
+ * over each other is worse than no narration at all.
+ *
+ * Second, cues are timed against `audio.currentTime` and nothing else. A timer
+ * started alongside `play()` agrees with the audio right up until the first
+ * stall, and then never again — and a stall is exactly when a viewer is looking
+ * at the subtitle to find out what they missed.
+ *
+ * Exported, with `Voice`, only so a test can drive its failure paths: everything
+ * that matters below happens after `play()` rejects, and nothing else in this
+ * module can hand it that promise. `start` is the only caller.
+ */
+export declare function mountVoice(doc: Document, narration: Narration, ui: {
+    subs: HTMLElement;
+    flags: HTMLElement;
+}): Voice;
+/** One player-page video, keyed in the island by the scene that draws its still. */
+export interface ClipSpec {
+    /** Already in embeddable form — `embedUrl` in src/pack/media.ts did that at build time. */
+    url: string;
+    /** The figure's caption. It titles the frame, which is all a screen reader gets. */
+    title: string;
+}
+/**
+ * Read the island, defensively, for the same reason `parseNarration` is
+ * defensive: a deck built before this existed has no island, and one built by a
+ * newer emitter may carry fields this reader has never heard of. Neither may do
+ * anything worse than leave the poster alone.
+ */
+export declare function parseClips(json: string | null | undefined): Record<string, ClipSpec>;
+export {};

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

@@ -1,9 +1,2 @@
-/**
- * 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/camera.d.ts

@@ -13,12 +13,20 @@
  *
  * Three things here are load-bearing and each of them cost a render to learn:
  *
- * 1. THE MOVE IS TWO `fromTo`s AND NOTHING ELSE. `seek()` passes
- *    `suppressEvents`, so a GSAP `onUpdate` never fires under capture. The first
- *    camera in experiment 008 drove `viewBox` from an `onUpdate`, played
- *    perfectly in a browser, and rendered 900 frames of a frozen `0 0 1920 1080`
- *    with every gate green (invariant 11). State must be applied by the thing
- *    being seeked.
+ * 1. THE MOVE IS TWO `fromTo`s AND NOTHING ELSE. The first camera in experiment
+ *    008 drove `viewBox` from an `onUpdate`, played perfectly in a browser, and
+ *    rendered 900 frames of a frozen `0 0 1920 1080` with every gate green.
+ *
+ *    THAT RECORD STANDS; THE MECHANISM IT WAS ATTRIBUTED TO DOES NOT. `seek()`
+ *    passing `suppressEvents` is why `decksmith frames` sees nothing, but the
+ *    render does not seek — capture runs off Chrome's `beginFrame`, and both
+ *    constructions were re-rendered on 2026-09-04 and both ramped smoothly. What
+ *    a callback actually costs is reproducibility: 11 differing frames of 3,120
+ *    on the demo as built, 260 with one `onUpdate` tween added. Whatever froze
+ *    experiment 008's camera, it was not measured, and this file should not keep
+ *    asserting it. The rule is unchanged and so is the reason for it — state must
+ *    be applied by the thing being seeked. See invariant 11 in AGENTS.md and
+ *    `.planning/2026-09-04-invariant-11-under-beginframe.md`.
  *
  * 2. THE EASES ARE CLOSED FORM AND THEY ARE NOT DECORATION. `zoomEase` travels
  *    scale in log space — a linear scale tween reads as a lurch, and every

package/dist/types/emit/composition.d.ts

@@ -67,6 +67,19 @@ export interface DeckOptions {
      * failure shape.
      */
     onBeatError?: (beatId: string, err: Error) => void;
+    /**
+     * What to do when a beat IS drawn but not as it was authored.
+     *
+     * The other half of `onBeatError`, and the reason it is a second hook rather
+     * than a second call to that one: this beat is IN the deck. An emitter that
+     * drops an ornament to fit its beat — see `Scene.warnings` — says so here, and
+     * absent this hook it says it to nobody, which is the silence the whole
+     * mechanism exists to avoid.
+     *
+     * Called once per built scene, from `layout`. `planCut` emits every beat as
+     * well and stays quiet: its scenes are thrown away.
+     */
+    onBeatWarning?: (beatId: string, warning: string) => void;
     /**
      * The subsetted bundle's `@font-face` CSS, INLINED rather than linked.
      *

package/dist/types/emit/kit.d.ts

@@ -137,6 +137,39 @@ export interface EmitContext {
      * `hyperframes lint` rejects it (`unscoped_gsap_selector`).
      */
     sid: string;
+    /**
+     * WHERE THIS SCENE BEGINS ON THE DECK'S OWN CLOCK, in seconds, ALREADY ROUNDED
+     * to invariant 10's three places — the identical number the scene wrapper
+     * publishes as `data-start`. Write it; do not round it again, because two
+     * roundings of one number is how a byte moves.
+     *
+     * Everything else an archetype emits is scene-relative, and that is the right
+     * default: an emitter that knew where it sat in the deck would be an emitter a
+     * cut could invalidate. ONE thing is not expressible that way. A `<video>` is
+     * timed by the RUNTIME, not by this scene's timeline, and the runtime reads
+     * `data-start` as an ABSOLUTE composition second — so a clip that declares a
+     * scene-relative start is seeked into a window that has already passed.
+     *
+     * MEASURED, because the alternative looked right on paper. hyperframes'
+     * compiler injects `data-start="0" data-hf-auto-start=""` into a media tag
+     * that declares no timing, and its runtime resolves that marker against the
+     * enclosing `[data-composition-id]`, which is exactly this scene — so the
+     * marker ought to have been enough. Rendered at 0.8.27, on a two-beat deck
+     * whose clip is red for 2s, green for 2s then blue for 2s and whose second
+     * scene starts at 7s: with the marker the plate is BLUE at composition 9.5s,
+     * 10.5s and 12.5s — the clip's last frame, frozen, because the render placed
+     * it at second 0 and it had ended before the scene began. With `data-start="7"`
+     * the same frames are green, green, blue: clip seconds 2.5, 3.5 and 5.5. Every
+     * gate is green over both.
+     *
+     * OPTIONAL, because the shell is not the only caller: an archetype test calls
+     * `emitScene` with a context it builds by hand, and twelve of the thirteen
+     * emitters have no use for this. The one that does refuses by name when it is
+     * missing rather than inventing a second, i.e. wrong, clock. `planCut` passes
+     * a provisional 0 for the same reason it passes provisional scene ids — its
+     * pass exists to measure holds, and every scene it emits is thrown away.
+     */
+    start: number;
 }
 /**
  * A value in a GSAP vars payload that is JavaScript rather than data.
@@ -278,20 +311,45 @@ export interface Scene {
      * off, against 7 frames of antialiasing once deferred. Both failures are
      * invisible to every gate. `cameraMeasure` carries the numbers and the controls.
      *
-     * INVARIANT 11 IS THE TRAP HERE. This is not a callback on a tween. `seek()`
-     * passes `suppressEvents`, so measuring from an `onUpdate` — the obvious way to
-     * "measure late" — renders a frozen video with every gate green. Measurement
-     * happens before the timeline exists, and what it produces is ordinary tween
-     * values.
+     * INVARIANT 11 IS THE TRAP HERE. This is not a callback on a tween. Measuring
+     * from an `onUpdate` — the obvious way to "measure late" — is what the
+     * invariant forbids, and the reason is reproducibility rather than the frozen
+     * video an older version of this comment claimed: measured 2026-09-04, one
+     * `onUpdate` tween took the demo from 11 non-reproducible frames of 3,120 to
+     * 260. See AGENTS.md invariant 11. Measurement here happens before the
+     * timeline exists, and what it produces is ordinary tween values.
      */
     measure?: string[];
     /**
      * Vendored runtimes this scene's tweens need registered before its script
-     * runs — `"dsMorph"` for the equation morph. The shell loads a runtime only
-     * when some scene names it, so a deck that names none is byte-for-byte what
-     * it was.
+     * runs — `"dsMorph"` for the equation morph, `"morphSVG"` for a reshape. The
+     * shell loads a runtime only when some scene names it, so a deck that names
+     * none is byte-for-byte what it was.
+     *
+     * `PLUGINS` in `composition.ts` is the ONE place a name resolves, and it is
+     * the list to read before returning this field: the type is
+     * `readonly string[]`, so a name that table does not know is a typo no
+     * compiler can see, and the shell refuses it there rather than emitting a
+     * scene whose plugin tween animates nothing.
      */
     plugins?: readonly string[];
+    /**
+     * WHAT THE ARCHETYPE HAD TO GIVE UP TO DRAW THIS BEAT, one sentence each.
+     *
+     * The middle answer between drawing the beat as asked and refusing it. An
+     * emitter that cannot fit everything it was given has three moves: draw it
+     * anyway and let it collide or truncate, which is the failure this project
+     * keeps finding by eye; throw, which reaches `onBeatError` and costs the whole
+     * SLIDE; or draw less and say so, which is this. Reach for it when the thing
+     * dropped is an ORNAMENT — line-chart's reshape against a baseline, say —
+     * and for the throw when what is left would misrepresent the source.
+     *
+     * Surfaced by `layout` through `DeckOptions.onBeatWarning`, once per built
+     * scene. `planCut`'s measuring pass emits every beat too and deliberately does
+     * not report these: it throws its scenes away, and the same sentence twice per
+     * beat trains people to stop reading it.
+     */
+    warnings?: readonly string[];
     /**
      * Hold points in seconds from the scene's start — where a presenter should
      * pause. The shell converts these to absolute island fragment times.

package/dist/types/emit/svg.d.ts

@@ -69,6 +69,33 @@ export declare function nv(v: number): number;
  */
 export declare const DRAW_FROM: Vars;
 export declare const DRAW_TO: Vars;
+/**
+ * ONE SHAPE BECOMES ANOTHER — a baseline curve lifting off its own position and
+ * settling into the result, leaving whatever was drawn under it behind.
+ *
+ * The from-vars are SELF-REFERENTIAL: `{ morphSVG: { shape: target } }` means
+ * "start from the `d` you were authored with". That is the construction
+ * `experiments/013-vocabulary/gaps/spike/index.html:147` measured, and it is the
+ * only one that keeps invariant 2 checkable by `tsc` — MorphSVG's natural
+ * spelling is a bare `to`, which is a `from()` wearing different clothes.
+ * `_parseShape` reads `data-original` when the shape names the target itself
+ * (MorphSVGPlugin.js), so the start is the authored path however many times the
+ * tween is re-initialised under a seek.
+ *
+ * `to` NAMES A SELECTOR, so the end shape lives in the document as a hidden
+ * sibling rather than as a path string in the timeline. Two copies of the same
+ * geometry — one in the `d` attribute, one in the tween — is the duplication
+ * `drawFrom` was retired for.
+ *
+ * Safe under capture for the reason DrawSVG is: a plugin's `render()` is part of
+ * being seeked where a callback is not. Measured for THIS plugin in a deck, not
+ * inherited from that one — `.planning/2026-09-08-reshape-seam.md`.
+ *
+ * ONE CALL PER (ELEMENT, MORPH). `first` is false for any reshape that is not
+ * the element's first on `morphSVG`; a second immediate render on one property
+ * would establish its start state at build time and undo the first.
+ */
+export declare function reshape(target: string, to: string, at: number, seconds: number, first: boolean): Tween;
 /**
  * Something travels a polyline — a pulse along an arrow, a marker ring along a
  * curve, a highlight down a divider: one `x`/`y` `fromTo` per leg, each leg's

package/dist/types/images/providers.d.ts

@@ -82,11 +82,20 @@ export declare function codexImages(opts?: CodexImagesOptions): ImageProvider;
  * something better draws it. Same request, same bytes.
  */
 export declare function drawSvg(req: ImageRequest): string;
-/** The size the tool wrote into its own SVG. `imageSize` is raster-only on purpose. */
-export declare function svgSize(bytes: Buffer): {
-    width: number;
-    height: number;
-};
+/**
+ * The size an SVG declares, for `sizeOf` in ./illustrate.ts and for anything
+ * else that already imports this module.
+ *
+ * It USED to live here, as a regex for `viewBox="0 0 %d %d"` over the first 200
+ * bytes — four integers, no units, no preamble — which is exactly the SVG
+ * `drawSvg` above writes and nothing else. Figure ingest needs to measure an SVG
+ * a stranger wrote, so the reader was generalised and moved to src/source/assets.ts
+ * beside the other formats. It moved THERE rather than staying here because
+ * that module imports nothing but node and the schemas: the reverse would put
+ * the Codex runner and this file's OpenAI adapter on the import path of every
+ * source parse, for two integers.
+ */
+export { svgSize } from "../source/assets.js";
 /** The last rung. Pure, so it cannot fail, so `illustrate` always finishes. */
 export declare function toolSvg(): ImageProvider;
 /**

package/dist/types/index.d.ts

@@ -8,12 +8,25 @@ import { type Format, type Source, type Storyboard } from "./types.js";
  */
 export { parseMarkdown } from "./source/markdown.js";
 export type { ParseOptions } from "./source/markdown.js";
+/**
+ * A web page in, a markdown document and a directory of files out — the step
+ * BEFORE `parseMarkdown`, not a replacement for it. Separate because it needs a
+ * browser and the network, which `parseMarkdown` deliberately does not.
+ *
+ * `attachClips` is exported with it because a harvest is not finished without
+ * it: the markdown dialect has no way to say `kind: "clip"`, so a page's videos
+ * come back beside the document and this is what puts them into the source. It
+ * runs BEFORE `fetchFigures`, which passes a clip through untouched.
+ */
+export { attachClips, harvest, toMarkdown } from "./source/harvest.js";
+export type { Block, Harvested, HarvestedClip, HarvestOptions } from "./source/harvest.js";
 /**
  * Figures referenced by URL, downloaded beside the source. Separate from
  * `parseMarkdown` because it touches the network and a server may want to fetch
  * through its own client instead.
  */
 export { fetchFigures } from "./source/assets.js";
+export { fetchGuarded, isBlockedAddress } from "./net/fetch.js";
 /**
  * Subset a CJK webfont over the glyphs a deck actually renders. Exported
  * because invariant 9 — a font stack naming a family the bundle does not
@@ -153,6 +166,19 @@ export type { AssetRequest, Fetcher, Media, MediaPlan } from "./pack/media.js";
  */
 export { CONFIG_FILE, loadPrefs } from "./prefs.js";
 export type { Prefs, PrefsPatch } from "./prefs.js";
+/**
+ * The `TMPDIR` guard, exported because `src/server/main.ts` has no other way to
+ * reach it: `build:server` transpiles without bundling, so a deep import there
+ * would survive into `dist/server/` and resolve to nothing. It fails the house
+ * rule for this file — nobody outside asked for it — and it is here anyway,
+ * because the alternative is a second copy of the guard living under `server/`.
+ *
+ * A CONSUMER SHOULD NEVER NEED TO CALL IT. It is a no-op in a published install
+ * (see src/tmpdir.ts for why), and importing this module does not run it: an
+ * absent `TMPDIR` is inherited by every child process, which is not something a
+ * library import may decide for its host.
+ */
+export { guardTmpdir } from "./tmpdir.js";
 /**
  * Every schema and type. Unusually broad for this file, and justified: `types.ts`
  * is nothing but the wire format — what `source.json`, `storyboard.json`,
@@ -184,6 +210,12 @@ export interface BuildDeckOptions {
      * Absent, the emitter's error propagates — see `DeckOptions.onBeatError`.
      */
     onBeatError?: (beatId: string, err: Error) => void;
+    /**
+     * Called when a beat is drawn but not as it was authored — an emitter dropped
+     * an ornament to fit the beat's length. The beat is IN the deck; nothing is
+     * missing but the ornament. See `DeckOptions.onBeatWarning`.
+     */
+    onBeatWarning?: (beatId: string, warning: string) => void;
     /** Any name in `THEME_NAMES`. Overrides `storyboard.theme`. */
     theme?: string;
     /** Multiplies every duration and hold. 1 leaves the bytes untouched. */

package/dist/types/mcp/tools.d.ts

@@ -90,6 +90,7 @@ export declare const estimateSchema: z.ZodObject<{
 export declare const createSchema: z.ZodObject<{
     document_path: z.ZodOptional<z.ZodString>;
     document_text: z.ZodOptional<z.ZodString>;
+    document_url: z.ZodOptional<z.ZodString>;
     settings: z.ZodOptional<z.ZodObject<{
         format: z.ZodOptional<z.ZodEnum<{
             [x: string]: string;
@@ -221,6 +222,25 @@ export declare function deckTools(opts: McpOptions): {
             state: import("../server/queue.js").StepState;
         }[];
         log: string[];
+    } | {
+        harvest_warnings: string[];
+        next: string;
+        deck_path?: string | undefined;
+        slides?: number | undefined;
+        duration_seconds?: number | undefined;
+        warnings?: string[] | undefined;
+        storyboard_path: string;
+        error?: import("../server/errors.js").JobError | undefined;
+        job_id: string;
+        state: import("../server/queue.js").JobState;
+        stage: import("../server/queue.js").Stage | undefined;
+        queue_position: number | undefined;
+        elapsed_seconds: number;
+        steps: {
+            name: import("../server/queue.js").Stage;
+            state: import("../server/queue.js").StepState;
+        }[];
+        log: string[];
     }>;
     /** Poll, blocking up to `wait_seconds` for the job to move on. */
     status(input: z.infer<typeof statusSchema>): Promise<{