npm - ossclip - Versions diffs - 0.1.11 → 0.1.13 - Mend

ossclip 0.1.11 → 0.1.13

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 (9) hide show

package/editor-dist/assets/{index-Bo0WME7k.js → index-BBVLCP-N.js} +24 -24
package/editor-dist/index.html +1 -1
package/package.json +4 -4
package/src/interactive/produce-argv.ts +9 -0
package/src/interactive/produce-wizard.ts +133 -17
package/src/produce.ts +211 -32
package/src/program.ts +57 -3
package/src/replay-argv.ts +19 -1
package/src/stranded-overrides.ts +77 -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-Bo0WME7k.js"></script>
+    <script type="module" crossorigin src="/assets/index-BBVLCP-N.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-C8IPo60X.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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",
@@ -36,9 +36,9 @@
     "commander": "^12.1.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76",
-    "@ossclip/core": "0.1.11",
-    "@ossclip/renderer": "0.1.11",
-    "@ossclip/scenes": "0.1.11"
+    "@ossclip/core": "0.1.13",
+    "@ossclip/renderer": "0.1.13",
+    "@ossclip/scenes": "0.1.13"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/interactive/produce-argv.ts CHANGED Viewed

@@ -11,9 +11,14 @@ export interface ProduceExtras {
   sourceFit?: "cover" | "contain";
   speaker?: string;
   whisperModel?: string;
+  whisperLanguage?: string;
   blooperMarker?: string;
   collapseRetakes?: boolean;
   sourceIsEdited?: boolean;
+  /** Opt-in "made with ossclip" credit. The wizard only ever turns it ON —
+   * off is the default, and a config-on user who wants it off for one run
+   * types `--no-watermark`, a flags-only surface like --sort. */
+  watermark?: boolean;
   llm?: "claude" | "claude-cli" | "gemini" | "mock";
 }
@@ -50,9 +55,13 @@ export function produceArgv(a: ProduceAnswers): string[] {
   if (e.sourceFit === "contain") argv.push("--source-fit", "contain");
   if (e.speaker) argv.push("--speaker", e.speaker);
   if (e.whisperModel) argv.push("--whisper-model", e.whisperModel);
+  // Empty answer means "whisper's default (en)" — the elision rule above:
+  // no flag whose value equals the default.
+  if (e.whisperLanguage) argv.push("--whisper-language", e.whisperLanguage);
   if (e.blooperMarker) argv.push("--blooper-marker", e.blooperMarker);
   if (e.collapseRetakes === true) argv.push("--collapse-retakes");
   if (e.sourceIsEdited === true) argv.push("--source-is-edited");
+  if (e.watermark === true) argv.push("--watermark");
   if (e.llm) argv.push("--llm", e.llm);
   return argv;

package/src/interactive/produce-wizard.ts CHANGED Viewed

@@ -1,15 +1,16 @@
 import { basename } from "node:path";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
 import { produceArgv, type ProduceAnswers, type ProduceExtras } from "./produce-argv";
 import { assertInteractive, confirm, intro, multiselect, select, text, unwrap } from "./prompts";
 /**
- * The produce wizard. Thirty flags (plus the positional input path) sorted
- * into three tiers: six prompts asked directly — the input path, plus five
- * flags (--out, --cleanup, --aspect, --produce, --intent) — eight behind one
- * "anything else?" multiselect, and the remaining seventeen stay flags-only:
- * debug/internal surfaces, replay-only fields, or (final-review fix wave,
- * Finding 1) --sort. A folder's clip order only means anything once the
+ * The produce wizard. Thirty-two flags (plus the positional input path)
+ * sorted into three tiers: six prompts asked directly — the input path, plus
+ * five flags (--out, --cleanup, --aspect, --produce, --intent) — nine behind
+ * one "anything else?" multiselect, and the remaining stay flags-only:
+ * debug/internal surfaces, replay-only fields, --no-watermark (the
+ * multiselect only turns the credit ON; off is already the default), or
+ * (final-review fix wave, Finding 1) --sort. A folder's clip order only means anything once the
  * folder has been enumerated, and that enumeration happens inside
  * `produce()` — after the wizard has already returned argv — so there is
  * nothing for a prompt to offer a choice about beforehand. --sort stays
@@ -34,6 +35,7 @@ const EXTRAS = [
     hint: "--collapse-retakes",
   },
   { value: "sourceIsEdited", label: "Source already has burned-in text", hint: "--source-is-edited" },
+  { value: "watermark", label: 'Credit the tool with a small "made with ossclip"', hint: "--watermark" },
   { value: "llm", label: "Choose the LLM provider", hint: "--llm" },
 ] as const;
@@ -45,12 +47,92 @@ const EXTRAS = [
  * error nine prompts later — so the clip extra is only ever listed once
  * graphics is already on. Exported and kept pure so this can be asserted
  * without a TTY.
+ *
+ * `watermarkFromConfig` (review, minor a): on a config-on machine the
+ * watermark entry sits UNCHECKED while the credit will render anyway —
+ * unchecked is "don't emit the flag", not "off", and the multiselect has no
+ * way to say the second thing. The honest cheap fix is to say so in the
+ * entry's own hint rather than pre-checking it (a pre-check would emit a
+ * redundant --watermark and teach a command line longer than the run needs,
+ * against produceArgv's default-elision rule).
+ */
+export function extrasFor(
+  graphics: boolean,
+  opts: { watermarkFromConfig?: boolean } = {},
+): { value: (typeof EXTRAS)[number]["value"]; label: string; hint: string }[] {
+  const list = graphics ? [...EXTRAS] : EXTRAS.filter((e) => e.value !== "graphicsClip");
+  if (opts.watermarkFromConfig !== true) return [...list];
+  return list.map((e) =>
+    e.value === "watermark"
+      ? { ...e, hint: "already on via your config — unticking does not disable it; --no-watermark does" }
+      : e,
+  );
+}
+/** Select value that routes to the free-text model prompt instead of a name. */
+export const CUSTOM_MODEL = "__custom__";
+/**
+ * A model pick reduced to its bare name: basename, minus the optional ggml-
+ * prefix and .bin suffix. Exists because the language prefill classifies on
+ * `.endsWith(".en")`, and an absolute path like /x/ggml-small.en.bin ends in
+ * ".bin" — an English model would have been prefilled `auto` (review fix,
+ * Urdu field test 2026-08-05).
+ */
+export function bareWhisperModelName(nameOrPath: string): string {
+  const base = basename(nameOrPath);
+  const m = /^(?:ggml-)?(.+?)(?:\.bin)?$/.exec(base);
+  return m?.[1] ?? base;
+}
+/** The three names `ossclip setup` knows how to download, with their hints. */
+const CANONICAL_MODELS = [
+  { value: "base.en", hint: "fastest, least accurate" },
+  { value: "small.en", hint: "default" },
+  { value: "medium.en", hint: "slowest, most accurate" },
+] as const;
+/**
+ * modelDir listing → select choices. Pure so the enumeration rules —
+ * `ggml-*.bin` stripped to bare names, everything else ignored — are testable
+ * without a TTY or a real ~/.ossclip. Exists because the fixed .en-only list
+ * made a downloaded fine-tune unpickable from the wizard (Urdu field test
+ * 2026-08-05: ggml-medium-urdu.bin was installed and working via
+ * `--whisper-model medium-urdu`, and the wizard could not name it).
  */
-export function extrasFor(graphics: boolean): (typeof EXTRAS)[number][] {
-  return graphics ? [...EXTRAS] : EXTRAS.filter((e) => e.value !== "graphicsClip");
+export function whisperModelChoices(
+  modelDirFiles: string[],
+): { value: string; label: string; hint: string }[] {
+  const installed = new Set<string>();
+  for (const f of modelDirFiles) {
+    // Bare name is what --whisper-model takes: produce.ts joins it back into
+    // `ggml-<name>.bin`, so the round trip is exact by construction.
+    const m = /^ggml-(.+)\.bin$/.exec(f);
+    if (m?.[1] !== undefined) installed.add(m[1]);
+  }
+  // Canonicals stay listed whether or not downloaded: produce.ts already
+  // errors helpfully (naming the setup/curl fix) on a missing model, so the
+  // pick works — but the download should not be a surprise, hence the marker.
+  const choices: { value: string; label: string; hint: string }[] = CANONICAL_MODELS.map((c) => ({
+    value: c.value,
+    label: c.value,
+    hint: installed.has(c.value) ? c.hint : `${c.hint} · will need download`,
+  }));
+  const canonical = new Set<string>(CANONICAL_MODELS.map((c) => c.value));
+  for (const name of [...installed].filter((n) => !canonical.has(n)).sort()) {
+    choices.push({ value: name, label: name, hint: "installed" });
+  }
+  choices.push({
+    value: CUSTOM_MODEL,
+    label: "type a name or absolute path",
+    hint: "anything whisper.cpp can load",
+  });
+  return choices;
 }
-export async function produceWizard(cfg: { speaker?: string; input?: string } = {}): Promise<string[]> {
+export async function produceWizard(
+  cfg: { speaker?: string; modelDir?: string; input?: string; watermark?: boolean } = {},
+): Promise<string[]> {
   assertInteractive("produce wizard");
   intro("ossclip produce");
@@ -128,7 +210,7 @@ export async function produceWizard(cfg: { speaker?: string; input?: string } =
   const chosen = unwrap(
     await multiselect({
       message: "Anything else? (space to toggle, enter to accept)",
-      options: extrasFor(graphics),
+      options: extrasFor(graphics, { watermarkFromConfig: cfg.watermark === true }),
       required: false,
     }),
   ) as string[];
@@ -153,6 +235,7 @@ export async function produceWizard(cfg: { speaker?: string; input?: string } =
   if (chosen.includes("sourceFit")) extras.sourceFit = "contain";
   if (chosen.includes("collapseRetakes")) extras.collapseRetakes = true;
   if (chosen.includes("sourceIsEdited")) extras.sourceIsEdited = true;
+  if (chosen.includes("watermark")) extras.watermark = true;
   if (chosen.includes("speaker")) {
     extras.speaker = unwrap(
       await text({
@@ -165,17 +248,50 @@ export async function produceWizard(cfg: { speaker?: string; input?: string } =
     ) as string;
   }
   if (chosen.includes("whisperModel")) {
-    extras.whisperModel = unwrap(
+    // Enumerated from disk, not hardcoded (Urdu field test 2026-08-05): a
+    // fine-tune the user already installed must be pickable here, not
+    // flags-only. A missing/unset modelDir just means nothing extra to list.
+    const modelFiles =
+      cfg.modelDir !== undefined && existsSync(cfg.modelDir) ? readdirSync(cfg.modelDir) : [];
+    let model = unwrap(
       await select({
         message: "Transcription model",
         initialValue: "small.en",
-        options: [
-          { value: "base.en", label: "base.en", hint: "fastest, least accurate" },
-          { value: "small.en", label: "small.en", hint: "default" },
-          { value: "medium.en", label: "medium.en", hint: "slowest, most accurate" },
-        ],
+        options: whisperModelChoices(modelFiles),
       }),
     ) as string;
+    if (model === CUSTOM_MODEL) {
+      // Trimmed before the guard: " " passing as truthy would emit a
+      // whitespace --whisper-model that produce.ts then fails to resolve.
+      model = (
+        unwrap(
+          await text({
+            message: "Model name or absolute path to a ggml .bin",
+            placeholder: "medium-urdu",
+            validate: (v) => (v?.trim() ? undefined : "a model name or path is required"),
+          }),
+        ) as string
+      ).trim();
+    }
+    extras.whisperModel = model;
+    // Follow-up under the same extra, like --clip's seconds prompt: a language
+    // only means anything once a model is being picked, and a multilingual
+    // fine-tune silently decodes English without it (Urdu field test
+    // 2026-08-05). A non-.en pick is multilingual by construction, so the
+    // prefill makes plain Enter the safe answer — `auto` lets whisper detect.
+    // Empty keeps whisper's en default, and produceArgv's default-elision
+    // rule then emits no flag at all.
+    const lang = (
+      unwrap(
+        await text({
+          message: "Transcription language code (empty = default en)",
+          placeholder: "ur",
+          initialValue: bareWhisperModelName(model).endsWith(".en") ? "" : "auto",
+          defaultValue: "",
+        }),
+      ) as string
+    ).trim(); // a whitespace answer means "default", not a bogus -l " "
+    if (lang) extras.whisperLanguage = lang;
   }
   if (chosen.includes("blooperMarker")) {
     extras.blooperMarker = unwrap(

package/src/produce.ts CHANGED Viewed

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { mkdir, readFile, writeFile, rename } from "node:fs/promises";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { z } from "zod/v4";
 import {
@@ -24,6 +24,7 @@ import {
   concatFolder,
   folderManifestKey,
   listFolderVideos,
+  coverDecision,
   coverHeadline,
   cropFilter,
   detectContentRect,
@@ -97,6 +98,11 @@ import {
   type Transcript,
 } from "@ossclip/core";
 import { recordRecentProject } from "./edit";
+import {
+  strandedOverrideSiblings,
+  strandedPointerLine,
+  workdirBaseName,
+} from "./stranded-overrides";
 import { editHint } from "./interactive/edit-hint";
 import { recordedProduceArgs } from "./replay-argv";
 import { renderCover, renderProduction } from "@ossclip/renderer";
@@ -118,6 +124,43 @@ export interface ProduceResult {
   rendered: boolean;
 }
+/**
+ * What produced the workdir's transcript.json — written beside it as
+ * transcript-key.json (review fix, Urdu field test 2026-08-05). Parsed with
+ * zod like the transcript itself: a hand-edited or truncated key must error,
+ * not silently decide whether a cache is reused.
+ */
+export const TranscriptKeySchema = z.object({
+  model: z.string(),
+  language: z.string().optional(),
+});
+export type TranscriptKey = z.infer<typeof TranscriptKeySchema>;
+/**
+ * Whether the cached transcript answers the current request. Pure so all
+ * four corners (matching key, differing key, keyless + default, keyless +
+ * non-default) are testable without a workdir. A missing key means a workdir
+ * from before the key existed; every one of those was transcribed with the
+ * config-default model and no -l, so it is treated as exactly that — old
+ * workdirs must not all re-transcribe spuriously, but a non-default request
+ * against a keyless cache must.
+ */
+export function transcriptCacheReusable(
+  recorded: TranscriptKey | null,
+  requested: TranscriptKey,
+  defaultModel: string,
+): { reuse: boolean; recorded: TranscriptKey } {
+  const effective = recorded ?? { model: defaultModel };
+  return {
+    reuse:
+      effective.model === requested.model &&
+      // "" and absent both mean whisper's en default — program.ts rejects an
+      // empty code, but a key file predating that guard must not wedge.
+      (effective.language ?? "") === (requested.language ?? ""),
+    recorded: effective,
+  };
+}
 export interface ProduceOptions {
   out?: string;
   cleanup: CleanupLevel;
@@ -143,6 +186,12 @@ export interface ProduceOptions {
   repair?: boolean;
   /** Override the whisper model for this run (A/B base.en vs small.en). */
   whisperModel?: string;
+  /**
+   * `-l` language code for whisper (e.g. "ur", "auto"). Unset keeps whisper's
+   * English default — required for a non-English fine-tune, which otherwise
+   * decodes garbage (Urdu field test 2026-08-05).
+   */
+  whisperLanguage?: string;
   /** Debug: force every graphic moment to this component. */
   forceComponent?: SceneComponentId;
   /** Write a cover image beside the video (default on). */
@@ -190,6 +239,14 @@ export interface ProduceOptions {
    * window with zero LLM calls. Written by clip runs; not for hand use.
    */
   clipWindow?: string;
+  /**
+   * `--watermark` / `--no-watermark` tri-state: true/false when TYPED,
+   * undefined when not — undefined lets the config's `watermark` key supply
+   * the default (`resolveWatermark`). Opt-in by design: the default is off
+   * for everyone, because a forced watermark on an open-source tool reads as
+   * a free-tier limitation; this is voluntary attribution.
+   */
+  watermark?: boolean;
   /**
    * `<input>` a DIRECTORY: order its clips before concatenating them into the
    * source produce runs on (folder-input-brief.md). `name` (default) is a
@@ -207,6 +264,23 @@ export interface ProduceOptions {
   sortExplicit?: boolean;
 }
+/**
+ * The effective watermark switch: a TYPED flag always wins (so
+ * `--no-watermark` beats a config-on), and only then does the config supply
+ * the default. The config side is `=== true`, never truthiness — the value
+ * comes from a hand-editable JSON file loadConfig doesn't zod-parse, and a
+ * typo'd `"watermark": "no"` coercing a credit ON is exactly the
+ * parse-don't-coerce failure CLAUDE.md forbids; for an opt-in credit, off is
+ * the only safe reading of anything malformed. Pure so the whole
+ * flag × config matrix is testable without a config file on disk.
+ */
+export function resolveWatermark(
+  flag: boolean | undefined,
+  configValue: boolean | undefined,
+): boolean {
+  return flag ?? configValue === true;
+}
 function sha1File(path: string): Promise<string> {
   return new Promise((res, rej) => {
     const h = createHash("sha1");
@@ -246,10 +320,9 @@ function deriveWorkdir(
   landscape: boolean,
 ): string {
   const workRoot = workdirOpt ? resolve(workdirOpt) : join(dirname(identity), ".ossclip");
-  return join(
-    workRoot,
-    `${basename(identity).replace(/\.[^.]+$/, "")}-${hash}${landscape ? "-16x9" : ""}`,
-  );
+  // The basename half is shared with the §131 stranded-edits scan so the
+  // scan's matching can never drift from the naming it scans for.
+  return join(workRoot, `${workdirBaseName(identity)}-${hash}${landscape ? "-16x9" : ""}`);
 }
 /**
@@ -495,6 +568,36 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   await mkdir(work, { recursive: true });
   console.log(`▸ workdir ${work}`);
+  // §131 residue: a folder re-key (clips renamed/added/removed → new content
+  // hash) correctly lands in a fresh workdir, but any editor edits saved in
+  // the PREVIOUS workdir's overrides.json don't carry over — and without this
+  // pointer the user sees a clean produce and never learns where those edits
+  // went. Gated on the current workdir lacking overrides.json: a warm re-run
+  // that already has edits needs no pointer. Print-only by design — no
+  // migration, no prompt — and best-effort: a courtesy line must never be the
+  // reason a produce fails.
+  if (isFolder && !existsSync(join(work, "overrides.json"))) {
+    try {
+      const workRoot = dirname(work);
+      const entries = readdirSync(workRoot, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => {
+          const overrides = join(workRoot, d.name, "overrides.json");
+          const st = existsSync(overrides) ? statSync(overrides) : null;
+          return { name: d.name, hasOverrides: st !== null, mtimeMs: st?.mtimeMs ?? 0 };
+        });
+      const stranded = strandedOverrideSiblings({
+        base: workdirBaseName(input),
+        currentHash: hash,
+        entries,
+      });
+      for (const name of stranded) console.log(strandedPointerLine(join(workRoot, name)));
+    } catch {
+      // Racing deletes/permissions while scanning siblings: drop the hint,
+      // keep the run (§131 — the pointer is a courtesy, not a dependency).
+    }
+  }
   if (isFolder && folderListing) {
     const sort = opts.sort ?? "name";
     const result = await concatFolder(tools, input, folderListing, work, sort, {
@@ -563,18 +666,48 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   let transcript: Transcript;
   const transcriptCache = join(work, "transcript.json");
+  // Which model/language WROTE transcript.json, recorded beside it (review
+  // fix, Urdu field test 2026-08-05): the cache used to be reused on
+  // existence alone, so a warm workdir silently served the stale English
+  // transcript on the first `--whisper-language ur` retry — the exact run
+  // the flag exists for — and equally defeated the model A/B the
+  // --whisper-model help text advertises.
+  const transcriptKeyPath = join(work, "transcript-key.json");
+  const requestedKey: TranscriptKey = {
+    model: opts.whisperModel ?? cfg.model,
+    ...(opts.whisperLanguage !== undefined ? { language: opts.whisperLanguage } : {}),
+  };
+  let cacheVerdict: ReturnType<typeof transcriptCacheReusable> | null = null;
+  if (!opts.transcript && existsSync(transcriptCache)) {
+    const recorded = existsSync(transcriptKeyPath)
+      ? TranscriptKeySchema.parse(JSON.parse(await readFile(transcriptKeyPath, "utf8")))
+      : null;
+    cacheVerdict = transcriptCacheReusable(recorded, requestedKey, cfg.model);
+  }
   if (opts.transcript) {
     transcript = TranscriptSchema.parse(JSON.parse(await readFile(resolve(opts.transcript), "utf8")));
     console.log(`▸ transcript injected from ${opts.transcript} (${transcript.words.length} words)`);
-  } else if (existsSync(transcriptCache)) {
+    // An injected transcript came from no whisper run at all, so any key left
+    // by an earlier one would mislabel the cache this branch overwrites below.
+    // Keyless-as-default keeps today's behavior: later default runs reuse it,
+    // and only an explicit model/language request re-transcribes over it.
+    await rm(transcriptKeyPath, { force: true });
+  } else if (cacheVerdict?.reuse) {
     transcript = TranscriptSchema.parse(JSON.parse(await readFile(transcriptCache, "utf8")));
     console.log(`▸ transcript cached (${transcript.words.length} words)`);
   } else {
+    if (cacheVerdict !== null) {
+      const fmt = (k: TranscriptKey) => `${k.model}/lang ${k.language ?? "default"}`;
+      console.log(
+        `▸ transcript cache is for model ${fmt(cacheVerdict.recorded)} — ` +
+          `re-transcribing with ${fmt(requestedKey)}`,
+      );
+    }
     await preflight(
       cfg.whisperPath,
       "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 model = requestedKey.model;
     const modelPath = isAbsolute(model) ? model : join(cfg.modelDir, `ggml-${model}.bin`);
     if (!existsSync(modelPath)) {
       throw new Error(
@@ -585,10 +718,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     }
     console.log(`▸ transcribing (${basename(modelPath)})…`);
     transcript = await runWhisper(
-      { whisperPath: cfg.whisperPath, modelPath, outBase: join(work, "whisper") },
+      {
+        whisperPath: cfg.whisperPath,
+        modelPath,
+        outBase: join(work, "whisper"),
+        language: opts.whisperLanguage,
+      },
       audioPath,
     );
     console.log(`▸ transcribed ${transcript.words.length} words`);
+    await writeFile(transcriptKeyPath, JSON.stringify(requestedKey, null, 2));
   }
   await writeFile(transcriptCache, JSON.stringify(transcript, null, 2));
@@ -1882,6 +2021,17 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     );
   }
+  // Resolved HERE, next to the props it feeds, and announced when on — the
+  // one ▸ line is how a config-sourced credit stays visible per run instead
+  // of surprising the author on upload.
+  const watermark = resolveWatermark(opts.watermark, cfg.watermark);
+  if (watermark) {
+    console.log(
+      `▸ watermark: "made with ossclip" in the top-left safe area` +
+        `${opts.watermark === undefined ? " (from config; --no-watermark overrides)" : ""}`,
+    );
+  }
   const props = {
     videoFileName: basename(renderVideo),
     spans: [...map.spans],
@@ -1938,6 +2088,10 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
     ...(opts.sourceFit === "contain"
       ? { sourceFit: "contain" as const, sourceSize: content }
       : {}),
+    // Written only when ON, matching the field's absent-means-off contract:
+    // an off run's render-props.json stays byte-identical to a pre-watermark
+    // one, so nothing downstream can tell the feature ever shipped.
+    ...(watermark ? { watermark: true } : {}),
   };
   await writeFile(join(work, "render-props.json"), JSON.stringify(props, null, 2));
@@ -2008,13 +2162,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // A separate file, not a burned-in intro: both platforms accept a custom
   // cover, so nothing has to be pickable from the video — and spending the
   // opening seconds on a title card fights the hook-in-2s policy directly.
-  if (opts.cover !== false) {
+  {
     // §35's cap applies here too: a cached beat sheet from before the fix, or
     // the hook fallback, must not slip a 13-word paragraph onto a thumbnail.
     const coverText = coverHeadline(beatSheet?.coverText ?? beatSheet?.hook ?? "");
-    if (!coverText) {
-      console.log("▸ no cover text (run --produce for one) — skipping cover");
-    } else {
+    // Urdu field run 2026-08-05: a run without --produce has no hook text,
+    // and skipping the cover for that threw away the part that never needed
+    // text — the sharpness-scored face frame. No headline now means a bare
+    // frame, not no cover; see `coverDecision`'s doc comment.
+    const cover = coverDecision(opts.cover !== false, coverText);
+    if (cover !== "none") {
       const detector = await createFaceDetector();
       const pick = await pickCoverFrame(tools, analysisInput, analysisProbe.duration, {
         cacheDir: work,
@@ -2042,31 +2199,45 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
         const coverPath = resolve(
           opts.coverPath ?? outPath.replace(/(\.[^.]+)?$/, ".cover.jpg"),
         );
-        // §34: if the source's own title is up at this instant, the frame
-        // already has a headline. Adding ours states the same claim twice in
-        // one image — a cover with one title beats a cover with two.
-        const sourceTitled = regionsDuring(
-          sourceText.regions,
-          pick.timeSec - 0.5,
-          pick.timeSec + 0.5,
-        ).length > 0;
-        console.log(
-          `▸ cover from ${pick.timeSec.toFixed(1)}s ` +
-            `(${pick.hasFace ? "face" : "no face"}, sharpness ${pick.sharpness.toFixed(0)})…`,
-        );
-        if (sourceTitled) {
-          console.log("  ▸ source already has a title in this frame — shipping it without a banner");
-        } else if (pick.face) {
-          const band = coverTextRect(pick.face, frame);
+        // The §34 dedupe check and the band-placement log exist only to
+        // route a banner around the frame's contents — a textless cover
+        // (Urdu field run 2026-08-05) has no banner to place, so both are
+        // skipped rather than run against text that isn't there.
+        let bannerText = "";
+        if (cover === "banner") {
+          // §34: if the source's own title is up at this instant, the frame
+          // already has a headline. Adding ours states the same claim twice in
+          // one image — a cover with one title beats a cover with two.
+          const sourceTitled = regionsDuring(
+            sourceText.regions,
+            pick.timeSec - 0.5,
+            pick.timeSec + 0.5,
+          ).length > 0;
+          console.log(
+            `▸ cover from ${pick.timeSec.toFixed(1)}s ` +
+              `(${pick.hasFace ? "face" : "no face"}, sharpness ${pick.sharpness.toFixed(0)})…`,
+          );
+          if (sourceTitled) {
+            console.log("  ▸ source already has a title in this frame — shipping it without a banner");
+          } else if (pick.face) {
+            const band = coverTextRect(pick.face, frame);
+            console.log(
+              `  ▸ banner in the ${band.y + band.h / 2 < pick.face.centerYFrac ? "band above" : "band below"} ` +
+                `the face (${(band.y * 100).toFixed(0)}-${((band.y + band.h) * 100).toFixed(0)}%)`,
+            );
+          }
+          bannerText = sourceTitled ? "" : coverText;
+        } else {
           console.log(
-            `  ▸ banner in the ${band.y + band.h / 2 < pick.face.centerYFrac ? "band above" : "band below"} ` +
-              `the face (${(band.y * 100).toFixed(0)}-${((band.y + band.h) * 100).toFixed(0)}%)`,
+            `▸ cover from ${pick.timeSec.toFixed(1)}s ` +
+              `(${pick.hasFace ? "face" : "no face"}, sharpness ${pick.sharpness.toFixed(0)}) ` +
+              `— no banner text (run --produce for one)`,
           );
         }
         await renderCover(
           {
             frameFileName: frameName,
-            text: sourceTitled ? "" : coverText,
+            text: bannerText,
             theme,
             face: pick.face,
             // The cover is the OUTPUT's thumbnail — a landscape render gets a
@@ -2107,9 +2278,17 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // recordedProduceArgs prefers the argv the re-entry stashed and falls back
   // to process.argv for a directly typed `ossclip produce …`, which stays
   // byte-identical to what was always recorded.
+  // Watermark pin, same §75 shape, and in BOTH directions (review,
+  // Important): the effective default comes from THIS machine's
+  // ~/.ossclip/config.json, so an unpinned record replays differently
+  // wherever that config differs — an off-run would silently gain a credit
+  // under a later/foreign config-on, an on-run would silently lose it. The
+  // RESOLVED state is always pinned; a typed flag is already in the argv and
+  // the includes-guard leaves it alone.
   const recordedArgs = recordedProduceArgs({
     llm: provider ? providerName : undefined,
     clipWindow: clipWindow ? `${clipWindow.startWord}:${clipWindow.endWord}` : undefined,
+    watermark,
   });
   await writeFile(
     join(work, "command.json"),