@hypit/hypit 0.1.3 → 0.1.5

package/packages/cli/src/view.ts

@@ -46,15 +46,27 @@ export type CliBuildResultView = {
   readonly targets: readonly string[];
   readonly omittedTargets?: number;
   readonly outputs: readonly CliOutputView[];
+  readonly outputCount: number;
+  /** Available Outputs outside the selected inspection scope. */
+  readonly otherOutputCount?: number;
   readonly omittedOutputs?: number;
   readonly failure?: string;
-  readonly operations?: BuildResultManifest["operations"];
+  readonly operations?: readonly Pick<NonNullable<BuildResultManifest["operations"]>[number],
+    "endpoint" | "status" | "receipt" | "failure">[];
+  readonly executionLog?: BuildResultManifest["executionLog"];
   readonly omittedOperations?: number;
 };
 
 export type CliBuildStatusView = {
   readonly id: string;
   readonly title?: string;
+  readonly targets?: readonly string[];
+  readonly failure?: string;
+  readonly commands?: readonly {
+    readonly id?: string;
+    readonly endpoint: string;
+    readonly progress: NonNullable<BuildView["commands"]>[number]["progress"];
+  }[];
   readonly work: {
     readonly state: "unknown" | "submitting" | "working" | "done";
     readonly outcome?: "complete" | "failed" | "cancelled";
@@ -68,6 +80,7 @@ export type CliBuildStatusView = {
   };
   readonly attention?: { readonly message: string; readonly action?: string };
   readonly operations?: readonly {
+    readonly count?: number;
     readonly id?: string;
     readonly receipt?: { readonly id: string; readonly url?: string };
     readonly endpoint: string;
@@ -127,8 +140,8 @@ function orderedOutputNames(manifest: BuildResultManifest): readonly string[] {
   const highlighted = new Set(manifest.highlightedOutputs ?? []);
   const targets = new Set(manifest.targets);
   return names.sort((left, right) => {
-    const leftRank = highlighted.has(left) ? 0 : targets.has(left) ? 1 : 2;
-    const rightRank = highlighted.has(right) ? 0 : targets.has(right) ? 1 : 2;
+    const leftRank = targets.has(left) ? 0 : highlighted.has(left) ? 1 : 2;
+    const rightRank = targets.has(right) ? 0 : highlighted.has(right) ? 1 : 2;
     return leftRank - rightRank || left.localeCompare(right);
   });
 }
@@ -146,7 +159,6 @@ export function buildStatusView(options: {
   readonly result?: BuildResultManifest;
   readonly resultReadError?: string;
   readonly verbose?: boolean;
-  readonly operationLimit?: number;
 }): CliBuildStatusView {
   const resultState = options.resultReadError !== undefined
     ? "unavailable" as const
@@ -154,6 +166,15 @@ export function buildStatusView(options: {
   const issue = options.runtime?.issue;
   return {
     id: options.id,
+    ...((options.runtime?.targets ?? options.result?.targets) === undefined ? {} : {
+      targets: options.runtime?.targets ?? options.result!.targets,
+    }),
+    ...((options.result?.failure ?? options.runtime?.stop?.reason) === undefined ? {} : {
+      failure: options.result?.failure ?? options.runtime!.stop!.reason,
+    }),
+    ...(options.runtime?.commands?.length ? { commands: options.runtime.commands.map((command) => ({
+      ...(options.verbose ? { id: command.id } : {}), endpoint: command.endpoint, progress: command.progress,
+    })) } : {}),
     ...(options.result?.title === undefined ? {} : { title: options.result.title }),
     work: {
       state: workState(options.runtime, options.result),
@@ -176,13 +197,12 @@ export function buildStatusView(options: {
           }
         : { message: options.resultReadError! },
     }),
-    ...(!options.verbose ? {} : {
-      operations: (options.runtime?.operations ?? options.result?.operations ?? [])
+    ...((options.runtime?.operations ?? options.result?.operations ?? []).some((item) => item.status !== "completed") ? {
+      operations: groupOperationViews((options.runtime?.operations ?? options.result?.operations ?? [])
         .filter((item) => item.status !== "completed")
-        .slice(0, options.operationLimit ?? 20)
         .map((item) => ({
-          ...("operation" in item ? { id: item.operation } : item.id === undefined ? {} : { id: item.id }),
-          ...(item.receipt === undefined ? {} : { receipt: item.receipt }),
+          ...(!options.verbose ? {} : "operation" in item ? { id: item.operation } : item.id === undefined ? {} : { id: item.id }),
+          ...(item.receipt === undefined || (!options.verbose && item.failure === undefined) ? {} : { receipt: item.receipt }),
           endpoint: item.endpoint,
           state: item.status,
           ...(item.progress === undefined ? {} : { progress: item.progress }),
@@ -190,23 +210,43 @@ export function buildStatusView(options: {
             code: item.failure.code,
             message: item.failure.message,
           } }),
-        })),
-    }),
+        })), options.verbose === true),
+    } : {}),
   };
 }
 
+function groupOperationViews(
+  operations: NonNullable<CliBuildStatusView["operations"]>,
+  verbose: boolean,
+): NonNullable<CliBuildStatusView["operations"]> {
+  if (verbose) return operations;
+  const groups = new Map<string, { view: typeof operations[number]; count: number }>();
+  for (const operation of operations) {
+    const key = JSON.stringify(operation);
+    const existing = groups.get(key);
+    if (existing !== undefined) existing.count += 1;
+    else groups.set(key, { view: operation, count: 1 });
+  }
+  return [...groups.values()].map(({ view, count }) => count === 1 ? view : { ...view, count });
+}
+
 export async function buildResultView(
   repository: BuildResultRepository,
   manifest: BuildResultManifest,
-  options: { readonly projectRoot: string; readonly output?: string; readonly limit: number },
+  options: { readonly projectRoot: string; readonly output?: string; readonly limit: number; readonly verbose?: boolean },
 ): Promise<CliBuildResultView> {
   if (options.output !== undefined && manifest.outputs[options.output] === undefined) {
     throw new Error(`Build Result ${manifest.id} has no public Output ${options.output}`);
   }
-  const allNames = options.output === undefined ? orderedOutputNames(manifest) : [options.output];
-  const selected = allNames.slice(0, options.limit);
+  const available = orderedOutputNames(manifest);
+  const allNames = options.output !== undefined ? [options.output] : options.verbose ? available
+    : available.filter((name) => manifest.targets.includes(name) || manifest.highlightedOutputs?.includes(name));
+  const selected = options.verbose ? allNames.slice(0, options.limit) : allNames;
   const outputs = await Promise.all(selected.map(async (name) =>
     await outputView(repository, manifest, name)));
+  const operations = options.verbose ? manifest.operations ?? []
+    : (manifest.operations ?? []).filter((item) => item.failure !== undefined);
+  const selectedOperations = options.verbose ? operations.slice(0, options.limit) : operations;
   return {
     id: manifest.id,
     ...(manifest.title === undefined ? {} : { title: manifest.title }),
@@ -217,12 +257,18 @@ export async function buildResultView(
     source: projectPath(manifest.source.path, options.projectRoot),
     ...(manifest.run === undefined ? {} : { run: projectPath(manifest.run.path, options.projectRoot) }),
     targetCount: manifest.targets.length,
-    targets: manifest.targets.slice(0, options.limit),
-    ...(manifest.targets.length <= options.limit ? {} : { omittedTargets: manifest.targets.length - options.limit }),
+    targets: manifest.targets,
+    outputCount: available.length,
     outputs,
+    ...(available.length === allNames.length ? {} : { otherOutputCount: available.length - allNames.length }),
     ...(selected.length === allNames.length ? {} : { omittedOutputs: allNames.length - selected.length }),
     ...(manifest.failure === undefined ? {} : { failure: manifest.failure }),
-    ...(manifest.operations === undefined ? {} : { operations: manifest.operations.slice(0, options.limit) }),
-    ...((manifest.operations?.length ?? 0) <= options.limit ? {} : { omittedOperations: manifest.operations!.length - options.limit }),
+    ...(manifest.executionLog === undefined ? {} : { executionLog: manifest.executionLog }),
+    ...(selectedOperations.length === 0 ? {} : { operations: selectedOperations.map((item) => options.verbose ? item : ({
+      endpoint: item.endpoint, status: item.status,
+      ...(item.receipt === undefined ? {} : { receipt: item.receipt }),
+      ...(item.failure === undefined ? {} : { failure: item.failure }),
+    })) }),
+    ...(selectedOperations.length === operations.length ? {} : { omittedOperations: operations.length - selectedOperations.length }),
   };
 }

package/packages/comment-sticker/README.md

@@ -1,7 +1,7 @@
 # `@hypit/comment-sticker`
 
-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.
 
 An author package for timed social-comment cards. It publishes an ordinary `VisualTrack` containing
@@ -21,7 +21,7 @@ The author surface keeps the three independent concerns visible:
 
 <comment:Style id="social-comment" recipe={styles.comment} font={fonts.ui}/>
 
-<comment:Track id="comments" canvas={video.canvas} semantic={speech.semantic}>
+<comment:Track id="comments" canvas={video.canvas} timeline={speech.timeline}>
   <comment:Sticker
     id="opening-comment"
     comment={comment-copy}

package/packages/comment-sticker/package.json

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

package/packages/comment-sticker/src/component.ts

@@ -1,7 +1,7 @@
+import type { Timeline } from "@hypit/timeline";
 import type { ComponentPackage, ProducerHandlerContext } 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, SpatialFrame } from "@hypit/spatial";
 import type { Text } from "@hypit/text";
 
@@ -28,7 +28,7 @@ function common(inputs: Record<string, { readonly value: StoredValue } | undefin
   return {
     set: inline<CommentStickerSet>(inputs.set?.value, "CommentStickerSet"),
     header: inline<CommentStickerHeader>(inputs.header?.value, "CommentStickerHeader"),
-    space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+    timeline: inline<Timeline>(inputs.timeline?.value, "Timeline"),
     frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
     style: inline<CommentStickerStyle>(inputs.style?.value, "CommentStickerStyle"),
     spec: inline<CommentStickerItemSpec>(inputs.spec?.value, "CommentStickerItemSpec"),
@@ -69,7 +69,7 @@ export const commentStickerComponent = {
       handler: ({ inputs }: ProducerHandlerContext) => {
         const values = common(inputs);
         return { outputs: { set: output(appendProjectedCommentSticker(
-          values.set, values.header, values.space, values.frame, values.style, values.spec, values.content, values.window,
+          values.set, values.header, values.timeline, values.frame, values.style, values.spec, values.content, values.window,
           avatar ? inline<BlobRef>(inputs.avatar?.value, "Comment Sticker avatar") : undefined,
         )) }, needs: {} };
       },
@@ -85,7 +85,7 @@ export const commentStickerComponent = {
       producer: commentStickerProducers.render,
       handler: ({ inputs }) => ({ outputs: { track: output(renderCommentSticker(
         inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
-        inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+        inline<Timeline>(inputs.timeline?.value, "Timeline"),
         inline<CommentStickerProgram>(inputs.program?.value, "CommentStickerProgram"),
       )) }, needs: {} }),
     },

package/packages/comment-sticker/src/fragment.ts

@@ -1,4 +1,5 @@
-import { programSpaceTypes } from "@hypit/program-space";
+import { timelineTypes } from "@hypit/timeline";
+
 import { artifactTypes } from "@hypit/artifact";
 import { compositionTypes } from "@hypit/composition";
 import { sealGraphFragment } from "@hypit/elaborator";
@@ -82,7 +83,7 @@ export function createCommentStickerFragment(items: readonly CommentStickerFragm
       inputs: {
         set: operation(current),
         header: input("header"),
-        space: input("space"),
+        timeline: input("timeline"),
         frame: input(item.frameName),
         style: input(item.styleName),
         window: input(item.windowName),
@@ -104,7 +105,7 @@ export function createCommentStickerFragment(items: readonly CommentStickerFragm
     {
       id: "comment:track",
       producer: commentStickerProducers.render,
-      inputs: { canvas: input("canvas"), space: input("space"), program: operation("comment:program") },
+      inputs: { canvas: input("canvas"), timeline: input("timeline"), program: operation("comment:program") },
       result: { kind: "output", name: "track" },
     },
   );
@@ -112,7 +113,7 @@ export function createCommentStickerFragment(items: readonly CommentStickerFragm
     inputs: [
       { name: "canvas", type: spatialTypes.canvas },
       { name: "header", type: commentStickerTypes.header },
-      { name: "space", type: programSpaceTypes.programSpace },
+      { name: "timeline", type: timelineTypes.track },
       ...[...types].map(([inputName, type]) => ({ name: inputName, type })),
     ],
     operations,

package/packages/comment-sticker/src/manifest.ts

@@ -1,3 +1,4 @@
+import { timelineTypes } from "@hypit/timeline";
 import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { readFile } from "node:fs/promises";
 
@@ -5,9 +6,9 @@ import { artifactDependency, artifactTypes } from "@hypit/artifact";
 import { compositionDependency, compositionTypes } from "@hypit/composition";
 import { fontArtifactSchema, mediaDependency, mediaTypes } from "@hypit/media";
 import { narrativeDependency } 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, spatialFrameSchema, spatialTypes } from "@hypit/spatial";
 import { svsRecipeType } from "@hypit/svs";
 import { temporalDependency, temporalTypes } from "@hypit/temporal";
@@ -134,7 +135,7 @@ export const commentStickerProgramSchema: ValueSchema = object({
 });
 const appendInputs = [
   { name: "set", type: commentStickerTypes.set }, { name: "header", type: commentStickerTypes.header },
-  { name: "space", type: programSpaceTypes.programSpace },
+  { name: "timeline", type: timelineTypes.track },
   { name: "frame", type: spatialTypes.frame }, { name: "style", type: commentStickerTypes.style },
   { name: "spec", type: commentStickerTypes.itemSpec },
   { name: "content", type: commentStickerTypes.content }, { name: "window", type: temporalTypes.window },
@@ -311,7 +312,7 @@ export const commentStickerMarkupSurfaces = [
             summary: "That Program rendered as one VisualTrack." },
         ],
         example: `
-<comment:Track id="comments" canvas={vertical} semantic={speech.semantic}>
+<comment:Track id="comments" canvas={vertical} timeline={speech.timeline}>
   <comment:Sticker id="one" frame={comment-frame} style={social} avatar={viewer-avatar}
     author="@viewer" meta="Featured" during={story.selection.reaction}>
     Wait, it pinned the caption to the word, not the second.
@@ -334,7 +335,7 @@ export const commentStickerManifest: ModuleManifest = {
   format: "hypit.module@1",
   name: commentStickerModuleRef.name,
   version: commentStickerModuleRef.version,
-  dependencies: [artifactDependency, narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, mediaDependency, compositionDependency, textDependency],
+  dependencies: [artifactDependency, narrativeDependency, timelineDependency, spatialDependency, temporalDependency, mediaDependency, compositionDependency, textDependency],
   types: [
     { name: commentStickerTypes.header.name },
     { name: commentStickerTypes.style.name },
@@ -366,7 +367,7 @@ export const commentStickerManifest: ModuleManifest = {
       needs: [],
     })),
     { name: commentStickerProducers.finalize.name, inputs: [{ name: "set", type: commentStickerTypes.set }, { name: "header", type: commentStickerTypes.header }], outputs: [{ name: "program", type: commentStickerTypes.program }], needs: [] },
-    { name: commentStickerProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: commentStickerTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+    { name: commentStickerProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "timeline", type: timelineTypes.track }, { name: "program", type: commentStickerTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
   ],
 };
 

package/packages/comment-sticker/src/program.ts

@@ -1,3 +1,4 @@
+import type { Timeline } from "@hypit/timeline";
 import {
   assertVisualTrackIdentity,
   sealVisualTrack,
@@ -12,7 +13,6 @@ import type {
 } from "@hypit/composition";
 import { assertFontArtifactRef } from "@hypit/media";
 import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import { canonicalize, isResourceId } from "@hypit/protocol";
 import type { BlobRef } from "@hypit/protocol";
 import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
@@ -195,7 +195,7 @@ export function assertCommentStickerSet(value: CommentStickerSet): void {
 function realized(
   set: CommentStickerSet,
   header: CommentStickerHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   frame: SpatialFrame,
   style: CommentStickerStyle,
   spec: CommentStickerItemSpec,
@@ -229,7 +229,7 @@ function realized(
 export function appendProjectedCommentSticker(
   set: CommentStickerSet,
   header: CommentStickerHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   frame: SpatialFrame,
   style: CommentStickerStyle,
   spec: CommentStickerItemSpec,
@@ -237,8 +237,8 @@ export function appendProjectedCommentSticker(
   window: ProjectedWindow,
   avatar?: BlobRef,
 ): CommentStickerSet {
-  assertTemporalWindowFor(window, { subjectId: spec.id, space });
-  return realized(set, header, space, frame, style, spec, content, window, avatar);
+  assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
+  return realized(set, header, timeline, frame, style, spec, content, window, avatar);
 }
 
 export function assertCommentStickerProgram(value: CommentStickerProgram): void {
@@ -589,12 +589,12 @@ function stickerElements(item: CommentStickerItemProgram): readonly VisualElemen
   return elements;
 }
 
-export function renderCommentSticker(canvas: CanvasSpace, space: ProgramSpace, program: CommentStickerProgram): VisualTrack {
+export function renderCommentSticker(canvas: CanvasSpace, timeline: Timeline, program: CommentStickerProgram): VisualTrack {
   assertCanvasSpace(canvas);
-  assertProgramSpaceIdentity(space);
+  assertProgramSpaceIdentity(timeline);
   assertCommentStickerProgram(program);
   const track = sealVisualTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     visualIr: "hypit.visual-ir@1",
     id: program.id,
     presents: program.items.map((item) => ({
@@ -605,6 +605,6 @@ export function renderCommentSticker(canvas: CanvasSpace, space: ProgramSpace, p
       elements: stickerElements(item),
     })),
   });
-  assertVisualTrackIdentity(track, space);
+  assertVisualTrackIdentity(track, timeline);
   return track;
 }

package/packages/comment-sticker/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import { artifactTypes } from "@hypit/artifact";
 import { mediaTypes } from "@hypit/media";
 import type { FontStackRef } from "@hypit/media";
@@ -88,11 +88,10 @@ export const decodeCommentStickerStyleSurface: StructuredSurfaceHandler = ({ ele
 };
 
 export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  allowed(element, ["id", "canvas", "semantic"], ["id", "canvas", "semantic"]);
+  allowed(element, ["id", "canvas", "timeline"], ["id", "canvas", "timeline"]);
   const id = text(element, "id");
   const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const headerId = `${id}.__header`;
   const records: SurfaceRecordDraft[] = [{
     id: headerId,
@@ -100,9 +99,9 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ ele
     value: { kind: "inline", value: sealCommentStickerHeader({ id }) },
     range: element.range,
   }];
-  const temporalComponents: SurfaceComponentDraft[] = [...time.components];
-  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [...time.fragments];
-  const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, space: time.space.ref };
+  const temporalComponents: SurfaceComponentDraft[] = [];
+  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
+  const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, header: { kind: "record", id: headerId }, timeline: context.timeline.ref };
   const items: Parameters<typeof createCommentStickerFragment>[0][number][] = [];
   for (const child of element.children) {
     if (child.kind === "text") {
@@ -113,7 +112,7 @@ export const decodeCommentStickerTrackSurface: StructuredSurfaceHandler = ({ ele
     if (child.children.some((node) => node.kind === "element")) throw new Error(`${child.name} accepts plain comment text only.`);
     allowed(child, ["id", "comment", "frame", "style", "avatar", "author", "header", "meta", ...TIMING], ["id", "frame", "style"]);
     const itemId = text(child, "id");
-    const temporal = createTemporalWindowProjection({ id: itemId, element: child, ...context, space: time.space, resolveReference });
+    const temporal = createTemporalWindowProjection({ id: itemId, element: child, ...context, resolveReference });
     records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
     const suffix = String(items.length + 1).padStart(4, "0");
     const frame = reference(child.attributes.frame, `${child.name}.frame`, spatialTypes.frame, resolveReference);

package/packages/comment-sticker-studio/src/index.ts

@@ -117,12 +117,13 @@ export const commentStickerStudioTrackCompanions: readonly StudioTrackCompanion[
     inspector: [
       ...frameParameters.filter(({ writable }) => writable === true).map(({ name }) => ({
         binding: `frame.${name}`, label: title(name), domain: "where" as const,
-        page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "text" as const,
+        page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "number" as const, number: { suffixes: ["%", "px"], step: 1 },
       })),
       ...commentInspector,
       ...["comment", "author", "header", "meta"].map((binding) => ({
         binding, label: title(binding), domain: "how" as const,
         page: { id: "copy", label: "Copy" }, section: { id: "copy", label: "Copy" }, control: "text" as const,
+        ...(binding === "comment" ? { multiline: true } : {}),
       })),
     ],
     requiredValues: ["program"], project: projectComments,

package/packages/compiler-node/src/compiler.ts

@@ -51,6 +51,7 @@ export function mergeAttachments(groups: readonly (readonly ArtifactAttachment[]
     merged.set(key, {
       artifact: { ...item.artifact },
       open: item.open,
+      ...(item.location === undefined ? {} : { location: item.location }),
     });
   }
   return [...merged.values()]

package/packages/composition/README.md

@@ -51,3 +51,24 @@ A Composition carries its id, Canvas with clear color, and peer Tracks. The Trac
 ProgramSpace identity; assembly and rendering receive the corresponding time domain separately.
 `@hypit/film` is one author-facing way to assemble it;
 `@hypit/render-hyperframes` consumes it to produce a video.
+
+### Visibility without a new playback origin
+
+A VisualPresent may supply `visibility`, an ordered list of non-overlapping subranges in program
+frames, all inside its `span`. Omission means the full span; an empty list means never visible.
+`span` continues to define local animation and media-sampling time. This permits rule overrides or
+other partial visibility without cutting a program into restarted copies. HyperFrames applies the
+visibility independently when seeking; custom HTML and typed media keep their original clocks.
+
+## Audio presentation on the program clock
+
+AudioClip optionally carries `gainEnvelope: { sample, gain }[]` and
+`audibility: { startSample, endSampleExclusive }[]`. Both use absolute 48 kHz program samples.
+Envelope points have strictly increasing sample positions and interpolate linearly, holding the
+outer endpoint gains. They multiply the existing Clip gain and fades. Audible subranges are ordered,
+disjoint and inside the original target; omission means the whole target, an empty list means silence.
+`audioEnvelopeGainAt` evaluates the envelope; `assertAudioPresentation` checks these values.
+
+Original target and source sampling remain intact when presentation is partially hidden. Range
+rendering applies envelopes and masks before cropping. These fields express generic sound behavior;
+source selection and Style/Use precedence belong to author components such as Sound.

package/packages/composition/src/audio-presentation.ts

@@ -0,0 +1,44 @@
+/** Gain and audibility are measured on the complete 48 kHz program clock. */
+export type AudioSampleSpan = { readonly startSample: number; readonly endSampleExclusive: number };
+export type AudioGainPoint = { readonly sample: number; readonly gain: number };
+export 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[];
+};
+
+export function assertAudioPresentation(value: AudioPresentation, target: AudioSampleSpan,
+  totalSamples = Number.MAX_SAFE_INTEGER): void {
+  if (value.gainEnvelope !== undefined) {
+    if (!Array.isArray(value.gainEnvelope) || value.gainEnvelope.length === 0) throw new Error("Audio gain envelope needs points.");
+    let previous = -1;
+    for (const point of value.gainEnvelope) {
+      if (!Number.isSafeInteger(point.sample) || point.sample <= previous || point.sample > totalSamples
+        || !Number.isFinite(point.gain) || point.gain < 0 || point.gain > 64) throw new Error("Audio gain envelope point is invalid.");
+      previous = point.sample;
+    }
+  }
+  if (value.audibility !== undefined) {
+    if (!Array.isArray(value.audibility)) throw new Error("Audio audibility must be sample intervals.");
+    let previous = target.startSample;
+    for (const span of value.audibility) {
+      if (!Number.isSafeInteger(span.startSample) || span.startSample < previous
+        || !Number.isSafeInteger(span.endSampleExclusive) || span.endSampleExclusive <= span.startSample
+        || span.endSampleExclusive > target.endSampleExclusive) throw new Error("Audio audibility is outside its target or overlaps.");
+      previous = span.endSampleExclusive;
+    }
+  }
+}
+
+export function audioEnvelopeGainAt(points: readonly AudioGainPoint[] | undefined, sample: number): number {
+  if (points === undefined) return 1;
+  const first = points[0];
+  if (first === undefined) throw new Error("Audio gain envelope needs points.");
+  if (sample <= first.sample) return first.gain;
+  for (let index = 1; index < points.length; index++) {
+    const left = points[index - 1]!, right = points[index]!;
+    if (sample <= right.sample) return left.gain + (right.gain - left.gain) * (sample - left.sample) / (right.sample - left.sample);
+  }
+  return points.at(-1)!.gain;
+}

package/packages/composition/src/index.ts

@@ -16,3 +16,6 @@ export {
 export { assertAudioTrackIdentity, assertCompositionIdentity, assertVisualTrackIdentity, sealAudioTrack, sealComposition, sealVisualTrack } from "./track.js";
 export { animatableLocalStyles } from "./track.js";
 export type * from "./track.js";
+
+export * from "./audio-presentation.js";
+export { audioSampleSpanSchema, audioGainEnvelopeSchema } from "./schema.js";

package/packages/composition/src/schema.ts

@@ -170,13 +170,16 @@ export const visualSurfaceSchema: ValueSchema = object({ ...base, kind: { schema
 export const visualProgramSchema: ValueSchema = object({ ...base, kind: { schema: { kind: "literal", value: "program" } }, program: { schema: object({ format: { schema: string }, payload: { schema: object({}, true) }, artifacts: { schema: { kind: "array", items: mediaBlobRef } } }) } });
 export const visualElementSchema: ValueSchema = { kind: "oneOf", variants: [visualBoxSchema, visualMaskSchema, visualTextSchema, textFlowElement, pathTextElement, visualImageSchema, visualVideoSchema, visualSurfaceSchema, visualProgramSchema] };
 const span = object({ startFrame: { schema: integer }, endFrameExclusive: { schema: integer } });
-const present = object({ id: { schema: string }, span: { schema: span }, stacking: { schema: object({ order: { schema: signedInteger }, tieBreak: { schema: string } }) }, elements: { schema: { kind: "array", minItems: 1, items: visualElementSchema } } });
+const present = object({ id: { schema: string }, subjectId: { schema: string, optional: true }, span: { schema: span }, visibility: { schema: { kind: "array", items: span }, optional: true }, stacking: { schema: object({ order: { schema: signedInteger }, tieBreak: { schema: string } }) }, elements: { schema: { kind: "array", minItems: 1, items: visualElementSchema } } });
 export const visualTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "visual" } }, programSpaceId: { schema: string }, visualIr: { schema: { kind: "literal", value: VISUAL_IR_V1 } }, id: { schema: string }, presents: { schema: { kind: "array", items: present } } });
-const audioSampleSpan = object({ startSample: { schema: integer }, endSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } } });
+export const audioSampleSpanSchema = object({ startSample: { schema: integer }, endSampleExclusive: { schema: { kind: "number", integer: true, minimum: 1 } } });
+export const audioGainEnvelopeSchema: ValueSchema = { kind: "array", minItems: 1, items: object({
+  sample: { schema: integer }, gain: { schema: { kind: "number", minimum: 0, maximum: 64 } },
+}) };
 const audioClip = object({
   id: { schema: string },
   artifact: { schema: audioBlobRef },
-  target: { schema: audioSampleSpan },
+  target: { schema: audioSampleSpanSchema },
   source: { schema: object({
     sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } },
     startSample: { schema: integer },
@@ -189,6 +192,8 @@ const audioClip = object({
   gain: { schema: { kind: "number", minimum: 0, maximum: 64 } },
   fadeInSamples: { schema: integer },
   fadeOutSamples: { schema: integer },
+  gainEnvelope: { schema: audioGainEnvelopeSchema, optional: true },
+  audibility: { schema: { kind: "array", items: audioSampleSpanSchema }, optional: true },
 });
 export const audioTrackSchema: ValueSchema = object({ kind: { schema: { kind: "literal", value: "audio" } }, programSpaceId: { schema: string }, id: { schema: string }, clips: { schema: { kind: "array", items: audioClip } } });
 export const compositionSchema: ValueSchema = object({ id: { schema: string }, canvas: { schema: object({ width: { schema: integer }, height: { schema: integer }, clearColor: { schema: string } }) }, tracks: { schema: { kind: "array", items: { kind: "oneOf", variants: [visualTrackSchema, audioTrackSchema] } } } });

package/packages/composition/src/track.ts

@@ -1,3 +1,5 @@
+import { assertAudioPresentation } from "./audio-presentation.js";
+import type { AudioPresentation } from "./audio-presentation.js";
 import { canonicalStringify, isResourceId } from "@hypit/protocol";
 import type { BlobRef, CanonicalValue } from "@hypit/protocol";
 
@@ -361,6 +363,8 @@ export type VisualPresent = {
   /** Optional domain entity implemented by this renderer Present. */
   readonly subjectId?: string;
   readonly span: FrameSpan;
+  /** Optional visible subranges in program frames; span remains the animation and sampling origin. */
+  readonly visibility?: readonly FrameSpan[];
   /** Absolute paint position for this Present, not for its authoring Track. */
   readonly stacking: {
     readonly order: number;
@@ -380,7 +384,7 @@ export type VisualTrack = {
   readonly presents: readonly VisualPresent[];
 };
 
-export type AudioClip = {
+export type AudioClip = AudioPresentation & {
   readonly id: string;
   /** Optional domain entity implemented by this renderer Clip. */
   readonly subjectId?: string;
@@ -935,6 +939,12 @@ function assertPresent(present: VisualPresent, programSpace: ProgramSpace | unde
   assertNonEmpty(present.id, `${trackId} Present id`);
   if (present.subjectId !== undefined) assertNonEmpty(present.subjectId, `${trackId}.${present.id} subjectId`);
   assertFrameSpan(present.span, totalFrames, `${trackId}.${present.id}.span`);
+  let previousEnd = present.span.startFrame;
+  for (const span of present.visibility ?? []) {
+    assertFrameSpan(span, present.span.endFrameExclusive, `${trackId}.${present.id}.visibility`);
+    if (span.startFrame < previousEnd) throw new Error(`${trackId}.${present.id} visibility must be ordered within its span.`);
+    previousEnd = span.endFrameExclusive;
+  }
   assertNonEmpty(present.stacking.tieBreak, `${trackId}.${present.id} stacking tieBreak`);
   if (!Number.isSafeInteger(present.stacking.order)) {
     throw new Error(`${trackId}.${present.id} has invalid stacking order.`);
@@ -1236,6 +1246,7 @@ function visualTrackContent(value: Omit<VisualTrack, "kind">): VisualTrack {
         id: present.id,
         ...(present.subjectId === undefined ? {} : { subjectId: present.subjectId }),
         span: { ...present.span },
+        ...(present.visibility === undefined ? {} : { visibility: present.visibility.map(span => ({ ...span })) }),
         stacking: { ...present.stacking },
         elements: [...present.elements].map(normalizeElement).sort((a, b) => a.order - b.order || a.id.localeCompare(b.id)),
       }))
@@ -1263,6 +1274,8 @@ function audioTrackContent(value: Omit<AudioTrack, "kind">): AudioTrack {
         gain: clip.gain,
         fadeInSamples: clip.fadeInSamples,
         fadeOutSamples: clip.fadeOutSamples,
+        ...(clip.gainEnvelope === undefined ? {} : { gainEnvelope: clip.gainEnvelope.map(point => ({ ...point })) }),
+        ...(clip.audibility === undefined ? {} : { audibility: clip.audibility.map(span => ({ ...span })) }),
       }))
       .sort((a, b) => a.target.startSample - b.target.startSample || a.id.localeCompare(b.id)),
   };
@@ -1337,6 +1350,7 @@ export function assertAudioTrackIdentity(track: AudioTrack, programSpace?: Progr
     if (!Number.isFinite(clip.gain) || clip.gain < 0 || clip.gain > 64) {
       throw new Error(`${track.id}.${clip.id} gain is invalid.`);
     }
+    assertAudioPresentation(clip, clip.target, totalSamples);
     const targetLength = clip.target.endSampleExclusive - clip.target.startSample;
     if (!Number.isSafeInteger(clip.fadeInSamples) || clip.fadeInSamples < 0 || clip.fadeInSamples > targetLength
       || !Number.isSafeInteger(clip.fadeOutSamples) || clip.fadeOutSamples < 0

package/packages/credential-store-env/README.md

@@ -3,7 +3,7 @@
 Read-only `CredentialStore` backed by explicitly named environment variables.
 
 ```ts
-credentialRef("env", "KIE_API_KEY")
+credentialRef("env", "IMAGE_API_KEY")
 ```
 
 It resolves only the requested key when an Endpoint needs it. It never enumerates or serializes the