Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

fix: persist preview mock runs and route revisions

rpone8a5b88ef7592
diff --git a/.agents/skills/hypit/SKILL.md b/.agents/skills/hypit/SKILL.md
index 89cb5d24..8725420a 100644
--- a/.agents/skills/hypit/SKILL.md
+++ b/.agents/skills/hypit/SKILL.md
@@ -1,10 +1,16 @@
---
name: hypit
-description: Produce a complete video program from a description — a ranking, a talking head, an explainer, a short — or reconstruct one from a reference video; author, check, preview, build, inspect and retrieve Hypit/SVML projects; configure runtimes and credentials; develop missing project-local author packages; and apply native video production playbooks. Use for making a video with Hypit, the Hypit repository, SVML/SVS/SVRun authoring, reconstruction, package vocabulary, runtime operations, or video craft decisions.
+description: Produce a complete video program from a description — a ranking, a talking head, an explainer, a short — or reconstruct one from a reference video; author, check, preview, build, inspect and retrieve Hypit/SVML projects; configure runtimes and credentials; develop missing project-local author packages; and apply native video production playbooks. Use for video production with Hypit and SVML/SVS/SVRun authoring; this is not for developing the Hypit repository itself.
---
# Hypit
+> **Scope boundary:** This is a production skill for creating, reconstructing, previewing, reviewing,
+> revising and building videos with Hypit. It is **not a development skill for the Hypit repository
+> itself**. If the task is to implement, debug, test, refactor or otherwise develop Hypit packages,
+> CLIs, Studio, runtime or repository infrastructure, ignore the video-production routes and follow
+> the repository's contributor/development instructions instead.
+
**Run the route to the end without stopping.** There are exactly two things worth interrupting the
author for, and everything else is yours to decide:
@@ -84,7 +90,9 @@ the boundary and launcher selection. Read it before the first command of any rou
the independent `revision_state` route. Restore the element's role in the frozen brief, edit only
Source/Recipe/Run, invalidate the affected graph closure, and rerun deterministic gates. Revision
never invokes VLM/observer visual inspection; after the change, start Studio only when the current
- Run has no Studio session so the author can see the updated result.
+ Run has no Studio session so the author can see the updated result. This routing rule also applies
+ after a paid Build has produced the full video: revise the accepted-material Run, never the rendered
+ artifact and never by resuming either creation route.
- A syntax question about one element, or a source that already exists → read
`references/authoring.md`, then `references/quickstart.md` and the linked authoritative
docs/package READMEs. A whole video is `references/original-authoring/route.md`, not this file.
diff --git a/.agents/skills/hypit/references/original-authoring/route.md b/.agents/skills/hypit/references/original-authoring/route.md
index 334cb6fe..282d56b4 100644
--- a/.agents/skills/hypit/references/original-authoring/route.md
+++ b/.agents/skills/hypit/references/original-authoring/route.md
@@ -19,6 +19,8 @@ a reconstruction gets for free have to be decided deliberately: what the program
If a completed project receives a natural-language change, use `../revision.md` instead of restarting
this route. Revision is Source/Recipe/Run-only and deterministic; it does not invoke a VLM or visual
observer.
+This remains true after a paid Build has produced the full video: start `revision_state` against the
+accepted-material Run, never edit the rendered file or resume the creation steps.
## Checkpoint and recovery
@@ -198,10 +200,12 @@ configured to empty its window.
### 13. The Build
-**Read now:** `../studio-confirmation.md`. Before the paid gate, start Studio for the complete
-preview-mock Run, show the author the mock, and obtain explicit acceptance and cost approval. If the
-author declines, enter `../revision.md` and do not submit a Build. After acceptance and paid Build
-submission, start Studio for the accepted Run while the HyperFrames/final render runs concurrently.
+**Read now:** `../studio-confirmation.md`. Before the paid gate, call the preview-mock realizer and
+start Studio with its returned temporary `preview.svrun` (not the unresolved author Run). Show the
+complete estimate-timed mock, then obtain explicit acceptance and cost approval. If the author
+declines, enter `../revision.md` and do not submit a Build. After acceptance and paid Build
+submission, persist the accepted Build-Record Run, start Studio for that Run, and start the
+HyperFrames/final render concurrently.
Confirm credentials, the Runtime Profile, the installed packages, model limits, resolution and
Endpoint prerequisites. Run `doctor`, `check` and `plan`.
diff --git a/.agents/skills/hypit/references/preview-mock.md b/.agents/skills/hypit/references/preview-mock.md
index a42ca4cc..f4171fb2 100644
--- a/.agents/skills/hypit/references/preview-mock.md
+++ b/.agents/skills/hypit/references/preview-mock.md
@@ -7,15 +7,17 @@ The lifecycle is fixed:
```text
build.svrun → compiler-node Author/Run Graph → preview-mock realization
-→ temporary .hypit/preview/<digest>/preview.svrun
-→ mock-media local Provider materialization → Studio deterministic preview
+→ mock.svrun + mock-media local Provider materialization
+→ persisted content-addressed Artifacts + temporary .hypit/preview/<digest>/preview.svrun
+→ Studio deterministic preview
```
`realizePreviewMock({run, targets?, timing: "estimate"})` derives replacements from the compiled
Graph. It must not parse SVML dimensions, read a reference transcript, write a user Source, or emit
-absolute-path `<file>` Candidates. The temporary Run uses the existing `<fragment>` and `<satisfy>`
-syntax and contains only Author references, mock imports/declarations, satisfactions, and explicitly
-carried Run Candidates.
+absolute-path `<file>` Candidates. The realizer first persists a native mock Run and then writes a
+second temporary Run whose relative `<file>` Candidates point at the content-addressed results;
+Studio can reopen that Run in a separate process without an in-memory attachment list or a
+mock-media Provider (only local deterministic media tools may be enabled).
Mock mapping is ordinary graph substitution: image/video/audio BlobArtifact outputs use
`mock:image`, `mock:video`, and `mock:silence`; WhisperX SemanticTake outputs use the
diff --git a/.agents/skills/hypit/references/preview.md b/.agents/skills/hypit/references/preview.md
index 35e4e2cc..c169e37e 100644
--- a/.agents/skills/hypit/references/preview.md
+++ b/.agents/skills/hypit/references/preview.md
@@ -83,8 +83,9 @@ hypit-reference-video-tools render_element /path/to/project/build.svrun \
```
It compiles the Author/Run Graph once, delegates preview substitutions to `@hypit/preview-mock`,
-materializes ordinary mock Artifacts through `@hypit/mock-media`, and drives the package's deterministic
-Producers. No mock file or SemanticTake is hand-authored in the project.
+materializes ordinary mock Artifacts through `@hypit/mock-media` into the temporary preview Store, and
+drives the package's deterministic Producers from the generated `preview.svrun`. No mock file or
+SemanticTake is hand-authored in the project.
`--element` takes the element's bare id — `captions`, the `id=` the Source wrote on the element. The
command appends the output suffix itself when it looks for the track, so `--element captions.track`
@@ -123,7 +124,8 @@ restart merely because the same Run's SVML/SVS changed.
```bash
cd /path/to/project
-hypit-studio --run build.svrun --runtime hypit.runtime.json &
+# Start Studio with the persisted previewRun returned by realizePreviewMock.
+hypit-studio --run .hypit/preview/<digest>/preview.svrun --runtime hypit.runtime.json &
```
If another Studio process is already using a different Run or startup parameters, stop that process
diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.md
index fee8d739..495f9161 100644
--- a/.agents/skills/hypit/references/reconstruction/route.md
+++ b/.agents/skills/hypit/references/reconstruction/route.md
@@ -13,6 +13,8 @@ Those belong to the Build the author starts deliberately, after reading what was
Seeing the reconstruction is what that Build is for. What is settled here is that the graph traces,
which is the part a Build cannot repair. The route then pauses at the Studio confirmation handoff
before any paid Build; after explicit acceptance it may proceed with the Runtime Build lifecycle.
+Once the paid Build has produced the accepted full video, any new natural-language change starts
+`../revision.md` from that completed Run; never continue this creation route or edit the rendered file.
If the project is already complete and the author asks for a natural-language change, stop following
this creation route and read `../revision.md`. Revision edits Source/Recipe/Run and reruns deterministic
@@ -299,6 +301,11 @@ hypit-reference-video-tools preview_check /path/to/project/build.svrun
generations rather than performing them is the state every reconstruction is in when its sources are
first written. This gate is not bounded by the round's attempt ceilings.
+### 17. Create the comparison plan
+
+Run `reconstruction_check` once to persist the element/window plan. Do not invent a render list from
+the Source; the check's plan is the durable handoff to the comparison round.
+
---
## Phase 4 — The comparison round
@@ -367,19 +374,32 @@ drawing element passes with nothing to require.
**Done when:** `"passed": true`.
-### 24. Studio confirmation and paid handoff
-
-**Read now:** `../studio-confirmation.md`. Before any paid Build, start Studio for the complete
-preview-mock Run, show it to the author, and obtain explicit acceptance and cost approval. If the
-author declines, enter `../revision.md` and do not Build. After acceptance, start Studio for the
-accepted Run while the HyperFrames/final render proceeds concurrently.
-
-After acceptance, continue with `../runtime.md` for the approved paid Build and retrieval lifecycle.
-
----
-
### 23. Apply the author's requested change
Read what you wrote and change it to what they asked for at the start. The identity of each recurring
person and product is already a single anchor, because `../playbooks/craft/persona-and-audio.md` and
`../playbooks/craft/visual-continuity.md` required that while you were writing.
+
+If the author requests a change after seeing the preview, leave this route and follow
+`../revision.md`; do not pay or Build a source that has not passed the final deterministic gate.
+
+### 24. Re-run the final deterministic gate
+
+After any requested change (or when there was none), run `reconstruction_check` again and require
+`passed: true`. This is the last source/graph gate before the paid handoff.
+
+### 25. Studio confirmation and paid handoff
+
+**Read now:** `../studio-confirmation.md`. Realize the preview-mock Run first, then start Studio with
+the returned temporary `preview.svrun` (never the original unresolved Run), show the complete
+estimate-timed mock, and obtain explicit acceptance and cost approval. If the author declines, enter
+`../revision.md` and do not Build. Once accepted, submit the paid Build and persist its accepted
+Build-Record Run; start Studio for that accepted Run while the HyperFrames/final render proceeds
+concurrently.
+
+After acceptance, continue with `../runtime.md` for the approved paid Build and retrieval lifecycle.
+
+When the accepted full video is available, a later request such as moving an element or raising
+captions is a new revision request. Start `revision_state` against the accepted-material Run and
+follow `../revision.md`; after its deterministic gates, Studio may hot-reload (or be started for the
+Run if none is running), but Revision still performs no VLM/visual review.
diff --git a/.agents/skills/hypit/references/studio-confirmation.md b/.agents/skills/hypit/references/studio-confirmation.md
index 9a00f2fb..a67620e0 100644
--- a/.agents/skills/hypit/references/studio-confirmation.md
+++ b/.agents/skills/hypit/references/studio-confirmation.md
@@ -7,12 +7,19 @@ VLM review and it does not replace the route's mechanical checks.
After the route-specific final check passes, but before submitting any paid Build:
-1. Start Hypit Studio for the current `build.svrun` and give the author its URL.
-2. Let Studio show the complete program through the normal SVRun-native preview path:
- `compiler-node Graph → preview-mock → mock-media → temporary preview.svrun → Studio`.
-3. Tell the author this is an estimate-timed, preview-only mock and ask whether the structure and
+1. Run `realizePreviewMock({ run: "<project>/build.svrun", timing: "estimate" })`. It writes a
+ durable `.hypit/preview/<digest>/mock.svrun` (the native mock materialization Run), its
+ content-addressed Artifacts, and a second `preview.svrun` whose relative file Candidates point
+ at those results.
+2. Start Hypit Studio with that returned `previewRun` path and give the author its URL. Studio can
+ therefore be started as a separate process and reopen the same bytes; it does not depend on an
+ in-memory attachment list or a mock-media endpoint (Studio may use the local FFmpeg endpoint for
+ deterministic inspect/normalize operations).
+3. Let Studio show the complete program through the normal SVRun-native preview path:
+ `compiler-node Graph → mock.svrun/mock-media → persisted Artifacts → preview.svrun → Studio`.
+4. Tell the author this is an estimate-timed, preview-only mock and ask whether the structure and
intended result are acceptable for paid generation.
-4. Do not submit `hypit build` until the author explicitly accepts and confirms the cost.
+5. Do not submit `hypit build` until the author explicitly accepts and confirms the cost.
If the author does not accept, do not Build. Capture the requested change and enter `revision.md`.
Revision edits Source/Recipe/Run and reruns deterministic gates; it does not ask an agent or VLM to
@@ -20,12 +27,18 @@ judge the picture.
## After the paid Build
-Once the author has accepted and the paid Build is submitted/accepted, start Studio for the same Run
-to show the complete program using the accepted material. Start the HyperFrames/final render at the
-same time; the render must not wait for the author to finish looking at Studio. Studio is a live,
+Once the author has accepted and the paid Build is submitted/accepted, create/persist a derived Run
+that selects the accepted Build Records (the same `<build-record>`/`<satisfy>` mechanism documented in
+`runtime.md`), then start Studio for that accepted-material Run. Start the HyperFrames/final render at
+the same time; the render must not wait for the author to finish looking at Studio. Studio is a live,
read-only presentation of the current Run while the render proceeds. Report render/build status and
the Studio URL independently.
+After that full video is delivered, any new natural-language change is routed to
+`revision_state start --run <accepted-material-run>` and `revision.md`. It is not a second visual
+review loop and it never edits the rendered artifact; the revision updates Source/Recipe/Run and
+reruns only the deterministic gates before the next Studio handoff or paid Build confirmation.
+
## After a revision
When a user-requested revision completes its deterministic gates, preserve a running Studio session
diff --git a/packages/preview-mock/package.json b/packages/preview-mock/package.json
index 04d61f7e..94710154 100644
--- a/packages/preview-mock/package.json
+++ b/packages/preview-mock/package.json
@@ -8,6 +8,7 @@
"hypit": { "activation": "./src/activation.ts" },
"dependencies": {
"@hypit/artifact": "workspace:*",
+ "@hypit/artifact-store-fs": "workspace:*",
"@hypit/compiler-node": "workspace:*",
"@hypit/driver-node": "workspace:*",
"@hypit/mock-media": "workspace:*",
diff --git a/packages/preview-mock/src/materialize.ts b/packages/preview-mock/src/materialize.ts
index 8bd63877..989b1ee9 100644
--- a/packages/preview-mock/src/materialize.ts
+++ b/packages/preview-mock/src/materialize.ts
@@ -3,9 +3,24 @@ import type { BlobRef } from "@hypit/protocol";
import { MemoryArtifactStore, EndpointRegistry } from "@hypit/driver-node";
import { createLocalMediaProvider } from "@hypit/provider-media-local";
import { mockMediaCapabilities } from "@hypit/mock-media";
+type ArtifactStore = {
+ readonly get: (digest: BlobRef["digest"]) => Promise<Uint8Array | undefined>;
+ readonly put: (bytes: Uint8Array, mediaType: string) => Promise<BlobRef>;
+ readonly has: (digest: BlobRef["digest"]) => Promise<boolean>;
+};
-export async function materializeMockNeed(input: { readonly capability: typeof mockMediaCapabilities[keyof typeof mockMediaCapabilities]; readonly constraints: unknown }): Promise<{ readonly artifact: BlobRef; readonly attachment: ArtifactAttachment }> {
- const artifacts = new MemoryArtifactStore();
+/**
+ * Execute one mock Need with the local Provider. Callers may provide the
+ * project preview ArtifactStore so the resulting bytes survive the process
+ * which created the temporary Run (Studio is deliberately a separate
+ * process). The in-memory default is retained for small library callers.
+ */
+export async function materializeMockNeed(input: {
+ readonly capability: typeof mockMediaCapabilities[keyof typeof mockMediaCapabilities];
+ readonly constraints: unknown;
+ readonly artifacts?: ArtifactStore;
+}): Promise<{ readonly artifact: BlobRef; readonly attachment: ArtifactAttachment }> {
+ const artifacts = input.artifacts ?? new MemoryArtifactStore();
const registry = new EndpointRegistry();
await createLocalMediaProvider({}).install(registry);
const registration = registry.resolve({ id: "mock", capability: input.capability, returns: { module: { name: "@hypit/artifact", version: "1" }, name: "BlobArtifact" }, constraints: input.constraints as never, result: "mock" });
@@ -13,5 +28,14 @@ export async function materializeMockNeed(input: { readonly capability: typeof m
const result = await registration.registration.handler({ command: { kind: "fulfill-need", id: "mock", need: { id: "mock", capability: input.capability, returns: registration.registration.returns, constraints: input.constraints as never, result: "mock" } }, need: { id: "mock", capability: input.capability, returns: registration.registration.returns, constraints: input.constraints as never, result: "mock" }, artifacts, credentials: {} });
if (result.value.kind !== "blob") throw new Error("Mock Provider returned a non-Artifact value");
const artifact = result.value;
- return { artifact, attachment: { artifact, open: async () => (async function* () { const bytes = await artifacts.get(artifact.digest); if (bytes !== undefined) yield bytes; })() } };
+ return {
+ artifact,
+ attachment: {
+ artifact,
+ open: async () => (async function* () {
+ const bytes = await artifacts.get(artifact.digest);
+ if (bytes !== undefined) yield bytes;
+ })(),
+ },
+ };
}
diff --git a/packages/preview-mock/src/realizer.ts b/packages/preview-mock/src/realizer.ts
index 217296b3..eed58f96 100644
--- a/packages/preview-mock/src/realizer.ts
+++ b/packages/preview-mock/src/realizer.ts
@@ -1,6 +1,6 @@
import { createHash } from "node:crypto";
import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
import type { ArtifactAttachment } from "@hypit/workspace";
import type { CompiledGraph, TypedRecord } from "@hypit/protocol";
import { findMockTargets } from "./graph.js";
@@ -8,10 +8,25 @@ import { deriveGeometry } from "./geometry.js";
import { previewRunSource } from "./run-source.js";
import { materializeMockNeed } from "./materialize.js";
import { mockMediaCapabilities } from "@hypit/mock-media";
+import { FileArtifactStore } from "@hypit/artifact-store-fs";
export type PreviewMockTiming = "estimate";
export type PreviewMockRequest = { readonly run: string; readonly targets?: readonly string[]; readonly timing?: PreviewMockTiming; readonly cacheRoot?: string; readonly graph?: CompiledGraph; readonly records?: readonly TypedRecord[]; readonly author?: string; readonly aliases?: ReadonlyMap<string, string> };
-export type PreviewMockResult = { readonly run: string; readonly root: string; readonly previewRun: string; readonly attachments: readonly ArtifactAttachment[]; readonly mocked: readonly { output: string; candidate: string; kind: "image" | "video" | "audio" | "semantic-take" }[]; readonly timingBasis: "estimate" };
+export type PreviewMockResult = {
+ readonly run: string;
+ readonly root: string;
+ /** The persisted Run containing the native mock fragments. */
+ readonly mockRun: string;
+ /** The persisted Run consumed by Studio; its mock outputs are file Candidates. */
+ readonly previewRun: string;
+ readonly attachments: readonly ArtifactAttachment[];
+ readonly mocked: readonly { output: string; candidate: string; kind: "image" | "video" | "audio" | "semantic-take" }[];
+ readonly timingBasis: "estimate";
+};
+
+function artifactRelativePath(root: string, digest: string): string {
+ return `./artifacts/sha256/${digest.split(":")[1]!.slice(0, 2)}/${digest.split(":")[1]!}`;
+}
export async function realizePreviewMock(input: PreviewMockRequest): Promise<PreviewMockResult> {
const run = resolve(input.run);
@@ -22,8 +37,10 @@ export async function realizePreviewMock(input: PreviewMockRequest): Promise<Pre
const root = input.cacheRoot ?? join(dirname(run), ".hypit", "preview", createHash("sha256").update(source).digest("hex").slice(0, 16));
await mkdir(root, { recursive: true });
const previewRun = join(root, "preview.svrun");
+ const mockRun = join(root, "mock.svrun");
await writeFile(previewRun, source, "utf8");
- return { run, root, previewRun, attachments: [], mocked: [], timingBasis: "estimate" };
+ await writeFile(mockRun, source, "utf8");
+ return { run, root, mockRun, previewRun, attachments: [], mocked: [], timingBasis: "estimate" };
}
const alias = (ref: string): string => input.aliases?.get(ref) ?? ref;
const rawTargets = findMockTargets(input.graph, input.targets, input.records);
@@ -46,19 +63,31 @@ export async function realizePreviewMock(input: PreviewMockRequest): Promise<Pre
})).digest("hex").slice(0, 16));
await mkdir(root, { recursive: true });
const previewRun = join(root, "preview.svrun");
- const preserved = [...source.matchAll(/^\s*<(?:file|value|build-record)\b[^>]*\/?>\s*$/gmu)]
+ const mockRun = join(root, "mock.svrun");
+ const artifactStore = new FileArtifactStore(join(root, "artifacts"));
+ const preserved = [...source.matchAll(/^\s*<(?:file|value|build-record)\b[^>]*\/?>(?:\s*)$/gmu)]
.map((match) => (match[0] ?? "").trim())
- .filter((line) => !/from="\//u.test(line));
- const generated = previewRunSource(resolve(dirname(run), author), previewRun, selectedTargets, geometry, targets);
+ .map((line) => line.replace(/\bfrom="([^"]+)"/u, (_whole, from: string) => {
+ // Rebase carried Run assets against the temporary Run directory. The
+ // generated source never contains an absolute Candidate path, even when
+ // the original Run used one.
+ const absolute = resolve(dirname(run), from);
+ const relativePath = relative(root, absolute).replaceAll("\\", "/");
+ return `from="${relativePath.startsWith(".") ? relativePath : `./${relativePath}`}"`;
+ }));
+ // Keep the native mock Run as a durable audit/debug artifact. Its Needs are
+ // fulfilled by the local mock Provider below; Studio then opens the second
+ // Run, whose relative file Candidates point at those content-addressed
+ // results and therefore require no Provider endpoint.
+ const generatedMock = previewRunSource(resolve(dirname(run), author), mockRun, selectedTargets, geometry, targets);
+ await writeFile(mockRun, generatedMock, "utf8");
const mockedOutputs = new Set(targets.map((item) => item.output));
const carriedSatisfactions = [...source.matchAll(/^\s*<satisfy\s+output="([^"]+)"[^>]*\/?>\s*$/gmu)]
.filter((match) => !mockedOutputs.has(match[1] ?? ""))
.map((match) => ` ${(match[0] ?? "").trim()}`);
- const withCarried = generated.replace("</svrun>", `${carriedSatisfactions.join("\n")}\n</svrun>`);
- const carried = preserved.map((line) => ` ${line}`).join("\n");
- await writeFile(previewRun, withCarried.replace(" <target", `${carried}${carried.length === 0 ? "" : "\n"} <target`), "utf8");
const attachments: ArtifactAttachment[] = [];
const attached = new Set<string>();
+ const files = new Map<string, { readonly id: string; readonly from: string; readonly mediaType: string }>();
for (const target of targets) {
if (target.kind === "semantic-take") continue;
const capability = target.kind === "image" ? mockMediaCapabilities.image
@@ -66,13 +95,35 @@ export async function realizePreviewMock(input: PreviewMockRequest): Promise<Pre
const constraints = target.kind === "image"
? { width: geometry.width, height: geometry.height, color: "#9AA0A6" }
: target.kind === "video"
- ? { width: geometry.width, height: geometry.height, frameRate: { numerator: 30, denominator: 1 }, frameCount: 30, color: "#9AA0A6", audio: "silence" }
+ // A mock video needs enough frames for the estimate-timed SemanticTake
+ // to place every token. The real duration remains owned by the graph;
+ // this conservative preview domain avoids squeezing long Scripts into
+ // the old 30-frame placeholder.
+ ? { width: geometry.width, height: geometry.height, frameRate: { numerator: 30, denominator: 1 }, frameCount: 300, color: "#9AA0A6", audio: "silence" }
: { sampleRate: 48_000, channels: 2, sampleFrames: 48_000 };
- const materialized = await materializeMockNeed({ capability, constraints });
+ const materialized = await materializeMockNeed({ capability, constraints, artifacts: artifactStore });
if (!attached.has(materialized.artifact.digest)) {
attached.add(materialized.artifact.digest);
attachments.push(materialized.attachment);
}
+ const candidateId = `mock-file-${files.size}`;
+ files.set(target.output, {
+ id: candidateId,
+ from: artifactRelativePath(root, materialized.artifact.digest),
+ mediaType: materialized.artifact.mediaType,
+ });
}
- return { run, root, previewRun, attachments, mocked: targets.map((item, index) => ({ output: item.output, candidate: `mock-${index}.${item.kind === "audio" ? "audio" : item.kind}`, kind: item.kind })), timingBasis: "estimate" };
+ const generated = previewRunSource(resolve(dirname(run), author), previewRun, selectedTargets, geometry, targets, files);
+ const withCarried = generated.replace("</svrun>", `${carriedSatisfactions.join("\n")}\n</svrun>`);
+ const carried = preserved.map((line) => ` ${line}`).join("\n");
+ await writeFile(previewRun, withCarried.replace(" <target", `${carried}${carried.length === 0 ? "" : "\n"} <target`), "utf8");
+ return {
+ run, root, mockRun, previewRun, attachments,
+ mocked: targets.map((item, index) => ({
+ output: item.output,
+ candidate: files.get(item.output)?.id ?? `mock-${index}.${item.kind === "audio" ? "audio" : item.kind}`,
+ kind: item.kind,
+ })),
+ timingBasis: "estimate",
+ };
}
diff --git a/packages/preview-mock/src/run-source.ts b/packages/preview-mock/src/run-source.ts
index 6ef5620d..c4648031 100644
--- a/packages/preview-mock/src/run-source.ts
+++ b/packages/preview-mock/src/run-source.ts
@@ -1,7 +1,20 @@
import { relative, dirname } from "node:path";
import type { MockTarget } from "./graph.js";
-export function previewRunSource(author: string, runFile: string, targets: readonly string[], geometry: { width: number; height: number }, mocks: readonly MockTarget[]): string {
+export type PreviewMockFile = {
+ readonly id: string;
+ readonly from: string;
+ readonly mediaType: string;
+};
+
+export function previewRunSource(
+ author: string,
+ runFile: string,
+ targets: readonly string[],
+ geometry: { width: number; height: number },
+ mocks: readonly MockTarget[],
+ files: ReadonlyMap<string, PreviewMockFile> = new Map(),
+): string {
const authorRef = relative(dirname(runFile), author).replaceAll("\\", "/");
const declarations: string[] = [];
const satisfactions: string[] = [];
@@ -10,6 +23,12 @@ export function previewRunSource(author: string, runFile: string, targets: reado
? ` <import from="@hypit/semantic-take-estimate@1" as="estimate"/>\n`
: "";
for (const [index, mock] of mocks.entries()) {
+ const file = files.get(mock.output);
+ if (file !== undefined) {
+ declarations.push(` <file id="${file.id}" type="@hypit/artifact@1#BlobArtifact" from="${file.from}" media-type="${file.mediaType}"/>`);
+ satisfactions.push(` <satisfy output="${mock.output}" candidate="${file.id}"/>`);
+ continue;
+ }
const fragment = mock.kind === "semantic-take" ? "estimate:semantic-take"
: mock.kind === "image" ? "mock:image" : mock.kind === "video" ? "mock:video" : "mock:silence";
const id = `mock-${index}`;
diff --git a/packages/reference-video-tools/src/authoring.ts b/packages/reference-video-tools/src/authoring.ts
index 1fbcf178..970b0455 100644
--- a/packages/reference-video-tools/src/authoring.ts
+++ b/packages/reference-video-tools/src/authoring.ts
@@ -18,11 +18,11 @@ import { openStudioArchive } from "@hypit/studio/src/archive.js";
import { loadStudioDomain } from "@hypit/studio/src/domain.js";
import type { Preview } from "@hypit/studio/src/programme.js";
import { preview } from "@hypit/studio/src/programme.js";
-import { EndpointRegistry } from "@hypit/driver-node";
-import { createLocalMediaProvider } from "@hypit/provider-media-local";
import { loadStudioRun } from "@hypit/studio/src/run.js";
import { inspectStudioRun } from "@hypit/studio/src/studio-preflight.js";
import { realizePreviewMock } from "@hypit/preview-mock";
+import { EndpointRegistry } from "@hypit/driver-node";
+import { createLocalMediaProvider } from "@hypit/provider-media-local";
import { assert, ensureDir } from "./media.js";
import type { TranscriptFile } from "./types.js";
@@ -611,8 +611,6 @@ export async function renderElement(input: RenderElementInput): Promise<Record<s
const previewArchive = await openStudioArchive(undefined, packageRoot, projectRoot, distributionPackageRoot);
const loadedPreview = await loadStudioRun({ run: previewMock.previewRun, domain: previewDomain, registry: previewRegistry, ...(previewArchive === undefined ? {} : { archive: previewArchive }) });
const previewRun = { ...loadedPreview, attachments: [...loadedPreview.attachments, ...previewMock.attachments] };
- const mockEndpoints = new EndpointRegistry();
- await createLocalMediaProvider({}).install(mockEndpoints);
const inspection = inspectStudioRun(previewRegistry, previewRun.source, previewRun, new Set([
"@hypit/mock-media@1#render-mock-image",
"@hypit/mock-media@1#render-mock-video",
@@ -620,6 +618,8 @@ export async function renderElement(input: RenderElementInput): Promise<Record<s
"@hypit/media-pipeline@1#inspect-media",
"@hypit/media-pipeline@1#normalize-media",
]));
+ const deterministicEndpoints = new EndpointRegistry();
+ await createLocalMediaProvider({}).install(deterministicEndpoints);
built = await preview({
source: previewRun.source,
run: previewRun,
@@ -628,7 +628,7 @@ export async function renderElement(input: RenderElementInput): Promise<Record<s
compositionRef: inspection.filmComposition,
projections: inspection.projections,
...(previewArchive === undefined ? {} : { archive: previewArchive }),
- endpoints: mockEndpoints,
+ endpoints: deterministicEndpoints,
});
programFrames = Math.max(1, ...built.anchors.values());
frameOfToken = built.tokens.map((token) => ({ frame: built.anchors.get(token.startAnchorId) ?? 0, end: built.anchors.get(token.endAnchorId) ?? 0 }));
diff --git a/packages/reference-video-tools/src/revision-state.ts b/packages/reference-video-tools/src/revision-state.ts
index ca727e34..b8d3185d 100644
--- a/packages/reference-video-tools/src/revision-state.ts
+++ b/packages/reference-video-tools/src/revision-state.ts
@@ -22,6 +22,11 @@ export const REVISION_STEPS: readonly RevisionStep[] = [
"preview-rendered", "review-complete", "final-checked", "revision-complete", "build-complete",
];
+// Revision is intentionally source-and-gate only. A preview render or VLM
+// review is never a prerequisite, and a paid Build is conditional on the
+// impact of the change and a fresh user approval.
+const REQUIRED_REVISION_STEPS = new Set<number>([1, 2, 3, 4, 5, 8, 9]);
+
export type RevisionState = {
readonly version: 1;
readonly project_root: string;
@@ -70,7 +75,9 @@ export function revisionStatePath(projectRoot: string): string {
function nextUncompleted(completed: readonly number[]): number {
const done = new Set(completed);
- for (let step = 1; step <= REVISION_STEPS.length; step += 1) if (!done.has(step)) return step;
+ for (let step = 1; step <= REVISION_STEPS.length; step += 1) {
+ if (REQUIRED_REVISION_STEPS.has(step) && !done.has(step)) return step;
+ }
return REVISION_STEPS.length + 1;
}
diff --git a/packages/studio/package.json b/packages/studio/package.json
index 295c9500..9aba4ab2 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -45,6 +45,7 @@
"@hypit/video-cli": "workspace:*",
"@hypit/workspace": "workspace:*",
"@hypit/workspace-fs-node": "workspace:*",
+ "@hypit/provider-media-local": "workspace:*",
"vite": "5.4.21"
}
}
diff --git a/packages/studio/src/server.ts b/packages/studio/src/server.ts
index 6c8fdcae..6a4343e8 100644
--- a/packages/studio/src/server.ts
+++ b/packages/studio/src/server.ts
@@ -6,6 +6,7 @@ import { dirname, isAbsolute, relative, resolve } from "node:path";
import type { Plugin, ViteDevServer } from "vite";
import type { StudioTemporalInstantProjection } from "@hypit/studio-adapter";
+import type { EndpointRegistry } from "@hypit/driver-node";
import type { StudioArchive } from "./archive.js";
import type { ServedFile } from "./compile.js";
@@ -27,6 +28,7 @@ export type StudioPluginOptions = {
readonly registry: StudioCompanionRegistry;
readonly workspaceRoot: string;
readonly archive?: StudioArchive;
+ readonly endpoints?: EndpointRegistry;
};
function json(response: import("node:http").ServerResponse, status: number, value: unknown): void {
@@ -108,6 +110,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
domain: options.domain,
registry: options.registry,
...(options.archive === undefined ? {} : { archive: options.archive }),
+ ...(options.endpoints === undefined ? {} : { endpoints: options.endpoints }),
});
currentSource = run.authorSource;
watchSource(options.runPath);
diff --git a/packages/studio/src/session.ts b/packages/studio/src/session.ts
index 58d3e311..10f0560d 100644
--- a/packages/studio/src/session.ts
+++ b/packages/studio/src/session.ts
@@ -1,5 +1,6 @@
import { existsSync, readFileSync } from "node:fs";
import { relative } from "node:path";
+import type { EndpointRegistry } from "@hypit/driver-node";
import { markupAuthorFrontendId } from "@hypit/markup";
import { svsFrontendId } from "@hypit/svs";
@@ -60,6 +61,8 @@ export async function readStudioSession(input: {
readonly revision: number;
readonly sourcePath?: string;
readonly workspaceRoot: string;
+ /** Preview-only local deterministic media endpoints (never paid/external Providers). */
+ readonly endpoints?: EndpointRegistry;
}): Promise<StudioSession> {
const source = input.run.source;
const inspection = inspectStudioRun(input.registry, source, input.run);
@@ -75,6 +78,7 @@ export async function readStudioSession(input: {
compositionRef: inspection.filmComposition,
projections: inspection.projections,
...(input.archive === undefined ? {} : { archive: input.archive }),
+ ...(input.endpoints === undefined ? {} : { endpoints: input.endpoints }),
});
const rendered = renderPreview({
composition: built.composition,
diff --git a/packages/studio/start.ts b/packages/studio/start.ts
index f42376f2..f4127b51 100644
--- a/packages/studio/start.ts
+++ b/packages/studio/start.ts
@@ -4,6 +4,8 @@ import { fileURLToPath } from "node:url";
import { createServer } from "vite";
import { findRuntimeProfile } from "@hypit/cli";
import { videoCliDistribution } from "@hypit/video-cli";
+import { EndpointRegistry } from "@hypit/driver-node";
+import { createLocalMediaProvider } from "@hypit/provider-media-local";
import { openStudioArchive } from "./src/archive.js";
import { loadStudioCompanionRegistry } from "./src/companion-profile.js";
@@ -47,6 +49,7 @@ const invokedFrom = process.env.INIT_CWD ?? process.cwd();
const runArgument = values.get("run");
if (runArgument === undefined || runArgument.trim().length === 0) usage("Missing --run");
const runPath = resolve(invokedFrom, runArgument);
+const previewOnly = /[\\/]\.hypit[\\/]preview[\\/]/u.test(runPath);
const packageRootArgument = values.get("package-root");
const workspaceArgument = values.get("workspace");
const requestedWorkspaceRoot = workspaceArgument === undefined
@@ -90,8 +93,20 @@ try {
throw error;
}
const source = run.authorSource;
+// A preview Run has already persisted all mock media as relative file
+// Candidates, but deterministic inspect/normalize/render-media Producers still
+// need the local FFmpeg endpoint. This is not a paid or external Provider and
+// is never installed for ordinary production Runs.
+const endpoints = previewOnly ? new EndpointRegistry() : undefined;
+if (endpoints !== undefined) await createLocalMediaProvider({}).install(endpoints);
try {
- inspectStudioRun(registry, run.source, run);
+ inspectStudioRun(registry, run.source, run, previewOnly ? new Set([
+ "@hypit/media-pipeline@1#inspect-media",
+ "@hypit/media-pipeline@1#normalize-media",
+ "@hypit/media-pipeline@1#extract-audio",
+ "@hypit/media-pipeline@1#render-audio",
+ "@hypit/media-pipeline@1#mux",
+ ]) : undefined);
} catch (error) {
await archive?.close();
throw error;
@@ -114,6 +129,7 @@ const server = await createServer({
domain,
registry,
...(archive === undefined ? {} : { archive }),
+ ...(endpoints === undefined ? {} : { endpoints }),
})],
});
await server.listen();
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 10c86f77..65f08faf 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1743,6 +1743,9 @@ importers:
'@hypit/artifact':
specifier: workspace:*
version: link:../artifact
+ '@hypit/artifact-store-fs':
+ specifier: workspace:*
+ version: link:../artifact-store-fs
'@hypit/compiler-node':
specifier: workspace:*
version: link:../compiler-node
@@ -2862,6 +2865,9 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ '@hypit/provider-media-local':
+ specifier: workspace:*
+ version: link:../provider-media-local
'@hypit/ranking-studio':
specifier: workspace:*
version: link:../ranking-studio