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: complete author package public fixture

rpone920361216f70
diff --git a/.agents/skills/hypit/references/local-author-package.md b/.agents/skills/hypit/references/local-author-package.md
index 0f3a6836..4fd1ce26 100644
--- a/.agents/skills/hypit/references/local-author-package.md
+++ b/.agents/skills/hypit/references/local-author-package.md
@@ -108,9 +108,10 @@ record; only read an inline value after checking `record.value.kind === "inline"
`record.value.value`. Never infer a value from the reference path.
The temporal-markup helpers take one object `{ id, subjectId?, element, semantic, resolveReference }`
-and return `records`, `components` and `fragments` collections to append to the Surface result. The resulting
-`TemporalInstant` carries `frame`; a `TemporalWindow` carries `span` with `startFrame` and
-`endFrameExclusive`.
+and return `records`, `components`, `fragments` and a component-output `ref`. The resulting
+`TemporalInstant` has `{ id, subjectId, source, projection, authority, frame }`; a
+`TemporalWindow` has `{ id, subjectId, start, end, span }`, where each endpoint is a
+`TemporalInstant` and `span` has `startFrame` and `endFrameExclusive`.
`SpatialFrame` uses `xPx`, `yPx`, `widthPx` and `heightPx`; `ProgramSpace` provides `id`,
`narrativeId`, `durationSec` and `frameRate` (`numerator` and `denominator`). A `fonts:Stack` Surface publishes a
@@ -176,26 +177,14 @@ Choose raw versus structured Surface, timing dependencies, ProgramSpace, Frame,
Artifact, Recipe and output Types from the observed behavior and the anatomy the guide states. A
declaration-only or Surface-only package is incomplete.
-For variable child counts, emit one Fragment operation per child and pass those fixed-port results
-to an append/merge Producer (for example `head`, `item`, `tail`). Do not add an undeclared
-`items[]` input or let a handler consume arbitrary children; every child must be represented by a
-sealed operation.
+For variable child counts, emit one child operation per child and chain those fixed-port results
+through an append Producer (`previous`, `item` → `set`). Do not add an undeclared `items[]` input or
+let a handler consume arbitrary children; every child must be represented by a sealed operation.
-```typescript
-const childOps = children.map((child, index) => ({
- id: `child-${index}`, producer: childProducer,
- inputs: { value: childInput(child) },
- result: { kind: "output", name: `child-${index}` },
-}));
-const merge = {
- id: "merge", producer: appendProducer,
- inputs: { head: childOps[0]!, item: childOps[1]!, tail: childOps[2]! },
- result: { kind: "output", name: "items" },
-};
-```
-
-The real implementation repeats the fixed operation shape for the actual child count and uses the
-package's documented empty/one/many merge forms; the handler never accepts undeclared variadic input.
+The fixture's `exampleAppendFragment` and `append-example-items` Producer are the runnable reference:
+each operation has exactly `previous` and `item` inputs and returns `set`, so the returned set can be
+fed into the next operation. The empty set is an ordinary typed Record. The handler never accepts
+undeclared variadic input.
## The package draws itself
@@ -261,15 +250,17 @@ nothing.
not render a complete PNG sequence; when no interval is stable for two frames, it uses the middle
frame of the longest Present.
-For a media slot, declare an Artifact Fragment input and read the BlobRef from `inputs`. Branch on
-its `mediaType` (`image/*` or `video/*`) when choosing the Visual IR element, and still draw the
-empty frame/cell when no material is supplied. `hypit image` uses the selected Runtime Profile's
-image endpoint and is billed; obtain approval before using it and reserve it for package-owned
-chrome, never video content or previews.
+For a media slot, declare an Artifact Fragment input. Producer inputs are `TypedRecord`s: inspect
+`inputs.media.value`; a filled slot is a BlobRef (`kind === "blob"`), while an authored structured
+value is under `kind === "inline"`. Branch on BlobRef `mediaType` (`image/*` or `video/*`) when
+choosing the Visual IR element, and still draw the empty frame/cell when no material is supplied.
+`hypit image` is a direct, billed KIE image-model call (default `@hypit/gpt-image`, credential
+`KIE_API_KEY`); it does not use a project Runtime Profile, Build or Run Source. Obtain approval
+before using it and reserve it for package-owned chrome.
```typescript
handler: ({ inputs }) => {
- const media = inputs.media?.kind === "blob" ? inputs.media : undefined;
+ const media = inputs.media?.value.kind === "blob" ? inputs.media.value : undefined;
const kind = media?.mediaType.startsWith("video/") ? "video" : "image";
return { outputs: { track: output(renderSlot(kind, media)) }, needs: {} };
}
diff --git a/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md b/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md
index cea78f3e..87a1fd8f 100644
--- a/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md
+++ b/.agents/skills/hypit/references/playbooks/craft/graphic-compositions.md
@@ -115,9 +115,10 @@ project that installs it to obtain a picture that was never theirs to choose. If
writing a Run Source whose only purpose is to produce a component's own texture, the texture is in
the wrong place: generate it once while authoring the package and commit the file.
-Produce that file with `hypit image --prompt <text> --to <path>`, which writes a picture and nothing
-else. A package asset is authoring input, not the output of anybody's video, so it is never a Target
-and never a Record.
+Produce that file with `hypit image --prompt <text> --to <path>`, a direct billed KIE image-model
+call (default `@hypit/gpt-image`, using `KIE_API_KEY`). It writes a picture and nothing else; no
+project Runtime Profile, Source, Run, Build or Record participates. A package asset is authoring
+input, not the output of anybody's video, so it is never a Target or Record.
A package is installed vocabulary. `.svml`, `.svs` and `.svrun` are documents that use it. A package
that needs one of those documents in order to draw itself has inverted that relationship.
diff --git a/.agents/skills/hypit/references/vocabulary.md b/.agents/skills/hypit/references/vocabulary.md
index 290f4178..fc4efb3a 100644
--- a/.agents/skills/hypit/references/vocabulary.md
+++ b/.agents/skills/hypit/references/vocabulary.md
@@ -94,9 +94,11 @@ it may not move an element into the wrong semantic role merely because another t
shape. Never invent a component, attribute, child, port, Recipe property or literal value.
Installed packages are immutable dependencies. Do not modify them, copy or vendor their source into
-the project, or read implementation source to discover undeclared syntax. When the fit is not good
-enough, use the project-local package route and author it from the visible requirement, inspect
-contract, README and `local-author-package.md`.
+the project, or read implementation source to discover undeclared syntax. If the author explicitly
+chooses to copy a named package as a close structural sibling, that package's README and required
+role files may be read as the bounded implementation skeleton; this is the only source-reading
+exception. When the fit is not good enough, use the project-local package route and author it from
+the visible requirement, inspect contract, README and `local-author-package.md`.
## Freeze the judgement
diff --git a/examples/minimal-author-package/README.md b/examples/minimal-author-package/README.md
index d639e4c4..b5557c05 100644
--- a/examples/minimal-author-package/README.md
+++ b/examples/minimal-author-package/README.md
@@ -2,7 +2,8 @@
Use this directory only as the generic author-package fixture. It is deliberately not a complete video
project: the `packages/example-component` package is the authoritative small implementation, while
-the package's `preview/` asset demonstrates a Surface preview.
+the package's `preview/` asset demonstrates a Surface preview. The fixture also includes a Style
+Surface that reads an SVS Recipe and exact FontStackRef.
The fixture's Surface decoder also demonstrates the public value boundary: Style-like values consume
a decoded recipe shaped as `{ path, properties }`, exact `FontStackRef` records and inline values
diff --git a/examples/minimal-author-package/packages/example-component/README.md b/examples/minimal-author-package/packages/example-component/README.md
index 2d4c9232..ded68498 100644
--- a/examples/minimal-author-package/packages/example-component/README.md
+++ b/examples/minimal-author-package/packages/example-component/README.md
@@ -9,6 +9,7 @@ literal `fragment-input`, `fragment-operation` and `output` references. `src/tem
Surface-side `@hypit/temporal-markup` Window/Moment projections; that package is distinct from the
graph-side `@hypit/temporal` Producers.
-The three Surfaces demonstrate a box, a text surface and a media slot. The slot is a graph input; it is
-not a file bundled by the package. `preview/Box.png` is a real catalogue frame supplied by the
-package's vocabulary.
+The Surfaces demonstrate a box, a text surface, a media slot and a Style decoder. The slot is a graph
+input; it is not a file bundled by the package. `preview/Box.png` is a real catalogue frame supplied
+by the package's vocabulary. `exampleAppendFragment` and `append-example-items` show a fixed-port
+append that can be chained once per child.
diff --git a/examples/minimal-author-package/packages/example-component/package.json b/examples/minimal-author-package/packages/example-component/package.json
index 5cf0d7bf..1d1a63f6 100644
--- a/examples/minimal-author-package/packages/example-component/package.json
+++ b/examples/minimal-author-package/packages/example-component/package.json
@@ -9,10 +9,12 @@
"@hypit/component-kit": "workspace:*",
"@hypit/composition": "workspace:*",
"@hypit/elaborator": "workspace:*",
+ "@hypit/media": "workspace:*",
"@hypit/markup": "workspace:*",
"@hypit/protocol": "workspace:*",
"@hypit/program-space": "workspace:*",
"@hypit/semantic-track": "workspace:*",
+ "@hypit/svs": "workspace:*",
"@hypit/temporal": "workspace:*",
"@hypit/temporal-markup": "workspace:*",
"@hypit/visual-ir": "workspace:*"
diff --git a/examples/minimal-author-package/packages/example-component/src/component.ts b/examples/minimal-author-package/packages/example-component/src/component.ts
index 99f480e4..3c5c885a 100644
--- a/examples/minimal-author-package/packages/example-component/src/component.ts
+++ b/examples/minimal-author-package/packages/example-component/src/component.ts
@@ -2,6 +2,7 @@ import { sealVisualTrack } from "@hypit/composition";
import type { ProgramSpace } from "@hypit/program-space";
import type { ComponentPackage, ProducerHandler } from "@hypit/component-kit";
import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, TypedRecord } from "@hypit/protocol";
import { VISUAL_IR_V1 } from "@hypit/visual-ir";
import { exampleProducers, exampleTypes } from "./manifest.js";
@@ -10,7 +11,10 @@ const inline = <T>(record: { readonly value: { readonly kind: string; readonly v
return record.value.value as T;
};
const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
-function render(kind: string, space: ProgramSpace) {
+function blob(record: TypedRecord | undefined): BlobRef | undefined {
+ return record?.value.kind === "blob" ? record.value : undefined;
+}
+function render(kind: string, space: ProgramSpace, media?: BlobRef) {
const frames = Math.max(1, Math.round(space.durationSec * space.frameRate.numerator / space.frameRate.denominator));
return sealVisualTrack({
programSpaceId: space.id,
@@ -19,16 +23,19 @@ function render(kind: string, space: ProgramSpace) {
presents: [{ id: `present-${kind}`, span: { startFrame: 0, endFrameExclusive: frames }, stacking: { order: 0, tieBreak: kind }, elements: [{
id: `${kind}-root`, kind: "box", order: 0,
style: [{ name: "background-color", value: "#6b7280" }],
- }] }],
+ }, ...(kind === "media" && media !== undefined ? [{ id: `${kind}-content`, parent: `${kind}-root`, kind: media.mediaType.startsWith("video/") ? "video" as const : "image" as const, artifact: media, order: 1, style: [{ name: "position", value: "absolute" }, { name: "left", value: 0 }, { name: "top", value: 0 }, { name: "width", value: "100%" }, { name: "height", value: "100%" }, { name: "object-fit", value: "contain" }] }] : []),
+ ] }],
});
}
-const producer = (kind: string): { readonly handler: ProducerHandler } => ({ handler: ({ inputs }) => ({ outputs: { track: output(render(kind, inline<ProgramSpace>(inputs.space))) }, needs: {} }) });
+const producer = (kind: string): { readonly handler: ProducerHandler } => ({ handler: ({ inputs }) => ({ outputs: { track: output(render(kind, inline<ProgramSpace>(inputs.space), blob(inputs.media))) }, needs: {} }) });
+const appendItems: { readonly handler: ProducerHandler } = { handler: ({ inputs }) => ({ outputs: { set: output({ items: [inline<{ items: readonly unknown[] }>(inputs.previous).items, inline<{ items: readonly unknown[] }>(inputs.item).items].flat() }) }, needs: {} }) };
export const exampleComponent = {
producers: [
{ producer: exampleProducers.renderBox, ...producer("box") },
{ producer: exampleProducers.renderText, ...producer("text") },
{ producer: exampleProducers.renderMedia, ...producer("media") },
+ { producer: exampleProducers.appendItems, ...appendItems },
],
validators: [
{ type: exampleTypes.box, handler: () => {} },
diff --git a/examples/minimal-author-package/packages/example-component/src/fragment.ts b/examples/minimal-author-package/packages/example-component/src/fragment.ts
index 24358adf..4ee3de1c 100644
--- a/examples/minimal-author-package/packages/example-component/src/fragment.ts
+++ b/examples/minimal-author-package/packages/example-component/src/fragment.ts
@@ -1,18 +1,22 @@
import { compositionTypes } from "@hypit/composition";
+import { artifactTypes } from "@hypit/artifact";
import { sealGraphFragment } from "@hypit/elaborator";
import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
import { programSpaceTypes } from "@hypit/program-space";
import { exampleProducers } from "./manifest.js";
+import { exampleTypes } from "./manifest.js";
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-export function createExampleFragment(producer: typeof exampleProducers[keyof typeof exampleProducers], id: string) {
+export function createExampleFragment(producer: typeof exampleProducers[keyof typeof exampleProducers], id: string, media = false) {
+ const inputs = [{ name: "semantic", type: semanticTrackTypes.track }, ...(media ? [{ name: "media", type: artifactTypes.blob }] : [])];
+ const renderInputs = { space: operation("space"), ...(media ? { media: input("media") } : {}) };
return sealGraphFragment({
- inputs: [{ name: "semantic", type: semanticTrackTypes.track }],
+ inputs,
operations: [
{ id: "space", producer: semanticTrackProducers.projectProgramSpace, inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },
- { id, producer, inputs: { space: operation("space") }, result: { kind: "output", name: "track" } },
+ { id, producer, inputs: renderInputs, result: { kind: "output", name: "track" } },
],
exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation(id) }],
});
@@ -20,4 +24,9 @@ export function createExampleFragment(producer: typeof exampleProducers[keyof ty
export const exampleBoxFragment = createExampleFragment(exampleProducers.renderBox, "render-box");
export const exampleTextFragment = createExampleFragment(exampleProducers.renderText, "render-text");
-export const exampleMediaFragment = createExampleFragment(exampleProducers.renderMedia, "render-media-slot");
+export const exampleMediaFragment = createExampleFragment(exampleProducers.renderMedia, "render-media-slot", true);
+export const exampleAppendFragment = sealGraphFragment({
+ inputs: [{ name: "previous", type: exampleTypes.itemSet }, { name: "item", type: exampleTypes.itemSet }],
+ operations: [{ id: "append-items", producer: exampleProducers.appendItems, inputs: { previous: input("previous"), item: input("item") }, result: { kind: "output", name: "set" } }],
+ exports: [{ name: "set", type: exampleTypes.itemSet, root: operation("append-items") }],
+});
diff --git a/examples/minimal-author-package/packages/example-component/src/index.ts b/examples/minimal-author-package/packages/example-component/src/index.ts
index 7a6274a2..e9504e75 100644
--- a/examples/minimal-author-package/packages/example-component/src/index.ts
+++ b/examples/minimal-author-package/packages/example-component/src/index.ts
@@ -1,5 +1,5 @@
export { exampleComponent } from "./component.js";
-export { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";
+export { exampleAppendFragment, exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from "./fragment.js";
export { exampleManifest, exampleMarkupSurfaces, exampleModuleRef, exampleProducers, exampleTypes } from "./manifest.js";
export { decodeExampleSurface } from "./surface.js";
export { decodeExampleStyle } from "./style.js";
diff --git a/examples/minimal-author-package/packages/example-component/src/manifest.ts b/examples/minimal-author-package/packages/example-component/src/manifest.ts
index d8d6a320..e4de1186 100644
--- a/examples/minimal-author-package/packages/example-component/src/manifest.ts
+++ b/examples/minimal-author-package/packages/example-component/src/manifest.ts
@@ -6,6 +6,7 @@ import { semanticTrackTypes } from "@hypit/semantic-track";
import { temporalTypes } from "@hypit/temporal";
import { mediaTypes } from "@hypit/media";
import { svsRecipeType } from "@hypit/svs";
+import { artifactTypes } from "@hypit/artifact";
const previewImage = (file: string) => ({
mediaType: "image/png",
@@ -19,27 +20,35 @@ export const exampleTypes = {
text: { module: exampleModuleRef, name: "ExampleText" },
mediaSlot: { module: exampleModuleRef, name: "ExampleMediaSlot" },
style: { module: exampleModuleRef, name: "ExampleStyle" },
+ itemSet: { module: exampleModuleRef, name: "ExampleItemSet" },
} satisfies Record<string, TypeRef>;
export const exampleProducers = {
renderBox: { module: exampleModuleRef, name: "render-example-box" },
renderText: { module: exampleModuleRef, name: "render-example-text" },
renderMedia: { module: exampleModuleRef, name: "render-example-media-slot" },
+ appendItems: { module: exampleModuleRef, name: "append-example-items" },
} satisfies Record<string, ProducerRef>;
export const exampleManifest: ModuleManifest = {
format: "hypit.module@1", name: exampleModuleRef.name, version: exampleModuleRef.version,
dependencies: [
{ module: compositionTypes.visualTrack.module },
+ { module: mediaTypes.fontStack.module },
{ module: programSpaceTypes.programSpace.module },
{ module: semanticTrackTypes.track.module },
+ { module: svsRecipeType.module },
{ module: temporalTypes.window.module },
],
types: Object.values(exampleTypes).map(({ name }) => ({ name })),
capabilities: [],
producers: Object.values(exampleProducers).map((producer) => ({
name: producer.name,
- inputs: [{ name: "space", type: programSpaceTypes.programSpace }],
- outputs: [{ name: "track", type: compositionTypes.visualTrack }],
+ inputs: producer === exampleProducers.appendItems
+ ? [{ name: "previous", type: exampleTypes.itemSet }, { name: "item", type: exampleTypes.itemSet }]
+ : [{ name: "space", type: programSpaceTypes.programSpace }, ...(producer === exampleProducers.renderMedia ? [{ name: "media", type: artifactTypes.blob }] : [])],
+ outputs: producer === exampleProducers.appendItems
+ ? [{ name: "set", type: exampleTypes.itemSet }]
+ : [{ name: "track", type: compositionTypes.visualTrack }],
needs: [],
})),
};
@@ -60,7 +69,7 @@ const vocabulary = (summary: string, example: string) => ({
export const exampleMarkupSurfaces = [
{ name: "box", tag: "Box", mode: "structured", outputs: [exampleTypes.box, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A framed box surface.", "<example:Box id=\"box\" semantic={speech.semantic}/>") , preview: previewImage("Box.png") } },
{ name: "text", tag: "Text", mode: "structured", outputs: [exampleTypes.text, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A text-bearing surface.", "<example:Text id=\"title\" semantic={speech.semantic}>Hello</example:Text>"), preview: previewImage("Box.png") } },
- { name: "media-slot", tag: "MediaSlot", mode: "structured", outputs: [exampleTypes.mediaSlot, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A media slot whose content is a graph input.", "<example:MediaSlot id=\"shot\" semantic={speech.semantic}/>") , preview: previewImage("Box.png") } },
+ { name: "media-slot", tag: "MediaSlot", mode: "structured", outputs: [exampleTypes.mediaSlot, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A media slot whose content is a graph input.", "<example:MediaSlot id=\"shot\" semantic={speech.semantic} media={shot-media}/>") , attributes: [...vocabulary("", "").attributes, { name: "media", kind: "reference" as const, required: false, accepts: [artifactTypes.blob], summary: "Optional image or video Blob Artifact." }], preview: previewImage("Box.png") } },
{ name: "style", tag: "Style", mode: "structured", outputs: [exampleTypes.style], vocabulary: {
summary: "Decodes one SVS Recipe and exact FontStackRef into a Style value.",
attributes: [
diff --git a/examples/minimal-author-package/packages/example-component/src/surface.ts b/examples/minimal-author-package/packages/example-component/src/surface.ts
index 5c5d2283..188332dd 100644
--- a/examples/minimal-author-package/packages/example-component/src/surface.ts
+++ b/examples/minimal-author-package/packages/example-component/src/surface.ts
@@ -3,6 +3,7 @@ import { exampleBoxFragment, exampleMediaFragment, exampleTextFragment } from ".
import { exampleMarkupSurfaces, exampleTypes } from "./manifest.js";
import { mediaTypes } from "@hypit/media";
import { svsRecipeType } from "@hypit/svs";
+import { artifactTypes } from "@hypit/artifact";
function text(element: StructuredElement, name: string): string {
const value = element.attributes[name];
@@ -33,6 +34,8 @@ export const decodeExampleSurface: StructuredSurfaceHandler = ({ element, resolv
const fragment = surface.name === "box" ? exampleBoxFragment : surface.name === "text" ? exampleTextFragment : exampleMediaFragment;
const type = surface.name === "box" ? exampleTypes.box : surface.name === "text" ? exampleTypes.text : exampleTypes.mediaSlot;
const record: SurfaceRecordDraft = { id: `${id}.value`, type, value: { kind: "inline", value: { id } }, range: element.range };
- const component: SurfaceComponentDraft = { id, fragment: fragment.id, inputs: { semantic: semantic.ref }, outputs: { track: `${id}.track` }, range: element.range };
+ const media = element.attributes.media === undefined ? undefined : reference(element, "media", resolveReference);
+ if (media !== undefined && (media.type.module.name !== artifactTypes.blob.module.name || media.type.name !== artifactTypes.blob.name)) throw new Error(`${element.name}.media must be a Blob Artifact.`);
+ const component: SurfaceComponentDraft = { id, fragment: fragment.id, inputs: { semantic: semantic.ref, ...(media === undefined ? {} : { media: media.ref }) }, outputs: { track: `${id}.track` }, range: element.range };
return { records: [record], components: [component], fragments: [fragment], exports: [`${id}.value`, `${id}.track`] };
};