@hypit/hypit 0.1.3 → 0.1.5

package/packages/ranking/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import {
   assertEmptyElement as empty,
   assertAttributes as allowed,
@@ -199,7 +199,7 @@ const variantDefinition = {
 
 function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
   return ({ element, resolveReference }) => {
-    const common = ["id", "semantic", "space", "frame", "during", "terminal", "style", "appear-sound", "move-sound"];
+    const common = ["id", "timeline", "frame", "during", "terminal", "style", "appear-sound", "move-sound"];
     const attributes = variant === "column" || variant === "tier-board"
       ? [...common.filter((name) => name !== "terminal"), "canvas"]
       : common;
@@ -207,31 +207,30 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
     const id = text(element, "id");
     const selected = variantDefinition[variant];
     const context = resolveTemporalContext({ element, resolveReference });
-    const time = createTemporalSpace({ id, element, ...context });
     const canvas = variant === "column" || variant === "tier-board"
       ? reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference)
       : undefined;
     const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);
-    const outerTemporal = createTemporalWindowProjection({ id: `${id}.outer`, subjectId: id, element, ...context, space: time.space, resolveReference });
+    const outerTemporal = createTemporalWindowProjection({ id: `${id}.outer`, subjectId: id, element, ...context, resolveReference });
     const terminalTemporal = variant === "top-three"
       ? createTemporalInstantProjection({
-          id: `${id}.terminal`, subjectId: id, element, ...context, space: time.space, resolveReference,
+          id: `${id}.terminal`, subjectId: id, element, ...context, resolveReference,
           semanticAttribute: "terminal", projectedAttribute: false,
         })
       : undefined;
     const styleRaw = element.attributes.style;
     const style = reference(styleRaw, `${element.name}.style`, selected.style, resolveReference);
     const records: SurfaceRecordDraft[] = [...outerTemporal.records, ...(terminalTemporal?.records ?? [])];
-    const temporalComponents: SurfaceComponentDraft[] = [...time.components, ...outerTemporal.components, ...(terminalTemporal?.components ?? [])];
-    const temporalFragments = [...time.fragments, ...outerTemporal.fragments, ...(terminalTemporal?.fragments ?? [])];
+    const temporalComponents: SurfaceComponentDraft[] = [...outerTemporal.components, ...(terminalTemporal?.components ?? [])];
+    const temporalFragments = [...outerTemporal.fragments, ...(terminalTemporal?.fragments ?? [])];
     const headerId = `${id}.header`;
     records.push({
       id: headerId, type: rankingTypes.header,
       value: { kind: "inline", value: sealRankingHeader({ id, variant }) as unknown as CanonicalValue },
       range: element.range,
     });
-    const inputs: Record<string, typeof time.space.ref> = {
-      header: { kind: "record", id: headerId }, space: time.space.ref, frame: frame.ref,
+    const inputs: Record<string, typeof context.timeline.ref> = {
+      header: { kind: "record", id: headerId }, timeline: context.timeline.ref, frame: frame.ref,
       outer: outerTemporal.ref, style: style.ref,
       ...(canvas === undefined ? {} : { canvas: canvas.ref }),
       ...(terminalTemporal === undefined ? {} : { terminal: terminalTemporal.ref }),
@@ -260,8 +259,8 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
       const contentName = authored.content === undefined ? undefined : `item-${suffix}-content`;
       if (authored.content !== undefined) inputs[contentName!] = authored.content.ref;
       const itemTemporal = !authored.timed ? undefined : variant === "top-three"
-        ? createTemporalInstantProjection({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, ...context, space: time.space, resolveReference })
-        : createTemporalWindowProjection({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, ...context, space: time.space, resolveReference });
+        ? createTemporalInstantProjection({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, ...context, resolveReference })
+        : createTemporalWindowProjection({ id: `${id}.item.${suffix}`, subjectId: spec.id, element: child, ...context, resolveReference });
       if (itemTemporal !== undefined) {
         records.push(...itemTemporal.records);
         temporalComponents.push(...itemTemporal.components);
@@ -307,12 +306,12 @@ function rankingSurface(variant: RankingVariant): StructuredSurfaceHandler {
         id, fragment: fragment.id, inputs,
         outputs: {
           schedule: `${id}.schedule`, program: `${id}.program`, visual: `${id}.visual`,
-          ...(sound.appearName === undefined && sound.moveName === undefined ? {} : { audio: `${id}.audio` }),
+          ...(sound.appearName === undefined && sound.moveName === undefined ? {} : { events: `${id}.events`, audio: `${id}.audio` }),
         },
         range: element.range,
       }],
       fragments: [...temporalFragments, fragment],
-      exports: [`${id}.schedule`, `${id}.program`, `${id}.visual`, ...(sound.appearName === undefined && sound.moveName === undefined ? [] : [`${id}.audio`])],
+      exports: [`${id}.schedule`, `${id}.program`, `${id}.visual`, ...(sound.appearName === undefined && sound.moveName === undefined ? [] : [`${id}.events`, `${id}.audio`])],
     };
   };
 }

package/packages/ranking-studio/README.md

@@ -1,3 +1,32 @@
 # `@hypit/ranking-studio`
 
 Hypit Studio Companion for the Ranking module's Column, Tier and Top Three surfaces.
+
+Each surface has separate visual and audio Companion declarations in this one
+package. Film chooses `.visual` and `.audio` independently; selecting the visual
+output does not connect its sound.
+
+The root lane represents the board; `attachments` expose reveal or activation
+events on a detail lane. Both use Studio's ordinary item selection and overlap
+behavior. Their time ranges remain the authored event ranges.
+
+Ranking's renderer assigns `subjectId` to each item's rendered phases. The
+Companion associates those phases with the item's `renderIds`, so clicking an
+entering or settled icon selects the same detail entity. The board and preset
+items without a detail event remain associated with the root. Studio measures
+the visible parts at the current frame; the Companion does not duplicate motion
+geometry or infer identities from rendered ID strings.
+
+The audio Companion presents a `Ranking Sounds` lane. Each emitted clip shows
+its item and phase (`Appear` or `Move`) with a waveform. It joins the board's
+exported `.events` to the rendered audio clips by exact event identity, so a
+phase without a supplied sound contributes no audio item. `Move` is the motion
+into the board, not an exit sound.
+
+Selecting a sound exposes the event trigger as a read-only fact and the shared
+Ranking Style's sound gains and fade-in length as editable fields. Gain is
+displayed as a percentage; edits write the original linear gain to the Style's
+recipe. These fields affect every matching event using that recipe. Event
+timing comes from the Ranking animation; changing the visual event timing
+updates its sound too. The visual Companion owns layout and motion controls,
+while the audio Companion owns the sound controls.

package/packages/ranking-studio/package.json

@@ -4,11 +4,16 @@
   "license": "SEE LICENSE IN LICENSE",
   "private": true,
   "type": "module",
-  "exports": { ".": "./src/index.ts" },
-  "hypit": { "activation": "./src/activation.ts" },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
   "dependencies": {
     "@hypit/ranking": "workspace:*",
     "@hypit/composition": "workspace:*",
-    "@hypit/studio-adapter": "workspace:*"
+    "@hypit/studio-adapter": "workspace:*",
+    "@hypit/fonts-open": "workspace:*"
   }
 }

package/packages/ranking-studio/src/index.ts

@@ -1,17 +1,25 @@
+import { openFontStudioFields } from "@hypit/fonts-open/studio";
 import { rankingMarkupSurfaces, rankingModuleRef, rankingTypes } from "@hypit/ranking";
-import type { RankingProgram, RankingSchedule } from "@hypit/ranking";
+import type { RankingProgram, RankingSchedule, RankingSoundEventPlan } from "@hypit/ranking";
 import { compositionTypes } from "@hypit/composition";
+import type { AudioTrack } from "@hypit/composition";
 import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
 import { artifactPreview, authoredChildFor, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
 
+
+const fontInspector = openFontStudioFields("style");
+
 const frameParameters: readonly StudioSourceBindingDeclaration[] = [
   { name: "within" },
   ...["left", "top", "right", "bottom", "x", "y", "width", "height"].map((name) => ({ name, writable: true })),
 ];
 
-function rankingProperties(surface: "column-style" | "tier-style" | "top-three-style") {
-  return rankingMarkupSurfaces.find((candidate) => candidate.name === surface)
-    ?.vocabulary.attributes.find((attribute) => attribute.name === "recipe")?.recipe ?? [];
+const soundProperties = new Set(["appear-gain", "move-gain", "sound-fade-frames"]);
+
+function rankingProperties(surface: "column-style" | "tier-style" | "top-three-style", audio = false) {
+  return (rankingMarkupSurfaces.find((candidate) => candidate.name === surface)
+    ?.vocabulary.attributes.find((attribute) => attribute.name === "recipe")?.recipe ?? [])
+    .filter((property) => soundProperties.has(property.name) === audio);
 }
 
 function title(name: string): string {
@@ -76,7 +84,7 @@ const rankingInspectorPlacement = {
 } as const satisfies Readonly<Record<string, RankingInspectorPlacement>>;
 
 function rankingInspector(surface: "column-style" | "tier-style" | "top-three-style"): readonly StudioInspectorFieldDeclaration[] {
-  return rankingProperties(surface).map((property) => {
+  return [...fontInspector.fields, ...rankingProperties(surface).map((property) => {
     const placement = rankingInspectorPlacement[property.name as keyof typeof rankingInspectorPlacement];
     if (placement === undefined) throw new Error(`Ranking Studio has no explicit placement for ${property.name}.`);
     return {
@@ -85,13 +93,14 @@ function rankingInspector(surface: "column-style" | "tier-style" | "top-three-st
       ...placement,
       ...(property.summary === undefined ? {} : { summary: property.summary }),
     };
-  });
+  })];
 }
 
-function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style"): StudioSourceBindingDeclaration {
+function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style", audio = false): StudioSourceBindingDeclaration {
   return {
     name: "style",
-    recipe: { through: ["recipe"], bindings: rankingProperties(surface).map(({ name, schema, fallback }) => ({
+    ...(audio ? {} : { referenced: [fontInspector.binding] }),
+    recipe: { through: ["recipe"], bindings: rankingProperties(surface, audio).map(({ name, schema, fallback }) => ({
       name,
       schema,
       ...(fallback === undefined ? {} : { fallback }),
@@ -133,6 +142,7 @@ function projectRanking(context: StudioTrackCompanionContext): readonly StudioEn
     return [{
       id: `${context.track.outputRef}:entity:${entry.itemId}`,
       authoredId: entry.itemId,
+      renderIds: context.spans.filter((span) => span.subjectId === entry.itemId).map((span) => span.id),
       ...(semanticSource?.id === undefined ? {} : { markerId: semanticSource.id }),
       display: {
         title: label,
@@ -147,23 +157,72 @@ function projectRanking(context: StudioTrackCompanionContext): readonly StudioEn
       ...(temporal === undefined ? {} : { temporal }),
     }];
   }).sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id));
-  return [group, ...reveals];
+  const childRenderIds = new Set(reveals.flatMap((entity) => entity.renderIds ?? []));
+  return [{ ...group, renderIds: group.renderIds!.filter((id) => !childRenderIds.has(id)) }, ...reveals];
 }
 
 const commonBindings: readonly StudioSourceBindingDeclaration[] = [
   { name: "frame", referenced: frameParameters },
-  { name: "appear-sound" },
-  { name: "move-sound" },
 ];
 
+function projectRankingAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const events = requiredSurfaceValue(context, "events") as RankingSoundEventPlan;
+  const byId = new Map(events.events.map((event) => [event.id, event]));
+  const clips = new Map((context.track.value as AudioTrack).clips.map((clip) => [clip.id, clip]));
+  const boardId = context.placement?.id ?? context.track.outputRef;
+  return context.spans.map((span): StudioEntityDraft => {
+    const event = byId.get(span.id);
+    const clip = clips.get(span.id);
+    if (event === undefined || clip === undefined) throw new Error(`Ranking sound ${span.id} has no event or audio clip.`);
+    const child = authoredChildFor(context, event.itemId, [rankingTypes.itemSpec, rankingTypes.textItemShell]);
+    const label = child?.attributes.label ?? event.itemId;
+    const phase = event.kind === "appear" ? "Appear" : "Move";
+    return {
+      id: `${context.track.outputRef}:entity:${event.id}`,
+      authoredId: boardId,
+      display: { title: `${label} · ${phase}`, layers: [previewLayer(artifactPreview("audio", clip.artifact.resource), "waveform")] },
+      startFrame: span.startFrame, endFrameExclusive: span.endFrameExclusive, stackOrder: span.stackOrder,
+      ...(context.placement === undefined ? {} : { elementRange: context.placement.range }),
+      presentation: { entity: "ranking-sound", chrome: "standard" },
+      inspector: [{
+        id: "trigger", label: "Trigger", domain: "when", page: { id: "sound", label: "Sound" }, section: { id: "event", label: "Event" },
+        value: `${label} · ${phase} · ${event.frame}f`,
+        summary: "Follows the Ranking item's animation event. Adjust its visual timing to move the sound with it.",
+      }],
+    };
+  });
+}
+
+function rankingAudioCompanion(surface: "column" | "tier" | "top-three"): StudioTrackCompanion {
+  const style = `${surface}-style` as const;
+  return {
+    id: `${surface}-audio`, role: "track",
+    output: { type: compositionTypes.audioTrack, surface, modules: [rankingModuleRef] },
+    family: "audio", tone: "green", label: "Ranking Sounds", icon: "waveform",
+    lane: { heightPx: 48 }, requiredValues: ["events"],
+    bindings: [{ name: "appear-sound" }, ...(surface === "top-three" ? [] : [{ name: "move-sound" }]), rankingStyle(style, true)],
+    inspector: rankingProperties(style, true).map((property) => ({
+      binding: `style.${property.name}`, label: property.name === "sound-fade-frames" ? "Fade In" : title(property.name),
+      ...rankingInspectorPlacement[property.name as keyof typeof rankingInspectorPlacement],
+      control: "number",
+      ...(property.name === "sound-fade-frames"
+        ? { unit: "f", number: { minimum: 0, step: 1 } }
+        : { unit: "%", number: { scale: 100, minimum: 0, step: 1 } }),
+      summary: "Shared by every matching sound event using this Ranking style.",
+    })),
+    project: projectRankingAudio,
+  };
+}
+
 const frameInspector: readonly StudioInspectorFieldDeclaration[] = frameParameters
   .filter(({ writable }) => writable === true)
   .map(({ name }) => ({
     binding: `frame.${name}`, label: title(name), domain: "where",
-    page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "text",
+    page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "number", number: { suffixes: ["%", "px"], step: 1 },
   }));
 
 export const rankingStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+  ...(["column", "tier", "top-three"] as const).map(rankingAudioCompanion),
   {
     id: "column", role: "track",
     output: { type: compositionTypes.visualTrack, surface: "column", modules: [rankingModuleRef] },

package/packages/render-hyperframes/README.md

@@ -1,14 +1,14 @@
 # `@hypit/render-hyperframes`
 
-The Surface accepts `semantic={speech.semantic}` for performance time or `space={animation}` for an
-authored ProgramSpace. Its Fragment receives `space` directly; rendering does not require Script
-or prepared performance media. Both time sources use the same frame and audio pipeline.
+The Surface accepts `timeline={program.timeline}` and projects its complete ProgramSpace.
+Its Fragment receives that range as `space`; rendering works with partial, overlapping or absent
+semantic coverage through the same frame and audio pipeline.
 
 Explicit author and capability boundary for final HyperFrames video rendering.
 
 The package owns `<render:Video composition={...}/>` and lowers it to ordinary Operations that:
 
-1. obtain the `ProgramSpace` from the semantic input and compile the referenced `Composition` into a `HyperframesDocument`;
+1. obtain the `ProgramSpace` from the Timeline input and compile the referenced `Composition` into a `HyperframesDocument`;
 2. request a silent, frame-exact `RenderedVisual`;
 3. compile every peer `AudioTrack` into one `AudioProgramPlan`;
 4. request an exact 48 kHz `TimelineAudio`;
@@ -29,7 +29,7 @@ Core therefore sees three real byte-operation Needs, not one opaque mega-render.
 contiguous or interleaved chunks, retries and image-sequence assembly remain inside the selected
 visual Endpoint; clip decoding/mixing remains inside the audio Endpoint; container encoding remains
 inside the mux Endpoint. A single Provider package may implement all three locally, or a Runtime may
-bind them to separate Lambda-backed Endpoints. The author still sees one `<render:Video>` result.
+bind them to separate compatible Endpoints. The author still sees one `<render:Video>` result.
 
 Film is not a dependency of this author meaning. Any package that produces the common Composition
 contract can feed the render Surface. Conversely, targeting Composition never demands this package;
@@ -43,7 +43,7 @@ stream with the declared canvas, rational frame rate and frame count.
 Select a contiguous interval using zero-based, half-open frame bounds:
 
 ```xml
-<render:Video id="preview" composition={main.composition} semantic={speech.semantic}
+<render:Video id="preview" composition={main.composition} timeline={speech.timeline}
   start-frame="240" end-frame-exclusive="360"/>
 ```
 
@@ -54,5 +54,5 @@ Provider's Runtime configuration.
 
 In TypeScript, `hyperframesVisualRequest(document, { range })` constructs the visual request;
 `createRenderHyperframesFragment(true)` accepts a `MediaFrameRange` input and connects it to visual
-and audio requests. The AWS Lambda Provider currently declines range requests. Selection limits
+and audio requests. Provider support checks establish range support for other deployments. Selection limits
 final rendering work; it does not prune upstream generation dependencies.

package/packages/render-hyperframes/package.json

@@ -20,7 +20,7 @@
     "@hypit/media-pipeline": "workspace:*",
     "@hypit/program-space": "workspace:*",
     "@hypit/protocol": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/temporal-markup": "workspace:*"
   },

package/packages/render-hyperframes/src/component.ts

@@ -4,6 +4,7 @@ import type { ComponentPackage } from "@hypit/component-kit";
 import type { StoredValue } from "@hypit/protocol";
 
 import { hyperframesVisualRequest } from "./product.js";
+import type { HyperframesVisualRequest } from "./product.js";
 import { renderHyperframesCapabilities, renderHyperframesProducers } from "./manifest.js";
 
 /** Declares the visual Need. It contains no renderer, queue, credentials or deployment choice. */
@@ -26,7 +27,16 @@ export const renderHyperframesComponent = {
       return { constraints: {}, pendingInputs: plannedNeedInputs(state, step) };
     },
     present(specification) {
-      return { fields: {}, references: {} };
+      const request = specification.constraints as Partial<HyperframesVisualRequest>;
+      if (request.document === undefined) return { fields: {}, references: {} };
+      const { document, range } = request;
+      const startFrame = range?.startFrame ?? 0;
+      const endFrameExclusive = range?.endFrameExclusive ?? document.frameCount;
+      return { fields: {
+        width: [document.canvas.width], height: [document.canvas.height],
+        startFrame: [startFrame], endFrameExclusive: [endFrameExclusive],
+        frameRate: [`${document.frameRate.numerator}/${document.frameRate.denominator}`],
+      }, references: {} };
     },
   })),
 } satisfies ComponentPackage;

package/packages/render-hyperframes/src/fragment.ts

@@ -1,6 +1,7 @@
+import { timelineProducers, timelineTypes } from "@hypit/timeline";
 import { mediaTypes } from "@hypit/media";
 import { artifactTypes } from "@hypit/artifact";
-import { programSpaceTypes } from "@hypit/program-space";
+
 import { compositionTypes } from "@hypit/composition";
 import { sealGraphFragment } from "@hypit/elaborator";
 import { hyperframesProducers } from "@hypit/hyperframes";
@@ -17,14 +18,16 @@ export function createRenderHyperframesFragment(selectedRange = false) {
   return sealGraphFragment({
     inputs: [
       { name: "composition", type: compositionTypes.composition },
-      { name: "space", type: programSpaceTypes.programSpace },
+      { name: "timeline", type: timelineTypes.track },
       ...(selectedRange ? [{ name: "range", type: mediaTypes.frameRange }] : []),
     ],
     operations: [
+      { id: "render-range", producer: timelineProducers.projectProgramSpace,
+        inputs: { track: input("timeline") }, result: { kind: "output", name: "space" } },
       {
         id: "compile-document",
         producer: hyperframesProducers.compile,
-        inputs: { composition: input("composition"), space: input("space") },
+        inputs: { composition: input("composition"), space: operation("render-range") },
         result: { kind: "output", name: "document" },
       },
       {
@@ -36,7 +39,7 @@ export function createRenderHyperframesFragment(selectedRange = false) {
       {
         id: "compile-audio-program",
         producer: mediaPipelineProducers.planAudio,
-        inputs: { composition: input("composition"), space: input("space") },
+        inputs: { composition: input("composition"), space: operation("render-range") },
         result: { kind: "output", name: "plan" },
       },
       {

package/packages/render-hyperframes/src/manifest.ts

@@ -2,7 +2,7 @@ import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { artifactDependency, artifactTypes } from "@hypit/artifact";
 import { mediaDependency, mediaTypes } from "@hypit/media";
 import { compositionDependency, compositionTypes } from "@hypit/composition";
-import { semanticTrackDependency } from "@hypit/semantic-track";
+import { timelineDependency } from "@hypit/timeline";
 import {
   hyperframesManifest,
   hyperframesModuleRef,
@@ -48,9 +48,9 @@ export const renderHyperframesMarkupSurfaces = [{
         { name: "video", type: artifactTypes.blob,
           summary: "The final muxed video Artifact, addressed as `<id>.video`." },
       ],
-      example: '<render:Video id="final" composition={main.composition} semantic={speech.semantic}/>',
+      example: '<render:Video id="final" composition={main.composition} timeline={speech.timeline}/>',
       notes: [
-        "Supply id, composition and one time source: semantic or space. Write both frame bounds to select a range. The element is empty.",
+        "Supply id, composition and timeline. Write both frame bounds to select a range. The element is empty.",
         "The visual render, the audio render and the mux are three separate Needs, each realized by a Provider this package does not choose.",
         "The published Artifact carries no duration or lineage metadata, so a consumer that needs stream facts requests explicit media inspection.",
       ],
@@ -66,7 +66,7 @@ export const renderHyperframesManifest: ModuleManifest = {
     artifactDependency,
     mediaDependency,
     compositionDependency,
-    semanticTrackDependency,
+    timelineDependency,
     { module: hyperframesModuleRef },
     { module: mediaPipelineModuleRef },
   ],

package/packages/render-hyperframes/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import { compositionTypes } from "@hypit/composition";
 import { mediaTypes, verifyMediaFrameRange } from "@hypit/media";
 import type {
@@ -25,7 +25,7 @@ function referenceAttribute(element: StructuredElement, name: string): string {
 
 export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
   const names = Object.keys(element.attributes).sort();
-  if (names.some((name) => !["composition", "id", "semantic", "space", "start-frame", "end-frame-exclusive"].includes(name))) {
+  if (names.some((name) => !["composition", "id", "timeline", "start-frame", "end-frame-exclusive"].includes(name))) {
     throw new Error(`${element.name} contains unsupported attributes`);
   }
   if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
@@ -40,7 +40,7 @@ export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ eleme
     || composition.type.name !== compositionTypes.composition.name) {
     throw new Error(`${element.name}.composition must reference Composition`);
   }
-  const time = createTemporalSpace({ id, element, ...resolveTemporalContext({ element, resolveReference }) });
+  const context = resolveTemporalContext({ element, resolveReference });
   const selected = element.attributes["start-frame"] !== undefined || element.attributes["end-frame-exclusive"] !== undefined;
   const frame = (name: string): number => {
     const text = stringAttribute(element, name);
@@ -53,13 +53,13 @@ export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ eleme
   const rangeId = `${id}.frame-range`;
   return {
     records: range === undefined ? [] : [{ id: rangeId, type: mediaTypes.frameRange, value: { kind: "inline", value: range }, range: element.range }],
-    components: [...time.components, {
+    components: [{
       id,
       fragment: fragment.id,
-      inputs: { composition: composition.ref, space: time.space.ref, ...(selected ? { range: { kind: "record" as const, id: rangeId } } : {}) },
+      inputs: { composition: composition.ref, timeline: context.timeline.ref, ...(selected ? { range: { kind: "record" as const, id: rangeId } } : {}) },
       outputs: { video: `${id}.video` },
       range: element.range,
     }],
-    fragments: [...time.fragments, fragment],
+    fragments: [fragment],
   };
 };

package/packages/runtime/README.md

@@ -7,7 +7,7 @@ The package defines the small ports used by a runtime:
 * `BuildStore` keeps one active Build definition and its accepted facts until the Result is saved and active state is removed.
 * `OperationStore` keeps asynchronous external work only while the owning Build is active.
 * `PendingBuildStore` owns the short submission transaction before the Build becomes active.
-* `BuildExecutionStore` owns active scheduling facts, a stop request, the immutable decision, attention and shared capacity reservations.
+* `BuildExecutionStore` owns active scheduling facts, opaque Host execution choices, a stop request, the immutable decision, attention and shared capacity reservations.
 * `ResourceStore` is the transient byte gateway used during Provider execution.
 * `CredentialStore` resolves secrets outside source and build state.
 * `RuntimeCommandExecutor` turns the commands regenerated by Core into component or endpoint calls.
@@ -37,3 +37,10 @@ Capacity claims describe occupancy; action rate budgets describe admissions over
 Operation holds its declared occupancy while Runtime manages the remote task. Its submit, poll and
 collect actions can have separate concurrency and rate limits. Waiting claims park until a resource
 release or their next eligible time; polling does not require rematerializing the whole Build.
+
+The local Host uses one code context per Build. `claim(owner, now, build)` limits an executor to its
+own work; `start` records launch, and `interrupt` concludes a lost executor after its owner confirms
+exit. These stores do not prescribe processes or module loading. They retain one active execution
+record, while components and Providers remain ordinary replaceable implementations.
+There is no turn-reclaim operation that makes a lost attempt runnable again. Result-writer ownership
+can be cleared independently so an already decided outcome can still be saved.

package/packages/runtime/src/catalog.ts

@@ -3,6 +3,8 @@ import type {
 } from "@hypit/protocol";
 
 export type BuildPublishedOutput = {
+  /** Author-provided display name; the Output identifier remains unchanged. */
+  readonly displayName?: string;
   readonly name: string;
   readonly ref: LogicalOutputRef;
 };

package/packages/runtime/src/execution.ts

@@ -10,7 +10,9 @@ export type BuildOutcome = "complete" | "failed" | "cancelled";
 
 export type BuildExecutionRequest = {
   readonly build: string;
-  /** Installed component packages loaded when a Worker takes an execution turn. */
+  /** Host-owned execution choices. Opaque to the graph and Core. */
+  readonly context?: import("@hypit/protocol").CanonicalValue;
+  /** Installed component packages loaded when this execution context starts. */
   readonly componentPackages: readonly string[];
   /** Exact project Result Repository selected at submission. */
   readonly result: BuildResultRepositoryLocation;
@@ -48,6 +50,8 @@ export type BuildResultWriteLease = BuildExecutionTurn;
  */
 export type BuildExecutionSnapshot = BuildExecutionRequest & {
   readonly createdAt: number;
+  /** An execution context has been assigned; losing it ends this attempt. */
+  readonly startedAt?: number;
   /** Absent when waiting for a resource release. */
   readonly wakeAt?: number;
   /** Only these Operations can advance the Build until their next outcome. */
@@ -79,10 +83,14 @@ export type BuildExecutionStore = {
   create(request: BuildExecutionRequest, options?: { readonly now?: number }): Promise<BuildExecutionSnapshot>;
   read(build: string): Promise<BuildExecutionSnapshot | undefined>;
   list(): Promise<readonly BuildExecutionSnapshot[]>;
+  /** Lightweight scheduling views; no Definition, Profile or Operation payloads are loaded. */
+  listUnstarted(): Promise<readonly string[]>;
+  listReady(now?: number): Promise<readonly string[]>;
   /** Atomically take one ready, undecided execution turn for this Worker owner. */
-  claim(owner: string, now?: number): Promise<BuildExecutionSnapshot | undefined>;
-  /** A new owning Worker clears turns left by the previous process; no external action is repeated here. */
-  reclaimTurns(now?: number): Promise<readonly string[]>;
+  claim(owner: string, now?: number, build?: string): Promise<BuildExecutionSnapshot | undefined>;
+  start(build: string, now?: number): Promise<BuildExecutionSnapshot>;
+  /** Conclude after the owner confirms this execution context has ended. Never repeats external work. */
+  interrupt(build: string, reason: string): Promise<BuildExecutionSnapshot>;
   /** An unobserved stop wakes the next turn immediately to finish the attempt. */
   releaseTurn(build: string, owner: string, wakeAt: number | undefined, operationWait?: readonly string[]): Promise<BuildExecutionSnapshot>;
   /** Freeze the one conclusion. An execution with a decision can never be claimed again. */
@@ -106,6 +114,8 @@ export type CommandExecutionReceipt = {
   readonly command: string;
   readonly status: "started" | "completed";
   readonly event?: CommandResult;
+  /** Current Provider-reported activity; discarded when this call completes. */
+  readonly activity?: { readonly endpoint: string; readonly progress: import("./operations.js").OperationProgress };
 };
 
 export type CommandExecutionBegin = {
@@ -119,6 +129,7 @@ export type CommandExecutionBegin = {
  */
 export type CommandExecutionStore = {
   begin(build: string, command: string): Promise<CommandExecutionBegin>;
+  reportProgress(build: string, command: string, activity: NonNullable<CommandExecutionReceipt["activity"]>): Promise<void>;
   complete(build: string, command: string, event: CommandResult): Promise<CommandExecutionReceipt>;
   list(build: string): Promise<readonly CommandExecutionReceipt[]>;
   removeBuild(build: string): Promise<void>;

package/packages/runtime/src/index.ts

@@ -14,7 +14,6 @@ export type * from "./capacity.js";
 export { capacityUnits } from "./capacity.js";
 export { buildExecutionActivity } from "./execution.js";
 export type * from "./execution.js";
-export type * from "./environment.js";
 export type * from "./operations.js";
 export { LocalBuildScheduler } from "./scheduler.js";
 export type * from "./submission.js";
@@ -22,3 +21,5 @@ export {
   isStreamingResourceStore,
 } from "./types.js";
 export type * from "./types.js";
+export type * from "./log.js";
+export { readExecutionLog } from "./log.js";

package/packages/runtime/src/log.ts

@@ -0,0 +1,51 @@
+/** Provider-authored diagnostic text suitable for users; never credentials or request bodies. */
+export type ExecutionDiagnostic = {
+  readonly level: "info" | "warning" | "error";
+  readonly message: string;
+  readonly stream?: "stdout" | "stderr";
+};
+
+export type ExecutionLogEvent = { readonly endpoint: string } & (
+  | { readonly kind: "started" | "completed" }
+  | { readonly kind: "failed"; readonly message: string }
+  | { readonly kind: "phase"; readonly phase: string }
+  | ({ readonly kind: "diagnostic" } & ExecutionDiagnostic)
+);
+
+export type ExecutionLogRecord = ExecutionLogEvent & {
+  readonly format: "hypit.execution-log@1";
+  readonly time: number;
+  readonly command: string;
+};
+
+export type ExecutionLogView = {
+  readonly records: readonly ExecutionLogRecord[];
+  readonly total: number;
+};
+
+/** Read a bounded tail without loading the whole log. Storage and transport remain caller-owned. */
+export async function readExecutionLog(chunks: AsyncIterable<Uint8Array>, limit: number): Promise<ExecutionLogView> {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("Log line count must be a positive integer");
+  const decoder = new TextDecoder();
+  const records: ExecutionLogRecord[] = [];
+  let pending = "";
+  let total = 0;
+  const consume = (line: string) => {
+    if (!line.trim()) return;
+    const record = JSON.parse(line) as ExecutionLogRecord;
+    if (record.format !== "hypit.execution-log@1") throw new Error("Unsupported execution log format");
+    records[total % limit] = record;
+    total++;
+  };
+  for await (const chunk of chunks) {
+    pending += decoder.decode(chunk, { stream: true });
+    let newline: number;
+    while ((newline = pending.indexOf("\n")) >= 0) {
+      consume(pending.slice(0, newline));
+      pending = pending.slice(newline + 1);
+    }
+  }
+  // A running writer may still be appending its last record; only complete lines are visible.
+  const offset = total > limit ? total % limit : 0;
+  return { records: [...records.slice(offset), ...records.slice(0, offset)], total };
+}