npm - ossclip - Versions diffs - 0.1.3 → 0.1.5 - Mend

ossclip 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/editor-dist/assets/{index-B5H_dKAW.js → index-DZhkQB1i.js} +24 -24
package/editor-dist/index.html +1 -1
package/package.json +4 -4
package/src/doctor.ts +31 -9
package/src/index.ts +56 -4
package/src/open.ts +30 -0
package/src/produce.ts +121 -14
package/src/setup/download.ts +122 -0
package/src/setup/extract.ts +91 -0
package/src/setup/manifest.ts +159 -0
package/src/setup/plan.ts +211 -0
package/src/setup/provider.ts +51 -0
package/src/setup/setup.ts +233 -0

package/editor-dist/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ossclip editor</title>
-    <script type="module" crossorigin src="/assets/index-B5H_dKAW.js"></script>
+    <script type="module" crossorigin src="/assets/index-DZhkQB1i.js"></script>
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Local-first CLI video producer: cuts silence and fillers, word-timed captions, face-aware framing, and LLM-planned code-rendered graphics — transcription and rendering never leave your machine",
   "type": "module",
   "license": "MIT",
@@ -35,9 +35,9 @@
     "commander": "^12.1.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76",
-    "@ossclip/scenes": "0.1.3",
-    "@ossclip/core": "0.1.3",
-    "@ossclip/renderer": "0.1.3"
+    "@ossclip/core": "0.1.5",
+    "@ossclip/scenes": "0.1.5",
+    "@ossclip/renderer": "0.1.5"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/doctor.ts CHANGED Viewed

@@ -10,6 +10,11 @@ import type { OssclipConfig } from "@ossclip/core";
  * every one that fails silently becomes a GitHub issue instead of a
  * one-line fix the tool could have printed itself.
  *
+ * Since `ossclip setup` exists, doctor and setup are two halves of one
+ * contract: setup is the fix doctor prints first, and doctor is the
+ * verification setup ends with. The manual command stays on every fix line
+ * for people who'd rather own their toolchain.
+ *
  * Checks are pure over injected probes so the table is unit-testable; the
  * CLI wires the real spawn/existsSync in. The provider check MUST run after
  * `loadEnvFiles` (R16 §77) or a key living in `.env` reports a false
@@ -36,9 +41,18 @@ export interface DoctorProbes {
   editorPageDir: string | null;
 }
-/** brew on mac, apt elsewhere — the generic hint covers the rest. */
-const installHint = (platform: NodeJS.Platform, brew: string, apt: string, generic: string): string =>
-  platform === "darwin" ? brew : platform === "linux" ? apt : generic;
+/** brew on mac, apt on linux, winget/prebuilt on windows — generic covers the rest. */
+const installHint = (
+  platform: NodeJS.Platform,
+  brew: string,
+  apt: string,
+  win: string,
+  generic: string,
+): string =>
+  platform === "darwin" ? brew : platform === "linux" ? apt : platform === "win32" ? win : generic;
+/** Every installable prerequisite leads with the one-command ramp. */
+const viaSetup = (manual: string): string => "run `ossclip setup` — or manually: " + manual;
 export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<DoctorCheck[]> {
   const checks: DoctorCheck[] = [];
@@ -60,13 +74,15 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
     ...(ffmpegOk
       ? {}
       : {
-          fix:
+          fix: viaSetup(
             installHint(
               p.platform,
               "brew install ffmpeg",
               "sudo apt install ffmpeg",
+              "winget install ffmpeg",
               "install ffmpeg from https://ffmpeg.org",
             ) + " — or point OSSCLIP_FFMPEG (or config.json ffmpegPath) at the binary",
+          ),
         }),
   });
@@ -78,13 +94,15 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
     ...(ffprobeOk
       ? {}
       : {
-          fix:
+          fix: viaSetup(
             installHint(
               p.platform,
               "brew install ffmpeg (provides ffprobe)",
               "sudo apt install ffmpeg (provides ffprobe)",
+              "winget install ffmpeg (provides ffprobe)",
               "ffprobe ships with ffmpeg — https://ffmpeg.org",
             ) + " — or set OSSCLIP_FFPROBE",
+          ),
         }),
   });
@@ -96,13 +114,15 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
     ...(whisperOk
       ? {}
       : {
-          fix:
+          fix: viaSetup(
             installHint(
               p.platform,
               "brew install whisper-cpp",
-              "build whisper.cpp from source: https://github.com/ggml-org/whisper.cpp",
+              "download a prebuilt from https://github.com/ggml-org/whisper.cpp/releases",
+              "download whisper-blas-bin-x64.zip from https://github.com/ggml-org/whisper.cpp/releases",
               "build whisper.cpp from source: https://github.com/ggml-org/whisper.cpp",
             ) + " — or point OSSCLIP_WHISPER at your whisper-cli",
+          ),
         }),
   });
@@ -117,9 +137,10 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
     ...(modelOk
       ? {}
       : {
-          fix:
+          fix: viaSetup(
             `mkdir -p ${cfg.modelDir} && curl -L -o ${modelPath} ` +
-            `https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${cfg.model}.bin`,
+              `https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${cfg.model}.bin`,
+          ),
         }),
   });
@@ -141,6 +162,7 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
       ? {}
       : {
           fix:
+            "run `ossclip setup` (it can save a key for you), or " +
             "export ANTHROPIC_API_KEY or GEMINI_API_KEY (a .env file works — see README), " +
             "or install Claude Code (https://claude.com/claude-code) and log in",
         }),

package/src/index.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 #!/usr/bin/env tsx
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { Command, InvalidArgumentError } from "commander";
 import { z } from "zod/v4";
 import { CleanupLevelSchema, SceneComponentIdSchema } from "@ossclip/core";
@@ -110,6 +110,11 @@ program
     "--source-is-edited",
     "the source is already an edited reel with burned-in text — keep ossclip's graphics off it without waiting on detection",
   )
+  .option(
+    "--blooper-marker <word>",
+    "cut the flubbed take whenever you say this word out loud (e.g. blooper): " +
+      "removal runs back to the start of the sentence it spoiled. Off unless given",
+  )
   .option("--no-cover", "skip the cover image written beside the video")
   .option("--cover <path>", "cover image output path (default: <out>.cover.jpg)")
   .action(async (input: string, opts) => {
@@ -148,6 +153,7 @@ program
       // commander gives `--no-cover` as cover:false and `--cover <path>` as a
       // string on the same key.
       sourceIsEdited: opts.sourceIsEdited === true,
+      blooperMarker: opts.blooperMarker,
       sourceFit,
       cover: opts.cover !== false,
       coverPath: typeof opts.cover === "string" ? opts.cover : undefined,
@@ -186,11 +192,38 @@ program
   .action(async (renderProps: string, opts) => {
     const propsPath = resolve(renderProps);
     const publicDir = opts.videoDir ? resolve(opts.videoDir) : dirname(propsPath);
+    // Resolve Remotion's CLI through module resolution instead of spawning
+    // `pnpm` — a global `npm i -g ossclip` has no pnpm and no workspace, and
+    // Windows would need the .cmd shim. `@remotion/cli` is a dependency of
+    // @ossclip/renderer, so resolving from THERE works in both a clone and a
+    // published install, on every OS, run via the node that's running us.
+    const { createRequire } = await import("node:module");
+    let remotionCliJs: string;
+    try {
+      const require = createRequire(import.meta.url);
+      const rendererDir = dirname(require.resolve("@ossclip/renderer/package.json"));
+      const fromRenderer = createRequire(join(rendererDir, "package.json"));
+      const cliPkgPath = fromRenderer.resolve("@remotion/cli/package.json");
+      const cliPkg = JSON.parse(readFileSync(cliPkgPath, "utf8")) as {
+        bin: string | Record<string, string>;
+      };
+      const binRel = typeof cliPkg.bin === "string" ? cliPkg.bin : cliPkg.bin.remotion;
+      if (!binRel) throw new Error("no remotion bin entry");
+      remotionCliJs = join(dirname(cliPkgPath), binRel);
+    } catch {
+      throw new Error(
+        "couldn't resolve @remotion/cli — in a clone, run `pnpm install` first",
+      );
+    }
     const child = spawn(
-      "pnpm",
-      ["exec", "remotion", "studio", STUDIO_ENTRY, `--props=${propsPath}`, `--public-dir=${publicDir}`],
+      process.execPath,
+      [remotionCliJs, "studio", STUDIO_ENTRY, `--props=${propsPath}`, `--public-dir=${publicDir}`],
       { stdio: "inherit" },
     );
+    child.on("error", (e) => {
+      console.error(`✗ failed to start Remotion Studio: ${e.message}`);
+      process.exit(1);
+    });
     child.on("exit", (code) => process.exit(code ?? 0));
   });
@@ -218,7 +251,26 @@ program
     }
     const server = await startEditServer(workdir, { port: opts.port, pageDir });
     console.log(`▸ editor at ${server.url}`);
-    if (opts.open) spawn("open", [server.url], { stdio: "ignore" });
+    if (opts.open) {
+      const { openInBrowser } = await import("./open");
+      openInBrowser(server.url);
+    }
+  });
+program
+  .command("setup")
+  .description(
+    "install everything ossclip needs (ffmpeg, whisper.cpp, the transcription model) " +
+      "into ~/.ossclip — the one-command onboarding on macOS, Linux, and Windows",
+  )
+  .option("--model <name>", "transcription model to download (default: config, i.e. small.en)")
+  .option("--skip-llm", "don't ask about an LLM provider (only --produce needs one)", false)
+  .option("--force", "re-download the pieces setup manages, even if present", false)
+  .option("-y, --yes", "no questions — accept the plan and skip the provider prompt", false)
+  .action(async (opts) => {
+    if (envFiles.length > 0) console.log(`▸ env: ${envFiles.join(", ")}`);
+    const { setup } = await import("./setup/setup");
+    await setup({ model: opts.model, skipLlm: opts.skipLlm, force: opts.force, yes: opts.yes });
   });
 program

package/src/open.ts ADDED Viewed

@@ -0,0 +1,30 @@
+import { spawn } from "node:child_process";
+/**
+ * Open a URL in the default browser, per platform. The old code spawned
+ * macOS's `open` unconditionally — on Linux and Windows that ENOENT became
+ * an unhandled 'error' event and took the whole edit server down with it.
+ *
+ * Failure here is not an error: a headless box or WSL without a browser is
+ * a normal place to run `ossclip edit` — print the URL and move on.
+ */
+export function openCommand(
+  url: string,
+  platform: NodeJS.Platform,
+): { bin: string; args: string[] } {
+  if (platform === "darwin") return { bin: "open", args: [url] };
+  if (platform === "win32") {
+    // `start` is a cmd built-in, not an executable; the empty string is
+    // start's window-title slot so the URL isn't eaten as the title.
+    return { bin: "cmd", args: ["/c", "start", "", url] };
+  }
+  return { bin: "xdg-open", args: [url] };
+}
+export function openInBrowser(url: string, platform: NodeJS.Platform = process.platform): void {
+  const { bin, args } = openCommand(url, platform);
+  const child = spawn(bin, args, { stdio: "ignore", detached: false });
+  child.on("error", () => {
+    console.log(`▸ couldn't open a browser here — open ${url} yourself`);
+  });
+}

package/src/produce.ts CHANGED Viewed

@@ -37,6 +37,9 @@ import {
   splitCues,
   landscapeLayout,
   formatCutReport,
+  formatGraphicsAccounting,
+  findBloopSpans,
+  formatBloopSpan,
   formatUsageLine,
   formatUsageReport,
   loadConfig,
@@ -73,6 +76,7 @@ import {
   sliceTranscript,
   type Analysis,
   type AppliedRepair,
+  type BeatsValidationIssue,
   type CleanupLevel,
   type ClipWindow,
   type LlmProvider,
@@ -125,6 +129,11 @@ export interface ProduceOptions {
   coverPath?: string;
   /** Treat the source as an already-edited reel with burned-in graphics. */
   sourceIsEdited?: boolean;
+  /**
+   * Spoken blooper marker (R27 §122) — `--blooper-marker blooper`. Saying it
+   * on camera cuts the attempt it spoiled, back to that sentence's start.
+   */
+  blooperMarker?: string;
   /**
    * How the source meets the vertical frame. `cover` (default) crops it to
    * fill; `contain` shows the WHOLE frame inset against the backdrop, which is
@@ -206,8 +215,8 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
     throw new Error("--clip-window is recorded by --clip runs for replay — pass --clip too.");
   }
-  await preflight(cfg.ffmpegPath, "Install ffmpeg (brew install ffmpeg / apt install ffmpeg) or set OSSCLIP_FFMPEG.");
-  await preflight(cfg.ffprobePath, "Install ffmpeg (provides ffprobe) or set OSSCLIP_FFPROBE.");
+  await preflight(cfg.ffmpegPath, "Run `ossclip setup`, install ffmpeg yourself (brew/apt/winget), or set OSSCLIP_FFMPEG.");
+  await preflight(cfg.ffprobePath, "Run `ossclip setup`, install ffmpeg (provides ffprobe), or set OSSCLIP_FFPROBE.");
   // The output frame — every rect downstream is a fraction of THIS, and the
   // stage geometry now takes it as an argument rather than assuming portrait.
@@ -278,14 +287,15 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
   } else {
     await preflight(
       cfg.whisperPath,
-      "Install whisper.cpp (https://github.com/ggml-org/whisper.cpp) or set OSSCLIP_WHISPER.",
+      "Run `ossclip setup`, install whisper.cpp yourself (https://github.com/ggml-org/whisper.cpp), or set OSSCLIP_WHISPER.",
     );
     const model = opts.whisperModel ?? cfg.model;
     const modelPath = isAbsolute(model) ? model : join(cfg.modelDir, `ggml-${model}.bin`);
     if (!existsSync(modelPath)) {
       throw new Error(
         `whisper model not found at ${modelPath}.\n` +
-          `Download one, e.g.:\n  curl -L -o ${modelPath} https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${model}.bin`,
+          `Run \`ossclip setup${model === cfg.model ? "" : ` --model ${model}`}\` to download it — or manually:\n` +
+          `  curl -L -o ${modelPath} https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${model}.bin`,
       );
     }
     console.log(`▸ transcribing (${basename(modelPath)})…`);
@@ -310,11 +320,25 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
   // `let`, not `const` (R19 §93): a clip run re-derives all three from the
   // transcript sliced to the chosen window, further down.
   let analysis: Analysis = analyze(transcript, silences, sourceProbe.duration, levels);
+  // Spoken blooper markers (R27 §122). Detected on the RAW transcript, before
+  // repair — the repair pass reads a bare "blooper." as an oddity and has
+  // already been observed proposing "break loop." for it. Detecting first
+  // means the marker cannot be rewritten out from under the detector.
+  let bloops = opts.blooperMarker ? findBloopSpans(transcript, opts.blooperMarker) : [];
+  if (opts.blooperMarker) {
+    console.log(
+      bloops.length > 0
+        ? `▸ blooper marker "${opts.blooperMarker}": ${bloops.length} take(s) cut`
+        : `▸ blooper marker "${opts.blooperMarker}": never said — nothing cut`,
+    );
+    for (const b of bloops) console.log(`  ▸ ${formatBloopSpan(transcript, b)}`);
+  }
   let cutlist: Segment[] = buildCutlist({
     transcript,
     analysis,
     duration: sourceProbe.duration,
     level: opts.cleanup,
+    bloops,
   });
   let map = new TimeMap(cutlist);
@@ -446,6 +470,11 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
   let scenes: Scene[] = [];
   /** Editorial output kept for the cover (§31): hook + its thumbnail form. */
   let beatSheet: { hook: string; coverText?: string } | undefined;
+  /** The graphics accounting line for report.txt (§118b), and the beat-sheet
+   * issues that explain it. Cached alongside the beat sheet so a cached
+   * re-run's report keeps the accounting instead of erasing it (§78). */
+  let graphicsLine: string | undefined;
+  let beatIssues: BeatsValidationIssue[] = [];
   /** Who planned this run (R16 §78) — stamped into production.json below. */
   let producerStamp: Production["producer"];
   /** The resolved `--clip` window (R19 §93) — set only on a clip run; feeds
@@ -543,12 +572,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
       rawTranscript = rawSlice.transcript;
       transcript = sliceTranscript(transcript, clipWindow);
       analysis = analyze(rawTranscript, silences, sourceProbe.duration, levels);
+      // Re-detect on the SLICE: word indices moved, so the spans found against
+      // the full take no longer address the same words.
+      bloops = opts.blooperMarker ? findBloopSpans(rawTranscript, opts.blooperMarker) : [];
       cutlist = boundCutlistToWindow(
         buildCutlist({
           transcript: rawTranscript,
           analysis,
           duration: sourceProbe.duration,
           level: opts.cleanup,
+          bloops,
         }),
         clipWindow,
         sourceProbe.duration,
@@ -599,13 +632,33 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
       for (const issue of clipFresh.beatIssues) {
         console.log(`  ⚠ moment ${issue.moment}: ${issue.issue}`);
       }
+      beatIssues = clipFresh.beatIssues;
+      // `transcript` is the slice here — the space the accounting was made in.
+      graphicsLine = formatGraphicsAccounting(
+        clipFresh.graphics.delivered,
+        clipFresh.graphics.asked,
+        transcript,
+      );
       await writeFile(sceneCache, JSON.stringify(scenes, null, 2));
-      await writeFile(beatCache, JSON.stringify(beatSheet, null, 2));
+      await writeFile(
+        beatCache,
+        JSON.stringify({ ...beatSheet, graphics: graphicsLine, issues: beatIssues }, null, 2),
+      );
     } else if (existsSync(sceneCache)) {
       scenes = z.array(SceneSchema).parse(JSON.parse(await readFile(sceneCache, "utf8")));
       console.log(`▸ scenes cached (${scenes.length})`);
       if (existsSync(beatCache)) {
-        beatSheet = JSON.parse(await readFile(beatCache, "utf8")) as typeof beatSheet;
+        // Pre-§118b caches carry no accounting — the report then simply
+        // omits the graphics section rather than guessing one.
+        const cached = JSON.parse(await readFile(beatCache, "utf8")) as {
+          hook: string;
+          coverText?: string;
+          graphics?: string;
+          issues?: BeatsValidationIssue[];
+        };
+        beatSheet = { hook: cached.hook, coverText: cached.coverText };
+        graphicsLine = cached.graphics;
+        beatIssues = cached.issues ?? [];
       }
     } else {
       console.log(`▸ producing scenes (${providerName})…`);
@@ -629,11 +682,20 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
       for (const issue of result.beatIssues) {
         console.log(`  ⚠ moment ${issue.moment}: ${issue.issue}`);
       }
+      beatIssues = result.beatIssues;
+      graphicsLine = formatGraphicsAccounting(
+        result.graphics.delivered,
+        result.graphics.asked,
+        transcript,
+      );
       // Cache props only — overrides are user-owned and live in overrides.json,
       // never in production.json (that file is derived and every `produce`
       // run overwrites it, per the merge rule in `overrides.ts`).
       await writeFile(sceneCache, JSON.stringify(scenes, null, 2));
-      await writeFile(beatCache, JSON.stringify(beatSheet, null, 2));
+      await writeFile(
+        beatCache,
+        JSON.stringify({ ...beatSheet, graphics: graphicsLine, issues: beatIssues }, null, 2),
+      );
     }
   }
@@ -828,12 +890,23 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
   // existing one — cropping through the source's title and then restating it
   // underneath. Graphics move to a clear slot or are skipped; captions never
   // are, they just relocate.
-  const sourceText = await scanSourceText(tools, analysisInput, analysisProbe.duration, {
-    cacheDir: work,
-    assumeEdited: opts.sourceIsEdited,
-    cropVf: analysisCropVf,
-    cacheTag,
-  });
+  //
+  // Behind --source-is-edited since R27 §120. The detector cannot tell burned-in
+  // GRAPHICS from text that is simply in the room, and on a raw take at a desk
+  // it read the background monitors as 45 bands of "source text". The cost is
+  // not cosmetic: every graphic was then moved and SHRUNK to a free band —
+  // a BulletList pinned to its 36px font floor, a FlowDiagram's slot halved
+  // (0.54 → 0.27, type 71 → 35), and a ScreenshotFrame slid onto the speaker's
+  // face. Routing around a hazard only pays when there is a hazard, and only
+  // the user knows whether their source is already edited.
+  const sourceText = opts.sourceIsEdited
+    ? await scanSourceText(tools, analysisInput, analysisProbe.duration, {
+        cacheDir: work,
+        assumeEdited: true,
+        cropVf: analysisCropVf,
+        cacheTag,
+      })
+    : { regions: [], assumed: false, framesSampled: 0 };
   if (sourceText.regions.length > 0) {
     console.log(
       sourceText.assumed
@@ -965,7 +1038,21 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
   // Grounding post-check (FINDINGS §14a): flags label tokens the take never
   // says — a hallucinated hook label is visible here without watching the video.
-  const groundingIssues = checkGrounding(scenes, transcript, opts.speaker ?? cfg.speaker);
+  //
+  // Checked against the copy that will actually RENDER, overrides included
+  // (R27 §124). It used to read the producer's raw scenes, so it was wrong in
+  // both directions: it kept reporting invented copy the user had already
+  // fixed by hand — the warning outlived the defect, which teaches people to
+  // ignore warnings — and it never looked at copy the user typed themselves.
+  // `checkGrounding` already merges a scene's `overrides` slot; nothing was
+  // filling it from `overrides.json`.
+  const scenesAsRendered = scenes.map((s) => {
+    const edit = overrideDoc.scenes[s.id]?.props;
+    return edit && Object.keys(edit).length > 0
+      ? { ...s, overrides: { ...s.overrides, ...edit } }
+      : s;
+  });
+  const groundingIssues = checkGrounding(scenesAsRendered, transcript, opts.speaker ?? cfg.speaker);
   for (const g of groundingIssues) {
     console.log(`  ⚠ grounding: ${g.component} ${g.sceneId} ${g.field} "${g.token}" — not in the take`);
   }
@@ -1050,6 +1137,14 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
       `${((dur / sourceProbe.duration) * 100).toFixed(0)}% of the take)\n` +
       `  reason: ${clipWindow.reason}\n`;
   }
+  // §122: a cut that takes whole sentences owes the user the words it took —
+  // the timestamps above say WHERE, not what was lost.
+  if (bloops.length > 0) {
+    report +=
+      `\nbloopers cut (you said "${opts.blooperMarker}" — FINDINGS §122):\n` +
+      bloops.map((b) => `  ${formatBloopSpan(rawTranscript, b)}`).join("\n") +
+      "\n";
+  }
   const landed = repairs.filter((r) => r.applied);
   if (landed.length > 0) {
     report +=
@@ -1072,6 +1167,18 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
         .join("\n") +
       "\n";
   }
+  // §118b: the graphics count justified in the artefact, like every cut is —
+  // delivered vs asked and why, then the scheduler's own account of what it
+  // demoted. The shortfall issue repeats the accounting line, so it is the
+  // one issue not reprinted here.
+  if (graphicsLine) {
+    report +=
+      `\n${graphicsLine} (FINDINGS §118)\n` +
+      beatIssues
+        .filter((i) => !i.issue.startsWith("graphics:"))
+        .map((i) => `  ⚠ moment ${i.moment}: ${i.issue}\n`)
+        .join("");
+  }
   if (provider) {
     report += formatUsageReport(provider.usage, cfg.pricing);
     // A cached run has no usage block to print, and used to leave the report

package/src/setup/download.ts ADDED Viewed

@@ -0,0 +1,122 @@
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+/**
+ * Download with resume + integrity check — the model is a 466 MB file and
+ * "my wifi dropped at 91%" must not mean starting over.
+ *
+ * Writes `<dest>.part`, resumes with a Range header when a partial exists
+ * (GitHub and Hugging Face both honor ranges; a server that answers 200
+ * instead of 206 restarts cleanly), verifies the hash of the COMPLETE file
+ * before renaming into place — a `.part` never becomes a `dest` unverified.
+ */
+export interface DownloadOptions {
+  /** hex digest; algorithm chosen by which field is set */
+  sha256?: string;
+  sha1?: string;
+  onProgress?: (doneBytes: number, totalBytes: number | null) => void;
+  /** injected in tests */
+  fetchImpl?: typeof fetch;
+}
+export async function download(url: string, dest: string, opts: DownloadOptions = {}): Promise<void> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const part = `${dest}.part`;
+  mkdirSync(dirname(dest), { recursive: true });
+  let offset = 0;
+  try {
+    offset = statSync(part).size;
+  } catch {
+    // no partial — fresh download
+  }
+  const headers: Record<string, string> = {};
+  if (offset > 0) headers.Range = `bytes=${offset}-`;
+  const res = await fetchImpl(url, { headers, redirect: "follow" });
+  if (res.status === 200) {
+    offset = 0; // server ignored the range — start over
+  } else if (res.status !== 206) {
+    throw new Error(`download failed: HTTP ${res.status} for ${url}`);
+  }
+  if (!res.body) throw new Error(`download failed: empty body for ${url}`);
+  const lengthHeader = res.headers.get("content-length");
+  const total = lengthHeader ? offset + Number.parseInt(lengthHeader, 10) : null;
+  const out = createWriteStream(part, offset > 0 ? { flags: "a" } : {});
+  let done = offset;
+  const reader = res.body.getReader();
+  try {
+    for (;;) {
+      const { value, done: finished } = await reader.read();
+      if (finished) break;
+      if (value) {
+        done += value.length;
+        if (!out.write(value)) {
+          await new Promise<void>((r) => out.once("drain", () => r()));
+        }
+        opts.onProgress?.(done, total);
+      }
+    }
+  } finally {
+    await new Promise<void>((r) => out.end(() => r()));
+  }
+  const algo = opts.sha256 ? "sha256" : opts.sha1 ? "sha1" : null;
+  const expected = opts.sha256 ?? opts.sha1;
+  if (algo && expected) {
+    const actual = await hashFile(part, algo);
+    if (actual !== expected.toLowerCase()) {
+      // A corrupt partial would resume corrupt forever — a mismatch removes it.
+      const { rmSync } = await import("node:fs");
+      rmSync(part, { force: true });
+      throw new Error(
+        `checksum mismatch for ${url}\n  expected ${algo} ${expected}\n  got      ${actual}\n` +
+          "The partial download was removed — re-run to try again.",
+      );
+    }
+  }
+  renameSync(part, dest);
+}
+export function hashFile(path: string, algo: "sha256" | "sha1"): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const hash = createHash(algo);
+    createReadStream(path)
+      .on("data", (chunk) => hash.update(chunk))
+      .on("error", reject)
+      .on("end", () => resolve(hash.digest("hex")));
+  });
+}
+/**
+ * Single rewritten stderr line: `▸ ggml-small.en.bin  312/466 MB  67%`.
+ * Piped output (CI logs) gets a plain line every 10% instead — `\r` doesn't
+ * rewrite in a captured log, it accumulates.
+ */
+export function progressLine(label: string): (done: number, total: number | null) => void {
+  const tty = process.stderr.isTTY === true;
+  const stepPct = tty ? 1 : 10;
+  let lastPct = -1;
+  let lastMB = -1;
+  return (done, total) => {
+    const doneMB = Math.round(done / 1e6);
+    if (total === null) {
+      if (doneMB !== lastMB && doneMB % 25 === 0) {
+        lastMB = doneMB;
+        process.stderr.write(`${tty ? "\r" : ""}▸ ${label}  ${doneMB} MB${tty ? "" : "\n"}`);
+      }
+      return;
+    }
+    const pct = Math.floor((done / total) * 100);
+    if (pct === lastPct || pct % stepPct !== 0) return;
+    lastPct = pct;
+    const totalMB = Math.round(total / 1e6);
+    const line = `▸ ${label}  ${doneMB}/${totalMB} MB  ${pct}%`;
+    process.stderr.write(tty ? `\r${line}${pct === 100 ? "\n" : ""}` : `${line}\n`);
+  };
+}