Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
fix: cut shots on boundaries precise enough to describe
rpone09b91f9f4cf3
diff --git a/.agents/skills/hypit/references/credentials.md b/.agents/skills/hypit/references/credentials.mdindex 6696b093..4e5a20a9 100644--- a/.agents/skills/hypit/references/credentials.md+++ b/.agents/skills/hypit/references/credentials.md@@ -45,6 +45,30 @@ values with, for example,`node .agents/skills/hypit/scripts/check-credentials.mjs KIE_API_KEY MIMO_API_KEY`, then run`hypit doctor <profile>`.+## A changed credential does not reach a running Worker++The durable Worker keeps the environment it started with. Correct a key in `.env` or the shell while+one is running and the next Build still authenticates with the old value, which the Provider reports+as an ordinary `401 Invalid API Key` — pointing at the key you just fixed, or at the Provider, and+never at the stale process. Restart it:++```bash+hypit runtime down+```++The next Build starts a fresh Worker with the current environment. Do this before concluding that a+key is wrong; and when a `401` survives the restart, settle it against the API directly, once, rather+than by editing the key again:++```bash+curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $MIMO_API_KEY" \+ https://api.xiaomimimo.com/v1/models+```++`hypit runtime down` stops the Worker for the whole project, so a Build running in another terminal+stops with it. The Build itself is durable and survives; resume it with+`hypit status <build-id> --watch`.+An Endpoint whose Runtime Profile points at the read-only `env` CredentialStore must be configuredby setting its exact environment variable. `hypit auth login` deliberately refuses to prompt inthat case. For an interactive workstation, select the writable macOS Keychain CredentialStore indiff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.mdindex f6456d7c..0658f694 100644--- a/.agents/skills/hypit/references/local-author-package.md+++ b/.agents/skills/hypit/references/local-author-package.md@@ -4,29 +4,15 @@ Use this workflow only after proving that no legal composition of installed packrequired behavior. A similar-looking tag is insufficient when its declared Types, timing or outputbehavior differs. Never write an unknown tag before its package exists.-## Start from the scaffold+## Write `package.json` and the activation first-Do not write the package from nothing. One command generates it:--```bash-hypit new-package @hypit/local-<slug> --to <project>/packages/local-<slug>-```--It writes `package.json`, the Manifest with a complete vocabulary skeleton, Types, Surface,-Producers, activation, index, README, `assets/`, `preview/`, and — for a component that draws — a-still-render entry that produces the preview image its Surface owes. The result compiles and is-importable with no edits, so run `pnpm install` and `pnpm check` once and start from something that-already works.--Writing those files by hand costs roughly four hundred lines of boilerplate identical in every-package, and puts the `package.json` last, which means discovering only at the end that nothing is-linked. Add `--no-visual` when the component draws nothing.+Write those two before any implementation, run `pnpm install` once, and only then start on the+vocabulary. They are short and almost the same in every package, and leaving them until the end means+discovering at the end that nothing is linked — a failure that looks like broken code and is not.+Everything after them is specific to this component and cannot be copied from anywhere.## Required reading-Read these before editing what the scaffold produced. Reading them after generating means reading-about files that exist.-1. `docs/guide/component-anatomy.md` — the roles every component package fills, and how to find eachone in an existing package. Read this first; it is what the rest is measured against.2. `docs/guide/author-packages.md`@@ -44,8 +30,8 @@ worse outcome than understanding its structure — which is what anatomy is for.## Package boundary-The scaffold places the package at `<project>/packages/local-<slug>/` named `@hypit/local-<slug>`,-with physical version `0.0.0-dev` and logical Module version `1`. Only create a new package: do not+Place the package at `<project>/packages/local-<slug>/`, named `@hypit/local-<slug>`, with physical+version `0.0.0-dev` and logical Module version `1`. Only create a new package: do notedit, extend, delete or overwrite an existing Hypit package to fill the gap.The package is project-local even when the project is the Hypit checkout. Do not move it into andiff --git a/.agents/skills/hypit/references/reference-video/final-sources.md b/.agents/skills/hypit/references/reference-video/final-sources.mdindex e81038b7..fd705b26 100644--- a/.agents/skills/hypit/references/reference-video/final-sources.md+++ b/.agents/skills/hypit/references/reference-video/final-sources.md@@ -10,6 +10,18 @@ systems this reference actually contains, and write one complete project:properties and admitted values.- `build.svrun` references the Author Source and declares the required Targets with resolvabledependencies.+- `hypit.runtime.json` binds an Endpoint to every capability those sources demand.++The Runtime Profile is part of the deliverable even though this route runs nothing. Without it the+first thing the author meets is `RUNTIME_CAPABILITY_UNBOUND`, and the work of discovering which+Provider serves each model falls on them — work you have already done, since you chose every package+in the Source. Copy the nearest existing `examples/*/hypit.runtime.json` and bind one Endpoint per+capability your Sources actually reach: the picture and video models, speech, alignment, the media+Provider and the local renderer. Read each Provider's README for the shape of its `config`, and+reference credentials through the store rather than writing any secret into the file.++A capability whose credential this machine does not hold is still declared. Preflight names it before+any Build is submitted, which is the correct place for the author to find out.Do not author one source fragment per shot. Do not let check success substitute for unresolvedsemantic evidence; return to a narrow `observe_reference` question when necessary.diff --git a/.agents/skills/hypit/references/reference-video/index.md b/.agents/skills/hypit/references/reference-video/index.mdindex 34a3c398..5e53bf37 100644--- a/.agents/skills/hypit/references/reference-video/index.md+++ b/.agents/skills/hypit/references/reference-video/index.md@@ -6,7 +6,8 @@ visual and audio evidence only.## What this route delivers, and what it does not-The deliverable is **the components the video needs and the three source files**. Every generation the+The deliverable is **the components the video needs, the three source files, and the Runtime Profile+that binds what they demand**. Every generation theSource declares is declared, not performed: no Build is submitted for the pictures, and no videogeneration, speech synthesis, alignment or final render is run. Those belong to a later step that theauthor starts deliberately, after reading what was written.@@ -32,7 +33,21 @@ set -a && source .env && set +a`../credentials.md` lists which variables each Provider needs.-Before acting, read these files completely in order:+## Start the evidence before you read++`prepare_reference` and the full `observe_reference` sweep take several minutes and need none of the+knowledge below: their prompts are fixed, and nothing you are about to read changes what they ask.+Start them first and read while they run. Reading first and observing afterwards makes the same run+several minutes longer for nothing.++```bash+hypit-reference-video-tools prepare_reference --video-path <path> # about a minute+hypit-reference-video-tools observe_reference --reference-id <id> # run in the background+```++Then read the files below while the sweep is working, and collect its result when you are done.++Before acting on the evidence, read these files completely in order:1. `workflow.md` — CLI sequence, evidence flow and responsibility boundaries.2. `continuity.md` — mandatory shot, overlay, B-roll, speaker, product and persistent-system rules.diff --git a/.agents/skills/hypit/references/reference-video/reconstruction-loop.md b/.agents/skills/hypit/references/reference-video/reconstruction-loop.mdindex e45a4e97..a1c3d347 100644--- a/.agents/skills/hypit/references/reference-video/reconstruction-loop.md+++ b/.agents/skills/hypit/references/reference-video/reconstruction-loop.md@@ -6,9 +6,13 @@ something the reference never contained. Close that gap deliberately.## The reference side is finished-The reference video does not change. Its observations are cached and authoritative. Re-observing at a-fixed temperature of `1.0` buys paraphrase drift and another bill, so never re-run a completed-observation to "check" it. `--reobserve` exists for a shot whose media was rebuilt, not for doubt.+The reference video does not change, and its observations are cached. Re-observing at a fixed+temperature of `1.0` buys paraphrase drift and another bill, so never re-run a completed observation+to "check" it. `--reobserve` exists for a shot whose media was rebuilt, not for doubt.++Cached does not mean correct. The authority on the reference side is the frame, not the prose written+about it — `workflow.md` says when to go and look, and doubt is settled there, for free, rather than+by paying for a second description.Everything in this file happens on the reconstruction side, which changes every time a package,Recipe or source edge is edited.@@ -68,9 +72,21 @@ return a difference every round for ever. So the loop ends on whichever of these- **No progress ends it immediately.** If a comparison returns the same difference it returned beforethe repair, stop. The repair is not reaching the problem, and two more rounds of the same reasoningwill not find it. Rendering and comparing cost real time on every round.-- **Three aimed attempts per element is the ceiling.** The first fixes what is obvious, the second- fixes what the first revealed, the third is the last one likely to be aimed rather than hopeful.- This is a judgement, not a measurement.+- **Two aimed attempts per element is the ceiling.** The first fixes what is obvious, the second+ fixes what the first revealed. A third round is where guessing starts to overshoot — correcting+ past the reference rather than towards it — and the run has more elements waiting than any one of+ them is worth. Time beats fidelity here by explicit choice.++## Measure what can be measured; iterate only on what cannot++Two attempts is not enough to converge by guessing, and it is not meant to be. A difference stated as+a quantity — a stroke that is too thick, a shape that is too tall, type that is too large, a margin+that is too wide — is not a guessing problem. Read the value off the reference frame directly:+the frames are ordinary images in `.hypit/reference-video-tools/<reference-id>/shots/`, and measuring+one against the known frame size gives the number in a single step.++Do that instead of spending an attempt. An attempt is for differences that have no number — a+typeface's character, a texture, a rhythm — where the only route is change it and look again.When you stop with a difference still there, record it as an accepted deviation with what it is andwhy it stayed. A difference nobody wrote down reads afterwards as a difference nobody noticed, anddiff --git a/.agents/skills/hypit/references/reference-video/workflow.md b/.agents/skills/hypit/references/reference-video/workflow.mdindex 1f8d91af..b696ae82 100644--- a/.agents/skills/hypit/references/reference-video/workflow.md+++ b/.agents/skills/hypit/references/reference-video/workflow.md@@ -15,11 +15,13 @@ Defaults are sufficient for normal use. Each also accepts `--input <json>`. Foll```textlist_svml_packages→ prepare_reference-→ observe_reference for all shots+→ observe_reference for all shots, in the background — read the route's required+ files while it runs, since its prompts do not depend on anything you read→ narrow observe_reference questions for unresolved appearance and conflicts→ inspect_svml_vocabulary for candidate packages→ develop a project-local package only for a proven vocabulary gap→ read final-sources.md, then author complete main.svml, studio.svs, build.svrun+ and the hypit.runtime.json that binds every capability they demand→ use existing checks and repair until legal→ read reconstruction-loop.md, then render each authored element and compare it```@@ -33,21 +35,35 @@ is missing.## prepare_reference-`prepare_reference` deterministically prepares clips, representative frames, tail frames, audio tails-and storyboard context, then obtains four whole-reference observations. `people_and_product` and `voices` cover who recurs.+`prepare_reference` deterministically prepares clips, representative frames, tail frames, audio tails,+storyboard context and a word-level transcript, then obtains four whole-reference observations. `people_and_product` and `voices` cover who recurs.`persistent_systems` covers the on-screen text and graphic systems that continue or recur across thewhole video, each one's lifetime, and whether its appearance ever changes. `places` covers how manylocations the video was shot in, which camera positions appear in each, which parts of the video useeach one, and each position described in enough detail to draw from the words alone — which is whatreconstructing a location depends on, since reference frames are never fed to generation.+`transcript` is the verbatim speech of the whole reference with a start and an end for every single+word, measured locally by WhisperX. It is not an observation: no model wrote it, nothing about it is+sent to Gemini, and it does not go in the observation cache. Read it whenever a decision depends on+when a word is said — placing each on-screen text reveal against the line that triggers it, timing a+caption, or checking that a voice observation matches what was actually spoken. Do not run WhisperX+by hand and do not ask a model to transcribe: the transcript is already there.++`transcript` reports `status`, `transcript_ref` and `word_count`. Read the words from+`transcript_ref`, a JSON file of passages, each with its own `words` array of+`{ text, start_seconds, end_seconds, score }`. A machine with no WhisperX service running reports+`status: "unavailable"` with a `reason` and prepares everything else; start the service with+`uv run --project services/whisperx --frozen hypit-whisperx-service` and prepare again.+When a completed preparation stage must be rerun, use one small `--redo` value:```bashhypit-reference-video-tools prepare_reference --video-path <path> --redo people```-`--redo media` rebuilds shot media and clears every derived observation. `--redo people`,+`--redo media` rebuilds shot media and clears every derived observation. `--redo transcript`+re-extracts the speech audio and measures the words again. `--redo people`,`--redo voices`, `--redo systems` and `--redo places` rerun one whole-reference stage. `--redo all` reruns everything.## observe_reference@@ -81,6 +97,25 @@ run a completed observation again, and it exists for rebuilt media, not for doubevidence quality: a complete observation that says "unclear" is still complete, and that is what anarrow question is for.+## A complete observation can still be wrong++An observation is prose written once, at a fixed temperature, by a model that saw the shot and+nothing else. It comes back complete and confident whether or not it is right. On a twenty-shot+reference, four shots came back wrong: two described a picture belonging to a different shot, and two+reported letters being *deleted* from the screen where the text was only typing in.++The frames are already on disk at+`.hypit/reference-video-tools/<reference-id>/shots/NNN-representative.jpg`, and the shot clips beside+them. Opening one costs nothing and settles the question outright, so when evidence disagrees —+one shot against the next, a shot against a whole-reference pass, or an observation against what the+video plainly is — look at the frame and decide from it. Do not re-observe: that is paid, and at+temperature `1.0` it returns a paraphrase rather than a correction.++Be most suspicious of anything an observation asserts about change over time — something appearing,+vanishing, being removed, being drawn in a single frame. A describer working from one pass infers+those rather than seeing them, and infers them wrongly. Extract a few frames across the stretch with+`ffmpeg` and look at the sequence yourself before building anything on such a claim.+## Narrow questions`--question` is a separate path. It requires one to three `--shot-id` values, answers only thatdiff --git a/packages/cli/src/main.ts b/packages/cli/src/main.tsindex 39a8719e..d113797b 100644--- a/packages/cli/src/main.ts+++ b/packages/cli/src/main.ts@@ -35,7 +35,6 @@ import type {import { writeCliHelp, writeCliOutput } from "./output.js";import type { CliColorMode, CliIo } from "./output.js";import { hypitHostStateRoot, hypitProjectStateRoot } from "./paths.js";-import { scaffoldComponentPackage } from "./scaffold.js";import { loadDiscoveredSourcePackages } from "./source-packages.js";import {clearRuntimeProfile,@@ -69,8 +68,6 @@ type ParsedArgs = {readonly model: string | undefined;readonly aspectRatio: string | undefined;readonly resolution: string | undefined;- /** Scaffold a component package that draws nothing, so it needs no preview and no still. */- readonly noVisual: boolean;/** Leave the declared external programs alone; build against what is running. */readonly noPrograms: boolean;readonly json: boolean;@@ -136,7 +133,6 @@ function parseArgs(argv: readonly string[]): ParsedArgs {let model: string | undefined;let aspectRatio: string | undefined;let resolution: string | undefined;- let noVisual = false;let noPrograms = false;let json = false;let color: CliColorMode = "auto";@@ -285,10 +281,6 @@ function parseArgs(argv: readonly string[]): ParsedArgs {index += 1;continue;}- if (item === "--no-visual") {- noVisual = true;- continue;- }if (item === "--follow") {follow = true;continue;@@ -368,7 +360,6 @@ function parseArgs(argv: readonly string[]): ParsedArgs {model,aspectRatio,resolution,- noVisual,noPrograms,json,color,@@ -415,10 +406,6 @@ function assertCommandOptions(args: ParsedArgs): void {// A package asset needs credentials and nothing else; no Runtime Profile applies.add("--prompt", "--to", "--model", "--aspect-ratio", "--resolution");break;- case "new-package":- // Writing files from string templates reads no Source and opens no Runtime.- add("--to", "--no-visual");- break;case "cancel":add("--runtime", "--reason");break;@@ -474,7 +461,6 @@ function usage(): string {" hypit cancel <build-id> [--runtime profile.json] [--reason text]"," hypit auth status|login|logout <endpoint-instance> [--runtime profile.json] [--slot name] [--from secret-file]"," hypit image --prompt <text|text-file> --to <path.png> [--model package] [--aspect-ratio r] [--resolution r]",- " hypit new-package <package-name> [--to directory] [--no-visual]","","output:"," --json --verbose --color auto|always|never --no-color --debug",@@ -920,7 +906,7 @@ export async function runCli(|| args.command === "inspect" || args.command === "get" || args.command === "cancel"|| args.command === "doctor" || args.command === "programs"|| args.command === "runtime" || args.command === "queue" || args.command === "paths"- || args.command === "image" || args.command === "new-package";+ || args.command === "image";const operational = known || args.command === "auth";const fileOptional = args.command === "builds" || args.command === "history" || args.command === "queue"|| args.command === "paths" || args.command === "image"@@ -953,41 +939,6 @@ export async function runCli(packageRoot,});};- if (args.command === "new-package") {- if (args.file === undefined) throw new Error("new-package requires a package name such as @hypit/local-notepad-list");- const scaffolded = await scaffoldComponentPackage({- name: args.file,- visual: !args.noVisual,- cwd: process.cwd(),- ...(args.to === undefined ? {} : { to: args.to }),- });- // A path outside the working directory reads better absolute than as a run of `..`.- const nested = relative(process.cwd(), scaffolded.root);- const shown = nested === "" ? "."- : nested.startsWith("..") || isAbsolute(nested) ? scaffolded.root- : nested;- writeOperational({- format: "hypit.cli-new-package@1",- name: scaffolded.name,- path: scaffolded.root,- tag: scaffolded.tag,- surface: scaffolded.surface,- visual: scaffolded.visual,- files: scaffolded.files,- }, "Package scaffolded", "success", [- ["Package", scaffolded.name],- ["Path", shown],- ["Element", `<${scaffolded.surface}:${scaffolded.tag}>`],- ["Files", String(scaffolded.files.length)],- ], [- "Run pnpm install so the workspace links it, then pnpm check.",- "The Manifest declares no Type and no Producer yet; the Surface validates and publishes nothing.",- ...(scaffolded.visual- ? [`Write preview/${scaffolded.tag}.png with node --import tsx ${shown}/test/render-still.ts`]- : []),- ]);- return;- }if (args.command === "image") {if (args.prompt === undefined) throw new Error("image requires --prompt with text or a text file path");if (args.to === undefined) throw new Error("image requires --to with the file to write");diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.tsindex dd733f0a..3b534ecc 100644--- a/packages/cli/src/output.ts+++ b/packages/cli/src/output.ts@@ -532,23 +532,6 @@ function commandHelp(topic: string, colors: Palette): readonly string[] | undefi"the credentials the selected Provider declares.","Unset options take the model's own first declared value.",],- "new-package": [- colors.accent(colors.strong("hypit new-package")),- colors.dim("Scaffold one component package: a Markup element and the code behind it."),- "",- " hypit new-package <package-name> [--to <directory>] [--no-visual]",- "",- " <package-name> the full name, such as @hypit/local-notepad-list",- " --to <directory> where to write it; defaults to packages/<name-after-the-scope>",- " --no-visual the component draws nothing, so skip the still render and preview",- "",- "It writes the Manifest, Types, Surface, Producers, Activation and README, plus a",- "still-render entry that draws one frame into preview/<Tag>.png through the local",- "HyperFrames Runtime. Nothing is generated it cannot decide: the nominal Types, the",- "Producers and the renderer are left with the comment saying where they go.",- "The directory must be empty, and only a package under a workspace glob is linked",- "by pnpm install and typechecked by pnpm check.",- ],auth: [colors.accent(colors.strong("hypit auth")),colors.dim("Manage credentials required by one declared Endpoint instance."),@@ -589,7 +572,6 @@ export function writeCliHelp(io: CliIo, topic?: string): void {row("plan <run-source>", "freeze and inspect a Build plan"),row("build <run-source>", "submit a durable Build; --follow only observes"),row("image --prompt … --to <path>", "generate one picture file for a package asset"),- row("new-package <package-name>", "scaffold one component package"),"",colors.strong("Archive"),row("builds", "list known Builds"),diff --git a/packages/cli/src/scaffold.ts b/packages/cli/src/scaffold.tsdeleted file mode 100644index e91743e2..00000000--- a/packages/cli/src/scaffold.ts+++ /dev/null@@ -1,566 +0,0 @@-import { mkdir, readdir, writeFile } from "node:fs/promises";-import { dirname, join, resolve } from "node:path";--/**- * The files a new component package starts life with.- *- * These are pure string templates over one package name, so they need nothing the generic- * command engine does not already have: no compiler, no Host, no Provider and no new- * dependency. Anything a template cannot decide — the nominal Types, the Producers, the- * renderer — is left to the author with the comment that says where it goes, rather than- * guessed here.- */--export type ScaffoldRequest = {- /** Full package name, such as `@hypit/local-notepad-list`. */- readonly name: string;- /** Directory the package is written into; defaults to `packages/<slug>` under `cwd`. */- readonly to?: string;- /** A package that draws nothing skips the still-render entry and the preview picture. */- readonly visual?: boolean;- readonly cwd: string;-};--export type ScaffoldedPackage = {- readonly name: string;- /** Absolute directory the package was written into. */- readonly root: string;- /** The Markup tag its one Surface declaration answers to. */- readonly tag: string;- /** The Surface's declared name inside the Module. */- readonly surface: string;- readonly visual: boolean;- /** Package-relative paths, in the order they were written. */- readonly files: readonly string[];-};--const NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;--/** `@hypit/local-notepad-list` → `local-notepad-list`; an unscoped name is its own slug. */-function slugOf(name: string): string {- const separator = name.indexOf("/");- return separator === -1 ? name : name.slice(separator + 1);-}--function words(slug: string): readonly string[] {- return slug.split(/[^a-z0-9]+/u).filter((word) => word.length > 0);-}--function pascal(parts: readonly string[]): string {- return parts.map((word) => word[0]!.toUpperCase() + word.slice(1)).join("");-}--function camel(parts: readonly string[]): string {- const value = pascal(parts);- return value[0]!.toLowerCase() + value.slice(1);-}--/**- * A package installed only by one project is conventionally named `local-…`; that prefix- * says where the package lives, not what its element is, so it is not part of the tag.- */-function tagWords(slug: string): readonly string[] {- const parts = words(slug);- const stripped = parts[0] === "local" ? parts.slice(1) : parts;- return stripped.length > 0 ? stripped : parts;-}--export type ScaffoldNames = {- readonly slug: string;- readonly tag: string;- readonly surface: string;- /** Identifier prefix every exported binding carries. */- readonly symbol: string;-};--export function scaffoldNames(name: string): ScaffoldNames {- if (!NAME.test(name)) {- throw new Error(`${name} is not a package name; write it as @scope/kebab-case-name`);- }- const slug = slugOf(name);- const parts = tagWords(slug);- return {- slug,- tag: pascal(parts),- surface: parts.join("-"),- symbol: camel(parts),- };-}--function packageJson(name: string, visual: boolean): string {- const value = {- name,- version: "0.0.0-dev",- license: "SEE LICENSE IN LICENSE",- private: true,- type: "module",- exports: { ".": "./src/index.ts" },- hypit: { activation: "./src/activation.ts" },- dependencies: {- "@hypit/component-kit": "workspace:*",- "@hypit/markup": "workspace:*",- "@hypit/protocol": "workspace:*",- },- ...(visual- ? {- devDependencies: {- "@hypit/composition": "workspace:*",- "@hypit/hyperframes": "workspace:*",- "@hypit/program-space": "workspace:*",- "@hypit/provider-hyperframes-local": "workspace:*",- },- }- : {}),- };- return `${JSON.stringify(value, undefined, 2)}\n`;-}--function manifest(name: string, names: ScaffoldNames, visual: boolean): string {- const { tag, surface, symbol } = names;- const preview = visual- ? ` preview: previewImage("${tag}.png"),\n`- : "";- const previewHelper = visual- ? [- `import { readFile } from "node:fs/promises";`,- ``,- ``,- ].join("\n")- : "";- const previewFunction = visual- ? [- `/** The picture this package ships for its own Surface, read from its own preview/ directory. */`,- `const previewImage = (file: string) => ({`,- ` mediaType: "image/png",`,- ` path: \`preview/\${file}\`,`,- ` open: async () => Uint8Array.from(await readFile(new URL(\`../preview/\${file}\`, import.meta.url))),`,- `});`,- ``,- ``,- ].join("\n")- : "";- const appearance = visual- ? ` appearance: "Describe exactly what a viewer sees: the shapes, where they sit, how they enter, hold and leave. Replace this sentence before the package ships — a reader who cannot picture the element cannot choose it.",\n`- : "";- return `${previewHelper}import type { MarkupSurfaceDeclaration } from "@hypit/markup";-import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";--${previewFunction}export const ${symbol}ModuleRef = { name: "${name}", version: "1" } as const;--/**- * Nominal Types this Module owns. Add one entry per authored value, declare the same name- * in the Manifest below, and give it a TypeScript shape in types.ts.- */-export const ${symbol}Types = {} satisfies Record<string, TypeRef>;--/**- * Producers this Module declares. Add one entry per deterministic step, declare its inputs- * and outputs in the Manifest below, and implement it in component.ts.- */-export const ${symbol}Producers = {} satisfies Record<string, ProducerRef>;--export const ${symbol}MarkupSurfaces = [{- name: "${surface}", tag: "${tag}", mode: "structured",- // One entry per Type this element publishes, once the Manifest declares one.- outputs: [],- vocabulary: {- summary: "One ${tag}. Say what the element is for in one sentence, in the author's terms.",-${appearance}${preview} attributes: [- { name: "id", kind: "identifier", required: true,- summary: "Names this ${tag} and prefixes every binding it publishes." },- ],- example: \`<${surface}:${tag} id="example"/>\`,- notes: [- "The element is empty; it accepts no children and no text.",- "This Surface publishes nothing yet: its Module declares no Type for it to carry.",- ],- },-}] as const satisfies readonly MarkupSurfaceDeclaration[];--export const ${symbol}Manifest: ModuleManifest = {- format: "hypit.module@1",- name: ${symbol}ModuleRef.name,- version: ${symbol}ModuleRef.version,- // One entry per Module whose Types this one references.- dependencies: [],- types: [],- capabilities: [],- producers: [],-};--export const ${symbol}Dependency = { module: ${symbol}ModuleRef } as const;-`;-}--function types(names: ScaffoldNames): string {- const { tag } = names;- return `/**- * The TypeScript shapes the Manifest's nominal Types carry. Every value that crosses a- * boundary belongs here, and gets an \`assert…\` and a \`seal…\` beside the code that builds it.- */--/** Identity every ${tag} value is prefixed by. */-export type ${tag}Header = {- readonly id: string;-};-`;-}--function surface(names: ScaffoldNames): string {- const { tag, symbol } = names;- return `import type { StructuredElement, StructuredSurfaceHandler } from "@hypit/markup";--import type { ${tag}Header } from "./types.js";--/** Exactly the attributes the vocabulary declares; add each new one here and there together. */-const ATTRIBUTES: readonly string[] = ["id"];--function requiredText(element: StructuredElement, name: string): string {- const value = element.attributes[name];- if (typeof value !== "string" || value.trim().length === 0) {- throw new Error(\`\${element.name}.\${name} must be text.\`);- }- return value.trim();-}--/** Reads what the vocabulary promises, and refuses anything else in the author's terms. */-export function read${tag}Header(element: StructuredElement): ${tag}Header {- const unknown = Object.keys(element.attributes).find((name) => !ATTRIBUTES.includes(name));- if (unknown !== undefined) throw new Error(\`\${element.name} does not accept \${unknown}.\`);- if (element.children.length > 0) throw new Error(\`\${element.name} accepts no children.\`);- return { id: requiredText(element, "id") };-}--/**- * Decodes one <${tag}> element.- *- * It validates the element today and publishes nothing, because the Module declares no- * Type yet. To publish: add the Type to \`${symbol}Types\`, list it in the Manifest and in- * this Surface's \`outputs\`, then push a SurfaceRecordDraft here —- *- * records.push({- * id: header.id,- * type: ${symbol}Types.program,- * value: { kind: "inline", value: seal${tag}Program(header) },- * range: element.range,- * });- *- * Operations the element needs run as Producers, wired by a GraphFragment in \`fragments\`.- */-export const decode${tag}Surface: StructuredSurfaceHandler = ({ element }) => {- read${tag}Header(element);- return { records: [], components: [], fragments: [] };-};-`;-}--function component(names: ScaffoldNames): string {- const { symbol } = names;- return `import type { ComponentPackage } from "@hypit/component-kit";--/**- * The deterministic handlers this package's Manifest declared, plus the Validators that- * guard its nominal Types. Both lists stay in step with the Manifest: a Producer declared- * there and missing here fails at load, not at Build.- */-export const ${symbol}Component = {- producers: [],- validators: [],-} satisfies ComponentPackage;-`;-}--function activation(names: ScaffoldNames): string {- const { tag, symbol } = names;- return `import { createMarkupSurfaceHostFacet } from "@hypit/markup";--import {- decode${tag}Surface,- ${symbol}Component,- ${symbol}Manifest,- ${symbol}MarkupSurfaces,- ${symbol}ModuleRef,-} from "./index.js";--/** Everything a Host installs from this package, and nothing a Host has to know by name. */-export const hypitPackage = {- format: "hypit.node-package@1" as const,- modules: [{ manifest: ${symbol}Manifest }],- components: [${symbol}Component],- hostFacets: [- createMarkupSurfaceHostFacet({- module: ${symbol}ModuleRef,- declaration: ${symbol}MarkupSurfaces[0],- handler: decode${tag}Surface,- }),- ],-};--export default hypitPackage;-`;-}--function index(names: ScaffoldNames): string {- const { tag, symbol } = names;- return `export { ${symbol}Component } from "./component.js";-export {- ${symbol}Dependency,- ${symbol}Manifest,- ${symbol}MarkupSurfaces,- ${symbol}ModuleRef,- ${symbol}Producers,- ${symbol}Types,-} from "./manifest.js";-export { decode${tag}Surface, read${tag}Header } from "./surface.js";-export type { ${tag}Header } from "./types.js";-`;-}--function renderStill(names: ScaffoldNames): string {- const { tag, slug } = names;- return `/**- * Renders one frame of this package through the local HyperFrames Runtime and writes it to- * preview/${tag}.png — the picture this package's Surface declaration points at.- *- * node --import tsx test/render-still.ts [frame]- *- * No Provider, no Build and no Runtime Profile take part: the preview is authoring input- * that ships inside the package, so it is never anybody's Output.- */-import { spawnSync } from "node:child_process";-import { copyFile, mkdir, mkdtemp, readdir, rm, stat, writeFile } from "node:fs/promises";-import { createRequire } from "node:module";-import os from "node:os";-import path from "node:path";--import { sealComposition, sealVisualTrack } from "@hypit/composition";-import type { VisualTrack } from "@hypit/composition";-import { compileHyperframesDocument, materializeHyperframesHtml } from "@hypit/hyperframes";-import { sealProgramSpace } from "@hypit/program-space";-import type { ProgramSpace } from "@hypit/program-space";--const CANVAS = { width: 1080, height: 1920, clearColor: "#101014" } as const;-const FPS = 10;-const TOTAL_FRAMES = 10;--/** The repository that owns the local HyperFrames Provider, whatever depth this package sits at. */-async function repositoryRoot(): Promise<string> {- let directory = import.meta.dirname;- while (true) {- const marker = path.join(directory, "packages/provider-hyperframes-local/package.json");- if (await stat(marker).then((entry) => entry.isFile(), () => false)) return directory;- const parent = path.dirname(directory);- if (parent === directory) throw new Error("run this inside the repository that owns @hypit/provider-hyperframes-local");- directory = parent;- }-}--/**- * Replace this with your renderer.- *- * Build the Program your Surface publishes and lower it to one VisualTrack, exactly as the- * Producer will. Until then it draws one placeholder card, so the render path can be run- * and looked at from the first minute.- */-function render(space: ProgramSpace): VisualTrack {- void space;- return sealVisualTrack({- visualIr: "hypit.visual-ir@1",- id: "${slug}-preview",- presents: [{- id: "placeholder",- span: { startFrame: 0, endFrameExclusive: TOTAL_FRAMES },- stacking: { order: 0, tieBreak: "${slug}-preview" },- elements: [{- id: "card",- order: 0,- kind: "box",- style: [- { name: "background-color", value: "#f5f2e8" },- { name: "border-radius", value: "48px" },- { name: "height", value: "640px" },- { name: "left", value: "120px" },- { name: "position", value: "absolute" },- { name: "top", value: "640px" },- { name: "width", value: "840px" },- ],- }],- }],- });-}--async function main(): Promise<void> {- const wanted = Number(process.argv[2] ?? "0");- if (!Number.isSafeInteger(wanted) || wanted < 0) throw new Error("frame must be a whole number");- const space = sealProgramSpace({- durationSec: TOTAL_FRAMES / FPS,- frameRate: { numerator: FPS, denominator: 1 },- });- const document = compileHyperframesDocument(sealComposition({- id: "${slug}-preview",- canvas: CANVAS,- tracks: [render(space)],- }), space);- const hyperframesCli = createRequire(path.join(await repositoryRoot(), "packages/provider-hyperframes-local/package.json"))- .resolve("hyperframes/bin/hyperframes.mjs");- const temporary = await mkdtemp(path.join(os.tmpdir(), "${slug}-still-"));- try {- if (document.artifacts.length > 0) {- // Write each Artifact's bytes into \`temporary\` and return its file name below.- throw new Error(\`this still does not carry Artifacts yet; \${document.artifacts.length} were required\`);- }- await writeFile(path.join(temporary, "index.html"), materializeHyperframesHtml(document, (artifact) => {- throw new Error(\`unmapped Artifact \${artifact.digest}\`);- }));- const frames = path.join(temporary, "frames");- await mkdir(frames);- const rendered = spawnSync(process.execPath, [- hyperframesCli, "render", temporary,- "--format", "png-sequence", "--output", frames,- "--fps", String(FPS), "--workers", "1",- "--no-browser-gpu", "--no-best-effort", "--quiet",- ], { encoding: "utf8", timeout: 600_000 });- if (rendered.status !== 0) throw new Error(\`\${rendered.stdout}\\n\${rendered.stderr}\`);- const produced = (await readdir(frames)).filter((name) => name.endsWith(".png")).sort();- const chosen = produced[wanted];- if (chosen === undefined) throw new Error(\`frame \${wanted} is out of range; \${produced.length} rendered\`);- const output = path.join(import.meta.dirname, "../preview/${tag}.png");- await mkdir(path.dirname(output), { recursive: true });- await copyFile(path.join(frames, chosen), output);- process.stdout.write(\`\${output} (\${produced.length} frames rendered)\\n\`);- } finally {- await rm(temporary, { recursive: true, force: true });- }-}--await main();-`;-}--function readme(name: string, names: ScaffoldNames, visual: boolean): string {- const { tag, surface: surfaceName, symbol, slug } = names;- const visualSection = visual- ? `-## The preview picture--\`src/manifest.ts\` declares \`preview/${tag}.png\`. Write it with the still-render entry, which-renders one frame through the local HyperFrames Runtime and needs no Provider:--\`\`\`-node --import tsx test/render-still.ts-\`\`\`--It draws a placeholder card until \`render\` in \`test/render-still.ts\` calls your renderer.--Other pictures a component draws itself with — paper, a board, a panel — go in \`assets/\` and-are read with \`readFile(new URL("../assets/…", import.meta.url))\`. Generate one with-\`hypit image --prompt … --to assets/….png\` and commit the result: neither the preview nor an-asset is an input the installing project supplies, and neither is produced by a Build.-`- : "";- return `# ${name}--One component package: a Markup element authors write, and the deterministic code behind it.--## What is here--| File | Role |-|---|---|-| \`src/manifest.ts\` | Module identity, nominal Types, Producers and the Surface declaration with its vocabulary |-| \`src/types.ts\` | The TypeScript shapes those nominal Types carry |-| \`src/surface.ts\` | \`<${surfaceName}:${tag}>\` into typed Records and graph inputs |-| \`src/component.ts\` | The Producer handlers the Manifest declared, and the Type Validators |-| \`src/activation.ts\` | The Host facets a Host installs |-| \`src/index.ts\` | The package's public surface |-${visual ? `| \`test/render-still.ts\` | One frame rendered locally into \`preview/${tag}.png\` |\n` : ""}| \`assets/\` | Pictures this component draws itself with |-| \`preview/\` | The picture the Surface declaration points at |--\`docs/guide/component-anatomy.md\` describes every role, including the ones this package does-not have a file for yet: the value layer (\`assert…\`, \`seal…\`), the Style decoder, the renderer-and the Fragment.--## What is still yours to write--1. **The Types.** Add each nominal Type to \`${symbol}Types\` in \`src/manifest.ts\`, declare the- same name under \`types\`, and give it a shape in \`src/types.ts\`. Write these first and stop- changing them: everything else agrees with them.-2. **The value layer.** One \`assert…\` stating what is wrong in the author's terms and one- \`seal…\` canonicalising it, for every value that crosses a boundary.-3. **The Producers.** Declare inputs and outputs under \`producers\` in the Manifest, then- implement each one in \`src/component.ts\`.-4. **The Surface's real output.** \`decode${tag}Surface\` validates and publishes nothing today.- Add the Records it pushes and the GraphFragment that wires the Producers.-5. **The vocabulary.** \`summary\`${visual ? ", `appearance`" : ""}, every attribute and every note in \`src/manifest.ts\` are what a- reader chooses this element by. The scaffolded text is placeholder; replace it.-${visualSection}-## Installing it--The package is a workspace member. From the repository root:--\`\`\`-pnpm install-pnpm check-\`\`\`--Then a Source reaches it by Module name, and \`as\` chooses the prefix its element is written under:--\`\`\`-<?svml using="@hypit/markup@1"?>--<svml>- <import as="${surfaceName}" from="${name}@1"/>-- <${surfaceName}:${tag} id="${slug}-one"/>-</svml>-\`\`\`--\`hypit check\` on that Source is the shortest proof the package loads.-`;-}--/**- * Writes one component package and returns what it wrote.- *- * The directory must not already hold files: a scaffold that merges into existing work has- * no way to tell an intentional edit from something it is about to lose.- */-export async function scaffoldComponentPackage(request: ScaffoldRequest): Promise<ScaffoldedPackage> {- const names = scaffoldNames(request.name);- const visual = request.visual ?? true;- const root = resolve(request.cwd, request.to ?? join("packages", names.slug));- const existing = await readdir(root).catch((error: NodeJS.ErrnoException) => {- if (error.code === "ENOENT") return [];- throw error;- });- if (existing.length > 0) {- throw new Error(`${root} is not empty; scaffold into a new directory`);- }- const files: (readonly [string, string])[] = [- ["package.json", packageJson(request.name, visual)],- ["README.md", readme(request.name, names, visual)],- ["src/manifest.ts", manifest(request.name, names, visual)],- ["src/types.ts", types(names)],- ["src/surface.ts", surface(names)],- ["src/component.ts", component(names)],- ["src/activation.ts", activation(names)],- ["src/index.ts", index(names)],- ...(visual ? [["test/render-still.ts", renderStill(names)] as const] : []),- ];- for (const [file, contents] of files) {- const target = join(root, file);- await mkdir(dirname(target), { recursive: true });- await writeFile(target, contents);- }- // Both directories are part of the package's shape even before anything is put in them.- for (const directory of ["assets", "preview"]) {- await mkdir(join(root, directory), { recursive: true });- }- return {- name: request.name,- root,- tag: names.tag,- surface: names.surface,- visual,- files: [...files.map(([file]) => file), "assets/", "preview/"],- };-}diff --git a/packages/cli/test/new-package.test.ts b/packages/cli/test/new-package.test.tsdeleted file mode 100644index baa13447..00000000--- a/packages/cli/test/new-package.test.ts+++ /dev/null@@ -1,172 +0,0 @@-import assert from "node:assert/strict";-import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";-import os from "node:os";-import path from "node:path";-import test from "node:test";--import type { CliDistribution } from "../src/distribution.js";-import { runCli } from "../src/main.js";-import { scaffoldNames } from "../src/scaffold.js";--/** new-package writes files and nothing else, so no Distribution capability is reachable. */-const distribution = {- openRuntimeHost: () => { throw new Error("new-package must open no Runtime"); },- generatePicture: () => { throw new Error("new-package must call no Provider"); },-} as unknown as CliDistribution;--async function scaffold(argv: readonly string[]): Promise<{ readonly output: string; readonly root: string }> {- const temporary = await mkdtemp(path.join(os.tmpdir(), "hypit-new-package-"));- let output = "";- await runCli(argv.map((item) => (item === "<to>" ? temporary : item)),- { write: (text) => { output += text; } }, distribution);- return { output, root: temporary };-}--type Machine = {- readonly format: string;- readonly name: string;- readonly path: string;- readonly tag: string;- readonly surface: string;- readonly visual: boolean;- readonly files: readonly string[];-};--test("a scaffolded package carries every role a component package fills", async () => {- const { output, root } = await scaffold([- "new-package", "@hypit/local-notepad-list", "--to", "<to>", "--json",- ]);- try {- const machine = JSON.parse(output) as Machine;- assert.equal(machine.format, "hypit.cli-new-package@1");- assert.equal(machine.name, "@hypit/local-notepad-list");- assert.equal(machine.path, root);- assert.equal(machine.tag, "NotepadList");- assert.equal(machine.surface, "notepad-list");- assert.equal(machine.visual, true);- assert.deepEqual(machine.files, [- "package.json", "README.md",- "src/manifest.ts", "src/types.ts", "src/surface.ts", "src/component.ts",- "src/activation.ts", "src/index.ts",- "test/render-still.ts",- "assets/", "preview/",- ]);-- const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8")) as {- readonly name: string;- readonly version: string;- readonly private: boolean;- readonly type: string;- readonly exports: Readonly<Record<string, string>>;- readonly hypit: Readonly<Record<string, string>>;- readonly dependencies: Readonly<Record<string, string>>;- };- assert.equal(manifest.name, "@hypit/local-notepad-list");- assert.equal(manifest.version, "0.0.0-dev");- assert.equal(manifest.private, true);- assert.equal(manifest.type, "module");- assert.equal(manifest.exports["."], "./src/index.ts");- assert.equal(manifest.hypit["activation"], "./src/activation.ts");- assert.equal(manifest.dependencies["@hypit/markup"], "workspace:*");-- const module = await readFile(path.join(root, "src/manifest.ts"), "utf8");- assert.match(module, /name: "@hypit\/local-notepad-list", version: "1"/u);- assert.match(module, /types: \[\],/u);- assert.match(module, /producers: \[\],/u);- // The vocabulary is what a reader chooses the element by, so every part of it is written.- for (const part of ["summary:", "appearance:", "preview: previewImage(\"NotepadList.png\")", "attributes:", "example:", "notes:"]) {- assert.ok(module.includes(part), `manifest is missing ${part}`);- }- assert.match(module, /\{ name: "id", kind: "identifier", required: true,/u);-- // Both directories exist even before anything is put in them.- assert.deepEqual(await readdir(path.join(root, "assets")), []);- assert.deepEqual(await readdir(path.join(root, "preview")), []);-- const still = await readFile(path.join(root, "test/render-still.ts"), "utf8");- assert.match(still, /preview\/NotepadList\.png/u);- assert.match(still, /hyperframes\/bin\/hyperframes\.mjs/u);- } finally {- await rm(root, { recursive: true, force: true });- }-});--test("--no-visual drops the still render and the preview the Surface would declare", async () => {- const { output, root } = await scaffold([- "new-package", "@hypit/local-quiet-thing", "--to", "<to>", "--no-visual", "--json",- ]);- try {- const machine = JSON.parse(output) as Machine;- assert.equal(machine.visual, false);- assert.ok(!machine.files.includes("test/render-still.ts"));- const module = await readFile(path.join(root, "src/manifest.ts"), "utf8");- assert.ok(!module.includes("previewImage"));- assert.ok(!module.includes("appearance:"));- const manifest = JSON.parse(await readFile(path.join(root, "package.json"), "utf8")) as {- readonly devDependencies?: unknown;- };- assert.equal(manifest.devDependencies, undefined);- } finally {- await rm(root, { recursive: true, force: true });- }-});--test("the element tag drops the local- prefix, which says where a package lives", () => {- assert.deepEqual(scaffoldNames("@hypit/local-notepad-list"),- { slug: "local-notepad-list", tag: "NotepadList", surface: "notepad-list", symbol: "notepadList" });- assert.deepEqual(scaffoldNames("@hypit/ranking"),- { slug: "ranking", tag: "Ranking", surface: "ranking", symbol: "ranking" });- assert.deepEqual(scaffoldNames("comment-sticker"),- { slug: "comment-sticker", tag: "CommentSticker", surface: "comment-sticker", symbol: "commentSticker" });-});--test("a name that is not a package name is refused before anything is written", async () => {- await assert.rejects(- async () => await scaffold(["new-package", "@hypit/Notepad List", "--to", "<to>"]),- /is not a package name/u,- );-});--test("new-package refuses to write into a directory that already holds files", async () => {- const temporary = await mkdtemp(path.join(os.tmpdir(), "hypit-new-package-"));- try {- await writeFile(path.join(temporary, "package.json"), "{}\n");- await assert.rejects(- async () => await runCli(- ["new-package", "@hypit/local-notepad-list", "--to", temporary],- { write: () => {} }, distribution,- ),- /is not empty/u,- );- } finally {- await rm(temporary, { recursive: true, force: true });- }-});--test("new-package takes its name positionally and refuses options that do not apply", async () => {- await assert.rejects(- async () => await runCli(["new-package"], { write: () => {} }, distribution),- /hypit new-package <package-name>/u,- );- await assert.rejects(- async () => await runCli(- ["new-package", "@hypit/local-notepad-list", "--runtime", "/tmp/profile.json"],- { write: () => {} }, distribution,- ),- /--runtime does not apply to new-package/u,- );- await assert.rejects(- async () => await runCli(["build", "run.svrun", "--no-visual"], { write: () => {} }, distribution),- /--no-visual does not apply to build/u,- );-});--test("help lists new-package and describes it under its own topic", async () => {- let listing = "";- await runCli(["--help"], { write: (text) => { listing += text; } }, distribution);- assert.match(listing, /new-package <package-name>/u);- let topic = "";- await runCli(["help", "new-package"], { write: (text) => { topic += text; } }, distribution);- assert.match(topic, /--no-visual/u);- assert.match(topic, /packages\/<name-after-the-scope>/u);-});diff --git a/packages/reference-video-tools/README.md b/packages/reference-video-tools/README.mdindex 6402a0e4..f2cc75c2 100644--- a/packages/reference-video-tools/README.md+++ b/packages/reference-video-tools/README.md@@ -15,6 +15,7 @@ Run the CLI from the repository or an installed package:pnpm hypit-reference-video-tools list_svml_packagespnpm hypit-reference-video-tools prepare_reference --video-path ./reference.mp4pnpm hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --redo people+pnpm hypit-reference-video-tools prepare_reference --video-path ./reference.mp4 --redo transcriptpnpm hypit-reference-video-tools observe_reference --reference-id <reference-id>pnpm hypit-reference-video-tools observe_reference --reference-id <reference-id> --shot-id shot-007pnpm hypit-reference-video-tools observe_reference --reference-id <reference-id> --shot-id shot-007 --question "How thick is the outline on the caption words?"@@ -37,9 +38,21 @@ gitignored `.hypit/reference-video-tools/` directory. It produces four full-refethe whole video, each one's lifetime, and whether its appearance ever changes — and `places`: howmany locations the video was shot in, which camera positions appear in each, which parts of the videouse each one, and each position described in enough detail to draw from the words alone. Without `--redo`, completed stages are reused. Use `--redo media` to rebuild shot media and-clear derived observations, or `--redo people`, `--redo voices`, `--redo systems`, `--redo places`, or `--redo all` to+clear derived observations, `--redo transcript` to measure the words again, or `--redo people`, `--redo voices`, `--redo systems`, `--redo places`, or `--redo all` torerun only the selected full-reference stages.+It also produces `transcript`: the verbatim speech of the whole reference with a start and an end for+every single word. Placing an on-screen text reveal against the line that triggers it needs the time+of the word, not of the sentence around it, and that question comes up in every reconstruction. The+speech audio is extracted to `speech.wav` beside the shot media and measured by the local WhisperX+Provider in `@hypit/provider-whisperx-local`, which answers a loopback service on+`http://127.0.0.1:8765`; start it with `uv run --project services/whisperx --frozen hypit-whisperx-service`.+The result reports `status`, `transcript_ref` and `word_count`, and the words themselves live in+`transcript.json` as passages, each with a `words` array of `{ text, start_seconds, end_seconds, score }`.+The transcript is deterministic local evidence rather than an observation: it is never written to the+observation cache and nothing about it is sent to Gemini. A machine with no WhisperX service running+reports `status: "unavailable"` with the reason and prepares everything else.+`observe_reference` observes every unfinished shot, or only the shots named by `--shot-id`. Each shotproduces three observations — `visual` (base picture, covering content, continuity, whether the frameis a depicted scene or a flat designed field, and each framed element's inner picture separately fromdiff --git a/packages/reference-video-tools/package.json b/packages/reference-video-tools/package.jsonindex 08a660df..53b8b4dc 100644--- a/packages/reference-video-tools/package.json+++ b/packages/reference-video-tools/package.json@@ -12,10 +12,15 @@},"dependencies": {"@google/genai": "1.52.0",+ "@hypit/driver-node": "workspace:*","@hypit/markup": "workspace:*","@hypit/model-kit": "workspace:*","@hypit/package-loader-node": "workspace:*","@hypit/protocol": "workspace:*",+ "@hypit/provider-whisperx-local": "workspace:*",+ "@hypit/speech": "workspace:*",+ "@hypit/speech-evidence": "workspace:*",+ "@hypit/whisperx": "workspace:*","tsx": "4.21.0"},"devDependencies": {diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.tsindex c28fc3c0..dc149bf9 100644--- a/packages/reference-video-tools/src/cli.ts+++ b/packages/reference-video-tools/src/cli.ts@@ -7,7 +7,7 @@ function usage(): string {return ["Usage:"," hypit-reference-video-tools list_svml_packages",- " hypit-reference-video-tools prepare_reference --video-path <path> [--redo media|people|voices|systems|places|all]",+ " hypit-reference-video-tools prepare_reference --video-path <path> [--redo media|transcript|people|voices|systems|places|all]"," hypit-reference-video-tools observe_reference --reference-id <id> [--shot-id <id> ...] [--reobserve]"," hypit-reference-video-tools observe_reference --reference-id <id> --shot-id <id> [--shot-id <id> ...] --question <text>"," hypit-reference-video-tools inspect_svml_vocabulary --package <name> [--package <name> ...] [--tag <tag> ...] [--without-previews]",@@ -87,7 +87,7 @@ async function main(): Promise<void> {video_path: required(flags, "video-path"),...(one(flags, "redo") === undefined ? {} : { redo: one(flags, "redo") }),};- result = await tools.prepare_reference(input as { video_path: string; redo?: "media" | "people" | "voices" | "systems" | "places" | "all" });+ result = await tools.prepare_reference(input as { video_path: string; redo?: "media" | "transcript" | "people" | "voices" | "systems" | "places" | "all" });} else if (command === "observe_reference") {const input = supplied ?? {reference_id: required(flags, "reference-id"),diff --git a/packages/reference-video-tools/src/media.ts b/packages/reference-video-tools/src/media.tsindex 5322c087..d713867a 100644--- a/packages/reference-video-tools/src/media.ts+++ b/packages/reference-video-tools/src/media.ts@@ -57,14 +57,22 @@ async function signatures(path: string, sampleRate: number): Promise<readonly Uireturn result;}+// Boundaries are only as precise as this rate, and a clip cut on an imprecise boundary opens on+// content belonging to the shot before it. At three samples a second that overhang reached a third+// of a second — long enough for an observer to describe a shot as the picture that precedes it, and+// to read a list that had been typing all along as one whose letters were being deleted. The whole+// video is decoded once whatever the rate, so sampling four times as often costs four times as many+// 32×32 signatures and no additional decoding.+const SAMPLE_RATE = 12;+async function contentBoundaries(path: string, duration: number): Promise<readonly number[]> {- const frames = await signatures(path, 3);+ const frames = await signatures(path, SAMPLE_RATE);if (frames.length < 2) return [0, duration];const starts = [0];let anchor = frames[0]!;for (let index = 1; index < frames.length; index += 1) {if (distance(frames[index]!, anchor) > 0.1) {- starts.push(round(index / 3));+ starts.push(round(index / SAMPLE_RATE));anchor = frames[index]!;}}@@ -114,8 +122,10 @@ export async function prepareMedia(videoPath: string, root: string, duration: nuawait Promise.all(bounds.map(async (bound, index) => {const id = String(index + 1).padStart(3, "0");const clip = join(shotDir, `${id}.mp4`);- await extract(videoPath, ["-ss", String(bound.start), "-i", videoPath, "-t", String(Math.max(0.1, bound.end - bound.start)), "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-c:a", "aac", "-b:a", "96k", "-movflags", "+faststart"], clip);- await extract(videoPath, ["-ss", String(bound.start + (bound.end - bound.start) / 2), "-i", videoPath, "-frames:v", "1", "-vf", "scale='min(720,iw)':-2", "-q:v", "3"], join(shotDir, `${id}-representative.jpg`));+ // `-ss` goes after `-i`: seeking the output decodes from the start and lands on the frame asked+ // for, where seeking the input lands on the keyframe before it.+ await extract(videoPath, ["-i", videoPath, "-ss", String(bound.start), "-t", String(Math.max(0.1, bound.end - bound.start)), "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-c:a", "aac", "-b:a", "96k", "-movflags", "+faststart"], clip);+ await extract(videoPath, ["-i", videoPath, "-ss", String(bound.start + (bound.end - bound.start) / 2), "-frames:v", "1", "-vf", "scale='min(720,iw)':-2", "-q:v", "3"], join(shotDir, `${id}-representative.jpg`));await extract(videoPath, ["-sseof", "-0.1", "-i", clip, "-update", "1", "-frames:v", "1", "-vf", "scale='min(720,iw)':-2", "-q:v", "3"], join(shotDir, `${id}-tail.jpg`));if (await hasAudio(clip)) await extract(videoPath, ["-sseof", "-3", "-i", clip, "-map", "0:a:0", "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le"], join(shotDir, `${id}-audio.wav`));}));diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.tsindex 5259a451..49c481e3 100644--- a/packages/reference-video-tools/src/tools.ts+++ b/packages/reference-video-tools/src/tools.ts@@ -18,11 +18,12 @@ import {referenceId,writeJson,} from "./media.js";-import type { Observation, PrepareResult, ReferenceState, Shot } from "./types.js";+import { prepareTranscript } from "./transcript.js";+import type { Observation, PrepareResult, ReferenceState, Shot, Transcript } from "./types.js";export type PrepareReferenceInput = {readonly video_path: string;- readonly redo?: "media" | "people" | "voices" | "systems" | "places" | "all";+ readonly redo?: "media" | "transcript" | "people" | "voices" | "systems" | "places" | "all";};export type ObserveReferenceInput = {readonly reference_id: string;@@ -63,6 +64,7 @@ export type GenerateText = (input: { readonly parts: readonly Part[]; readonly itype ObservationTask = { readonly key: string; readonly run: () => Promise<Observation> };function observation(status: "complete" | "failed", text: string): Observation { return { status, text }; }+function unavailable(reason: string): Transcript { return { status: "unavailable", transcript_ref: null, word_count: 0, reason }; }function positiveEnv(name: string): number | undefined {const raw = process.env[name]?.trim();@@ -225,7 +227,8 @@ async function shotFromBound(root: string, index: number, bound: { start: number}function prepared(state: ReferenceState): boolean {- return state.people_and_product?.status === "complete"+ return state.transcript?.status === "complete"+ && state.people_and_product?.status === "complete"&& state.voices?.status === "complete"&& state.persistent_systems?.status === "complete"&& state.places?.status === "complete";@@ -238,6 +241,7 @@ function publicPrepare(state: ReferenceState): PrepareResult {video: state.video,shots: state.shots,storyboard_ref: state.storyboard_ref,+ transcript: state.transcript ?? unavailable("not transcribed"),people_and_product: state.people_and_product ?? observation("failed", "not analyzed"),voices: state.voices ?? observation("failed", "not analyzed"),persistent_systems: state.persistent_systems ?? observation("failed", "not analyzed"),@@ -313,7 +317,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV},async prepare_reference(input): Promise<PrepareResult> {- assert(input.redo === undefined || input.redo === "media" || input.redo === "people" || input.redo === "voices" || input.redo === "systems" || input.redo === "places" || input.redo === "all", "redo must be one of: media, people, voices, systems, places, all");+ assert(input.redo === undefined || input.redo === "media" || input.redo === "transcript" || input.redo === "people" || input.redo === "voices" || input.redo === "systems" || input.redo === "places" || input.redo === "all", "redo must be one of: media, transcript, people, voices, systems, places, all");const videoPath = resolve(input.video_path);const file = await stat(videoPath).catch(() => undefined);assert(file?.isFile(), `video_path is not a file: ${videoPath}`);@@ -322,6 +326,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVconst statePath = join(root, "state.json");let existing = await readJson<ReferenceState>(statePath);const redoMedia = input.redo === "media" || input.redo === "all";+ const redoTranscript = input.redo === "transcript" || input.redo === "all";const redoPeople = input.redo === "people" || input.redo === "all";const redoVoices = input.redo === "voices" || input.redo === "all";const redoSystems = input.redo === "systems" || input.redo === "all";@@ -350,6 +355,8 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVshots,storyboard_ref: media.storyboard,analysis_video_ref: media.analysisVideo,+ // The transcript is measured from the source audio, which rebuilt shot media cannot change.+ ...(existing?.transcript === undefined ? {} : { transcript: existing.transcript }),...(existing?.people_and_product === undefined ? {} : { people_and_product: existing.people_and_product }),...(existing?.voices === undefined ? {} : { voices: existing.voices }),...(existing?.persistent_systems === undefined ? {} : { persistent_systems: existing.persistent_systems }),@@ -360,6 +367,11 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceVawait writeFile(join(root, "observations.json"), "{}\n", "utf8");}const generate = await generator();+ // WhisperX is local and slow and shares nothing with the Gemini requests, so it runs beside+ // them rather than ahead of them.+ const transcribing = state.transcript?.status === "complete" && !redoTranscript+ ? Promise.resolve(state.transcript)+ : prepareTranscript(reference, videoPath, root, info.hasAudio, redoTranscript);const mediaPart = mediaParts();const globalParts: Part[] = [await mediaPart(analysisVideo)];const [people, voices, systems, places] = await Promise.all([@@ -376,7 +388,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV? Promise.resolve(state.places): callSafely(retryDelayMs, generate, [...globalParts, { text: "Describe every distinct place this reference video was shot in, and every distinct camera position within each place. State how many places there are, which parts of the video happen in each, and for each place which camera positions appear and which parts of the video use each one. Two shots are the same camera position when the camera sees the same part of the room from the same side; a reverse angle is a different position of the same place.\n\nDescribe each camera position in enough detail that someone who has never seen this video could draw it from your words alone: what is behind and beside the subject, the shape and depth of the space, where the light comes from and how hard it is, the colours and materials of the surfaces, and the objects a viewer would use to recognise it again. Say what stays identical between positions of one place and what differs.\n\nReturn natural language only." }], "You only observe a reference video. Return natural language evidence only. Do not write code, markup, SVML, or component names."),]);- const complete: ReferenceState = { ...state, people_and_product: people, voices, persistent_systems: systems, places };+ const complete: ReferenceState = { ...state, transcript: await transcribing, people_and_product: people, voices, persistent_systems: systems, places };await writeJson(statePath, complete);return publicPrepare(complete);},diff --git a/packages/reference-video-tools/src/transcript.ts b/packages/reference-video-tools/src/transcript.tsnew file mode 100644index 00000000..2a31fef3--- /dev/null+++ b/packages/reference-video-tools/src/transcript.ts@@ -0,0 +1,115 @@+import { access } from "node:fs/promises";+import { join } from "node:path";+import { EndpointRegistry, MemoryArtifactStore } from "@hypit/driver-node";+import type { Need } from "@hypit/protocol";+import { createLocalWhisperXProvider } from "@hypit/provider-whisperx-local";+import { sealSpeechEvidenceAudio } from "@hypit/speech";+import { speechEvidenceTypes } from "@hypit/speech-evidence";+import type { AlignedTranscriptEvidence } from "@hypit/speech-evidence";+import { whisperXCapabilities, whisperXRequestForEvidenceAudio } from "@hypit/whisperx";++import { assert, command, readBytes, round, writeJson } from "./media.js";+import type { Transcript, TranscriptFile, TranscriptPassage, TranscriptWord } from "./types.js";++// WhisperX measures in samples of the canonical evidence rate and refuses audio of any other shape,+// so this is both what the audio is extracted at and what its word times are divided by.+const EVIDENCE_SAMPLE_RATE = 16_000;++export async function extractSpeechAudio(videoPath: string, target: string): Promise<string> {+ await command("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", "-i", videoPath, "-map", "0:a:0", "-vn", "-ac", "1", "-ar", String(EVIDENCE_SAMPLE_RATE), "-c:a", "pcm_s16le", "-bitexact", target], 300_000);+ return target;+}++// The Provider checks that the declared sample count is exactly the one in the file, so the count is+// read out of the file rather than derived from a duration that rounds.+function sampleFrames(bytes: Uint8Array): number {+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);+ let offset = 12;+ while (offset + 8 <= bytes.byteLength) {+ const size = view.getUint32(offset + 4, true);+ if (String.fromCharCode(...bytes.subarray(offset, offset + 4)) === "data") return size / 2;+ offset += 8 + size + (size % 2);+ }+ throw new Error("extracted speech audio has no WAV data chunk");+}++function seconds(sample: number | undefined): number | undefined {+ return sample === undefined ? undefined : round(sample / EVIDENCE_SAMPLE_RATE);+}++// A refused connection arrives as `fetch failed` and says where only in its cause, which is the one+// thing the reader of an unavailable transcript needs.+function reason(error: unknown): string {+ if (!(error instanceof Error)) return String(error);+ return error.cause === undefined ? error.message : `${error.message}: ${reason(error.cause)}`;+}++/** Ask the local WhisperX Provider for the word times of one canonical evidence WAV. */+export async function transcribeSpeechAudio(audioPath: string): Promise<readonly TranscriptPassage[]> {+ const bytes = await readBytes(audioPath);+ const artifacts = new MemoryArtifactStore();+ const artifact = await artifacts.put(bytes, "audio/wav");+ const evidence = sealSpeechEvidenceAudio({ artifact, sampleFrames: sampleFrames(bytes) });+ const need: Need = {+ id: "need:reference-video-transcript",+ capability: whisperXCapabilities.alignment,+ returns: speechEvidenceTypes.alignedTranscript,+ constraints: whisperXRequestForEvidenceAudio(evidence),+ result: "record:reference-video-transcript",+ };+ const registry = new EndpointRegistry();+ await createLocalWhisperXProvider({ instance: "whisperx.local", pool: "whisperx.local" }).install(registry);+ const resolved = registry.resolve(need);+ assert(resolved.status === "resolved", "the local WhisperX Provider does not offer word alignment");+ assert(resolved.registration.kind === "immediate", "the local WhisperX Provider answers word alignment asynchronously");+ const fulfillment = await resolved.registration.handler({+ command: { kind: "fulfill-need", id: "command:reference-video-transcript", need },+ need,+ artifacts,+ credentials: {},+ });+ assert(fulfillment.value.kind === "inline", "WhisperX returned alignment evidence by reference");+ const aligned = fulfillment.value.value as unknown as AlignedTranscriptEvidence;+ return aligned.passages.map((passage): TranscriptPassage => {+ const words = passage.words.map((word): TranscriptWord => {+ const start = seconds(word.startSample);+ const end = seconds(word.endSampleExclusive);+ return {+ text: word.text,+ ...(start === undefined ? {} : { start_seconds: start }),+ ...(end === undefined ? {} : { end_seconds: end }),+ ...(word.score === undefined ? {} : { score: word.score }),+ };+ });+ const start = seconds(passage.startSample);+ const end = seconds(passage.endSampleExclusive);+ return {+ text: words.map((word) => word.text).join(" "),+ ...(start === undefined ? {} : { start_seconds: start }),+ ...(end === undefined ? {} : { end_seconds: end }),+ words,+ };+ });+}++/**+ * The verbatim transcript is local, deterministic evidence rather than an observation: it is never+ * cached with the Gemini answers and never sent to Gemini. A machine that is not running WhisperX+ * still prepares everything else, and is told what did not answer instead of losing the preparation.+ */+export async function prepareTranscript(reference: string, videoPath: string, root: string, hasAudio: boolean, redo: boolean): Promise<Transcript> {+ if (!hasAudio) return { status: "unavailable", transcript_ref: null, word_count: 0, reason: "the reference video has no audio track" };+ try {+ const audioPath = join(root, "speech.wav");+ if (redo || await access(audioPath).then(() => false, () => true)) await extractSpeechAudio(videoPath, audioPath);+ // A refused connection says only "fetch failed"; the reader still has to learn what to start.+ const passages = await transcribeSpeechAudio(audioPath)+ .catch((error: unknown) => { throw new Error(`local WhisperX did not answer: ${reason(error)}`); });+ const transcriptPath = join(root, "transcript.json");+ const file: TranscriptFile = { reference_id: reference, audio_ref: audioPath, passages };+ await writeJson(transcriptPath, file);+ return { status: "complete", transcript_ref: transcriptPath, word_count: passages.reduce((total, passage) => total + passage.words.length, 0) };+ } catch (error) {+ return { status: "unavailable", transcript_ref: null, word_count: 0, reason: reason(error) };+ }+}diff --git a/packages/reference-video-tools/src/types.ts b/packages/reference-video-tools/src/types.tsindex 236238d7..676469ba 100644--- a/packages/reference-video-tools/src/types.ts+++ b/packages/reference-video-tools/src/types.ts@@ -1,5 +1,34 @@export type Observation = { readonly status: "complete" | "failed"; readonly text: string };+export type TranscriptWord = {+ readonly text: string;+ readonly start_seconds?: number;+ readonly end_seconds?: number;+ readonly score?: number;+};++export type TranscriptPassage = {+ readonly text: string;+ readonly start_seconds?: number;+ readonly end_seconds?: number;+ readonly words: readonly TranscriptWord[];+};++export type TranscriptFile = {+ readonly reference_id: string;+ readonly audio_ref: string;+ readonly passages: readonly TranscriptPassage[];+};++// A reference of any length has thousands of words, so the words live in their own file and the+// prepared result carries the path to them, as it does for the storyboard and the shot media.+export type Transcript = {+ readonly status: "complete" | "unavailable";+ readonly transcript_ref: string | null;+ readonly word_count: number;+ readonly reason?: string;+};+export type Shot = {readonly shot_id: string;readonly index: number;@@ -23,6 +52,7 @@ export type ReferenceState = {readonly shots: readonly Shot[];readonly storyboard_ref: string;readonly analysis_video_ref: string;+ readonly transcript?: Transcript;readonly people_and_product?: Observation;readonly voices?: Observation;readonly persistent_systems?: Observation;@@ -35,6 +65,7 @@ export type PrepareResult = {readonly video: ReferenceState["video"];readonly shots: readonly Shot[];readonly storyboard_ref: string;+ readonly transcript: Transcript;readonly people_and_product: Observation;readonly voices: Observation;readonly persistent_systems: Observation;diff --git a/packages/reference-video-tools/test/transcript.test.ts b/packages/reference-video-tools/test/transcript.test.tsnew file mode 100644index 00000000..e5e02b94--- /dev/null+++ b/packages/reference-video-tools/test/transcript.test.ts@@ -0,0 +1,106 @@+import assert from "node:assert/strict";+import test from "node:test";+import { mkdtemp, readFile, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { prepareTranscript, transcribeSpeechAudio } from "../src/transcript.js";+import type { TranscriptFile } from "../src/types.js";++const REFERENCE = "ref-fixture";++/** The canonical evidence WAV the Provider refuses to normalize a second time: 16 kHz mono s16. */+function wav(sampleFrames: number): Uint8Array {+ const bytes = new Uint8Array(44 + sampleFrames * 2);+ const view = new DataView(bytes.buffer);+ const write = (offset: number, value: string): void => {+ for (let index = 0; index < value.length; index += 1) bytes[offset + index] = value.charCodeAt(index);+ };+ write(0, "RIFF");+ view.setUint32(4, bytes.byteLength - 8, true);+ write(8, "WAVE");+ write(12, "fmt ");+ view.setUint32(16, 16, true);+ view.setUint16(20, 1, true);+ view.setUint16(22, 1, true);+ view.setUint32(24, 16_000, true);+ view.setUint32(28, 32_000, true);+ view.setUint16(32, 2, true);+ view.setUint16(34, 16, true);+ write(36, "data");+ view.setUint32(40, sampleFrames * 2, true);+ return bytes;+}++async function serving(response: unknown, run: () => Promise<void>): Promise<void> {+ const original = globalThis.fetch;+ globalThis.fetch = (async (input: RequestInfo | URL) => new Response(JSON.stringify(String(input).endsWith("/health")+ ? {+ ok: true,+ protocol: "hypit.whisperx-service@1",+ serviceVersion: "0.1.0",+ whisperxVersion: "3.8.6",+ model: "small",+ device: "cpu",+ compute: "int8",+ batchSize: 8,+ punktTabDigest: "e57f64187974277726a3417ca6f181ec5403676c717672eef6a748a7b20e0106",+ }+ : response), { headers: { "content-type": "application/json" } })) as typeof fetch;+ try { await run(); } finally { globalThis.fetch = original; }+}++test("every word carries its own start and end in seconds, not only the passage around it", async () => {+ const root = await mkdtemp(join(tmpdir(), "reference-video-transcript-"));+ const audioPath = join(root, "speech.wav");+ await writeFile(audioPath, wav(32_000));++ await serving({+ language: "en",+ segments: [{ start: 0, end: 2, words: [+ { text: "number", start: 0.1, end: 0.4, score: 0.9 },+ { text: "five", start: 1.2, end: 1.6 },+ ] }],+ }, async () => {+ const passages = await transcribeSpeechAudio(audioPath);+ assert.equal(passages.length, 1);+ assert.equal(passages[0]!.text, "number five");+ assert.deepEqual(passages[0]!.words, [+ { text: "number", start_seconds: 0.1, end_seconds: 0.4, score: 0.9 },+ { text: "five", start_seconds: 1.2, end_seconds: 1.6 },+ ], "placing an on-screen reveal needs the time of the word, not of the sentence it sits in");+ });+});++test("a complete transcript is written beside the other prepared artifacts and summarized by its word count", async () => {+ const root = await mkdtemp(join(tmpdir(), "reference-video-transcript-"));+ await writeFile(join(root, "speech.wav"), wav(32_000));++ await serving({+ language: "en",+ segments: [{ start: 0, end: 2, words: [{ text: "hello", start: 0.1, end: 0.4 }, { text: "world", start: 1.2, end: 1.6 }] }],+ }, async () => {+ const result = await prepareTranscript(REFERENCE, join(root, "reference.mp4"), root, true, false);+ assert.deepEqual(result, { status: "complete", transcript_ref: join(root, "transcript.json"), word_count: 2 });++ const file = JSON.parse(await readFile(join(root, "transcript.json"), "utf8")) as TranscriptFile;+ assert.equal(file.reference_id, REFERENCE);+ assert.equal(file.audio_ref, join(root, "speech.wav"));+ assert.equal(file.passages[0]!.words.length, 2);+ });+});++test("a WhisperX that cannot answer leaves the transcript unavailable with its reason instead of failing preparation", async () => {+ const root = await mkdtemp(join(tmpdir(), "reference-video-transcript-"));+ assert.deepEqual(+ await prepareTranscript(REFERENCE, join(root, "reference.mp4"), root, false, false),+ { status: "unavailable", transcript_ref: null, word_count: 0, reason: "the reference video has no audio track" },+ "a silent reference is prepared, not refused");++ await writeFile(join(root, "reference.mp4"), "not a video", "utf8");+ const failed = await prepareTranscript(REFERENCE, join(root, "reference.mp4"), root, true, false);+ assert.equal(failed.status, "unavailable");+ assert.equal(failed.transcript_ref, null);+ assert.equal(typeof failed.reason === "string" && failed.reason.length > 0, true,+ "the whole preparation survives, so the one thing that did not work has to say why");+});diff --git a/packages/video-cli/src/picture.ts b/packages/video-cli/src/picture.tsindex 606ae920..88d106e2 100644--- a/packages/video-cli/src/picture.ts+++ b/packages/video-cli/src/picture.ts@@ -15,7 +15,7 @@ import { createKieProvider } from "@hypit/provider-kie";* The exact model family this Distribution reaches for when the author names none.* It is a Host default, not a Core preference: `--model` replaces it outright.*/-const defaultPictureModel = "@hypit/nano-banana";+const defaultPictureModel = "@hypit/gpt-image";/** Options this command exposes, mapped onto the port names models declare for them. */const optionPorts = {diff --git a/packages/video-cli/test/cli.test.ts b/packages/video-cli/test/cli.test.tsindex 328bd64f..a77fc0a2 100644--- a/packages/video-cli/test/cli.test.ts+++ b/packages/video-cli/test/cli.test.ts@@ -81,7 +81,7 @@ test("image writes one picture file with no Source, Build, Record or Runtime Pro}if (url.includes("/api/v1/jobs/recordInfo")) {return Response.json({ code: 200, data: {- taskId: "task_image_test", model: "nano-banana-2", state: "success",+ taskId: "task_image_test", model: "gpt-image-2", state: "success",resultJson: JSON.stringify({ resultUrls: ["https://tempfile.aiquickdraw.com/paper.png"] }),} });}@@ -106,21 +106,19 @@ test("image writes one picture file with no Source, Build, Record or Runtime Proreadonly package: string; readonly model: string;readonly mediaType: string; readonly size: number; readonly path: string;};- assert.equal(machine.package, "@hypit/nano-banana");- assert.equal(machine.model, "nano-banana-2");+ assert.equal(machine.package, "@hypit/gpt-image");+ assert.equal(machine.model, "gpt-image-2");assert.equal(machine.mediaType, "image/png");assert.equal(machine.size, pictureBytes.byteLength);assert.equal(machine.path, destination);assert.deepEqual(Uint8Array.from(await readFile(destination)), pictureBytes);// The author gave one option; every other port took the model's own first value.assert.deepEqual(requests, [{- model: "nano-banana-2",+ model: "gpt-image-2-text-to-image",input: {prompt: "A sheet of warm cream laid paper, even lighting, no text.",- image_input: [],aspect_ratio: "1:1",resolution: "1K",- output_format: "png",},}]);assert.equal(calls.filter((item) => item.endsWith("/api/v1/jobs/createTask")).length, 1);diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex efb4683a..24f27104 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -225,70 +225,6 @@ importers:specifier: ^1.6.4version: 1.6.4(@algolia/[email protected])(@types/[email protected])([email protected])([email protected])([email protected])- examples/ranking-typewriter-reverse/packages/local-notebook-list:- dependencies:- '@hypit/artifact':- specifier: workspace:*- version: link:../../../../packages/artifact- '@hypit/component-kit':- specifier: workspace:*- version: link:../../../../packages/component-kit- '@hypit/composition':- specifier: workspace:*- version: link:../../../../packages/composition- '@hypit/elaborator':- specifier: workspace:*- version: link:../../../../packages/elaborator- '@hypit/markup':- specifier: workspace:*- version: link:../../../../packages/markup- '@hypit/media':- specifier: workspace:*- version: link:../../../../packages/media- '@hypit/narrative':- specifier: workspace:*- version: link:../../../../packages/narrative- '@hypit/program-space':- specifier: workspace:*- version: link:../../../../packages/program-space- '@hypit/protocol':- specifier: workspace:*- version: link:../../../../packages/protocol- '@hypit/semantic-map':- specifier: workspace:*- version: link:../../../../packages/semantic-map- '@hypit/spatial':- specifier: workspace:*- version: link:../../../../packages/spatial- '@hypit/svs':- specifier: workspace:*- version: link:../../../../packages/svs- '@hypit/temporal':- specifier: workspace:*- version: link:../../../../packages/temporal- '@hypit/text':- specifier: workspace:*- version: link:../../../../packages/text- devDependencies:- '@hypit/core':- specifier: workspace:*- version: link:../../../../packages/core- '@hypit/fonts-open':- specifier: workspace:*- version: link:../../../../packages/fonts-open- '@hypit/hyperframes':- specifier: workspace:*- version: link:../../../../packages/hyperframes- '@hypit/provider-hyperframes-local':- specifier: workspace:*- version: link:../../../../packages/provider-hyperframes-local- '@types/node':- specifier: 24.10.1- version: 24.10.1- tsx:- specifier: 4.21.0- version: 4.21.0-packages/artifact:dependencies:'@hypit/protocol':@@ -2151,6 +2087,9 @@ importers:'@google/genai':specifier: 1.52.0version: 1.52.0(@modelcontextprotocol/[email protected]([email protected]))+ '@hypit/driver-node':+ specifier: workspace:*+ version: link:../driver-node'@hypit/markup':specifier: workspace:*version: link:../markup@@ -2163,6 +2102,18 @@ importers:'@hypit/protocol':specifier: workspace:*version: link:../protocol+ '@hypit/provider-whisperx-local':+ specifier: workspace:*+ version: link:../provider-whisperx-local+ '@hypit/speech':+ specifier: workspace:*+ version: link:../speech+ '@hypit/speech-evidence':+ specifier: workspace:*+ version: link:../speech-evidence+ '@hypit/whisperx':+ specifier: workspace:*+ version: link:../whisperxtsx:specifier: 4.21.0version: 4.21.0