@hypit/hypit 0.1.3 → 0.1.5

package/examples/provider-package/packages/provider-images/src/provider.ts

@@ -0,0 +1,122 @@
+import { canonicalize, defineEndpointPackage, wakeAfter } from "@hypit/hypit/endpoint-kit";
+import type { AsyncEndpoint, CredentialRef, EndpointRequest } from "@hypit/hypit/endpoint-kit";
+import { compileWireRequest, generationTypes, sealGeneratedImageSet } from "@hypit/hypit/generation";
+import type { GenerationRequest, GenerationWireMapping } from "@hypit/hypit/generation";
+
+export const providerModule = { name: "@example/provider-images", version: "1" } as const;
+export const capability = { module: { name: "@hypit/gpt-image", version: "1" }, name: "gpt-image-2" } as const;
+
+// This example service implements only this subset of the model. Its API is described in README.
+const mapping: GenerationWireMapping = {
+  capability, result: "image", routes: [{ model: "gpt-image-2" }],
+  fields: {
+    prompt: { as: "value", field: "prompt" },
+    aspectRatio: { as: "value", field: "ratio" },
+    resolution: { as: "value", field: "size" },
+    images: { as: "urlArray", field: "references" },
+  },
+};
+
+function object(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected service object");
+  return value as Record<string, unknown>;
+}
+function text(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0) throw new Error("Expected nonempty service text");
+  return value;
+}
+function address(value: string): string {
+  const url = new URL(value);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname))) {
+    throw new Error("Service URLs require HTTPS or loopback HTTP");
+  }
+  return url.href;
+}
+
+function support(request: EndpointRequest) {
+  const ports = (request.constraints as unknown as GenerationRequest).ports;
+  const unsupported = ports.resolution?.[0] !== "1K"
+    || !["1:1", "9:16", "16:9"].includes(String(ports.aspectRatio?.[0]))
+    || Object.keys(ports).some((port) => !(port in mapping.fields))
+    || request.pendingInputs?.some((slot) => !(slot.input in mapping.fields));
+  return unsupported
+    ? { status: "unsupported" as const, reason: "This service offers 1K at 1:1, 9:16 or 16:9, without background control" }
+    : { status: "supported" as const };
+}
+
+export function createImageProvider(options: {
+  instance: string; pool: string; baseUrl: string; apiKey: CredentialRef;
+  concurrency?: number; pollIntervalMs?: number; fetch?: typeof globalThis.fetch;
+}) {
+  const base = address(options.baseUrl).replace(/\/$/u, "");
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const interval = options.pollIntervalMs ?? 2_000;
+  const key = (credentials: Readonly<Record<string, { secret: string }>>) => text(credentials.apiKey?.secret);
+  async function json(path: string, secret: string, init: RequestInit = {}) {
+    const response = await fetcher(`${base}${path}`, {
+      ...init, headers: { ...init.headers, authorization: `Bearer ${secret}` },
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok) throw new Error(`Image service ${path} returned HTTP ${response.status}`);
+    return object(await response.json());
+  }
+  const endpoint: AsyncEndpoint = {
+    async start(context) {
+      const supported = support(context.need);
+      if (supported.status === "unsupported") throw new Error(supported.reason);
+      const secret = key(context.credentials);
+      const request = await compileWireRequest(mapping, context.need.constraints as unknown as GenerationRequest,
+        async (artifact) => {
+          const bytes = await context.resources.get(artifact.resource);
+          if (bytes === undefined) throw new Error("Reference image is unavailable");
+          const upload = await json("/uploads", secret, {
+            method: "POST", headers: { "content-type": artifact.mediaType }, body: new Blob([new Uint8Array(bytes)]),
+          });
+          return address(text(upload.url));
+        });
+      const task = await json("/tasks", secret, {
+        method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(request),
+      });
+      const id = text(task.id), handle = { id }, receipt = { id };
+      await context.checkpoint?.({ handle, receipt });
+      return { ...wakeAfter(handle, interval), receipt };
+    },
+    async poll(context) {
+      const id = text(object(context.handle).id);
+      const task = await json(`/tasks/${encodeURIComponent(id)}`, key(context.credentials));
+      if (task.state === "queued" || task.state === "running") {
+        return wakeAfter({ id }, interval, Date.now(), { phase: task.state });
+      }
+      if (task.state === "failed") return {
+        status: "failed", failure: { code: "IMAGE_SERVICE_FAILED", message: "Image service task failed" },
+      };
+      if (task.state !== "succeeded") throw new Error("Image service returned an unknown task state");
+      return { status: "ready", handle: { id, url: address(text(task.url)) } };
+    },
+    async collect(context) {
+      // The service returns a signed asset URL; account credentials go only to its API.
+      const url = address(text(object(context.handle).url));
+      const response = await fetcher(url, { signal: AbortSignal.timeout(60_000) });
+      if (!response.ok) throw new Error(`Image download returned HTTP ${response.status}`);
+      const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
+      if (!mediaType?.startsWith("image/")) throw new Error("Image service returned a non-image result");
+      const artifact = await context.resources.put(new Uint8Array(await response.arrayBuffer()), mediaType);
+      return { status: "completed", result: { value: {
+        kind: "inline", value: canonicalize(sealGeneratedImageSet({ images: [artifact] })),
+      } } };
+    },
+  };
+  return defineEndpointPackage({
+    module: providerModule, facet: "images", instance: options.instance, pool: options.pool,
+    credentials: { apiKey: options.apiKey }, credentialInputs: { apiKey: { label: "Image service API key" } },
+    defaultConcurrency: options.concurrency ?? 1,
+    actionLimits: { submit: { concurrency: 1 }, poll: { concurrency: 4 }, collect: { concurrency: 1 } },
+    pricing: { kind: "page", url: `${base}/pricing` },
+    async readPricing(context) {
+      const source = `${base}/rates?model=gpt-image-2`;
+      const rates = await json("/rates?model=gpt-image-2", key(await context.credentials()));
+      return [{ source, data: canonicalize(rates), summary: text(rates.description) }];
+    },
+    capabilities: [{ capability, returns: generationTypes.imageSet, lifecycle: "asynchronous", supports: support, endpoint }],
+  });
+}

package/examples/provider-package/packages/provider-images/tsconfig.json

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

package/examples/semantic-composition/README.md

@@ -33,3 +33,9 @@ there is no hosted generation account in this example. The final Output is `fina
 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.
+
+## Sound presentation Styles
+
+`packages/sound-styles` defines a project crossfade with explicit outgoing and incoming Segments.
+It uses Sound Uses over the same Timeline and preserves original source playback through the blend.
+Its README explains authoring and the public fragment interface.

package/examples/semantic-composition/chat.svml

@@ -1,6 +1,6 @@
 <?svml using="@hypit/markup@1"?>
 <svml>
-  <import as="time" from="@hypit/program-space@1"/>
+  <import as="time" from="@hypit/timeline-author@1"/>
   <import as="spatial" from="@hypit/spatial@1"/>
   <import as="fonts" from="@hypit/fonts-open@1"/>
   <import as="chat" from="@example/chat-scene@1"/>
@@ -8,18 +8,19 @@
   <import as="render" from="@hypit/render-hyperframes@1"/>
   <import as="style" source="./chat.svs"/>
 
-  <time:Space id="animation" frame-rate="30" duration="8s"/>
+  <time:Clock id="animation-clock" frame-rate="30"/>
+<time:Timeline id="animation" clock={animation-clock} end="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}
+  <chat:Scene id="conversation" timeline={animation.timeline} 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:Film id="main" canvas={canvas} timeline={animation.timeline} appearance={style.film.main}>
     <film:Track source={conversation.track}/>
   </film:Film>
-  <render:Video id="final" composition={main.composition} space={animation}/>
+  <render:Video id="final" composition={main.composition} timeline={animation.timeline}/>
 </svml>

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

@@ -6,20 +6,20 @@ Content lives in Source. Every Message has its own `at`; there is no fixed messa
 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}
+<chat:Scene id="conversation" timeline={speech.timeline} 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
+The same component can receive a zero-Take `timeline={animation.timeline}` 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
+graph. The rendering function receives Timeline, 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.
 

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

@@ -3,14 +3,13 @@ import type { ComponentPackage, FragmentOperation, ModuleManifest, StructuredSur
 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 type { Timeline } from "@hypit/hypit/timeline";
+import { timelineTypes } from "@hypit/hypit/timeline";
 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,
+import { createTemporalInstantProjection, createTemporalWindowProjection, resolveTemporalContext,
   temporalContextAttributeVocabulary, temporalInstantAttributeNames, temporalInstantAttributeVocabulary,
   temporalWindowAttributeNames, temporalWindowAttributeVocabulary } from "@hypit/hypit/temporal-markup";
 import { renderChat } from "./render.js";
@@ -20,14 +19,13 @@ 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 })),
+  dependencies: [compositionTypes.visualTrack, mediaTypes.fontStack, timelineTypes.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: "at", type: temporalTypes.instant }, { name: "timeline", type: timelineTypes.track }], 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: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas },
       { name: "window", type: temporalTypes.window }, { name: "font", type: mediaTypes.fontStack }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
   ],
 };
@@ -41,20 +39,19 @@ const component: ComponentPackage = { producers: [
   { 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) });
+    assertTemporalInstantFor(at, { subjectId: message.id, space: inline<Timeline>(inputs.timeline) });
     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),
+  { producer: producers.render, handler: ({ inputs }) => ({ outputs: { track: value(renderChat(inline<Timeline>(inputs.timeline),
     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]);
+  assertAttributes(element, ["id", "timeline", "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 window = createTemporalWindowProjection({ id: `${id}.window`, subjectId: id, element, ...context, 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.`);
@@ -64,10 +61,10 @@ export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveRefere
   };
   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 },
+  const components = [...window.components], fragments = [...window.fragments];
+  const inputs = [{ name: "timeline", type: timelineTypes.track }, { 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,
+  const bindings: Record<string, SurfaceResolvedReference["ref"]> = { timeline: context.timeline.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 });
@@ -79,24 +76,24 @@ export const decodeSurface: StructuredSurfaceHandler = ({ element, resolveRefere
     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 });
+    const at = createTemporalInstantProjection({ id: `${id}.${messageId}`, subjectId: messageId, element: child, ...context, 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" } });
+    operations.push({ id: key, producer: producers.append, inputs: { messages: operation(previous), message: input(key), at: input(`${key}-at`), timeline: input("timeline") }, 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" } });
+    timeline: input("timeline"), 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)],
+  outputs: [compositionTypes.visualTrack, timelineTypes.track, 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 })),
@@ -104,7 +101,7 @@ const declaration = { name: "scene", tag: "Scene", mode: "structured" as const,
   ], 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>',
+    example: '<chat:Scene id="chat" timeline={speech.timeline} 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],

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

@@ -2,7 +2,7 @@ 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 { Timeline } from "@hypit/hypit/timeline";
 import type { CanvasSpace } from "@hypit/hypit/spatial";
 import { assertTemporalWindowFor } from "@hypit/hypit/temporal";
 import type { TemporalInstant, TemporalWindow } from "@hypit/hypit/temporal";
@@ -11,9 +11,9 @@ export type Message = { id: string; sender: string; text: string; side: "left" |
 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,
+export function renderChat(timeline: Timeline, canvas: CanvasSpace, window: TemporalWindow,
   font: FontStackRef, messages: readonly Message[], options: ChatOptions) {
-  assertTemporalWindowFor(window, { subjectId: options.id, space });
+  assertTemporalWindowFor(window, { subjectId: options.id, space: timeline });
   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;
@@ -56,7 +56,7 @@ export function renderChat(space: ProgramSpace, canvas: CanvasSpace, window: Tem
         [...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",
+  return sealVisualTrack({ id: options.id, programSpaceId: timeline.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 },

package/examples/semantic-composition/packages/performance-styles/README.md

@@ -0,0 +1,42 @@
+# Project-authored Performance Styles
+
+This package demonstrates two ordinary project families: a viewport moving between Frames and a
+crossfade between explicitly selected Segments. Both export the common PerformanceStyle, so they
+work alongside the ordinary fixed Style inside one Performance Track.
+
+```svml
+<import as="performance" from="@hypit/performance@1"/>
+<import as="styles" from="@example/performance-styles@1"/>
+<performance:Style id="full" frame={layout.full} appearance={recipes.media.presenter}/>
+<performance:Style id="side" frame={layout.side} appearance={recipes.media.presenter}/>
+<styles:Move id="full-to-side" from={layout.full} to={layout.side}/>
+<styles:Crossfade id="mix" outgoing={story.segment.previous}
+  incoming={story.segment.next} frame={layout.side}/>
+<performance:Track id="presenter" timeline={program.timeline} canvas={canvas}>
+  <performance:Use style={full}/>
+  <performance:Use moment={story.moment.explain}
+    start="moment.cue" end="program.end" style={side}/>
+  <performance:Use at={story.moment.explain} for="2s" style={full-to-side}/>
+  <performance:Use start-source={story.segment.next} start="segment.start"
+    end-source={story.segment.previous} end="segment.end" style={mix}/>
+</performance:Track>
+```
+
+The two-second movement overrides the beginning of the already declared side treatment. Changing
+its duration requires no reference to a Use id. Shared endpoint Frames keep the fixed and moving
+layouts aligned. All timing belongs to Uses; each Style is independently reusable.
+
+Crossfade requires known outgoing/incoming Segment identities. A known audio-only source supplies
+transparent picture, giving a fade in or out; an unknown reference reports the actual error. This
+example uses isolated additive blending of weighted pictures. `projectTimelineMedia` preserves the
+original source positions; animation progress comes from the original Use Window.
+
+Read `activation.ts` for the complete author Surface, bound fragment and Producer wiring, and
+`render.ts` for the browser program. A project can add its own parameters or additional events without
+changing Performance. Compile with `npm run build`; install the package in the video project's
+ordinary package dependencies. The rendering test exercises these same functions with actual video.
+
+The package also includes `src/studio.ts`. Move exposes its `from` and `to` Frame coordinates;
+Crossfade exposes its Frame and read-only source references. These parameter Companions match the
+project's own Style Surfaces and are composed into any consuming Performance Use. The Track
+Companion and Studio require no knowledge of these Style names.

package/examples/semantic-composition/packages/performance-styles/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@example/performance-styles",
+  "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/performance-styles/src/activation.ts

@@ -0,0 +1,57 @@
+import { styleStudioFacet } from "./studio.js";
+import { assertAttributes, assertEmptyElement, canonicalize, createMarkupSurfaceHostFacet, sameType, sealGraphFragment, textAttribute } from "@hypit/hypit/author-kit";
+import type { ComponentPackage, ModuleManifest, StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/hypit/author-kit";
+import { compositionTypes } from "@hypit/hypit/composition";
+import { performanceStyle, performanceTypes, performanceModuleRef } from "@hypit/hypit/performance";
+import { timelineTypes } from "@hypit/hypit/timeline";
+import type { Timeline } from "@hypit/hypit/timeline";
+import { spatialTypes } from "@hypit/hypit/spatial";
+import type { SpatialFrame } from "@hypit/hypit/spatial";
+import { temporalTypes } from "@hypit/hypit/temporal";
+import type { TemporalWindow } from "@hypit/hypit/temporal";
+import { narrativeTypes } from "@hypit/hypit/narrative";
+import type { NarrativeExcerpt } from "@hypit/hypit/narrative";
+import { movingFrame, crossfade } from "./render.js";
+
+const module = { name: "@example/performance-styles", version: "1" } as const;
+const common = [{ name: "timeline", type: timelineTypes.track }, { name: "canvas", type: spatialTypes.canvas }, { name: "window", type: temporalTypes.window }];
+const moveInputs = [...common, { name: "from", type: spatialTypes.frame }, { name: "to", type: spatialTypes.frame }];
+const mixInputs = [...common, { name: "outgoing", type: narrativeTypes.excerpt }, { name: "incoming", type: narrativeTypes.excerpt }, { name: "frame", type: spatialTypes.frame }];
+const families = [{ name: "move", tag: "Move", ports: moveInputs }, { name: "crossfade", tag: "Crossfade", ports: mixInputs }];
+export const manifest: ModuleManifest = { format: "hypit.module@1", ...module,
+  dependencies: [performanceModuleRef, compositionTypes.visualTrack.module, timelineTypes.track.module, spatialTypes.canvas.module, temporalTypes.window.module, narrativeTypes.excerpt.module].map(module => ({ module })),
+  types: [], capabilities: [], producers: families.map(family => ({ name: family.name, inputs: family.ports, outputs: [{ name: "visual", type: compositionTypes.visualTrack }], needs: [] })) };
+const fragments = families.map(family => sealGraphFragment({ inputs: family.ports,
+  operations: [{ id: "render", producer: { module, name: family.name }, inputs: Object.fromEntries(family.ports.map(port => [port.name, { kind: "fragment-input" as const, name: port.name }])), result: { kind: "output", name: "visual" } }],
+  exports: [{ name: "visual", type: compositionTypes.visualTrack, root: { kind: "fragment-operation", operation: "render" } }] }));
+const component: ComponentPackage = { producers: families.map(family => ({ producer: { module, name: family.name }, handler: ({ inputs }) => {
+  const values = Object.fromEntries(Object.entries(inputs).map(([key, record]) => {
+    if (record.value.kind !== "inline") throw new Error(`${key} must be inline`);
+    return [key, record.value.value];
+  }));
+  const visual = family.name === "move" ? movingFrame(values.timeline as unknown as Timeline, values.window as unknown as TemporalWindow, values.from as unknown as SpatialFrame, values.to as unknown as SpatialFrame)
+    : crossfade(values.timeline as unknown as Timeline, values.window as unknown as TemporalWindow, values.outgoing as unknown as NarrativeExcerpt, values.incoming as unknown as NarrativeExcerpt, values.frame as unknown as SpatialFrame);
+  return { outputs: { visual: { kind: "inline", value: canonicalize(visual) } }, needs: {} };
+} })) };
+const hostFacets = families.map((family,index) => {
+  const params = family.ports.slice(common.length);
+  const handler: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+    assertAttributes(element, ["id", ...params.map(port => port.name)]); assertEmptyElement(element);
+    const bindings: Record<string, SurfaceResolvedReference> = {};
+    for (const param of params) {
+      const raw = element.attributes[param.name];
+      if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${param.name} must be a reference`);
+      const value = resolveReference(raw.path);
+      if (value === undefined || !sameType(value.type,param.type)) throw new Error(`${param.name} has the wrong Type`);
+      bindings[param.name] = value;
+    }
+    return { records: [{ id: textAttribute(element,"id"), type: performanceTypes.style,
+      value: { kind: "inline", value: canonicalize(performanceStyle(fragments[index]!,bindings)) }, range: element.range }], components: [], fragments: [] };
+  };
+  return createMarkupSurfaceHostFacet({ module, declaration: { name: family.name, tag: family.tag, mode: "structured", outputs: [performanceTypes.style], vocabulary: {
+    summary: `Project-owned ${family.name} presentation Style.`, example: `<styles:${family.tag} id="look" ${params.map(port => `${port.name}={${port.name}}`).join(' ')}/>`,
+    attributes: [{ name: "id", kind: "identifier", required: true, summary: "Style identity." }, ...params.map(port => ({ name: port.name, kind: "reference" as const, required: true, accepts: [port.type], summary: `Explicit ${port.name} input.` }))],
+  } }, handler });
+});
+export const hypitPackage = { format: "hypit.node-package@1" as const, modules: [{ manifest }], components: [component], hostFacets: [...hostFacets, styleStudioFacet(module)] };
+export default hypitPackage;

package/examples/semantic-composition/packages/performance-styles/src/render.ts

@@ -0,0 +1,54 @@
+import { sealVisualTrack } from "@hypit/hypit/composition";
+import type { VisualElement } from "@hypit/hypit/composition";
+import { browserProgram } from "@hypit/hypit/hyperframes";
+import { projectTimelineMedia } from "@hypit/hypit/timeline";
+import type { Timeline } from "@hypit/hypit/timeline";
+import type { TemporalWindow } from "@hypit/hypit/temporal";
+import type { SpatialFrame } from "@hypit/hypit/spatial";
+import type { NarrativeExcerpt } from "@hypit/hypit/narrative";
+
+/** Project behavior, not a registered special effect: the original Use window owns progress. */
+export function movingFrame(timeline: Timeline, window: TemporalWindow, from: SpatialFrame, to: SpatialFrame) {
+  return render(timeline, window, { from, to });
+}
+export function crossfade(timeline: Timeline, window: TemporalWindow, outgoing: NarrativeExcerpt, incoming: NarrativeExcerpt, frame: SpatialFrame) {
+  for (const ref of [outgoing, incoming]) {
+    if (ref.narrativeId !== timeline.narrativeId || !timeline.items.some(item => item.take.segment.segmentId === ref.id)) {
+      throw new Error(`Unknown crossfade source ${ref.id}.`);
+    }
+  }
+  return render(timeline, window, { outgoing: outgoing.id, incoming: incoming.id, from: frame, to: frame });
+}
+function render(timeline: Timeline, window: TemporalWindow, options: { from: SpatialFrame; to: SpatialFrame; outgoing?: string; incoming?: string }) {
+  const id = window.subjectId;
+  const clips = projectTimelineMedia(timeline, window.span).filter(clip => clip.media.visual !== undefined
+    && (options.outgoing === undefined || clip.segmentId === options.outgoing || clip.segmentId === options.incoming));
+  const videos: VisualElement[] = clips.map((clip, index) => ({
+    id: `source-${index}`, parent: "scene", order: index + 1, kind: "video", muted: true,
+    artifact: clip.media.visual!.artifact,
+    attributes: [{ name: "data-source-role", value: options.incoming === clip.segmentId ? "incoming" : "outgoing" }],
+    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 program = browserProgram({
+    html: `<div class="viewport">${videos.map((video,index) => `<div class="source" data-role="${clips[index]!.segmentId === options.incoming ? "incoming" : "outgoing"}">{{${video.id}}}</div>`).join("")}</div>`,
+    css: `.viewport{position:absolute;overflow:hidden;isolation:isolate}.source{position:absolute;inset:0;${options.outgoing === undefined ? '' : 'mix-blend-mode:plus-lighter'}}`,
+    data: { from: options.from, to: options.to, mixing: options.outgoing !== undefined, duration: window.span.endFrameExclusive - window.span.startFrame },
+    setup: `const view=root.querySelector('.viewport'), sources=view.querySelectorAll('.source');
+      return frame => {
+        const p=Math.max(0,Math.min(1,frame/Math.max(1,data.duration-1)));
+        const q=p*p*(3-2*p), a=data.from, b=data.to;
+        Object.assign(view.style,{left:(a.xPx+(b.xPx-a.xPx)*q)+'px',top:(a.yPx+(b.yPx-a.yPx)*q)+'px',
+          width:(a.widthPx+(b.widthPx-a.widthPx)*q)+'px',height:(a.heightPx+(b.heightPx-a.heightPx)*q)+'px'});
+        if(data.mixing) for(const child of sources) {
+          const role=child.dataset.role;
+          child.style.opacity=String(role==='incoming'?p:1-p);
+        }
+      };`,
+  });
+  return sealVisualTrack({ id, programSpaceId: timeline.id, visualIr: "hypit.visual-ir@1", presents: videos.length ? [{ id, span: window.span,
+    stacking: { order: 0, tieBreak: id }, elements: [{ id: "scene", kind: "program", order: 0, style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }], program }, ...videos] }] : [] });
+}

package/examples/semantic-composition/packages/performance-styles/src/studio.ts

@@ -0,0 +1,28 @@
+import { createStudioCompanionHostFacet } from "@hypit/hypit/studio-adapter";
+import type { StudioParameterCompanion } from "@hypit/hypit/studio-adapter";
+
+/** The project Style owns its inputs; Performance only owns its Use interval. */
+export function styleStudioFacet(module: { readonly name: string; readonly version: string }) {
+  const coordinates = ["left", "top", "right", "bottom", "x", "y", "width", "height"];
+  const definitions = [
+    { surface: "move", frames: ["from", "to"], sources: [] },
+    { surface: "crossfade", frames: ["frame"], sources: ["outgoing", "incoming"] },
+  ];
+  const parameters: StudioParameterCompanion[] = definitions.map(({ surface, frames, sources }) => ({
+    id: surface, match: { module, surface },
+    bindings: [
+      ...frames.map(name => ({ name, referenced: coordinates.map(name => ({ name, writable: true })) })),
+      ...sources.map(name => ({ name })),
+    ],
+    inspector: [
+      ...frames.flatMap(frame => coordinates.map(name => ({
+        binding: `${frame}.${name}`, label: name, domain: "where" as const,
+        page: { id: frame, label: frame }, section: { id: "frame", label: "Frame" },
+        control: "number" as const, number: { suffixes: ["%", "px"], step: 1 },
+      }))),
+      ...sources.map(name => ({ binding: name, label: name, domain: "how" as const,
+        section: { id: "sources", label: "Sources" }, control: "text" as const })),
+    ],
+  }));
+  return createStudioCompanionHostFacet({ parameters });
+}

package/examples/semantic-composition/packages/performance-styles/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"]
+}