@hypit/hypit 0.0.1 → 0.1.0

package/packages/media-track/README.md

@@ -0,0 +1,197 @@
+# `@hypit/media-track`
+
+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`
+inputs accept a Moment or a time such as `2s`; `at` with `for` produces a Window where required.
+`Performance` still needs `semantic`, which supplies its ordered prepared footage.
+
+Place images, prepared video or compositable surfaces over the semantic timeline. B-roll is a common
+use: the picture can illustrate a phrase while the A-roll's speech continues. Performance presents the semantic material as a full picture, inset or cutout.
+Media Items own independently timed pictures;
+a Sequence owns one visual slot whose Members replace each other through Handoffs.
+
+The Markup Track takes `canvas` and a time source (`semantic` or `space`). Its Surface projects
+authored Selections, Moments, Segments or clock expressions into Windows and Instants. The component
+consumes those projected times with Frames, media and appearance; its Fragment receives ProgramSpace.
+
+Moving media enters after [normalization](../media-pipeline/README.md), with the intended streams and
+frame clock already selected. Still images use their actual intrinsic Extent. Placement, fitting,
+sampling and motion remain separate authored choices.
+
+## Display a semantic performance
+
+```svml
+<media:Track id="performance" semantic={speech.semantic} canvas={canvas}>
+  <media:Performance during="program" frame={layout.full}
+    appearance={look.performance}/>
+</media:Track>
+```
+
+`Performance` displays the prepared material in its enclosing Track's `semantic` input. `during`
+selects the whole program, a Segment or a Selection; the other Window forms work as usual. One
+Performance can span any number of Takes. Each plays at its original program position: if a Take
+begins at program second 5, a Window from seconds 7 to 10 shows source seconds 2 to 5. An audio-only
+interval contributes no picture. The presentation shares one frame, appearance and lifecycle across
+Take boundaries.
+
+Its appearance Recipe needs `stack-order` and can set fit, crop anchors, opacity, filters, clipping,
+padding, border, shadow and frame paint. `motion` moves the framed presentation, and `Sampling`
+children transform the fitted picture over the complete selected Window, without restarting at
+Take boundaries. `Sound` children attach prepared effects to its entrance or exit. Its original
+sound is independently available as `speech.audio` for Film. Use an Item with direct `media` for
+independent playback or source trim; Performance preserves the semantic assembly's source timing.
+
+```svml
+<media:Performance during={story.segment.explanation} frame={layout.full}
+  appearance={look.performance}>
+  <media:Sampling at="start" zoom="1"/>
+  <media:Sampling at="end" zoom="1.08"/>
+</media:Performance>
+```
+
+This excerpt belongs inside the same Media Track. Its selected passage determines the appearance
+interval, while the two Sampling keys direct a gradual push-in inside the unchanged Frame.
+
+For a fixed card, full picture, circle or cutout this is ordinary Media presentation. If video and
+graphics must resize, mask or move together, write a project component that owns that relationship.
+`projectSemanticMedia` supplies the same material spans to its drawing function. The component can
+use a browser program from `@hypit/hypit/hyperframes` while Caption and independent overlays remain peers.
+
+## Place the frame, then fit its contents
+
+An Item or Sequence owns an outer destination `frame`. Each sampled source has a fitted content
+rectangle calculated from its intrinsic extent and its fit Recipe. Border and padding reduce the
+fitting area inside the outer Frame. Source dimensions stay factual; the calculated rectangle can
+be smaller or larger than the fitting area.
+
+[Spatial](../spatial/README.md#destination-and-fitted-content) owns the seven fit modes, the two
+alignment points, pixel offsets and bounded/free placement. `frame-x` / `frame-y` are alignment
+fractions in that fitting area. Move the whole visual by changing the `frame` reference; choose
+which part of the picture is visible through the fit and content alignment.
+
+The appearance Recipe separates the outer presentation from the sampled picture:
+
+| Properties | What they affect |
+| --- | --- |
+| `stack-order` | Absolute visual stacking of the Item or Sequence; required |
+| `clip` | Outer clipping: `frame` (default), `rounded`, or `none` |
+| `radius` | Pixel radius when `clip: rounded`; half a square Frame's side gives a circle |
+| `padding` | Fitting inset, as quoted pixel values: `"12"`, `"8 12"`, or `"8 12 16 12"` |
+| `border-width`, `border-style`, `border-color` | Border inside the outer Frame; a positive width requires a color |
+| `shadows` | Frame shadows, as quoted `x y blur spread color` entries separated by semicolons |
+| `frame-paint` | Solid or gradient backing behind the content |
+| `fit`, alignment and fit offsets | The scaled source's rectangle |
+| `opacity`, `blur`, `brightness`, `contrast`, `saturation` | The sampled picture, independently of frame decoration |
+
+For example, this is a rounded card with an inset picture and a painted backing:
+
+```svs
+media.card {
+  stack-order: 40;
+  fit: contain;
+  clip: rounded;
+  radius: 24;
+  padding: "12";
+  border-width: 2;
+  border-color: #B9A88B;
+  frame-paint: #25332D;
+  shadows: "0 8 20 0 #00000055";
+}
+```
+
+The outer size includes the border; border and padding both reduce the fitting area. The clip
+follows the outer Frame, so a smaller contained picture may retain square corners inside a rounded
+card. A rounded picture with a flush edge uses a Frame matching its displayed aspect. `clip: none`
+allows source overflow; fitting alone supplies no mask. An authored spatial Path can be bound to
+an Item or Sequence with `clip={path}` in place of the Recipe's clip choice. Path coordinates are in
+Canvas pixels.
+
+A `motion` Recipe transforms the framed unit, including its backing and decoration. `Sampling`
+transforms the fitted source inside it, around the source rectangle's center. It accepts `zoom`,
+pixel `x` / `y`, degree `rotate`, and `easing`, at `start`, `end`, or intermediate percentages. Supply
+keys spanning start to end. Sampling runs after fitting and is not constrained by `fit-constraint`;
+a deliberate pan or rotation may reveal the backing or lower layers.
+
+## Author Items and replacement Sequences
+
+These excerpts assume the imports, named assets, normalized media, Frames, Extents, Script,
+SemanticTrack and Recipes are already declared:
+
+```svml
+<media-track:Track id="coverage" semantic={speech.semantic} canvas={vertical}>
+  <media-track:Item image={photo} extent={photo-extent} frame={full-frame}
+    during={story.selection.example} appearance={recipes.media.still}/>
+  <media-track:Item media={clip-media.media} frame={full-frame}
+    during={story.selection.proof} appearance={recipes.media.clip}/>
+</media-track:Track>
+```
+
+One Item selects exactly one direct source form (`image` + `extent`, prepared `media`, or `surface`)
+or declares ordered `Paint`/`Layer` children. The current Surface has no raw `video` attribute.
+Appearance owns stack order, fit, clipping and source sampling; a `motion` Recipe owns lifecycle
+movement. `Sampling` children can move the sampled content inside the Frame independently.
+
+```svml
+<media-track:Track id="cards" semantic={speech.semantic} canvas={vertical}>
+  <media-track:Sequence id="steps" frame={card-frame} appearance={recipes.media.card}
+    until={story.selection.demo} until-boundary="end">
+    <media-track:Member id="one" image={first} extent={card-extent}
+      at={story.moment.first}/>
+    <media-track:Member id="two" image={second} extent={card-extent}
+      at={story.moment.second}/>
+    <media-track:Handoff id="one-two" from="one" transition={recipes.transition.cards}/>
+  </media-track:Sequence>
+</media-track:Track>
+```
+
+Members have ordered activation Instants; the next activation ends the preceding logical phase,
+and the Sequence has an explicit terminal Instant. Each adjacent pair needs a Handoff, including
+an explicit `cut` when no blended transition is intended. `from` names the outgoing Member; its
+successor is the incoming Member. A Handoff's duration and boundary ratio place the visual transition
+around that logical boundary without moving the semantic event.
+
+For layered content, `Paint` and `Layer` children draw in Source order inside the shared Frame. Give
+each Layer its own fit/sample Recipe. A Member appearance override selects its source fit, sampling
+and frame paint; the Sequence still owns the outer Frame, clip, padding, border, shadow, motion and
+stack order. Separate Items supply independently placed Frames.
+
+An Item or Member can select audio using `source-audio`: `content` for its direct source, or a child
+Layer id for layered content. This is opt-in. `Sound` can instead attach normalized audio to Item
+`at="enter"` / `at="exit"`, or to a Sequence `handoff="one-two"`. The Track publishes `.visual` and
+`.program`, plus `.audio` when sound is present; Film must include the desired peer outputs.
+
+## Item windows and source playback
+
+The Item's projected Window determines when it is active in the program. A timed sample's Recipe
+separately controls which source frames it occupies there. `playback` defaults to `once-start`:
+
+| Value | Source occupancy inside the Window |
+| --- | --- |
+| `once-start` | Play at native rate from the source start. Truncate if the Window is shorter; draw no source after it ends if the Window is longer. |
+| `once-end` | Align native playback to the Window end. Use the source tail if the Window is shorter; leave the initial excess unoccupied if longer. |
+| `hold-start` | Play from the start, then hold the last source frame over any remaining Window. |
+| `hold-end` | Align playback to the end, holding the first source frame over any initial excess. |
+| `loop-start` / `loop-end` | Repeat at native rate, aligning the loop phase to the start or end. |
+| `stretch` | Retime the selected source range across the full Window. |
+
+`trim-start` and `trim-end` are a pair of integer source-frame boundaries, with an exclusive end.
+Omit both to use the full source. The playback rules apply to the trimmed range when present.
+For `stretch`, the source-frame advance is `sourceLength / targetLength`. For native playback, moving
+media has already been normalized to ProgramSpace's frame rate, so one program frame advances one
+source frame. These are source sampling choices; they do not move a Selection's semantic boundaries.
+
+A two-second Item can use the beginning of a four-second generated clip without requesting a
+model-invalid two-second generation. Conversely, an Item active longer than its source must choose
+whether a return to the layer below, a hold, a loop or retiming is intended. No mode is universally
+correct for B-roll. Extending a Window with `once-start` does not extend the underlying video.
+
+Durationless still images refuse `playback`, `trim-start` and `trim-end`. Their spatial placement and
+Item Window are sufficient. A static B-roll picture does not need conversion to a generated clip.
+
+Visual and source-audio projections remain separate. Selecting source audio applies the corresponding
+sampling policy to that audio; a held visual frame does not synthesize held sound. A silent B-roll
+layer can cover a speaking Track while the latter's audio continues unchanged.
+
+For adjacent semantic Items that should have no uncovered pause, author touching Selection boundaries
+using Script affinity. Also inspect opacity transitions and source exhaustion: touching Windows alone
+do not guarantee opaque visual coverage.

package/packages/media-track/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hypit/media-track",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/artifact": "workspace:*",
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/spatial": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*"
+  }
+}

package/packages/media-track/preview/build.svrun

@@ -0,0 +1,5 @@
+<?svml using="@hypit/run-markup@1"?>
+<svrun version="1">
+  <author source="./preview.svml"/>
+  <target output="final.video"/>
+</svrun>

package/packages/media-track/preview/preview.svml

@@ -0,0 +1,47 @@
+<?svml using="@hypit/markup@1"?>
+<!-- A wordless catalogue composition using this package's two sample graphics.
+     The samples are the displayed content. Their frame treatments demonstrate fit,
+     padding, clipping and motion; build.svrun renders the same composition. -->
+<svml>
+  <import from="@hypit/script@1"/>
+  <import as="media" from="@hypit/media@1"/>
+  <import as="pipeline" from="@hypit/media-pipeline@1"/>
+  <import as="speech" from="@hypit/speech-track@1"/>
+  <import as="whisperx" from="@hypit/whisperx@1"/>
+  <import as="media-track" from="@hypit/media-track@1"/>
+  <import as="space" from="@hypit/spatial@1"/>
+  <import as="program" from="@hypit/program-space@1"/>
+  <import as="film" from="@hypit/film@1"/>
+  <import as="render" from="@hypit/render-hyperframes@1"/>
+  <import as="recipes" source="./recipes.svs"/>
+
+  <script id="story"><empty></empty></script>
+  <space:Canvas id="vertical" width="720" height="1280"/>
+  <program:Clock id="clock" frame-rate="30"/>
+  <space:Frame id="full" within={vertical} left="0%" top="0%" right="100%" bottom="100%"/>
+  <space:Frame id="card-a" within={vertical}
+    left="8%" top="16%" right="92%" bottom="46%"/>
+  <space:Frame id="card-b" within={vertical}
+    left="12%" top="52%" right="88%" bottom="78%"/>
+  <space:Extent id="picture-size" width="640" height="360"/>
+  <media:Image id="picture-a" src="./rounded.png"/>
+  <media:Image id="picture-b" src="./flush.png"/>
+
+  <pipeline:StillVideo id="duration" source={picture-a} duration="5" clock={clock}/>
+  <pipeline:Normalize id="duration-media" source={duration.video} clock={clock}
+    video="primary-moving" audio="none" span-authority="video"/>
+  <whisperx:SemanticTake id="showcase-time" narrative={story}
+    segment={story.segment.empty} media={duration-media.media}/>
+  <speech:Track id="speech"><speech:Take source={showcase-time.take}/></speech:Track>
+
+  <media-track:Track id="showcase" semantic={speech.semantic} canvas={vertical}>
+    <media-track:Item id="rounded-card" image={picture-a} extent={picture-size} during="program"
+      frame={card-a} appearance={recipes.media.card} motion={recipes.motion.card}/>
+    <media-track:Item id="flush-card" image={picture-b} extent={picture-size} during="program"
+      frame={card-b} appearance={recipes.media.wide} motion={recipes.motion.card}/>
+  </media-track:Track>
+  <film:Film id="main" canvas={vertical} semantic={speech.semantic} appearance={recipes.film.vertical}>
+    <film:Track source={showcase.visual}/>
+  </film:Film>
+  <render:Video id="final" composition={main.composition} semantic={speech.semantic}/>
+</svml>

package/packages/media-track/preview/recipes.svs

@@ -0,0 +1,23 @@
+<?svml using="@hypit/svs@1"?>
+
+<sheet version="1">
+  media.performance { stack-order: 0; fit: cover; }
+  film.vertical { background: #09090B; }
+
+  /* Rounded and padded, so the painted content box is visibly inset from the
+     Placement Frame Studio draws as a guide. */
+  media.card {
+    stack-order: 40; fit: cover;
+    frame-paint: #16161d; clip: rounded; radius: 24; padding: 12 12;
+  }
+  /* Square and flush, for contrast with media.card. */
+  media.wide {
+    stack-order: 41; fit: cover;
+    frame-paint: #1d1620; clip: frame;
+    border-width: 2; border-color: #ee7b6255;
+  }
+  motion.card {
+    enter: slide; enter-frames: 5; enter-direction: up; enter-easing: ease-out;
+    exit: fade; exit-frames: 5; exit-easing: ease-in;
+  }
+</sheet>

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

@@ -0,0 +1,20 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import {
+  decodeMediaTrackSurface,
+  mediaTrackComponent,
+  mediaTrackManifest,
+  mediaTrackModuleRef,
+  mediaTrackMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: mediaTrackManifest }],
+  components: [mediaTrackComponent],
+  hostFacets: [createMarkupSurfaceHostFacet({
+    module: mediaTrackModuleRef,
+    declaration: mediaTrackMarkupSurfaces.find((item) => item.name === "track")!,
+    handler: decodeMediaTrackSurface,
+  })],
+};
+export default hypitPackage;

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

@@ -0,0 +1,317 @@
+import type { SvsRecipe } from "@hypit/svs";
+import { decodeContentFitProperties } from "@hypit/spatial";
+import type { ContentFit } from "@hypit/spatial";
+
+import {
+  sealMediaPaintLayerSpec,
+  sealMediaSampleLayerSpec,
+} from "./layers.js";
+import { sealMediaItemSpec } from "./program.js";
+import { sealMediaHandoffSpec, sealMediaSequenceSpec } from "./sequence.js";
+import type {
+  MediaFramePresentation,
+  MediaHandoffSpec,
+  MediaItemSpec,
+  MediaLifecycleMotion,
+  MediaPaint,
+  MediaPaintLayerSpec,
+  MediaSampleLayerSpec,
+  MediaSampleAppearance,
+  MediaSequenceSpec,
+  MediaVisualOccupancy,
+  MediaVisualTrim,
+} from "./types.js";
+
+function fail(recipe: SvsRecipe, message: string): never {
+  throw new Error(`Media Recipe ${recipe.path} ${message}`);
+}
+
+function optionalNumber(recipe: SvsRecipe, name: string): number | undefined {
+  const value = recipe.properties[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value)) fail(recipe, `${name} must be a finite number.`);
+  return value;
+}
+
+function number(recipe: SvsRecipe, name: string, fallback?: number): number {
+  const value = optionalNumber(recipe, name);
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (value === undefined) fail(recipe, `requires ${name}.`);
+  return value;
+}
+
+function optionalString(recipe: SvsRecipe, name: string): string | undefined {
+  const value = recipe.properties[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.trim().length === 0) fail(recipe, `${name} must be text.`);
+  return value.trim();
+}
+
+function string(recipe: SvsRecipe, name: string, fallback?: string): string {
+  const value = optionalString(recipe, name);
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (value === undefined) fail(recipe, `requires ${name}.`);
+  return value;
+}
+
+function oneOf<T extends string>(recipe: SvsRecipe, name: string, values: readonly T[], fallback?: T): T {
+  const value = optionalString(recipe, name);
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (value === undefined || !values.includes(value as T)) fail(recipe, `${name} must be ${values.join(" | ")}.`);
+  return value as T;
+}
+
+function assertKeys(recipe: SvsRecipe, allowed: readonly string[]): void {
+  const unknown = Object.keys(recipe.properties).filter((name) => !allowed.includes(name));
+  if (unknown.length > 0) fail(recipe, `does not accept ${unknown.join(", ")}.`);
+}
+
+function scalarList(recipe: SvsRecipe, name: string, allowed: readonly number[]): number[] {
+  const source = optionalString(recipe, name);
+  if (source === undefined) return [];
+  const values = source.split(/\s+/u).map(Number);
+  if (!allowed.includes(values.length) || values.some((value) => !Number.isFinite(value))) {
+    fail(recipe, `${name} requires ${allowed.join(" or ")} finite numbers.`);
+  }
+  return values;
+}
+
+function padding(recipe: SvsRecipe): MediaFramePresentation["padding"] {
+  const values = scalarList(recipe, "padding", [1, 2, 4]);
+  if (values.length === 0) return { topPx: 0, rightPx: 0, bottomPx: 0, leftPx: 0 };
+  if (values.length === 1) return { topPx: values[0]!, rightPx: values[0]!, bottomPx: values[0]!, leftPx: values[0]! };
+  if (values.length === 2) return { topPx: values[0]!, rightPx: values[1]!, bottomPx: values[0]!, leftPx: values[1]! };
+  return { topPx: values[0]!, rightPx: values[1]!, bottomPx: values[2]!, leftPx: values[3]! };
+}
+
+function gradientStops(recipe: SvsRecipe, source: string): readonly { readonly offset: number; readonly color: string }[] {
+  const stops = source.split(",").map((entry) => {
+    const match = /^(.+?)@((?:0(?:\.\d+)?)|(?:1(?:\.0+)?))$/u.exec(entry.trim());
+    if (match === null) fail(recipe, "gradient stops must be color@offset inside [0,1].");
+    return { color: match[1]!.trim(), offset: Number(match[2]) };
+  });
+  if (stops.length < 2) fail(recipe, "gradient requires at least two stops.");
+  return stops;
+}
+
+function paint(recipe: SvsRecipe, property = "paint"): MediaPaint {
+  const source = string(recipe, property);
+  const linear = /^linear\(([-+]?\d+(?:\.\d+)?);(.+)\)$/u.exec(source);
+  if (linear !== null) {
+    return { kind: "linear-gradient", angleDeg: Number(linear[1]), stops: gradientStops(recipe, linear[2]!) };
+  }
+  const radial = /^radial\(((?:0(?:\.\d+)?)|(?:1(?:\.0+)?)),((?:0(?:\.\d+)?)|(?:1(?:\.0+)?));(.+)\)$/u.exec(source);
+  if (radial !== null) {
+    return { kind: "radial-gradient", center: { x: Number(radial[1]), y: Number(radial[2]) }, stops: gradientStops(recipe, radial[3]!) };
+  }
+  return { kind: "solid", color: source };
+}
+
+function shadows(recipe: SvsRecipe): MediaFramePresentation["shadows"] {
+  const source = optionalString(recipe, "shadows");
+  if (source === undefined || source === "none") return [];
+  return source.split(";").map((entry) => {
+    const match = /^([-+]?\d+(?:\.\d+)?)\s+([-+]?\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)\s+([-+]?\d+(?:\.\d+)?)\s+(.+)$/u.exec(entry.trim());
+    if (match === null) fail(recipe, "shadows entries require x y blur spread color.");
+    return {
+      offsetX: Number(match[1]), offsetY: Number(match[2]), blurPx: Number(match[3]),
+      spreadPx: Number(match[4]), color: match[5]!.trim(),
+    };
+  });
+}
+
+const FIT_KEYS = ["fit", "frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y", "fit-constraint"] as const;
+const SAMPLE_KEYS = ["opacity", "blur", "brightness", "contrast", "saturation", "playback", "trim-start", "trim-end"] as const;
+const FRAME_KEYS = ["stack-order", "clip", "radius", "padding", "border-width", "border-style", "border-color", "shadows", "frame-paint"] as const;
+const MOTION_KEYS = ["enter", "enter-frames", "enter-easing", "enter-direction", "enter-amount", "enter-origin", "sustain", "exit", "exit-frames", "exit-easing", "exit-direction", "exit-amount", "exit-origin"] as const;
+
+export function decodeMediaFit(recipe: SvsRecipe): ContentFit {
+  return decodeContentFitProperties(recipe.properties, `Media Recipe ${recipe.path}`);
+}
+
+function occupancy(recipe: SvsRecipe): MediaVisualOccupancy {
+  switch (oneOf(recipe, "playback", ["once-start", "once-end", "hold-start", "hold-end", "loop-start", "loop-end", "stretch"] as const, "once-start")) {
+    case "once-start": return { mode: "once", align: "start" };
+    case "once-end": return { mode: "once", align: "end" };
+    case "hold-start": return { mode: "hold", align: "start" };
+    case "hold-end": return { mode: "hold", align: "end" };
+    case "loop-start": return { mode: "loop", align: "start" };
+    case "loop-end": return { mode: "loop", align: "end" };
+    case "stretch": return { mode: "stretch" };
+  }
+}
+
+function trim(recipe: SvsRecipe): MediaVisualTrim | undefined {
+  const startFrame = optionalNumber(recipe, "trim-start");
+  const endFrameExclusive = optionalNumber(recipe, "trim-end");
+  if (startFrame === undefined && endFrameExclusive === undefined) return undefined;
+  if (
+    startFrame === undefined
+    || endFrameExclusive === undefined
+    || !Number.isSafeInteger(startFrame)
+    || !Number.isSafeInteger(endFrameExclusive)
+  ) {
+    fail(recipe, "trim-start and trim-end must both be integer frames.");
+  }
+  return { startFrame, endFrameExclusive };
+}
+
+export function decodeMediaSampleSpec(
+  recipe: SvsRecipe,
+  id: string,
+  sourceKind: "still" | "timed" | "surface",
+  samplingMotion?: MediaSampleLayerSpec["samplingMotion"],
+  combinedItemAppearance = false,
+): MediaSampleLayerSpec {
+  assertKeys(recipe, [...FIT_KEYS, ...SAMPLE_KEYS, ...(combinedItemAppearance ? FRAME_KEYS : [])]);
+  const hasTimedProperties = recipe.properties.playback !== undefined
+    || recipe.properties["trim-start"] !== undefined
+    || recipe.properties["trim-end"] !== undefined;
+  if (sourceKind === "still" && hasTimedProperties) {
+    fail(recipe, "cannot apply playback or trim to durationless still material.");
+  }
+  const timed = sourceKind === "timed" || (sourceKind === "surface" && hasTimedProperties);
+  const sourceTrim = timed ? trim(recipe) : undefined;
+  return sealMediaSampleLayerSpec({
+
+    id,
+    ...(timed ? { occupancy: occupancy(recipe), ...(sourceTrim === undefined ? {} : { trim: sourceTrim }) } : {}),
+    appearance: decodeMediaSampleAppearance(recipe),
+    ...(samplingMotion === undefined ? {} : { samplingMotion }),
+  });
+}
+
+/** Decode visual-only sample styling without choosing playback or source trim. */
+export function decodeMediaSampleAppearance(recipe: SvsRecipe): MediaSampleAppearance {
+  return {
+    opacity: number(recipe, "opacity", 1),
+    filter: {
+      blurPx: number(recipe, "blur", 0), brightness: number(recipe, "brightness", 1),
+      contrast: number(recipe, "contrast", 1), saturation: number(recipe, "saturation", 1),
+    },
+  };
+}
+
+function edge(recipe: SvsRecipe, prefix: "enter" | "exit"): MediaLifecycleMotion["enter"] {
+  const operator = optionalString(recipe, prefix);
+  if (operator === undefined || operator === "none") return undefined;
+  const allowed = ["fade", "slide", "scale", "pop", "bounce", "blur-reveal", "wipe", "flip", "spin"] as const;
+  if (!allowed.includes(operator as typeof allowed[number])) fail(recipe, `${prefix} operator is invalid.`);
+  const direction = optionalString(recipe, `${prefix}-direction`);
+  const origin = optionalString(recipe, `${prefix}-origin`);
+  return {
+    operator: operator as typeof allowed[number],
+    durationFrames: number(recipe, `${prefix}-frames`),
+    easing: oneOf(recipe, `${prefix}-easing`, ["linear", "ease-in", "ease-out", "ease-in-out"] as const, "ease-in-out"),
+    ...(direction === undefined ? {} : { direction: oneOf(recipe, `${prefix}-direction`, ["left", "right", "up", "down"] as const) }),
+    ...(origin === undefined ? {} : { origin: oneOf(recipe, `${prefix}-origin`, ["outside-canvas"] as const) }),
+    ...(optionalNumber(recipe, `${prefix}-amount`) === undefined ? {} : { amount: number(recipe, `${prefix}-amount`) }),
+  };
+}
+
+function sustain(recipe: SvsRecipe): MediaLifecycleMotion["sustain"] {
+  const source = optionalString(recipe, "sustain");
+  if (source === undefined || source === "none") return [];
+  return source.split(",").map((entry) => {
+    const match = /^(float|breathe|pulse|wobble|shake|drift)\s+([-+]?\d+(?:\.\d+)?)\s+([1-9]\d*)(?:\s+(left|right|up|down))?$/u.exec(entry.trim());
+    if (match === null) fail(recipe, "sustain entries require operator amount cycles [direction].");
+    return {
+      operator: match[1] as MediaLifecycleMotion["sustain"][number]["operator"],
+      amount: Number(match[2]), cycles: Number(match[3]),
+      ...(match[4] === undefined ? {} : { direction: match[4] as "left" | "right" | "up" | "down" }),
+    };
+  });
+}
+
+export function decodeMediaMotion(recipe: SvsRecipe | undefined): MediaLifecycleMotion {
+  if (recipe === undefined) return { sustain: [] };
+  assertKeys(recipe, MOTION_KEYS);
+  const enter = edge(recipe, "enter");
+  const exit = edge(recipe, "exit");
+  return {
+    ...(enter === undefined ? {} : { enter }),
+    sustain: sustain(recipe),
+    ...(exit === undefined ? {} : { exit }),
+  };
+}
+
+export function decodeMediaPresentation(recipe: SvsRecipe): MediaFramePresentation {
+  const clip = oneOf(recipe, "clip", ["none", "frame", "rounded"] as const, "frame");
+  const borderWidth = number(recipe, "border-width", 0);
+  return {
+    clip: clip === "rounded" ? { kind: "rounded", radiusPx: number(recipe, "radius", 0) } : { kind: clip },
+    padding: padding(recipe),
+    ...(borderWidth === 0 ? {} : { border: {
+      widthPx: borderWidth,
+      style: oneOf(recipe, "border-style", ["solid", "dashed", "dotted"] as const, "solid"),
+      color: string(recipe, "border-color"),
+    } }),
+    shadows: shadows(recipe),
+  };
+}
+
+export function decodeMediaItemSpec(
+  recipe: SvsRecipe,
+  input: Pick<MediaItemSpec, "id"> & {
+    readonly motion: MediaLifecycleMotion;
+    readonly sourceAudio?: MediaItemSpec["sourceAudio"];
+  },
+): MediaItemSpec {
+  assertKeys(recipe, [...FIT_KEYS, ...SAMPLE_KEYS, ...FRAME_KEYS]);
+  return sealMediaItemSpec({
+
+    id: input.id,
+    presentation: decodeMediaPresentation(recipe),
+    motion: input.motion,
+    stackingOrder: number(recipe, "stack-order"),
+    ...(input.sourceAudio === undefined ? {} : { sourceAudio: input.sourceAudio }),
+  });
+}
+
+export function decodeMediaFramePaint(recipe: SvsRecipe, id: string): MediaPaintLayerSpec | undefined {
+  const source = optionalString(recipe, "frame-paint");
+  if (source === undefined || source === "transparent") return undefined;
+  const adapted: SvsRecipe = { ...recipe, properties: { paint: source } };
+  return sealMediaPaintLayerSpec({ id, paint: paint(adapted), opacity: 1 });
+}
+
+export function decodeMediaPaintSpec(recipe: SvsRecipe, id: string): MediaPaintLayerSpec {
+  assertKeys(recipe, ["paint", "opacity"]);
+  return sealMediaPaintLayerSpec({
+    id, paint: paint(recipe), opacity: number(recipe, "opacity", 1),
+  });
+}
+
+export function decodeMediaHandoffSpec(
+  recipe: SvsRecipe,
+  id: string,
+  fromMemberId: string,
+  toMemberId: string,
+): MediaHandoffSpec {
+  assertKeys(recipe, ["operator", "duration-frames", "boundary-ratio", "direction", "audio"]);
+  const operator = oneOf(recipe, "operator", ["cut", "crossfade", "push", "wipe", "cover", "page-turn"] as const);
+  const direction = optionalString(recipe, "direction");
+  return sealMediaHandoffSpec({
+    id, fromMemberId, toMemberId, operator,
+    durationFrames: number(recipe, "duration-frames"),
+    boundaryRatio: number(recipe, "boundary-ratio", 0.5),
+    ...(direction === undefined ? {} : { direction: oneOf(recipe, "direction", ["left", "right", "up", "down"] as const) }),
+    audio: oneOf(recipe, "audio", ["cut", "crossfade"] as const, "cut"),
+  });
+}
+
+export function decodeMediaSequenceSpec(
+  recipe: SvsRecipe,
+  id: string,
+  motion: MediaLifecycleMotion,
+  handoffs: readonly MediaHandoffSpec[],
+): MediaSequenceSpec {
+  assertKeys(recipe, [...FIT_KEYS, ...SAMPLE_KEYS, ...FRAME_KEYS]);
+  return sealMediaSequenceSpec({
+    id,
+    presentation: decodeMediaPresentation(recipe), motion,
+    stackingOrder: number(recipe, "stack-order"), handoffs,
+  });
+}
+
+export const mediaAppearanceKeys = { fit: FIT_KEYS, sample: SAMPLE_KEYS, frame: FRAME_KEYS, motion: MOTION_KEYS } as const;