ossclip 0.1.17 → 0.1.19

package/editor-dist/assets/index-ChRVBVLj.css

@@ -0,0 +1 @@
+.ossclip-scroll-list{scrollbar-width:thin;scrollbar-color:#3a3a44 transparent}.ossclip-scroll-list::-webkit-scrollbar{width:8px}.ossclip-scroll-list::-webkit-scrollbar-track{background:transparent}.ossclip-scroll-list::-webkit-scrollbar-thumb{background:#3a3a44;border-radius:4px}.ossclip-picker-row{color:#c9c9d4;background:transparent;border:1px solid transparent}.ossclip-picker-row.is-workdir{color:#ededf2;background:#1a1a21;border-color:#2a2a33}.ossclip-picker-row:disabled{cursor:default;opacity:.5}.ossclip-picker-row:hover:not(:disabled){background:#1f1f28;border-color:#3a3a48}.ossclip-picker-row:focus{outline:none;background:#23232e;border-color:#8ab4f8}.ossclip-picker-row:active:not(:disabled){background:#2a2a36}

package/editor-dist/index.html

@@ -4,8 +4,8 @@
     <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-CdwzWN3j.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-C8IPo60X.css">
+    <script type="module" crossorigin src="/assets/index-B44I-xE4.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-ChRVBVLj.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "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.17",
-    "@ossclip/renderer": "0.1.17",
-    "@ossclip/scenes": "0.1.17"
+    "@ossclip/core": "0.1.19",
+    "@ossclip/renderer": "0.1.19",
+    "@ossclip/scenes": "0.1.19"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/caption-report.ts

@@ -0,0 +1,217 @@
+import {
+  applyCaptionEdits,
+  captionEditsToKeep,
+  isLegacyCaptionKey,
+  migrateCaptionKeys,
+  MIGRATION_SEARCH_RADIUS,
+} from "@ossclip/core";
+import type {
+  AppliedCaptionEdits,
+  CaptionEdit,
+  CaptionKeyMigration,
+  CaptionLine,
+  OverrideDoc,
+} from "@ossclip/core";
+
+/**
+ * What `produce` does with the user's retyped caption words, and what it says
+ * about the ones that did not land (§137).
+ *
+ * Pure, and in its own module rather than inline in `produce.ts`, for the
+ * house reason: this is a decision about the user's data (which edits are
+ * re-anchored, which are applied, and why the others were not) and a
+ * `produce()` run needs ffmpeg, a transcript and a workdir before it reaches
+ * any of it. `produce.ts` keeps the `console.log` and the file writes.
+ */
+
+/** One drop, as a console line. Three cases, and the caller must not merge them. */
+export function captionDropLine(drop: AppliedCaptionEdits["dropped"][number]): string {
+  // `found: null` used to be interpolated straight into the sentence, so a
+  // word the cut removed reported `the transcript now has "null"` — the one
+  // case §137 exists for, described as a JSON literal. The three cases carry
+  // genuinely different advice, so they get genuinely different sentences.
+  if (drop.reason === "duplicate-anchor") {
+    // NOT a stale edit: the edit almost certainly applied, to the FIRST word
+    // carrying this anchor. Two words share one source instant by design
+    // (captions.ts:44-50 — backfilled seam preimages and cut-clamped words),
+    // so this is a note about reach, not a failure.
+    return (
+      `  ⚠ caption edit "${drop.expected}" (${drop.key}): a second word shares that ` +
+      `source moment and was left as it is — only the first was retyped`
+    );
+  }
+  if (drop.found === null) {
+    // A key that is a POSITION, not a source anchor, never had a moment to
+    // lose — it is a pre-§137 doc the migration could not upgrade. Saying "the
+    // cut removed it" there sends the user to redo work that is sitting intact
+    // on screen (§137 Task 6 review, Important 2). Reachable whenever an edit
+    // reaches `applyCaptionEdits` without going through `migrateCaptionKeys`.
+    if (isLegacyCaptionKey(drop.key)) {
+      return (
+        `  ⚠ caption edit "${drop.expected}" (position ${drop.key}) not applied: it is keyed ` +
+        `by word POSITION, from a project saved before source anchors, and nothing ` +
+        `re-anchored it — open the project in the editor, or retype it there`
+      );
+    }
+    return (
+      `  ⚠ caption edit "${drop.expected}" (${drop.key}) dropped: no word starts at that ` +
+      `source moment any more — the cut removed the word it was typed over. ` +
+      `Retype it in the editor if you still want it.`
+    );
+  }
+  return (
+    `  ⚠ caption edit "${drop.expected}" (${drop.key}) dropped: the transcript now says ` +
+    `"${drop.found}" there`
+  );
+}
+
+/**
+ * How many stored edits actually landed.
+ *
+ * NOT `keys.length - dropped.length` (§137): `dropped` is not one entry per
+ * key. A `duplicate-anchor` entry is pushed for every EXTRA word carrying an
+ * anchor, so a single key can appear in `dropped` two or three times — and it
+ * may have applied anyway. The old subtraction therefore undercounted, and
+ * with enough duplicates went NEGATIVE, which the `> 0` guard then hid
+ * entirely: the run printed nothing at all about edits that had applied.
+ *
+ * The rule comes straight from `applyCaptionEdits`' own contract: a key is
+ * marked `seen` by the first word carrying it, and that word either applied
+ * the edit or was reported with `reason` ABSENT. So an edit landed exactly
+ * when nothing was reported for its key without a `reason`.
+ */
+export function appliedCaptionEditCount(
+  edits: Record<string, CaptionEdit>,
+  dropped: AppliedCaptionEdits["dropped"],
+): number {
+  const failed = new Set(dropped.filter((d) => d.reason === undefined).map((d) => d.key));
+  return Object.keys(edits).filter((key) => !failed.has(key)).length;
+}
+
+/**
+ * One console line for a legacy edit the migration would not place (§137).
+ *
+ * One sentence per CAUSE, like the editor's own notice: three of the four
+ * leave the word sitting right there in the transcript, and a single message
+ * blaming the cut would send the user hunting for it.
+ */
+export function captionMigrationLine(u: CaptionKeyMigration["unresolved"][number]): string {
+  const head = `  ⚠ caption edit "${u.was}" (${u.key}) could not be re-anchored`;
+  switch (u.reason) {
+    case "out-of-range":
+      // The word is ON SCREEN. Blaming the cut here (which the shared
+      // `not-found` sentence did until the final review) sends the user to
+      // retype something that is sitting intact in the transcript — and the
+      // edit is kept in the doc, so the next run against a different cut may
+      // place it without them doing anything at all.
+      // No promise that retyping fixes it, either: the word this found may
+      // itself be unanchorable (a pre-§137 render-props.json with nothing to
+      // backfill from), and "re-anchors it for good" would be a guarantee this
+      // line cannot make.
+      return `${head}: the word is still here, but more than ${MIGRATION_SEARCH_RADIUS} words from where the edit was stored, so it was left alone rather than applied to the wrong one — it is kept in overrides.json, so retype it in the editor if that is the word you meant`;
+    case "ambiguous":
+      return `${head}: more than one word says it here, so it was left alone rather than applied to the wrong one — retype the one you meant in the editor`;
+    case "unanchorable":
+      return `${head}: the word is here but carries no source timing to key on`;
+    case "collision":
+      return `${head}: two stored edits point at the same word — neither was applied, retype the one you meant in the editor`;
+    case "superseded":
+      return `${head}: a newer edit already covers that word — the newer one was kept`;
+    default:
+      return `${head}: no word says it any more — the cut or a re-plan removed it. Retype it in the editor if you still want it.`;
+  }
+}
+
+/**
+ * How many edits came out under a key they did not go in under — the ones the
+ * migration actually moved.
+ *
+ * NOT `Object.keys(migration.edits).length`, which is what the count in the log
+ * line was first written as: a MIXED doc (`{"0": …, "w6000": …}` over one word)
+ * keeps its already-source-keyed edit and retires the legacy one, so that
+ * count announced "1 caption edit re-anchored" about a key nothing had
+ * touched. A number the user can check against their own file has to be true
+ * for the same reason the drop lines do.
+ */
+export function reanchoredKeyCount(
+  before: Record<string, CaptionEdit>,
+  migration: CaptionKeyMigration,
+): number {
+  return Object.keys(migration.edits).filter((key) => !(key in before)).length;
+}
+
+export interface CaptionReconciliation {
+  /** The doc with its caption keys upgraded — what produce writes back. */
+  doc: OverrideDoc;
+  /** The caption lines with every edit that could be applied, applied. */
+  lines: CaptionLine[];
+  /**
+   * Whether the migration actually MOVED an edit onto a source anchor — the
+   * write-back gate, and the only thing that earns spending the `.bak`.
+   *
+   * It used to be `captionKeysMigrated`: true whenever anything was
+   * unresolved, including when nothing at all was placed. That is a write with
+   * no repair in it, and on the field workdir (`cutResult.changed` false,
+   * because the cut already carries `src`) it was a NEW write on a run that
+   * previously touched nothing — spending `overrides.json.bak`, the user's
+   * only surviving pre-cut save and the sole route back to the split half they
+   * deleted, on a copy of the already-damaged document (final review, Critical
+   * 2). A run that placed nothing has nothing to write and no business
+   * touching the `.bak`. Renamed as well as re-defined, because "keys changed"
+   * is no longer even true of it: a `superseded` retirement changes the keys
+   * and deliberately does not fire this.
+   */
+  reanchored: boolean;
+  /** Everything produce should print about this, in order. */
+  log: string[];
+}
+
+/**
+ * Migrate, then apply, then account for the difference — the whole caption
+ * half of a produce run, in one pure pass.
+ *
+ * MIGRATE FIRST, and against these same lines: `applyCaptionEdits` addresses
+ * words by source anchor, so a pre-§137 positional key matches nothing at all
+ * and every retype in an old project would be silently absent from the render
+ * (§137 Task 6 review, Critical 1). Nothing needs backfilling here — produce
+ * builds these lines itself, with a real `srcStart` on every word — which is
+ * exactly why this migration belongs in produce even though the same call in
+ * the edit server would be inert.
+ *
+ * WHAT IS APPLIED AND WHAT IS KEPT ARE DIFFERENT SETS, deliberately (final
+ * review, Critical 1). Only the edits the migration PLACED are applied — an
+ * unresolved key addresses no word, so handing it to `applyCaptionEdits` would
+ * buy nothing but a second, worse-worded report of the same edit. The doc
+ * written back keeps them anyway (`captionEditsToKeep`), because a run that
+ * cannot place an edit today is not a licence to delete it.
+ *
+ * The caller must hand a doc that has been through `OverrideDocSchema`
+ * (`produce.ts` parses it at the top of the run). On raw `JSON.parse` output a
+ * literal `"__proto__"` key would be assigned THROUGH rather than kept, and
+ * the migration would report nothing lost while losing it.
+ */
+export function reconcileCaptionEdits(
+  doc: OverrideDoc,
+  baseLines: readonly CaptionLine[],
+): CaptionReconciliation {
+  const log: string[] = [];
+  const migration = migrateCaptionKeys(doc.captions, baseLines);
+  // The MOVED count is both the log gate and the write gate. As a log gate:
+  // announcing "0 caption edit(s) re-anchored" above the lines saying why is
+  // noise on the one run where the user is reading carefully. As a write gate:
+  // see `CaptionReconciliation.reanchored` — a run that placed nothing must
+  // not spend the `.bak`.
+  const reanchored = reanchoredKeyCount(doc.captions, migration);
+  if (reanchored > 0) {
+    log.push(
+      `▸ ${reanchored} caption edit(s) re-anchored from word positions to source time (§137)`,
+    );
+  }
+  for (const u of migration.unresolved) log.push(captionMigrationLine(u));
+  const migrated = { ...doc, captions: captionEditsToKeep(doc.captions, migration) };
+  const { lines, dropped } = applyCaptionEdits(baseLines, migration.edits);
+  const live = appliedCaptionEditCount(migration.edits, dropped);
+  if (live > 0) log.push(`▸ ${live} caption word(s) retyped by the editor`);
+  for (const d of dropped) log.push(captionDropLine(d));
+  return { doc: migrated, lines, reanchored: reanchored > 0, log };
+}

package/src/edit.ts

@@ -259,9 +259,29 @@ export async function startEditServer(
             return send(200, { noWorkdir: true, recent: await readRecentProjects(opts.recentDir) });
           }
           const renderProps = JSON.parse(await readFile(propsPath(), "utf8"));
+          // Parsed, never cast — and that parse is also what makes the doc
+          // safe to migrate downstream: a literal `"__proto__"` caption key
+          // survives `JSON.parse` as an own property, and any later pass that
+          // rebuilds the record would assign through it instead of keeping it.
           const overrides = existsSync(overridesPath())
             ? OverrideDocSchema.parse(JSON.parse(await readFile(overridesPath(), "utf8")))
             : emptyOverrideDoc();
+          // §137 DECISION (Task 6): the pre-§137 caption-key migration does
+          // NOT run here. It resolves a positional key by finding the word it
+          // named and taking that word's source anchor — and these render
+          // props are served exactly as they sit on disk, where a pre-§137
+          // file's caption words have no `srcStart` at all. Every word would
+          // answer "no anchor", every edit would land in `unresolved`, and the
+          // migration would report total loss while doing nothing: a call that
+          // passes its own tests and is inert in production.
+          // Anchoring them here instead would mean a second copy of the "no
+          // usable map, no repair" rule (`anchorCaptionLines`, apps/editor) in
+          // this package — the CLI cannot import the editor's source, which it
+          // only ever ships as a built `editor-dist/` — and that rule is
+          // exactly the one §137 refuses to have two of. So the EDITOR owns
+          // the repair, at the one point that holds anchored lines and the doc
+          // at the same time (App.tsx's load path), and it loses no reach:
+          // this endpoint has exactly one consumer.
           return send(200, {
             renderProps,
             overrides,
@@ -450,6 +470,24 @@ export async function startEditServer(
           for await (const c of req) chunks.push(c as Buffer);
           const parsed = OverrideDocSchema.safeParse(JSON.parse(Buffer.concat(chunks).toString()));
           if (!parsed.success) return send(400, { error: parsed.error.message });
+          // NO `.bak` HERE, and that is a decision, not an omission (final
+          // review, Important 5). This write is safe without one only because
+          // it ROUND-TRIPS: whatever the editor loaded, it saves back, plus
+          // the change the user just made. §137 briefly broke that property —
+          // `migrateLoadedDoc` stripped the caption edits the migration could
+          // not place before `edits.load` (which also clears undo), so the
+          // first save after opening a legacy project deleted them
+          // permanently. The fix is in `migrateLoadedDoc`, which now keeps
+          // them, rather than here.
+          //
+          // Adding produce's `.bak` to this handler was the other option and
+          // is actively worse: `overrides.json.bak` is single-generation and
+          // SHARED with produce's write, so a routine ⌘S would spend the one
+          // the user's pre-cut save is sitting in — which on the §137 field
+          // workdir is the only artefact their deleted split half can ever be
+          // recovered from (`legacySplitId`). That is the review's own
+          // Critical 2 reintroduced through the editor.
+          //
           // Atomic: the producer may read this file at any moment, and a
           // half-written document would be worse than a stale one.
           const tmp = `${overridesPath()}.tmp`;

package/src/interactive/ask-input.ts

@@ -0,0 +1,191 @@
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { livePickerDeps, pickPath, pickerAvailable, type PickMode } from "./picker";
+import { assertInteractive, select, text, unwrap } from "./prompts";
+import { rankSuggestions, scanLikelyDirs, type Suggestion } from "./suggest-inputs";
+
+/**
+ * "Which video?" — the first prompt of the wizard, and until §136 the one
+ * step a non-technical user could not get past: it demanded a typed path.
+ * Now it is a menu of the newest videos on the machine, a native picker, and
+ * typing, in that order.
+ *
+ * Every branch converges on `validateInputPath` rather than trusting its
+ * source. A picker result is not more trustworthy than typed text: the file
+ * can be deleted between the dialog closing and the path arriving, and
+ * "Browse for a folder" happily returns a folder with no video in it.
+ */
+
+export const BROWSE_FILE = "__browse_file__";
+export const BROWSE_FOLDER = "__browse_folder__";
+export const TYPE_PATH = "__type_path__";
+
+export type InputSource = "suggestion" | "picker" | "typed";
+
+/**
+ * Not a zod schema, deliberately: the house rule parses user values with zod
+ * because a typo must not silently coerce, and there is nothing to coerce
+ * here — this is a filesystem predicate (does it exist, is it a file or a
+ * folder), which zod cannot answer. The wording is carried over verbatim
+ * from the prompt this replaced.
+ *
+ * There is deliberately no extension whitelist, on any branch: typing a path
+ * was never extension-checked either, and ossclip accepts whatever ffmpeg can
+ * read — a list would reject legitimate containers.
+ */
+export function validateInputPath(v: string | undefined): string | undefined {
+  if (!v) return "a path is required";
+  if (!existsSync(v)) return `no such path: ${v}`;
+  const st = statSync(v);
+  if (!st.isFile() && !st.isDirectory()) return `${v} is neither a video file nor a folder`;
+  return undefined;
+}
+
+export function inputChoices(
+  suggestions: Suggestion[],
+  canBrowse: boolean,
+): { value: string; label: string; hint?: string }[] {
+  const rows = suggestions.map((s) => ({ value: s.path, label: s.label, hint: s.hint }));
+  // Offering a "Browse…" row on a machine with no dialog to open is worse
+  // than not offering it — `pickerAvailable` has already probed, so the row
+  // simply does not exist when it cannot work.
+  if (canBrowse) {
+    rows.push(
+      { value: BROWSE_FILE, label: "Browse…", hint: "opens a file picker" },
+      { value: BROWSE_FOLDER, label: "Browse for a folder of clips", hint: "concatenated by name" },
+    );
+  }
+  rows.push({ value: TYPE_PATH, label: "Type a path", hint: "if you already know it" });
+  return rows;
+}
+
+let lastInputSource: InputSource | "argv" = "argv";
+
+/** Which branch produced the input, for the produce_completed event (§136). */
+export function noteInputSource(s: InputSource): void {
+  lastInputSource = s;
+}
+
+export function inputSourceUsed(): InputSource | "argv" {
+  return lastInputSource;
+}
+
+/**
+ * Module state outlives a single wizard, and "argv" is a real answer — the
+ * value the telemetry reads when `ossclip <path>` prefilled the input and
+ * `askInput` never ran. So a second run in the same process (a batch or REPL
+ * caller, and every test file, where module state persists across `it`s)
+ * would report the PREVIOUS run's branch with nothing to signal the staleness.
+ * Reset at the start of a run — or of a test — rather than trusting one
+ * invocation per process.
+ */
+export function resetInputSource(): void {
+  lastInputSource = "argv";
+}
+
+/**
+ * The seam. Same shape and same reason as `PickerDeps` (picker.ts) and
+ * `TtyDeps` (tty.ts): the branch logic is what has rules worth pinning — a
+ * cancelled dialog re-asks, every branch validates, each sets its own source —
+ * and none of that is reachable through a real `select` blocking on a human.
+ * `pickPath` is tested the same way through its own injected deps.
+ *
+ * Structural signatures rather than `typeof select`: clack's are generic, and
+ * a fake cannot satisfy an unresolved type parameter. Narrowing here is what
+ * makes the fakes writable, exactly as `PickerDeps` declares `hasBin` rather
+ * than `typeof binOnPath`.
+ */
+export interface AskInputDeps {
+  /** Probed once per run, not per loop — no dialog appears mid-prompt. */
+  canBrowse: boolean;
+  suggest: () => Promise<Suggestion[]>;
+  pick: (mode: PickMode) => Promise<string | undefined>;
+  select: (opts: {
+    message: string;
+    options: { value: string; label: string; hint?: string }[];
+  }) => Promise<string | symbol>;
+  text: (opts: {
+    message: string;
+    placeholder?: string;
+    validate?: (v: string | undefined) => string | undefined;
+  }) => Promise<string | symbol>;
+  /** Injected because the guard itself takes an injected check (tty.ts:58). */
+  assertInteractive: () => void;
+}
+
+export const liveAskInputDeps = (): AskInputDeps => ({
+  canBrowse: pickerAvailable(livePickerDeps()),
+  suggest: async () => rankSuggestions(await scanLikelyDirs(), Date.now(), homedir()),
+  pick: (mode) => pickPath(mode),
+  select,
+  text,
+  assertInteractive: () => assertInteractive("input prompt"),
+});
+
+const typePath = async (deps: AskInputDeps): Promise<string> =>
+  unwrap(
+    await deps.text({
+      // Finding 1 (final-review fix wave): `ossclip produce <folder>` shipped
+      // (folder-input-brief.md) but this prompt still rejected a directory —
+      // the wizard was the only way in that couldn't do what the CLI could.
+      // A folder is concatenated by name (codepoint order, like `ls`); --sort
+      // mtime reorders it but stays a typed flag, not a wizard question (see
+      // the file-level comment in produce-wizard.ts for why).
+      message: "Video file, or a folder of clips to concatenate (by name; --sort mtime is a typed flag)",
+      placeholder: "./raw/take1.mp4",
+      validate: validateInputPath,
+    }),
+  ) as string;
+
+export async function askInput(deps: AskInputDeps = liveAskInputDeps()): Promise<string> {
+  deps.assertInteractive();
+  const canBrowse = deps.canBrowse;
+  const suggestions = await deps.suggest();
+
+  // Nothing found and nowhere to browse: a one-row menu is pure noise, so go
+  // straight to the prompt this whole unit replaced.
+  if (suggestions.length === 0 && !canBrowse) {
+    noteInputSource("typed");
+    return typePath(deps);
+  }
+
+  // Loops rather than returns, because cancelling the OS dialog must land
+  // back on the menu — Escape in a Finder window means "not that one", not
+  // "abandon the run". Ctrl-C at the menu still exits via `unwrap`.
+  for (;;) {
+    const choice = unwrap(
+      await deps.select({ message: "Which video?", options: inputChoices(suggestions, canBrowse) }),
+    ) as string;
+
+    if (choice === TYPE_PATH) {
+      noteInputSource("typed");
+      return typePath(deps);
+    }
+
+    if (choice === BROWSE_FILE || choice === BROWSE_FOLDER) {
+      const picked = await deps.pick(choice === BROWSE_FOLDER ? "folder" : "file");
+      // An empty result conflates "cancelled" with "the backend failed
+      // silently" — no backend distinguishes them reliably (picker.ts), and
+      // `pickPath` has already printed the fallback notice in the failure
+      // case. Re-asking is the right next step either way.
+      if (picked === undefined) continue;
+      const problem = validateInputPath(picked);
+      if (problem !== undefined) {
+        console.log(`▸ ${problem}`);
+        continue;
+      }
+      noteInputSource("picker");
+      return picked;
+    }
+
+    // A suggestion. Still validated: the listing is a snapshot, and a file
+    // can be moved between the scan and the keypress.
+    const problem = validateInputPath(choice);
+    if (problem !== undefined) {
+      console.log(`▸ ${problem}`);
+      continue;
+    }
+    noteInputSource("suggestion");
+    return choice;
+  }
+}