@jokerized/decksmith 0.1.0

package/dist/types/render/timing.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Where the words go.
+ *
+ * A narrated deck used to render SILENT: thirty-seven mp3s sat beside a deck
+ * whose mp4 had one stream. This module is the arithmetic that puts them back,
+ * and it is arithmetic rather than an ffmpeg incantation because the thing that
+ * can be wrong here is a number, not a codec. Audio that drifts from the
+ * animation is worse than no audio at all, so every offset below is derived
+ * from the composition the emitter actually wrote, not from a second guess at
+ * what it must have written.
+ *
+ * THE TIMING MODEL, and the one thing to understand before changing anything:
+ *
+ * A narration segment belongs to a STOP, and a stop is a hold — a settled time
+ * inside a scene where a presenter pauses. In the PRESENTED deck the runtime
+ * seeks to that hold and waits for the sentence to finish. A linear render has
+ * no waiting: the GSAP timeline runs straight through, so on the demo deck a
+ * six-reveal pipeline fires every reveal inside 7.75 seconds and then sits
+ * motionless for the 31 seconds of speech that follow. Placing the audio at the
+ * holds would overlap five-second sentences into 1.4-second gaps; placing it
+ * sequentially would leave the last sentence nineteen seconds behind the reveal
+ * it describes. Both are the drift this feature exists to avoid.
+ *
+ * So the renderer does what the presenter does: it FREEZES the video at each
+ * hold for exactly as long as that stop's audio, and drops the dead tail the
+ * composition parked at the end of the scene. That is not a liberty — it is
+ * what `beatSeconds` in src/emit/composition.ts already budgeted for. It makes
+ * a narrated scene `lastHold + sum(segment.seconds)` long, which is precisely
+ * `motion + freezes`, so the retimed scene comes out the same length as the
+ * scene the composition claims and the whole video keeps its duration to the
+ * frame. Measured on the demo deck: all twelve narrated scenes satisfy
+ * `D == lastHold + spoken` exactly.
+ *
+ * `assertFits` is the loud failure the brief asks for. If a scene's speech does
+ * not fit inside its window we stop, because the alternatives are truncating a
+ * sentence or stretching the video, and both are silent lies.
+ *
+ * WHY THIS LIVES HERE AND NOT IN `layout()`. `layout` is the only function that
+ * knows a scene's absolute start and its holds in the same breath, and that is
+ * where this manifest ideally comes from. This workstream does not own
+ * src/emit/composition.ts, so instead: scene windows are READ BACK from the
+ * composition that was just emitted — authoritative, no arithmetic repeated —
+ * and holds are obtained the way `narrate` already obtains them, by asking the
+ * emitter to stage the beat and reading `scene.holds`. When the format is
+ * navigable the composition also carries the slideshow island, and
+ * `assertHoldsAgree` cross-checks the derived holds against the fragments the
+ * emitter itself wrote. If those two ever disagree, this throws rather than
+ * rendering a deck whose audio is aimed at the wrong frames.
+ */
+import type { z } from "zod";
+import { type Cue } from "../deck/subtitles.js";
+import { type DeckNarration } from "../emit/composition.js";
+import type { Beat, Format, Source, Storyboard, segmentSchema } from "../types.js";
+type Segment = z.infer<typeof segmentSchema>;
+/** Written beside `index.html` by `build`; read by `render`. */
+export declare const TIMING_FILE = "timing.json";
+export interface TimedScene {
+    /** Composition id — `s1`, `s2`. */
+    id: string;
+    /** Absolute seconds. Identical on the composition and output timelines. */
+    start: number;
+    duration: number;
+    /** Absolute composition seconds: sorted, deduplicated, one per stop. */
+    holds: number[];
+    /**
+     * Scene-relative seconds at which this scene may start speaking — when its
+     * headline has landed. Read from the same emit the holds come from, so the two
+     * cannot disagree. See `openSeconds`.
+     */
+    open: number;
+}
+export interface TimedSegment {
+    /** `<scene>.<stop>` — stable, and unique because a stop speaks once. */
+    id: string;
+    scene: string;
+    stop: number;
+    /** mp3 filename, relative to `audioDir`. */
+    audio: string;
+    /** Absolute COMPOSITION seconds of the reveal this segment speaks over. */
+    hold: number;
+    /** Absolute OUTPUT seconds where the audio starts, once the freezes are in. */
+    start: number;
+    /** Measured length of the mp3. */
+    duration: number;
+    /** Seconds from the start of this segment's own audio. */
+    cues: Cue[];
+}
+/**
+ * The timing manifest. Small on purpose: everything a renderer needs and
+ * nothing it could derive differently from the deck it is pointed at.
+ */
+export interface Timing {
+    version: 1;
+    width: number;
+    height: number;
+    /** Composition seconds. The rendered video is exactly this long. */
+    duration: number;
+    /** BCP-47 tag of the deck's copy. Picks the burn-in font; see `burnStyle`. */
+    lang: string;
+    /** Directory holding the mp3s, relative to the deck. `""` when silent. */
+    audioDir: string;
+    voice: string;
+    scenes: TimedScene[];
+    segments: TimedSegment[];
+}
+/**
+ * The scene windows, out of the composition itself.
+ *
+ * The attribute set `sceneHtml` writes is exact and one-per-line, which is what
+ * makes this honest rather than a guess: every scene div carries
+ * `data-composition-id`, `data-start` and `data-duration` in that order, and
+ * nothing else in the document does. Reading them back means the accumulated
+ * `beatSeconds` arithmetic is never performed twice — this is the emitter's own
+ * answer, whatever it decided.
+ *
+ * `data-duration` is the scene's CLIP, and since the handoff work it is longer
+ * than the scene's SLIDE by `HANDOFF_SECONDS`: the outgoing scene stays painted
+ * into the next one's window so the deck does not cut to background between
+ * them (src/emit/camera.ts). Everything here — where a sentence starts, how many
+ * frames a piece is — is measured in slides, and a slide ends where the next one
+ * begins. Taking the clip instead makes the frame plan longer than the capture
+ * by one handoff per scene, which `render` refuses outright rather than
+ * silently mistiming; the last scene has no successor and no extension, so its
+ * own number is already the slide.
+ */
+export declare function readSceneWindows(html: string): TimedScene[];
+/** The root's `data-duration` — the whole deck, in seconds. */
+export declare function readDuration(html: string): number;
+/**
+ * The island's fragments, keyed by scene, or null when the format is linear and
+ * carries no island. Only ever used to CHECK the holds, never to supply them —
+ * a video format has no island and must take the same path.
+ */
+export declare function readFragments(html: string): Record<string, number[]> | null;
+/**
+ * The derived holds must be the ones the emitter wrote into the island.
+ *
+ * This is the check that makes reading the staging back out of `emitScene`
+ * safe. It can only run for a navigable format — a linear one has no island —
+ * but the code path either side of it is identical, so a divergence introduced
+ * by an emitter change is caught on the deck format and never reaches a video.
+ */
+export declare function assertHoldsAgree(scenes: TimedScene[], fragments: Record<string, number[]>): void;
+/**
+ * Lay the segments out on the output timeline.
+ *
+ * Per scene, walking the stops in order: the video plays to the hold, then
+ * freezes for the whole of that stop's audio. So a segment's output start is
+ * its hold plus every freeze already inserted in the same scene, and the
+ * scene's own start needs no adjustment at all — the freezes it adds are
+ * exactly the tail it drops, which is why `start` means the same thing on both
+ * timelines and why the video keeps its length.
+ *
+ * A segment whose `stop` is past the end of the stop list is clamped onto the
+ * last one. That only happens when a deck is narrated for one format and built
+ * for another whose staging differs; speaking it late over the final state
+ * beats dropping the sentence on the floor.
+ */
+export declare function place(scenes: TimedScene[], spoken: Record<string, Segment[]>): TimedSegment[];
+/**
+ * Every scene's speech fits inside the window the composition gave it.
+ *
+ * `beatSeconds` already made a narrated scene `max(authored, lastHold + spoken)`
+ * long, so this holds by construction today — which is exactly why it is worth
+ * asserting. The failure it guards against is a deck built from a storyboard
+ * whose narration was re-cut after the fact, or a `--speed` that shrank the
+ * holds without shrinking the speech. The brief's rule: fail loudly rather than
+ * truncate, and never stretch the video to fit.
+ */
+export declare function assertFits(scenes: TimedScene[], segments: TimedSegment[]): void;
+export interface TimingInput {
+    storyboard: Storyboard;
+    source: Source;
+    format: Format;
+    /** `prefs.animationSpeed`. Scales holds exactly as `layout` scales them. */
+    speed: number;
+    /** The composition `emitDeck` just returned. Read, never re-derived. */
+    composition: string;
+    /**
+     * The beats that composition actually drew, in order — `emitDeck`'s `cut.kept`.
+     *
+     * Absent, the list is re-derived with the format's flat weight threshold, which
+     * is what this did before `planCut` could also cut a deck to the format's
+     * LENGTH. That fallback is exact for an unbudgeted format and wrong for a
+     * budgeted one, so it fails immediately below rather than mis-pairing scenes
+     * with beats: a manifest that indexes audio by the wrong scene puts every
+     * sentence on the wrong picture, which no gate here can see.
+     */
+    beats?: readonly Beat[];
+    narration?: DeckNarration;
+    theme?: string;
+}
+/**
+ * One pass over the built deck, producing the manifest `render` consumes.
+ *
+ * The beat filter and the scene ids repeat `layout`'s two rules — a scene id is
+ * a position over the beats a format KEPT — and the scene count is asserted
+ * against the composition so a drift in either is a failure and not a
+ * misalignment.
+ */
+export declare function planTiming(input: TimingInput): Timing;
+/**
+ * One stretch of the output video: `motion` frames copied from the source
+ * starting at `from`, then `freeze` copies of the last of them.
+ */
+export interface Piece {
+    /** Source frame index, inclusive. */
+    from: number;
+    /** Source frames played. Always at least 1. */
+    motion: number;
+    /** Frames of the last source frame, cloned. 0 outside a stop. */
+    freeze: number;
+}
+export interface PlacedAudio {
+    id: string;
+    audio: string;
+    /** Milliseconds from the start of the output. What ffmpeg's `adelay` takes. */
+    delayMs: number;
+    startFrame: number;
+}
+export interface FramePlan {
+    fps: number;
+    /** Output frames. Equal to the source's, by construction. */
+    frames: number;
+    pieces: Piece[];
+    audio: PlacedAudio[];
+    /** Absolute OUTPUT seconds, already split and wrapped for a screen. */
+    cues: Cue[];
+}
+/**
+ * The manifest, quantised to whole frames.
+ *
+ * Everything above is seconds, because seconds are what the composition and the
+ * mp3s are measured in. ffmpeg cuts frames, and a trim expressed in seconds
+ * lands wherever the nearest frame boundary happens to be — thirty-seven of
+ * those rounding independently is a video that ends up a fraction of a second
+ * away from its audio. So the cuts are computed as frame indices once, and the
+ * audio delays are computed from the same indices, which keeps the two locked
+ * together whatever the frame rate is.
+ *
+ * The tail piece is what makes a scene come out exactly as long as the
+ * composition says: it absorbs whatever the motion and the freezes did not use,
+ * taken from the static stretch after the last hold. Where narration exactly
+ * fills the scene — the ordinary case, since `beatSeconds` sized it that way —
+ * the tail is zero and the whole dead tail is dropped.
+ */
+export declare function framePlan(timing: Timing, fps: number): FramePlan;
+/**
+ * A cue's character budget, scaled for the script it is written in.
+ *
+ * MEASURED at 40px bold in the caption band, against a usable width of 994px:
+ * Latin caption prose advances 0.485em per character, Hangul 0.80em. The 84 of
+ * `CUE_MAX_CHARS` is two lines of 42 at the LATIN number, and 42 Hangul
+ * characters is 1,346px — half as much again as the band can hold. So a Korean
+ * cue at the cap soft-wrapped to a THIRD line: measured at 64 characters the
+ * band grew from 128px to 192px and covered the slide, while 60 characters
+ * still came out on two. Korean is a first-class language for this product, so
+ * the budget is a function of the text rather than a Latin constant.
+ *
+ * Scaling the budget rather than the font keeps the same headroom `burnStyle`
+ * measured — the type stays 40px, which invariant 5 requires, and the cue gets
+ * shorter instead.
+ */
+export declare function cueMax(text: string, max?: number): number;
+/**
+ * A cue on two lines at most.
+ *
+ * `splitCue` has already capped the cue at its script's budget, which is two
+ * lines of broadcast width; this only decides WHERE the break falls, so the two
+ * lines come out even instead of one long and one orphaned word. Left to itself
+ * the layout would wrap at whatever the box width happened to be, and a
+ * burned-in caption that reflows between formats is a caption you cannot
+ * art-direct.
+ *
+ * The default budget is derived from the text for the same reason `cueMax` is:
+ * half of 84 is a Latin line, and half of a Korean cue is not.
+ */
+export declare function wrap(text: string, max?: number): string;
+/** `01:02:03,456` — SubRip's clock, comma decimal and all. */
+export declare function srtTime(seconds: number): string;
+/**
+ * The cues as a SubRip file.
+ *
+ * Overlaps are clipped rather than dropped: edge-tts has been seen to end a cue
+ * a frame after the next one starts, and two captions on screen at once is the
+ * one thing a burned-in band cannot survive. A cue left with nothing to show
+ * after clipping is dropped instead.
+ */
+export declare function toSrt(cues: readonly Cue[]): string;
+export {};

package/dist/types/server/errors.d.ts

@@ -0,0 +1,11 @@
+export interface JobError {
+    message: string;
+    hint: string;
+}
+/**
+ * Turn anything thrown into the `{ message, hint }` the API promises.
+ *
+ * `UploadError` already carries its own hint, because the thing that knows a
+ * zip has no markdown in it is the code that looked.
+ */
+export declare function explain(err: unknown): JobError;

package/dist/types/server/http.d.ts

@@ -0,0 +1,57 @@
+import { type Server } from "node:http";
+import { type PipelineInput } from "./pipeline.js";
+import { type JobHandle, type JobResult, Queue } from "./queue.js";
+export interface ServeOptions {
+    port: number;
+    host: string;
+    /** Root under which every job gets its own directory. */
+    work: string;
+    maxUploadBytes: number;
+    maxQueued: number;
+    ttlMs: number;
+    /** Jobs one IP may submit per hour. The expensive verb gets its own budget. */
+    jobsPerHour: number;
+    requestsPerMinute: number;
+    fetchRemoteFigures: boolean;
+    /** Serve decks into a CSP sandbox. On unless deliberately turned off. */
+    sandboxDecks: boolean;
+    /** Remove a finished job's directory. Injected so tests need no filesystem. */
+    removeDir: (dir: string) => void;
+    log: (line: string) => void;
+    /**
+     * The work a job does. Defaults to the real pipeline; substituted in tests so
+     * that exercising the routes never spawns a Codex or spends anyone's quota.
+     * Same seam, and the same reason, as `Runner` in src/plan/codex.ts.
+     */
+    run?: (job: JobHandle, input: PipelineInput) => Promise<JobResult>;
+}
+export declare function createDeckServer(opts: ServeOptions): {
+    server: Server;
+    queue: Queue;
+};
+/**
+ * A URL path, turned into a relative path or refused.
+ *
+ * Same rule as `safeEntryPath`, and for the same reason: percent-decoding is
+ * what turns `%2e%2e%2f` back into `../`, so the decode has to happen BEFORE the
+ * segments are judged, not after they are joined.
+ */
+export declare function safeUrlPath(rest: string): string | null;
+/** One byte range, the only form a browser sends for media. */
+export declare function parseRange(header: string | undefined, size: number): {
+    start: number;
+    end: number;
+} | "unsatisfiable" | null;
+/**
+ * A fixed-window counter per key. Not a token bucket: the thing being limited is
+ * "how many decks may one address ask for in an hour", and an hour is the unit
+ * the answer is stated in, so a window is what the message can honestly describe.
+ */
+export declare class RateLimiter {
+    #private;
+    private readonly limit;
+    private readonly windowMs;
+    private readonly now;
+    constructor(limit: number, windowMs: number, now?: () => number);
+    take(key: string): boolean;
+}

package/dist/types/server/main.d.ts

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

package/dist/types/server/options.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The form fields, turned into the two objects the pipeline actually runs on: a
+ * `Format` (canvas and budget) and a `Prefs` (what is said and how it sounds).
+ *
+ * Every field is optional and every one has a server-side default, so the
+ * smallest legal request is a file and nothing else. Validation is delegated to
+ * `prefsSchema` wherever the schema already has an opinion — there is one place
+ * that decides what a legal tone is, and it is not this file.
+ *
+ * `loadPrefs` is deliberately NOT used. It walks up from a working directory
+ * looking for `decksmith.config.json`, which on a server means a file somewhere
+ * above the job directory silently changing what a stranger's upload produces.
+ * A request states its own preferences or takes the schema's.
+ */
+import { type Format, type Prefs } from "../index.js";
+/**
+ * The ONE canvas rule this server adds to the library's.
+ *
+ * Everything else — whole numbers, `MIN_EDGE`, `MAX_EDGE`, `MAX_ASPECT` — is
+ * `canvasProblem`'s, and is derived there from the layout and from Chrome's
+ * texture ceiling. This file used to restate the whole question as
+ * `MIN_SIDE = 320 … MAX_SIDE = 2560`, which meant three files held three
+ * different opinions about what a canvas may be: src/types.ts said 64–16384,
+ * this said 320–2560, and src/server/ui.ts's number inputs said 240–7680. The
+ * UI's own maximum was refused by the server it posts to — 3840×2160 came back
+ * 400 — so the picker offered sizes that could not be built.
+ *
+ * What survives is the part the library cannot know: this process holds whole
+ * frames of width×height×4 bytes in flight during capture, on a box shared with
+ * every other job. That is a deployment limit, not a layout one, so it belongs
+ * here — and it is published in `catalog()` so the page can enforce the same
+ * number rather than guess at one.
+ *
+ * With `MAX_ASPECT` also in force this implies a longest edge of about 5650px
+ * (`MAX_SIDE` below), which is why no separate edge cap is stated: a second
+ * number would only be a way to disagree with this one.
+ */
+export declare const MAX_PIXELS = 4000000;
+/**
+ * The longest edge that can actually be BUILT, which is not quite the longest
+ * edge that satisfies the two limits above.
+ *
+ * `sqrt(MAX_PIXELS × MAX_ASPECT)` is 5656.85, so 5656 looks like the answer —
+ * and it is unbuildable. At 5656 wide the aspect limit needs a height of at
+ * least 707 and the pixel limit allows at most 707.2, so 707 is the only height
+ * that fits; 707 is odd, `even()` rounds it to 706, and 5656/706 is 8.01:1,
+ * which is refused. An advertised maximum that returns 400 at every height is
+ * exactly the kind of number this reconciliation exists to delete.
+ *
+ * Rounding down to a multiple of 16 fixes it by construction: it makes
+ * `MAX_SIDE / MAX_ASPECT` an even integer, so the extreme canvas is exactly
+ * 8:1 with both sides even, and `MAX_SIDE² / MAX_ASPECT ≤ MAX_PIXELS` follows
+ * from the same square root. 5648×706 = 3.99 megapixels, and it builds.
+ * Asserted in test/server.test.ts rather than left to this comment.
+ */
+export declare const MAX_SIDE: number;
+export interface JobOptions {
+    format: Format;
+    /** The preset the format came from, for the log line and the job view. */
+    formatId: string;
+    prefs: Prefs;
+    narrate: boolean;
+    video: boolean;
+    /**
+     * Whether the REQUEST said so, as opposed to the schema defaulting.
+     *
+     * `prefs` comes back fully populated, so a theme sitting at "ink" is
+     * indistinguishable from one nobody mentioned — and the two must behave
+     * differently: the storyboard records the theme it was planned under and the
+     * document knows what language it is in, and both should beat a default and
+     * lose to anything a person chose. Same rule `stated()` enforces in src/cli.ts.
+     */
+    stated: {
+        theme: boolean;
+        lang: boolean;
+    };
+    /** Anything we corrected rather than refused. Surfaced on the finished job. */
+    warnings: string[];
+}
+/** `GET /api/formats`: what the picker needs to draw itself. */
+export declare function formatCatalog(): {
+    id: string;
+    width: number;
+    height: number;
+    navigable: boolean;
+    maxSeconds: number | null;
+}[];
+/** Everything the picker needs, in one payload, so the UI makes no assumptions. */
+export declare function catalog(): Record<string, unknown>;
+export declare function parseOptions(fields: Record<string, string>): JobOptions;

package/dist/types/server/pipeline.d.ts

@@ -0,0 +1,21 @@
+import type { JobOptions } from "./options.js";
+import type { JobHandle, JobResult, Stage } from "./queue.js";
+import { type Upload } from "./upload.js";
+export interface PipelineInput {
+    upload: Upload;
+    options: JobOptions;
+    /**
+     * Whether a figure named by an http(s) URL may be downloaded.
+     *
+     * OFF by default, and that is a security decision, not a performance one. The
+     * document is a stranger's; `![](http://169.254.169.254/latest/meta-data/)` is
+     * a request this process would make from inside the network it runs in, and a
+     * hostname allowlist does not close it because DNS can answer differently the
+     * second time. Off, the figure is dropped and named in the warnings. On (the
+     * owner's own box, own papers), it is fetched with a count and a timeout.
+     */
+    fetchRemoteFigures: boolean;
+}
+/** Which rows the step list should have, decided before anything runs. */
+export declare function stagesFor(options: JobOptions): Stage[];
+export declare function runPipeline(job: JobHandle, input: PipelineInput): Promise<JobResult>;

package/dist/types/server/queue.d.ts

@@ -0,0 +1,105 @@
+/**
+ * One job at a time, and a line for the rest.
+ *
+ * WHY ONE. A deck is minutes of work, not milliseconds: planning spawns Codex
+ * for about a minute, rendering drives a headless Chrome and ffmpeg for two more
+ * on a four-minute video, and capture holds whole frames in memory. This machine
+ * has already lost a Chrome to memory pressure at frame 5547 of a single render.
+ * Two concurrent renders do not halve the wall clock, they double the peak and
+ * turn a slow job into a killed one — so concurrency is 1, the queue is short and
+ * bounded, and a waiting caller is told its place rather than left on a spinner.
+ *
+ * This file runs no pipeline and touches no filesystem. The work is injected as
+ * a function, which is what makes the state machine testable without a network,
+ * a browser, or a Codex.
+ */
+import { type JobError } from "./errors.js";
+export type JobState = "queued" | "running" | "done" | "error";
+export type Stage = "ingest" | "plan" | "narrate" | "build" | "render";
+export type StepState = "pending" | "running" | "done" | "skipped" | "error";
+export interface StepView {
+    name: Stage;
+    state: StepState;
+    /** Epoch ms, absent until the step starts. */
+    startedAt?: number;
+    /** Wall clock of the step, absent until it ends. */
+    ms?: number;
+    detail?: string;
+}
+export interface JobResult {
+    deckUrl: string;
+    videoUrl?: string;
+    srtUrl?: string;
+    packUrl?: string;
+    slides: number;
+    /** Seconds of finished deck — measured from the render when there was one. */
+    duration: number;
+    warnings: string[];
+}
+export interface JobView {
+    id: string;
+    state: JobState;
+    /** The stage currently running, or the one it stopped at. */
+    stage?: Stage;
+    steps: StepView[];
+    log: string[];
+    error?: JobError;
+    result?: JobResult;
+    /** 1 = next to start. Absent once the job is running. */
+    queuePosition?: number;
+    createdAt: number;
+    /** Wall clock since submission, so a UI can say "3m12s" without its own timer. */
+    ms: number;
+}
+/** What the injected work is handed to report itself. */
+export interface JobHandle {
+    readonly id: string;
+    readonly dir: string;
+    begin(stage: Stage, detail?: string): void;
+    done(stage: Stage, detail?: string): void;
+    skip(stage: Stage, why: string): void;
+    log(line: string): void;
+}
+export interface QueueOptions {
+    /** Refuse past this many WAITING jobs. The running one is not counted. */
+    maxQueued?: number;
+    /** How long a finished job's files and record survive. */
+    ttlMs?: number;
+    /** Keep the tail of the log; a render writes a line per few frames. */
+    maxLog?: number;
+    /** Injected in tests so the clock is not the wall's. */
+    now?: () => number;
+    /** Called by `sweep` for each expired job, to delete its directory. */
+    onExpire?: (id: string, dir: string) => void;
+}
+export declare class QueueFullError extends Error {
+    readonly hint: string;
+    readonly status = 503;
+    constructor(max: number);
+}
+export declare class Queue {
+    #private;
+    constructor(opts?: QueueOptions);
+    get depth(): number;
+    get running(): string | undefined;
+    /**
+     * Take a job, or refuse. Refusing is the point: an unbounded queue on a
+     * one-at-a-time worker is a promise the server cannot keep, and a caller told
+     * "position 400" has been lied to more politely than one told "full".
+     */
+    submit(input: {
+        id: string;
+        dir: string;
+        stages: Stage[];
+        run: (h: JobHandle) => Promise<JobResult>;
+    }): JobView;
+    view(id: string): JobView | undefined;
+    /** Subscribe to changes for one job. Returns the unsubscribe. */
+    watch(id: string, fn: (v: JobView) => void): () => void;
+    /**
+     * Drop every job whose time is up and report their ids, so the caller can
+     * delete the directories. A running job is never swept, however old — the TTL
+     * measures how long an ANSWER is kept, not how long work may take.
+     */
+    sweep(): string[];
+}

package/dist/types/server/ui.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The page, as one self-contained HTML document.
+ *
+ * A function rather than a constant so the interpolated tables above are read
+ * once per call and a server that hot-reloads a theme picks the change up
+ * without a module cache dance. It is a few hundred microseconds of string
+ * concatenation against a request that will take two minutes to satisfy.
+ */
+export declare function uiPage(): string;