@jokerized/decksmith 0.1.0

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

@@ -0,0 +1,81 @@
+/**
+ * The architecture overview, redrawn as motion.
+ *
+ * Every paper has this figure and every paper renders it as a flat PNG the
+ * reader has to decode all at once. Drawn here instead, one stage at a time with
+ * its connector arriving first, the viewer watches the method assemble in the
+ * order it actually runs — which is the only reading order a static diagram
+ * cannot impose.
+ *
+ * Two decisions carry the whole archetype:
+ *
+ * Boxes are all one width, solved from the widest label (`pipeLayout`). Boxes
+ * sized individually to their own text is what a generator produces; a row of
+ * equal boxes on a shared centreline is what a designer draws. When the labels
+ * genuinely do not fit on one line the answer is more lines, not smaller type —
+ * type stops at `MIN_FONT` and the box grows downwards, because a stage nobody
+ * in the third row can read is not a stage.
+ *
+ * The two connector reveals are different on purpose. A stage-to-stage arrow is
+ * ~120px, so it fades in as one object and its head is never orphaned. The
+ * feedback loop is a ~1000px elbow, and something that long has to be watched
+ * travelling: it is revealed by a clip sweeping against the flow, so the path
+ * appears in the direction it runs and its arrowhead lands last, on the stage it
+ * returns to.
+ *
+ * A row is a landscape idea. In portrait the same four stages get 860px to share
+ * and come out as columns — the demo's "Window" broke to "Windo/w" and "DQ-CTM"
+ * to "DQ-CT/M", which is a diagram that has stopped being one. So portrait turns
+ * the flow ninety degrees and runs it down the page instead: full-width boxes,
+ * arrows pointing down, and the return path up a channel on the right. See
+ * `columnLayout` — the two arrangements share their type, their reveal and their
+ * furniture, and nothing else.
+ */
+import type { BeatOf } from "../../types.js";
+import type { Emitter } from "../kit.js";
+import { type Track } from "../svg.js";
+type Stage = BeatOf<"pipeline">["params"]["stages"][number];
+type Loop = {
+    from: number;
+    to: number;
+    label: string;
+};
+export interface PipeLayout {
+    /** Label type size. Never below `MIN_FONT`, whatever the labels cost. */
+    size: number;
+    /**
+     * Position and extent along the flow axis: `x`/`w` read as x/width across a
+     * row, and as y/height down a column. One field rather than two so the emitter
+     * paints both arrangements with one expression — a second `rows` array is how
+     * the landscape and portrait geometries drift apart.
+     */
+    boxes: Track[];
+    /** The cross-axis extent every box shares: its height in a row, its width in a column. */
+    boxH: number;
+    boxX: number;
+    boxW: number;
+    /** True when the flow runs down the page. Decides every axis below it. */
+    vertical: boolean;
+    /** Width available to text inside a box — what every `wrap` here is given. */
+    innerW: number;
+    /** Wrapped lines per stage. The box height is derived from these, not guessed. */
+    labelLines: string[][];
+    noteLines: string[][];
+    /** Box bottom to the feedback leg. Zero when there is no loop. */
+    loopDrop: number;
+    loopLines: string[];
+    /** The loop's label column, and where it starts. Portrait only. */
+    loopX: number;
+    loopW: number;
+    svgH: number;
+}
+/**
+ * All the geometry, with no SVG in sight.
+ *
+ * Exported because "the text stays inside the box" is the one thing this
+ * archetype must never get wrong, and asserting it against numbers beats
+ * asserting it against a rendered string.
+ */
+export declare function pipeLayout(stageW: number, stages: readonly Stage[], loop?: Loop): PipeLayout;
+export declare const pipeline: Emitter<"pipeline">;
+export {};

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

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

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

@@ -0,0 +1,93 @@
+/**
+ * A stack, drawn as a stack.
+ *
+ * An encoder stack, a feature pyramid, a protocol layering: the source states
+ * these as a list and leaves the reader to hold the ordering in their head.
+ * Drawing them as offset planes receding up-right puts the ordering on the
+ * screen — and the build order *is* the explanation, so each plane arrives on
+ * its own beat instead of the pile fading in whole.
+ *
+ * Two decisions are worth knowing before changing anything here.
+ *
+ * The labels sit on a fixed right-hand spine, one per plane, so they read as a
+ * column rather than as seven captions scattered across a slanted pile. That
+ * spine is what makes the slide legible with the headline covered.
+ *
+ * The pile grows upward, so the top plane and its label are where this
+ * overflows — and the overflow is not a rounding error, it is structural: seven
+ * layers each carrying a note is more text than 1080px has room for once the
+ * chrome and the slide note have taken their share. So the rise is *solved*
+ * from the height that is actually left rather than assumed and hoped for, and
+ * the solve reserves the largest plane it might later choose so that clamping
+ * `sy` can never push the pile back out of the box.
+ */
+import type { BeatOf, Format } from "../../types.js";
+import type { Emitter } from "../kit.js";
+type Params = BeatOf<"stack">["params"];
+export interface StackLayout {
+    /**
+     * False when the rise the canvas allows is shorter than the tallest label
+     * block — i.e. adjacent labels would overlap. `stackLayout` re-composes rather
+     * than shipping that, so a returned layout is only `!fits` when no composition
+     * fitted and the caller is looking at the least-bad one.
+     */
+    fits: boolean;
+    /** Notes set beside their label rather than beneath it. See `stackLayout`. */
+    inline: boolean;
+    /** The svg's own box. `width` is the full content column. */
+    width: number;
+    height: number;
+    /** Vertical room the svg was allowed, after chrome, its margin and the note. */
+    avail: number;
+    chromeH: number;
+    noteH: number;
+    /** Distance between adjacent planes' front edges. */
+    rise: number;
+    /** The recede vector, and the slab's thickness. */
+    sx: number;
+    sy: number;
+    t: number;
+    /** Plane geometry: left edge of the front face, and its width. */
+    x0: number;
+    w: number;
+    /** Label spine: left edge and width of the label column. */
+    labelX: number;
+    colW: number;
+    labelSize: number;
+    /** Tallest label+note block. Adjacent labels collide once `rise` drops below it. */
+    blockH: number;
+    /** Half `blockH`, floored — the outermost labels overhang the pile by this. */
+    pad: number;
+    /** Front-face y of the bottom plane. Layer `i` sits `i * rise` above it. */
+    yBase: number;
+    /**
+     * Per-layer wrapped text and the width each ran against, so the emitter and
+     * the fit test cannot disagree about how many lines a label took.
+     */
+    lines: {
+        label: string[];
+        note: string[];
+        noteW: number;
+        labelMaxW: number;
+    }[];
+}
+/**
+ * Solve the whole composition before a byte of SVG exists.
+ *
+ * Exported because every way this archetype can fail is a number in here: the
+ * pile leaving the canvas, a label set below `MIN_FONT`, a label column narrower
+ * than its longest label. Asserting those against rendered markup means parsing
+ * text extents back out of SVG, which is a second implementation of the metrics
+ * and would agree with the first right up until it mattered.
+ *
+ * The hard case is seven layers that each carry a note. Two lines of audience
+ * type per layer is ~106px, seven of those want 740px of rise, and after an
+ * eyebrow, a headline and a slide note there are barely 580px left — the
+ * stacked label simply does not fit, and clamping the rise to make it fit is
+ * how notes end up printed through the label below. So when it does not fit the
+ * composition changes rather than the type: the note moves beside its label, on
+ * the same line, right-aligned against the spine.
+ */
+export declare function stackLayout(p: Params, format: Format): StackLayout;
+export declare const stack: Emitter<"stack">;
+export {};

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

@@ -0,0 +1,188 @@
+/**
+ * The opening beat — and the slide chrome the other five archetypes reuse.
+ *
+ * A title slide is that chrome, enlarged and centred, so the eyebrow/headline
+ * block and its theme-derived CSS live here rather than being written out five
+ * more times. `kit.ts` owns the seam between shell and vocabulary; it does not
+ * own the vocabulary's typography.
+ */
+import type { Format } from "../../types.js";
+import type { Emitter, Theme, Tween, Vars } from "../kit.js";
+/**
+ * Whether this format's content box is taller than it is wide.
+ *
+ * The one question an archetype has to ask before it lays anything out. At
+ * `short-9x16` the box is 860x1752 against 16:9's 1700x912 — half as wide and
+ * nearly twice as tall — so a two-column comparison wants to become two stacked
+ * rows and a chart wants its readout underneath rather than beside it. Clamping
+ * a wide arrangement to the narrower width fits and still looks wrong.
+ *
+ * Read off the format rather than off `contentW`/`contentH` so `post-1x1`
+ * (1080x1080, box 860x912) stays on the landscape branch: it is square, and the
+ * landscape arrangements are the ones that survive a square box.
+ */
+export declare function isPortrait(format: Format): boolean;
+/**
+ * The chrome's type scale, and the line boxes that fall out of it.
+ *
+ * These are exported because every archetype that draws a diagram has to know
+ * how much room the chrome took before it can decide how big the diagram is. A
+ * duplicated `const HEADLINE_H = 76` in five files is a type scale that can only
+ * ever be changed in one of them, and the other four then overflow or leave a
+ * band — both silent.
+ *
+ * 76/42, not 66/40. The floor is 40 and most of the deck was sitting on it, so
+ * the whole slide read as body text with one slightly larger line. Growing type
+ * is the safe direction (invariant 5 is a minimum), and the budget arithmetic
+ * below is what keeps the extra height from pushing a scene off both edges.
+ */
+export declare const EYEBROW_SIZE = 42;
+export declare const EYEBROW_LH = 1.2;
+/** One line box. The block is this per line, plus `margin-bottom` once. */
+export declare const EYEBROW_LINE: number;
+export declare const EYEBROW_GAP = 22;
+/** One line box plus `margin-bottom` — the one-line case, which is the common one. */
+export declare const EYEBROW_H: number;
+/**
+ * The eyebrow is drawn UPPERCASE at `.14em` of tracking, and the headline at
+ * `-.015em`. Neither is decoration to the arithmetic below: measured against the
+ * browser, a 60-character eyebrow sets on two lines where an untracked
+ * lowercase measurement predicts one, and a 138-character headline sets on three
+ * where an untracked one predicts four.
+ */
+export declare const EYEBROW_TRACKING = 0.14;
+export declare const HEADLINE_TRACKING = -0.015;
+export declare const HEADLINE_SIZE = 76;
+export declare const HEADLINE_LH = 1.15;
+export declare const HEADLINE_H: number;
+/** Body copy — notes, captions, claims. One notch off the floor, deliberately. */
+export declare const BODY_SIZE = 44;
+export declare const BODY_LH = 1.45;
+/**
+ * Bind the tail of a headline so it cannot break to a one- or two-word last line.
+ *
+ * Gluing the final words with U+00A0 pulls one more word down with the orphan:
+ * "…the carrier is read / through" becomes "…the carrier is / read through". The
+ * line count does not change — greedy wrapping only ever moves words forward — so
+ * `chromeHeight` needs no adjustment and keeps measuring the raw string. (`wrap`
+ * splits on `\s`, which U+00A0 is, so it would not see the binding anyway; the
+ * width guard below is what keeps the browser's line count in step.)
+ *
+ * The run bound is the WIDEST that fits the measure, from `tail + 1` words down
+ * to two, rather than `tail + 1` alone. `wrap` errs wide by construction, so its
+ * last line is not the browser's: it broke "…reports three / different numbers"
+ * where the browser broke "…reports three different / numbers", and the three
+ * words it asked for were both too wide for the measure and aimed at an orphan
+ * that was not the one on screen. Any run that fits protects the same seam, and
+ * binding words that already sit together costs nothing.
+ *
+ * A candidate is REJECTED if it would leave some earlier line raggeder than the
+ * orphan it removes. Binding "dense output" in the demo's title pushed the run
+ * off line three and stranded "with" there by itself — a one-word line in the
+ * MIDDLE of a headline, which is worse than the one at the end. So each candidate
+ * is re-wrapped with the bound run held together as a single token, and kept only
+ * if the shortest line does not get shorter and no line is added.
+ *
+ * Two cases are left alone rather than forced: a headline that IS the orphan
+ * (nothing to borrow from), and one where every candidate is wider than the
+ * measure — the browser would break that anyway, and then in mid-word.
+ */
+export declare function unwidow(text: string, width: number, size: number, weight?: number): string;
+/**
+ * Height the chrome will actually occupy, headline wrapping included.
+ *
+ * `wrap` errs wide, so this over-counts lines rather than under-counting them.
+ * That is the safe direction: an under-count overflows the canvas, and `.scene`
+ * is centred so it overflows off *both* edges at once.
+ */
+export declare function chromeHeight(eyebrow: string | undefined, headline: string, width: number): number;
+/**
+ * What is left for the body once the chrome, the body's own top margin, and
+ * anything below it (a note, a caption band) have been paid for.
+ *
+ * `floor` IS A LAST RESORT, NOT A BUDGET, and the difference has already cost a
+ * defect. `claim-figure` asked for the space left under a 216-character claim,
+ * was told 320 when the true remainder was 163, sized the figure to fit 320, and
+ * drew the caption 7px below the canvas — with every gate green, because the
+ * gate was sampling nine midpoints and never looked at that hold. A caller that
+ * is LAST in the queue for space has to be able to hear "there is almost none",
+ * so it can pass its own floor and act on the answer.
+ */
+export declare function bodyBudget(format: Format, eyebrow: string | undefined, headline: string, below?: number, top?: number, floor?: number): number;
+/**
+ * The largest size at which `text` sets in `width` lines of `maxLines`, capped
+ * both ends. Used where a headline should grow to meet its box instead of
+ * sitting at one authored size with 600px of air beside it.
+ *
+ * The division solves for perfect packing — every line filled to the last pixel —
+ * which no real line break achieves. At 1700 the slack is a few percent and the
+ * answer holds; at 860 it is not, because one long word is a fifth of the
+ * measure. The demo's title came back at 116px, set on FOUR lines against a cap
+ * of three, and the extra line was a stranded "with". So the quotient is an
+ * upper bound, and `wrap` is asked whether it is true.
+ *
+ * Stepping down rather than bisecting: the answer is within a few px of the
+ * bound in every case that matters, and a monotone scan cannot pick a size that
+ * a bisection's midpoint happened to skip. `lo` is a floor, not a target — a
+ * string that will not set in `maxLines` at `lo` simply lands there, as before.
+ */
+export declare function fitText(text: string, width: number, maxLines: number, lo: number, hi: number, weight?: number): number;
+/**
+ * The vocabulary's own constructor: a `fromTo` at a rounded position.
+ *
+ * `kit.fromTo` is the bare structure; this is what an archetype calls, and the
+ * only thing it adds is invariant 10. Every archetype's positions are sums of
+ * authored beat times, so they accumulate float tails — `7.199999999999999` —
+ * and a position that prints differently between two builds of one storyboard
+ * moves a byte in the composition. Rounded HERE rather than in the serialiser
+ * because `camera.ts` rounds its own positions to three places against a clock
+ * the shell owns, and a second rounding on the way out would quietly truncate
+ * them.
+ *
+ * Every tween is `fromTo` — `from()` captures its end state when the timeline
+ * is constructed, which is wrong the moment the deck seeks somewhere else, and
+ * seeking is all deck navigation does. That is now the `Tween` type's doing
+ * rather than this comment's: there is no shape here that omits `from`.
+ */
+export declare function tween(target: string, from: Vars, to: Vars, at: number): Tween;
+/**
+ * Hold points become absolute island fragment times and must land inside the
+ * slide's window, so a beat planned shorter than its own reveal schedule gets
+ * its holds clamped rather than silently pushed into the next slide.
+ */
+export declare function holdsWithin(times: number[], seconds: number): number[];
+/**
+ * The eyebrow + headline block. Ids are scoped by `sid`, as every selector must be.
+ *
+ * `width` is the measure the headline will set in — always `contentW(ctx.format)`,
+ * since `.headline` is a block child of `.scene` and so spans the content box.
+ *
+ * Required, not optional. It was optional for one round while eleven emitters
+ * were being changed by different hands, and the six that never got the argument
+ * were exactly the six still printing one-word last lines ("…is read / through",
+ * "…not the / smallest"). A defaulted measure is indistinguishable at the call
+ * site from a deliberate one, so the next archetype would inherit the same
+ * silent opt-out; requiring it makes the omission a type error instead.
+ */
+export declare function chrome(sid: string, eyebrow: string | undefined, headline: string, width: number): string;
+/** Reveals the chrome. Finishes at 0.9s, which is where archetype bodies pick up. */
+export declare function chromeIn(sid: string, eyebrow: boolean): Tween[];
+export declare function chromeCss(t: Theme): string;
+/**
+ * The note that closes a slide. Eight archetypes each declared their own copy of
+ * this at 40px with a different class name; the sizes then drifted apart by
+ * archetype, which is a hierarchy nobody chose.
+ */
+export declare function noteCss(cls: string, t: Theme, top?: number): string;
+/** The column a `.<cls>` note actually sets in: the cap, or the box if that is narrower. */
+export declare function noteWidth(format: Format): number;
+/**
+ * One `.<cls>` line box, wrapping included — what `bodyBudget`'s `below` wants.
+ *
+ * `width` is the caller's because two archetypes set their note in a column of
+ * their own rather than across the box. Everyone else passes `noteWidth(format)`;
+ * measuring against the bare 1600 cap at 9:16 under-counts the lines by half and
+ * hands the body a budget the note then overruns.
+ */
+export declare function noteHeight(note: string | undefined, width: number, top?: number): number;
+export declare const title: Emitter<"title">;