@hypit/hypit 0.0.1 → 0.1.1

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

@@ -0,0 +1,162 @@
+import { appendMediaPerformance } from "./performance.js";
+import type { SemanticTrack } from "@hypit/semantic-track";
+import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
+import type { CompositableSurfaceRef, SynchronizedMedia } from "@hypit/media";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, StoredValue } from "@hypit/protocol";
+import type { ProgramSpace } from "@hypit/program-space";
+import type { CanvasSpace, ContentFit, IntrinsicExtent, SpatialFrame, SpatialPath } from "@hypit/spatial";
+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
+
+import {
+  appendMediaPaintLayer,
+  appendStillMediaLayer,
+  appendSurfaceMediaLayer,
+  appendTimedMediaLayer,
+  createMediaLayerSet,
+} from "./layers.js";
+import { mediaTrackProducers, mediaTrackTypes } from "./manifest.js";
+import { appendMediaItem, appendMediaSequence, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaTrackProgram, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack } from "./program.js";
+import {
+  appendMediaSequenceMember,
+  createMediaSequenceMemberSet,
+} from "./sequence.js";
+import {
+  appendMediaSound,
+  createMediaSoundSet,
+} from "./sounds.js";
+import type {
+  MediaItemSpec,
+  MediaLayerSet,
+  MediaPaintLayerSpec,
+  MediaSampleLayerSpec,
+  MediaSoundSet,
+  MediaSoundSpec,
+  MediaSequenceMemberSet,
+  MediaSequenceMemberSpec,
+  MediaSequenceSpec,
+  MediaTrackHeader,
+  MediaTrackProgram,
+  MediaTrackSet,
+} 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;
+}
+function blob(value: StoredValue | undefined): BlobRef {
+  if (value?.kind !== "blob") throw new Error("Media source must be a BlobArtifact.");
+  return value;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+function itemInputs(inputs: ProducerHandlerContext["inputs"]) {
+  return {
+    set: inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"),
+    header: inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
+    space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+    canvas: inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
+    layers: inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
+    frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+    spec: inline<MediaItemSpec>(inputs.spec?.value, "MediaItemSpec"),
+    sounds: inline<MediaSoundSet>(inputs.sounds?.value, "MediaSoundSet"),
+    window: inline<import("@hypit/temporal").TemporalWindow>(inputs.window?.value, "TemporalWindow"),
+  };
+}
+
+function memberInputs(inputs: ProducerHandlerContext["inputs"]) {
+  return {
+    members: inline<MediaSequenceMemberSet>(inputs.members?.value, "MediaSequenceMemberSet"),
+    space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+    layers: inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
+    spec: inline<MediaSequenceMemberSpec>(inputs.spec?.value, "MediaSequenceMemberSpec"),
+    activation: inline<TemporalInstant>(inputs.activation?.value, "TemporalInstant"),
+  };
+}
+
+function sequenceInputs(inputs: ProducerHandlerContext["inputs"]) {
+  return {
+    set: inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"),
+    header: inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
+    space: inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+    canvas: inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"),
+    members: inline<MediaSequenceMemberSet>(inputs.members?.value, "MediaSequenceMemberSet"),
+    frame: inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+    spec: inline<MediaSequenceSpec>(inputs.spec?.value, "MediaSequenceSpec"),
+    sounds: inline<MediaSoundSet>(inputs.sounds?.value, "MediaSoundSet"),
+    terminal: inline<TemporalInstant>(inputs.terminal?.value, "TemporalInstant"),
+  };
+}
+
+export const mediaTrackComponent = {
+  producers: [
+    { producer: mediaTrackProducers.appendPerformance, handler: ({ inputs }) => ({ outputs: { set: output(appendMediaPerformance(
+      itemInputs(inputs), inline<SemanticTrack>(inputs.semantic?.value, "SemanticTrack"),
+      inline<ContentFit>(inputs.fit?.value, "ContentFit"), inline<MediaSampleLayerSpec>(inputs.sampleSpec?.value, "MediaSampleLayerSpec"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.createLayers, handler: () => ({ outputs: { layers: output(createMediaLayerSet()) }, needs: {} }) },
+    { producer: mediaTrackProducers.appendPaintLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendMediaPaintLayer(
+      inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"),
+      inline<MediaPaintLayerSpec>(inputs.spec?.value, "MediaPaintLayerSpec"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.appendStillLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendStillMediaLayer(
+      inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), blob(inputs.source?.value),
+      inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<ContentFit>(inputs.fit?.value, "ContentFit"),
+      inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.appendTimedLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendTimedMediaLayer(
+      inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), inline<SynchronizedMedia>(inputs.source?.value, "SynchronizedMedia"),
+      inline<ContentFit>(inputs.fit?.value, "ContentFit"), inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.appendSurfaceLayer, handler: ({ inputs }) => ({ outputs: { layers: output(appendSurfaceMediaLayer(
+      inline<MediaLayerSet>(inputs.layers?.value, "MediaLayerSet"), inline<CompositableSurfaceRef>(inputs.source?.value, "CompositableSurfaceRef"),
+      inline<ContentFit>(inputs.fit?.value, "ContentFit"), inline<MediaSampleLayerSpec>(inputs.spec?.value, "MediaSampleLayerSpec"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.createSounds, handler: () => ({ outputs: { sounds: output(createMediaSoundSet()) }, needs: {} }) },
+    { producer: mediaTrackProducers.appendSound, handler: ({ inputs }) => ({ outputs: { sounds: output(appendMediaSound(
+      inline<MediaSoundSet>(inputs.sounds?.value, "MediaSoundSet"),
+      inline<SynchronizedMedia>(inputs.source?.value, "SynchronizedMedia"),
+      inline<MediaSoundSpec>(inputs.spec?.value, "MediaSoundSpec"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.createSet, handler: () => ({ outputs: { set: output(createMediaTrackSet()) }, needs: {} }) },
+    { producer: mediaTrackProducers.appendItem, handler: ({ inputs }) => {
+      const value = itemInputs(inputs);
+      return { outputs: { set: output(appendMediaItem(value.set, value.header, value.space, value.canvas, value.layers, value.frame, value.spec, value.sounds, value.window)) }, needs: {} };
+    } },
+    { producer: mediaTrackProducers.bindItemClipPath, handler: ({ inputs }) => ({ outputs: { spec: output(bindMediaItemClipPath(
+      inline<MediaItemSpec>(inputs.spec?.value, "MediaItemSpec"),
+      inline<SpatialPath>(inputs.path?.value, "SpatialPath"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.bindSequenceClipPath, handler: ({ inputs }) => ({ outputs: { spec: output(bindMediaSequenceClipPath(
+      inline<MediaSequenceSpec>(inputs.spec?.value, "MediaSequenceSpec"),
+      inline<SpatialPath>(inputs.path?.value, "SpatialPath"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.createMembers, handler: () => ({ outputs: { members: output(createMediaSequenceMemberSet()) }, needs: {} }) },
+    { producer: mediaTrackProducers.appendMember, handler: ({ inputs }) => {
+      const value = memberInputs(inputs);
+      return { outputs: { members: output(appendMediaSequenceMember(
+        value.members, value.space, value.layers, value.spec, value.activation,
+      )) }, needs: {} };
+    } },
+    { producer: mediaTrackProducers.appendSequence, handler: ({ inputs }) => {
+      const value = sequenceInputs(inputs);
+      return { outputs: { set: output(appendMediaSequence(
+        value.set, value.header, value.space, value.canvas, value.members, value.frame, value.spec, value.sounds, value.terminal,
+      )) }, needs: {} };
+    } },
+    { producer: mediaTrackProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeMediaTrack(
+      inline<MediaTrackSet>(inputs.set?.value, "MediaTrackSet"), inline<MediaTrackHeader>(inputs.header?.value, "MediaTrackHeader"),
+      inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.projectVisual, handler: ({ inputs }) => ({ outputs: { track: output(projectMediaVisualTrack(
+      inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
+    )) }, needs: {} }) },
+    { producer: mediaTrackProducers.projectAudio, handler: ({ inputs }) => ({ outputs: { track: output(projectMediaAudioTrack(
+      inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"), inline<MediaTrackProgram>(inputs.program?.value, "MediaTrackProgram"),
+    )) }, needs: {} }) },
+  ],
+  validators: [{
+    type: mediaTrackTypes.program,
+    handler: ({ value }) => assertMediaTrackProgram(inline<MediaTrackProgram>(value, "MediaTrackProgram")),
+  }],
+} satisfies ComponentPackage;

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

@@ -0,0 +1,57 @@
+import { programSpaceTypes } from "@hypit/program-space";
+import { artifactTypes } from "@hypit/artifact";
+import { compositionTypes } from "@hypit/composition";
+import { sealGraphFragment } from "@hypit/elaborator";
+import { spatialTypes } from "@hypit/spatial";
+import { temporalTypes } from "@hypit/temporal";
+
+import { mediaTrackProducers, mediaTrackTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+/** Minimal complete graph witness; richer Surfaces generate the same primitive operations dynamically. */
+export const stillMediaTrackFragment = sealGraphFragment({
+  inputs: [
+    { name: "header", type: mediaTrackTypes.header },
+    { name: "space", type: programSpaceTypes.programSpace },
+    { name: "canvas", type: spatialTypes.canvas },
+    { name: "source", type: artifactTypes.blob },
+    { name: "extent", type: spatialTypes.extent },
+    { name: "frame", type: spatialTypes.frame },
+    { name: "fit", type: spatialTypes.fit },
+    { name: "sample-spec", type: mediaTrackTypes.sampleLayerSpec },
+    { name: "item-spec", type: mediaTrackTypes.itemSpec },
+    { name: "window", type: temporalTypes.window },
+  ],
+  operations: [
+    { id: "layers", producer: mediaTrackProducers.createLayers, inputs: {}, result: { kind: "output", name: "layers" } },
+    { id: "sample", producer: mediaTrackProducers.appendStillLayer, inputs: {
+      layers: operation("layers"), source: input("source"), extent: input("extent"), fit: input("fit"), spec: input("sample-spec"),
+    }, result: { kind: "output", name: "layers" } },
+    { id: "set", producer: mediaTrackProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
+    { id: "sounds", producer: mediaTrackProducers.createSounds, inputs: {}, result: { kind: "output", name: "sounds" } },
+    { id: "append", producer: mediaTrackProducers.appendItem, inputs: {
+      set: operation("set"), header: input("header"), space: input("space"), canvas: input("canvas"), layers: operation("sample"),
+      frame: input("frame"), spec: input("item-spec"), sounds: operation("sounds"), window: input("window"),
+    }, result: { kind: "output", name: "set" } },
+    { id: "finalize", producer: mediaTrackProducers.finalize, inputs: {
+      set: operation("append"), header: input("header"), space: input("space"),
+    }, result: { kind: "output", name: "program" } },
+    { id: "visual", producer: mediaTrackProducers.projectVisual, inputs: {
+      space: input("space"), program: operation("finalize"),
+    }, result: { kind: "output", name: "track" } },
+  ],
+  exports: [
+    { name: "program", type: mediaTrackTypes.program, root: operation("finalize") },
+    { name: "track", type: compositionTypes.visualTrack, root: operation("visual") },
+  ],
+});
+
+export const renderMediaTrackFragment = sealGraphFragment({
+  inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: mediaTrackTypes.program }],
+  operations: [
+    { id: "visual", producer: mediaTrackProducers.projectVisual, inputs: { space: input("space"), program: input("program") }, result: { kind: "output", name: "track" } },
+  ],
+  exports: [{ name: "track", type: compositionTypes.visualTrack, root: operation("visual") }],
+});

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

@@ -0,0 +1,65 @@
+export { mediaTrackComponent } from "./component.js";
+export {
+  decodeMediaFit,
+  decodeMediaFramePaint,
+  decodeMediaMotion,
+  decodeMediaPresentation,
+  decodeMediaSampleAppearance,
+  decodeMediaSampleSpec,
+  mediaAppearanceKeys,
+} from "./author.js";
+export { renderMediaTrackFragment, stillMediaTrackFragment } from "./fragment.js";
+export {
+  appendMediaPaintLayer,
+  appendStillMediaLayer,
+  appendSurfaceMediaLayer,
+  appendTimedMediaLayer,
+  assertMediaLayerSet,
+  assertMediaPaintLayerSpec,
+  assertMediaSampleLayerSpec,
+  assertMediaVisualOccupancy,
+  assertMediaVisualSource,
+  createMediaLayerSet,
+  sealMediaPaintLayerSpec,
+  sealMediaSampleLayerSpec,
+} from "./layers.js";
+export { lowerMediaItemElements } from "./lower.js";
+export { mediaItemSpecSchema, mediaFramePresentationSchema, mediaLifecycleMotionSchema, mediaLayerSetSchema, mediaHandoffSpecSchema, mediaPaintLayerSpecSchema, mediaSampleAppearanceSchema, mediaSampleLayerSpecSchema, mediaSamplingMotionSchema, mediaSoundSetSchema, mediaSoundSpecSchema, mediaSequenceMemberSetSchema, mediaSequenceMemberSpecSchema, mediaSequenceSpecSchema, mediaTrackDependency, mediaTrackHeaderSchema, mediaTrackManifest, mediaTrackMarkupSurfaces, mediaTrackModuleRef, mediaTrackProducers, mediaTrackProgramSchema, mediaTrackSetSchema, mediaTrackTypes } from "./manifest.js";
+export {
+  assertMediaEdgeMotion,
+  assertMediaLifecycleMotion,
+  assertMediaSustainMotion,
+  lifecycleAnimation,
+  samplingAnimation,
+  lifecycleAnimationWindow,
+  resolveMediaLifecycleMotion,
+  sustainAnimation,
+  sustainAnimationWindow,
+} from "./motion.js";
+export { assertMediaFramePresentation } from "./presentation.js";
+export {
+  appendMediaSound,
+  assertMediaSoundSet,
+  assertMediaSoundSpec,
+  createMediaSoundSet,
+  sealMediaSoundSpec,
+} from "./sounds.js";
+export { appendMediaItem, appendMediaSequence, bindMediaItemClipPath, bindMediaSequenceClipPath, assertMediaItemSpec, assertMediaTrackHeader, assertMediaTrackProgram, assertMediaTrackProgramIdentity, assertMediaTrackSet, createMediaTrackSet, finalizeMediaTrack, projectMediaAudioTrack, projectMediaVisualTrack, sealMediaItemSpec, sealMediaTrackHeader, sealMediaTrackProgram } from "./program.js";
+export { resolveVisualSampling } from "./sampling.js";
+export { appendMediaPerformance } from "./performance.js";
+export { decodeMediaSamplingKeyframe, decodeMediaTrackSurface } from "./surface.js";
+export {
+  appendMediaSequenceMember,
+  assertMediaHandoffSpec,
+  assertMediaSequenceMemberSet,
+  assertMediaSequenceMemberSpec,
+  assertMediaSequenceSpec,
+  createMediaSequenceMemberSet,
+  lowerMediaSequencePresents,
+  resolveMediaSequence,
+  sealMediaHandoffSpec,
+  sealMediaSequenceMemberSpec,
+  sealMediaSequenceSpec,
+  sequenceMemberHandoffAnimation,
+} from "./sequence.js";
+export type * from "./types.js";

package/packages/media-track/src/layers.ts

@@ -0,0 +1,308 @@
+import {
+  assertCompositableSurfaceRef,
+  synchronizedMediaSampleFrames,
+  verifySynchronizedMedia,
+} from "@hypit/media";
+import type { CompositableSurfaceRef, SynchronizedMedia } from "@hypit/media";
+import { canonicalize, isResourceId } from "@hypit/protocol";
+import type { BlobRef } from "@hypit/protocol";
+import {
+  assertContentFit,
+  assertIntrinsicExtent,
+} from "@hypit/spatial";
+import type { ContentFit, IntrinsicExtent } from "@hypit/spatial";
+
+import type {
+  MediaGradientStop,
+  MediaLayerProgram,
+  MediaLayerSet,
+  MediaPaint,
+  MediaPaintLayerSpec,
+  MediaSampleLayerProgram,
+  MediaSampleLayerSpec,
+  MediaSamplingMotion,
+  MediaVisualOccupancy,
+  MediaVisualSource,
+  MediaVisualTrim,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+export function assertMediaIdentity(value: string, label: string): void {
+  assert(/^[A-Za-z][A-Za-z0-9_.:#-]{0,191}$/u.test(value), `${label} is invalid.`);
+}
+
+function assertBlob(value: BlobRef, label: string, prefix?: string): void {
+  assert(value.kind === "blob" && isResourceId(value.resource)
+    && Number.isSafeInteger(value.size) && value.size >= 0 && value.mediaType.length > 0,
+  `${label} is not a valid BlobArtifact.`);
+  if (prefix !== undefined) assert(value.mediaType.startsWith(prefix), `${label} must be ${prefix} bytes.`);
+}
+
+function finite(value: number, label: string): void {
+  assert(Number.isFinite(value), `${label} must be finite.`);
+}
+
+function unit(value: number, label: string): void {
+  finite(value, label);
+  assert(value >= 0 && value <= 1, `${label} must be inside [0, 1].`);
+}
+
+function assertColor(value: string, label: string): void {
+  assert(typeof value === "string" && value.trim().length > 0 && !/[;{}]/u.test(value), `${label} is invalid.`);
+}
+
+function assertStops(stops: readonly MediaGradientStop[], label: string): void {
+  assert(stops.length >= 2, `${label} needs at least two stops.`);
+  let previous = -1;
+  for (const [index, stop] of stops.entries()) {
+    unit(stop.offset, `${label}.${index}.offset`);
+    assert(stop.offset > previous, `${label} offsets must be strictly increasing.`);
+    assertColor(stop.color, `${label}.${index}.color`);
+    previous = stop.offset;
+  }
+}
+
+export function assertMediaPaint(value: MediaPaint, label: string): void {
+  if (value.kind === "solid") {
+    assertColor(value.color, `${label}.color`);
+    return;
+  }
+  assertStops(value.stops, `${label}.stops`);
+  if (value.kind === "linear-gradient") {
+    finite(value.angleDeg, `${label}.angleDeg`);
+    return;
+  }
+  assert(value.kind === "radial-gradient", `${label}.kind is unsupported.`);
+  unit(value.center.x, `${label}.center.x`);
+  unit(value.center.y, `${label}.center.y`);
+}
+
+export function assertMediaVisualTrim(value: MediaVisualTrim, sourceFrames: number, label: string): void {
+  assert(Number.isSafeInteger(value.startFrame) && Number.isSafeInteger(value.endFrameExclusive)
+    && value.startFrame >= 0 && value.endFrameExclusive > value.startFrame
+    && value.endFrameExclusive <= sourceFrames, `${label} is outside its source.`);
+}
+
+export function assertMediaVisualOccupancy(value: MediaVisualOccupancy, label: string): void {
+  if (value.mode === "stretch") return;
+  assert(["once", "hold", "loop"].includes(value.mode)
+    && (value.align === "start" || value.align === "end"), `${label} is invalid.`);
+}
+
+export function assertMediaSamplingMotion(value: MediaSamplingMotion, label: string): void {
+  assert(value.keyframes.length >= 2, `${label} needs at least two keyframes.`);
+  let previous = -1;
+  for (const [index, keyframe] of value.keyframes.entries()) {
+    finite(keyframe.atProgress, `${label}.${index}.atProgress`);
+    assert(keyframe.atProgress >= 0 && keyframe.atProgress <= 1 && keyframe.atProgress > previous,
+      `${label}.${index}.atProgress is invalid.`);
+    finite(keyframe.zoom, `${label}.${index}.zoom`);
+    assert(keyframe.zoom > 0 && keyframe.zoom <= 100, `${label}.${index}.zoom is invalid.`);
+    finite(keyframe.offsetX, `${label}.${index}.offsetX`);
+    finite(keyframe.offsetY, `${label}.${index}.offsetY`);
+    finite(keyframe.rotationDeg, `${label}.${index}.rotationDeg`);
+    if (keyframe.easing !== undefined) {
+      assert(["linear", "ease-in", "ease-out", "ease-in-out"].includes(keyframe.easing),
+        `${label}.${index}.easing is invalid.`);
+    }
+    previous = keyframe.atProgress;
+  }
+  assert(value.keyframes[0]!.atProgress === 0 && value.keyframes.at(-1)!.atProgress === 1,
+    `${label} must cover normalized progress [0, 1].`);
+}
+
+export function assertMediaVisualSource(value: MediaVisualSource, label: string): void {
+  assertIntrinsicExtent(value.extent);
+  if (value.kind === "still") {
+    assertBlob(value.artifact, `${label}.artifact`, "image/");
+    return;
+  }
+  if (value.kind === "surface") {
+    assertCompositableSurfaceRef(value.surface, `${label}.surface`);
+    assert(value.extent.widthPx === value.surface.width && value.extent.heightPx === value.surface.height,
+      `${label} Surface extent disagrees with its intrinsic dimensions.`);
+    return;
+  }
+  assert(value.kind === "timed", `${label}.kind is unsupported.`);
+  assertBlob(value.artifact, `${label}.artifact`, "video/");
+  assert(Number.isSafeInteger(value.frameRate.numerator) && value.frameRate.numerator > 0
+    && Number.isSafeInteger(value.frameRate.denominator) && value.frameRate.denominator > 0
+    && Number.isSafeInteger(value.frameCount) && value.frameCount > 0, `${label} timing is invalid.`);
+  if (value.audio !== undefined) {
+    assertBlob(value.audio.artifact, `${label}.audio.artifact`, "audio/");
+    assert(Number.isSafeInteger(value.audio.sampleFrames) && value.audio.sampleFrames > 0,
+      `${label}.audio.sampleFrames is invalid.`);
+  }
+}
+
+export function assertMediaSampleLayerSpec(value: MediaSampleLayerSpec): void {
+  assertMediaIdentity(value.id, "MediaSampleLayerSpec.id");
+  unit(value.appearance.opacity, "MediaSampleLayerSpec.appearance.opacity");
+  const filter = value.appearance.filter;
+  finite(filter.blurPx, "MediaSampleLayerSpec.filter.blurPx");
+  finite(filter.brightness, "MediaSampleLayerSpec.filter.brightness");
+  finite(filter.contrast, "MediaSampleLayerSpec.filter.contrast");
+  finite(filter.saturation, "MediaSampleLayerSpec.filter.saturation");
+  assert(filter.blurPx >= 0 && filter.brightness >= 0 && filter.contrast >= 0 && filter.saturation >= 0,
+    "MediaSampleLayerSpec filter values must be non-negative.");
+  if (value.occupancy !== undefined) assertMediaVisualOccupancy(value.occupancy, "MediaSampleLayerSpec.occupancy");
+  if (value.samplingMotion !== undefined) assertMediaSamplingMotion(value.samplingMotion, "MediaSampleLayerSpec.samplingMotion");
+}
+
+export function sealMediaSampleLayerSpec(value: MediaSampleLayerSpec): MediaSampleLayerSpec {
+  assertMediaSampleLayerSpec(value);
+  return canonicalize(value) as unknown as MediaSampleLayerSpec;
+}
+
+export function assertMediaPaintLayerSpec(value: MediaPaintLayerSpec): void {
+  assertMediaIdentity(value.id, "MediaPaintLayerSpec.id");
+  assertMediaPaint(value.paint, "MediaPaintLayerSpec.paint");
+  unit(value.opacity, "MediaPaintLayerSpec.opacity");
+}
+
+export function sealMediaPaintLayerSpec(value: MediaPaintLayerSpec): MediaPaintLayerSpec {
+  assertMediaPaintLayerSpec(value);
+  return canonicalize(value) as unknown as MediaPaintLayerSpec;
+}
+
+export function createMediaLayerSet(): MediaLayerSet {
+  return { layers: [] };
+}
+
+export function assertMediaLayerSet(value: MediaLayerSet): void {
+  assert(Array.isArray(value.layers), "MediaLayerSet is invalid.");
+  const ids = new Set<string>();
+  for (const layer of value.layers) {
+    assertMediaIdentity(layer.id, "Media layer id");
+    assert(!ids.has(layer.id), `MediaLayerSet repeats layer ${layer.id}.`);
+    ids.add(layer.id);
+    if (layer.kind === "paint") {
+      assertMediaPaint(layer.paint, `Media layer ${layer.id}.paint`);
+      unit(layer.opacity, `Media layer ${layer.id}.opacity`);
+      continue;
+    }
+    assert(layer.kind === "sample", `Media layer ${layer.id} kind is unsupported.`);
+    assertMediaVisualSource(layer.source, `Media layer ${layer.id}.source`);
+    assertContentFit(layer.fit);
+    if (layer.source.kind === "still") {
+      assert(layer.trim === undefined && layer.occupancy === undefined,
+        `Still Media layer ${layer.id} cannot have trim or occupancy.`);
+    } else {
+      const frames = layer.source.kind === "timed"
+        ? layer.source.frameCount
+        : layer.source.surface.timing.kind === "frames" ? layer.source.surface.timing.frameCount : undefined;
+      if (frames === undefined) {
+        assert(layer.trim === undefined && layer.occupancy === undefined,
+          `Still Surface layer ${layer.id} cannot have trim or occupancy.`);
+      } else {
+        if (layer.trim !== undefined) assertMediaVisualTrim(layer.trim, frames, `Media layer ${layer.id}.trim`);
+        assert(layer.occupancy !== undefined, `Timed Media layer ${layer.id} requires occupancy.`);
+        assertMediaVisualOccupancy(layer.occupancy, `Media layer ${layer.id}.occupancy`);
+      }
+    }
+    assertMediaSampleLayerSpec({
+
+      id: layer.id,
+      ...(layer.trim === undefined ? {} : { trim: layer.trim }),
+      ...(layer.occupancy === undefined ? {} : { occupancy: layer.occupancy }),
+      appearance: layer.appearance,
+      ...(layer.samplingMotion === undefined ? {} : { samplingMotion: layer.samplingMotion }),
+    });
+  }
+}
+
+function append(set: MediaLayerSet, layer: MediaLayerProgram): MediaLayerSet {
+  assertMediaLayerSet(set);
+  assert(!set.layers.some((item) => item.id === layer.id), `MediaLayerSet already contains ${layer.id}.`);
+  const result = { layers: [...set.layers, layer] };
+  assertMediaLayerSet(result);
+  return canonicalize(result) as unknown as MediaLayerSet;
+}
+
+export function appendMediaPaintLayer(set: MediaLayerSet, spec: MediaPaintLayerSpec): MediaLayerSet {
+  assertMediaPaintLayerSpec(spec);
+  return append(set, { id: spec.id, kind: "paint", paint: structuredClone(spec.paint), opacity: spec.opacity });
+}
+
+function sampleLayer(source: MediaVisualSource, fit: ContentFit, spec: MediaSampleLayerSpec): MediaSampleLayerProgram {
+  assertMediaVisualSource(source, "Media sample source");
+  assertContentFit(fit);
+  assertMediaSampleLayerSpec(spec);
+  const layer: MediaSampleLayerProgram = {
+    id: spec.id,
+    kind: "sample",
+    source: structuredClone(source),
+    fit: structuredClone(fit),
+    ...(spec.trim === undefined ? {} : { trim: { ...spec.trim } }),
+    ...(spec.occupancy === undefined ? {} : { occupancy: structuredClone(spec.occupancy) }),
+    appearance: structuredClone(spec.appearance),
+    ...(spec.samplingMotion === undefined ? {} : { samplingMotion: structuredClone(spec.samplingMotion) }),
+  };
+  return layer;
+}
+
+export function appendStillMediaLayer(
+  set: MediaLayerSet,
+  source: BlobRef,
+  extent: IntrinsicExtent,
+  fit: ContentFit,
+  spec: MediaSampleLayerSpec,
+): MediaLayerSet {
+  assertBlob(source, "Still Media source", "image/");
+  assertIntrinsicExtent(extent);
+  assert(spec.trim === undefined && spec.occupancy === undefined,
+    "Still Media source cannot have trim or occupancy.");
+  return append(set, sampleLayer({ kind: "still", artifact: structuredClone(source), extent: { ...extent } }, fit, spec));
+}
+
+export function appendTimedMediaLayer(
+  set: MediaLayerSet,
+  media: SynchronizedMedia,
+  fit: ContentFit,
+  spec: MediaSampleLayerSpec,
+): MediaLayerSet {
+  verifySynchronizedMedia(media);
+  assert(media.visual !== undefined, "Timed Media source has no normalized visual member.");
+  assert(spec.occupancy !== undefined, "Timed Media source requires explicit occupancy.");
+  const source: MediaVisualSource = {
+    kind: "timed",
+    artifact: structuredClone(media.visual.artifact),
+    extent: {
+      widthPx: media.visual.width,
+      heightPx: media.visual.height,
+    },
+    frameRate: { ...media.timeline.frameRate },
+    frameCount: media.timeline.frameCount,
+    ...(media.audio === undefined ? {} : { audio: {
+      artifact: structuredClone(media.audio.artifact),
+      sampleFrames: synchronizedMediaSampleFrames(media),
+    } }),
+  };
+  return append(set, sampleLayer(source, fit, spec));
+}
+
+export function appendSurfaceMediaLayer(
+  set: MediaLayerSet,
+  surface: CompositableSurfaceRef,
+  fit: ContentFit,
+  spec: MediaSampleLayerSpec,
+): MediaLayerSet {
+  assertCompositableSurfaceRef(surface);
+  let effectiveSpec = spec;
+  if (surface.timing.kind === "frames") {
+    effectiveSpec = spec.occupancy === undefined
+      ? sealMediaSampleLayerSpec({ ...spec, occupancy: { mode: "once", align: "start" } })
+      : spec;
+  } else {
+    assert(spec.trim === undefined && spec.occupancy === undefined,
+      "Still Media Surface cannot have trim or occupancy.");
+  }
+  return append(set, sampleLayer({
+    kind: "surface",
+    surface: structuredClone(surface),
+    extent: { widthPx: surface.width, heightPx: surface.height },
+  }, fit, effectiveSpec));
+}