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 reconstruction route tooling gaps (#124)

rponeawa1df04578100f
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index 4d3770f6..fe5d693b 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -275,6 +275,35 @@ is not bounded by the round's attempt ceiling:
hypit-reference-video-tools preview_check path/to/build.svrun
```
+If a mandatory gate itself appears defective, do not read or modify Distribution source and do not
+silently continue. Record the exact command, complete error, project/package/run digest and the
+reason the failure is attributable to the gate in a durable waiver evidence file:
+
+```json
+{
+ "waived": true,
+ "gate": "package_ready",
+ "diagnosis": "validator selected a transitive package instead of the project package",
+ "command": "validate_local_author_packages --run build.svrun",
+ "error": "<complete error>",
+ "package_digest": "<sha256>",
+ "run_digest": "<sha256>"
+}
+```
+
+Checkpoint that evidence as a controlled waiver (or use `blocked` when no maintainer decision is
+available):
+
+```bash
+hypit-reference-video-tools route_state checkpoint --project-root <project> --route <route> \
+ --step package-ready --status complete --artifacts '{"package_ready":".hypit/evidence/gate-waiver.json"}' \
+ --error "<exact gate error>" --decision "gate waiver recorded with reproducible diagnosis"
+```
+
+The waiver is visible in route state and remains subject to maintainer review; it preserves the
+evidence without weakening package boundaries. Use `--status blocked` instead when continuation is
+not explicitly authorized, and resume only after the gate is fixed or a decision is recorded.
+
It takes the Run Source, not the `.svml`. `preview.md` says why this spelling rather than the
`hypit-preview-check` bin: the subcommand honours `--package-root`, which is what a project-local
package needs when the Run is not at the project root. A pass here means the graph reaches a Film and
diff --git a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
index d6ae9d02..87635b8b 100644
--- a/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
+++ b/.agents/skills/hypit/references/playbooks/craft/generated-dependencies.md
@@ -252,10 +252,11 @@ fix.
last left off.
- **One edge is spoken and the other is decided elsewhere.** `@id!` marks a Moment — a point, not a
range, right-absorbing at the next word's start, `~@id!` left-absorbing at the previous word's end.
- Give the element the span it actually occupies and let the Moment cut it: `during="program"
- until={story.moment.X}` runs from the start of the program to that word, and `at={story.moment.X}`
- places a single arrival there. A Deck that stacks cards as they are named and clears on a word
- reads this way.
+ Give the element the span it actually occupies and let the Moment cut it. The accepted spelling for
+ a window from the program start to that Moment is `start="program.start" end="moment.cue"
+ moment={story.moment.X}`; `at={story.moment.X}` places a single arrival there. A Deck that stacks
+ cards as they are named and clears on a word reads this way. `during="program" until={...}` is not
+ a valid temporal projection.
A Selection is free to open in one Segment and close in another. Each end records its own Segment,
and nothing closes it at the boundary — the only refusal is `SCRIPT_SELECTION_UNCLOSED`, raised after
diff --git a/.agents/skills/hypit/references/reconstruction/route.md b/.agents/skills/hypit/references/reconstruction/route.md
index ad836e4b..64d046c8 100644
--- a/.agents/skills/hypit/references/reconstruction/route.md
+++ b/.agents/skills/hypit/references/reconstruction/route.md
@@ -151,6 +151,18 @@ for them again. Ask only for a credential that is absent or invalid after both `
and this machine does not hold is named, and the route stops there. The Vertex pair is the one
exception: it selects an observer rather than blocking one, and step 5 owns it.
+Create the project's `hypit.runtime.json` now with at least the local media and WhisperX endpoints,
+then select and start it before reference preparation:
+
+```bash
+hypit runtime use hypit.runtime.json
+hypit runtime up
+```
+
+Step 15 completes the same Profile with every capability reached by the authored Source; it does not
+create the first Profile after transcription has already needed one. Checkpoint `environment` only
+after this preliminary Profile and the selected credentials are ready.
+
### 4. Read the observer question
**Read now:** `observers.md`, down to and including "Say which path is running" — the cost of each
@@ -278,11 +290,11 @@ If no gap remains, remove unused project-owned package directories.
## Phase 3 — Author, check, wire
-### 15. Write the four files
+### 15. Write the sources and complete the Runtime Profile
-`main.svml`, `recipes.svs`, `build.svrun`, `hypit.runtime.json`. 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`.
+Write `main.svml`, `recipes.svs` and `build.svrun`, then extend the existing `hypit.runtime.json` with
+every capability those Sources reach. The Runtime Profile is part of the deliverable: without it the
+first thing the author meets is `RUNTIME_CAPABILITY_UNBOUND`.
Now persist the Run-scoped half of the frozen vocabulary decision. This completes
`vocabulary-checked` only when `.hypit/component-fit.json` remains valid:
diff --git a/.agents/skills/hypit/references/runtime.md b/.agents/skills/hypit/references/runtime.md
index c1f2c668..26374f45 100644
--- a/.agents/skills/hypit/references/runtime.md
+++ b/.agents/skills/hypit/references/runtime.md
@@ -10,10 +10,11 @@ first thing they meet is `RUNTIME_CAPABILITY_UNBOUND`, and the work of discoveri
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.
+Start from the Runtime Profile template in `docs/guide/runtime.md` (the repository does not ship a
+canonical `examples/*/hypit.runtime.json`). 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.
@@ -74,6 +75,10 @@ Studio viewing.
Use `check` during authoring. `plan` works without a Runtime as a graph-only operation; with the
project's selected Runtime it performs a cheap, read-only preflight over only unsatisfied Needs and
returns non-zero when that slice is not ready. It never installs, starts or contacts a remote Store.
+`hypit check <run> --json` and `hypit plan <run> --json` expose Provider-free `estimate:Speech`
+values under `deterministic_durations`; after execution, `hypit inspect <build> --json` reports the
+accepted `SpeechDuration` Records. Read those seconds directly when reviewing generated take length
+or cost instead of probing a mock media file.
After Runtime package selection changes, run `runtime up`: this is the explicit provisioning
boundary for machine npm dependencies, Managed Programs and the detached Worker. Use `doctor` for
diff --git a/.agents/skills/hypit/references/studio-confirmation.md b/.agents/skills/hypit/references/studio-confirmation.md
index 0b5c4b4c..fc94eb21 100644
--- a/.agents/skills/hypit/references/studio-confirmation.md
+++ b/.agents/skills/hypit/references/studio-confirmation.md
@@ -7,10 +7,13 @@ 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. 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.
+1. Realize the preview through the native `reference-video-tools render_element` path (or the
+ repository API `realizePreviewMock({ run: "<project>/build.svrun", timing: "estimate" })`).
+ The tool 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. The realization is keyed by the Author/Run/target/geometry/timing digest,
+ so repeating the command reopens the cached bytes instead of generating new media or spending
+ Provider quota.
2. Start Hypit Studio with that returned `previewRun` path. Capture the URL printed by
`server.printUrls()` and give the author the exact URL (for example,
`http://localhost:5179/`) in the handoff. Studio can
diff --git a/docs/guide/author-packages.md b/docs/guide/author-packages.md
index f5095740..2affa7a3 100644
--- a/docs/guide/author-packages.md
+++ b/docs/guide/author-packages.md
@@ -294,3 +294,49 @@ Producer ports are exact, not variadic: the keys supplied by a Fragment operatio
Manifest's `inputs`, `outputs` and `needs` exactly. For a variable number of child items, emit one
operation per item and feed those operations into an append/merge Producer with fixed named ports;
do not invent an `items[]` port that the Manifest did not declare.
+
+### Less-common literal shapes
+
+These details are part of the public vocabulary metadata and are easy to miss:
+
+```typescript
+children: [{ tag: "Row", cardinality: "many", summary: "Rows in display order." }];
+attributes: [{ name: "appearance", kind: "reference", required: true, summary: "Recipe sheet.",
+ recipe: [{ name: "accent", required: true, summary: "Colour for the active row.", values: ["red", "blue"] }] }];
+```
+
+`cardinality` and recipe-property `required` are mandatory. A validator receives the stored wrapper,
+so unwrap an inline value before inspecting it:
+
+```typescript
+handler: ({ value }) => {
+ if (value.kind !== "inline") throw new Error("Widget must be inline");
+ if (typeof value.value !== "object" || value.value === null) throw new Error("Widget is empty");
+}
+```
+
+When a component input refers to an authored Record, use `{ kind: "record", id: "record.id" }`;
+`space.ref` is a resolved reference, not the literal input shape. A temporal projection stores its
+resolved frame range at `window.span` (`startFrame` and `endFrameExclusive`), not beside the window.
+Media slots are Fragment inputs carrying a Blob Artifact; child elements and recipe properties belong
+in the Surface vocabulary, while deterministic rendering belongs in the Producer. Keep parent nesting
+and animation in the sealed `VisualElement` (`parent`, `order`, `animation.keyframes`) rather than
+inventing package-specific fields.
+
+```typescript
+// A child can be nested under a parent and animate an admitted local style.
+const panel = { id: "panel", kind: "box", order: 0, style: [] };
+const label = {
+ id: "label", parent: "panel", kind: "text", order: 1, style: [],
+ text: "A", fonts: [fontArtifact],
+ animation: { keyframes: [
+ { atFrame: 0, style: [{ name: "opacity", value: 0 }] },
+ { atFrame: 12, style: [{ name: "opacity", value: 1 }] },
+ ] },
+};
+```
+
+The exact `fontArtifact` fields are shown by `inspect_visual_contract`; use a real Blob Artifact in
+`sources`, with an explicit weight and style. The important boundary is that parent links, child
+cardinality, recipe properties, slot inputs and animation are declared explicitly and validated by
+their owning layer.
diff --git a/docs/guide/runtime.md b/docs/guide/runtime.md
index 674ec816..0a30698a 100644
--- a/docs/guide/runtime.md
+++ b/docs/guide/runtime.md
@@ -36,7 +36,7 @@ The Profile contains only environmental choices that genuinely vary:
"config": { "path": "artifacts" }
},
"credentials": {
- "environment": { "use": "@hypit/credential-store-env" }
+ "env": { "use": "@hypit/credential-store-env" }
},
"endpoints": {
"media": { "use": "@hypit/provider-media-local" }
diff --git a/docs/zh/guide/runtime.md b/docs/zh/guide/runtime.md
index 6e9ad567..d0a00ad3 100644
--- a/docs/zh/guide/runtime.md
+++ b/docs/zh/guide/runtime.md
@@ -35,7 +35,7 @@ Profile 只保留真正会随环境变化的选择:
"config": { "path": "artifacts" }
},
"credentials": {
- "environment": { "use": "@hypit/credential-store-env" }
+ "env": { "use": "@hypit/credential-store-env" }
},
"endpoints": {
"media": { "use": "@hypit/provider-media-local" }
diff --git a/packages/cli/src/archive.ts b/packages/cli/src/archive.ts
index 590c3ce6..bf1d3ce6 100644
--- a/packages/cli/src/archive.ts
+++ b/packages/cli/src/archive.ts
@@ -229,6 +229,11 @@ export function inspectBuild(state: BuildState, catalog?: BuildCatalogEntry) {
accepted: records.has(selection.record),
})),
records: state.records.map(summarizeRecord),
+ deterministic_durations: state.records.flatMap((record) =>
+ record.type.module.name === "@hypit/speech" && record.type.name === "SpeechDuration"
+ && record.value.kind === "inline" && typeof record.value.value === "number"
+ ? [{ record: record.id, seconds: record.value.value }]
+ : []),
diagnostics: state.diagnostics,
...(catalog === undefined ? {} : {
presentation: {
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index b3583189..421ccd4c 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { deterministicSpeechDurations, deterministicSpeechDurationsFromGraph } from "@hypit/compiler-node";
import type { NodeCompiledSourceClosure } from "@hypit/compiler-node";
import type { NodeRuntimeHost } from "@hypit/runtime-host-node";
import {
@@ -1704,6 +1705,7 @@ export async function runCli(
candidates: Object.fromEntries(loaded.document.candidates.map((item) => [item.id, item.kind])),
satisfactions: loaded.document.satisfactions,
unresolvedBuildRecords: loaded.unresolvedBuildRecords,
+ deterministic_durations: deterministicSpeechDurationsFromGraph(loaded.author.graph, loaded.author.program.records),
} as const;
writeCliOutput(io, args, {
kind: "check-run",
@@ -1907,6 +1909,7 @@ export async function runCli(
ok: preflight?.ok ?? true,
plan: result.definition.plan,
unreached: unreachedGenerations(result.compilation.author.graph, result.state, outputNames),
+ deterministic_durations: deterministicSpeechDurations(result.compilation),
...(preflight === undefined ? {} : { preflight }),
},
run: loaded.path,
diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.ts
index 3ffc2b84..f32025ef 100644
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -70,6 +70,13 @@ export type RunCheckOutput = {
readonly build: string;
readonly output: string;
}[];
+ /** Provider-free estimate:Speech values available before any Build. */
+ readonly deterministic_durations?: readonly {
+ readonly operation: string;
+ readonly speech_record: string;
+ readonly policy_record: string;
+ readonly seconds: number;
+ }[];
};
export type PlanPreflight = {
@@ -85,6 +92,13 @@ export type PlanOutput = {
readonly plan: BuildPlan;
/** Generations the Source declares that these Targets do not reach and no Record supplies. */
readonly unreached?: readonly { readonly name: string; readonly producer: string }[];
+ /** Provider-free estimate:Speech values used to size deterministic preview and paid takes. */
+ readonly deterministic_durations?: readonly {
+ readonly operation: string;
+ readonly speech_record: string;
+ readonly policy_record: string;
+ readonly seconds: number;
+ }[];
readonly preflight?: PlanPreflight;
};
diff --git a/packages/compiler-node/package.json b/packages/compiler-node/package.json
index 147fd621..e21a43e4 100644
--- a/packages/compiler-node/package.json
+++ b/packages/compiler-node/package.json
@@ -10,10 +10,12 @@
"dependencies": {
"@hypit/core": "workspace:*",
"@hypit/elaborator": "workspace:*",
+ "@hypit/estimate": "workspace:*",
"@hypit/workspace": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/run": "workspace:*",
"@hypit/source": "workspace:*",
+ "@hypit/text": "workspace:*",
"@hypit/validation": "workspace:*"
},
"devDependencies": {
diff --git a/packages/compiler-node/src/index.ts b/packages/compiler-node/src/index.ts
index f6014179..aef77733 100644
--- a/packages/compiler-node/src/index.ts
+++ b/packages/compiler-node/src/index.ts
@@ -7,7 +7,7 @@ export type {
RegisteredModulePackage,
} from "./modules.js";
export { NodeCompiler } from "./compiler.js";
-export { NodeRunCompiler } from "./run.js";
+export { NodeRunCompiler, deterministicSpeechDurations, deterministicSpeechDurationsFromGraph } from "./run.js";
export type {
NodeCompilerOptions,
NodeCompiledSourceClosure,
diff --git a/packages/compiler-node/src/run.ts b/packages/compiler-node/src/run.ts
index 0d79c803..c2ae4219 100644
--- a/packages/compiler-node/src/run.ts
+++ b/packages/compiler-node/src/run.ts
@@ -28,6 +28,9 @@ import type {
RunSourceUnit,
} from "@hypit/run";
import type { LinkedProgram } from "@hypit/protocol";
+import { estimateSpeechDuration } from "@hypit/estimate";
+import type { SpeechEstimatePolicy } from "@hypit/estimate";
+import type { Text } from "@hypit/text";
import type { NodeCompiledSourceClosure } from "./compiler.js";
import { mergeAttachments, NodeCompiler } from "./compiler.js";
@@ -76,6 +79,40 @@ export type PlannedBuild = {
readonly state: BuildState;
};
+/** Provider-free values produced by estimate:Speech and therefore useful before a paid Build. */
+export function deterministicSpeechDurationsFromGraph(
+ graph: NodeCompiledRun["author"]["graph"],
+ records: NodeCompiledRun["author"]["program"]["records"],
+): readonly {
+ readonly operation: string;
+ readonly speech_record: string;
+ readonly policy_record: string;
+ readonly seconds: number;
+}[] {
+ const recordMap = new Map(records.map((record) => [record.id, record]));
+ const result: { operation: string; speech_record: string; policy_record: string; seconds: number }[] = [];
+ for (const operation of graph.operations) {
+ if (operation.producer.module.name !== "@hypit/estimate" || operation.producer.name !== "estimate-speech-duration") continue;
+ const speech = operation.inputs.speech;
+ const policy = operation.inputs.policy;
+ if (speech?.kind !== "record" || policy?.kind !== "record") continue;
+ const speechValue = recordMap.get(speech.id)?.value;
+ const policyValue = recordMap.get(policy.id)?.value;
+ if (speechValue?.kind !== "inline" || policyValue?.kind !== "inline") continue;
+ try {
+ const duration = estimateSpeechDuration(speechValue.value as unknown as Text, policyValue.value as unknown as SpeechEstimatePolicy);
+ result.push({ operation: operation.id, speech_record: speech.id, policy_record: policy.id, seconds: duration });
+ } catch {
+ // Invalid inputs are reported by the ordinary graph check; this read-only aid must not mask it.
+ }
+ }
+ return result;
+}
+
+export function deterministicSpeechDurations(compilation: NodeCompiledRun): ReturnType<typeof deterministicSpeechDurationsFromGraph> {
+ return deterministicSpeechDurationsFromGraph(compilation.author.graph, compilation.author.program.records);
+}
+
function decodeStoredValue(bytes: Uint8Array, from: string): StoredValue {
let parsed: unknown;
try {
diff --git a/packages/composition/src/index.ts b/packages/composition/src/index.ts
index c360d462..187002f9 100644
--- a/packages/composition/src/index.ts
+++ b/packages/composition/src/index.ts
@@ -11,6 +11,7 @@ export {
visualTextSequenceSchema,
visualTextTypographySchema,
visualTrackSchema,
+ visualBoxSchema, visualMaskSchema, visualTextSchema, visualImageSchema, visualVideoSchema, visualSurfaceSchema, visualElementSchema,
} from "./schema.js";
export { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackIdentity, sealAudioTrack, sealComposition, sealVisualTrack } from "./track.js";
export { animatableLocalStyles } from "./track.js";
diff --git a/packages/composition/src/schema.ts b/packages/composition/src/schema.ts
index 46c41959..7beb0cae 100644
--- a/packages/composition/src/schema.ts
+++ b/packages/composition/src/schema.ts
@@ -41,15 +41,15 @@ const attribute = object({ name: { schema: string }, value: { schema: { kind: "s
const keyframe = object({ atFrame: { schema: integer }, easing: { schema: { kind: "string", enum: ["linear", "ease-in", "ease-out", "ease-in-out"] }, optional: true }, style: { schema: { kind: "array", minItems: 1, items: styleDeclaration } } });
const animation = object({ keyframes: { schema: { kind: "array", minItems: 2, items: keyframe } } });
const base = { id: { schema: string }, parent: { schema: string, optional: true }, order: { schema: integer }, style: { schema: { kind: "array", items: styleDeclaration } }, attributes: { schema: { kind: "array", items: attribute }, optional: true }, animation: { schema: animation, optional: true } } as const;
-const box = object({ ...base, kind: { schema: { kind: "literal", value: "box" } } });
-const mask = object({
+export const visualBoxSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "box" } } });
+export const visualMaskSchema: ValueSchema = object({
...base,
kind: { schema: { kind: "literal", value: "mask" } },
mode: { schema: { kind: "string", enum: ["alpha", "luminance"] } },
maskElement: { schema: string },
contentElement: { schema: string },
});
-const text = object({ ...base, kind: { schema: { kind: "literal", value: "text" } }, text: { schema: { kind: "string" } }, fonts: { schema: { kind: "array", minItems: 1, items: fontArtifactSchema } } });
+export const visualTextSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "text" } }, text: { schema: { kind: "string" } }, fonts: { schema: { kind: "array", minItems: 1, items: fontArtifactSchema } } });
const finiteNumber = { kind: "number" } as const;
const boolean = { kind: "boolean" } as const;
const enumString = (values: readonly string[]): ValueSchema => ({ kind: "string", enum: values });
@@ -164,11 +164,12 @@ export const visualPathCommandSchema: ValueSchema = { kind: "oneOf", variants: [
object({ kind: { schema: { kind: "literal", value: "close" } } }),
] };
const pathTextElement = object({ ...base, kind: { schema: { kind: "literal", value: "path-text" } }, document: { schema: visualTextDocumentSchema }, typography: { schema: visualTextTypographySchema }, paints: { schema: { kind: "array", items: visualTextPaintSchema } }, path: { schema: { kind: "array", minItems: 2, items: visualPathCommandSchema } }, side: { schema: enumString(["left", "right"]) }, orientation: { schema: enumString(["follow", "upright"]) }, startMarginPx: { schema: number }, endMarginPx: { schema: number }, align: { schema: enumString(["start", "center", "end"]) }, reverse: { schema: boolean }, overflow: { schema: enumString(["visible", "clip"]) }, sequences: { schema: { kind: "array", items: visualTextSequenceSchema } }, marginAnimation: { schema: object({ keyframes: { schema: { kind: "array", minItems: 2, items: object({ atFrame: { schema: integer }, startMarginPx: { schema: number }, easing: { schema: enumString(["linear", "ease-in", "ease-out", "ease-in-out"]), optional: true } }) } } }), optional: true } });
-const media = (kind: "image" | "video") => object({ ...base, kind: { schema: { kind: "literal", value: kind } }, artifact: { schema: mediaBlobRef }, sampling: { schema: sampling, optional: true }, muted: { schema: { kind: "boolean" }, optional: true } });
-const surface = object({ ...base, kind: { schema: { kind: "literal", value: "surface" } }, surface: { schema: compositableSurfaceSchema }, sampling: { schema: sampling, optional: true } });
-const element: ValueSchema = { kind: "oneOf", variants: [box, mask, text, textFlowElement, pathTextElement, media("image"), media("video"), surface] };
+export const visualImageSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "image" } }, artifact: { schema: mediaBlobRef }, sampling: { schema: sampling, optional: true }, muted: { schema: { kind: "boolean" }, optional: true } });
+export const visualVideoSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "video" } }, artifact: { schema: mediaBlobRef }, sampling: { schema: sampling, optional: true }, muted: { schema: { kind: "boolean" }, optional: true } });
+export const visualSurfaceSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "surface" } }, surface: { schema: compositableSurfaceSchema }, sampling: { schema: sampling, optional: true } });
+export const visualElementSchema: ValueSchema = { kind: "oneOf", variants: [visualBoxSchema, visualMaskSchema, visualTextSchema, textFlowElement, pathTextElement, visualImageSchema, visualVideoSchema, visualSurfaceSchema] };
const span = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });
-const present = object({ id: { schema: string }, span: { schema: span }, stacking: { schema: object({ order: { schema: signedInteger }, tieBreak: { schema: string } }) }, elements: { schema: { kind: "array", minItems: 1, items: element } } });
+const present = object({ id: { schema: string }, span: { schema: span }, stacking: { schema: object({ order: { schema: signedInteger }, tieBreak: { schema: string } }) }, elements: { schema: { kind: "array", minItems: 1, items: visualElementSchema } } });
export const visualTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "visual" } }, programSpaceId: { schema: string }, visualIr: { schema: { kind: "literal", value: VISUAL_IR_V1 } }, id: { schema: string }, presents: { schema: { kind: "array", items: present } } });
const audioSampleSpan = object({ startSample: { schema: integer }, endSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } } });
const audioClip = object({
diff --git a/packages/preview-mock/src/graph.ts b/packages/preview-mock/src/graph.ts
index 91f750c1..42e59d7a 100644
--- a/packages/preview-mock/src/graph.ts
+++ b/packages/preview-mock/src/graph.ts
@@ -128,22 +128,43 @@ function estimateOperationDuration(graph: CompiledGraph, operation: ReturnType<t
}
}
+/** Resolve the SpeechDuration belonging to one generation operation, without falling back to the
+ * first duration in the graph. Seedance's duration arrives through its internal DurationProgram, so
+ * the useful edge may be an operation result rather than a logical output. */
+function durationFromRef(
+ graph: CompiledGraph,
+ ref: GraphValueRef | undefined,
+ records: readonly TypedRecord[],
+ seen = new Set<string>(),
+): number | undefined {
+ if (ref === undefined) return undefined;
+ if (ref.kind === "record") return inlineDuration(recordValue(records, ref.id));
+ if (ref.kind === "logical-output") {
+ const candidate = findLogicalOutput(graph, ref.id);
+ if (candidate === undefined) return undefined;
+ const primary = findCandidate(graph, candidate.primary);
+ return primary?.root.kind === "value" ? inlineDuration(primary.root.value.value) : undefined;
+ }
+ if (seen.has(ref.operation)) return undefined;
+ seen.add(ref.operation);
+ const operation = findOperation(graph, ref.operation);
+ if (operation === undefined) return undefined;
+ const estimated = estimateOperationDuration(graph, operation, records);
+ if (estimated !== undefined) return estimated;
+ return durationFromRef(graph, operation.inputs.duration, records, seen)
+ ?? durationFromRef(graph, operation.inputs.speech, records, seen);
+}
+
function durationForTarget(graph: CompiledGraph, operation: ReturnType<typeof findOperation>, inputs: Readonly<Record<string, string>>, records: readonly TypedRecord[]): number | undefined {
+ const direct = durationFromRef(graph, operation?.inputs.duration, records);
+ if (direct !== undefined) return direct;
const durationId = inputs.duration;
- if (durationId === undefined) return undefined;
- const candidate = graph.candidates.find((item) => item.root.kind === "value" && item.root.value.id === durationId)
- ?? graph.candidates.find((item) => graph.outputs.some((output) => output.id === durationId && output.primary === item.id));
- if (candidate?.root.kind === "value") return inlineDuration(candidate.root.value.value);
- // Some compilers retain the duration as an operation result candidate. Resolve the referenced
- // operation's value when it was already evaluated deterministically; never consult reference media.
- const operationId = operation?.inputs.duration?.kind === "operation-result" ? operation.inputs.duration.operation : undefined;
- const estimated = operationId === undefined ? undefined : estimateOperationDuration(graph, findOperation(graph, operationId), records);
- if (estimated !== undefined) return estimated;
- for (const id of operationRecordRefs(graph, operation)) {
- const duration = inlineDuration(recordValue(records, id));
- if (duration !== undefined) return duration;
+ if (durationId !== undefined) {
+ const candidate = graph.candidates.find((item) => item.root.kind === "value" && item.root.value.id === durationId)
+ ?? graph.candidates.find((item) => graph.outputs.some((output) => output.id === durationId && output.primary === item.id));
+ if (candidate?.root.kind === "value") return inlineDuration(candidate.root.value.value);
}
- return undefined;
+ return operationRecordRefs(graph, operation).map((id) => inlineDuration(recordValue(records, id))).find((value): value is number => value !== undefined);
}
function mockInputs(graph: CompiledGraph, kind: MockKind, operation: ReturnType<typeof findOperation>, records: readonly TypedRecord[] = []): Readonly<Record<string, string>> {
diff --git a/packages/reference-video-tools/src/checks.ts b/packages/reference-video-tools/src/checks.ts
index 696313a6..75cca6f9 100644
--- a/packages/reference-video-tools/src/checks.ts
+++ b/packages/reference-video-tools/src/checks.ts
@@ -634,6 +634,20 @@ export async function authoringCheck(
}
}
+ // Recipe attributes are part of the authored declaration just like inline attributes. Keep a
+ // small source-side index so coverage does not mistake a generated video declared by
+ // `recipe={recipes.media.aroll}` for a voice merely because there is no `video=` attribute.
+ const recipeSheets = new Map<string, Map<string, string>>();
+ for (const match of svml.matchAll(/<import\s+as="([^"]+)"\s+source="([^"]+\.svs)"/gu)) {
+ const alias = match[1] ?? "";
+ const source = match[2] ?? "";
+ const text = await readFile(resolve(dirname(svmlPath), source), "utf8").catch(() => undefined);
+ if (text === undefined) continue;
+ const recipes = new Map<string, string>();
+ for (const recipe of text.matchAll(/([A-Za-z0-9_.-]+)\s*\{([^}]*)\}/gu)) recipes.set(recipe[1] ?? "", recipe[2] ?? "");
+ recipeSheets.set(alias, recipes);
+ }
+
// Which Normalize ids carry a picture. A take normalized with `video="none"` is a voice: it has no
// window to fill, and nothing it feeds puts anything on the Canvas.
const moving = new Set<string>();
@@ -642,7 +656,12 @@ export async function authoringCheck(
const attributes = match[1] ?? "";
const id = /\bid="([^"]+)"/u.exec(attributes)?.[1];
const video = /\bvideo="([^"]+)"/u.exec(attributes)?.[1];
- if (id !== undefined && video !== undefined && video !== "none") moving.add(id);
+ const recipe = /\brecipe=\{([A-Za-z0-9_-]+)\.([A-Za-z0-9_.-]+)\}/u.exec(attributes);
+ const recipeVideo = recipe === null ? undefined
+ : /\bvideo\s*:\s*([^;\s]+)/u.exec(recipeSheets.get(recipe[1] ?? "")?.get(recipe[2] ?? "") ?? "")?.[1];
+ if (id !== undefined && ((video !== undefined && video !== "none") || (video === undefined && recipeVideo !== undefined && recipeVideo !== "none"))) {
+ moving.add(id);
+ }
}
// ---- Timed pictures that stop before their window ends ----
@@ -663,18 +682,6 @@ export async function authoringCheck(
// ends rather than where the shot should" — in the one form the route can settle before a Build, from
// the Source and its Recipe sheets alone.
const playbackReport = async (): Promise<readonly PlaybackReport[]> => {
- // Every Recipe body the Source can name, by the alias its sheet was imported under.
- const sheets = new Map<string, Map<string, string>>();
- for (const match of svml.matchAll(/<import\s+as="([^"]+)"\s+source="([^"]+\.svs)"/gu)) {
- const alias = match[1] ?? "";
- const source = match[2] ?? "";
- const text = await readFile(resolve(dirname(svmlPath), source), "utf8").catch(() => undefined);
- if (text === undefined) continue;
- const recipes = new Map<string, string>();
- for (const recipe of text.matchAll(/([A-Za-z0-9_.-]+)\s*\{([^}]*)\}/gu)) recipes.set(recipe[1] ?? "", recipe[2] ?? "");
- sheets.set(alias, recipes);
- }
-
// Which aliases belong to a package that draws. Plenty of elements consume a normalized media
// without placing it — `whisperx:SemanticTake` reads one to align speech against it and puts no
// picture on the Canvas, so it has no window to fill and no occupancy to choose. Requiring the
@@ -694,7 +701,7 @@ export async function authoringCheck(
const media = /\bmedia=\{([A-Za-z0-9_-]+)\.media\}/u.exec(attributes)?.[1];
if (media === undefined || !moving.has(media)) continue;
const appearance = /\bappearance=\{([A-Za-z0-9_-]+)\.([A-Za-z0-9_.-]+)\}/u.exec(attributes);
- const body = appearance === null ? undefined : sheets.get(appearance[1] ?? "")?.get(appearance[2] ?? "");
+ const body = appearance === null ? undefined : recipeSheets.get(appearance[1] ?? "")?.get(appearance[2] ?? "");
const playback = body === undefined ? undefined : /\bplayback\s*:\s*([A-Za-z-]+)/u.exec(body)?.[1];
if (playback !== undefined && playback !== "once-start" && playback !== "once-end") continue;
running.push({
diff --git a/packages/reference-video-tools/src/cli.ts b/packages/reference-video-tools/src/cli.ts
index e709a914..d4c1ac7a 100644
--- a/packages/reference-video-tools/src/cli.ts
+++ b/packages/reference-video-tools/src/cli.ts
@@ -44,7 +44,7 @@ function usage(): string {
" hypit-reference-video-tools inspect_svml_vocabulary --package <name> [--package <name> ...] [--tag <tag> ...] [--without-previews] [--run <build.svrun>]",
" hypit-reference-video-tools validate_local_author_packages --run <build.svrun> [--expected-package <name> ...]",
" hypit-reference-video-tools validate_script_cues --run <build.svrun>",
- " hypit-reference-video-tools inspect_visual_contract [--shape visual-track|text-flow|text-typography|text-paint|text-document|path-command] [--producers-of <package> ...]",
+ " hypit-reference-video-tools inspect_visual_contract [--shape visual-track|visual-element|box|mask|text|image|video|surface|text-flow|text-typography|text-paint|text-document|path-command] [--producers-of <package> ...]",
" hypit-reference-video-tools paths",
" hypit-reference-video-tools compare_reconstruction --reference-id <id> --run <build.svrun> --segment <id>|--selection <id>|--tokens <from:to> --video <path>|--image <path> [--question <scope>] [--element <id>] [--tolerance-frames <n>]",
" hypit-reference-video-tools compare_reconstruction --reference-id <id> --shot-id <id> --video <path>|--image <path> [--question <scope>] [--element <id>] [--tolerance-frames <n>]",
diff --git a/packages/reference-video-tools/src/route-state.ts b/packages/reference-video-tools/src/route-state.ts
index 77615c81..87ce1fe3 100644
--- a/packages/reference-video-tools/src/route-state.ts
+++ b/packages/reference-video-tools/src/route-state.ts
@@ -540,6 +540,9 @@ async function evidenceSatisfied(key: string, path: string | undefined): Promise
if (key === "package_ready" || key === "script_cues" || key === "vocabulary") {
try {
const value = JSON.parse(await readFile(path, "utf8")) as { passed?: unknown; surfaces?: unknown[]; packages?: unknown[] };
+ if ((value as { waived?: unknown }).waived === true
+ && typeof (value as { diagnosis?: unknown }).diagnosis === "string"
+ && ((value as { diagnosis?: string }).diagnosis?.trim().length ?? 0) > 0) return true;
if (key === "vocabulary") return Array.isArray(value.surfaces) || Array.isArray(value.packages);
return value.passed === true;
} catch { return false; }
diff --git a/packages/reference-video-tools/src/tools.ts b/packages/reference-video-tools/src/tools.ts
index 0e1922db..34555351 100644
--- a/packages/reference-video-tools/src/tools.ts
+++ b/packages/reference-video-tools/src/tools.ts
@@ -13,8 +13,11 @@ import type { ValueSchema } from "@hypit/protocol";
import {
visualPathCommandSchema, visualTextDocumentSchema, visualTextFlowSchema,
visualTextPaintSchema, visualTextTypographySchema, visualTrackSchema,
+ visualBoxSchema, visualMaskSchema, visualTextSchema, visualImageSchema,
+ visualVideoSchema, visualSurfaceSchema, visualElementSchema,
animatableLocalStyles,
} from "@hypit/composition";
+import { VISUAL_STYLE_ENUM_VALUES_V1, VISUAL_STYLE_NAMES_V1 } from "@hypit/visual-ir";
import { describeSchema } from "./contract.js";
import { videoCliDistribution } from "@hypit/video-cli";
@@ -1300,7 +1303,8 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
let loaded: Awaited<ReturnType<typeof loadNodePackageSelection>> = [];
try { loaded = await loadNodePackageSelection([specifier], projectRoot, loading); }
catch { errors.push("PACKAGE_ACTIVATION_INVALID"); }
- const contribution = loaded[0]?.contribution;
+ const selected = loaded.find((pack) => pack.specifier === specifier || physicalPackageName(pack.specifier) === physicalPackageName(specifier));
+ const contribution = selected?.contribution;
const modules = contribution?.modules ?? [];
const surfaces = (contribution?.hostFacets ?? []).filter((facet) => facet.abi === markupSurfaceHostFacetAbi);
// Author packages expand Markup Surfaces into Graph Fragments; they do not need the separate
@@ -1333,7 +1337,7 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
const graphUsed = modules.some((module) => graphModules.has(`${module.manifest.name}@${module.manifest.version}`));
if (!sourceImported) errors.push("PACKAGE_NOT_IMPORTED");
else if (!graphUsed) errors.push("PACKAGE_IMPORTED_BUT_UNUSED");
- results.push({ specifier, manifest: modules.length > 0, surfaces: surfaces.length, producers: producers.length, fragments: fragmentValues.length, run_fragment_facets: runFragmentFacets.length, source_imported: sourceImported, source_used: graphUsed, graph_used: graphUsed, status: errors.length === 0 ? "passed" : "failed", ...(errors.length === 0 ? {} : { errors }) });
+ results.push({ specifier, loaded_specifier: selected?.specifier, manifest: modules.length > 0, surfaces: surfaces.length, producers: producers.length, fragments: fragmentValues.length, run_fragment_facets: runFragmentFacets.length, source_imported: sourceImported, source_used: graphUsed, graph_used: graphUsed, status: errors.length === 0 ? "passed" : "failed", ...(errors.length === 0 ? {} : { errors }) });
}
for (const specifier of expected) {
if (!results.some((item) => item.specifier === specifier)) results.push({ specifier, status: "failed", errors: ["PACKAGE_EXPECTED_BUT_MISSING"] });
@@ -1955,6 +1959,13 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
async inspect_visual_contract(input): Promise<Record<string, unknown>> {
const shapes: Record<string, ValueSchema> = {
"visual-track": visualTrackSchema,
+ "visual-element": visualElementSchema,
+ box: visualBoxSchema,
+ mask: visualMaskSchema,
+ text: visualTextSchema,
+ image: visualImageSchema,
+ video: visualVideoSchema,
+ surface: visualSurfaceSchema,
"text-flow": visualTextFlowSchema,
"text-typography": visualTextTypographySchema,
"text-paint": visualTextPaintSchema,
@@ -1981,6 +1992,8 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
return {
shapes: chosen.map((name) => ({ shape: name, describes: describeSchema(shapes[name]!).join("\n") })),
animatable_local_styles: [...animatableLocalStyles],
+ visual_style_names: [...VISUAL_STYLE_NAMES_V1],
+ visual_style_enum_values: VISUAL_STYLE_ENUM_VALUES_V1,
...(calls.length === 0 ? {} : { producers: calls }),
// Each of these is refused somewhere, or follows from how the emitted CSS is written. None is
// a convention: a rule stated here that the code does not hold would be worse than silence.
@@ -1993,6 +2006,11 @@ export function createReferenceVideoTools(options: ToolOptions = {}): ReferenceV
"An animation carries at least two keyframes, and every keyframe of one animation declares "
+ "the same properties: one that appears in some and not others is interpolated from the "
+ "element's own value on the frames it is missing from.",
+ "A plain text element must provide exact ordered font artifacts and cannot combine them with raw font styles.",
+ "A text element using glyph Paint cannot also declare raw stroke or paint-order styles.",
+ "A media element's artifact media type must match image/video, and still images cannot carry sampling.",
+ "A Surface with still timing cannot carry sampling; frame-based Surface sampling must match its typed timing.",
+ "Mask roots must be direct children of one Present and both mask/content references must resolve to owned elements.",
],
};
},
diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.md
index d9bf37c7..aec11c5f 100644
--- a/packages/runtime-local/README.md
+++ b/packages/runtime-local/README.md
@@ -17,7 +17,7 @@ A Runtime Profile selects only the environmental parts that genuinely vary:
"config": { "path": "artifacts" }
},
"credentials": {
- "environment": { "use": "@hypit/credential-store-env" }
+ "env": { "use": "@hypit/credential-store-env" }
},
"endpoints": {}
}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8ab8f330..4662534f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -641,6 +641,9 @@ importers:
'@hypit/elaborator':
specifier: workspace:*
version: link:../elaborator
+ '@hypit/estimate':
+ specifier: workspace:*
+ version: link:../estimate
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
@@ -650,6 +653,9 @@ importers:
'@hypit/source':
specifier: workspace:*
version: link:../source
+ '@hypit/text':
+ specifier: workspace:*
+ version: link:../text
'@hypit/validation':
specifier: workspace:*
version: link:../validation