@hypit/hypit 0.0.1 → 0.1.1

package/examples/minimal-author-package/packages/example-component/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/examples/semantic-composition/README.md

@@ -0,0 +1,35 @@
+# Semantic composition
+
+`packages/responsive-explainer` is an ordinary project component. Its video viewport moves from
+full screen into a side portrait while a diagram appears in the space it releases. The same prepared
+video continues playing. A projected Moment triggers the layout change; an independently projected
+Window defines the scene's lifetime. Captions and other independent contributions can remain peers.
+
+The package demonstrates HTML, CSS, SVG and frame-driven JavaScript inside one VisualTrack Present,
+with typed child video sampling and exact-font text. It uses public `@hypit/hypit/*` imports. No component
+name is registered in Core or in the renderer.
+
+Copy the package into a video's `packages/`, select the installed Hypit version for its development
+dependency, build it and declare it in the project's ordinary package configuration. The package
+README shows its Source use and explains the timing and material boundaries.
+
+## Authored chat animation
+
+`chat.svml` is an eight-second composition drawn entirely in a project component. It needs no Script,
+WhisperX, image generation or source video. Four messages arrive on authored times; the same
+`@example/chat-scene` component accepts Script Moments when used beside a speaking performance.
+
+From the repository after installing its dependencies:
+
+```bash
+pnpm build:public-types
+pnpm --filter @example/chat-scene build
+node bin/hypit.mjs check examples/semantic-composition/chat.svml --workspace examples/semantic-composition
+node bin/hypit.mjs build examples/semantic-composition/chat.svrun --workspace examples/semantic-composition --runtime examples/semantic-composition/hypit.runtime.json --follow
+```
+
+The Profile selects local HyperFrames and FFmpeg. Use the machine's prepared browser/media tools;
+there is no hosted generation account in this example. The final Output is `final.video`. The same
+Run can be opened in Studio, where its component lane and physical clock work without a Script lane.
+For an independent project, install `@hypit/hypit`, copy the component into `packages/`, replace its workspace
+dependency with the installed Hypit version, and build the package normally.

package/examples/semantic-composition/chat.svml

@@ -0,0 +1,25 @@
+<?svml using="@hypit/markup@1"?>
+<svml>
+  <import as="time" from="@hypit/program-space@1"/>
+  <import as="spatial" from="@hypit/spatial@1"/>
+  <import as="fonts" from="@hypit/fonts-open@1"/>
+  <import as="chat" from="@example/chat-scene@1"/>
+  <import as="film" from="@hypit/film@1"/>
+  <import as="render" from="@hypit/render-hyperframes@1"/>
+  <import as="style" source="./chat.svs"/>
+
+  <time:Space id="animation" frame-rate="30" duration="8s"/>
+  <spatial:Canvas id="canvas" width="540" height="960"/>
+  <fonts:Stack id="font" family="inter" weight="600" style="normal"/>
+  <chat:Scene id="conversation" space={animation} canvas={canvas} font={font}
+    during="program" title="Launch crew">
+    <chat:Message id="question" sender="Maya" side="left" at="0.5s" text="Are we ready to launch?"/>
+    <chat:Message id="reply" sender="Leo" side="right" at="2s" text="The video is ready."/>
+    <chat:Message id="turn" sender="Maya" side="left" at="3.5s" text="Great. One tiny change..."/>
+    <chat:Message id="reveal" sender="Leo" side="right" at="5.2s" text="I left the whole scene editable."/>
+  </chat:Scene>
+  <film:Film id="main" canvas={canvas} space={animation} appearance={style.film.main}>
+    <film:Track source={conversation.track}/>
+  </film:Film>
+  <render:Video id="final" composition={main.composition} space={animation}/>
+</svml>

package/examples/semantic-composition/chat.svrun

@@ -0,0 +1,6 @@
+<?svml using="@hypit/run-markup@1"?>
+
+<svrun version="1">
+  <author source="./chat.svml"/>
+  <target output="final.video"/>
+</svrun>

package/examples/semantic-composition/chat.svs

@@ -0,0 +1,4 @@
+<?svml using="@hypit/svs@1"?>
+<sheet version="1">
+  film.main { background: #142b32; }
+</sheet>

package/examples/semantic-composition/hypit.runtime.json

@@ -0,0 +1,8 @@
+{
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/runtime",
+  "endpoints": {
+    "media.local": { "use": "@hypit/provider-media-local", "config": { "defaultConcurrency": 2 } },
+    "hyperframes.local": { "use": "@hypit/provider-hyperframes-local", "config": { "workers": 2, "defaultConcurrency": 1 } }
+  }
+}

package/examples/semantic-composition/packages/chat-scene/README.md

@@ -0,0 +1,29 @@
+# Chat scene
+
+A project component for a conversation whose arrivals, bubble layout and scrolling belong together.
+Content lives in Source. Every Message has its own `at`; there is no fixed message count.
+
+For speech-led work, bind the message to the words that introduce it:
+
+```svml
+<chat:Scene id="conversation" semantic={speech.semantic} canvas={canvas} font={font}
+  during={story.selection.demo} title="Conversation">
+  <chat:Message id="answer" sender="Maya" side="left" text="Here it is."
+    at={story.moment.answer}/>
+</chat:Scene>
+```
+
+The same component can receive `space={animation}` and `at="2s"` for authored animation. A Scene
+has an outer Window; its message Instants trigger persistent state. `entrance-frames` controls arrival
+and scrolling duration independently of those triggers (default 10). Messages stay visible or scroll
+up as the conversation develops. Message times are on the film clock and must fall inside the Scene.
+
+The Surface uses the shared temporal helpers and expands children to a finite create/append/render
+graph. The rendering function receives ProgramSpace, Window and Instants, so it knows nothing about
+Script parsing, speech models or Runtime. The browser program evaluates any requested frame directly,
+including frames reached by scrubbing, range rendering or concurrent workers.
+
+Compile with `npm run build`. The package uses the public `@hypit/hypit/*` interfaces and can live in any
+video project's `packages/`. It is an example to adapt, not an official component to install for every
+animation. The complete runnable Source is [chat.svml](../../chat.svml); see the surrounding
+example README for commands. `font` receives a FontStack, for example from `fonts:Stack`.

package/examples/semantic-composition/packages/chat-scene/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@example/chat-scene",
+  "version": "0.0.0-dev",
+  "private": true,
+  "type": "module",
+  "hypit": { "activation": "./dist/activation.js" },
+  "exports": { ".": "./dist/render.js" },
+  "files": ["dist", "README.md"],
+  "scripts": { "build": "tsc -p tsconfig.json", "prepack": "npm run build" },
+  "devDependencies": { "@hypit/hypit": "workspace:*", "typescript": "5.9.3", "@types/node": "24.10.1" }
+}

package/examples/semantic-composition/packages/chat-scene/src/activation.ts

@@ -0,0 +1,112 @@
+import { assertAttributes, assertEmptyElement, canonicalize, createMarkupSurfaceHostFacet, sameType, sealGraphFragment, textAttribute } from "@hypit/hypit/author-kit";
+import type { ComponentPackage, FragmentOperation, ModuleManifest, StructuredSurfaceHandler, SurfaceResolvedReference, TypeRef } from "@hypit/hypit/author-kit";
+import { compositionTypes } from "@hypit/hypit/composition";
+import { mediaTypes } from "@hypit/hypit/media";
+import type { FontStackRef } from "@hypit/hypit/media";
+import { programSpaceTypes } from "@hypit/hypit/program-space";
+import type { ProgramSpace } from "@hypit/hypit/program-space";
+import { semanticTrackTypes } from "@hypit/hypit/semantic-track";
+import { spatialTypes } from "@hypit/hypit/spatial";
+import type { CanvasSpace } from "@hypit/hypit/spatial";
+import { assertTemporalInstantFor, temporalTypes } from "@hypit/hypit/temporal";
+import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
+import { createTemporalInstantProjection, createTemporalSpace, createTemporalWindowProjection, resolveTemporalContext,
+  temporalContextAttributeVocabulary, temporalInstantAttributeNames, temporalInstantAttributeVocabulary,
+  temporalWindowAttributeNames, temporalWindowAttributeVocabulary } from "@hypit/hypit/temporal-markup";
+import { renderChat } from "./render.js";
+import type { ChatOptions, Message } from "./render.js";
+
+const module = { name: "@example/chat-scene", version: "1" } as const;
+const types = Object.fromEntries(["Options", "Message", "Messages"].map(name => [name, { module, name }])) as Record<"Options" | "Message" | "Messages", TypeRef>;
+const producers = Object.fromEntries(["empty", "append", "render"].map(name => [name, { module, name }])) as Record<"empty" | "append" | "render", { module: typeof module; name: string }>;
+export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
+  dependencies: [compositionTypes.visualTrack, mediaTypes.fontStack, programSpaceTypes.programSpace,
+    semanticTrackTypes.track, spatialTypes.canvas, temporalTypes.instant].map(type => ({ module: type.module })),
+  types: Object.values(types).map(type => ({ name: type.name })), capabilities: [], producers: [
+    { name: "empty", inputs: [], outputs: [{ name: "messages", type: types.Messages }], needs: [] },
+    { name: "append", inputs: [{ name: "messages", type: types.Messages }, { name: "message", type: types.Message },
+      { name: "at", type: temporalTypes.instant }, { name: "space", type: programSpaceTypes.programSpace }], outputs: [{ name: "messages", type: types.Messages }], needs: [] },
+    { name: "render", inputs: [{ name: "messages", type: types.Messages }, { name: "options", type: types.Options },
+      { name: "space", type: programSpaceTypes.programSpace }, { name: "canvas", type: spatialTypes.canvas },
+      { name: "window", type: temporalTypes.window }, { name: "font", type: mediaTypes.fontStack }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+  ],
+};
+const inline = <T>(record: { value: { kind: string; value?: unknown } } | undefined): T => {
+  if (record?.value.kind !== "inline") throw new Error("Chat inputs must be inline values.");
+  return record.value.value as T;
+};
+const value = (data: unknown) => ({ kind: "inline" as const, value: canonicalize(data) });
+const component: ComponentPackage = { producers: [
+  { producer: producers.empty, handler: () => ({ outputs: { messages: value([]) }, needs: {} }) },
+  { producer: producers.append, handler: ({ inputs }) => {
+    const message = inline<Omit<Message, "at">>(inputs.message), at = inline<TemporalInstant>(inputs.at);
+    const messages = inline<Message[]>(inputs.messages);
+    assertTemporalInstantFor(at, { subjectId: message.id, space: inline<ProgramSpace>(inputs.space) });
+    if (messages.some(item => item.id === message.id) || (messages.at(-1)?.at.frame ?? -1) > at.frame) throw new Error("Chat messages need unique ids and chronological arrival times.");
+    return { outputs: { messages: value([...messages, { ...message, at }]) }, needs: {} };
+  } },
+  { producer: producers.render, handler: ({ inputs }) => ({ outputs: { track: value(renderChat(inline<ProgramSpace>(inputs.space),
+    inline<CanvasSpace>(inputs.canvas), inline<TemporalWindow>(inputs.window), inline<FontStackRef>(inputs.font),
+    inline<Message[]>(inputs.messages), inline<ChatOptions>(inputs.options))) }, needs: {} }) },
+] };
+
+export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id", "semantic", "space", "canvas", "font", "title", "entrance-frames", ...temporalWindowAttributeNames]);
+  const id = textAttribute(element, "id"), context = resolveTemporalContext({ element, resolveReference });
+  const time = createTemporalSpace({ id, element, ...context });
+  const window = createTemporalWindowProjection({ id: `${id}.window`, subjectId: id, element, ...context, space: time.space, resolveReference });
+  const reference = (name: string, type: TypeRef): SurfaceResolvedReference => {
+    const raw = element.attributes[name];
+    if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${name} must be a reference.`);
+    const found = resolveReference(raw.path);
+    if (found === undefined || !sameType(found.type, type)) throw new Error(`${name} has the wrong Type.`);
+    return found;
+  };
+  const options: ChatOptions = { id, title: textAttribute(element, "title"), entranceFrames: Number(element.attributes["entrance-frames"] ?? "10") };
+  const records = [...window.records, { id: `${id}.options`, type: types.Options, value: value(options), range: element.range }];
+  const components = [...time.components, ...window.components], fragments = [...time.fragments, ...window.fragments];
+  const inputs = [{ name: "space", type: programSpaceTypes.programSpace }, { name: "canvas", type: spatialTypes.canvas },
+    { name: "font", type: mediaTypes.fontStack }, { name: "window", type: temporalTypes.window }, { name: "options", type: types.Options }];
+  const bindings: Record<string, SurfaceResolvedReference["ref"]> = { space: time.space.ref, canvas: reference("canvas", spatialTypes.canvas).ref,
+    font: reference("font", mediaTypes.fontStack).ref, window: window.ref, options: { kind: "record", id: `${id}.options` } };
+  const input = (name: string) => ({ kind: "fragment-input" as const, name });
+  const operation = (name: string) => ({ kind: "fragment-operation" as const, operation: name });
+  const operations: FragmentOperation[] = [{ id: "empty", producer: producers.empty, inputs: {}, result: { kind: "output", name: "messages" } }];
+  let previous = "empty", index = 0;
+  for (const child of element.children) {
+    if (child.kind === "text") { if (child.value.trim()) throw new Error("Chat Scene accepts Message children."); continue; }
+    if (child.name.split(":").at(-1) !== "Message") throw new Error("Chat Scene accepts Message children.");
+    assertAttributes(child, ["id", "sender", "text", "side", ...temporalInstantAttributeNames]); assertEmptyElement(child);
+    const messageId = textAttribute(child, "id"), side = textAttribute(child, "side");
+    if (side !== "left" && side !== "right") throw new Error("Message side must be left or right.");
+    const at = createTemporalInstantProjection({ id: `${id}.${messageId}`, subjectId: messageId, element: child, ...context, space: time.space, resolveReference });
+    records.push(...at.records); components.push(...at.components); fragments.push(...at.fragments);
+    const key = `message-${++index}`;
+    records.push({ id: `${id}.${key}`, type: types.Message, value: value({ id: messageId, sender: textAttribute(child, "sender"), text: textAttribute(child, "text"), side }), range: child.range });
+    inputs.push({ name: key, type: types.Message }, { name: `${key}-at`, type: temporalTypes.instant });
+    bindings[key] = { kind: "record", id: `${id}.${key}` }; bindings[`${key}-at`] = at.ref;
+    operations.push({ id: key, producer: producers.append, inputs: { messages: operation(previous), message: input(key), at: input(`${key}-at`), space: input("space") }, result: { kind: "output", name: "messages" } });
+    previous = key;
+  }
+  if (!index) throw new Error("Chat Scene requires a Message.");
+  operations.push({ id: "render", producer: producers.render, inputs: { messages: operation(previous), options: input("options"),
+    space: input("space"), canvas: input("canvas"), font: input("font"), window: input("window") }, result: { kind: "output", name: "track" } });
+  const fragment = sealGraphFragment({ inputs, operations, exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation("render") }] });
+  return { records, fragments: [...fragments, fragment], components: [...components,
+    { id, fragment: fragment.id, inputs: bindings, outputs: { track: `${id}.track` }, range: element.range }], exports: [`${id}.track`] };
+};
+const declaration = { name: "scene", tag: "Scene", mode: "structured" as const,
+  outputs: [compositionTypes.visualTrack, programSpaceTypes.programSpace, temporalTypes.window, temporalTypes.instant, temporalTypes.windowSpec, temporalTypes.instantSpec, ...Object.values(types)],
+  vocabulary: { summary: "A conversation whose message arrivals and scrolling form one visual scene.", attributes: [
+    ...temporalContextAttributeVocabulary, ...temporalWindowAttributeVocabulary,
+    ...["id", "title", "canvas", "font"].map(name => ({ name, kind: "expression" as const, required: true, summary: name })),
+    { name: "entrance-frames", kind: "literal" as const, required: false, summary: "Arrival and scrolling duration; defaults to 10 frames." },
+  ], children: [{ tag: "Message", cardinality: "many" as const, summary: "One authored message and the event that reveals it.", attributes: [
+    ...["id", "sender", "text", "side"].map(name => ({ name, kind: "literal" as const, required: true, summary: name })), ...temporalInstantAttributeVocabulary,
+  ] }], ports: [{ name: "track", type: compositionTypes.visualTrack, summary: "The complete conversation scene." }],
+    example: '<chat:Scene id="chat" semantic={speech.semantic} canvas={canvas} font={font} during="program" title="Conversation"><chat:Message id="answer" sender="Maya" side="left" text="Here it is." at={story.moment.answer}/></chat:Scene>',
+  },
+};
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component],
+  hostFacets: [createMarkupSurfaceHostFacet({ module, declaration, handler: decodeSurface })] };
+export default hypitPackage;

package/examples/semantic-composition/packages/chat-scene/src/render.ts

@@ -0,0 +1,64 @@
+import { sealVisualTrack } from "@hypit/hypit/composition";
+import type { VisualElement } from "@hypit/hypit/composition";
+import { browserProgram } from "@hypit/hypit/hyperframes";
+import type { FontStackRef } from "@hypit/hypit/media";
+import type { ProgramSpace } from "@hypit/hypit/program-space";
+import type { CanvasSpace } from "@hypit/hypit/spatial";
+import { assertTemporalWindowFor } from "@hypit/hypit/temporal";
+import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
+
+export type Message = { id: string; sender: string; text: string; side: "left" | "right"; at: TemporalInstant };
+export type ChatOptions = { id: string; title: string; entranceFrames: number };
+
+/** Layout, arrival and scrolling share one visual component; timing is already resolved. */
+export function renderChat(space: ProgramSpace, canvas: CanvasSpace, window: TemporalWindow,
+  font: FontStackRef, messages: readonly Message[], options: ChatOptions) {
+  assertTemporalWindowFor(window, { subjectId: options.id, space });
+  if (!Number.isSafeInteger(options.entranceFrames) || options.entranceFrames < 1) throw new Error("Chat entrance-frames must be a positive integer.");
+  if (messages.some(message => message.at.frame < window.span.startFrame || message.at.frame >= window.span.endFrameExclusive)) throw new Error("Chat messages must appear inside the scene's window.");
+  let order = 0;
+  const text = (id: string, value: string, size: number, color: string): VisualElement => ({
+    id, kind: "text", parent: "chat", order: ++order, text: value, fonts: font.faces,
+    style: [{ name: "font-size", value: `${size}px` }, { name: "line-height", value: 1.3 }, { name: "color", value: color }],
+  });
+  const children = [text("title", options.title, 30, "#f6ead9"), text("subtitle", "A small change of plan", 16, "#b8c6c5"),
+    ...messages.flatMap((message, index) => [text(`sender-${index}`, message.sender, 16, "#a9b8bd"), text(`text-${index}`, message.text, 27, "#f4efe6")])];
+  const program = browserProgram({
+    html: `<header><div class="status"></div><div>{{title}}<div class="subtitle">{{subtitle}}</div></div></header>
+      <div class="viewport"><div class="messages">${messages.map((message, index) => `<article class="${message.side}" data-message="${index}">
+      <div class="sender">{{sender-${index}}}</div><div class="bubble">{{text-${index}}}</div></article>`).join("")}</div></div>
+      <footer><div class="dots"><i></i><i></i><i></i></div></footer>`,
+    css: `:scope{background:#142b32;overflow:hidden}
+      header{position:absolute;inset:0 0 auto;padding:48px 38px 32px;display:flex;align-items:center;gap:18px;border-bottom:1px solid #35505a;background:#1c353e}
+      .status{width:17px;height:17px;border-radius:50%;background:#abda82;box-shadow:0 0 0 7px #304b43}
+      .subtitle{margin-top:6px}.viewport{position:absolute;inset:164px 32px 96px;overflow:hidden}
+      .messages{position:relative}article{margin:0 0 28px;max-width:84%;transform-origin:left bottom}
+      article.right{margin-left:auto;transform-origin:right bottom}.sender{margin:0 10px 8px}
+      .right .sender{text-align:right}.bubble{padding:20px 23px;border-radius:23px 23px 23px 5px;background:#304953;box-shadow:0 6px 0 #10262d}
+      .right .bubble{background:#47694d;border-radius:23px 23px 5px 23px}footer{position:absolute;inset:auto 0 0;height:90px;background:#1c353e}
+      .dots{display:flex;gap:9px;margin:35px 40px}.dots i{width:10px;height:10px;background:#a6b8b9;border-radius:50%}`,
+    data: { times: messages.map(message => message.at.frame - window.span.startFrame), entrance: options.entranceFrames },
+    setup: `const cards=[...root.querySelectorAll('article')], list=root.querySelector('.messages'), viewport=root.querySelector('.viewport'), dots=root.querySelector('.dots');
+      return frame=>{
+        let last=-1;
+        cards.forEach((card,i)=>{
+          const age=frame-data.times[i], visible=age>=0;
+          card.style.display=visible?'block':'none';
+          if(visible){last=i;const t=Math.min(1,age/data.entrance), p=1-Math.pow(1-t,3);
+            card.style.opacity=String(p);card.style.transform='translateY('+(18*(1-p))+'px) scale('+(0.96+0.04*p)+')';}
+        });
+        const bottom=last<0?0:cards[last].offsetTop+cards[last].offsetHeight;
+        const previous=last<1?0:cards[last-1].offsetTop+cards[last-1].offsetHeight;
+        const t=last<0?1:Math.max(0,Math.min(1,(frame-data.times[last])/data.entrance));
+        const before=Math.max(0,previous-viewport.clientHeight), after=Math.max(0,bottom-viewport.clientHeight);
+        list.style.transform='translateY('+(-(before+(after-before)*(1-Math.pow(1-t,3))))+'px)';
+        dots.style.opacity=last===cards.length-1?'0':'1';
+        [...dots.children].forEach((dot,i)=>dot.style.transform='translateY('+(-3*(1+Math.sin(frame*.18-i)))+'px)');
+      };`,
+  });
+  return sealVisualTrack({ id: options.id, programSpaceId: space.id, visualIr: "hypit.visual-ir@1",
+    presents: [{ id: options.id, span: window.span, stacking: { order: 0, tieBreak: options.id },
+      elements: [{ id: "chat", kind: "program", order: 0, program,
+        style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 },
+          { name: "width", value: `${canvas.widthPx}px` }, { name: "height", value: `${canvas.heightPx}px` }] }, ...children] }] });
+}

package/examples/semantic-composition/packages/chat-scene/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/examples/semantic-composition/packages/responsive-explainer/README.md

@@ -0,0 +1,45 @@
+# Responsive explainer
+
+One scene coordinates a playing performance and the diagram it makes room for. This intentionally
+small example can be adapted to the video's own visual idea; its HTML and motion live in `src/render.ts`.
+
+With prepared Takes, a Canvas and an exact FontStack already available:
+
+```svml
+<import as="explainer" from="@example/responsive-explainer@1"/>
+
+<speech:Track id="speech">
+  <speech:Take source={opening.take}/>
+  <speech:Take source={explanation.take}/>
+</speech:Track>
+<explainer:Scene id="scene" semantic={speech.semantic} canvas={canvas} font={font}
+  during="program" reveal={story.moment.demonstrate} title="Make room for meaning"
+  transition-frames="24" stack-order="0"/>
+<film:Film id="main" canvas={canvas} semantic={speech.semantic} appearance={look.film}>
+  <film:Track source={scene.visual}/>
+  <film:Track source={speech.audio}/>
+  <film:Track source={captions.track}/>
+</film:Film>
+```
+
+`during` also accepts a Script Selection or Segment; the shared Window syntax supports other authored
+intervals. `reveal` selects a Script Moment, such as `@demonstrate!` before the relevant word. Rewriting
+the Script or using another delivery changes the projected frame while retaining the layout behavior.
+`transition-frames` is the duration of that change, separate from the scene's lifetime. `stack-order`
+places this scene among other contributions. The caller supplies its title and exact fonts.
+
+`projectSemanticMedia` selects all intersecting prepared Takes. Each video's target interval is
+Present-local and its source offset is preserved. The parent viewport changes size and position;
+playback is never restarted by the layout change. The component owns the diagram and the viewport,
+so its internal overlap, rounded clipping and backdrop blur are ordinary HTML/CSS relationships.
+The original audio stays independently selectable as `speech.audio`.
+
+`src/activation.ts` declares the Module, Surface, semantic projections and Producer Fragment.
+`src/render.ts` emits a browser program with HTML slots for typed video and text children. Its render
+function computes state directly from local frame time, supporting direct seeking, range renders
+and independent workers.
+
+The package builds against `@hypit/hypit` and emits JavaScript. In a standalone project, replace the
+repository's `workspace:*` development dependency with the Hypit version you use. Run `npm run build`
+and connect this directory through an ordinary `file:` dependency during development. Cross-project
+sharing can use a tarball or a versioned package under the owner's scope.

package/examples/semantic-composition/packages/responsive-explainer/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@example/responsive-explainer",
+  "version": "0.0.0-dev",
+  "private": true,
+  "type": "module",
+  "hypit": { "activation": "./dist/activation.js" },
+  "exports": { ".": "./dist/render.js" },
+  "files": ["dist", "README.md"],
+  "scripts": { "build": "tsc -p tsconfig.json", "prepack": "npm run build" },
+  "devDependencies": { "@hypit/hypit": "workspace:*", "typescript": "5.9.3", "@types/node": "24.10.1" }
+}

package/examples/semantic-composition/packages/responsive-explainer/src/activation.ts

@@ -0,0 +1,90 @@
+import { assertAttributes, assertEmptyElement, canonicalize, createMarkupSurfaceHostFacet, sameType,
+  sealGraphFragment, textAttribute } from "@hypit/hypit/author-kit";
+import type { ComponentPackage, ModuleManifest, StructuredSurfaceHandler, SurfaceResolvedReference, TypeRef } from "@hypit/hypit/author-kit";
+import { compositionTypes } from "@hypit/hypit/composition";
+import { mediaTypes } from "@hypit/hypit/media";
+import type { FontStackRef } from "@hypit/hypit/media";
+import { narrativeTypes } from "@hypit/hypit/narrative";
+import { semanticTrackTypes } from "@hypit/hypit/semantic-track";
+import type { SemanticTrack } from "@hypit/hypit/semantic-track";
+import { spatialTypes } from "@hypit/hypit/spatial";
+import type { CanvasSpace } from "@hypit/hypit/spatial";
+import { temporalTypes } from "@hypit/hypit/temporal";
+import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
+import { createTemporalInstantProjection, createTemporalWindowProjection, temporalWindowAttributeNames,
+  temporalWindowAttributeVocabulary } from "@hypit/hypit/temporal-markup";
+import { renderExplainer } from "./render.js";
+import type { ExplainerOptions } from "./render.js";
+
+const module = { name: "@example/responsive-explainer", version: "1" } as const;
+const optionsType = { module, name: "ExplainerOptions" };
+const producer = { module, name: "compose" };
+const inputs = [
+  { name: "semantic", type: semanticTrackTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+  { name: "window", type: temporalTypes.window }, { name: "reveal", type: temporalTypes.instant },
+  { name: "font", type: mediaTypes.fontStack }, { name: "options", type: optionsType },
+];
+export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
+  dependencies: [compositionTypes.visualTrack, mediaTypes.fontStack, semanticTrackTypes.track,
+    spatialTypes.canvas, temporalTypes.window].map(type => ({ module: type.module })),
+  types: [{ name: optionsType.name }], capabilities: [],
+  producers: [{ name: producer.name, inputs, outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] }],
+};
+const fragment = sealGraphFragment({ inputs, operations: [{ id: "compose", producer,
+  inputs: Object.fromEntries(inputs.map(input => [input.name, { kind: "fragment-input" as const, name: input.name }])),
+  result: { kind: "output", name: "visual" } }],
+  exports: [{ name: "visual", type: compositionTypes.visualTrack, root: { kind: "fragment-operation", operation: "compose" } }],
+});
+const inline = <T>(record: { value: { kind: string; value?: unknown } } | undefined): T => {
+  if (record?.value.kind !== "inline") throw new Error("Explainer inputs must be inline values.");
+  return record.value.value as T;
+};
+const component: ComponentPackage = { producers: [{ producer, handler: ({ inputs }) => ({ needs: {}, outputs: {
+  visual: { kind: "inline", value: canonicalize(renderExplainer(inline<SemanticTrack>(inputs.semantic),
+    inline<CanvasSpace>(inputs.canvas), inline<TemporalWindow>(inputs.window), inline<TemporalInstant>(inputs.reveal),
+    inline<FontStackRef>(inputs.font).faces, inline<ExplainerOptions>(inputs.options))) },
+} }) }] };
+export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id", "semantic", "canvas", "font", "reveal", "title", "transition-frames", "stack-order", ...temporalWindowAttributeNames]);
+  assertEmptyElement(element);
+  const id = textAttribute(element, "id");
+  const reference = (name: string, type: TypeRef): SurfaceResolvedReference => {
+    const raw = element.attributes[name];
+    if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${name} must be a reference.`);
+    const value = resolveReference(raw.path);
+    if (value === undefined || !sameType(type, value.type)) throw new Error(`${name} has the wrong type.`);
+    return value;
+  };
+  const semantic = reference("semantic", semanticTrackTypes.track);
+  const window = createTemporalWindowProjection({ id: `${id}.window`, element, semantic, resolveReference });
+  // Reveal has its own Moment; the outer Window independently controls this scene's lifetime.
+  reference("reveal", narrativeTypes.moment);
+  const reveal = createTemporalInstantProjection({ id: `${id}.reveal`,
+    element: { ...element, attributes: { at: element.attributes.reveal! } }, semantic, resolveReference });
+  const options: ExplainerOptions = { id, title: textAttribute(element, "title"),
+    transitionFrames: Number(textAttribute(element, "transition-frames")), stackingOrder: Number(textAttribute(element, "stack-order")) };
+  return { records: [...window.records, ...reveal.records, { id: `${id}.options`, type: optionsType,
+      value: { kind: "inline", value: canonicalize(options) }, range: element.range }],
+    fragments: [...window.fragments, ...reveal.fragments, fragment],
+    components: [...window.components, ...reveal.components, { id, fragment: fragment.id,
+      inputs: { semantic: semantic.ref, canvas: reference("canvas", spatialTypes.canvas).ref,
+        font: reference("font", mediaTypes.fontStack).ref, window: window.ref, reveal: reveal.ref,
+        options: { kind: "record", id: `${id}.options` } }, outputs: { visual: `${id}.visual` }, range: element.range }],
+    exports: [`${id}.visual`] };
+};
+const declaration = { name: "scene", tag: "Scene", mode: "structured" as const,
+  outputs: [compositionTypes.visualTrack, temporalTypes.window, temporalTypes.instant, temporalTypes.windowSpec, temporalTypes.instantSpec, optionsType],
+  vocabulary: { summary: "A continuously playing performance makes room for a diagram on a semantic Moment.",
+    attributes: [
+      ...["id", "title", "transition-frames", "stack-order"].map(name => ({ name, kind: "literal" as const, required: true, summary: name })),
+      ...[{ name: "semantic", type: semanticTrackTypes.track }, { name: "canvas", type: spatialTypes.canvas },
+        { name: "font", type: mediaTypes.fontStack }, { name: "reveal", type: narrativeTypes.moment }]
+        .map(({ name, type }) => ({ name, kind: "reference" as const, required: true, accepts: [type], summary: name })),
+      ...temporalWindowAttributeVocabulary,
+    ], ports: [{ name: "visual", type: compositionTypes.visualTrack, summary: "The coordinated scene." }],
+    example: '<explainer:Scene id="scene" semantic={speech.semantic} canvas={canvas} font={font} during="program" reveal={story.moment.reveal} title="How it works" transition-frames="18" stack-order="0"/>',
+  },
+};
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component],
+  hostFacets: [createMarkupSurfaceHostFacet({ module, declaration, handler: decodeSurface })] };
+export default hypitPackage;

package/examples/semantic-composition/packages/responsive-explainer/src/render.ts

@@ -0,0 +1,68 @@
+import { sealVisualTrack } from "@hypit/hypit/composition";
+import type { VisualElement } from "@hypit/hypit/composition";
+import { browserProgram } from "@hypit/hypit/hyperframes";
+import type { FontArtifactRef } from "@hypit/hypit/media";
+import { projectSemanticMedia, projectSemanticProgramSpace } from "@hypit/hypit/semantic-track";
+import type { SemanticTrack } from "@hypit/hypit/semantic-track";
+import type { CanvasSpace } from "@hypit/hypit/spatial";
+import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
+
+export type ExplainerOptions = { id: string; title: string; transitionFrames: number; stackingOrder: number };
+
+/** One scene owns the moving performance viewport and the diagram it makes room for. */
+export function renderExplainer(semantic: SemanticTrack, canvas: CanvasSpace, window: TemporalWindow,
+  reveal: TemporalInstant, fonts: readonly FontArtifactRef[], options: ExplainerOptions) {
+  const space = projectSemanticProgramSpace(semantic);
+  if (window.start.source.spaceId !== space.id || reveal.source.spaceId !== space.id)
+    throw new Error("Explainer timing must belong to its semantic performance.");
+  if (!Number.isSafeInteger(options.transitionFrames) || options.transitionFrames < 1)
+    throw new Error("Explainer transitionFrames must be a positive integer.");
+  const clips = projectSemanticMedia(semantic, window.span).filter(clip => clip.media.visual !== undefined);
+  const videos: VisualElement[] = clips.map((clip, i) => ({
+    id: `take-${i}`, parent: "scene", kind: "video", order: i + 1,
+    artifact: clip.media.visual!.artifact, muted: true,
+    style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 },
+      { name: "width", value: "100%" }, { name: "height", value: "100%" }, { name: "object-fit", value: "cover" }],
+    sampling: { sourceFrameRate: clip.media.timeline.frameRate, sourceFrameCount: clip.media.timeline.frameCount,
+      segments: [{ target: { startFrame: clip.span.startFrame - window.span.startFrame,
+        endFrameExclusive: clip.span.endFrameExclusive - window.span.startFrame },
+        sourceFrame: { numerator: clip.source.startFrame, denominator: 1 }, rate: { numerator: 1, denominator: 1 } }] },
+  }));
+  const labels: VisualElement[] = [options.title, "Intent", "Performance", "Composition"].map((text, i) => ({
+    id: `label-${i}`, parent: "scene", kind: "text", order: videos.length + i + 1, text, fonts,
+    style: [{ name: "font-size", value: `${i === 0 ? Math.round(canvas.widthPx * .035) : 23}px` }, { name: "color", value: "#f5eddc" },
+      { name: "white-space", value: "nowrap" }],
+  }));
+  // Exact fonts belong to the typed text children; the program supplies layout and behavior.
+  const program = browserProgram({
+    html: `<div class="diagram"><div class="heading">{{label-0}}</div>
+      <svg viewBox="0 0 440 300"><path d="M60 60 H320 V150 H60 V240 H320"/></svg>
+      <div class="step first">{{label-1}}</div><div class="step second">{{label-2}}</div>
+      <div class="step third">{{label-3}}</div></div>
+      <div class="viewport">${videos.map(video => `{{${video.id}}}`).join("")}<div class="glass"></div></div>`,
+    css: `:scope { background:#193c3a; overflow:hidden; }
+      .viewport { position:absolute; overflow:hidden; isolation:isolate; }
+      .glass { position:absolute; inset:auto 0 0; height:12%; backdrop-filter:blur(9px); background:rgba(20,40,40,.15); }
+      .diagram { position:absolute; left:5%; top:17%; width:48%; height:70%; }
+      .heading { position:absolute; top:0; left:0; }
+      svg { position:absolute; inset:22% 0 0; width:100%; height:70%; overflow:visible; }
+      path { fill:none; stroke:#c5e98b; stroke-width:4; stroke-linecap:round; stroke-dasharray:900; }
+      .step { position:absolute; padding:14px 24px; border:1px solid #91c6a2; border-radius:16px; background:#285b51; }
+      .first { left:2%; top:30%; } .second { right:2%; top:53%; } .third { left:2%; top:76%; }`,
+    data: { width: canvas.widthPx, height: canvas.heightPx,
+      reveal: reveal.frame - window.span.startFrame, transition: options.transitionFrames },
+    setup: `const viewport=root.querySelector('.viewport'), diagram=root.querySelector('.diagram'), path=root.querySelector('path');
+      return frame => {
+        const t=Math.max(0, Math.min(1,(frame-data.reveal)/data.transition));
+        const p=t*t*(3-2*t);
+        Object.assign(viewport.style,{left:(p*.61*data.width)+'px',top:(p*.06*data.height)+'px',
+          width:((1-p*.65)*data.width)+'px',height:((1-p*.12)*data.height)+'px',borderRadius:(p*24)+'px'});
+        diagram.style.opacity=String(p); diagram.style.transform='translateX('+(-24*(1-p))+'px)';
+        path.style.strokeDashoffset=String(900*(1-p));
+      };`,
+  });
+  return sealVisualTrack({ id: options.id, programSpaceId: space.id, visualIr: "hypit.visual-ir@1",
+    presents: [{ id: options.id, span: window.span, stacking: { order: options.stackingOrder, tieBreak: options.id },
+      elements: [{ id: "scene", kind: "program", order: 0, program,
+        style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }] }, ...videos, ...labels] }] });
+}

package/examples/semantic-composition/packages/responsive-explainer/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "declaration": true,
+    "sourceMap": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}