@jokerized/decksmith 0.3.1 → 0.4.0

package/dist/types/source/readability.d.ts

@@ -0,0 +1,120 @@
+/**
+ * WHICH PART OF A PAGE IS THE ARTICLE — the Readability scoring algorithm,
+ * implemented here rather than depended on.
+ *
+ * `src/source/harvest.ts` picks its content region with three rules: believe
+ * `<main>`, believe `<article>`, else take the deepest element whose block text
+ * minus its link text is maximal. Its own comment says that is deliberately not
+ * a Readability implementation, and it holds up on the shapes it was written
+ * against. It loses on the shapes it was not: a `<main>` that also wraps the
+ * comment thread is believed whole and short-circuits before the loop ever runs;
+ * a `<div role="dialog">` cookie banner matches nothing in the walker's SKIP set,
+ * so it is neither scored down nor skipped; and the score counts text inside
+ * `nav`/`aside`/`footer` subtrees that the walker will then throw away, so a
+ * wrapper can be chosen on the strength of text that never reaches the markdown.
+ *
+ * This is Mozilla Readability's `grabArticle`, in the shape that fits here:
+ * strip the elements whose tag, role, class or id say chrome; score every
+ * paragraph by its length and its comma count; propagate that score to the
+ * parent, the grandparent and up to five levels of ancestor, dividing as it
+ * climbs; discount each candidate by its LINK DENSITY, which is the term that
+ * tells a rail of headlines from prose; take the highest, climb to a parent that
+ * scores higher still, then merge in the siblings that score close to it.
+ *
+ * WHAT THIS IS NOT. It is not a semantic understanding of the page. Nothing here
+ * reads the article; it is arithmetic over text length, punctuation, and the
+ * words site authors happen to put in class names. It is much better than one
+ * subtraction and it is wrong in ways that are structural rather than accidental,
+ * so they are worth naming:
+ *
+ *  - A PAGINATED ARTICLE harvests as page one and nothing says so. Readability
+ *    proper follows "next page" links; this cannot, because `harvest` fetches
+ *    exactly one document and every subresource is aborted.
+ *  - A PAGE WHOSE CONTENT IS A LIST OF LINKS — a link blog, a search result, a
+ *    documentation index — is scored down by the very term that makes the pass
+ *    work. Link density cannot tell a nav from a page that is a nav on purpose.
+ *  - A GALLERY loses. Pictures carry no text, `<li>` is not a scored tag, and a
+ *    page of captioned images scores near zero everywhere, so the winner is
+ *    whichever caption block happened to be longest.
+ *  - CLASS NAMES ARE A GUESS, and the same word list that rescues
+ *    `<div class="article-body">` rescues `<div class="comment-body">`.
+ *  - AN ELEMENT THE STRIP REMOVES TAKES ITS `<video>` WITH IT. That matters more
+ *    here than in a reader: harvest's poster is the join that lets `attachClips`
+ *    keep a clip's id, section and mention, so a silently dropped player demotes
+ *    a clip with every gate green. Hence `mediaDropped` in the report — this pass
+ *    counts what it lost rather than leaving the caller to find out later.
+ *
+ * When it declines it says so, PUTS BACK EVERY NODE IT REMOVED, and changes
+ * nothing else, so `harvest`'s own heuristic runs against the document it would
+ * have seen. Declining is the retry Readability performs with its flags off;
+ * here the simpler pass IS that retry, and it already exists.
+ *
+ * IT RUNS INSIDE THE PAGE. `harvest` ships code into the browser as a function
+ * reference — `page.evaluate(readDom)` — which puppeteer serialises with
+ * `Function.prototype.toString()` and evaluates as source text. `readContentRegion`
+ * is shipped the same way and carries the same rule: it may not close over
+ * anything in this module, so every constant and every helper it uses is declared
+ * inside it, INCLUDING the marker attribute that `CONTENT_MARKER` below spells a
+ * second time. A closed-over constant does not fail here, where a test would see
+ * it; it fails in the page, as a `ReferenceError`, on somebody's ingest — so
+ * test/readability.test.ts asserts the two spellings agree and that the source
+ * names nothing from Node. The node bundle is built with `minify: false`
+ * (scripts/build.mjs), which is what keeps the serialised text intact.
+ */
+/**
+ * The attribute the pass puts on the region it chose.
+ *
+ * A marker rather than a return value because an `Element` cannot cross the
+ * `page.evaluate` boundary — what comes back is structured-clone data. Marking
+ * is also what lets this stay a second self-contained function beside `readDom`
+ * rather than something `readDom` has to grow a second job for: the walker's
+ * `pickRoot` need only look for this attribute first and keep its own three
+ * rules as the fallback for when this pass declines.
+ */
+export declare const CONTENT_MARKER = "data-ds-content";
+/** One element the scorer considered, in the terms it was judged on. */
+export interface Candidate {
+    /** Up to three levels, `div#page > div#content > article.post`, to name it. */
+    path: string;
+    /** Paragraph scores propagated up, plus this element's tag and class weight. */
+    content: number;
+    /** Anchor text over all text, 0..1 — a rail of headlines is near 1. */
+    linkDensity: number;
+    /** `content * (1 - linkDensity)`. This is what the winner is chosen on. */
+    score: number;
+    /** Characters of text held, whitespace collapsed. */
+    text: number;
+}
+/** What the pass hands back across the `page.evaluate` boundary. */
+export interface ContentPick {
+    /** True when some element in the document now carries `CONTENT_MARKER`. */
+    marked: boolean;
+    /**
+     * Why, in a sentence a `warnings` entry can carry verbatim. Populated on
+     * every path, including the ones that change nothing.
+     */
+    reason: string;
+    /** The best few candidates, best first, so a failure names which part broke. */
+    candidates: Candidate[];
+    /** Siblings merged in beside the winner, the winner itself not counted. */
+    merged: number;
+    /** Elements the strip removed. Zero when the pass declined and put them back. */
+    stripped: number;
+    /** Characters of text in the marked region. */
+    text: number;
+    /**
+     * `<video>` and `<iframe>` elements the page had that the region does not.
+     * Not an error — a related-videos rail SHOULD be lost — but the clip path is
+     * load-bearing enough downstream that the number is reported rather than
+     * discovered.
+     */
+    mediaDropped: number;
+}
+/**
+ * Choose the content region, mark it, and report what that cost.
+ *
+ * Evaluated INSIDE THE PAGE, so nothing outside this function body exists at
+ * run time. Type annotations are erased by the build and are the only thing
+ * here that refers to anything above.
+ */
+export declare function readContentRegion(): ContentPick;

package/dist/types/source/transcode.d.ts

@@ -0,0 +1,83 @@
+export interface TranscodeOptions {
+    /** Longest edge of the box to fit inside, in pixels. Default 1280. */
+    maxEdgePx?: number;
+    /** Seconds to keep. A longer video is TRUNCATED, and the trim is warned. */
+    maxSeconds?: number;
+    /** Wall clock for the ffmpeg run before it is killed. Default 10 minutes. */
+    timeoutMs?: number;
+    /**
+     * TEST SEAM: the binary to run. Only ever "ffmpeg" in src.
+     *
+     * It exists so test/transcode.test.ts can prove the skip path by naming a
+     * binary that is not installed, which is the one branch here that cannot be
+     * exercised on a machine where the feature works.
+     */
+    ffmpeg?: string;
+}
+export interface Transcoded {
+    /** The `out` given, or the `input` given back when nothing was done to it. */
+    path: string;
+    /** Measured off the file `path` names — never the arithmetic that asked for it. */
+    width: number;
+    height: number;
+    /** Absent when the container declares no usable duration, as `Measured` says. */
+    seconds?: number;
+    /** False when `path` is still the original's bytes. */
+    transcoded: boolean;
+    /** What was skipped or traded, and why. Empty when nothing was. */
+    warnings: string[];
+}
+/**
+ * The even box `width`x`height` fits inside, never larger than it started.
+ *
+ * FLOOR to even rather than round, on both edges. Even because VP9 in yuv420p
+ * refuses odd dimensions and says so in a way nobody reads as "your width is
+ * odd"; floor because rounding UP a 1919-wide source that needs no scaling at
+ * all would enlarge it by a pixel, and "never upscale" is easier to keep than to
+ * qualify.
+ *
+ * Rounding each edge independently moves the aspect ratio by up to a pixel's
+ * worth, and there is one place downstream where that is visible: claim-figure
+ * picks a full-width layout at exactly `width / height >= 3` (claim-figure.ts:197),
+ * so a source sitting on that boundary can land either side of it afterwards.
+ * That is a layout choice moving one step, not a deck disagreeing with its file
+ * — the figure carries the measured box, so the planner and the emitter still
+ * describe the same rectangle.
+ */
+export declare function fitBox(width: number, height: number, maxEdgePx: number): {
+    width: number;
+    height: number;
+};
+/**
+ * The command, built where it can be read and tested without running anything.
+ *
+ * The house pattern from src/render/ffmpeg.ts: an exported pure args builder and
+ * a one-line `runTool` at the use site, so the flags are assertable on a machine
+ * with no ffmpeg on it.
+ *
+ * `-an` drops the audio track outright. A clip is emitted muted on purpose — the
+ * deck already spends its single audio track on narration (claim-figure.ts:121)
+ * — so carrying the audio is pure bytes for something nothing will ever unmute.
+ *
+ * `-crf 32 -b:v 0` is libvpx-vp9's constant-quality mode; `-deadline good
+ * -cpu-used 4 -row-mt 1` is the speed setting that makes this affordable at
+ * ingest time (4 seconds of 1080p in 0.8s of wall clock, measured) rather than
+ * the several-minutes-per-clip the encoder's defaults cost. The three bitexact
+ * and metadata flags are the determinism story in the header.
+ */
+export declare function transcodeArgs(input: string, out: string, plan: {
+    width: number;
+    height: number;
+    seconds?: number;
+}): string[];
+/**
+ * Shrink `input` into `out`, and say what the result actually is.
+ *
+ * Throws for exactly one thing: an `input` this cannot measure. That is a bug at
+ * the call site rather than a machine missing a tool — `grabVideo` in harvest
+ * measures the same bytes with the same function before it writes them, and
+ * refuses what it cannot read — and there is no honest box to hand back for a
+ * file whose header says nothing. Everything else that can go wrong comes back
+ * as the original plus a warning.
+ */
+export declare function transcode(input: string, out: string, opts?: TranscodeOptions): Promise<Transcoded>;

package/dist/types/tmpdir.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The directory holding our own `package.json`, found by RESOLVING it rather
+ * than by counting `..` segments off `import.meta.url`.
+ *
+ * The positional form gives the same answer everywhere this module can land
+ * today — `src/` under vitest, and the depth-one bundles `dist/cli.js`,
+ * `dist/mcp.js` and `dist/index.js`, which is the convention `src/version.ts`
+ * relies on and explains at length. The problem is how it FAILS: at any other
+ * depth the root silently becomes `dist/`, nothing is ever inside it, and the
+ * guard turns into a no-op that prints nothing and throws nothing. Nobody would
+ * notice until the directories came back. `require.resolve` throws
+ * MODULE_NOT_FOUND there instead, which is the whole reason for the detour.
+ *
+ * One consequence, stated rather than left to be discovered: in a published
+ * install this resolves to `node_modules/@jokerized/decksmith`, and nobody's
+ * TMPDIR is inside that, so the guard is a deliberate no-op for consumers. It
+ * protects this checkout — the mess is ours. Do NOT "fix" the asymmetry by
+ * testing `process.cwd()`: a user who legitimately works inside their temp
+ * directory would have their `TMPDIR` deleted for it.
+ *
+ * Exported for the test that asserts the depth is still right.
+ */
+export declare function packageRoot(): string;
+/** True when `dir` is the package root or sits inside it, symlinks resolved. */
+export declare function insideRoot(dir: string): boolean;
+/**
+ * Unset a `TMPDIR` that resolves inside the package root, and say so.
+ *
+ * Idempotent by construction rather than by a flag: once the variable is gone
+ * `os.tmpdir()` answers from the platform default, so a second call finds
+ * nothing to do and stays silent.
+ */
+export declare function guardTmpdir(): void;

package/dist/types/types.d.ts

@@ -23,12 +23,19 @@ export declare const refSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const figureSchema: z.ZodObject<{
     id: z.ZodString;
+    kind: z.ZodDefault<z.ZodEnum<{
+        image: "image";
+        clip: "clip";
+    }>>;
     src: z.ZodString;
     caption: z.ZodString;
     width: z.ZodInt;
     height: z.ZodInt;
     sectionId: z.ZodOptional<z.ZodString>;
     mention: z.ZodOptional<z.ZodString>;
+    poster: z.ZodOptional<z.ZodString>;
+    seconds: z.ZodOptional<z.ZodNumber>;
+    href: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const equationSchema: z.ZodObject<{
     id: z.ZodString;
@@ -59,12 +66,19 @@ export declare const sourceSchema: z.ZodObject<{
     }, z.core.$strip>>;
     figures: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
+        kind: z.ZodDefault<z.ZodEnum<{
+            image: "image";
+            clip: "clip";
+        }>>;
         src: z.ZodString;
         caption: z.ZodString;
         width: z.ZodInt;
         height: z.ZodInt;
         sectionId: z.ZodOptional<z.ZodString>;
         mention: z.ZodOptional<z.ZodString>;
+        poster: z.ZodOptional<z.ZodString>;
+        seconds: z.ZodOptional<z.ZodNumber>;
+        href: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     equations: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
@@ -191,6 +205,13 @@ export declare const lineChartParamsSchema: z.ZodObject<{
     }, z.core.$strip>>;
     deltas: z.ZodOptional<z.ZodArray<z.ZodString>>;
     readout: z.ZodOptional<z.ZodString>;
+    compare: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        points: z.ZodArray<z.ZodObject<{
+            x: z.ZodString;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const calloutParamsSchema: z.ZodObject<{
     eyebrow: z.ZodOptional<z.ZodString>;
@@ -595,6 +616,13 @@ export declare const beatSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strip>>;
         deltas: z.ZodOptional<z.ZodArray<z.ZodString>>;
         readout: z.ZodOptional<z.ZodString>;
+        compare: z.ZodOptional<z.ZodObject<{
+            label: z.ZodString;
+            points: z.ZodArray<z.ZodObject<{
+                x: z.ZodString;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
     id: z.ZodString;
     intent: z.ZodString;
@@ -1194,6 +1222,13 @@ export declare const storyboardSchema: z.ZodObject<{
             }, z.core.$strip>>;
             deltas: z.ZodOptional<z.ZodArray<z.ZodString>>;
             readout: z.ZodOptional<z.ZodString>;
+            compare: z.ZodOptional<z.ZodObject<{
+                label: z.ZodString;
+                points: z.ZodArray<z.ZodObject<{
+                    x: z.ZodString;
+                    y: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
         }, z.core.$strip>;
         id: z.ZodString;
         intent: z.ZodString;
@@ -1720,12 +1755,19 @@ export declare const packSchema: z.ZodObject<{
         }, z.core.$strip>>;
         figures: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
+            kind: z.ZodDefault<z.ZodEnum<{
+                image: "image";
+                clip: "clip";
+            }>>;
             src: z.ZodString;
             caption: z.ZodString;
             width: z.ZodInt;
             height: z.ZodInt;
             sectionId: z.ZodOptional<z.ZodString>;
             mention: z.ZodOptional<z.ZodString>;
+            poster: z.ZodOptional<z.ZodString>;
+            seconds: z.ZodOptional<z.ZodNumber>;
+            href: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         equations: z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -1960,6 +2002,13 @@ export declare const packSchema: z.ZodObject<{
                 }, z.core.$strip>>;
                 deltas: z.ZodOptional<z.ZodArray<z.ZodString>>;
                 readout: z.ZodOptional<z.ZodString>;
+                compare: z.ZodOptional<z.ZodObject<{
+                    label: z.ZodString;
+                    points: z.ZodArray<z.ZodObject<{
+                        x: z.ZodString;
+                        y: z.ZodNumber;
+                    }, z.core.$strip>>;
+                }, z.core.$strip>>;
             }, z.core.$strip>;
             id: z.ZodString;
             intent: z.ZodString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jokerized/decksmith",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Turn a source document into an animated explanation deck.",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,7 @@
     "commander": "^14.0.1",
     "fflate": "^0.8.3",
     "gsap": "^3.14.2",
-    "hyperframes": "0.8.27",
+    "hyperframes": "0.8.33",
     "katex": "^0.16.11",
     "puppeteer-core": "^25.3.0",
     "remark-gfm": "^4.0.1",