frameyard 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to Frameyard are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Frameyard uses `0.x` versions until the composition, configuration, CLI,
+JSON-result, transcript, and skill contracts stabilize. Before `1.0.0`, a
+contract change may ship in a minor release and is called out explicitly below.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-28
+
+### Added
+
+- Native JavaScript composition contract with fixed `width`, `height`, `fps`,
+  and `durationInFrames`, JSON props, and synchronous seek-safe `update()`.
+- Browser runtime with deterministic frame time, keyed `random()`, CSS and Web
+  Animations seeking, and preview diagnostics for non-deterministic clocks,
+  randomness, and CSS transitions.
+- Interactive preview with composition selection, prop editing, frame
+  scrubbing, playback, and audio synchronization.
+- CLI commands: `init`, `dev`, `check`, `still`, `render`, `tts`, `transcribe`,
+  and `doctor`, with `--json` result envelopes and stable error codes.
+- Deterministic Chromium capture through Playwright and FFmpeg H.264/AAC
+  encoding, with atomic output publication and explicit overwrite flags.
+- Audio clips placed on composition frames with source trimming in seconds and
+  an offline FFmpeg mix.
+- Canonical transcript validation, measured word timings, and SRT/VTT
+  formatting, including transcript requirements attached to compositions.
+- Local `qwen-tts` speech synthesis and `whisper-cli` transcription wrappers
+  with executable resolution, atomic publishing, and a versioned provenance
+  manifest.
+- `frameyard doctor` environment, integration, and manifest inspection without
+  downloading, repairing, or modifying anything.
+- Host-neutral agent skill under `skill/`, versioned with the npm package API.
+- 30-second reference composition, deterministic render benchmark, public-seam
+  test suite, design baseline, and architecture decision records.
+
+[Unreleased]: https://github.com/vladiantio/frameyard/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/vladiantio/frameyard/releases/tag/v0.1.0

package/GLOSSARY.md

@@ -0,0 +1,145 @@
+# Frameyard
+
+Frameyard is a local-first framework for creating short, parameterized videos with HTML, CSS, and JavaScript. Its domain separates reusable compositions from the fixed inputs and deterministic renders that turn them into videos.
+
+## Language
+
+### Authoring
+
+**Project**:
+A collection of related compositions and the assets and configuration they share.
+_Avoid_: Video, render
+
+**Composition**:
+A uniquely identified, reusable video definition with fixed dimensions, frame rate, duration in frames, and content parameterized by props.
+_Avoid_: Scene, template, video
+
+**Composition metadata**:
+The fixed dimensions, frame rate, and duration in frames that define a composition's output contract.
+_Avoid_: Render options, props
+
+**Composition lifecycle**:
+The `mount → update → dispose` sequence that governs a composition's frame production.
+_Avoid_: Render loop, playback lifecycle
+
+**Composition revision**:
+A specific version of a composition's source and metadata.
+_Avoid_: Build, release
+
+**Props**:
+The immutable, JSON-serializable inputs supplied to a composition for one render.
+_Avoid_: Options, settings, mutable state
+
+**Asset**:
+A local file required by a composition, whether static or generated.
+_Avoid_: Resource, media file
+
+### Deterministic execution
+
+**Frame**:
+An integer-addressed position on a composition's timeline.
+_Avoid_: Timestamp, animation tick
+
+**Deterministic execution**:
+The rule that a composition's visual state at any frame depends only on that frame, its props, and pre-loaded data and assets.
+_Avoid_: Playback-driven animation
+
+**Frame clock**:
+The single source of animation time, derived from the current frame and the composition's frame rate.
+_Avoid_: Wall clock, playback timer
+
+**Seek safety**:
+The property that any frame can be produced correctly without depending on previously produced frames.
+_Avoid_: History-dependent updates
+
+**Deterministic randomness**:
+Random values derived statelessly from a key so they do not depend on call order or rendering history.
+_Avoid_: Unseeded randomness
+
+**Frame production**:
+The phase in which the runtime produces the visual state of a requested frame, without network access or model inference.
+_Avoid_: Real-time playback
+
+**Loading phase**:
+The phase before frame production when required data and assets become available.
+_Avoid_: Per-frame fetching
+
+### Audio
+
+**Audio clip**:
+An audio source placed on a composition's timeline with a start frame, source trim, and volume.
+_Avoid_: Audio track
+
+**Audio mix**:
+The single offline mix of a composition's audio clips for one render.
+_Avoid_: Soundtrack, audio track, final cut
+
+### Rendering
+
+**Preview**:
+An interactive, frame-accurate inspection of a composition using the same composition behavior as a render.
+_Avoid_: Visual editor
+
+**Check**:
+A validation operation that checks configuration, props, assets, audio, and transcript requirements, then mounts a composition and evaluates every frame without capturing or encoding.
+_Avoid_: Test render, dry run
+
+**Render**:
+The production of one complete video from a composition and a fixed set of props.
+_Avoid_: Recording, export
+
+**Video**:
+The finished audiovisual output of a successful render.
+_Avoid_: Composition, project
+
+**Still**:
+A single frame captured as a PNG through the production rendering path for debugging.
+_Avoid_: Frame export, image sequence
+
+**Reproducibility**:
+The guarantee that, for the same composition revision, props, assets, and frame under a pinned runtime/browser environment, the visual state is identical. It does not imply identical encoded bytes, even on the same machine; encoded output depends on the encoder and its runtime.
+_Avoid_: Bit-for-bit encoding equality
+
+### Agent operation
+
+**Agent-assisted authoring and operation**:
+The creation and operation of a Frameyard project by an AI agent acting on a user's behalf.
+_Avoid_: Built-in generative AI
+
+**Agent skill**:
+An API-version-matched set of instructions and resources through which an AI agent uses Frameyard's public authoring and operation contracts.
+_Avoid_: Agent runtime, MCP server
+
+### Local asset production
+
+**Generated asset**:
+A frozen local input produced by speech synthesis or transcription before a composition is loaded or rendered.
+_Avoid_: Per-frame generation
+
+**Provenance manifest**:
+A versioned, project-local record of generated assets, their content hashes, and the inputs and processes that produced them.
+_Avoid_: Render cache
+
+**Speech synthesis** (TTS):
+The local production of a spoken audio asset from text using a named speaker.
+_Avoid_: Voice generation, voice cloning, voice design
+
+**Transcription**:
+The local production of timed text from source audio or video.
+_Avoid_: Subtitle rendering
+
+**Transcript**:
+The canonical, versioned artifact containing full text, source identity, and source-relative timed segments, with optional word timings.
+_Avoid_: Subtitle file, raw generator output
+
+**Transcript segment**:
+A timed span of transcript text with source-relative start and end times.
+_Avoid_: Subtitle cue, line
+
+**Word timing**:
+The measured, source-relative start and end of a word in source audio.
+_Avoid_: Interpolated segment timing
+
+**Karaoke subtitle**:
+A subtitle presentation pattern that highlights words according to actual word timings.
+_Avoid_: Segment-timed highlighting

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frameyard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,303 @@
-# Temporary Holding Version
+# Frameyard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Frameyard is a local-first framework for building short, parameterized videos with HTML, CSS, and JavaScript and rendering them deterministically.
+
+The v0.1 design is implemented: composition contracts, browser runtime and preview, `init`, `dev`, `check`, `still`, `render`, `tts`, `transcribe`, `doctor`, deterministic Chromium capture, FFmpeg output, provenance manifests, transcript validation, and the official agent skill.
+
+## Requirements
+
+- Node.js 22.12 or newer
+- FFmpeg and FFprobe on `PATH`, built with H.264 (`libx264`) and AAC support
+- The Playwright-managed Chromium build
+- Optional: `qwen-tts` from [`qwentts.cpp`](https://github.com/ServeurpersoCom/qwentts.cpp) for local speech synthesis
+- Optional: `whisper-cli` from [`whisper.cpp`](https://github.com/ggml-org/whisper.cpp) for local transcription
+
+```sh
+pnpm install
+pnpm exec playwright install chromium
+pnpm build
+```
+
+Run `node dist/cli.js doctor` to inspect the environment without repairing or downloading anything. The wrappers target the CLI surfaces of qwentts.cpp commit `5916bf7c79dbb4e66fc059cdc507a79a23a28bb4` and whisper.cpp commit `284029c07012d2000941a08d38a31ffb71f4734e`.
+
+CI uses fake `qwen-tts` and `whisper-cli` executables. Real-model tests are opt-in:
+
+```sh
+FRAMEYARD_REAL_INTEGRATIONS=1 \
+FRAMEYARD_REAL_TALKER=/path/to/talker.gguf \
+FRAMEYARD_REAL_CODEC=/path/to/codec.gguf \
+FRAMEYARD_REAL_WHISPER_MODEL=/path/to/ggml-model.bin \
+FRAMEYARD_REAL_WHISPER_SOURCE=/path/to/source.wav \
+# optional, for GPUs with too little VRAM:
+FRAMEYARD_REAL_TTS_DEVICE=CPU \
+pnpm vitest run test/real-integrations.test.ts
+```
+
+## Quick start
+
+Scaffold a project:
+
+```sh
+node dist/cli.js init my-video
+cd my-video
+node ../dist/cli.js dev
+```
+
+`dev` prints a local preview URL. Select a composition, edit its JSON props, scrub frames, and play the composition with its audio timeline.
+
+Validate and render:
+
+```sh
+node ../dist/cli.js doctor
+node ../dist/cli.js check hello
+node ../dist/cli.js render hello --props props/hello.json --out hello.mp4
+node ../dist/cli.js still hello --frame 42 --out hello-frame.png
+```
+
+The 30-second reference composition lives in [`examples/demo`](./examples/demo):
+
+```sh
+node dist/cli.js check demo --project examples/demo
+node dist/cli.js render demo --project examples/demo --props examples/demo/props/demo.json --out demo.mp4
+```
+
+## Project format
+
+A project is ordinary HTML, CSS, assets, and native JavaScript ES modules. `video.config.js` explicitly lists composition entry points; there is no directory scanning:
+
+```js
+export default {
+  compositions: {
+    hello: "./compositions/hello.js",
+  },
+};
+```
+
+A composition default-exports a definition. `defineComposition` is optional but gives early metadata validation and editor types:
+
+```js
+import { defineComposition } from "frameyard";
+import { random } from "frameyard/runtime";
+
+let title;
+
+export default defineComposition({
+  width: 1920,
+  height: 1080,
+  fps: 30,
+  durationInFrames: 900,
+  defaultProps: { title: "Hello" },
+  validateProps(props) {
+    return typeof props.title === "string" ? [] : ["title must be a string"];
+  },
+  audio: [{ src: "assets/hit.wav", startFrame: 15, volume: 0.8 }],
+
+  mount({ container }) {
+    container.innerHTML = "<h1 id='title'></h1>";
+    title = container.querySelector("#title");
+  },
+
+  update({ frame, props }) {
+    title.textContent = props.title;
+    title.style.transform = `translateX(${random("title:" + frame) * 40}px)`;
+  },
+
+  dispose() {
+    title = undefined;
+  },
+});
+```
+
+The runtime supplies an import map for `frameyard` and `frameyard/runtime`, so project code needs no bundling step and no `node_modules` import.
+
+### Composition lifecycle
+
+- `mount({ container, props })` creates the visual structure once and may finish asynchronous work.
+- `update({ frame, props })` makes that structure represent the frame. It must be synchronous and seek-safe.
+- `dispose()` releases resources after the last frame.
+
+The only animation inputs are the integer frame and immutable props. Metadata (`width`, `height`, `fps`, `durationInFrames`) is fixed and validated before mounting. Props are JSON-serializable, deep-frozen, and merged shallowly over `defaultProps`.
+
+Use `random("stable:key")` instead of `Math.random()`. The runtime pauses CSS animations and the Web Animations API inside the composition container and seeks them to the current frame. Independent `requestAnimationFrame` loops, timers, transitions, and wall-clock reads are not deterministic animation drivers.
+
+## Audio timeline
+
+Audio clips are declarative:
+
+```js
+audio: [
+  {
+    src: "assets/voice.wav", // project-relative local file
+    startFrame: 30,          // composition timeline position
+    trimStart: 0.25,         // seconds trimmed from the source
+    trimDuration: 4.2,       // optional seconds to use
+    volume: 0.8,             // 0..1
+  },
+];
+```
+
+Preview synchronizes the timeline in the browser. Production mixes the same clips offline with FFmpeg. `check` reports clip durations and warnings when a clip extends beyond the composition. Frameyard never time-stretches audio or changes composition duration to fit it.
+
+## Transcripts
+
+A composition can declare canonical transcript assets that `check`, `still`, and `render` must validate:
+
+```js
+transcripts: [
+  { src: "assets/voice.transcript.json", words: true },
+],
+```
+
+Transcript paths are project-relative. `words: true` requires actual measured word timings for karaoke-style presentation; Frameyard fails with `TRANSCRIPT_WORDS_UNAVAILABLE` rather than interpolating them. See [subtitles and karaoke](./skill/references/subtitles-karaoke.md) for the canonical JSON shape and the seek-safe frame conversion recipe.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `frameyard init [directory]` | Scaffold a minimal project |
+| `frameyard dev [--port <port>]` | Start the preview server |
+| `frameyard check <id> [--props <file>]` | Validate props, assets, audio, transcripts, and every frame without capture |
+| `frameyard still <id> --frame <n>` | Capture one PNG through the production path |
+| `frameyard render <id> --out <video.mp4>` | Capture frames with Chromium and encode with FFmpeg |
+| `frameyard tts ...` | Produce one frozen 24 kHz mono WAV with local qwentts.cpp |
+| `frameyard transcribe ...` | Produce canonical transcript JSON with optional word timings and SRT/VTT exports |
+| `frameyard doctor` | Inspect core requirements, optional integrations, and manifest integrity |
+
+Common options: `--project <dir>`, `--json`, `--help`, and `--version`. `still` and `render` accept `--overwrite`; `tts` and `transcribe` accept `--force`. `init` takes the target directory as a positional argument. Output paths are relative to the current working directory.
+
+A render fails immediately on an uncaught error, unhandled rejection, missing required asset, or invalid composition output. It writes to a temporary file and publishes only after FFmpeg succeeds. Existing outputs are not replaced unless `--overwrite` is supplied.
+
+### JSON results
+
+Non-interactive commands support `--json`. Results go to stdout and human progress/diagnostics go to stderr:
+
+```json
+{
+  "ok": true,
+  "command": "render",
+  "composition": "hello",
+  "path": "/absolute/path/hello.mp4",
+  "width": 1920,
+  "height": 1080,
+  "fps": 30,
+  "durationInFrames": 900,
+  "framesRendered": 900,
+  "audio": { "clips": 1, "warnings": [] },
+  "transcripts": { "clips": 1, "warnings": [] }
+}
+```
+
+Errors use the same envelope:
+
+```json
+{
+  "ok": false,
+  "command": "render",
+  "error": { "code": "OUTPUT_EXISTS", "message": "Output already exists: ..." }
+}
+```
+
+`doctor --json` reports findings rather than throwing for environment problems: `ok: true` means inspection completed, while `healthy` reports whether required checks, manifest integrity, explicitly supplied models, and integration compatibility passed. See the [JSON result reference](./skill/references/json-results.md) for all command shapes.
+
+## Local asset production
+
+`tts` and `transcribe` wrap optional local executables. Frameyard never builds upstream tools, downloads models, or runs inference during composition loading or frame production.
+
+```sh
+# One frozen 24 kHz mono WAV. Text comes from --text-file or stdin.
+node dist/cli.js tts \
+  --speaker vivian \
+  --talker-model models/qwen-talker-1.7b-customvoice-Q8_0.gguf \
+  --codec-model models/qwen-tokenizer-12hz-Q8_0.gguf \
+  --language English \
+  --text-file script.txt \
+  --out assets/voice.wav
+
+# Canonical transcript with measured word timings and derived SRT/VTT.
+node dist/cli.js transcribe assets/voice.wav \
+  --model models/ggml-base.en.bin \
+  --out assets/voice.transcript.json \
+  --words --export srt,vtt
+```
+
+- Executable resolution: `--executable`, then `FRAMEYARD_QWEN_TTS` or `FRAMEYARD_WHISPER_CLI`, then `PATH`.
+- `tts` supports CustomVoice only: a named speaker is required. Reference-audio cloning and VoiceDesign are deferred.
+- `--device CPU` forces qwentts.cpp onto the CPU when a GPU does not have enough VRAM.
+- `transcribe` normalizes the source with FFmpeg to 16 kHz mono PCM WAV before `whisper-cli`.
+- Outputs are atomic. Existing assets are replaced only with `--force`.
+- A partial operation leaves no apparently valid artifact and no manifest entry.
+- Transcription never fabricates word timings and never executes Whisper's generated karaoke script.
+
+### Provenance
+
+Successful operations update `frameyard.assets.json` in the project root, or the file passed to `--manifest`. The versioned manifest records artifact SHA-256 hashes and sizes, generator command and executable, Frameyard version, integration revision, model identities, operation parameters, and (for transcription) source identity and derived exports. Commit this manifest with the project.
+
+## Doctor
+
+```sh
+node dist/cli.js doctor
+node dist/cli.js doctor --json
+node dist/cli.js doctor --talker-model models/talker.gguf --codec-model models/codec.gguf
+```
+
+`doctor` checks Node, FFmpeg and required encoders, FFprobe, Playwright Chromium, manifest integrity (artifact, source, model, and derived-export hashes), explicitly supplied model readability, and optional `qwen-tts`/`whisper-cli` capabilities. It does not repair, download, or modify anything. Missing optional integrations do not fail, but a found executable with incompatible capabilities does.
+
+## Agent skill
+
+The optional host-neutral agent skill lives in [`skill/`](./skill). It uses the same project format and CLI as humans, documents deterministic authoring, audio assets, subtitle/karaoke recipes, JSON results, and failure recovery, and ships a thin CLI wrapper. The npm package includes the skill files matching its API version. See [`skill/README.md`](./skill/README.md) for host-specific installation or referencing.
+
+## Rendering and reproducibility
+
+Production rendering:
+
+1. Starts the same preview server and browser runtime used by `dev`.
+2. Launches pinned Chromium through Playwright.
+3. Seeks explicitly to each frame and waits for composition updates.
+4. Captures the viewport through the Chrome DevTools Protocol.
+5. Pipes PNG frames and the offline audio mix to FFmpeg.
+6. Encodes H.264 video with `yuv420p` and AAC audio into an MP4.
+
+Rendering is sequential in v0.1. For the same composition revision, props, assets, frame, and pinned runtime/browser environment, the visual state is identical. Encoded bytes are not a reproducibility guarantee, even on the same machine; they depend on the FFmpeg build, encoder threading, and runtime environment.
+
+For a repeatable local measurement of seek, capture, encode, and full-render time, run `pnpm bench`. The demo and the controlled fixtures under `bench/fixtures/` are the reference workloads.
+
+## Current limits
+
+Deferred from this implementation slice:
+
+- Built-in subtitle rendering, automatic caption burn-in, and karaoke rendering
+- `qwentts.cpp` reference-audio voice cloning and VoiceDesign
+- Automatic long-text chunking, streaming synthesis, and alternative generated-audio formats
+- Automatic upstream builds, model downloads, environment repair, and hosted rendering
+- Parallel rendering, frame caches, and general image-sequence output
+- React or other UI-framework adapters, plugin APIs, and agent-only runtimes
+- TypeScript transpilation for project compositions and npm dependency optimization
+
+See the [v0.1 design baseline](./docs/v0.1-design.md) for the full product contract and the [domain glossary](./GLOSSARY.md) for terminology.
+
+## Repository layout
+
+- `src/contracts.ts`: shared composition, props, audio, and transcript requirement contracts
+- `src/transcript.ts`: canonical transcript validation and SRT/VTT formatting
+- `src/runtime/`: browser lifecycle, frame clock, deterministic randomness
+- `src/preview/`: interactive preview client
+- `src/server/`: native ES-module server and import map
+- `src/renderer/`: Chromium capture, audio mixing, transcript inspection, FFmpeg encoding
+- `src/assets/`: local TTS/transcription wrappers, executable resolution, atomic publishing, provenance
+- `src/doctor.ts`: environment, integration, and manifest inspection
+- `src/cli.ts`: command-line entry point
+- `skill/`: official host-neutral agent skill
+- `examples/demo/`: the 30-second reference composition
+- `bench/fixtures/`: controlled compositions for the render benchmark
+- `scripts/`: benchmark, versioning, and git-hook installation
+- `docs/adr/`: architecture decision records
+
+## Development
+
+`pnpm install` installs the repository's git hooks. Pre-commit runs typecheck, test typecheck, and unit tests; pre-push runs the full suite. CI runs the same checks on Linux with Node 22 and 24, using fake model executables.
+
+Releases are tag-driven. See [`RELEASING.md`](./RELEASING.md) for version policy, npm trusted publishing, and the release checklist, and [`CHANGELOG.md`](./CHANGELOG.md) for release notes.
+
+## License
+
+MIT

package/dist/assets/executable.d.ts

@@ -0,0 +1,16 @@
+export interface ResolvedExecutable {
+    /** The default command name, such as "qwen-tts". */
+    command: string;
+    /** Absolute path to the executable that will be used. */
+    path: string;
+    source: "option" | "environment" | "path";
+}
+/** Resolves an integration executable: explicit option, environment, then PATH. */
+export declare function resolveExecutable(options: {
+    command: string;
+    explicit?: string;
+    envVar: string;
+    cwd?: string;
+    installHint: string;
+}): Promise<ResolvedExecutable>;
+//# sourceMappingURL=executable.d.ts.map

package/dist/assets/executable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executable.d.ts","sourceRoot":"","sources":["../../src/assets/executable.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC3C;AAwCD,mFAAmF;AACnF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2B9B"}

package/dist/assets/executable.js

@@ -0,0 +1,59 @@
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import path from "node:path";
+import { FrameyardError } from "../errors.js";
+async function isExecutable(filePath) {
+    try {
+        const info = await stat(filePath);
+        if (!info.isFile()) {
+            return false;
+        }
+        await access(filePath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function pathCandidates(command) {
+    if (process.platform !== "win32") {
+        return [command];
+    }
+    const extensions = (process.env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
+    return path.extname(command) ? [command] : extensions.map((extension) => `${command}${extension}`);
+}
+async function findOnPath(command, cwd) {
+    const entries = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    for (const entry of entries) {
+        for (const candidate of pathCandidates(command)) {
+            const absolute = path.resolve(cwd, entry, candidate);
+            if (await isExecutable(absolute)) {
+                return absolute;
+            }
+        }
+    }
+    return undefined;
+}
+/** Resolves an integration executable: explicit option, environment, then PATH. */
+export async function resolveExecutable(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const configured = options.explicit ?? process.env[options.envVar];
+    const source = options.explicit !== undefined ? "option" : process.env[options.envVar] !== undefined ? "environment" : "path";
+    if (configured !== undefined) {
+        const absolute = hasPathSeparator(configured) ? path.resolve(cwd, configured) : await findOnPath(configured, cwd);
+        if (absolute && (await isExecutable(absolute))) {
+            return { command: options.command, path: absolute, source };
+        }
+        const sourceLabel = source === "environment" ? ` in ${options.envVar}` : "";
+        throw new FrameyardError("EXECUTABLE_NOT_FOUND", `Could not find an executable at "${configured}"${sourceLabel}. ${options.installHint}`);
+    }
+    const fromPath = await findOnPath(options.command, cwd);
+    if (fromPath) {
+        return { command: options.command, path: fromPath, source: "path" };
+    }
+    throw new FrameyardError("EXECUTABLE_NOT_FOUND", `${options.command} was not found on PATH. ${options.installHint} You can also pass --executable or set ${options.envVar}.`);
+}
+//# sourceMappingURL=executable.js.map

package/dist/assets/executable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executable.js","sourceRoot":"","sources":["../../src/assets/executable.ts"],"names":[],"mappings":"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"}

package/dist/assets/files.d.ts

@@ -0,0 +1,4 @@
+/** Fails early with an actionable error when an input file is missing or unreadable. */
+export declare function assertReadableFile(filePath: string, label: string): Promise<number>;
+export declare function requireExtension(filePath: string, extension: string, label: string): void;
+//# sourceMappingURL=files.d.ts.map

package/dist/assets/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/assets/files.ts"],"names":[],"mappings":"AAKA,wFAAwF;AACxF,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBzF;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIzF"}

package/dist/assets/files.js

@@ -0,0 +1,30 @@
+import { access, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { FrameyardError } from "../errors.js";
+/** Fails early with an actionable error when an input file is missing or unreadable. */
+export async function assertReadableFile(filePath, label) {
+    let info;
+    try {
+        info = await stat(filePath);
+    }
+    catch {
+        throw new FrameyardError("ASSET_NOT_FOUND", `${label} does not exist: ${filePath}`);
+    }
+    if (!info.isFile()) {
+        throw new FrameyardError("ASSET_NOT_FOUND", `${label} is not a file: ${filePath}`);
+    }
+    try {
+        await access(filePath, constants.R_OK);
+    }
+    catch {
+        throw new FrameyardError("ASSET_NOT_FOUND", `${label} is not readable: ${filePath}`);
+    }
+    return info.size;
+}
+export function requireExtension(filePath, extension, label) {
+    if (path.extname(filePath).toLowerCase() !== extension) {
+        throw new FrameyardError("USAGE", `${label} must use a ${extension} extension: ${filePath}`);
+    }
+}
+//# sourceMappingURL=files.js.map

package/dist/assets/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/assets/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAgB,EAAE,KAAa;IACtE,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,cAAc,CAAC,iBAAiB,EAAE,GAAG,KAAK,oBAAoB,QAAQ,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;QACnB,MAAM,IAAI,cAAc,CAAC,iBAAiB,EAAE,GAAG,KAAK,mBAAmB,QAAQ,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,cAAc,CAAC,iBAAiB,EAAE,GAAG,KAAK,qBAAqB,QAAQ,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,SAAiB,EAAE,KAAa;IACjF,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,KAAK,SAAS,EAAE,CAAC;QACvD,MAAM,IAAI,cAAc,CAAC,OAAO,EAAE,GAAG,KAAK,eAAe,SAAS,eAAe,QAAQ,EAAE,CAAC,CAAC;IAC/F,CAAC;AACH,CAAC"}

package/dist/assets/integrations.d.ts

@@ -0,0 +1,15 @@
+export declare const QWEN_TTS_ENV = "FRAMEYARD_QWEN_TTS";
+export declare const WHISPER_CLI_ENV = "FRAMEYARD_WHISPER_CLI";
+/**
+ * The qwentts.cpp and whisper.cpp revisions whose CLI surfaces this wrapper
+ * targets. Real-model integration tests are opt-in and must name the exact
+ * revision they exercise; doctor reports these values so generated provenance
+ * is interpretable.
+ */
+export declare const QWEN_TTS_REFERENCE_REVISION = "5916bf7c79dbb4e66fc059cdc507a79a23a28bb4";
+export declare const WHISPER_CPP_REFERENCE_REVISION = "284029c07012d2000941a08d38a31ffb71f4734e";
+export declare const QWEN_TTS_COMMAND = "qwen-tts";
+export declare const WHISPER_CLI_COMMAND = "whisper-cli";
+export declare const QWEN_TTS_INSTALL_HINT = "Build qwentts.cpp and make its qwen-tts executable available on PATH.";
+export declare const WHISPER_CLI_INSTALL_HINT = "Build whisper.cpp and make its whisper-cli executable available on PATH.";
+//# sourceMappingURL=integrations.d.ts.map