@hypit/hypit 0.0.1 → 0.1.1

package/packages/grok-imagine/src/index.ts

@@ -0,0 +1,174 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@hypit/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@hypit/generation";
+import type {
+  SurfaceAttributeVocabulary,
+  SurfaceChildVocabulary,
+  SurfacePortVocabulary,
+  SurfaceVocabulary,
+} from "@hypit/markup";
+import { defineExactModelModule } from "@hypit/model-kit";
+import { textTypes } from "@hypit/text";
+
+export const grokImagineModuleRef = { name: "@hypit/grok-imagine", version: "1" } as const;
+export const grokImagineModels = ["grok-imagine-video", "grok-imagine-video-1.5-preview"] as const;
+export type GrokImagineModel = typeof grokImagineModels[number];
+
+export const grokImagineVideoPorts: GenerationPortTable = sealGenerationPortTable({
+  model: "grok-imagine-video",
+  result: "video",
+  ports: [
+    { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },
+    {
+      name: "aspectRatio",
+      value: { kind: "enum", values: ["2:3", "3:2", "1:1", "16:9", "9:16"] },
+      minItems: 1,
+      maxItems: 1,
+    },
+    { name: "resolution", value: { kind: "enum", values: ["480p", "720p", "1080p"] }, minItems: 1, maxItems: 1 },
+    { name: "duration", value: { kind: "number", integer: true, minimum: 6, maximum: 30 }, minItems: 1, maxItems: 1 },
+    { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 7 },
+  ],
+  requires: [],
+});
+
+export const grokImagine15PreviewPorts: GenerationPortTable = sealGenerationPortTable({
+  model: "grok-imagine-video-1.5-preview",
+  result: "video",
+  ports: [
+    { name: "prompt", value: { kind: "text", maxChars: 4_096 }, minItems: 1, maxItems: 1 },
+    {
+      name: "aspectRatio",
+      value: { kind: "enum", values: ["auto", "2:3", "3:2", "1:1", "16:9", "9:16"] },
+      minItems: 1,
+      maxItems: 1,
+    },
+    { name: "resolution", value: { kind: "enum", values: ["480p", "720p", "1080p"] }, minItems: 1, maxItems: 1 },
+    { name: "duration", value: { kind: "number", integer: true, minimum: 1, maximum: 15 }, minItems: 1, maxItems: 1 },
+    { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 7 },
+  ],
+  requires: [],
+});
+
+export const grokImaginePorts: Readonly<Record<GrokImagineModel, GenerationPortTable>> = {
+  "grok-imagine-video": grokImagineVideoPorts,
+  "grok-imagine-video-1.5-preview": grokImagine15PreviewPorts,
+};
+
+export function sealGrokImagineRequest(
+  model: GrokImagineModel,
+  ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+  return sealGenerationPortRequest(grokImaginePorts[model], ports);
+}
+
+const grokImagineBaseDefinition = defineExactModelModule({
+  module: grokImagineModuleRef,
+  endpoints: [
+    {
+      key: "video",
+      requestTypeName: "GrokImagineVideoRequest",
+      producerName: "request-grok-imagine-video",
+      ports: grokImagineVideoPorts,
+    },
+    {
+      key: "preview-1.5",
+      requestTypeName: "GrokImagine15PreviewRequest",
+      producerName: "request-grok-imagine-preview-1-5",
+      ports: grokImagine15PreviewPorts,
+    },
+  ],
+});
+
+export const grokImagineEndpoints = grokImagineBaseDefinition.endpoints;
+export const grokImagineComponent = grokImagineBaseDefinition.component;
+const surface = (
+  name: "video" | "preview-video",
+  tag: "Video" | "PreviewVideo",
+  endpoint: NonNullable<(typeof grokImagineEndpoints)["video" | "preview-1.5"]>,
+  vocabulary: SurfaceVocabulary,
+) => ({
+  name,
+  tag,
+  mode: "structured" as const,
+  outputs: [endpoint.draftType, endpoint.mediaBindings.images!.type],
+  vocabulary,
+});
+
+const grokImagineBaseAttributes: readonly SurfaceAttributeVocabulary[] = [
+  { name: "id", kind: "identifier", required: true,
+    summary: "Names this generation so its video Artifact can be referenced elsewhere in the Source." },
+  { name: "prompt", kind: "reference", required: true, accepts: [textTypes.text],
+    summary: "Selects the Text the model generates from." },
+  { name: "resolution", kind: "literal", required: true,
+    values: ["480p", "720p", "1080p"],
+    summary: "Sets the picture height of the generated video." },
+];
+
+function grokImagineVideoAttributes(preview: boolean): readonly SurfaceAttributeVocabulary[] {
+  return [
+    ...grokImagineBaseAttributes,
+    { name: "duration", kind: "literal", required: true,
+      summary: "Sets the length of the generated video in whole seconds." },
+    { name: "aspect-ratio", kind: "literal", required: true,
+      values: preview
+        ? ["auto", "2:3", "3:2", "1:1", "16:9", "9:16"]
+        : ["2:3", "3:2", "1:1", "16:9", "9:16"],
+      summary: "Sets the width-to-height ratio of the generated video." },
+  ];
+}
+
+const grokImagineVideoChildren: readonly SurfaceChildVocabulary[] = [
+  { tag: "Reference", cardinality: "many",
+    summary: "Attaches one image Artifact the model generates from.",
+    attributes: [
+      { name: "image", kind: "reference", required: true, accepts: [artifactTypes.blob],
+        summary: "Selects the image Artifact this reference contributes." },
+    ] },
+];
+
+const grokImagineVideoPortVocabulary: readonly SurfacePortVocabulary[] = [
+  { name: "video", type: artifactTypes.blob,
+    summary: "The generated video Artifact." },
+];
+
+const grokImagineReferenceNote = "`Reference` accepts only an `image` reference to an image Blob, is empty, and repeats at most seven times.";
+
+export const grokImagineMarkupSurfaces = [
+    surface("video", "Video", grokImagineEndpoints.video!, {
+      summary: "Generates one video Artifact from a Text prompt and up to seven reference images with the Grok Imagine video model.",
+      attributes: grokImagineVideoAttributes(false),
+      children: grokImagineVideoChildren,
+      ports: grokImagineVideoPortVocabulary,
+      example: [
+        '<grok:Video id="clip" prompt={prompt} duration="6" aspect-ratio="9:16" resolution="720p">',
+        "  <grok:Reference image={person.image}/>",
+        "</grok:Video>",
+      ].join("\n"),
+      notes: [
+        grokImagineReferenceNote,
+        "`duration` is a whole number of seconds between 6 and 30.",
+        "The element carries no text content.",
+      ],
+    }),
+    surface("preview-video", "PreviewVideo", grokImagineEndpoints["preview-1.5"]!, {
+      summary: "Generates one video Artifact from a Text prompt and up to seven reference images with the Grok Imagine 1.5 preview video model.",
+      attributes: grokImagineVideoAttributes(true),
+      children: grokImagineVideoChildren,
+      ports: grokImagineVideoPortVocabulary,
+      example: '<grok:PreviewVideo id="preview" prompt={previewPrompt} duration="6" aspect-ratio="9:16" resolution="720p"/>',
+      notes: [
+        grokImagineReferenceNote,
+        "`duration` is a whole number of seconds between 1 and 15.",
+        "The element carries no text content.",
+      ],
+    }),
+  ] as const;
+
+export const grokImagineManifest = {
+  ...grokImagineBaseDefinition.manifest,
+};
+export const grokImagineDefinition = {
+  ...grokImagineBaseDefinition,
+  manifest: grokImagineManifest,
+};

package/packages/grok-imagine/src/surface.ts

@@ -0,0 +1,149 @@
+import { artifactTypes } from "@hypit/artifact";
+import { generationPort, sealGenerationMediaBinding, sealGenerationRequestDraft } from "@hypit/generation";
+import type { GenerationMediaPort, GenerationPortValue } from "@hypit/generation";
+import {
+  createExactModelPrimaryGenerationFragment,
+  exactModelMediaInputNames,
+  exactModelTextInputName,
+} from "@hypit/model-kit";
+import type { ExactModelEndpoint } from "@hypit/model-kit";
+import type {
+  MarkupAttributeValue,
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+} from "@hypit/markup";
+import type { CanonicalValue, TypeRef } from "@hypit/protocol";
+import { textTypes, verifyText } from "@hypit/text";
+
+import { grokImagineEndpoints } from "./index.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function localName(name: string): string {
+  return name.includes(":") ? name.slice(name.lastIndexOf(":") + 1) : name;
+}
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+  return left.name === right.name
+    && left.module.name === right.module.name
+    && left.module.version === right.module.version;
+}
+
+function exact(element: StructuredElement, allowed: readonly string[], required = allowed): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+  assert(unknown.length === 0, `${element.name} does not accept ${unknown[0]}`);
+  const missing = required.filter((name) => element.attributes[name] === undefined);
+  assert(missing.length === 0, `${element.name} requires ${missing.join(", ")}`);
+}
+
+function text(element: StructuredElement, name: string): string {
+  const value = element.attributes[name];
+  assert(typeof value === "string" && value.trim().length > 0, `${element.name}.${name} must be text`);
+  return value.trim();
+}
+
+function integer(element: StructuredElement, name: string): number {
+  const value = Number(text(element, name));
+  assert(Number.isSafeInteger(value), `${element.name}.${name} must be an integer`);
+  return value;
+}
+
+function ref(
+  element: StructuredElement,
+  name: string,
+  type: TypeRef,
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  assert(typeof value === "object" && value.kind === "reference", `${element.name}.${name} must be a reference`);
+  const result = resolve(value.path);
+  assert(result !== undefined && sameType(result.type, type), `${element.name}.${name} has the wrong type`);
+  return result;
+}
+
+function decoder(endpoint: ExactModelEndpoint): StructuredSurfaceHandler {
+  return ({ element, resolveReference }) => {
+    exact(element, ["id", "prompt", "duration", "aspect-ratio", "resolution"]);
+    const id = text(element, "id");
+    const prompt = ref(element, "prompt", textTypes.text, resolveReference);
+    if (prompt.record !== undefined) {
+      assert(prompt.record.value.kind === "inline", `${element.name}.prompt must reference Text`);
+      verifyText(prompt.record.value.value);
+    }
+    const imagePort = generationPort(endpoint.ports, "images");
+    assert(imagePort.value.kind === "media", "Grok images port is not media");
+    const images: SurfaceResolvedReference[] = [];
+    for (const child of element.children) {
+      if (child.kind === "text") {
+        assert(child.value.trim().length === 0, `${element.name} accepts only Reference children`);
+        continue;
+      }
+      assert(localName(child.name) === "Reference", `${element.name} accepts only Reference children`);
+      exact(child, ["image"]);
+      assert(!child.children.some((item) => item.kind === "element" || item.value.trim()), `${child.name} must be empty`);
+      const image = ref(child, "image", artifactTypes.blob, resolveReference);
+      if (image.record !== undefined) {
+        assert(image.record.value.kind === "blob" && image.record.value.mediaType.startsWith("image/"),
+          `${child.name}.image must be image media`);
+      }
+      images.push(image);
+    }
+    assert(images.length <= imagePort.maxItems, `${element.name} accepts at most ${imagePort.maxItems} references`);
+    const ports: Record<string, readonly GenerationPortValue[]> = {
+      duration: [integer(element, "duration")],
+      aspectRatio: [text(element, "aspect-ratio")],
+      resolution: [text(element, "resolution")],
+    };
+    const draft = sealGenerationRequestDraft(endpoint.ports, ports);
+    const records: Array<{
+      id: string;
+      type: TypeRef;
+      value: { kind: "inline"; value: CanonicalValue };
+      range: StructuredElement["range"];
+    }> = [{
+      id: `${id}.draft`,
+      type: endpoint.draftType,
+      value: { kind: "inline", value: draft as unknown as CanonicalValue },
+      range: element.range,
+    }];
+    const inputs: Record<string, SurfaceResolvedReference["ref"] | { kind: "record"; id: string }> = {
+      draft: { kind: "record", id: `${id}.draft` },
+      [exactModelTextInputName("prompt")]: prompt.ref,
+    };
+    const media = images.map((image, index) => {
+      const name = `image-${String(index + 1).padStart(4, "0")}`;
+      const bindingId = `${id}.${name}.binding`;
+      records.push({
+        id: bindingId,
+        type: endpoint.mediaBindings.images!.type,
+        value: {
+          kind: "inline",
+          value: sealGenerationMediaBinding(imagePort as GenerationMediaPort, { role: "image" }) as unknown as CanonicalValue,
+        },
+        range: element.range,
+      });
+      const names = exactModelMediaInputNames(name);
+      inputs[names.binding] = { kind: "record", id: bindingId };
+      inputs[names.artifact] = image.ref;
+      return { name, port: "images" } as const;
+    });
+    const fragment = createExactModelPrimaryGenerationFragment(endpoint, media, [{ name: "prompt", port: "prompt" }]);
+    return {
+      records,
+      fragments: [fragment],
+      components: [{
+        id,
+        fragment: fragment.id,
+        inputs,
+        outputs: { video: `${id}.video` },
+        range: element.range,
+      }],
+    };
+  };
+}
+
+export const decodeGrokImagineVideoSurface = decoder(grokImagineEndpoints.video!);
+export const decodeGrokImaginePreviewVideoSurface = decoder(grokImagineEndpoints["preview-1.5"]!);

package/packages/host/README.md

@@ -0,0 +1,5 @@
+# `@hypit/host`
+
+The minimal opaque `HostFacet` envelope: an ABI, logical offers, locked identity and inert
+implementation. Package loading can carry it without learning what it does; only the exact Host ABI
+may interpret it. Source and asset sessions live separately in `@hypit/workspace`.

package/packages/host/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@hypit/host",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  }
+}

package/packages/host/src/facet.ts

@@ -0,0 +1,6 @@
+/** One package contribution understood only by the Host that owns its ABI. */
+export type HostFacet = {
+  readonly abi: string;
+  readonly offers?: readonly string[];
+  readonly implementation: unknown;
+};

package/packages/host/src/frontend.ts

@@ -0,0 +1,56 @@
+import type { HostFacet } from "./facet.js";
+
+export type FrontendImplementation = {
+  readonly id: string;
+};
+
+export type FrontendHostFacet<
+  Kind extends string,
+  Frontend extends FrontendImplementation,
+> = HostFacet & {
+  readonly offers: readonly [string];
+  readonly implementation: {
+    readonly kind: Kind;
+    readonly frontend: Frontend;
+  };
+};
+
+/** Build the common inert declaration shared by every self-described Source Frontend. */
+export function createFrontendHostFacet<
+  Kind extends string,
+  Frontend extends FrontendImplementation,
+>(abi: string, kind: Kind, frontend: Frontend): FrontendHostFacet<Kind, Frontend> {
+  if (abi.trim().length === 0 || kind.trim().length === 0
+    || frontend.id.trim().length === 0) {
+    throw new Error(`${kind || "Source"} Frontend Host facet has an invalid identity`);
+  }
+  return {
+    abi,
+    offers: [frontend.id],
+    implementation: {
+      kind,
+      frontend,
+    },
+  };
+}
+
+/** Select and validate Frontends owned by one exact Host ABI and Frontend kind. */
+export function frontendsFromHostFacets<
+  Kind extends string,
+  Frontend extends FrontendImplementation,
+>(abi: string, kind: Kind, facets: readonly HostFacet[]): readonly Frontend[] {
+  const values: Frontend[] = [];
+  for (const facet of facets) {
+    if (facet.abi !== abi || facet.implementation === null
+      || typeof facet.implementation !== "object" || Array.isArray(facet.implementation)) continue;
+    const implementation = facet.implementation as { readonly kind?: unknown; readonly frontend?: unknown };
+    if (implementation.kind !== kind) continue;
+    const frontend = implementation.frontend;
+    if (frontend === null || typeof frontend !== "object" || Array.isArray(frontend)
+      || typeof (frontend as { readonly id?: unknown }).id !== "string") {
+      throw new Error(`${kind} Frontend Host facet has an invalid implementation`);
+    }
+    values.push(frontend as Frontend);
+  }
+  return values;
+}

package/packages/host/src/index.ts

@@ -0,0 +1,9 @@
+export type { HostFacet } from "./facet.js";
+export {
+  createFrontendHostFacet,
+  frontendsFromHostFacets,
+} from "./frontend.js";
+export type {
+  FrontendHostFacet,
+  FrontendImplementation,
+} from "./frontend.js";

package/packages/hyperframes/README.md

@@ -0,0 +1,69 @@
+# @hypit/hyperframes
+
+Deterministic reference lowering from the generic `Composition` contract to a portable
+`HyperframesDocument`.
+
+This package renders `hypit.visual-ir@1` structural elements and `hypit.browser-program@1`
+local programs. Structural elements cover ordinary boxes, exact-font text and frame-sampled media.
+A browser program carries HTML, CSS and frame-driven JavaScript for a component's own composition.
+Track and Composition remain owned by `@hypit/composition`; the browser format is owned here.
+
+This package understands only `VisualTrack`, `ProgramSpace` and canvas geometry. It
+does not know Caption, Speech, B-roll, Seedance or any other author-domain component. It flattens
+every Track's Presents, orders them by their own absolute stacking keys and emits frame-bound local
+keyframes. An authoring Track never becomes an isolated render stacking surface.
+
+It deliberately ignores `AudioTrack`. HyperFrames produces a silent visual fact; the media pipeline
+compiles and renders program audio separately, then an explicit mux Provider joins the two. Changing
+audio can therefore never be implemented by secretly changing HyperFrames HTML or its renderer.
+
+Media remains resource-referenced in compiled HTML as `hypit-resource://` placeholders. The
+document separately carries each dependency's complete `BlobRef` (Resource id, byte count and MIME), so
+a Provider can verify and name staged bytes without guessing from the hash. A local or hosted
+render Runtime calls `materializeHyperframesHtml()` with its own Artifact URL resolver before
+handing the HTML to HyperFrames. That environment-specific materialization is not a new compiled
+Record and does not change the compiled document.
+
+The document exposes its render domain directly rather than asking an Endpoint to scrape HTML:
+exact rational `frameRate`, integer `frameCount`, and canvas dimensions are explicit document
+content. The ProgramSpace relationship is an input edge of the Producer and is not copied into the
+document as lineage metadata. Legal frame addresses are exactly `[0, frameCount)`. A local worker pool or a
+hosted renderer may independently evaluate any legal frame or half-open chunk; partition size and
+worker count are Runtime policy, not author intent and not Core graph nodes. The emitted root also
+uses the rational HyperFrames `data-fps` form, so NTSC rates do not drift through a decimal guess.
+
+Exact `FontArtifactRef` dependencies lower to generated `@font-face` declarations with font
+synthesis disabled; a Unicode-range-sharded logical face emits one rule per exact source. Terminal
+text without a non-empty exact Font stack is invalid rather than falling back to machine fonts.
+`CompositableSurfaceRef` values lower as typed image/video surfaces carrying
+their declared alpha, color-space and frame-domain metadata. The package never guesses either fact
+from a user font name or filename extension. The document carries a deduplicated typed Surface set
+beside its Artifact set so a staging Runtime can verify the exact bytes before rendering.
+
+The ordinary test suite validates deterministic HTML, frame sampling markers and Artifact collection.
+The local Provider owns the Chrome integration tests. Run its tests with `HYPIT_BROWSER_TESTS=1`
+to exercise real multi-worker rendering, compare selected video frames with a full render, and check
+straight-alpha composition. These tests use the engine capture API and require Chrome and FFmpeg.
+
+## Local browser programs
+
+`browserProgram({ html, css, setup, data }, artifacts)` builds a program payload. Place it on a
+`kind: "program"` VisualElement inside a normal Present. `html` is a local fragment; `{{child-id}}`
+places a direct typed child. Every child is placed once, including sampled video and exact-font text.
+This keeps actual video available to the renderer's exact source-frame preparation.
+
+CSS is scoped to the generated program root with `@scope`; `:scope` styles that root. The HTML can
+contain arbitrary local structure, SVG, internal stacking, masks and backdrop filters. The optional
+`setup` string is a JavaScript function body with `root` and `data` arguments. It returns a synchronous
+`render(localFrame)` function, evaluated on initial load and every `hf-seek`. Express animation state
+as a function of this frame and inputs so any worker can begin at any frame. Async work belongs to
+material preparation before rendering; browser resources belong in the program's declared artifacts.
+Use `hyperframesResourceUri(artifact.resource)` in resource-bearing markup or CSS.
+
+Ordinary child sampling follows the Present clock. Reframing the parent leaves source playback
+unchanged. `projectSemanticMedia` from `@hypit/hypit/semantic-track` gives a component selected prepared
+clips with their exact program and source spans. Speech audio is an independently selected Track.
+
+`program.format` is explicit: this backend reports an unsupported format rather than interpreting
+another renderer's program. Core and the build graph do not contain browser-specific cases.
+The `examples/semantic-composition` project demonstrates a complete package using this interface.

package/packages/hyperframes/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@hypit/hyperframes",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./project": "./src/project.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/visual-ir": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/caption": "workspace:*",
+    "@hypit/caption-fine": "workspace:*",
+    "@hypit/deck-track": "workspace:*",
+    "@hypit/fonts-open": "workspace:*",
+    "@hypit/media-track": "workspace:*",
+    "@hypit/ranking": "workspace:*",
+    "@hypit/screen-overlay": "workspace:*",
+    "@hypit/script": "workspace:*",
+    "@hypit/spatial": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/typography-track": "workspace:*"
+  }
+}

package/packages/hyperframes/src/activation.ts

@@ -0,0 +1,8 @@
+import { hyperframesComponent, hyperframesManifest } from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: hyperframesManifest }],
+  components: [hyperframesComponent],
+};
+export default hypitPackage;

package/packages/hyperframes/src/browser-program.ts

@@ -0,0 +1,79 @@
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, CanonicalValue } from "@hypit/protocol";
+import type { VisualProgramElement } from "@hypit/composition";
+
+export const BROWSER_PROGRAM_FORMAT = "hypit.browser-program@1" as const;
+
+export type BrowserProgram = {
+  /** HTML fragment. {{child-id}} inserts an owned VisualElement, including frame-sampled video. */
+  readonly html: string;
+  /** CSS in an @scope rooted at this program's element. */
+  readonly css?: string;
+  /** Function body with (root, data) arguments; returns a synchronous render(localFrame) function. */
+  readonly setup?: string;
+  readonly data?: CanonicalValue;
+};
+
+export function browserProgram(value: BrowserProgram, artifacts: readonly BlobRef[] = []): VisualProgramElement["program"] {
+  return { format: BROWSER_PROGRAM_FORMAT, payload: canonicalize(value) as VisualProgramElement["program"]["payload"], artifacts: [...artifacts] };
+}
+
+export function readBrowserProgram(program: VisualProgramElement["program"]): BrowserProgram {
+  if (program.format !== BROWSER_PROGRAM_FORMAT) {
+    throw new Error(`HyperFrames does not support visual program format ${program.format}.`);
+  }
+  const value = program.payload as unknown as BrowserProgram;
+  if (value === null || typeof value !== "object" || typeof value.html !== "string"
+    || (value.css !== undefined && typeof value.css !== "string")
+    || (value.setup !== undefined && typeof value.setup !== "string")) {
+    throw new Error("Browser program requires HTML and optional CSS and setup source.");
+  }
+  return value;
+}
+
+export function browserProgramHtml(program: BrowserProgram, children: ReadonlyMap<string, string>): string {
+  const used = new Set<string>();
+  const result = program.html.replace(/\{\{([^{}]+)\}\}/gu, (_match, name: string) => {
+    const child = children.get(name);
+    if (child === undefined || used.has(name)) throw new Error(`Browser program slot ${name} is missing or repeated.`);
+    used.add(name);
+    return child;
+  });
+  for (const name of children.keys()) {
+    if (!used.has(name)) throw new Error(`Browser program does not place owned child ${name}.`);
+  }
+  return result;
+}
+
+/** JSON is embedded as data, so author text cannot close the surrounding script element. */
+const scriptJson = (value: unknown): string => JSON.stringify(value).replaceAll("<", "\\u003c");
+
+export function browserProgramScript(entries: readonly {
+  readonly id: string;
+  readonly startFrame: number;
+  readonly durationFrames: number;
+  readonly program: BrowserProgram;
+}[], numerator: number, denominator: number): string {
+  return `(() => {
+    const fail = error => { window.__hypitBrowserProgramError = String(error?.stack || error); };
+    const entries = ${scriptJson(entries)};
+    const renders = entries.map(entry => {
+      const root = document.getElementById(entry.id);
+      try {
+        const render = entry.program.setup === undefined ? () => {} :
+          new Function('root', 'data', entry.program.setup)(root, entry.program.data);
+        if (typeof render !== 'function') throw new Error('Browser program setup must return render(localFrame).');
+        return { ...entry, render };
+      } catch (error) { fail(error); return { ...entry, render: () => {} }; }
+    });
+    const apply = time => {
+      const frame = Math.round(Number(time || 0) * ${numerator} / ${denominator});
+      for (const entry of renders) {
+        try { entry.render(Math.max(0, Math.min(entry.durationFrames, frame - entry.startFrame))); }
+        catch (error) { fail(error); }
+      }
+    };
+    apply(0);
+    window.addEventListener('hf-seek', event => apply(event.detail?.time));
+  })();`;
+}

package/packages/hyperframes/src/component.ts

@@ -0,0 +1,32 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { ProgramSpace } from "@hypit/program-space";
+import type { Composition } from "@hypit/composition";
+import type { CanonicalValue, StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+
+import { compileHyperframesDocument } from "./document.js";
+import { hyperframesProducers } from "./manifest.js";
+
+function inline(value: StoredValue, subject: string): CanonicalValue {
+  if (value.kind !== "inline") throw new Error(`${subject} must be inline`);
+  return value.value;
+}
+
+/** Trusted deterministic lowering only; this component never renders frames or reads Artifacts. */
+export const hyperframesComponent = {
+  producers: [{
+    producer: hyperframesProducers.compile,
+    handler: ({ inputs }) => ({
+      outputs: {
+        document: {
+          kind: "inline",
+          value: canonicalize(compileHyperframesDocument(
+            inline(inputs.composition!.value, "Composition") as unknown as Composition,
+            inline(inputs.space!.value, "ProgramSpace") as unknown as ProgramSpace,
+          )),
+        },
+      },
+      needs: {},
+    }),
+  }],
+} satisfies ComponentPackage;