@hypit/hypit 0.1.3 → 0.1.5

package/packages/generation/src/mapping.ts

@@ -2,10 +2,16 @@ import { canonicalize } from "@hypit/protocol";
 import type { BlobRef, CanonicalValue, CapabilityRef } from "@hypit/protocol";
 
 import { isMediaPort } from "./ports.js";
-import type { GenerationMediaRole, GenerationMediaValue, GenerationPortTable } from "./ports.js";
+import type { GenerationMediaValue, GenerationPortTable } from "./ports.js";
 import { presentPorts } from "./request.js";
 import type { GenerationRequest } from "./request.js";
 
+/** Per-reference fields consumed by the service's resource transport rather than its generation body. */
+export type GenerationArtifactUrlResolver = (
+  artifact: BlobRef,
+  fields?: Readonly<Record<string, string | number | boolean>>,
+) => Promise<string>;
+
 /**
  * How one service names the fields of one model's declared input ports.
  *
@@ -13,8 +19,6 @@ import type { GenerationRequest } from "./request.js";
  * Provider package therefore never imports a model package: the model owns what
  * it eats, the service owns what it calls that on the wire.
  */
-export type GenerationArtifactUrlResolver = (artifact: BlobRef) => Promise<string>;
-
 export type GenerationFieldMapping =
   /** One scalar written as-is. */
   | { readonly as: "value"; readonly field: string; readonly whenAbsent?: CanonicalValue }
@@ -23,14 +27,15 @@ export type GenerationFieldMapping =
   /** Several scalars written as one array. */
   | { readonly as: "valueArray"; readonly field: string; readonly whenAbsent?: CanonicalValue }
   /** One media item written as a resolved URL. */
-  | { readonly as: "url"; readonly field: string; readonly whenAbsent?: CanonicalValue }
+  | { readonly as: "url"; readonly field: string; readonly resourceFields?: readonly string[]; readonly whenAbsent?: CanonicalValue }
   /** Several media items written as one array of resolved URLs. */
-  | { readonly as: "urlArray"; readonly field: string; readonly whenAbsent?: CanonicalValue }
+  | { readonly as: "urlArray"; readonly field: string; readonly resourceFields?: readonly string[]; readonly whenAbsent?: CanonicalValue }
   /** Media items written as objects carrying the resolved URL and their item fields. */
   | {
       readonly as: "itemObject";
       readonly field: string;
       readonly urlKey: string;
+      readonly resourceFields?: readonly string[];
       readonly fieldKeys: Readonly<Record<string, string>>;
       readonly whenAbsent?: CanonicalValue;
     };
@@ -95,11 +100,9 @@ export function selectWireModelForRequest(
   return selectWireModel(mapping, present);
 }
 
-async function urlsOf(
-  values: readonly GenerationMediaValue[],
-  resolve: GenerationArtifactUrlResolver,
-): Promise<string[]> {
-  return await Promise.all(values.map((item) => resolve(item.artifact)));
+function resourceFields(item: GenerationMediaValue, names: readonly string[] = []) {
+  return Object.fromEntries(names.filter((name) => item.fields?.[name] !== undefined)
+    .map((name) => [name, item.fields![name]!]));
 }
 
 /**
@@ -127,13 +130,15 @@ export async function compileWireRequest(
     } else if (field.as === "valueArray") {
       input[field.field] = supplied as readonly CanonicalValue[];
     } else if (field.as === "url") {
-      input[field.field] = await resolve((supplied[0] as GenerationMediaValue).artifact);
+      const item = supplied[0] as GenerationMediaValue;
+      input[field.field] = await resolve(item.artifact, resourceFields(item, field.resourceFields));
     } else if (field.as === "urlArray") {
-      input[field.field] = await urlsOf(supplied as readonly GenerationMediaValue[], resolve);
+      input[field.field] = await Promise.all((supplied as readonly GenerationMediaValue[])
+        .map((item) => resolve(item.artifact, resourceFields(item, field.resourceFields))));
     } else {
       const media = supplied as readonly GenerationMediaValue[];
       input[field.field] = await Promise.all(media.map(async (item) => ({
-        [field.urlKey]: await resolve(item.artifact),
+        [field.urlKey]: await resolve(item.artifact, resourceFields(item, field.resourceFields)),
         ...Object.fromEntries(Object.entries(field.fieldKeys)
           .filter(([source]) => item.fields?.[source] !== undefined)
           .map(([source, target]) => [target, item.fields![source] as CanonicalValue])),
@@ -178,30 +183,23 @@ export function assertMappingCoversPorts(
     if (isMediaPort(port)) {
       const media = port.value;
       const itemFields = media.itemFields ?? [];
-      if (itemFields.length > 0) {
-        assert(field.as === "itemObject", `${subject} must use itemObject because the port carries item fields`);
-        for (const item of itemFields) {
-          if (item.optional === true) continue;
-          assert(field.fieldKeys[item.name] !== undefined,
-            `${subject} does not map required item field ${item.name}`);
-        }
-        Object.keys(field.fieldKeys).forEach((name) => assert(
-          itemFields.some((item) => item.name === name),
-          `${subject} maps unknown item field ${name}`,
-        ));
-        continue;
-      }
-      assert(media.accepts.length === 1,
+      assert(itemFields.length > 0 || media.accepts.length === 1,
         `${subject} accepts ${media.accepts.join(", ")}; declare one port per media role so each maps to one wire field`);
       assert(field.as === "url" || field.as === "urlArray" || field.as === "itemObject",
         `${subject} must resolve media to a URL`);
       if (field.as === "url") {
         assert(port.maxItems === 1, `${subject} uses url but the port accepts up to ${port.maxItems} items`);
       }
-      if (field.as === "itemObject") {
-        assert(field.fieldKeys !== undefined && Object.keys(field.fieldKeys).length === 0,
-          `${subject} itemObject must not map undeclared item fields`);
+      const mappedFields = [
+        ...(field.resourceFields ?? []),
+        ...(field.as === "itemObject" ? Object.keys(field.fieldKeys) : []),
+      ];
+      for (const item of itemFields) {
+        if (item.optional !== true) assert(mappedFields.includes(item.name),
+          `${subject} does not map required item field ${item.name}`);
       }
+      for (const name of mappedFields) assert(itemFields.some((item) => item.name === name),
+        `${subject} maps unknown item field ${name}`);
       continue;
     }
     if (port.maxItems > 1) {

package/packages/gpt-image/README.md

@@ -5,8 +5,7 @@ Exact model/compute contracts for GPT Image 2 requests.
 One closed Port Table accepts the supported scalar settings and optional reference images. Runtime-
 produced references remain explicit Blob edges: the model-owned Draft is bound one edge at a time,
 then finalized into the only `GenerationRequest` a Provider can receive. The package owns model
-semantics but no API key, Provider selection, queue or network code. `@hypit/provider-kie` is
-one optional Runtime implementation.
+semantics but no API key, Provider selection, queue or network code. The selected Provider implements its exact capability.
 
 Provider-specific combination limits are checked by that Provider before any paid operation. They
 do not narrow this model-owned vocabulary or leak into author source.

package/packages/grok-imagine/README.md

@@ -4,8 +4,7 @@ Exact author/compute contracts and package-owned author Surfaces for Grok Imagin
 
 It exposes the standard and 1.5-preview models as distinct Surfaces. Each request is nominally typed and
 validated before yielding an ordinary video Artifact. The package declares the model
-choice; it does not route to another model or access a Provider. `@hypit/provider-kie` is one
-optional Runtime implementation.
+choice; it does not route to another model or access a Provider. The selected Provider implements its exact capability.
 
 ```xml
 <grok:Video id="clip" prompt={prompt} duration="6" aspect-ratio="9:16" resolution="720p">

package/packages/hyperframes/README.md

@@ -55,13 +55,17 @@ This keeps actual video available to the renderer's exact source-frame preparati
 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
+`render(localFrame)` function, evaluated on initial load and active `hf-seek` events. Outside the
+Present's lifetime, the dispatcher settles the boundary pose once instead of repeatedly updating
+an invisible program. Active seeks always redraw, including the same frame after resources become
+ready, and seeking back into the Present computes its requested pose directly. Prepare stable
+objects in `setup`; express animation state as a function of 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
+unchanged. `projectTimelineMedia` from `@hypit/hypit/timeline` 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

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

@@ -63,13 +63,22 @@ export function browserProgramScript(entries: readonly {
         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 };
+        return { ...entry, render, region: undefined };
       } 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))); }
+        const local = frame - entry.startFrame;
+        const region = local < 0 ? 'before' : local >= entry.durationFrames ? 'after' : 'active';
+        // Preserve the initial/boundary pose, but stop updating an invisible
+        // program at the same clamped endpoint. Active seeks always render,
+        // including repeated frame 0 after images/fonts finish loading.
+        if (region !== 'active' && entry.region === region) continue;
+        try {
+          entry.render(Math.max(0, Math.min(entry.durationFrames, local)));
+          entry.region = region;
+        }
         catch (error) { fail(error); }
       }
     };

package/packages/hyperframes/src/document.ts

@@ -461,7 +461,7 @@ function renderVisualPresent(
     emittedFilterIds,
     stableId,
   });
-  return `<div class="clip hypit-visual-present" data-hypit-track-id="${escapeHtml(track.id)}" data-hypit-present-id="${escapeHtml(present.id)}" data-hypit-stack-order="${present.stacking.order}" data-hypit-stack-tie="${escapeHtml(present.stacking.tieBreak)}" data-track-index="${stackIndex}" data-start="${start}" data-duration="${duration}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${contents}</div>`;
+  return `<div class="clip hypit-visual-present" data-hypit-track-id="${escapeHtml(track.id)}" data-hypit-present-id="${escapeHtml(present.id)}" data-hypit-stack-order="${present.stacking.order}" data-hypit-stack-tie="${escapeHtml(present.stacking.tieBreak)}" data-track-index="${stackIndex}" data-start="${start}" data-duration="${duration}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${present.visibility === undefined ? contents : `<div data-hypit-visibility="${escapeHtml(JSON.stringify(present.visibility))}" style="position:absolute;inset:0">${contents}</div>`}</div>`;
 }
 
 function renderAnimationRules(track: VisualTrack, present: VisualPresent, stableId: StableDomId): string[] {
@@ -667,6 +667,18 @@ function emitHtml(composition: Composition, programSpace: ProgramSpace): string
   }]));
   const programCss = programs.map(entry => `@scope (#${entry.id}) { ${entry.program.css ?? ""} }`).join("\n");
   const programRuntime = programs.length === 0 ? "" : `<script>${browserProgramScript(programs, numerator, denominator)}</script>`;
+  const visibilityRuntime = visuals.some(({ present }) => present.visibility !== undefined) ? `<script>
+(() => {
+  const entries = [...document.querySelectorAll('[data-hypit-visibility]')].map(element => ({ element, spans: JSON.parse(element.dataset.hypitVisibility) }));
+  const apply = time => {
+    const frame = Math.round(Number(time || 0) * ${numerator} / ${denominator});
+    // A presentation mask controls painting, not layout or animation existence.
+    // display:none removes CSS animations and prevents hidden text from being measured.
+    for (const { element, spans } of entries) element.style.opacity = spans.some(s => frame >= s.startFrame && frame < s.endFrameExclusive) ? '' : '0';
+  };
+  apply(0);
+  window.addEventListener('hf-seek', event => apply(event.detail?.time));
+})();</script>` : "";
   const duration = frameSeconds(programSpaceFrameCount(programSpace), numerator, denominator);
   const fps = fpsRational(numerator, denominator);
   const frameCount = programSpaceFrameCount(programSpace);
@@ -693,7 +705,8 @@ function emitHtml(composition: Composition, programSpace: ProgramSpace): string
 <body>
   <div data-composition-id="${escapeHtml(composition.id)}" data-start="0" data-no-timeline data-width="${composition.canvas.width}" data-height="${composition.canvas.height}" data-duration="${duration}" data-fps="${fps}" data-hypit-frame-count="${frameCount}">
     ${visualHtml}
-  </div>${programRuntime}${animationRuntime}${textRuntime}
+  </div>${programRuntime}
+  ${visibilityRuntime}${animationRuntime}${textRuntime}
 </body>
 </html>
 `;

package/packages/interview-emoji-reveal/README.md

@@ -1,7 +1,7 @@
 # Emoji Reveal
 
-The Track Surface accepts `semantic={speech.semantic}` or `space={animation}`. Semantic context
-resolves Script Selections and Moments; authored space supports clock-based animation. Shared `at`
+The Track Surface accepts `timeline={program.timeline}`. The same Timeline supports authored
+positions and, where prepared Takes supply evidence, Script Selections and Moments. Shared `at`
 inputs accept a Moment or a time such as `2s`; `at` with `for` produces a Window where required.
 
 Reusable Hypit author vocabulary for a top-of-frame icon answer strip.
@@ -21,7 +21,7 @@ answers remain and later slots remain unanswered.
 
 <emoji:Style id="emoji-strip" recipe={styles.emoji-strip}/>
 
-<emoji:Track id="rules" semantic={speech.semantic} canvas={vertical}
+<emoji:Track id="rules" timeline={speech.timeline} canvas={vertical}
   style={emoji-strip} placeholder={question-icon} during="program">
   <emoji:Item id="manifest" icon={manifest-icon} preset="true"/>
   <emoji:Item id="real-estate" icon={real-estate-icon} at={story.moment.real-estate}/>
@@ -30,7 +30,7 @@ answers remain and later slots remain unanswered.
 ```
 
 `Selection`, `Segment`, numeric instants and a `boundary` fallback are deliberately not part of an
-Item's vocabulary. The component consumes only `ProgramSpace`, the projected outer Window and the
+Item's vocabulary. The component consumes the shared `Timeline`, the projected outer Window and the
 projected Instants; it does not interpret Script semantics itself and has no Studio dependency.
 
 The bundled preview icons come from [Tabler Icons](https://tabler.io/icons), distributed under the

package/packages/interview-emoji-reveal/package.json

@@ -14,7 +14,7 @@
     "@hypit/narrative": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/spatial": "workspace:*",
     "@hypit/svs": "workspace:*",
     "@hypit/temporal": "workspace:*",

package/packages/interview-emoji-reveal/src/component.ts

@@ -1,7 +1,7 @@
+import type { Timeline } from "@hypit/timeline";
 import type { ComponentPackage } from "@hypit/component-kit";
 import { canonicalize } from "@hypit/protocol";
 import type { BlobRef, StoredValue } from "@hypit/protocol";
-import type { ProgramSpace } from "@hypit/program-space";
 import type { CanvasSpace } from "@hypit/spatial";
 import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
 
@@ -23,7 +23,7 @@ export const emojiRevealComponent = {
   producers: [
     { producer: emojiRevealProducers.createSet, handler: () => ({ outputs: { set: output(createEmojiRevealSet()) }, needs: {} }) },
     { producer: emojiRevealProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: output(appendEmojiRevealItem(
-      inline<EmojiRevealSet>(inputs.set?.value, "EmojiRevealSet"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+      inline<EmojiRevealSet>(inputs.set?.value, "EmojiRevealSet"), inline<Timeline>(inputs.timeline?.value, "Timeline"),
       inline<EmojiRevealItemSpec>(inputs.spec?.value, "EmojiRevealItemSpec"), blob(inputs.icon?.value, "Emoji Reveal icon"),
       inline<TemporalInstant>(inputs.activation?.value, "TemporalInstant"),
     )) }, needs: {} }) },
@@ -32,12 +32,12 @@ export const emojiRevealComponent = {
       inline<EmojiRevealItemSpec>(inputs.spec?.value, "EmojiRevealItemSpec"), blob(inputs.icon?.value, "Emoji Reveal icon"),
     )) }, needs: {} }) },
     { producer: emojiRevealProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeEmojiReveal(
-      inline<EmojiRevealHeader>(inputs.header?.value, "EmojiRevealHeader"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+      inline<EmojiRevealHeader>(inputs.header?.value, "EmojiRevealHeader"), inline<Timeline>(inputs.timeline?.value, "Timeline"),
       inline<TemporalWindow>(inputs.outer?.value, "TemporalWindow"), inline<EmojiRevealStyle>(inputs.style?.value, "EmojiRevealStyle"),
       blob(inputs.placeholder?.value, "Emoji Reveal placeholder"), inline<EmojiRevealSet>(inputs.set?.value, "EmojiRevealSet"),
     )) }, needs: {} }) },
     { producer: emojiRevealProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderEmojiReveal(
-      inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+      inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), inline<Timeline>(inputs.timeline?.value, "Timeline"),
       inline<EmojiRevealProgram>(inputs.program?.value, "EmojiRevealProgram"),
     )) }, needs: {} }) },
   ],

package/packages/interview-emoji-reveal/src/fragment.ts

@@ -1,4 +1,5 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+
 import { compositionTypes } from "@hypit/composition";
 import { artifactTypes } from "@hypit/artifact";
 import { sealGraphFragment } from "@hypit/elaborator";
@@ -29,23 +30,23 @@ export function createEmojiRevealFragment(items: readonly EmojiRevealFragmentIte
       : emojiRevealProducers.appendItem, inputs: {
       set: operation(current), spec: input(item.specName), icon: input(item.iconName),
       ...(item.activationName === undefined ? {} : {
-        space: input("space"), activation: input(item.activationName),
+        timeline: input("timeline"), activation: input(item.activationName),
       }),
     }, result: { kind: "output", name: "set" } });
     current = id;
   });
   operations.push(
     { id: "emoji:program", producer: emojiRevealProducers.finalize, inputs: {
-      header: input("header"), space: input("space"), outer: input("outer"), style: input("style"),
+      header: input("header"), timeline: input("timeline"), outer: input("outer"), style: input("style"),
       placeholder: input("placeholder"), set: operation(current),
     }, result: { kind: "output", name: "program" } },
     { id: "emoji:track", producer: emojiRevealProducers.render, inputs: {
-      canvas: input("canvas"), space: input("space"), program: operation("emoji:program"),
+      canvas: input("canvas"), timeline: input("timeline"), program: operation("emoji:program"),
     }, result: { kind: "output", name: "track" } },
   );
   return sealGraphFragment({
     inputs: [
-      { name: "header", type: emojiRevealTypes.header }, { name: "space", type: programSpaceTypes.programSpace },
+      { name: "header", type: emojiRevealTypes.header }, { name: "timeline", type: timelineTypes.track },
       { name: "canvas", type: spatialTypes.canvas }, { name: "outer", type: temporalTypes.window }, { name: "style", type: emojiRevealTypes.style },
       { name: "placeholder", type: artifactTypes.blob },
       ...items.flatMap((item) => [

package/packages/interview-emoji-reveal/src/manifest.ts

@@ -1,12 +1,13 @@
+import { timelineTypes } from "@hypit/timeline";
 import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { readFile } from "node:fs/promises";
 
 import { artifactDependency, artifactTypes } from "@hypit/artifact";
 import { compositionDependency, compositionTypes } from "@hypit/composition";
 import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+
 import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { semanticTrackDependency } from "@hypit/semantic-track";
+import { timelineDependency } from "@hypit/timeline";
 import { spatialDependency, spatialTypes } from "@hypit/spatial";
 import { svsRecipeType } from "@hypit/svs";
 import { temporalDependency, temporalInstantSchema, temporalTypes, temporalWindowSchema } from "@hypit/temporal";
@@ -107,7 +108,7 @@ export const emojiRevealMarkupSurfaces = [
           recipe: recipe.map(([name, fallback, summary]) => ({ name, required: false, fallback, summary })) },
       ],
       example: `<emoji:Style id="emoji-strip" recipe={styles.emoji-strip}/>` ,
-      notes: ["The Style owns appearance and placement, but never semantic timing."],
+      notes: ["The Style owns appearance and placement, but never event timing."],
     } },
   { name: "track", tag: "Track", mode: "structured",
     outputs: [emojiRevealTypes.header, emojiRevealTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, emojiRevealTypes.program, compositionTypes.visualTrack],
@@ -133,7 +134,7 @@ export const emojiRevealMarkupSurfaces = [
         { name: "program", type: emojiRevealTypes.program, summary: "The adaptive strip with its projected outer Window and fully traced Moment activations." },
         { name: "track", type: compositionTypes.visualTrack, summary: "That Program rendered as an ordinary VisualTrack." },
       ],
-      example: `<emoji:Track id="rules" semantic={speech.semantic} canvas={vertical} style={emoji-strip} placeholder={question-icon} during="program">
+      example: `<emoji:Track id="rules" timeline={speech.timeline} canvas={vertical} style={emoji-strip} placeholder={question-icon} during="program">
   <emoji:Item id="manifest" icon={manifest-icon} preset="true"/>
   <emoji:Item id="real-estate" icon={real-estate-icon} at={story.moment.real-estate}/>
   <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story.moment.bitcoin}/>
@@ -148,7 +149,7 @@ export const emojiRevealMarkupSurfaces = [
 
 export const emojiRevealManifest: ModuleManifest = {
   format: "hypit.module@1", name: emojiRevealModuleRef.name, version: emojiRevealModuleRef.version,
-  dependencies: [artifactDependency, narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, compositionDependency],
+  dependencies: [artifactDependency, narrativeDependency, timelineDependency, spatialDependency, temporalDependency, compositionDependency],
   types: [
     { name: emojiRevealTypes.header.name }, { name: emojiRevealTypes.style.name },
     { name: emojiRevealTypes.itemSpec.name }, { name: emojiRevealTypes.set.name }, { name: emojiRevealTypes.program.name },
@@ -157,16 +158,16 @@ export const emojiRevealManifest: ModuleManifest = {
   producers: [
     { name: emojiRevealProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: emojiRevealTypes.set }], needs: [] },
     { name: emojiRevealProducers.appendItem.name,
-      inputs: [{ name: "set", type: emojiRevealTypes.set }, { name: "space", type: programSpaceTypes.programSpace }, { name: "spec", type: emojiRevealTypes.itemSpec }, { name: "icon", type: artifactTypes.blob }, { name: "activation", type: temporalTypes.instant }],
+      inputs: [{ name: "set", type: emojiRevealTypes.set }, { name: "timeline", type: timelineTypes.track }, { name: "spec", type: emojiRevealTypes.itemSpec }, { name: "icon", type: artifactTypes.blob }, { name: "activation", type: temporalTypes.instant }],
       outputs: [{ name: "set", type: emojiRevealTypes.set }], needs: [] },
     { name: emojiRevealProducers.appendPresetItem.name,
       inputs: [{ name: "set", type: emojiRevealTypes.set }, { name: "spec", type: emojiRevealTypes.itemSpec }, { name: "icon", type: artifactTypes.blob }],
       outputs: [{ name: "set", type: emojiRevealTypes.set }], needs: [] },
     { name: emojiRevealProducers.finalize.name,
-      inputs: [{ name: "header", type: emojiRevealTypes.header }, { name: "space", type: programSpaceTypes.programSpace }, { name: "outer", type: temporalTypes.window }, { name: "style", type: emojiRevealTypes.style }, { name: "placeholder", type: artifactTypes.blob }, { name: "set", type: emojiRevealTypes.set }],
+      inputs: [{ name: "header", type: emojiRevealTypes.header }, { name: "timeline", type: timelineTypes.track }, { name: "outer", type: temporalTypes.window }, { name: "style", type: emojiRevealTypes.style }, { name: "placeholder", type: artifactTypes.blob }, { name: "set", type: emojiRevealTypes.set }],
       outputs: [{ name: "program", type: emojiRevealTypes.program }], needs: [] },
     { name: emojiRevealProducers.render.name,
-      inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: emojiRevealTypes.program }],
+      inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "timeline", type: timelineTypes.track }, { name: "program", type: emojiRevealTypes.program }],
       outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
   ],
 };

package/packages/interview-emoji-reveal/src/program.ts

@@ -1,7 +1,7 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
 import type { VisualAnimation, VisualElement, VisualTrack } from "@hypit/composition";
 import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import { canonicalize } from "@hypit/protocol";
 import type { BlobRef } from "@hypit/protocol";
 import { assertCanvasSpace } from "@hypit/spatial";
@@ -67,11 +67,11 @@ export function assertEmojiRevealSet(value: EmojiRevealSet): void {
   }
 }
 
-export function appendEmojiRevealItem(set: EmojiRevealSet, space: ProgramSpace, spec: EmojiRevealItemSpec, icon: BlobRef, activation: TemporalInstant): EmojiRevealSet {
-  assertEmojiRevealSet(set); assertProgramSpaceIdentity(space); assertEmojiRevealItemSpec(spec);
+export function appendEmojiRevealItem(set: EmojiRevealSet, timeline: Timeline, spec: EmojiRevealItemSpec, icon: BlobRef, activation: TemporalInstant): EmojiRevealSet {
+  assertEmojiRevealSet(set); assertProgramSpaceIdentity(timeline); assertEmojiRevealItemSpec(spec);
   assert(!spec.preset, `Emoji Reveal Item ${spec.id} with preset=true cannot have an activation.`);
   assertIconImage(icon, `Emoji Reveal Item ${spec.id} icon`);
-  assertTemporalInstantFor(activation, { subjectId: spec.id, space });
+  assertTemporalInstantFor(activation, { subjectId: spec.id, space: timeline });
   assert(!set.items.some((item) => item.spec.id === spec.id), `Duplicate Emoji Reveal Item ${spec.id}.`);
   return { items: [...set.items, { spec: structuredClone(spec), icon: structuredClone(icon), activation: structuredClone(activation) }] };
 }
@@ -85,11 +85,11 @@ export function appendPresetEmojiRevealItem(set: EmojiRevealSet, spec: EmojiReve
 }
 
 export function finalizeEmojiReveal(
-  header: EmojiRevealHeader, space: ProgramSpace, outer: TemporalWindow, style: EmojiRevealStyle, placeholder: BlobRef, set: EmojiRevealSet,
+  header: EmojiRevealHeader, timeline: Timeline, outer: TemporalWindow, style: EmojiRevealStyle, placeholder: BlobRef, set: EmojiRevealSet,
 ): EmojiRevealProgram {
-  assertEmojiRevealHeader(header); assertProgramSpaceIdentity(space); assertEmojiRevealStyle(style); assertEmojiRevealSet(set);
+  assertEmojiRevealHeader(header); assertProgramSpaceIdentity(timeline); assertEmojiRevealStyle(style); assertEmojiRevealSet(set);
   assertIconImage(placeholder, "Emoji Reveal placeholder");
-  assertTemporalWindowFor(outer, { subjectId: header.id, space });
+  assertTemporalWindowFor(outer, { subjectId: header.id, space: timeline });
   assert(set.items.length > 0, "Emoji Reveal requires at least one Item.");
   let previous = outer.span.startFrame - 1;
   let revealStarted = false;
@@ -106,7 +106,7 @@ export function finalizeEmojiReveal(
     previous = frame;
   }
   const program: EmojiRevealProgram = {
-    id: header.id, programSpaceId: space.id, outer: structuredClone(outer), style: structuredClone(style),
+    id: header.id, programSpaceId: timeline.id, outer: structuredClone(outer), style: structuredClone(style),
     placeholder: structuredClone(placeholder), items: structuredClone(set.items),
   };
   assertEmojiRevealProgram(program);
@@ -183,10 +183,10 @@ function iconElement(input: {
   };
 }
 
-export function renderEmojiReveal(canvas: CanvasSpace, space: ProgramSpace, program: EmojiRevealProgram): VisualTrack {
-  assertCanvasSpace(canvas); assertProgramSpaceIdentity(space); assertEmojiRevealProgram(program);
-  assert(program.programSpaceId === space.id, "EmojiRevealProgram belongs to another ProgramSpace.");
-  assertTemporalWindowFor(program.outer, { subjectId: program.id, space });
+export function renderEmojiReveal(canvas: CanvasSpace, timeline: Timeline, program: EmojiRevealProgram): VisualTrack {
+  assertCanvasSpace(canvas); assertProgramSpaceIdentity(timeline); assertEmojiRevealProgram(program);
+  assert(program.programSpaceId === timeline.id, "EmojiRevealProgram belongs to another Timeline.");
+  assertTemporalWindowFor(program.outer, { subjectId: program.id, space: timeline });
   const { style } = program;
   const count = program.items.length;
   const width = style.paddingXPx * 2 + style.slotSizePx * count + style.gapPx * (count - 1);
@@ -234,9 +234,9 @@ export function renderEmojiReveal(canvas: CanvasSpace, space: ProgramSpace, prog
     );
   });
   const track = sealVisualTrack({
-    programSpaceId: space.id, visualIr: "hypit.visual-ir@1", id: program.id,
+    programSpaceId: timeline.id, visualIr: "hypit.visual-ir@1", id: program.id,
     presents: [{ id: program.id, subjectId: program.id, span: { ...program.outer.span },
       stacking: { order: style.stackingOrder, tieBreak: program.id }, elements }],
   });
-  assertVisualTrackIdentity(track, space); return track;
+  assertVisualTrackIdentity(track, timeline); return track;
 }

package/packages/interview-emoji-reveal/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import {
   assertAttributes, assertEmptyElement, optionalTextAttribute, textAttribute, type MarkupAttributeValue, type StructuredSurfaceHandler,
   type SurfaceComponentDraft, type SurfaceRecordDraft, type SurfaceResolvedReference,
@@ -48,24 +48,23 @@ export const decodeEmojiRevealStyleSurface: StructuredSurfaceHandler = ({ elemen
 };
 
 export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  assertAttributes(element, ["id", "semantic", "space", "canvas", "style", "placeholder", ...temporalWindowAttributeNames]);
+  assertAttributes(element, ["id", "timeline", "canvas", "style", "placeholder", ...temporalWindowAttributeNames]);
   const id = textAttribute(element, "id");
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
   const style = reference(element.attributes.style, `${element.name}.style`, emojiRevealTypes.style, resolveReference);
   const placeholder = reference(element.attributes.placeholder, `${element.name}.placeholder`, artifactTypes.blob, resolveReference);
-  const outer = createTemporalWindowProjection({ id, subjectId: id, element, ...context, space: time.space, resolveReference });
+  const outer = createTemporalWindowProjection({ id, subjectId: id, element, ...context, resolveReference });
   const headerId = `${id}.header`;
   const records: SurfaceRecordDraft[] = [...outer.records, {
     id: headerId, type: emojiRevealTypes.header,
     value: { kind: "inline", value: sealEmojiRevealHeader({ id }) as unknown as CanonicalValue }, range: element.range,
   }];
-  const temporalComponents: SurfaceComponentDraft[] = [...time.components, ...outer.components];
-  const temporalFragments = [...time.fragments, ...outer.fragments];
+  const temporalComponents: SurfaceComponentDraft[] = [...outer.components];
+  const temporalFragments = [...outer.fragments];
   const items: { specName: string; iconName: string; activationName?: string }[] = [];
-  const inputs: Record<string, typeof time.space.ref> = {
-    header: { kind: "record", id: headerId }, space: time.space.ref, canvas: canvas.ref, style: style.ref,
+  const inputs: Record<string, typeof context.timeline.ref> = {
+    header: { kind: "record", id: headerId }, timeline: context.timeline.ref, canvas: canvas.ref, style: style.ref,
     placeholder: placeholder.ref, outer: outer.ref,
   };
   const ids = new Set<string>();
@@ -92,7 +91,7 @@ export const decodeEmojiRevealTrackSurface: StructuredSurfaceHandler = ({ elemen
     else {
       const activation = createTemporalInstantProjection({
         id: `${id}.item.${suffix}.activation`, subjectId: itemId,
-        element: child, ...context, space: time.space, resolveReference, semanticAttribute: "at", projectedAttribute: false,
+        element: child, ...context, resolveReference, semanticAttribute: "at", projectedAttribute: false,
       });
       records.push(...activation.records); temporalComponents.push(...activation.components); temporalFragments.push(...activation.fragments);
       const activationName = `item-${suffix}-activation`;

package/packages/media-execution/README.md

@@ -20,9 +20,13 @@ owns the byte-level implementations of the eight current operations:
 - render an exact sample-domain audio program;
 - mux rendered visual and audio products.
 
-Local and AWS Lambda Providers call these same functions with different Artifact I/O and FFmpeg
-launch environments. They therefore share stream selection, timing, codec and validation behavior
-instead of reimplementing media semantics per deployment.
+The local Provider calls these functions with its Artifact I/O and FFmpeg launch environment. Other
+deployments can reuse the same functions to preserve stream selection, timing, codec and validation behavior.
 
 This is not an author package, Provider, queue or Core extension. It performs no endpoint selection,
 credential lookup or SVML parsing.
+
+Audio gain envelopes and audible subranges are evaluated per sample after tempo/looping and Clip
+fades, before the requested range is cropped. Original source and envelope progress therefore survive
+local silence and range rendering. This is generic AudioProgramPlan execution, independent of author
+component or Style names.

package/packages/media-execution/src/audio-presentation.ts

@@ -0,0 +1,23 @@
+import type { AudioProgramClip } from "@hypit/media-pipeline";
+
+/** Per-sample gain after source playback/fades, before any requested render-range crop. */
+export function audioPresentationFilter(clip: AudioProgramClip): string[] {
+  if (clip.gainEnvelope === undefined && clip.audibility === undefined) return [];
+  const sample = `(n+${clip.targetStartSample})`;
+  let gain = "1";
+  const points = clip.gainEnvelope;
+  if (points !== undefined) {
+    gain = String(points.at(-1)!.gain);
+    for (let index = points.length - 1; index > 0; index--) {
+      const left = points[index - 1]!, right = points[index]!;
+      const line = `(${left.gain}+(${right.gain}-${left.gain})*(${sample}-${left.sample})/${right.sample-left.sample})`;
+      gain = `if(lt(${sample},${right.sample}),${line},${gain})`;
+    }
+    gain = `if(lt(${sample},${points[0]!.sample}),${points[0]!.gain},${gain})`;
+  }
+  if (clip.audibility !== undefined) {
+    const active = clip.audibility.map(span => `(gte(${sample},${span.startSample})*lt(${sample},${span.endSampleExclusive}))`).join("+") || "0";
+    gain = `(${gain})*(${active})`;
+  }
+  return [`aeval=exprs='val(0)*(${gain})|val(1)*(${gain})'`];
+}

package/packages/media-execution/src/execute.ts

@@ -1,3 +1,4 @@
+import { audioPresentationFilter } from "./audio-presentation.js";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
@@ -556,6 +557,7 @@ function audioClipFilter(clip: AudioProgramClip, inputIndex: number, outputIndex
     ...(clip.fadeOutSamples === 0 ? [] : [
       `afade=t=out:start_sample=${length - clip.fadeOutSamples}:nb_samples=${clip.fadeOutSamples}`,
     ]),
+    ...audioPresentationFilter(clip),
     // Crop after tempo, looping and envelopes, keeping their original phase.
     `atrim=start_sample=${left - clip.targetStartSample}:end_sample=${right - clip.targetStartSample}`,
     "asetpts=N/SR/TB",

package/packages/media-pipeline/README.md

@@ -37,7 +37,7 @@ This package is the shared execution vocabulary. Speech authoring makes the boun
 alignment produce one `SemanticTake`. Media Track consumes that prepared value; it never owns an
 implicit visual-only normalization policy.
 
-The frame clock is a separate program fact and can be shared by every Normalize and Speech Track:
+The frame clock is a separate program fact and can be shared by every Normalize and Timeline assembly:
 
 ```svml
 <program:Clock id="clock" frame-rate="30"/>
@@ -109,5 +109,9 @@ RenderedVisual + TimelineAudio -> mux-program-media Need -> MuxedMedia
 Compiling an `AudioProgramPlan` is ordinary deterministic code. Reading Artifact bytes, decoding,
 resampling, mixing, encoding or muxing is never a Producer shortcut: it is an explicit Provider
 Need. The plan fixes exact 48 kHz sample boundaries, gain/fade/playback parameters and the absence
-of hidden normalization/limiting. The local FFmpeg and AWS Lambda Providers consume the same shared
-execution body and return the same public contracts.
+of hidden normalization/limiting. The local FFmpeg Provider consumes the shared execution body. Other Providers implement the same
+public request and result semantics.
+
+AudioProgramPlan preserves AudioClip `gainEnvelope` and `audibility` on the full program sample
+clock. The [Composition definition](../composition/README.md#audio-presentation-on-the-program-clock)
+owns their semantics; the plan does not reinterpret source choice or presentation precedence.