@a-company/atelier 0.37.0 → 0.38.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
-import { AtelierDocument, StudioRecipe, VideoProjectManifest, CutEntry, VideoCutList, VideoTranscript, Layer, Delta, TranscriptWord } from '@a-company/atelier-types';
+import { AtelierDocument, StudioRecipe, VideoProjectManifest, CutEntry, VideoCutList, VideoTranscript, Layer, Delta, TranscriptWord, SlideTransition, ProjectKind } from '@a-company/atelier-types';
 import { ResolvedFrame } from '@a-company/atelier-core';
+import { DesignArtifact, ScriptArtifact, StoryboardArtifact } from '@a-company/atelier-schema';
 
 /**
  * Validate an .atelier file: parse YAML, check schema, check delta overlaps.
@@ -261,17 +262,24 @@ declare function carouselFileName(index: number, total: number, imagePath: strin
  */
 declare function carouselCommand(program: Command): void;
 
-/** Asset summary entry */
+/**
+ * Asset summary entry. v1.0: `usedByStates` removed — audio is no longer
+ * state-scoped (it's an AudioVisual layer), so layer-only tracking is now
+ * the complete picture.
+ */
 interface AssetInfo {
     assetId: string;
     type: string;
     src: string;
     description?: string;
     usedByLayers: string[];
-    usedByStates: string[];
 }
 /**
  * Extract asset info from a parsed AtelierDocument.
+ *
+ * Walks all layers (image, video, audio) for assetId references. Pre-v1
+ * docs that still carry `state.audio` are silently migrated by the parser
+ * (audio field stripped); no per-state asset usage is tracked.
  */
 declare function getAssets(doc: AtelierDocument): AssetInfo[];
 /**
@@ -310,6 +318,19 @@ interface RenderOptions {
     format: RenderFormat;
     states?: string[];
     onProgress?: (info: ProgressInfo) => void;
+    /**
+     * Absolute path of the .atelier document being rendered. Used to resolve
+     * relative `media/...` src paths in VideoVisual layers. When set, the
+     * pipeline detects the first video layer, passes the source MOV/MP4 to
+     * ffmpeg as a SECOND input, and uses an overlay filter to composite the
+     * caption canvas ON TOP of the source video frames (instead of feeding
+     * the encoder a synthetic canvas-only stream). Source audio is also
+     * mapped through verbatim. This is what closes the
+     * RENDER-AUDIO-ISSUE.md gap reported by the agent team on 2026-05-28.
+     *
+     * Omitted → legacy behaviour (canvas-only frames, no audio).
+     */
+    docPath?: string;
 }
 interface ProgressInfo {
     frame: number;
@@ -326,8 +347,26 @@ interface RenderResult {
 }
 /** Check whether FFmpeg is available on the system PATH. */
 declare function checkFfmpeg(): Promise<boolean>;
-/** Build the FFmpeg argument array for the given format. Pure function. */
-declare function buildFfmpegArgs(width: number, height: number, fps: number, format: RenderFormat, output: string): string[];
+/**
+ * Build the FFmpeg argument array for the given format. Pure function.
+ *
+ * When `sourceVideoPath` is provided, ffmpeg gets TWO inputs:
+ *   - Input 0: the source video file (decoded photographic frames + audio)
+ *   - Input 1: raw BGRA canvas frames on stdin (the caption overlay)
+ *
+ * A `[0:v][1:v]overlay` filter composites the canvas on top of the source
+ * video at matching timestamps. Source audio is copied through with
+ * `-map 0:a -c:a copy` (no re-encode). The MP4 output then has full source
+ * video bitrate + source audio + caption overlays — what the studio's
+ * MediaRecorder path produces by accident, but deterministically and
+ * scriptable for agent use.
+ *
+ * When `sourceVideoPath` is omitted, falls back to the legacy stdin-only
+ * mode (canvas frames only, no source pixels, no audio). Used by docs
+ * without any VideoVisual layers (e.g. text-only animations, image
+ * carousels).
+ */
+declare function buildFfmpegArgs(width: number, height: number, fps: number, format: RenderFormat, output: string, sourceVideoPath?: string): string[];
 /**
  * Render an Atelier document to a video/GIF file via FFmpeg.
  * Dynamically imports `canvas` (node-canvas) — fails with a helpful
@@ -460,8 +499,20 @@ declare function trimProject(projectDir: string, options?: TrimOptions): Promise
 /** Register `atelier trim` on the Commander program */
 declare function trimCommand(program: Command): void;
 
-/** Whisper model selection (size/quality tradeoff) */
-type WhisperModel = "tiny" | "tiny.en" | "base" | "base.en" | "small" | "small.en" | "medium" | "medium.en" | "large-v3";
+/**
+ * Whisper model selection (size/quality tradeoff).
+ *
+ * The set mirrors whisper.cpp's published model registry on HuggingFace
+ * (https://huggingface.co/ggerganov/whisper.cpp). Quantized variants and
+ * the v3-turbo line are first-class — creators get the best local-quality
+ * tradeoff without needing to know the model-zoo URL by heart.
+ *
+ * Note: the type is intentionally open to `string` via the fallback union so a
+ * creator can pass a future model name (e.g. a new quant variant) without us
+ * having to ship a code change. `resolveWhisperModelPath` will attempt to
+ * resolve any string against the cache + HuggingFace registry.
+ */
+type WhisperModel = "tiny" | "tiny.en" | "base" | "base.en" | "small" | "small.en" | "medium" | "medium.en" | "large-v3" | "large-v3-turbo" | "large-v3-turbo-q5_0" | "large-v3-q5_0" | (string & {});
 interface WhisperOptions {
     /** Model size (default: "base.en") */
     model?: WhisperModel;
@@ -469,6 +520,11 @@ interface WhisperOptions {
     language?: string;
     /** Explicit path to the model file — overrides model lookup by name */
     modelPath?: string;
+    /**
+     * Optional progress callback for model download (bytes received, total bytes
+     * when known). Surfaced as a one-time download on first use of any model name.
+     */
+    onProgress?: (received: number, total: number | null) => void;
 }
 /** Backend that produced a transcript run */
 type WhisperBackend = "whisper-cpp" | "openai-api" | "none";
@@ -486,6 +542,11 @@ declare function probeWhisper(): Promise<WhisperBackend>;
  * Note: whisper-cli writes JSON to stdout when given --output-json and "-"
  * as the output destination. Some builds always write to a file with the
  * `.json` suffix appended to the input path; we handle both.
+ *
+ * Model resolution: if `options.modelPath` is set, it's passed through. Else
+ * `options.model` (default `base.en`) is resolved via `resolveWhisperModelPath`,
+ * downloading from the HuggingFace public registry on first use. Once the
+ * model is cached, no network call is made.
  */
 declare function runWhisperCpp(sourcePath: string, options?: WhisperOptions): Promise<string>;
 /**
@@ -564,6 +625,15 @@ declare function rewriteCaptionLayers(doc: AtelierDocument, transcript: VideoTra
 interface TranscribeOptions {
     /** Whisper model selection */
     model?: WhisperModel;
+    /** Explicit path to the model file — overrides model short-name lookup */
+    modelPath?: string;
+    /**
+     * Override the source video path. By default `transcribeProject` uses the
+     * legacy VideoProject scanner (`<projectDir>/source.<ext>`). Passing
+     * `sourcePath` lets the multi-media ingest target an arbitrary media file
+     * (e.g. `<projectDir>/media/<basename>`) without copying it to root.
+     */
+    sourcePath?: string;
     /** BCP-47 language hint (omit for autodetect) */
     language?: string;
     /** Discard existing user edits; full fresh transcript */
@@ -683,6 +753,255 @@ declare function recipeCommand(program: Command): void;
  */
 declare function applyRecipeCommand(program: Command): void;
 
+/**
+ * Atelier creator learning-mode I/O.
+ *
+ * `learning-mode.yaml` lives at `<project-dir>/.atelier/learning-mode.yaml`
+ * and stores the creator's pre-declared autonomy posture (TD-2026-05-26-646):
+ *
+ *   - `ambient`  — the agent team captures corrections silently and surfaces
+ *                  patterns when confident.
+ *   - `explicit` — nothing locks in without the creator's "yes"; high control,
+ *                  more friction.
+ *
+ * Set once by `atelier init`. The system never auto-prompts to switch — the
+ * creator changes mode by editing the file. Iris (and friends) read it at
+ * session start to calibrate their behavior.
+ *
+ * Format is hand-rolled YAML (a handful of scalars) so we don't pull in a YAML
+ * dep here; the schema is intentionally tiny and stable.
+ */
+type LearningMode = "ambient" | "explicit";
+declare const LEARNING_MODES: readonly LearningMode[];
+declare const LEARNING_MODE_VERSION: "1.0";
+/** Shape persisted to disk. */
+interface LearningModeFile {
+    /** Schema version of this file. */
+    version: string;
+    /** Creator's chosen autonomy posture. */
+    mode: LearningMode;
+    /** ISO 8601 timestamp set by the writer. */
+    chosen_at: string;
+}
+/** Absolute path to the learning-mode file for a project. */
+declare function learningModePath(projectDir: string): string;
+/**
+ * Write `<projectDir>/.atelier/learning-mode.yaml` with the given mode and a
+ * fresh ISO timestamp. Creates `<projectDir>/.atelier/` if absent. Overwrites
+ * any existing file — re-running init is supported and refreshes the
+ * timestamp (mode is whatever the caller passes; the caller decides whether
+ * to re-prompt). Returns the absolute path written.
+ */
+declare function writeLearningMode(projectDir: string, mode: LearningMode, opts?: {
+    chosenAt?: Date;
+}): string;
+/**
+ * Read `<projectDir>/.atelier/learning-mode.yaml` if present. Returns `undefined`
+ * when the file does not exist. Throws a clear Error when the file exists but
+ * is malformed (missing required fields, unknown mode). Hand-rolled scalar
+ * parser — no YAML dep — matched to whatever `writeLearningMode` emits.
+ */
+declare function readLearningMode(projectDir: string): LearningModeFile | undefined;
+/**
+ * Render the canonical YAML body — a fixed-shape doc with header comments
+ * pointing the creator at where to change the mode (TD-2026-05-26-646). Kept
+ * here so the writer and any future reader/round-tripper agree on the shape.
+ */
+declare function renderLearningModeYaml(file: LearningModeFile): string;
+
+/**
+ * `atelier init <project-dir>` — first-run setup for a creator Project.
+ *
+ * Sequence (Phase 3, delegation C; see
+ * docs/keynote/paradigm/phase-3-reconciliation-notes.md §3):
+ *
+ *   1. Create `<project-dir>` if absent (recursive). Refuse if the path
+ *      exists as a file rather than a directory. Existing non-empty dir is
+ *      a "complete the init" workflow — proceed with a note in output.
+ *   2. Determine learning mode. `--mode <ambient|explicit>` skips the
+ *      prompt; otherwise readline-prompts the creator (single question, two
+ *      options, max 3 attempts). Bad `--mode` value exits 1 before any fs
+ *      writes (TD-2026-05-26-646: autonomy posture is pre-declared).
+ *   3. Write `<project-dir>/.atelier/learning-mode.yaml` with the choice
+ *      and an ISO timestamp (delegated to #learning-mode-io).
+ *   4. Create `<project-dir>/.atelier/mind-map/` with a README explaining
+ *      what to put there. README is preserved on re-init (TD-2026-05-26-271:
+ *      nothing in the mind-map leaves the machine).
+ *   5. Unless `--no-scaffold`, drop DESIGN/SCRIPT/STORYBOARD via the
+ *      existing #cli-artifacts `scaffoldArtifacts` helper. Re-init swallows
+ *      the refuse-to-overwrite throw as a soft skip (the operation is
+ *      explicitly idempotent — see init-idempotent-re-run-safe aspect).
+ *   6. Unless `--no-git`, run `git init` in `<project-dir>` if it isn't
+ *      already inside a git repo. Writes a minimal `.gitignore` only when
+ *      one doesn't exist.
+ *
+ * Output: human-formatted step-by-step summary by default; `--json` emits
+ * the documented machine-readable shape. Exit 0 on success, 1 on any
+ * irrecoverable error (file-not-dir, can't determine mode, fs failure).
+ *
+ * The Commander wiring is a thin shell around the pure `runInit(opts)`
+ * helper so test code drives the same code path without process.exit
+ * shenanigans (matches the artifacts.ts split).
+ */
+declare function initCommand(program: Command): void;
+/** Input to `runInit`. Booleans are positive-form (caller pre-resolves --no-X). */
+interface RunInitOptions {
+    projectDir: string;
+    /** Pre-supplied mode (skips the prompt). */
+    mode?: string;
+    /**
+     * When the mode was inherited from a workspace (not explicitly chosen
+     * by the creator for this project), the per-project learning-mode.yaml
+     * gets a comment noting the inheritance. The wrapper sets this when
+     * `--mode` was absent and a workspace's `default_mode` was used.
+     */
+    modeInheritedFromWorkspace?: boolean;
+    /** Run `git init` when not already in a repo. Default true. */
+    git: boolean;
+    /** Drop DESIGN/SCRIPT/STORYBOARD via `scaffoldArtifacts`. Default true. */
+    scaffold: boolean;
+    /** Forward to `scaffoldArtifacts({ force })`. Default false. */
+    force: boolean;
+    /** Suppress interactive prompt fallback (used by --json path). Default false. */
+    json: boolean;
+    /**
+     * Drop a minimal `project.atelier` manifest at the project root so this
+     * directory is recognized as a Project by legacy discovery callers. The
+     * CLI surface (`atelier init`) leaves this true so existing tooling that
+     * keys on the manifest's presence keeps working; the workspace `+ new`
+     * surface (via `createProjectInWorkspace`) passes `false` so the project
+     * stays "lazy" until its first composed `.atelier` doc lands. Default
+     * true (preserves pre-pivot behavior on the CLI path).
+     */
+    writeManifest?: boolean;
+    /**
+     * Test/programmatic override: a function that resolves to the chosen mode
+     * when no `--mode` was passed. Production wiring uses the readline prompt.
+     * Returning `undefined` or throwing aborts with the standard "couldn't
+     * determine learning mode" error.
+     */
+    promptForMode?: () => Promise<LearningMode>;
+}
+/** Result returned by `runInit` and serialized for `--json`. */
+interface InitResult {
+    /** True on the success path. */
+    ok: true;
+    projectDir: string;
+    mode: LearningMode;
+    learningModeFile: string;
+    /** Absolute paths of artifacts written by the scaffold step (may be empty). */
+    scaffolded: string[];
+    /** Absolute paths of artifacts skipped (already existed, no --force). */
+    scaffoldSkipped: string[];
+    mindMapDir: string;
+    /** True when `git init` ran in this invocation. */
+    gitInitialized: boolean;
+    /** True when the dir was already inside an existing git repo. */
+    alreadyInRepo: boolean;
+    /** Notes accumulated during the run (re-init warnings, etc.). */
+    notes: string[];
+}
+/**
+ * Pure helper for `atelier init`. Throws on any irrecoverable error; the
+ * Commander wrapper catches and maps to `process.exit(1)`. Re-runnable on an
+ * already-initialized dir (scaffold's refuse-to-overwrite is downgraded to a
+ * soft skip in this surface — see init-idempotent-re-run-safe aspect).
+ */
+declare function runInit(opts: RunInitOptions): Promise<InitResult>;
+/**
+ * Returns true when `dir` (or any ancestor) sits inside an existing git work
+ * tree. Implemented via `git rev-parse --show-toplevel`; non-zero exit and
+ * any spawn failure (missing git, etc.) are treated as "not in a repo" so the
+ * caller falls through to `git init`.
+ */
+declare function isInsideGitRepo(dir: string): boolean;
+/** Parse a single answer to the mode prompt. Returns undefined on no match. */
+declare function parseModeAnswer(answer: string): LearningMode | undefined;
+
+/**
+ * `atelier artifacts <verb>` — first user-facing surface over the
+ * Phase 2 front-of-pipeline artifact schemas (DESIGN/SCRIPT/STORYBOARD).
+ *
+ * Phase 2 lands the schemas + the `^valid-artifact-set` gate; this CLI
+ * verb is the on-disk runner. `atelier artifacts validate <project-dir>`
+ * walks a Project directory for the three artifact files, parses each
+ * one that's present, runs the cross-artifact validator on whatever
+ * parsed, and prints a human or JSON report.
+ *
+ * Exit-code matrix:
+ *   - parse error on any file → 1
+ *   - validator returns ok: false → 1
+ *   - warnings only, no errors → 0 (per spec §9: pre-VO duration overrun
+ *     is warn-only and must NOT fail the gate)
+ *   - missing artifacts → 0 (per validator: only what's present is checked)
+ *
+ * Output style mirrors `recipe.ts` — `console.log` for results, status
+ * lines prefixed with PASS/FAIL/WARN, `--json` toggles a machine
+ * readable payload. (CLI stdout IS the deliverable here; the generic
+ * Paradigm-logger rule does not apply to CLI verbs — see `recipe.ts`,
+ * `validate.ts`, etc., which all follow this same convention.)
+ */
+declare function artifactsCommand(program: Command): void;
+
+/**
+ * Pure filesystem walker for the front-of-pipeline artifact triplet
+ * (DESIGN.md, SCRIPT.md, STORYBOARD.md). Sibling-of-`project.atelier`
+ * convention per `docs/keynote/paradigm/atelier-front-of-pipeline-artifacts.md`
+ * §2 — the three files sit at the root of a Project directory.
+ *
+ * This module is intentionally pure: no stdout/exit-code coupling. The
+ * `atelier artifacts validate` CLI command (and any future agent / MCP
+ * caller) consumes the structured result and decides what to print.
+ *
+ * Any subset of the three files may exist — the absent ones are
+ * surfaced via `missing` (informational, NOT an error). The validator
+ * (`validateArtifactSet`) runs on whatever was successfully parsed.
+ */
+/** Filenames the walker looks for at the project-dir root. */
+declare const ARTIFACT_FILENAMES: {
+    readonly design: "DESIGN.md";
+    readonly script: "SCRIPT.md";
+    readonly storyboard: "STORYBOARD.md";
+};
+/** Per-file parse failure surface. */
+interface ArtifactParseError {
+    /** Which artifact triplet slot failed. */
+    artifact: "design" | "script" | "storyboard";
+    /** Absolute path to the file that failed. */
+    file: string;
+    /** Human-readable failure message. */
+    message: string;
+}
+/** Structured result of loading the three artifacts from a project dir. */
+interface LoadedArtifactProject {
+    /** Absolute project-dir path that was inspected. */
+    projectDir: string;
+    /** Successfully-parsed DESIGN.md, if present and valid. */
+    design?: DesignArtifact;
+    /** Successfully-parsed SCRIPT.md, if present and valid. */
+    script?: ScriptArtifact;
+    /** Successfully-parsed STORYBOARD.md, if present and valid. */
+    storyboard?: StoryboardArtifact;
+    /**
+     * Names of artifact files that were not found on disk.
+     * NOT an error — absent artifacts are valid per the spec
+     * (only what is present is validated).
+     */
+    missing: string[];
+    /** Per-file parse errors. Empty when all present artifacts parsed cleanly. */
+    parseErrors: ArtifactParseError[];
+}
+/**
+ * Walk a project directory for DESIGN.md / SCRIPT.md / STORYBOARD.md and
+ * parse whichever are present.
+ *
+ * Throws (synchronously) only when `projectDir` itself does not exist or
+ * is not a directory — per-file parse failures are captured into the
+ * returned `parseErrors` array so callers can show every problem at
+ * once instead of one at a time.
+ */
+declare function loadArtifactsFromProject(projectDir: string): LoadedArtifactProject;
+
 declare const RECIPE_VERSION = "1.0";
 interface LoadedRecipe {
     recipe: StudioRecipe;
@@ -741,4 +1060,378 @@ declare function renderRecipeWithDefaults(recipe: StudioRecipe): StudioRecipe;
 /** Serialize a recipe back to YAML for `recipe show` output */
 declare function recipeToYaml(recipe: StudioRecipe): string;
 
-export { type AssetInfo, type BuildCaptionsOptions, CanvasUnavailableError, type CaptionStyle, type DocumentInfo, type LoadedRecipe, type ProgressInfo, RECIPE_VERSION, type RenderFormat, type RenderOptions, type RenderResult, type TranscribeOptions, type TranscribeResult, type TrimOptions, type TrimResult, VIDEO_CUTLIST_VERSION, VIDEO_PROJECT_VERSION, VIDEO_TRANSCRIPT_VERSION, type VariableInfo, type VideoProject, type WhisperBackend, type WhisperModel, type WhisperOptions, applyAdd, applyBatchReplace, applyHide, applyMerge, applyRecipeCommand, applyRecipeToCaptionOptions, applyRecipeToTranscribeOptions, applyRecipeToTrimOptions, applySplit, applyTextEdit, assetsCommand, buildCaptionLayers, buildFfmpegArgs, captionsCommand, carouselCommand, carouselFileName, checkFfmpeg, composeCarouselFrameDoc, createVideoProject, effectiveSpan, expandInputs, exportImageCommand, exportLottieCommand, exportSvgCommand, fitImageToCanvas, flattenWords, getAssets, getInfo, getVariables, groupIntoPhrases, infoCommand, loadCanvasModule, loadRecipe, loadVideoProject, mergeTranscriptWithExisting, parseWhisperCppJson, probeWhisper, readComposition, readCutList, readTranscript, recipeCommand, recipeToYaml, renderCommand, renderDocument, renderDocumentToPng, renderRecipeWithDefaults, resolveExportDimensions, resolveRecipePath, resolveStill, rewriteCaptionLayers, rewriteCutLayers, runWhisperCpp, scaffoldRecipeYaml, stillCommand, transcribeCommand, transcribeProject, transcriptCommand, trimCommand, trimProject, validateCommand, validateFile, variablesCommand, writeComposition, writeCutList, writeTranscript };
+interface ComposeVideoProjectOptions {
+    /** Absolute path to the project root (contains the doc at docPath). */
+    projectDir: string;
+    /**
+     * Project-relative path to the .atelier composition document this helper
+     * reads/writes. Required — no default. Caller computes this from the
+     * ingest slug (e.g. `"img-7346.atelier"`, `"slides/slide-1.atelier"`).
+     * The parent directory is created on demand. The helper NEVER touches
+     * `project.atelier` specifically; only this caller-supplied path.
+     */
+    docPath: string;
+    /**
+     * Absolute path to the source media file. Used to (a) compute a canonical
+     * assetId/layer src reference, and (b) probe duration via ffprobe.
+     */
+    sourceFile: string;
+    /**
+     * Whether to run whisper transcription. Default true. When false, only the
+     * state-duration + video-layer wiring runs (useful when re-composing a
+     * project that already has transcript.json).
+     */
+    transcribe?: boolean;
+    /** Forwarded to `transcribeProject` — model selection, language, etc. */
+    transcribeOptions?: TranscribeOptions;
+    /**
+     * When set, after `transcribeProject` writes the root `transcript.json`
+     * the result is mirrored to `<projectDir>/transcripts/<stem>.json` (per
+     * #transcribe-orchestrator). Pass the basename of the file the creator
+     * just ingested — e.g. `IMG_7347.MOV` for a drag-drop video, or
+     * `source.mp4` for the legacy single-source layout. Omit for
+     * single-source projects that only need the root `transcript.json`
+     * (preserves the legacy `atelier transcribe` contract).
+     */
+    mediaBasename?: string;
+    /**
+     * Test injection point — production wiring uses the real `transcribeProject`.
+     * Mirrors the same hook on `runMediaIngest`. Used by both the single-source
+     * `transcribeProject` path and the per-file `transcribeMediaFile` path
+     * (the orchestrator forwards this fn through unchanged).
+     */
+    transcribeFn?: (dir: string, opts: TranscribeOptions) => Promise<TranscribeResult>;
+    /**
+     * Test injection point — production wiring uses `probeDuration` (ffprobe).
+     * When omitted and ffprobe fails (or isn't installed), we fall back to the
+     * transcript's last word end time.
+     */
+    probeDurationFn?: (sourcePath: string) => Promise<number>;
+    /** Optional caption style overrides passed through to `buildCaptionLayers`. */
+    captionOptions?: BuildCaptionsOptions;
+}
+interface ComposeVideoProjectResult {
+    /** The project.atelier as written to disk. */
+    doc: AtelierDocument;
+    /** True iff a NEW clip layer was added (false on re-ingest of the same src). */
+    addedVideoLayer: boolean;
+    /** Slug derived from the source basename — `clip-<slug>` is the clip layer id. */
+    clipSlug: string;
+    /** Id of the clip layer just (re-)ingested. */
+    clipLayerId: string;
+    /** Name of the state whose duration was set/updated. */
+    targetStateName: string;
+    /** Total duration in seconds written into the target state. */
+    targetDurationSeconds: number;
+    /** Transcription result, when transcription ran. */
+    transcribe?: TranscribeResult;
+    /**
+     * Absolute path to the per-file transcript mirror at
+     * `<projectDir>/transcripts/<stem>.json`. Present only when caller passed
+     * `mediaBasename` and transcription actually ran (and wasn't a dry-run).
+     */
+    mirroredTranscriptPath?: string;
+}
+/**
+ * Compose a playable VideoProject from an ingested source + transcript.
+ *
+ * - Transcribes (unless `transcribe: false`) — writes the transcript file(s).
+ *   The legacy caption-rewrite side effect is neutralized below.
+ * - Lazy-creates the `track-video-1` Group layer if absent.
+ * - Appends a `clip-<slug>` VideoVisual layer parented to the track at the
+ *   end-of-track startFrame (or preserves placement on re-ingest of the same).
+ * - Rebuilds per-clip captions as `cap-<slug>-N` parented to `clip-<slug>`,
+ *   leaving other clips' captions untouched.
+ * - Regenerates the derived `timeline` summary block.
+ * - Sets the target state's duration to cover all clips on all tracks.
+ */
+declare function composeVideoProject(opts: ComposeVideoProjectOptions): Promise<ComposeVideoProjectResult>;
+
+interface ComposeImageProjectOptions {
+    /** Absolute path to project root (contains or will contain the doc at docPath). */
+    projectDir: string;
+    /**
+     * Project-relative path to the .atelier composition document this helper
+     * reads/writes. Required — no default. Caller computes this from the
+     * ingest slug (e.g. `"hero-image.atelier"`, `"slides/slide-1.atelier"`).
+     * The parent directory is created on demand. The helper NEVER touches
+     * `project.atelier` specifically; only this caller-supplied path.
+     */
+    docPath: string;
+    /** Absolute path to the source image file. */
+    sourceFile: string;
+    /** Override target basename inside media/. Defaults to basename(sourceFile). */
+    mediaBasename?: string;
+}
+interface ComposeImageProjectResult {
+    doc: AtelierDocument;
+    /** True iff a new ImageVisual layer was added (vs. doc already had one). */
+    addedImageLayer: boolean;
+    /** Slug-based layer id, e.g. "img-photo-1". One-to-one with assetId. */
+    layerId: string;
+    /** Same as layerId — the asset key. */
+    assetId: string;
+}
+/**
+ * Compose (or re-compose) an Atelier image project from a single source image.
+ *
+ * - Single-image invariant: a second, differently-named image throws.
+ * - Idempotent on re-ingest of the same basename.
+ * - No timeline, no transcript — image projects render as a single frame.
+ */
+declare function composeImageProject(opts: ComposeImageProjectOptions): Promise<ComposeImageProjectResult>;
+
+interface ComposeCarouselProjectOptions {
+    /** Absolute path to project root (contains or will contain the doc at docPath). */
+    projectDir: string;
+    /**
+     * Project-relative path to the CAROUSEL .atelier composition document this
+     * helper reads/writes. Required — no default. Distinct from `slidePath`,
+     * which is the slide being added. Caller computes this from the ingest
+     * slug (e.g. `"gallery.atelier"`). The parent directory is created on
+     * demand. The helper NEVER touches `project.atelier` specifically; only
+     * this caller-supplied path.
+     */
+    docPath: string;
+    /** Absolute path to any .atelier file in the workspace — the slide to add. */
+    slidePath: string;
+    /** Workspace root used for cycle detection. Defaults to dirname(projectDir). */
+    workspaceRoot?: string;
+    /** Index to insert at; default = append. */
+    insertAt?: number;
+    transition?: SlideTransition;
+    /** For image slides — frames to hold; ignored for video slides. */
+    duration?: number;
+    label?: string;
+}
+interface ComposeCarouselProjectResult {
+    doc: AtelierDocument;
+    slideIndex: number;
+    addedSlide: boolean;
+}
+/**
+ * Add a slide reference to a carousel project, cycle-safe.
+ *
+ * - Scaffolds a fresh kind:"carousel" doc if project.atelier is absent.
+ * - Refuses to convert a non-carousel project.
+ * - Refuses to introduce a cycle.
+ * - Idempotent on duplicate slide src.
+ */
+declare function composeCarouselProject(opts: ComposeCarouselProjectOptions): Promise<ComposeCarouselProjectResult>;
+
+/** Classification result for a media filename. */
+type IngestKind = "video" | "image" | "audio" | "unsupported";
+/**
+ * Routing decision for a no-target ingest (file lands in the media bin).
+ *
+ * Post-pivot (TD-2026-05-28): either the file is a supported media kind and
+ * goes to `add-to-bin`, or it's unsupported and we reject. Project kind no
+ * longer factors in — composition is a separate, explicit step.
+ */
+interface BinIngestRoute {
+    kind: IngestKind;
+    target: "add-to-bin" | "reject";
+    /** When target === "reject", the human-readable reason. */
+    error?: string;
+}
+/**
+ * Routing decision for an explicit-target ingest (canvas-area drop).
+ *
+ * The target-set path still uses the legacy four-way target enum since it
+ * really does dispatch to compose-video / add-audio-clip / etc.
+ */
+interface IngestRoute {
+    kind: IngestKind;
+    target: "compose-video" | "compose-image" | "add-audio-clip" | "reject";
+    /** When target === "reject", the human-readable reason. */
+    error?: string;
+    /**
+     * When set, the project-relative `.atelier` doc path the route resolved
+     * to. Populated by `routeIngestWithTarget` for explicit canvas drops so the
+     * server-side handler can pass it straight to the composer / audio-add path
+     * without re-deriving.
+     */
+    docPath?: string;
+}
+/**
+ * Classify a media filename by its extension. Case-insensitive — `.MOV` and
+ * `.mov` both yield `"video"`. Returns `"unsupported"` for anything outside
+ * the known video/image/audio extension lists, including files with no
+ * extension at all.
+ */
+declare function classifyMediaFile(filename: string): IngestKind;
+/**
+ * Route a no-target ingest into the project's media bin.
+ *
+ * Post-pivot (TD-2026-05-28) the no-target path doesn't care about project
+ * kind — supported media always goes to `add-to-bin`, unsupported types are
+ * rejected. Composition is a separate explicit step downstream.
+ *
+ * Mirrors `classifyMediaFile` for the kind detection; the routing decision is
+ * a pure function of the filename.
+ */
+declare function routeIngest(filename: string): BinIngestRoute;
+/**
+ * Routing matrix for explicit "add to this specific doc" drops (canvas-area
+ * drag-drop, post-pivot). When the browser knows which doc is loaded in the
+ * canvas, it sends `targetDocPath` + the target doc's `kind`; the routing
+ * decision is then governed by the TARGET doc's kind — not the project's
+ * inferred kind — because the user picked a specific doc.
+ *
+ *   file kind   target doc kind  →  target
+ *   ─────────────────────────────────────
+ *   video       video            →  compose-video    (docPath = targetDocPath)
+ *   audio       video            →  add-audio-clip   (docPath = targetDocPath)
+ *   image       *                →  reject (v1)
+ *   video       image / carousel →  reject
+ *   audio       image / carousel →  reject
+ *   unsupported *                →  reject
+ *
+ * Pure / synchronous. The caller is responsible for verifying the target doc
+ * exists on disk and reading its kind — this function only encodes the
+ * compatibility matrix and produces the route decision.
+ */
+declare function routeIngestWithTarget(filename: string, targetDocPath: string, targetDocKind: ProjectKind | undefined): IngestRoute;
+
+/**
+ * Project kind that a NEW doc can be created as.
+ *
+ * Owner explicitly excluded "blank" from v1 — only the three named kinds.
+ * Future v1.1 may add `undefined` for blank docs.
+ */
+type DocKind = "video" | "image" | "carousel";
+interface CreateDocOptions {
+    projectDir: string;
+    name: string;
+    kind: DocKind;
+    /** For carousel slides: place file under slides/ and append SlideRef to target carousel. */
+    asCarouselSlide?: boolean;
+    /** Required when asCarouselSlide:true — the carousel doc whose slides[] should receive the ref. Usually <projectDir>/project.atelier. */
+    carouselDocPath?: string;
+    /** Insertion index for SlideRef (default = append). */
+    insertAt?: number;
+}
+interface DuplicateDocOptions {
+    projectDir: string;
+    /** Project-relative path of the doc to duplicate (e.g. "slides/slide-1.atelier" or "scenes/intro.atelier"). */
+    sourceDocPath: string;
+    /** When source is a slide, also append a new SlideRef pointing at the duplicate. */
+    appendSlideRef?: boolean;
+}
+interface DeleteDocOptions {
+    workspaceDir: string;
+    projectName: string;
+    /** Project-relative path of the doc to delete. */
+    docPath: string;
+}
+interface DocListEntry {
+    /** Project-relative path. */
+    path: string;
+    /** When determinable from the doc's `kind` field; undefined if doc kind is absent or unrecognized. */
+    kind?: "video" | "image" | "carousel";
+}
+interface DocDeleteCascadeReport {
+    /** Project-relative path of the doc that was deleted. */
+    docPath: string;
+    /** SlideRefs removed across the workspace. Each entry identifies the carousel project name + the index of the removed ref (PRE-removal index, in case multiple were removed). */
+    slideRefsRemoved: Array<{
+        project: string;
+        slideIndex: number;
+    }>;
+    /** RefVisual layers in any .atelier across the workspace that still point at the deleted doc. These are NOT auto-removed; reported for surfacing as warnings. */
+    refLayersDangling: Array<{
+        project: string;
+        docPath: string;
+        layerId: string;
+    }>;
+}
+interface DocDuplicateReport {
+    /** Source doc path (project-relative). */
+    sourceDocPath: string;
+    /** New doc path (project-relative). */
+    newDocPath: string;
+    /** When appendSlideRef was set and the source is a carousel slide: the index of the appended SlideRef. */
+    appendedSlideIndex?: number;
+}
+/**
+ * Aegis surface — same posture as `isValidMediaBasenameForRename` in rename-media.ts.
+ * Validates a user-typed doc display name.
+ *
+ * Rejects:
+ * - empty / whitespace-only
+ * - leading dot (hidden files)
+ * - any `/`, `\`, or `..` substring
+ * - control bytes (NUL through 0x1f)
+ * - longer than 200 characters
+ *
+ * The slug (kebab-case derivative) is computed elsewhere via `slugifyBasename`;
+ * this validator only checks the raw human input.
+ */
+declare function isValidDocName(name: unknown): name is string;
+
+interface CreateDocResult {
+    doc: AtelierDocument;
+    /** Project-relative. */
+    docPath: string;
+    /** Present when the new doc was appended as a SlideRef into a carousel. */
+    appendedSlideIndex?: number;
+}
+/**
+ * Scaffold a new .atelier doc inside a project.
+ *
+ * - Validates `opts.name` via `isValidDocName` (rejects path separators,
+ *   `..`, control bytes, etc.).
+ * - Slugs the name via `slugifyBasename` for the filesystem path.
+ * - Collision-suffixes with `-1`, `-2`, ... up to 999.
+ * - For `asCarouselSlide: true`, writes under `slides/<slug>.atelier` AND
+ *   calls `composeCarouselProject` so the cycle check + SlideRef append
+ *   run as one indivisible step.
+ */
+declare function createDoc(opts: CreateDocOptions): Promise<CreateDocResult>;
+/**
+ * Duplicate an existing doc next to itself with a `-copy` (then `-copy-2`,
+ * `-copy-3`, ...) suffix. Layer ids are preserved verbatim (they're
+ * doc-local — no cross-doc id collision concern).
+ *
+ * `appendSlideRef: true` requires the source to live under `slides/`; we
+ * also call `composeCarouselProject` for the append so the cycle detector
+ * runs defensively even though duplicating a clean slide can't introduce a
+ * new cycle.
+ */
+declare function duplicateDoc(opts: DuplicateDocOptions): Promise<DocDuplicateReport>;
+/**
+ * Delete a doc inside a project AND scrub any workspace-wide references:
+ *
+ *   1. Walk every project subdir of the workspace. For each project, walk
+ *      its root + `slides/` for *.atelier files (mirroring listDocs' scope).
+ *   2. For each `.atelier` doc found: scan `slides[]` (if kind:carousel) for
+ *      refs that resolve to the absolute path of the doc being deleted;
+ *      splice those refs out, persist the updated doc.
+ *   3. Same walk, but scan `layers[]` for RefVisual layers (`visual.type ==
+ *      "ref"`) whose `src` resolves to the same absolute path. Collect
+ *      these as `refLayersDangling` — do NOT remove them; the renderer
+ *      tolerates missing refs and we want the studio to surface dangling
+ *      refs as warnings rather than silently nuke them.
+ *   4. Unlink the doc.
+ *
+ * Every .atelier is equal — there is no "project manifest" carve-out.
+ */
+declare function deleteDoc(opts: DeleteDocOptions): DocDeleteCascadeReport;
+/**
+ * Enumerate the .atelier docs belonging to a project for the studio sidebar.
+ *
+ * Post-pivot: every .atelier is equal. Returns a flat alphabetical list of
+ * docs in the project's root + `slides/` subdir. The optional `kind` field
+ * is filled in when the doc parses and has a top-level `kind`; otherwise
+ * omitted.
+ *
+ * Scope is intentionally non-recursive (root + slides/ only) — per Arky's
+ * v1 plan, deeper trees are out of scope for the sidebar.
+ *
+ * Hardening: the `.atelier/` directory at project root (paradigm artifact
+ * sibling) matches `*.atelier` by name but is NOT a doc. We filter by
+ * `statSync().isFile()` AND skip basename `.atelier` defensively.
+ */
+declare function listDocs(projectDir: string): DocListEntry[];
+
+export { ARTIFACT_FILENAMES, type ArtifactParseError, type AssetInfo, type BinIngestRoute, type BuildCaptionsOptions, CanvasUnavailableError, type CaptionStyle, type ComposeCarouselProjectOptions, type ComposeCarouselProjectResult, type ComposeImageProjectOptions, type ComposeImageProjectResult, type ComposeVideoProjectOptions, type ComposeVideoProjectResult, type CreateDocOptions, type CreateDocResult, type DeleteDocOptions, type DocDeleteCascadeReport, type DocDuplicateReport, type DocKind, type DocListEntry, type DocumentInfo, type DuplicateDocOptions, type IngestKind, type IngestRoute, type InitResult, LEARNING_MODES, LEARNING_MODE_VERSION, type LearningMode, type LearningModeFile, type LoadedArtifactProject, type LoadedRecipe, type ProgressInfo, RECIPE_VERSION, type RenderFormat, type RenderOptions, type RenderResult, type RunInitOptions, type TranscribeOptions, type TranscribeResult, type TrimOptions, type TrimResult, VIDEO_CUTLIST_VERSION, VIDEO_PROJECT_VERSION, VIDEO_TRANSCRIPT_VERSION, type VariableInfo, type VideoProject, type WhisperBackend, type WhisperModel, type WhisperOptions, applyAdd, applyBatchReplace, applyHide, applyMerge, applyRecipeCommand, applyRecipeToCaptionOptions, applyRecipeToTranscribeOptions, applyRecipeToTrimOptions, applySplit, applyTextEdit, artifactsCommand, assetsCommand, buildCaptionLayers, buildFfmpegArgs, captionsCommand, carouselCommand, carouselFileName, checkFfmpeg, classifyMediaFile, composeCarouselFrameDoc, composeCarouselProject, composeImageProject, composeVideoProject, createDoc, createVideoProject, deleteDoc, duplicateDoc, effectiveSpan, expandInputs, exportImageCommand, exportLottieCommand, exportSvgCommand, fitImageToCanvas, flattenWords, getAssets, getInfo, getVariables, groupIntoPhrases, infoCommand, initCommand, isInsideGitRepo, isValidDocName, learningModePath, listDocs, loadArtifactsFromProject, loadCanvasModule, loadRecipe, loadVideoProject, mergeTranscriptWithExisting, parseModeAnswer, parseWhisperCppJson, probeWhisper, readComposition, readCutList, readLearningMode, readTranscript, recipeCommand, recipeToYaml, renderCommand, renderDocument, renderDocumentToPng, renderLearningModeYaml, renderRecipeWithDefaults, resolveExportDimensions, resolveRecipePath, resolveStill, rewriteCaptionLayers, rewriteCutLayers, routeIngest, routeIngestWithTarget, runInit, runWhisperCpp, scaffoldRecipeYaml, stillCommand, transcribeCommand, transcribeProject, transcriptCommand, trimCommand, trimProject, validateCommand, validateFile, variablesCommand, writeComposition, writeCutList, writeLearningMode, writeTranscript };