@hypit/hypit 0.1.4 → 0.1.5

package/dist/public/{semantic-track.d.ts → timeline.d.ts}

@@ -143,11 +143,11 @@ type ProducerHandlerContext = {
     readonly inputs: Readonly<Record<string, TypedRecord>>;
 };
 
-declare const semanticTrackComponent: {
+declare const timelineComponent: {
     producers: ({
         producer: {
             module: {
-                readonly name: "@hypit/semantic-track";
+                readonly name: "@hypit/timeline";
                 readonly version: "1";
             };
             name: string;
@@ -164,7 +164,7 @@ declare const semanticTrackComponent: {
     } | {
         producer: {
             module: {
-                readonly name: "@hypit/semantic-track";
+                readonly name: "@hypit/timeline";
                 readonly version: "1";
             };
             name: string;
@@ -182,7 +182,7 @@ declare const semanticTrackComponent: {
     validators: {
         type: {
             module: {
-                readonly name: "@hypit/semantic-track";
+                readonly name: "@hypit/timeline";
                 readonly version: "1";
             };
             name: string;
@@ -191,6 +191,16 @@ declare const semanticTrackComponent: {
     }[];
 };
 
+type ProgramSpace = {
+    /** Author-visible identity of this film time axis. */
+    readonly id: string;
+    readonly durationSec: number;
+    readonly frameRate: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+};
+
 type MediaRational = {
     readonly numerator: number;
     readonly denominator: number;
@@ -278,20 +288,17 @@ type NarrativeExcerpt = {
     readonly tokenEndExclusive: number;
 };
 
-type SemanticTrackItem = {
+type TimelineItem = {
     readonly take: SemanticTake;
+    readonly startFrame: number;
 };
-/**
- * The continuous program skeleton. Every item is a real SemanticTake and the
- * global frame domain is exactly their prefix sum: no gap or empty item exists.
- */
-type SemanticTrack = {
-    readonly id: string;
-    readonly narrativeId: string;
-    readonly items: readonly SemanticTrackItem[];
+/** One complete film time range, with prepared material placed where it belongs. */
+type Timeline = ProgramSpace & {
+    readonly narrativeId?: string;
+    readonly items: readonly TimelineItem[];
 };
-type SemanticTrackSpan = {
-    readonly item: SemanticTrackItem;
+type TimelineSpan = {
+    readonly item: TimelineItem;
     readonly startFrame: number;
     readonly endFrameExclusive: number;
 };
@@ -300,68 +307,74 @@ type LocatedFrameSpan = {
     readonly endFrameExclusive: number;
 };
 
-declare function sealSemanticTrack(value: SemanticTrack): SemanticTrack;
-declare function assertSemanticTrackIdentity(track: SemanticTrack): void;
-declare function semanticTrackSpans(track: SemanticTrack): readonly SemanticTrackSpan[];
-declare function semanticTrackFrameCount(track: SemanticTrack): number;
+declare function sealTimeline(value: Timeline): Timeline;
+declare function assertTimelineIdentity(track: Timeline): void;
+declare function timelineSpans(track: Timeline): readonly TimelineSpan[];
+declare function timelineFrameCount(track: Timeline): number;
 
 declare function assertNarrativeSelectionIdentity(selection: NarrativeSelectionRef): void;
 declare function assertNarrativeMomentIdentity(moment: NarrativeMomentRef): void;
-declare function semanticAnchorFrames(track: SemanticTrack): ReadonlyMap<string, number>;
-declare function selectionFrameSpan(track: SemanticTrack, selection: NarrativeSelectionRef): LocatedFrameSpan;
-declare function segmentFrameSpan(track: SemanticTrack, segment: NarrativeExcerpt): LocatedFrameSpan;
-declare function tokenFrameSpan(track: SemanticTrack, tokenIds: readonly string[]): LocatedFrameSpan | undefined;
-declare function momentFrame(track: SemanticTrack, moment: NarrativeMomentRef): number;
+declare function semanticAnchorFrames(track: Timeline): ReadonlyMap<string, number>;
+declare function selectionFrameSpan(track: Timeline, selection: NarrativeSelectionRef): LocatedFrameSpan;
+declare function segmentFrameSpan(track: Timeline, segment: NarrativeExcerpt): LocatedFrameSpan;
+declare function tokenFrameSpan(track: Timeline, tokenIds: readonly string[]): LocatedFrameSpan | undefined;
+declare function momentFrame(track: Timeline, moment: NarrativeMomentRef): number;
 
-declare const semanticTrackModuleRef: {
-    readonly name: "@hypit/semantic-track";
+declare const timelineModuleRef: {
+    readonly name: "@hypit/timeline";
     readonly version: "1";
 };
-declare const semanticTrackTypes: {
+declare const timelineTypes: {
     track: {
         module: {
-            readonly name: "@hypit/semantic-track";
+            readonly name: "@hypit/timeline";
             readonly version: "1";
         };
         name: string;
     };
 };
-declare const semanticTrackProducers: {
+declare const timelineProducers: {
     projectProgramSpace: {
         module: {
-            readonly name: "@hypit/semantic-track";
+            readonly name: "@hypit/timeline";
             readonly version: "1";
         };
         name: string;
     };
     projectAudio: {
         module: {
-            readonly name: "@hypit/semantic-track";
+            readonly name: "@hypit/timeline";
             readonly version: "1";
         };
         name: string;
     };
 };
-declare const semanticTrackSchema: ValueSchema;
-declare const semanticTrackManifest: ModuleManifest;
-declare const semanticTrackDependency: {
+declare const timelineSchema: ValueSchema;
+declare const timelineManifest: ModuleManifest;
+declare const timelineDependency: {
     readonly module: {
-        readonly name: "@hypit/semantic-track";
+        readonly name: "@hypit/timeline";
         readonly version: "1";
     };
 };
 
-type ProgramSpace = {
-    /** Author-visible identity of this film time axis. */
-    readonly id: string;
-    readonly durationSec: number;
-    readonly frameRate: {
-        readonly numerator: number;
-        readonly denominator: number;
-    };
+/** Gain and audibility are measured on the complete 48 kHz program clock. */
+type AudioSampleSpan = {
+    readonly startSample: number;
+    readonly endSampleExclusive: number;
+};
+type AudioGainPoint = {
+    readonly sample: number;
+    readonly gain: number;
+};
+type AudioPresentation = {
+    /** Linear interpolation; hold the first/last gain outside the supplied points. */
+    readonly gainEnvelope?: readonly AudioGainPoint[];
+    /** Half-open audible regions; omission means the complete target, [] means silence. */
+    readonly audibility?: readonly AudioSampleSpan[];
 };
 
-type AudioClip = {
+type AudioClip = AudioPresentation & {
     readonly id: string;
     /** Optional domain entity implemented by this renderer Clip. */
     readonly subjectId?: string;
@@ -396,7 +409,7 @@ type AudioTrack = {
 };
 
 /** Prepared material in an authored program interval, with its original source position retained. */
-declare function projectSemanticMedia(track: SemanticTrack, window?: {
+declare function projectTimelineMedia(track: Timeline, window?: {
     startFrame: number;
     endFrameExclusive: number;
 }): {
@@ -411,8 +424,8 @@ declare function projectSemanticMedia(track: SemanticTrack, window?: {
         endFrameExclusive: number;
     };
 }[];
-declare function projectSemanticProgramSpace(track: SemanticTrack): ProgramSpace;
-declare function projectSemanticAudioTrack(track: SemanticTrack): AudioTrack;
+declare function projectTimelineSpace(track: Timeline): ProgramSpace;
+declare function projectTimelineAudio(track: Timeline): AudioTrack;
 
-export { assertNarrativeMomentIdentity, assertNarrativeSelectionIdentity, assertSemanticTrackIdentity, momentFrame, projectSemanticAudioTrack, projectSemanticMedia, projectSemanticProgramSpace, sealSemanticTrack, segmentFrameSpan, selectionFrameSpan, semanticAnchorFrames, semanticTrackComponent, semanticTrackDependency, semanticTrackFrameCount, semanticTrackManifest, semanticTrackModuleRef, semanticTrackProducers, semanticTrackSchema, semanticTrackSpans, semanticTrackTypes, tokenFrameSpan };
-export type { LocatedFrameSpan, SemanticTrack, SemanticTrackItem, SemanticTrackSpan };
+export { assertNarrativeMomentIdentity, assertNarrativeSelectionIdentity, assertTimelineIdentity, momentFrame, projectTimelineAudio, projectTimelineMedia, projectTimelineSpace, sealTimeline, segmentFrameSpan, selectionFrameSpan, semanticAnchorFrames, timelineComponent, timelineDependency, timelineFrameCount, timelineManifest, timelineModuleRef, timelineProducers, timelineSchema, timelineSpans, timelineTypes, tokenFrameSpan };
+export type { LocatedFrameSpan, Timeline, TimelineItem, TimelineSpan };

package/examples/README.md

@@ -1,15 +1,21 @@
 # Video examples
 
-Each of the three formats has one complete generation entry, `reference.svml`, with an adjacent
-`reference.svrun`. These Sources generate their main images, recurring voice references and video
-Takes, then normalize media, align the Script and compose the finished video. They need no earlier
-Build Result or manually supplied presenter, host or scene image.
+These projects demonstrate different directing and composition decisions. Read the one closest to
+the question, then trace its intent, component boundaries, semantic events and rendered behavior.
+Adapt those relationships to a new work; its scene list and styling are choices for that production.
 
-| Example | What its reference entry demonstrates |
-| --- | --- |
-| [Football ranking](ranking-football/README.md) | One generated goth host, eight generated comic B-roll images, real player icons, independent speaking Takes and a persistent tier board |
-| [Podcast](podcast/README.md) | Related host views, a generated creatine product, holding views, a split opening and a three-scene lifestyle montage |
-| [Street interview](interview/README.md) | A shared encounter and two derived close views, motivated cuts, coordinated Moment reveals, and a fresh-footage Caption tracking extension |
+| Example | What to learn | Starting material |
+| --- | --- | --- |
+| [Football ranking](ranking-football/README.md) | Independent speaking Takes, a persistent tier board and timed reveals | Generate from `reference.svrun` |
+| [Podcast](podcast/README.md) | Related host views, product references, motivated cuts and a lifestyle montage | Generate from `reference.svrun` |
+| [Street interview](interview/README.md) | A shared encounter, derived close views, coordinated Moments and Caption tracking | Generate from `reference.svrun` |
+| [Complex spoken explainer](complex-explainer/README.md) | Coordinated project scenes, moving presenter framing, independent Caption, semantic graphic events and Take-free intervals | Download its accepted media/Result bundle; render locally |
+
+The three generation entries use `reference.svml` and an adjacent `reference.svrun`. They generate
+their main images, recurring voice references and video Takes, then normalize media, align the Script
+and compose the video. They need no earlier Build Result or manually supplied presenter, host or scene
+image. The explainer instead opens a complete 137-second production with 17 accepted Takes, recorded
+demonstrations, pixel graphics and sound; its default Run reuses the supplied material.
 
 Self-contained here means a project directory: SVML, its imported SVS/Kits and the selected local
 assets. The installed Hypit Distribution supplies the imported packages. A Runtime Profile and
@@ -21,4 +27,6 @@ The other `swap-*` and nested projects preserve separate variations and reuse st
 all been rebuilt to the same generation standard as these three reference entries. A linked showcase
 video demonstrates the original production; a fresh generation is a new result and will differ.
 
-`minimal-author-package/` demonstrates independent component packaging.
+For focused package work, `minimal-author-package/` demonstrates independent component packaging;
+[provider-package](provider-package/README.md) demonstrates connecting a chosen service through a
+project Provider. Each package's public inputs and behavior belong with its implementation.

package/examples/minimal-author-package/packages/example-component/preview/preview.svml

@@ -4,11 +4,13 @@
      Candidates are supplied, and a normal Build of the same Run can regenerate the catalogue frame. -->
 <svml>
   <import as="media-track" from="@hypit/media-track@1"/>
+  <import as="sound" from="@hypit/sound@1"/>
+  <import as="performance" from="@hypit/performance@1"/>
   <import from="@hypit/script@1"/>
   <import as="wording" from="@hypit/text@1"/>
   <import as="seedance" from="@hypit/seedance@1"/>
   <import as="pipeline" from="@hypit/media-pipeline@1"/>
-  <import as="speech" from="@hypit/speech-track@1"/>
+  <import as="time" from="@hypit/timeline-author@1"/>
   <import as="whisperx" from="@hypit/whisperx@1"/>
   <import as="space" from="@hypit/spatial@1"/>
   <import as="program" from="@hypit/program-space@1"/>
@@ -29,19 +31,24 @@
   <seedance:TextVideo id="take" model="mini" prompt={direction} duration="4" generate-audio="true"/>
   <pipeline:Normalize id="take-media" source={take.video} recipe={recipes.media.aroll} clock={clock}/>
   <whisperx:SemanticTake id="showcase-semantic" narrative={story} segment={story.segment.showcase} media={take-media.media} language="en"/>
-  <speech:Track id="speech">
-    <speech:Take source={showcase-semantic.take}/>
-  </speech:Track>
-  <media-track:Track id="speech-picture" semantic={speech.semantic} canvas={vertical}>
-    <media-track:Performance during="program" frame={speech-frame}
-      appearance={recipes.media.performance}/>
-  </media-track:Track>
+  <time:Timeline id="speech" clock={clock}>
+    <time:Take source={showcase-semantic.take}/>
+  </time:Timeline>
 
-  <example:Box id="box" semantic={speech.semantic}/>
-  <film:Film id="main" canvas={vertical} semantic={speech.semantic} appearance={recipes.film.vertical}>
+  <sound:Style id="speech-sound-style"/>
+  <sound:Track id="speech-sound" timeline={speech.timeline}>
+    <sound:Use style={speech-sound-style}/>
+  </sound:Track>
+  <performance:Style id="speech-picture-style" frame={speech-frame} appearance={recipes.media.performance}/>
+  <performance:Track id="speech-picture" timeline={speech.timeline} canvas={vertical}>
+    <performance:Use style={speech-picture-style} during="program"/>
+  </performance:Track>
+
+  <example:Box id="box" timeline={speech.timeline}/>
+  <film:Film id="main" canvas={vertical} timeline={speech.timeline} appearance={recipes.film.vertical}>
     <film:Track source={speech-picture.visual}/>
-    <film:Track source={speech.audio}/>
+    <film:Track source={speech-sound.audio}/>
     <film:Track source={box.track}/>
   </film:Film>
-  <render:Video id="final" composition={main.composition} semantic={speech.semantic}/>
+  <render:Video id="final" composition={main.composition} timeline={speech.timeline}/>
 </svml>

package/examples/minimal-author-package/packages/example-component/src/component.ts

@@ -1,5 +1,5 @@
 import { sealVisualTrack } from "@hypit/hypit/composition";
-import type { ProgramSpace } from "@hypit/hypit/program-space";
+import type { Timeline } from "@hypit/hypit/timeline";
 import { canonicalize } from "@hypit/hypit/author-kit";
 import type { BlobRef, ComponentPackage, ProducerHandler, TypedRecord } from "@hypit/hypit/author-kit";
 import { VISUAL_IR_V1 } from "@hypit/hypit/visual-ir";
@@ -13,10 +13,10 @@ const output = (value: unknown) => ({ kind: "inline" as const, value: canonicali
 function blob(record: TypedRecord | undefined): BlobRef | undefined {
   return record?.value.kind === "blob" ? record.value : undefined;
 }
-function render(kind: string, space: ProgramSpace, media?: BlobRef) {
-  const frames = Math.max(1, Math.round(space.durationSec * space.frameRate.numerator / space.frameRate.denominator));
+function render(kind: string, timeline: Timeline, media?: BlobRef) {
+  const frames = Math.max(1, Math.round(timeline.durationSec * timeline.frameRate.numerator / timeline.frameRate.denominator));
   return sealVisualTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     visualIr: VISUAL_IR_V1,
     id: `example-${kind}`,
     presents: [{ id: `present-${kind}`, span: { startFrame: 0, endFrameExclusive: frames }, stacking: { order: 0, tieBreak: kind }, elements: [{
@@ -26,7 +26,7 @@ function render(kind: string, space: ProgramSpace, media?: BlobRef) {
     ] }],
   });
 }
-const producer = (kind: string): { readonly handler: ProducerHandler } => ({ handler: ({ inputs }) => ({ outputs: { track: output(render(kind, inline<ProgramSpace>(inputs.space), blob(inputs.media))) }, needs: {} }) });
+const producer = (kind: string): { readonly handler: ProducerHandler } => ({ handler: ({ inputs }) => ({ outputs: { track: output(render(kind, inline<Timeline>(inputs.timeline), blob(inputs.media))) }, needs: {} }) });
 const appendItems: { readonly handler: ProducerHandler } = { handler: ({ inputs }) => ({ outputs: { set: output({ items: [inline<{ items: readonly unknown[] }>(inputs.previous).items, inline<{ items: readonly unknown[] }>(inputs.item).items].flat() }) }, needs: {} }) };
 
 export const exampleComponent = {

package/examples/minimal-author-package/packages/example-component/src/fragment.ts

@@ -1,8 +1,7 @@
 import { compositionTypes } from "@hypit/hypit/composition";
 import { artifactTypes } from "@hypit/hypit/artifact";
 import { sealGraphFragment } from "@hypit/hypit/author-kit";
-import { semanticTrackProducers, semanticTrackTypes } from "@hypit/hypit/semantic-track";
-import { programSpaceTypes } from "@hypit/hypit/program-space";
+import { timelineTypes } from "@hypit/hypit/timeline";
 import { exampleProducers } from "./manifest.js";
 import { exampleTypes } from "./manifest.js";
 
@@ -10,12 +9,11 @@ const input = (name: string) => ({ kind: "fragment-input" as const, name });
 const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
 
 export function createExampleFragment(producer: typeof exampleProducers[keyof typeof exampleProducers], id: string, media = false) {
-  const inputs = [{ name: "semantic", type: semanticTrackTypes.track }, ...(media ? [{ name: "media", type: artifactTypes.blob }] : [])];
-  const renderInputs = { space: operation("space"), ...(media ? { media: input("media") } : {}) };
+  const inputs = [{ name: "timeline", type: timelineTypes.track }, ...(media ? [{ name: "media", type: artifactTypes.blob }] : [])];
+  const renderInputs = { timeline: input("timeline"), ...(media ? { media: input("media") } : {}) };
   return sealGraphFragment({
     inputs,
     operations: [
-      { id: "space", producer: semanticTrackProducers.projectProgramSpace, inputs: { track: input("semantic") }, result: { kind: "output", name: "space" } },
       { id, producer, inputs: renderInputs, result: { kind: "output", name: "track" } },
     ],
     exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation(id) }],

package/examples/minimal-author-package/packages/example-component/src/manifest.ts

@@ -1,8 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { compositionTypes } from "@hypit/hypit/composition";
 import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/hypit/author-kit";
-import { programSpaceTypes } from "@hypit/hypit/program-space";
-import { semanticTrackTypes } from "@hypit/hypit/semantic-track";
+import { timelineTypes } from "@hypit/hypit/timeline";
 import { temporalTypes } from "@hypit/hypit/temporal";
 import { mediaTypes } from "@hypit/hypit/media";
 import { svsRecipeType } from "@hypit/hypit/svs";
@@ -35,8 +34,7 @@ export const exampleManifest: ModuleManifest = {
     { module: artifactTypes.blob.module },
     { module: compositionTypes.visualTrack.module },
     { module: mediaTypes.fontStack.module },
-    { module: programSpaceTypes.programSpace.module },
-    { module: semanticTrackTypes.track.module },
+    { module: timelineTypes.track.module },
     { module: svsRecipeType.module },
     { module: temporalTypes.window.module },
   ],
@@ -46,7 +44,7 @@ export const exampleManifest: ModuleManifest = {
     name: producer.name,
     inputs: producer === exampleProducers.appendItems
       ? [{ name: "previous", type: exampleTypes.itemSet }, { name: "item", type: exampleTypes.itemSet }]
-      : [{ name: "space", type: programSpaceTypes.programSpace }, ...(producer === exampleProducers.renderMedia ? [{ name: "media", type: artifactTypes.blob }] : [])],
+      : [{ name: "timeline", type: timelineTypes.track }, ...(producer === exampleProducers.renderMedia ? [{ name: "media", type: artifactTypes.blob }] : [])],
     outputs: producer === exampleProducers.appendItems
       ? [{ name: "set", type: exampleTypes.itemSet }]
       : [{ name: "track", type: compositionTypes.visualTrack }],
@@ -56,11 +54,11 @@ export const exampleManifest: ModuleManifest = {
 
 const vocabulary = (summary: string, example: string) => ({
   summary,
-  appearance: "A deterministic, self-contained example surface rendered on the supplied ProgramSpace.",
+  appearance: "A deterministic, self-contained example surface rendered on the supplied Timeline.",
   preview: previewImage("Box.png"),
   attributes: [
     { name: "id", kind: "identifier" as const, required: true, summary: "Names this instance." },
-    { name: "semantic", kind: "reference" as const, required: true, accepts: [semanticTrackTypes.track], summary: "Selects the semantic timing track." },
+    { name: "timeline", kind: "reference" as const, required: true, accepts: [timelineTypes.track], summary: "Selects the complete Timeline." },
   ],
   ports: [{ name: "track", type: compositionTypes.visualTrack, summary: "The terminal VisualTrack." }],
   example,
@@ -68,9 +66,9 @@ const vocabulary = (summary: string, example: string) => ({
 });
 
 export const exampleMarkupSurfaces = [
-  { name: "box", tag: "Box", mode: "structured", outputs: [exampleTypes.box, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A framed box surface.", "<example:Box id=\"box\" semantic={speech.semantic}/>") , preview: previewImage("Box.png") } },
-  { name: "text", tag: "Text", mode: "structured", outputs: [exampleTypes.text, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A text-bearing surface.", "<example:Text id=\"title\" semantic={speech.semantic}>Hello</example:Text>"), preview: previewImage("Box.png") } },
-  { name: "media-slot", tag: "MediaSlot", mode: "structured", outputs: [exampleTypes.mediaSlot, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A media slot whose content is a graph input.", "<example:MediaSlot id=\"shot\" semantic={speech.semantic} media={shot-media}/>") , attributes: [...vocabulary("", "").attributes, { name: "media", kind: "reference" as const, required: false, accepts: [artifactTypes.blob], summary: "Optional image or video Blob Artifact." }], preview: previewImage("Box.png") } },
+  { name: "box", tag: "Box", mode: "structured", outputs: [exampleTypes.box, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A framed box surface.", "<example:Box id=\"box\" timeline={speech.timeline}/>") , preview: previewImage("Box.png") } },
+  { name: "text", tag: "Text", mode: "structured", outputs: [exampleTypes.text, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A text-bearing surface.", "<example:Text id=\"title\" timeline={speech.timeline}>Hello</example:Text>"), preview: previewImage("Box.png") } },
+  { name: "media-slot", tag: "MediaSlot", mode: "structured", outputs: [exampleTypes.mediaSlot, compositionTypes.visualTrack], vocabulary: { ...vocabulary("A media slot whose content is a graph input.", "<example:MediaSlot id=\"shot\" timeline={speech.timeline} media={shot-media}/>") , attributes: [...vocabulary("", "").attributes, { name: "media", kind: "reference" as const, required: false, accepts: [artifactTypes.blob], summary: "Optional image or video Blob Artifact." }], preview: previewImage("Box.png") } },
   { name: "style", tag: "Style", mode: "structured", outputs: [exampleTypes.style], vocabulary: {
     summary: "Decodes one SVS Recipe and exact FontStackRef into a Style value.",
     attributes: [

package/examples/minimal-author-package/packages/example-component/src/surface.ts

@@ -28,7 +28,7 @@ export const decodeExampleSurface: StructuredSurfaceHandler = ({ element, resolv
     if (recipe.record?.value.kind !== "inline" || font.record?.value.kind !== "inline") throw new Error("Style references must resolve to inline records.");
     return { records: [{ id, type: exampleTypes.style, value: { kind: "inline", value: { recipe: recipe.record.value.value, fonts: font.record.value.value } }, range: element.range }], components: [], fragments: [], exports: [id] };
   }
-  const semantic = reference(element, "semantic", resolveReference);
+  const timeline = reference(element, "timeline", resolveReference);
   const surface = exampleMarkupSurfaces.find((item) => item.tag === element.name.split(":").at(-1));
   if (surface === undefined) throw new Error(`Unknown example surface ${element.name}`);
   const fragment = surface.name === "box" ? exampleBoxFragment : surface.name === "text" ? exampleTextFragment : exampleMediaFragment;
@@ -36,6 +36,6 @@ export const decodeExampleSurface: StructuredSurfaceHandler = ({ element, resolv
   const record: SurfaceRecordDraft = { id: `${id}.value`, type, value: { kind: "inline", value: { id } }, range: element.range };
   const media = element.attributes.media === undefined ? undefined : reference(element, "media", resolveReference);
   if (media !== undefined && (media.type.module.name !== artifactTypes.blob.module.name || media.type.name !== artifactTypes.blob.name)) throw new Error(`${element.name}.media must be a Blob Artifact.`);
-  const component: SurfaceComponentDraft = { id, fragment: fragment.id, inputs: { semantic: semantic.ref, ...(media === undefined ? {} : { media: media.ref }) }, outputs: { track: `${id}.track` }, range: element.range };
+  const component: SurfaceComponentDraft = { id, fragment: fragment.id, inputs: { timeline: timeline.ref, ...(media === undefined ? {} : { media: media.ref }) }, outputs: { track: `${id}.track` }, range: element.range };
   return { records: [record], components: [component], fragments: [fragment], exports: [`${id}.value`, `${id}.track`] };
 };

package/examples/provider-package/README.md

@@ -0,0 +1,78 @@
+# A project-owned Provider
+
+This complete package demonstrates an asynchronous image service through the public Hypit SDK.
+The service protocol below is **illustrative**, not a live vendor API. Replace its mapping and
+transport with the selected service's documented operations. The lifecycle test exercises the
+example without a paid request. Implement the capabilities needed by the production; a service's
+entire catalogue is not required.
+
+## Follow one request
+
+The existing GPT Image 2 Model produces `@hypit/gpt-image@1#gpt-image-2` with a generated image-set
+result. This Provider supports 1K at three ratios, with optional reference images. It reports its
+smaller support range without changing the Model. The Profile selects this implementation; the
+Source's prompt, references and model remain ordinary generation inputs.
+
+The example service uses Bearer authentication for these API operations:
+
+| Operation | Example protocol |
+| --- | --- |
+| Upload reference | `POST /uploads`, image bytes and media Content-Type → `{ "url": "https://…" }` |
+| Submit generation | `POST /tasks`, `{ "model": "gpt-image-2", "input": { "prompt": "…", "ratio": "9:16", "size": "1K", "references": [] } }` → `{ "id": "task-123" }` |
+| Poll task | `GET /tasks/task-123` → `state`: `queued`, `running`, `failed`, or `succeeded`; success includes a signed image `url` |
+| Read rates | `GET /rates?model=gpt-image-2` → service-owned fields and a `description` stating rates, units and conditions |
+| Collect result | GET the signed image URL without the account key |
+
+`start` records the received task ID through `checkpoint` before returning it. Runtime owns polling,
+capacity and durable operation state. `poll` returns `ready` for completed remote work; `collect`
+stores the image through `context.resources` and returns the Model's declared value. The Provider
+chooses neither a Result folder nor a project media path. A failed call ends the attempt while the
+received task ID remains evidence. This service defines no cancellation endpoint, so the package
+does not claim remote cancellation.
+
+`pricing` identifies the service page. `readPricing` maps the current request to its service rate
+source and preserves the response with a concise description. It reads no graph and invents no
+future media duration. Rates and credentials do not supply spending permission.
+
+## Make it a package in the production
+
+Copy `packages/provider-images` into the video's `packages/`. Choose your own package name and change
+`providerModule.name` with it. Implement the actual service protocol, including its request limits,
+upload/download limits and any OAuth or cancellation behavior it really offers. Configure the
+selected service address; `images.example` is a placeholder that cannot generate media.
+
+Use the active `@hypit/hypit` version as a development dependency. Build and install with the
+project's package manager. In this repository the example uses `workspace:*` for that dependency;
+replace it with your selected release when copying it out. The `@hypit/driver-node` and
+`@hypit/gpt-image` development dependencies serve the repository test only and can be removed from
+the copied package. For example:
+
+```bash
+cd packages/provider-images
+npm install
+npm run build
+cd ../..
+npm install ./packages/provider-images
+```
+
+The package ships JavaScript. Its `hypit.activation` exports a Profile-selected Runtime facet;
+installation alone activates nothing. The active Distribution resolves public SDK imports when
+loading project packages. Keep the chosen package version and lockfile with the project.
+
+Merge the endpoint, credential store and binding from `hypit.runtime.json` into the project's
+chosen Profile. Preserve its other services and resolve bindings explicitly. Once the user chooses
+that account, `hypit auth login images.personal` securely enters the key into its declared store.
+`plan` checks the requested parameters; `pricing` supplies the service's rates. Submitting a real
+generation follows the agreed production scope and spending authority.
+
+## Owners
+
+- `src/provider.ts`: exact capability, mapping, service support, task lifecycle, pricing and capacity.
+- `src/activation.ts`: configuration and package activation through the Runtime SDK.
+- Model: author inputs and result meaning. No service URL or account is placed in it.
+- Runtime: durable execution, scheduling, credentials supplied to declared slots, and Results.
+
+The Endpoint SDK README owns the precise handler fields; the Runtime SDK README owns activation.
+Both are included in the installed Distribution. A new service may need a small immediate handler,
+a different upload protocol, or an asynchronous implementation like this one. Those are Provider
+decisions within the same public boundary.

package/examples/provider-package/hypit.runtime.json

@@ -0,0 +1,12 @@
+{
+  "format": "hypit.runtime-local@1",
+  "dataRoot": ".hypit/execution",
+  "credentials": { "os": { "use": "@hypit/credential-store-os" } },
+  "endpoints": {
+    "images.personal": {
+      "use": "@example/provider-images",
+      "config": { "baseUrl": "https://images.example", "apiKey": { "store": "os", "key": "images.personal" } }
+    }
+  },
+  "bindings": { "@hypit/gpt-image@1#gpt-image-2": "images.personal" }
+}

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

@@ -0,0 +1,11 @@
+{
+  "name": "@example/provider-images",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "hypit": { "activation": "./dist/activation.js" },
+  "exports": { ".": "./dist/provider.js" },
+  "files": ["dist"],
+  "scripts": { "build": "tsc -p tsconfig.json" },
+  "devDependencies": { "@hypit/hypit": "workspace:*", "typescript": "5.9.3", "@hypit/driver-node": "workspace:*", "@hypit/gpt-image": "workspace:*" }
+}

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

@@ -0,0 +1,24 @@
+import {
+  createRuntimeEndpointAdapterFacet, runtimeConfigCredentialRef, runtimeConfigExact,
+  runtimeConfigObject, runtimeConfigPositiveInteger, runtimeConfigString,
+} from "@hypit/hypit/runtime-kit";
+import { createImageProvider, providerModule } from "./provider.js";
+
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createRuntimeEndpointAdapterFacet({
+    use: providerModule.name,
+    activate(context) {
+      const config = runtimeConfigObject(context.config, "Image service");
+      runtimeConfigExact(config, ["baseUrl", "apiKey", "concurrency", "pollIntervalMs"], "Image service");
+      const baseUrl = runtimeConfigString(config.baseUrl, "Image service baseUrl");
+      const apiKey = runtimeConfigCredentialRef(config.apiKey, "Image service apiKey");
+      if (!baseUrl || !apiKey || !context.pool) throw new Error("Image service requires baseUrl, apiKey and pool");
+      return { endpoint: createImageProvider({
+        instance: context.instance, pool: context.pool, baseUrl, apiKey,
+        concurrency: runtimeConfigPositiveInteger(config.concurrency, "concurrency") ?? 1,
+        pollIntervalMs: runtimeConfigPositiveInteger(config.pollIntervalMs, "pollIntervalMs") ?? 2_000,
+      }) };
+    },
+  })],
+};