@hypit/hypit 0.0.1 → 0.1.1

package/packages/deck-track/src/component.ts

@@ -0,0 +1,86 @@
+import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+import type { ProgramSpace } from "@hypit/program-space";
+import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+import type { TemporalInstant } from "@hypit/temporal";
+import type { MediaLayerSet } from "@hypit/media-track";
+import type { Text } from "@hypit/text";
+
+import { renderDepthStack } from "./lower.js";
+import { depthStackProducers, depthStackTypes } from "./manifest.js";
+import { appendDepthStackCard, assertDepthStackProgram, createDepthStackCardSet, finalizeDepthStack, bindDepthStackCardLabelText } from "./program.js";
+import type {
+  DepthStackCardLabel,
+  DepthStackCardLabelStyle,
+  DepthStackCardSet,
+  DepthStackCardSpec,
+  DepthStackHeader,
+  DepthStackProgram,
+  DepthStackSpec,
+} from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, label: string): T {
+  if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
+  return value.value as unknown as T;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+function finalizeInputs(inputs: ProducerHandlerContext["inputs"]) {
+  return {
+    set: inline<DepthStackCardSet>(inputs.set?.value, "DepthStackCardSet"),
+    header: inline<DepthStackHeader>(inputs.header?.value, "DepthStackHeader"),
+    frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+    spec: inline<DepthStackSpec>(inputs.spec?.value, "DepthStackSpec"),
+    space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+  };
+}
+
+export const depthStackComponent = {
+  producers: [
+    {
+      producer: depthStackProducers.bindLabelText,
+      handler: ({ inputs }) => ({ outputs: { label: output(bindDepthStackCardLabelText(
+        inline<DepthStackCardLabelStyle>(inputs.style?.value, "DepthStackCardLabelStyle"),
+        inline<Text>(inputs.content?.value, "Text"),
+      )) }, needs: {} }),
+    },
+    {
+      producer: depthStackProducers.createCards,
+      handler: () => ({ outputs: { set: output(createDepthStackCardSet()) }, needs: {} }),
+    },
+    {
+      producer: depthStackProducers.appendCard,
+      handler: ({ inputs }) => ({ outputs: { set: output(appendDepthStackCard(
+        inline<DepthStackCardSet>(inputs.set?.value, "DepthStackCardSet"),
+        inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+        inline<MediaLayerSet>(inputs.material?.value, "MediaLayerSet"),
+        inline<DepthStackCardLabel>(inputs.label?.value, "DepthStackCardLabel"),
+        inline<DepthStackCardSpec>(inputs.spec?.value, "DepthStackCardSpec"),
+        inline<TemporalInstant>(inputs.activation?.value, "TemporalInstant"),
+      )) }, needs: {} }),
+    },
+    {
+      producer: depthStackProducers.finalize,
+      handler: ({ inputs }) => {
+        const value = finalizeInputs(inputs);
+        return { outputs: { program: output(finalizeDepthStack(
+          value.set, value.header, value.frame, value.spec,
+          inline<TemporalInstant>(inputs.terminal?.value, "TemporalInstant"), value.space,
+        )) }, needs: {} };
+      },
+    },
+    {
+      producer: depthStackProducers.render,
+      handler: ({ inputs }) => ({ outputs: { track: output(renderDepthStack(
+        inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
+        inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+        inline<DepthStackProgram>(inputs.program?.value, "DepthStackProgram"),
+      )) }, needs: {} }),
+    },
+  ],
+  validators: [{
+    type: depthStackTypes.program,
+    handler: ({ value }) => assertDepthStackProgram(inline<DepthStackProgram>(value, "DepthStackProgram")),
+  }],
+} satisfies ComponentPackage;

package/packages/deck-track/src/fragment.ts

@@ -0,0 +1,148 @@
+import { programSpaceTypes } from "@hypit/program-space";
+import { artifactTypes } from "@hypit/artifact";
+import { compositionTypes } from "@hypit/composition";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation, GraphFragment } from "@hypit/elaborator";
+import { mediaTypes } from "@hypit/media";
+import { mediaTrackProducers, mediaTrackTypes } from "@hypit/media-track";
+import { spatialTypes } from "@hypit/spatial";
+import { temporalTypes } from "@hypit/temporal";
+
+import { depthStackProducers, depthStackTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export type DepthStackFragmentCard = {
+  readonly suffix: string;
+  readonly sourceKind: "still" | "timed" | "surface";
+  readonly sourceName: string;
+  readonly extentName?: string;
+  readonly fitName: string;
+  readonly sampleSpecName: string;
+  readonly framePaintSpecName?: string;
+  readonly labelName: string;
+  readonly cardSpecName: string;
+  readonly activationName: string;
+};
+
+function sourceInput(card: DepthStackFragmentCard): GraphFragment["inputs"][number] {
+  const type = card.sourceKind === "still"
+    ? artifactTypes.blob
+    : card.sourceKind === "timed" ? mediaTypes.synchronized : mediaTypes.compositableSurface;
+  return { name: card.sourceName, type };
+}
+
+export function createDepthStackFragment(
+  cards: readonly DepthStackFragmentCard[],
+  terminalName: string,
+) {
+  if (cards.length === 0) throw new Error("DepthStack Fragment requires Cards.");
+  const inputs: Array<GraphFragment["inputs"][number]> = [
+    { name: "canvas", type: spatialTypes.canvas },
+    { name: "frame", type: spatialTypes.frame },
+    { name: "header", type: depthStackTypes.header },
+    { name: "space", type: programSpaceTypes.programSpace },
+    { name: "spec", type: depthStackTypes.spec },
+  ];
+  const operations: FragmentOperation[] = [
+    {
+      id: "cards",
+      producer: depthStackProducers.createCards,
+      inputs: {},
+      result: { kind: "output", name: "set" },
+    },
+  ];
+  let cardSet = operation("cards");
+  for (const card of cards) {
+    inputs.push(sourceInput(card));
+    if (card.extentName !== undefined) inputs.push({ name: card.extentName, type: spatialTypes.extent });
+    inputs.push(
+      { name: card.fitName, type: spatialTypes.fit },
+      { name: card.sampleSpecName, type: mediaTrackTypes.sampleLayerSpec },
+      { name: card.labelName, type: depthStackTypes.cardLabel },
+      { name: card.cardSpecName, type: depthStackTypes.cardSpec },
+      { name: card.activationName, type: temporalTypes.instant },
+    );
+    if (card.framePaintSpecName !== undefined) {
+      inputs.push({ name: card.framePaintSpecName, type: mediaTrackTypes.paintLayerSpec });
+    }
+    const layersId = `layers-${card.suffix}`;
+    operations.push({
+      id: layersId,
+      producer: mediaTrackProducers.createLayers,
+      inputs: {},
+      result: { kind: "output", name: "layers" },
+    });
+    let layers = operation(layersId);
+    if (card.framePaintSpecName !== undefined) {
+      const paintId = `paint-${card.suffix}`;
+      operations.push({
+        id: paintId,
+        producer: mediaTrackProducers.appendPaintLayer,
+        inputs: { layers, spec: input(card.framePaintSpecName) },
+        result: { kind: "output", name: "layers" },
+      });
+      layers = operation(paintId);
+    }
+    const sampleId = `sample-${card.suffix}`;
+    const producer = card.sourceKind === "still"
+      ? mediaTrackProducers.appendStillLayer
+      : card.sourceKind === "timed" ? mediaTrackProducers.appendTimedLayer : mediaTrackProducers.appendSurfaceLayer;
+    operations.push({
+      id: sampleId,
+      producer,
+      inputs: {
+        layers,
+        source: input(card.sourceName),
+        ...(card.extentName === undefined ? {} : { extent: input(card.extentName) }),
+        fit: input(card.fitName),
+        spec: input(card.sampleSpecName),
+      },
+      result: { kind: "output", name: "layers" },
+    });
+    const appendId = `append-${card.suffix}`;
+    operations.push({
+      id: appendId,
+      producer: depthStackProducers.appendCard,
+      inputs: {
+        set: cardSet,
+        space: input("space"),
+        material: operation(sampleId),
+        label: input(card.labelName),
+        spec: input(card.cardSpecName),
+        activation: input(card.activationName),
+      },
+      result: { kind: "output", name: "set" },
+    });
+    cardSet = operation(appendId);
+  }
+  inputs.push({ name: terminalName, type: temporalTypes.instant });
+  operations.push({
+    id: "program",
+    producer: depthStackProducers.finalize,
+    inputs: {
+      set: cardSet,
+      header: input("header"),
+      frame: input("frame"),
+      spec: input("spec"),
+      space: input("space"),
+      terminal: input(terminalName),
+    },
+    result: { kind: "output", name: "program" },
+  });
+  operations.push({
+    id: "track",
+    producer: depthStackProducers.render,
+    inputs: { canvas: input("canvas"), space: input("space"), program: operation("program") },
+    result: { kind: "output", name: "track" },
+  });
+  return sealGraphFragment({
+    inputs,
+    operations,
+    exports: [
+      { name: "program", type: depthStackTypes.program, root: operation("program") },
+      { name: "track", type: compositionTypes.visualTrack, root: operation("track") },
+    ],
+  });
+}

package/packages/deck-track/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  decodeDepthStackCardSpec,
+  decodeDepthStackMaterial,
+  decodeDepthStackSpec,
+} from "./author.js";
+export { depthStackComponent } from "./component.js";
+export { createDepthStackFragment } from "./fragment.js";
+export type { DepthStackFragmentCard } from "./fragment.js";
+export {
+  decodeDepthStackLabelSurface,
+  decodeDepthStackSurface,
+} from "./surface.js";
+export { renderDepthStack } from "./lower.js";
+export { depthStackCardLabelSchema, depthStackCardLabelStyleSchema, depthStackCardSetSchema, depthStackCardSpecSchema, depthStackDependency, depthStackHeaderSchema, depthStackManifest, depthStackMarkupSurfaces, depthStackModuleRef, depthStackProducers, depthStackProgramSchema, depthStackSpecSchema, depthStackTypes } from "./manifest.js";
+export { appendDepthStackCard, assertDepthStackCardLabel, assertDepthStackCardLabelStyle, assertDepthStackCardSet, assertDepthStackCardSpec, assertDepthStackHeader, assertDepthStackProgram, assertDepthStackProgramIdentity, assertDepthStackSpec, createDepthStackCardSet, finalizeDepthStack, noDepthStackCardLabel, resolveDepthStackPose, resolveDepthStackState, sealDepthStackCardLabel, sealDepthStackCardLabelStyle, bindDepthStackCardLabelText, sealDepthStackCardSpec, sealDepthStackHeader, sealDepthStackSpec } from "./program.js";
+export type * from "./types.js";

package/packages/deck-track/src/lower.ts

@@ -0,0 +1,370 @@
+import {
+  assertVisualTrackIdentity,
+  sealVisualTrack,
+} from "@hypit/composition";
+import type {
+  VisualAnimation,
+  VisualElement,
+  VisualStyleDeclaration,
+  VisualTimedSampling,
+  VisualTrack,
+} from "@hypit/composition";
+import {
+  lifecycleAnimationWindow,
+  lowerMediaItemElements,
+  resolveVisualSampling,
+  sustainAnimationWindow,
+} from "@hypit/media-track";
+import type {
+  MediaItemProgram,
+  MediaSampleLayerProgram,
+  MediaVisualTrim,
+} from "@hypit/media-track";
+import type { ProgramSpace } from "@hypit/program-space";
+import { assertCanvasSpace } from "@hypit/spatial";
+import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+
+import {
+  assertDepthStackProgramIdentity,
+  resolveDepthStackPose,
+  resolveDepthStackState,
+} from "./program.js";
+import type {
+  DepthStackCard,
+  DepthStackPose,
+  DepthStackProgram,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function px(value: number): string {
+  return `${value}px`;
+}
+
+function poseStyle(value: DepthStackPose): VisualStyleDeclaration[] {
+  return [
+    {
+      name: "filter",
+      value: `brightness(${value.tone.brightness}) contrast(${value.tone.contrast}) saturate(${value.tone.saturation})`,
+    },
+    { name: "opacity", value: value.opacity },
+    {
+      name: "transform",
+      value: `translate(${value.xPx}px,${value.yPx}px) rotate(${value.rotationDeg}deg) scale(${value.scale})`,
+    },
+  ];
+}
+
+function hiddenPose(program: DepthStackProgram, direction: "previous" | "next"): DepthStackPose {
+  const depth = direction === "previous"
+    ? -(program.spec.visibility.previous + 1)
+    : program.spec.visibility.next + 1;
+  return { ...resolveDepthStackPose(program.spec, depth), opacity: 0 };
+}
+
+function poseAnimation(input: {
+  readonly program: DepthStackProgram;
+  readonly stageDuration: number;
+  readonly oldDepth?: number;
+  readonly newDepth?: number;
+}): VisualAnimation | undefined {
+  if (input.newDepth === undefined && input.oldDepth === undefined) return undefined;
+  if (input.program.spec.reflow.durationFrames === 0) return undefined;
+  const oldPose = input.oldDepth === undefined
+    ? hiddenPose(input.program, input.newDepth === 0 || input.newDepth! > 0 ? "next" : "previous")
+    : resolveDepthStackPose(input.program.spec, input.oldDepth);
+  const newPose = input.newDepth === undefined
+    ? hiddenPose(input.program, input.oldDepth === 0 || input.oldDepth! < 0 ? "previous" : "next")
+    : resolveDepthStackPose(input.program.spec, input.newDepth);
+  const duration = input.program.spec.reflow.durationFrames;
+  const keyframes = [
+    { atFrame: 0, easing: input.program.spec.reflow.easing, style: poseStyle(oldPose) },
+    { atFrame: duration, style: poseStyle(newPose) },
+  ];
+  if (duration < input.stageDuration) keyframes.push({ atFrame: input.stageDuration, style: poseStyle(newPose) });
+  return { keyframes };
+}
+
+function rootBox(id: string, parent: string | undefined, order: number, style: VisualStyleDeclaration[], animation?: VisualAnimation): VisualElement {
+  return {
+    id,
+    ...(parent === undefined ? {} : { parent }),
+    order,
+    kind: "box",
+    style,
+    ...(animation === undefined ? {} : { animation }),
+  };
+}
+
+function rational(numerator: number, denominator = 1) {
+  return { numerator, denominator };
+}
+
+function modulo(value: number, size: number): number {
+  return ((value % size) + size) % size;
+}
+
+function sourceTiming(layer: MediaSampleLayerProgram): {
+  readonly frameRate: { readonly numerator: number; readonly denominator: number };
+  readonly frameCount: number;
+} | undefined {
+  if (layer.source.kind === "timed") {
+    return { frameRate: layer.source.frameRate, frameCount: layer.source.frameCount };
+  }
+  if (layer.source.kind === "surface" && layer.source.surface.timing.kind === "frames") {
+    return {
+      frameRate: layer.source.surface.timing.frameRate,
+      frameCount: layer.source.surface.timing.frameCount,
+    };
+  }
+  return undefined;
+}
+
+function trimFor(layer: MediaSampleLayerProgram, frameCount: number): MediaVisualTrim {
+  return layer.trim ?? { startFrame: 0, endFrameExclusive: frameCount };
+}
+
+function heldSampling(
+  timing: NonNullable<ReturnType<typeof sourceTiming>>,
+  targetFrames: number,
+  sourceFrame: number,
+): VisualTimedSampling {
+  return {
+    sourceFrameRate: { ...timing.frameRate },
+    sourceFrameCount: timing.frameCount,
+    segments: [{
+      target: { startFrame: 0, endFrameExclusive: targetFrames },
+      sourceFrame: rational(sourceFrame),
+      rate: rational(0),
+    }],
+  };
+}
+
+function continuedSampling(input: {
+  readonly timing: NonNullable<ReturnType<typeof sourceTiming>>;
+  readonly trim: MediaVisualTrim;
+  readonly targetFrames: number;
+  readonly absoluteStart: number;
+  readonly activationFrame: number;
+}): VisualTimedSampling {
+  const length = input.trim.endFrameExclusive - input.trim.startFrame;
+  const phase = modulo(input.absoluteStart - input.activationFrame, length);
+  return {
+    sourceFrameRate: { ...input.timing.frameRate },
+    sourceFrameCount: input.timing.frameCount,
+    segments: [{
+      target: { startFrame: 0, endFrameExclusive: input.targetFrames },
+      sourceFrame: rational(input.trim.startFrame + phase),
+      rate: rational(1),
+      loop: { ...input.trim },
+    }],
+  };
+}
+
+function samplingFor(input: {
+  readonly program: DepthStackProgram;
+  readonly card: DepthStackCard;
+  readonly layer: MediaSampleLayerProgram;
+  readonly relation: number;
+  readonly stageStart: number;
+  readonly stageDuration: number;
+  readonly space: ProgramSpace;
+}): VisualTimedSampling | undefined {
+  const timing = sourceTiming(input.layer);
+  if (timing === undefined) return undefined;
+  assert(timing.frameRate.numerator === input.space.frameRate.numerator
+    && timing.frameRate.denominator === input.space.frameRate.denominator,
+  `DepthStack Card ${input.card.id} timed material must be normalized to ProgramSpace.`);
+  const trim = trimFor(input.layer, timing.frameCount);
+  if (input.relation === 0) {
+    return resolveVisualSampling({
+      space: input.space,
+      sourceFrameRate: timing.frameRate,
+      sourceFrameCount: timing.frameCount,
+      targetFrameCount: input.stageDuration,
+      trim,
+      occupancy: input.layer.occupancy!,
+    });
+  }
+  const mode = input.relation > 0 ? input.card.playback.future : input.card.playback.past;
+  if (mode === "continue") {
+    assert(input.layer.occupancy?.mode === "loop" && input.layer.occupancy.align === "start",
+      `DepthStack Card ${input.card.id} continue playback requires loop-start active occupancy.`);
+    return continuedSampling({
+      timing,
+      trim,
+      targetFrames: input.stageDuration,
+      absoluteStart: input.stageStart,
+      activationFrame: input.card.activationFrame,
+    });
+  }
+  return heldSampling(
+    timing,
+    input.stageDuration,
+    mode === "hold-tail" ? trim.endFrameExclusive - 1 : trim.startFrame,
+  );
+}
+
+function groupElements(input: {
+  readonly program: DepthStackProgram;
+  readonly stageStart: number;
+  readonly stageEnd: number;
+  readonly pose: DepthStackPose;
+  readonly poseAnimation?: VisualAnimation;
+}): { readonly elements: VisualElement[]; readonly poseParent: string } {
+  const frame = input.program.frame;
+  const duration = input.program.span.endFrameExclusive - input.program.span.startFrame;
+  const startOffset = input.stageStart - input.program.span.startFrame;
+  const endOffset = input.stageEnd - input.program.span.startFrame;
+  let order = 0;
+  const elements: VisualElement[] = [rootBox("deck-placement", undefined, order++, [
+    { name: "height", value: px(frame.heightPx) },
+    { name: "left", value: px(frame.xPx) },
+    { name: "position", value: "absolute" },
+    { name: "top", value: px(frame.yPx) },
+    { name: "width", value: px(frame.widthPx) },
+  ])];
+  let parent = "deck-placement";
+  const lifecycle = lifecycleAnimationWindow(input.program.spec.motion, duration, startOffset, endOffset);
+  elements.push(rootBox("deck-lifecycle", parent, order++, [
+    { name: "height", value: "100%" },
+    { name: "position", value: "absolute" },
+    { name: "transform-origin", value: "center center" },
+    { name: "width", value: "100%" },
+  ], lifecycle));
+  parent = "deck-lifecycle";
+  for (const [index, sustain] of input.program.spec.motion.sustain.entries()) {
+    const id = `deck-sustain-${index + 1}`;
+    elements.push(rootBox(id, parent, order++, [
+      { name: "height", value: "100%" },
+      { name: "position", value: "absolute" },
+      { name: "transform-origin", value: "center center" },
+      { name: "width", value: "100%" },
+    ], sustainAnimationWindow(sustain, duration, startOffset, endOffset)));
+    parent = id;
+  }
+  elements.push(rootBox("deck-pose", parent, order++, [
+    { name: "height", value: "100%" },
+    { name: "position", value: "absolute" },
+    { name: "transform-origin", value: "center center" },
+    { name: "width", value: "100%" },
+    ...poseStyle(input.pose),
+  ], input.poseAnimation));
+  return { elements, poseParent: "deck-pose" };
+}
+
+function localFrame(frame: SpatialFrame): SpatialFrame {
+  return {
+    xPx: 0,
+    yPx: 0,
+    widthPx: frame.widthPx,
+    heightPx: frame.heightPx,
+  };
+}
+
+function labelElement(card: DepthStackCard, parent: string, order: number): VisualElement | undefined {
+  if (card.label.kind === "none") return undefined;
+  return {
+    id: "deck-label",
+    parent,
+    order,
+    kind: "text-flow",
+    style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 }],
+    document: structuredClone(card.label.document),
+    typography: structuredClone(card.label.typography),
+    paints: structuredClone(card.label.paints),
+    flow: structuredClone(card.label.flow),
+    sequences: [],
+  };
+}
+
+export function renderDepthStack(
+  canvas: CanvasSpace,
+  space: ProgramSpace,
+  program: DepthStackProgram,
+): VisualTrack {
+  assertDepthStackProgramIdentity(program, space);
+  assertCanvasSpace(canvas);
+  const presents: VisualTrack["presents"][number][] = [];
+  for (let stageIndex = 0; stageIndex < program.cards.length; stageIndex += 1) {
+    const stageStart = program.cards[stageIndex]!.activationFrame;
+    const stageEnd = program.cards[stageIndex + 1]?.activationFrame ?? program.terminalFrame;
+    const stageDuration = stageEnd - stageStart;
+    const oldState = stageIndex === 0 ? new Map<number, number>() : resolveDepthStackState(program, stageIndex - 1);
+    const newState = resolveDepthStackState(program, stageIndex);
+    const cardIndices = stageIndex === 0 || program.spec.reflow.durationFrames === 0
+      ? [...newState.keys()]
+      : [...new Set([...oldState.keys(), ...newState.keys()])];
+    for (const cardIndex of cardIndices) {
+      const card = program.cards[cardIndex]!;
+      const oldDepth = oldState.get(cardIndex);
+      const newDepth = newState.get(cardIndex);
+      const staticPose = newDepth === undefined
+        ? hiddenPose(program, oldDepth === 0 || (oldDepth ?? -1) < 0 ? "previous" : "next")
+        : resolveDepthStackPose(program.spec, newDepth);
+      const animation = stageIndex === 0 ? undefined : poseAnimation({
+        program,
+        stageDuration,
+        ...(oldDepth === undefined ? {} : { oldDepth }),
+        ...(newDepth === undefined ? {} : { newDepth }),
+      });
+      const group = groupElements({
+        program,
+        stageStart,
+        stageEnd,
+        pose: staticPose,
+        ...(animation === undefined ? {} : { poseAnimation: animation }),
+      });
+      const relation = newDepth ?? (oldDepth === 0 ? -1 : oldDepth ?? 1);
+      const samplingOverrides: Record<string, VisualTimedSampling> = {};
+      const samplingAnimationOverrides: Record<string, VisualAnimation | null> = {};
+      for (const layer of card.material.layers) {
+        if (layer.kind !== "sample") continue;
+        const sampling = samplingFor({ program, card, layer, relation, stageStart, stageDuration, space });
+        if (sampling !== undefined) samplingOverrides[layer.id] = sampling;
+        if (relation !== 0 && layer.samplingMotion !== undefined) samplingAnimationOverrides[layer.id] = null;
+      }
+      const mediaItem: MediaItemProgram = {
+        id: "deck-material",
+        subjectId: card.id,
+        span: { startFrame: stageStart, endFrameExclusive: stageEnd },
+        frame: localFrame(program.frame),
+        presentation: structuredClone(program.spec.presentation),
+        layers: structuredClone(card.material.layers),
+        motion: { sustain: [] },
+        stacking: { order: 0, tieBreak: card.id },
+        sounds: [],
+      };
+      const material = [...lowerMediaItemElements(mediaItem, space, {
+        placementParent: group.poseParent,
+        lifecycleAnimationOverride: null,
+        samplingOverrides,
+        samplingAnimationOverrides,
+      })].map((element) => ({ ...element, order: element.order + group.elements.length }));
+      const frameId = `${mediaItem.id}:frame`;
+      const label = labelElement(card, frameId, material.reduce((maximum, element) => Math.max(maximum, element.order), 0) + 1);
+      presents.push({
+        id: `${card.id}:stage:${stageIndex + 1}`,
+        subjectId: card.id,
+        span: { startFrame: stageStart, endFrameExclusive: stageEnd },
+        stacking: {
+          order: program.spec.stackingOrder + (newDepth === undefined
+            ? resolveDepthStackPose(program.spec, oldDepth ?? 0).stacking
+            : resolveDepthStackPose(program.spec, newDepth).stacking),
+          tieBreak: `${program.id}:${String(stageIndex).padStart(4, "0")}:${card.id}`,
+        },
+        elements: [...group.elements, ...material, ...(label === undefined ? [] : [label])],
+      });
+    }
+  }
+  const track = sealVisualTrack({
+    programSpaceId: space.id,
+    visualIr: "hypit.visual-ir@1",
+    id: program.id,
+    presents,
+  });
+  assertVisualTrackIdentity(track, space);
+  return track;
+}