@ossclip/core 0.1.27 → 0.1.29

package/package.json

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

package/src/browser.ts

@@ -45,11 +45,72 @@ export {
 // types only). The editor's load-path repair needs the MAP, not the raw span
 // 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";
+// `mapsClose` rides along since cut review step 4: the editor's playhead
+// hand-off across a live re-cut needs "did the clock actually change" to be
+// the SAME float-tolerant comparison `livePreviewMap`'s identity gate uses,
+// or a 1-ulp drift could seek the player for nothing.
+export { mapFromKeptSpans, mapsClose, 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";
+// The cleanup veto layer (cut review step 3), VALUE exports and browser-safe:
+// cutlist.ts imports nothing but types from ./schema — verified before this
+// export, zero node built-ins in its graph. The editor marks vetoed seams
+// with the SAME `applyCleanupChoices` produce renders with (the
+// buildCoverRender one-implementation-two-callers pattern); a browser copy is
+// how the preview and the render would drift. `buildCutlist` itself rides
+// along in the module graph but stays unexported here on purpose — the
+// editor must never rebuild the proposal, only apply choices to the one
+// produce recorded.
+export {
+  applyCleanupChoices,
+  cleanupVetoable,
+  vetoedRemovals,
+  type CleanupChoices,
+} from "./cutlist";
+// The live post-veto preview (cut review step 4), VALUE exports and
+// browser-safe: retime-preview.ts composes cutlist + recut + timemap — all
+// already in this surface's runtime graph (recut.ts imports only overrides
+// and timemap, zero node built-ins, verified before this export). The editor
+// re-cuts its preview clock with the SAME `applyCleanupChoices` +
+// `subtractRangesFromCutlist` sequence produce runs and re-times every prop
+// through the SAME `remapPoint` produce re-anchors with — one implementation,
+// two callers, so the preview cannot drift from the render.
+// `previewClockMappers` rides along (step 4 follow-up): the surfaces that
+// speak in single instants — transcript seeks, ghost bands, the cover
+// panel's playhead — need the same walk as a point function, identity when
+// no re-cut is live, threaded by App so no consumer learns the machinery.
+// `cutRangeToOldClock` is the WRITE direction's range half (the follow-up's
+// follow-up): a cut gesture's live window converted to the old-clock frame
+// `doc.cuts` speaks, shared by the Inspector's button and App's delete
+// modal so the shrink/refuse verdict cannot drift between the two.
+export {
+  cutRangeToOldClock,
+  livePreviewMap,
+  previewClockMappers,
+  retimeForPreview,
+  type LivePreviewClocks,
+  type OldClockCutRange,
+  type PreviewClockMappers,
+  type RetimeablePreviewProps,
+  type RetimedPreviewFields,
+} from "./retime-preview";
+export type {
+  Probe,
+  Production,
+  // `RemovalReason` rides along with `Segment` (cut review step 2): the
+  // editor's reason→colour map is a `Record<RemovalReason, string>` precisely
+  // so a NEW reason in the vocabulary fails typecheck in the editor instead
+  // of silently drawing an uncoloured seam. (Since step 3 the schema module
+  // is in the runtime graph anyway — ./overrides imports RemovalReasonSchema
+  // for the `cleanup` key — but schema.ts is zod + scene-schema only, both
+  // already on this surface, so it stays browser-safe.)
+  RemovalReason,
+  RenderSettings,
+  Segment,
+  Transcript,
+  Word,
+} from "./schema";

package/src/config.ts

@@ -19,6 +19,16 @@ export interface OssclipConfig {
    * sheet always uses the main model. "same" disables tiering (FINDINGS §37).
    */
   fastModel?: string;
+  /**
+   * Reasoning effort for the antigravity provider — low | medium | high,
+   * agy's own `--effort` vocabulary. Consumed ONLY by antigravity today
+   * (§143: exposed after the hang incident — the knob existed and we passed
+   * nothing); every other provider ignores it. `--llm-effort` wins over this
+   * per run. File-only like `dictionary`; validated at the consumer
+   * (`resolveLlmEffort` in produce.ts), so a hand-edited `"max"` is one
+   * warning and an ignored key, never a coerced effort level.
+   */
+  llmEffort?: string;
   /**
    * Download URLs for models the ggerganov mirror doesn't host, keyed by the
    * bare model name — a user's own fine-tune needs one line:
@@ -196,6 +206,11 @@ export function loadConfig(): OssclipConfig {
     modelDir: process.env.OSSCLIP_MODEL_DIR ?? fileCfg.modelDir ?? DEFAULTS.modelDir,
     model: process.env.OSSCLIP_MODEL ?? fileCfg.model ?? DEFAULTS.model,
     fastModel: process.env.OSSCLIP_FAST_MODEL ?? fileCfg.fastModel,
+    // File-only, the `dictionary` posture — and deliberately NO env spelling
+    // (flag + config are the whole interface): validated where it is USED
+    // (`resolveLlmEffort` in produce.ts), so a hand-edited `"max"` earns one
+    // warning there and agy's default, never a coerced effort.
+    llmEffort: fileCfg.llmEffort,
     speaker: process.env.OSSCLIP_SPEAKER ?? fileCfg.speaker,
     openEditorAfterProduce: (process.env.OSSCLIP_OPEN_EDITOR ??
       fileCfg.openEditorAfterProduce) as OpenEditorPref | undefined,

package/src/cover-headline.ts

@@ -26,10 +26,17 @@
  */
 export const COVER_MAX_WORDS = 9;
 
-/** Trailing words that cannot end a headline — the truncation reads as broken. */
+/**
+ * Trailing words that cannot end a headline — the truncation reads as broken.
+ * Auxiliaries dangle exactly like prepositions: a real run (2026-08-22)
+ * truncated to "AI Gave Me Too Many Ideas. I Had" because the set had none.
+ * "i" is here for the same incident: popping "Had" alone leaves "…Ideas. I",
+ * a subject with its sentence cut off.
+ */
 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",
+  "had", "has", "have", "was", "were", "will", "can", "should", "i",
 ]);
 
 /**

package/src/cutlist.ts

@@ -329,3 +329,112 @@ export function buildCutlist({
 
   return segments;
 }
+
+/**
+ * The user's veto layer over the automatic cutlist (cut review step 3):
+ * `buildCutlist` PROPOSES removals, this is how the user DECLINES some of
+ * them — per category ("keep all pauses") and per individual span. Persisted
+ * as `overrides.json`'s `cleanup` key (`OverrideDocSchema.cleanup`, which
+ * owns the on-disk contract); this structural interface is what the pure
+ * functions below accept, so this module stays free of zod and of the
+ * overrides module — callable from produce AND from the editor bundle with
+ * nothing but the schema's own types.
+ */
+export interface CleanupChoices {
+  /**
+   * Category master switches. `false` = do not remove this reason's spans;
+   * absent (or a tolerated `true` on disk) = the default, remove as proposed.
+   */
+  reasons?: Partial<Record<RemovalReason, boolean>>;
+  /** Individual vetoes, SOURCE seconds — see `vetoedRemovals` for the
+   * overlap-based matching rule. */
+  kept?: readonly { srcIn: number; srcOut: number }[];
+}
+
+/**
+ * Whether a removal reason CAN be declined at all. `user` cuts come from the
+ * `cuts[]` array — declining your own cut is Restore on the cut, an existing
+ * gesture, and a second way to undo it would leave the entry behind as dead
+ * weight (there is no "not cut" state for a `cuts` entry to hold, per its
+ * schema comment). `clip` is the `--clip` window, a selection decision, not a
+ * cleanup — "keeping" a clip removal would silently un-clip the video. One
+ * predicate, exported, so produce, the panel's checkboxes and the timeline's
+ * seam handler cannot disagree about what is toggleable.
+ */
+export function cleanupVetoable(reason: RemovalReason | undefined): boolean {
+  return reason !== "user" && reason !== "clip";
+}
+
+/**
+ * The `remove` spans of `cutlist` that `choices` declines — the shared
+ * predicate under `applyCleanupChoices` (which re-keeps exactly these) and
+ * the editor's vetoed-seam state / produce's "kept N pause removal(s)" line
+ * (which both NAME them). One list, computed once, so what the seam shows as
+ * "will be kept" and what the render actually keeps cannot drift.
+ *
+ * Individual vetoes match by OVERLAP, deliberately NOT by float equality of
+ * endpoints: a re-produce can shift a removal's boundary by a frame (a
+ * changed silence threshold, a repair that re-stamps a word), and an
+ * exact-match veto that silently stops matching is the failure mode — the
+ * pause the user declined would quietly start being cut again. A partial
+ * overlap re-keeps the WHOLE removal span: a removal is one decision, not
+ * divisible.
+ */
+export function vetoedRemovals(
+  cutlist: readonly Segment[],
+  choices: CleanupChoices | undefined,
+): Segment[] {
+  if (!choices) return [];
+  const kept = choices.kept ?? [];
+  return cutlist.filter(
+    (seg) =>
+      seg.kind === "remove" &&
+      cleanupVetoable(seg.reason) &&
+      ((seg.reason !== undefined && choices.reasons?.[seg.reason] === false) ||
+        kept.some((k) => k.srcIn < seg.srcOut && k.srcOut > seg.srcIn)),
+  );
+}
+
+/**
+ * Apply the user's cleanup choices to the automatic cutlist: every vetoed
+ * removal (see `vetoedRemovals`) becomes a keep again, and adjacent keeps
+ * merge so the result stays the same canonical shape `buildCutlist` emits —
+ * a full partition of the input's range with no gaps, no overlaps, monotonic
+ * (the invariants `TimeMap`'s constructor checks). The partition holds BY
+ * CONSTRUCTION: spans are only relabelled and merged, never moved, so the
+ * covered range cannot change.
+ *
+ * `undefined`/empty choices return the input content unchanged — the
+ * regression anchor: an overrides.json with no `cleanup` key must produce a
+ * byte-identical render.
+ *
+ * ONE implementation, two callers (the `buildCoverRender` pattern): produce
+ * calls this between `buildCutlist` and the `TimeMap`; the editor calls it
+ * (via `@ossclip/core/browser`) to mark vetoed seams. A preview that
+ * disagrees with the render is worse than no preview.
+ */
+export function applyCleanupChoices(
+  cutlist: readonly Segment[],
+  choices: CleanupChoices | undefined,
+): Segment[] {
+  const vetoed = new Set(vetoedRemovals(cutlist, choices));
+  if (vetoed.size === 0) return [...cutlist];
+  const out: Segment[] = [];
+  for (const seg of cutlist) {
+    // A re-kept span drops `reason`/`confidence` — they described a removal
+    // that is no longer happening, and a keep carrying "pause" would read as
+    // a seventh segment kind everywhere the partition is consumed.
+    const next: Segment = vetoed.has(seg)
+      ? { srcIn: seg.srcIn, srcOut: seg.srcOut, kind: "keep" }
+      : seg;
+    const prev = out[out.length - 1];
+    if (prev !== undefined && prev.kind === "keep" && next.kind === "keep") {
+      // Merge in place — `prev` is always this function's own object (pushed
+      // below as a fresh literal when it is a keep), never the caller's.
+      prev.srcOut = next.srcOut;
+      continue;
+    }
+    out.push(next.kind === "keep" ? { srcIn: next.srcIn, srcOut: next.srcOut, kind: "keep" } : next);
+  }
+  return out;
+}

package/src/index.ts

@@ -12,6 +12,7 @@ export * from "./concat";
 export * from "./transcribe";
 export * from "./analyze";
 export * from "./cutlist";
+export * from "./retime-preview";
 export * from "./clip";
 export * from "./blooper";
 export * from "./retake";

package/src/overrides.ts

@@ -7,6 +7,7 @@ import {
   type SceneComponentId,
   type Theme,
 } from "./scene-schema";
+import { RemovalReasonSchema } from "./schema";
 import { resolveSceneProps } from "./scene-registry";
 import type { CaptionLine, CaptionWord } from "./captions";
 
@@ -435,6 +436,42 @@ export const OverrideDocSchema = z.object({
       }),
     )
     .default([]),
+  /**
+   * The user's VETO over the automatic cutlist (cut review step 3). `cuts`
+   * above is the user ADDING a removal; this is the user DECLINING one the
+   * pipeline proposed — opposite directions, deliberately not merged.
+   * Consumed by `applyCleanupChoices` (cutlist.ts, which owns the matching
+   * semantics), in produce and in the editor alike.
+   *
+   * `reasons` are the category master switches ("keep all pauses"). Only
+   * `false` is ever WRITTEN — a `true` entry restates the default, and the
+   * editor DELETES the key instead (the `hidden`/`captionsHidden` rule: an
+   * override with nothing to say). A `true` on disk is still parsed and
+   * means default, tolerantly. `user` and `clip` keys parse but are inert
+   * (`cleanupVetoable`): declining your own cut is Restore on the cut, and
+   * "keeping" the --clip window's removal would silently un-clip the video.
+   *
+   * `kept` are individual vetoes, in SOURCE seconds — and that anchoring is
+   * the whole trick, same as `cuts[].src` above: a bare output-seconds pair
+   * is meaningless once its own re-cut has happened, while source time is
+   * stable across every re-cut. This layer is therefore RECUT-IMMUNE BY
+   * CONSTRUCTION and — unlike `splits` and `scenes[*].timing` — needs NO
+   * entry in `remapOverridesThroughRecut`. Matching against the (possibly
+   * re-produced) cutlist is by OVERLAP, never float equality of endpoints;
+   * `vetoedRemovals` (cutlist.ts) states why.
+   *
+   * Optional-with-default like `splits`/`cuts`, so every overrides.json
+   * written before the key existed parses byte-identically; absent means
+   * today's behaviour exactly.
+   */
+  cleanup: z
+    .object({
+      reasons: z.partialRecord(RemovalReasonSchema, z.boolean()).default({}),
+      kept: z
+        .array(z.object({ srcIn: z.number().nonnegative(), srcOut: z.number().nonnegative() }))
+        .default([]),
+    })
+    .default({ reasons: {}, kept: [] }),
 });
 export type OverrideDoc = z.infer<typeof OverrideDocSchema>;