@ossclip/core 0.1.25 → 0.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/browser.ts

@@ -46,4 +46,10 @@ export {
 // array, to decide whether a repair is possible at all — see
 // `anchorCaptionLines` (§137): a non-empty array can still build an empty map.
 export { mapFromKeptSpans, TimeMap, type KeptSpan } from "./timemap";
+// The §35 cover word cap. The editor's CoverPanel shows the trimmed headline
+// live as you type, and restating the trimming rules there would drift from
+// the one the regenerate endpoint actually renders with. Imported from
+// ./cover-headline, NOT ./cover — that module is node all the way down
+// (node:fs, ./exec), which is exactly what this surface exists to keep out.
+export { COVER_MAX_WORDS, coverHeadline } from "./cover-headline";
 export type { Probe, Production, RenderSettings, Segment, Transcript, Word } from "./schema";

package/src/concat.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { z } from "zod/v4";
 import { probe, type IngestTools } from "./ingest";
 import { run } from "./exec";
@@ -42,6 +42,78 @@ export interface ConcatEntry {
   size: number;
 }
 
+/**
+ * Whether a produce output path lands INSIDE the folder being produced.
+ * 2026-08-18 field cascade: a folder input's clips are re-enumerated on
+ * EVERY run, so an `--out` written into that folder became a 7th "source
+ * clip" on the next run — the folder-content hash changed, produce minted a
+ * fresh workdir with EMPTY overrides, and the render silently dropped the
+ * user's saved edits while the output's duration doubled. It cascaded three
+ * times before the doubling duration was connected to the out path.
+ *
+ * Containment via `path.relative`, the same idiom as edit.ts's `isInside`:
+ * a `startsWith` string-prefix test has no separator boundary and is fooled
+ * by a sibling folder that merely shares a prefix (`/a/Clips` vs
+ * `/a/Clips-old/out.mp4`) — `child` is inside `parent` iff the relative path
+ * from one to the other never has to climb out with `..`. Both arguments are
+ * resolved here so a relative path is judged against cwd; `~` expansion is
+ * the CALLER's job (the 2026-08-16 rule in the CLI's paths.ts — expandHome
+ * at the call site — which also keeps core homedir-free).
+ */
+export function outPathInsideInput(outPath: string, inputDir: string): boolean {
+  const rel = relative(resolve(inputDir), resolve(outPath));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * The refusal for `outPathInsideInput`, shared verbatim by produce's own
+ * gate and the edit server's `/api/render` 400 — one message, one place, so
+ * the two boundaries can never describe the same hazard differently. Names
+ * the actual risk (the field cascade above) rather than just "invalid path",
+ * and suggests the exact default a flag-less run would pick (produce's
+ * `defaultOutPath` shape: at most the LAST dot-segment replaced).
+ */
+/**
+ * The default output path for an input: beside it, `.ossclip.mp4` suffix.
+ * Trailing separators are stripped FIRST (2026-08-18 field case, second
+ * report): shells tab-complete folders with the slash, and the bare regex
+ * appended after it — the "default" landed INSIDE the folder as a hidden
+ * `.ossclip.mp4` dotfile, the exact self-ingesting shape
+ * `outPathInsideInput` exists to refuse. One definition shared by produce's
+ * `defaultOutPath` and the refusal message below, so the suggestion can
+ * never disagree with what omitting `--out` actually does.
+ */
+export function ossclipOutputPathFor(input: string): string {
+  return input.replace(/[/\\]+$/, "").replace(/(\.[^.]+)?$/, ".ossclip.mp4");
+}
+
+export function outInsideInputFolderMessage(folder: string): string {
+  const suggestion = ossclipOutputPathFor(folder);
+  return (
+    `refusing to write the output inside the input folder ${folder} — the next ` +
+    `run would ingest this output as a source clip and re-plan from scratch, ` +
+    `abandoning your edits (the folder's content hash changes, so produce mints ` +
+    `a fresh workdir with empty overrides). Write it beside the folder instead, ` +
+    `e.g. --out ${suggestion}`
+  );
+}
+
+/**
+ * Defense-in-depth BEHIND the out-path refusal above (same 2026-08-18 field
+ * cascade): a produce output already sitting in the folder — written by a
+ * pre-fix run, or moved there by hand — must never be ingested as a source
+ * clip, and must be filtered BEFORE `folderManifestKey` sees the entries so
+ * its presence can't re-key the workdir either. Matches any name carrying
+ * the `.ossclip` marker: `X.ossclip.mp4`, `X.ossclip_fixed.mp4`, and
+ * `X.ossclip.mp4.partial.mp4` leftovers all qualify (bare `.ossclip.mp4` is
+ * a dotfile and already skipped upstream). A custom-named output
+ * (`--out final.mp4`) is undetectable here — the out-path refusal is the
+ * real gate; this only keeps a pre-fix folder from compounding further.
+ */
+export function isOssclipOutputName(name: string): boolean {
+  return name.includes(".ossclip");
+}
+
 /**
  * Order clips for concatenation. `name` (default, per the field request "sort
  * them by name or date modified, name being default") is a PLAIN codepoint
@@ -321,6 +393,8 @@ export interface FolderListing {
   entries: ConcatEntry[];
   /** Files skipped for not matching a video extension (dotfiles excluded). */
   nonVideoCount: number;
+  /** Video files skipped as produce's own outputs (`isOssclipOutputName`). */
+  ossclipOutputCount: number;
 }
 
 /**
@@ -339,6 +413,7 @@ export interface FolderListing {
 export async function listFolderVideos(folder: string): Promise<FolderListing> {
   const dirents = await readdir(folder, { withFileTypes: true });
   let nonVideoCount = 0;
+  let ossclipOutputCount = 0;
   const entries: ConcatEntry[] = [];
   for (const d of dirents) {
     if (d.name.startsWith(".")) continue;
@@ -357,11 +432,19 @@ export async function listFolderVideos(folder: string): Promise<FolderListing> {
       nonVideoCount++;
       continue;
     }
+    // Skipped HERE, before the entries ever exist — never in concatFolder —
+    // so an ossclip output left in the folder can neither become a source
+    // clip nor perturb the workdir hash `folderManifestKey` derives from
+    // this listing (2026-08-18 field cascade, see isOssclipOutputName).
+    if (isOssclipOutputName(d.name)) {
+      ossclipOutputCount++;
+      continue;
+    }
     const st = await stat(join(folder, d.name));
     entries.push({ name: d.name, mtimeMs: st.mtimeMs, size: st.size });
   }
   if (entries.length === 0) throw noVideoFilesError(folder);
-  return { entries, nonVideoCount };
+  return { entries, nonVideoCount, ossclipOutputCount };
 }
 
 export interface FolderConcatResult {
@@ -371,6 +454,8 @@ export interface FolderConcatResult {
   clips: Array<{ name: string; durationSec: number }>;
   /** Files skipped for not matching a video extension. */
   nonVideoCount: number;
+  /** Video files skipped as produce's own outputs (`isOssclipOutputName`). */
+  ossclipOutputCount: number;
   /** True when the existing `source-concat.mp4` was reused, not rebuilt. */
   cached: boolean;
   /** The concat's own total duration (ffprobe'd from the output). */
@@ -393,7 +478,7 @@ export async function concatFolder(
   sort: "name" | "mtime",
   target: { w: number; h: number },
 ): Promise<FolderConcatResult> {
-  const { entries: current, nonVideoCount } = listing;
+  const { entries: current, nonVideoCount, ossclipOutputCount } = listing;
   if (current.length === 0) throw noVideoFilesError(folder);
   const order = planFolderConcat(current, sort);
 
@@ -408,6 +493,7 @@ export async function concatFolder(
         path: outPath,
         clips: order.map((name) => ({ name, durationSec: byName.get(name)!.durationSec })),
         nonVideoCount,
+        ossclipOutputCount,
         cached: true,
         durationSec: outProbe.duration,
       };
@@ -461,6 +547,7 @@ export async function concatFolder(
     path: outPath,
     clips: order.map((name, i) => ({ name, durationSec: probes[i]!.duration })),
     nonVideoCount,
+    ossclipOutputCount,
     cached: false,
     durationSec: outProbe.duration,
   };

package/src/cover-headline.ts

@@ -0,0 +1,61 @@
+/**
+ * The cover banner's word cap, and nothing else.
+ *
+ * Split out of `./cover` (2026-08-19) for the reason `content-rect` is split
+ * from `content-rect-detect`: the EDITOR's cover panel shows the trimmed
+ * headline live as you type, so it needs this function at RUNTIME — and it
+ * imports `@ossclip/core/browser`, whose whole contract is "no node built-ins
+ * anywhere in this module graph". `./cover` is node all the way down
+ * (`node:fs`, `./exec`'s child_process), so re-exporting `coverHeadline` from
+ * there would have put ffmpeg's process runner in the Vite bundle.
+ *
+ * Restating the trimming rules in the editor was the alternative and is
+ * strictly worse: the server re-caps whatever the panel sends, so a second
+ * copy would drift into showing a preview the render disagrees with.
+ *
+ * `./cover` re-exports this file, so `@ossclip/core`'s surface is unchanged.
+ */
+
+/**
+ * A cover banner is a headline, not a sentence (FINDINGS §35). The producer
+ * shipped 13 words across five lines by reusing the video's hook verbatim; at
+ * grid-tile size that is unreadable. The reference covers run 4-9 words.
+ *
+ * Stated in the schema AND enforced here, because a `.describe()` is a request
+ * and this is a constraint — the same reason `normalizeBeatSheet` exists.
+ */
+export const COVER_MAX_WORDS = 9;
+
+/** Trailing words that cannot end a headline — the truncation reads as broken. */
+const DANGLING = new Set([
+  "a", "an", "and", "as", "at", "but", "by", "for", "from", "in", "is", "it",
+  "of", "on", "or", "the", "to", "with", "that", "this", "my", "your", "so",
+]);
+
+/**
+ * Cut a headline down to `maxWords`, preferring a natural break.
+ *
+ * A dash or colon usually separates a complete claim from its elaboration, so
+ * the first clause is a real headline rather than a sentence with its end
+ * lopped off. Only when that is still too long does this truncate — and then
+ * it refuses to stop on a preposition or article, which is what makes a
+ * truncation look like a bug instead of an edit.
+ */
+export function coverHeadline(text: string, maxWords = COVER_MAX_WORDS): string {
+  const clean = text.trim().replace(/\s+/g, " ");
+  if (!clean) return clean;
+  const words = (s: string): string[] => s.split(" ").filter(Boolean);
+  if (words(clean).length <= maxWords) return clean;
+
+  // First clause, if it stands on its own — never a two-word fragment. Even
+  // when the clause is itself too long it is the better thing to cut down,
+  // since truncating it can never wander past the dash into the elaboration.
+  const clause = clean.split(/\s*[—–:]\s*|\s+-\s+/)[0]!.trim();
+  const base = words(clause).length >= 3 ? clause : clean;
+  const out = words(base).slice(0, maxWords);
+  while (out.length > 3 && DANGLING.has(out[out.length - 1]!.toLowerCase().replace(/\W/g, ""))) {
+    out.pop();
+  }
+  // A clause that ended on its own punctuation keeps it; a cut does not.
+  return out.join(" ").replace(/[,;:—–-]+$/, "");
+}

package/src/cover.ts

@@ -1,5 +1,7 @@
-import { readFile, unlink } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { z } from "zod/v4";
 import { run } from "./exec";
 
 /**
@@ -15,49 +17,12 @@ import { run } from "./exec";
  * This module picks WHICH frame. The banner is drawn by the renderer.
  */
 
-/**
- * A cover banner is a headline, not a sentence (FINDINGS §35). The producer
- * shipped 13 words across five lines by reusing the video's hook verbatim; at
- * grid-tile size that is unreadable. The reference covers run 4-9 words.
- *
- * Stated in the schema AND enforced here, because a `.describe()` is a request
- * and this is a constraint — the same reason `normalizeBeatSheet` exists.
- */
-export const COVER_MAX_WORDS = 9;
-
-/** Trailing words that cannot end a headline — the truncation reads as broken. */
-const DANGLING = new Set([
-  "a", "an", "and", "as", "at", "but", "by", "for", "from", "in", "is", "it",
-  "of", "on", "or", "the", "to", "with", "that", "this", "my", "your", "so",
-]);
-
-/**
- * Cut a headline down to `maxWords`, preferring a natural break.
- *
- * A dash or colon usually separates a complete claim from its elaboration, so
- * the first clause is a real headline rather than a sentence with its end
- * lopped off. Only when that is still too long does this truncate — and then
- * it refuses to stop on a preposition or article, which is what makes a
- * truncation look like a bug instead of an edit.
- */
-export function coverHeadline(text: string, maxWords = COVER_MAX_WORDS): string {
-  const clean = text.trim().replace(/\s+/g, " ");
-  if (!clean) return clean;
-  const words = (s: string): string[] => s.split(" ").filter(Boolean);
-  if (words(clean).length <= maxWords) return clean;
-
-  // First clause, if it stands on its own — never a two-word fragment. Even
-  // when the clause is itself too long it is the better thing to cut down,
-  // since truncating it can never wander past the dash into the elaboration.
-  const clause = clean.split(/\s*[—–:]\s*|\s+-\s+/)[0]!.trim();
-  const base = words(clause).length >= 3 ? clause : clean;
-  const out = words(base).slice(0, maxWords);
-  while (out.length > 3 && DANGLING.has(out[out.length - 1]!.toLowerCase().replace(/\W/g, ""))) {
-    out.pop();
-  }
-  // A clause that ended on its own punctuation keeps it; a cut does not.
-  return out.join(" ").replace(/[,;:—–-]+$/, "");
-}
+// The §35 word cap lives in ./cover-headline — this file is node all the way
+// down (node:fs, ./exec's child_process) and the EDITOR's cover panel needs
+// `coverHeadline` at runtime through @ossclip/core/browser, which forbids a
+// node built-in anywhere in its graph. Re-exported here so `@ossclip/core`'s
+// surface is exactly what it was.
+export { COVER_MAX_WORDS, coverHeadline } from "./cover-headline";
 
 /**
  * What the cover step should emit.
@@ -190,6 +155,56 @@ export interface PickCoverOptions {
   subject?: "face" | "screen";
 }
 
+/**
+ * Measure ONE candidate frame: extract it at `timeSec` through the crop math,
+ * score its sharpness, and locate the face in the cover's own geometry.
+ *
+ * Extracted from `pickCoverFrame`'s sampling loop because `ossclip cover --at
+ * <t>` needs exactly this for a single timestamp. A second implementation of
+ * the cover crop would drift from this one — and a drifted crop puts the
+ * banner against geometry the cover does not have, which is the whole reason
+ * `COVER_CROP_VF` exists rather than face.ts's plain `scale`.
+ *
+ * Returns null on a short read: ffmpeg seeking past the end (or onto a
+ * corrupt packet) writes fewer bytes than the detection frame, and measuring
+ * that is measuring padding.
+ */
+export async function measureCoverFrame(
+  tools: { ffmpegPath: string },
+  videoPath: string,
+  timeSec: number,
+  opts: {
+    cacheDir?: string;
+    cropVf?: string;
+    detectFace?: PickCoverOptions["detectFace"];
+    /** Scratch file name — the sampler keeps one per sample so a crashed run
+     * leaves no ambiguity about which frame it died on. */
+    frameName?: string;
+  } = {},
+): Promise<{ timeSec: number; sharpness: number; hasFace: boolean; face?: CoverFace } | null> {
+  const framePath = join(opts.cacheDir ?? ".", opts.frameName ?? "cover-frame.gray");
+  await run(tools.ffmpegPath, [
+    "-v", "error",
+    "-ss", timeSec.toFixed(3),
+    "-i", videoPath,
+    "-frames:v", "1",
+    "-vf", `${opts.cropVf ? `${opts.cropVf},` : ""}${COVER_CROP_VF}`,
+    "-pix_fmt", "gray",
+    "-f", "rawvideo",
+    "-y", framePath,
+  ]);
+  const pixels = new Uint8Array(await readFile(framePath));
+  await unlink(framePath).catch(() => {});
+  if (pixels.length < DET_W * DET_H) return null;
+  const face = opts.detectFace?.(pixels, DET_W, DET_H) ?? undefined;
+  return {
+    timeSec,
+    sharpness: laplacianVariance(pixels, DET_W, DET_H),
+    hasFace: face !== undefined,
+    face,
+  };
+}
+
 /**
  * Pick the best cover frame from the take: sharp, face present, early.
  *
@@ -217,27 +232,13 @@ export async function pickCoverFrame(
 
   for (let i = 0; i < samples; i++) {
     const t = (window * (i + 0.5)) / samples;
-    const framePath = join(opts.cacheDir ?? ".", `cover-frame-${i}.gray`);
-    await run(tools.ffmpegPath, [
-      "-v", "error",
-      "-ss", t.toFixed(3),
-      "-i", videoPath,
-      "-frames:v", "1",
-      "-vf", `${opts.cropVf ? `${opts.cropVf},` : ""}${COVER_CROP_VF}`,
-      "-pix_fmt", "gray",
-      "-f", "rawvideo",
-      "-y", framePath,
-    ]);
-    const pixels = new Uint8Array(await readFile(framePath));
-    await unlink(framePath).catch(() => {});
-    if (pixels.length < DET_W * DET_H) continue;
-    const face = opts.detectFace?.(pixels, DET_W, DET_H) ?? undefined;
-    raw.push({
-      timeSec: t,
-      sharpness: laplacianVariance(pixels, DET_W, DET_H),
-      hasFace: face !== undefined,
-      face,
+    const measured = await measureCoverFrame(tools, videoPath, t, {
+      cacheDir: opts.cacheDir,
+      cropVf: opts.cropVf,
+      detectFace: opts.detectFace,
+      frameName: `cover-frame-${i}.gray`,
     });
+    if (measured) raw.push(measured);
   }
   if (raw.length === 0) return null;
 
@@ -251,3 +252,122 @@ export async function pickCoverFrame(
   candidates.sort((a, b) => b.score - a.score);
   return candidates[0]!;
 }
+
+// ---- Cover provenance (`<workdir>/cover.json`) ----------------------------
+// Until this file existed, the ONLY thing that survived a cover render was the
+// JPEG: changing a headline therefore meant a full re-render to re-derive the
+// pick. Everything a faithful rebuild needs is recorded here so a regeneration
+// is `renderCover` against a still that is already on disk.
+
+/** The file the workdir keeps its cover provenance in. */
+export const COVER_PROVENANCE_BASENAME = "cover.json";
+
+/**
+ * Annotated as `z.ZodType<CoverFace>` so the persisted shape and the in-memory
+ * one cannot drift apart silently — adding a fraction to `CoverFace` without
+ * adding it here is then a compile error, not a field that quietly stops
+ * round-tripping.
+ */
+const CoverFaceSchema: z.ZodType<CoverFace> = z.object({
+  centerXFrac: z.number(),
+  centerYFrac: z.number(),
+  sizeFrac: z.number(),
+});
+
+export const CoverProvenanceSchema = z.object({
+  version: z.literal(1),
+  /** The banner text as SHIPPED — already through `coverHeadline`, and "" for
+   * the §34 case where the frame carried its own title. What was rendered,
+   * not what was proposed. */
+  text: z.string(),
+  /** "user" means a headline someone typed, which a later produce must not
+   * quietly overwrite with a fresh beat sheet's `coverText`. */
+  textSource: z.enum(["beatsheet", "user"]),
+  frame: z.object({
+    /** Which video the still came from: the finished render or the source. */
+    source: z.enum(["final", "source"]),
+    timeSec: z.number(),
+    /**
+     * The load-bearing field. This is the COVER-CROP geometry — deliberately
+     * NOT face.json's source-geometry measurement (see the `COVER_CROP_VF`
+     * doc comment for why the two are different numbers). Without it nothing
+     * can place the banner where the shipped cover placed it, and re-deriving
+     * it costs an ffmpeg extraction plus a cascade sweep. That single fact is
+     * what forced this whole file to exist.
+     */
+    face: CoverFaceSchema.nullable(),
+    hasFace: z.boolean(),
+    sharpness: z.number(),
+    /** The still already on disk in the workdir (`cover-frame.png`) — a
+     * text-only regeneration reuses it verbatim and runs no ffmpeg at all. */
+    fileName: z.string(),
+    /**
+     * The ORIGINAL TAKE, and nothing else. Workdir-relative when the video
+     * lives in the workdir (a folder run's `mezzanine.mp4`), absolute
+     * otherwise: a workdir that moved must still resolve its own
+     * intermediates.
+     *
+     * Nullable, and never overwritten by a regeneration (2026-08-19): this
+     * field once recorded "whichever video the current frame was read from",
+     * so one `ossclip cover` on its default `--from final` rewrote a
+     * `mezzanine.mp4` here into the FINISHED render's path — after which
+     * `--from source` silently re-cut the cover from the finished video,
+     * burned-in captions, graphics and watermark included, while telling the
+     * user it was reading the clean source. It also destroyed the only
+     * on-disk record of where the take lives. `frame.source` already says
+     * which video the current still came from, so this one has no second
+     * job. Null means the take is genuinely unknown (a first regeneration off
+     * the final video, with no prior provenance) — `--from source` then says
+     * so instead of lying.
+     */
+    sourceVideo: z.string().nullable(),
+    /** produce's `cropFilter(detection.uniform)`, and the SOURCE's — it is
+     * meaningless against a final-video frame, so it travels with
+     * `sourceVideo` under the same preserve-never-overwrite rule. Persisted
+     * because it is NOT reconstructible from anything else on disk: the
+     * letterbox detection that produced it is cached per source, and
+     * re-picking a frame without it frames two-thirds baked-in black bar. */
+    cropVf: z.string().nullable(),
+  }),
+  /** The OUTPUT frame the cover belongs to (R16 §76) — a landscape render
+   * gets a landscape cover, and a rebuild must not revert to 1080×1920. */
+  size: z.object({ width: z.number(), height: z.number() }),
+  /** Absolute path of the written `.cover.jpg`. */
+  out: z.string(),
+});
+
+export type CoverProvenance = z.infer<typeof CoverProvenanceSchema>;
+
+/**
+ * Read `<work>/cover.json`, or null when it is absent, corrupt, or fails the
+ * schema. Never throws: a pre-feature workdir has no such file at all, and a
+ * half-written one must degrade to "re-pick the frame" rather than brick the
+ * command — the same GET-path posture as `readApprovedConcept`.
+ */
+export async function readCoverProvenance(work: string): Promise<CoverProvenance | null> {
+  const path = join(work, COVER_PROVENANCE_BASENAME);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = CoverProvenanceSchema.safeParse(JSON.parse(await readFile(path, "utf8")));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write `<work>/cover.json` atomically: tmp file, then rename.
+ *
+ * The editor and a `ossclip cover` run may read this at any moment, and a
+ * half-written document would be worse than a stale one — the same reasoning
+ * as the overrides save in edit.ts.
+ */
+export async function writeCoverProvenance(
+  work: string,
+  provenance: CoverProvenance,
+): Promise<void> {
+  const path = join(work, COVER_PROVENANCE_BASENAME);
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, JSON.stringify(provenance, null, 2));
+  await rename(tmp, path);
+}