@hypit/hypit 0.0.1 → 0.1.1

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

@@ -0,0 +1,367 @@
+import {
+  assertFontArtifactRef,
+} from "@hypit/media";
+import {
+  assertMediaFramePresentation,
+  assertMediaLayerSet,
+  assertMediaLifecycleMotion,
+} from "@hypit/media-track";
+import {
+  assertProgramSpaceIdentity,
+  programSpaceFrameCount,
+} from "@hypit/program-space";
+import type { ProgramSpace } from "@hypit/program-space";
+import { canonicalize } from "@hypit/protocol";
+import { verifyText } from "@hypit/text";
+import type { Text } from "@hypit/text";
+import { assertSpatialFrame } from "@hypit/spatial";
+import type { SpatialFrame } from "@hypit/spatial";
+import { assertTemporalInstantFor } from "@hypit/temporal";
+import type { TemporalInstant } from "@hypit/temporal";
+
+import type {
+  DeckCardTone,
+  DepthStackCardLabel,
+  DepthStackCardLabelStyle,
+  DepthStackCardSet,
+  DepthStackCardSpec,
+  DepthStackHeader,
+  DepthStackPose,
+  DepthStackPoseStep,
+  DepthStackProgram,
+  DepthStackSpec,
+  DepthStackState,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function identity(value: string, label: string): void {
+  assert(/^[A-Za-z][A-Za-z0-9_.:#-]{0,191}$/u.test(value), `${label} is invalid.`);
+}
+
+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 positive(value: number, label: string): void {
+  finite(value, label);
+  assert(value > 0, `${label} must be positive.`);
+}
+
+function assertTone(value: DeckCardTone, label: string): void {
+  positive(value.brightness, `${label}.brightness`);
+  positive(value.contrast, `${label}.contrast`);
+  positive(value.saturation, `${label}.saturation`);
+}
+
+function assertPose(value: DepthStackPose, label: string): void {
+  finite(value.xPx, `${label}.xPx`);
+  finite(value.yPx, `${label}.yPx`);
+  positive(value.scale, `${label}.scale`);
+  finite(value.rotationDeg, `${label}.rotationDeg`);
+  unit(value.opacity, `${label}.opacity`);
+  assert(Number.isSafeInteger(value.stacking), `${label}.stacking must be an integer.`);
+  assertTone(value.tone, `${label}.tone`);
+}
+
+function assertPoseStep(value: DepthStackPoseStep, label: string): void {
+  finite(value.xPerDepthPx, `${label}.xPerDepthPx`);
+  finite(value.yPerDepthPx, `${label}.yPerDepthPx`);
+  positive(value.scalePerDepth, `${label}.scalePerDepth`);
+  finite(value.rotationPerDepthDeg, `${label}.rotationPerDepthDeg`);
+  assert(value.rotationMode === "linear" || value.rotationMode === "alternate", `${label}.rotationMode is invalid.`);
+  unit(value.opacityPerDepth, `${label}.opacityPerDepth`);
+  assert(Number.isSafeInteger(value.stackingPerDepth), `${label}.stackingPerDepth must be an integer.`);
+  assertTone(value.tonePerDepth, `${label}.tonePerDepth`);
+}
+
+export function assertDepthStackSpec(value: DepthStackSpec): void {
+  for (const [name, count] of Object.entries(value.visibility)) {
+    if (name === "wrap") continue;
+    assert(Number.isSafeInteger(count) && typeof count === "number" && count >= 0 && count <= 1_000,
+      `DepthStackSpec.visibility.${name} is invalid.`);
+  }
+  assert(typeof value.visibility.wrap === "boolean", "DepthStackSpec.visibility.wrap is invalid.");
+  assertPose(value.poses.current, "DepthStackSpec.poses.current");
+  assertPoseStep(value.poses.previous, "DepthStackSpec.poses.previous");
+  assertPoseStep(value.poses.next, "DepthStackSpec.poses.next");
+  assert(Number.isSafeInteger(value.reflow.durationFrames) && value.reflow.durationFrames >= 0,
+    "DepthStackSpec.reflow.durationFrames must be a non-negative integer.");
+  assert(["linear", "ease-in", "ease-out", "ease-in-out"].includes(value.reflow.easing),
+    "DepthStackSpec.reflow.easing is invalid.");
+  assertMediaFramePresentation(value.presentation, "DepthStackSpec.presentation");
+  assert(Number.isSafeInteger(value.stackingOrder), "DepthStackSpec.stackingOrder must be an integer.");
+}
+
+export function sealDepthStackSpec(value: DepthStackSpec): DepthStackSpec {
+  assertDepthStackSpec(value);
+  return canonicalize(value) as unknown as DepthStackSpec;
+}
+
+export function assertDepthStackCardLabel(value: DepthStackCardLabel): void {
+  if (value.kind === "none") return;
+  assert(value.kind === "text", "DepthStackCardLabel kind is invalid.");
+  assert(value.document.paragraphs.length > 0, "DepthStackCardLabel document is empty.");
+  const fonts = value.typography.fonts;
+  assert(fonts !== undefined && fonts.length > 0,
+    "DepthStackCardLabel requires exact font Artifacts.");
+  for (const [index, font] of fonts.entries()) assertFontArtifactRef(font, `DepthStackCardLabel.fonts.${index}`);
+  assert(value.typography.synthesis === "none", "DepthStackCardLabel cannot synthesize an exact font.");
+  assert(value.flow.form.kind === "area", "DepthStackCardLabel uses Area flow inside its Card.");
+}
+
+export function sealDepthStackCardLabel(value: DepthStackCardLabel): DepthStackCardLabel {
+  assertDepthStackCardLabel(value);
+  return canonicalize(value) as unknown as DepthStackCardLabel;
+}
+
+export function assertDepthStackCardLabelStyle(value: DepthStackCardLabelStyle): void {
+  assert(value.typography.fonts.length > 0, "DepthStackCardLabelStyle requires exact fonts.");
+  value.typography.fonts.forEach((font, index) => assertFontArtifactRef(font, `DepthStackCardLabelStyle.fonts.${index}`));
+  assert(value.typography.synthesis === "none", "DepthStackCardLabelStyle cannot synthesize an exact font.");
+  assert(value.flow.form.kind === "area", "DepthStackCardLabelStyle uses Area flow inside its Card.");
+}
+
+export function sealDepthStackCardLabelStyle(value: DepthStackCardLabelStyle): DepthStackCardLabelStyle {
+  assertDepthStackCardLabelStyle(value);
+  return canonicalize(value) as unknown as DepthStackCardLabelStyle;
+}
+
+export function bindDepthStackCardLabelText(style: DepthStackCardLabelStyle, content: Text): DepthStackCardLabel {
+  assertDepthStackCardLabelStyle(style);
+  verifyText(content);
+  assert(content.value.trim().length > 0, "DepthStack Card label Text is empty.");
+  return sealDepthStackCardLabel({
+
+    kind: "text",
+    document: { paragraphs: [{ id: "label:paragraph", inlines: [{ kind: "text", id: "label:text", text: content.value }] }] },
+    typography: structuredClone(style.typography),
+    paints: structuredClone(style.paints),
+    flow: structuredClone(style.flow),
+  });
+}
+
+export const noDepthStackCardLabel = (): DepthStackCardLabel => ({
+
+  kind: "none",
+});
+
+export function assertDepthStackCardSpec(value: DepthStackCardSpec): void {
+  identity(value.id, "DepthStackCardSpec.id");
+  assert(value.playback.future === "hold-head" || value.playback.future === "continue",
+    "DepthStackCardSpec.playback.future is invalid.");
+  assert(["hold-tail", "continue", "hide"].includes(value.playback.past),
+    "DepthStackCardSpec.playback.past is invalid.");
+}
+
+export function sealDepthStackCardSpec(value: DepthStackCardSpec): DepthStackCardSpec {
+  assertDepthStackCardSpec(value);
+  return canonicalize(value) as unknown as DepthStackCardSpec;
+}
+
+export function assertDepthStackHeader(value: DepthStackHeader): void {
+  identity(value.id, "DepthStackHeader.id");
+}
+
+export function sealDepthStackHeader(value: DepthStackHeader): DepthStackHeader {
+  assertDepthStackHeader(value);
+  return canonicalize(value) as unknown as DepthStackHeader;
+}
+
+export function createDepthStackCardSet(): DepthStackCardSet {
+  return { cards: [] };
+}
+
+export function assertDepthStackCardSet(value: DepthStackCardSet): void {
+  assert(Array.isArray(value.cards),
+    "DepthStackCardSet is invalid.");
+  const ids = new Set<string>();
+  let previous = -1;
+  for (const card of value.cards) {
+    identity(card.id, "DepthStack Card id");
+    assert(!ids.has(card.id), `DepthStackCardSet repeats ${card.id}.`);
+    ids.add(card.id);
+    assert(Number.isSafeInteger(card.activationFrame) && card.activationFrame >= 0,
+      `DepthStack Card ${card.id} activation is invalid.`);
+    assert(card.activationFrame > previous, "DepthStack Card triggers must be strictly increasing in authored order.");
+    previous = card.activationFrame;
+    assertMediaLayerSet(card.material);
+    assert(card.material.layers.length > 0, `DepthStack Card ${card.id} material is empty.`);
+    assertDepthStackCardLabel(card.label);
+    assertDepthStackCardSpec({ id: card.id, playback: card.playback });
+  }
+}
+
+function appendDepthStackCardAtFrame(
+  set: DepthStackCardSet,
+  material: DepthStackCardSet["cards"][number]["material"],
+  label: DepthStackCardLabel,
+  spec: DepthStackCardSpec,
+  activationFrame: number,
+): DepthStackCardSet {
+  assertDepthStackCardSet(set);
+  assertMediaLayerSet(material);
+  assert(material.layers.length > 0, `DepthStack Card ${spec.id} material is empty.`);
+  assertDepthStackCardLabel(label);
+  assertDepthStackCardSpec(spec);
+  assert(Number.isSafeInteger(activationFrame) && activationFrame >= 0,
+    `DepthStack Card ${spec.id} activation is invalid.`);
+  const result: DepthStackCardSet = {
+
+    cards: [...set.cards, {
+      id: spec.id,
+      activationFrame,
+      material: structuredClone(material),
+      label: structuredClone(label),
+      playback: { ...spec.playback },
+    }],
+  };
+  assertDepthStackCardSet(result);
+  return canonicalize(result) as unknown as DepthStackCardSet;
+}
+
+export function appendDepthStackCard(
+  set: DepthStackCardSet,
+  space: ProgramSpace,
+  material: DepthStackCardSet["cards"][number]["material"],
+  label: DepthStackCardLabel,
+  spec: DepthStackCardSpec,
+  activation: TemporalInstant,
+): DepthStackCardSet {
+  assertTemporalInstantFor(activation, { subjectId: spec.id, space });
+  return appendDepthStackCardAtFrame(set, material, label, spec, activation.frame);
+}
+
+function finalizeDepthStackAtFrame(
+  set: DepthStackCardSet,
+  header: DepthStackHeader,
+  frame: SpatialFrame,
+  spec: DepthStackSpec,
+  terminalFrame: number,
+  space: ProgramSpace,
+): DepthStackProgram {
+  assertDepthStackCardSet(set);
+  assertDepthStackHeader(header);
+  assertSpatialFrame(frame);
+  assertDepthStackSpec(spec);
+  assertProgramSpaceIdentity(space);
+  assert(set.cards.length > 0, "DepthStack requires at least one Card.");
+  const first = set.cards[0]!;
+  const program: DepthStackProgram = {
+
+    id: header.id,
+    span: { startFrame: first.activationFrame, endFrameExclusive: terminalFrame },
+    terminalFrame,
+    frame: structuredClone(frame),
+    spec: structuredClone(spec),
+    cards: structuredClone(set.cards),
+  };
+  assertDepthStackProgramIdentity(program, space);
+  return canonicalize(program) as unknown as DepthStackProgram;
+}
+
+export function finalizeDepthStack(
+  set: DepthStackCardSet,
+  header: DepthStackHeader,
+  frame: SpatialFrame,
+  spec: DepthStackSpec,
+  terminal: TemporalInstant,
+  space: ProgramSpace,
+): DepthStackProgram {
+  assertTemporalInstantFor(terminal, { subjectId: header.id, space });
+  return finalizeDepthStackAtFrame(set, header, frame, spec, terminal.frame, space);
+}
+
+export function assertDepthStackProgram(program: DepthStackProgram): void {
+  identity(program.id, "DepthStackProgram.id");
+  assertSpatialFrame(program.frame);
+  assertDepthStackSpec(program.spec);
+  const set = { cards: program.cards } as const;
+  assertDepthStackCardSet(set);
+  assert(program.cards.length > 0, "DepthStackProgram has no Cards.");
+  assert(Number.isSafeInteger(program.terminalFrame) && program.terminalFrame > 0,
+    "DepthStack terminal is invalid.");
+  assert(program.span.startFrame === program.cards[0]!.activationFrame
+    && program.span.endFrameExclusive === program.terminalFrame,
+  "DepthStackProgram span disagrees with its Card triggers and terminal.");
+  assert(program.cards.at(-1)!.activationFrame < program.terminalFrame,
+    "DepthStack terminal must be after every Card trigger.");
+  if (program.spec.visibility.wrap) {
+    assert(program.spec.visibility.previous + program.spec.visibility.next + 1 <= program.cards.length,
+      "Wrapped DepthStack visibility would show one Card at several relative depths.");
+  }
+  const duration = program.terminalFrame - program.cards[0]!.activationFrame;
+  assertMediaLifecycleMotion(program.spec.motion, duration, "DepthStack whole-group motion");
+  for (let index = 1; index < program.cards.length; index += 1) {
+    const stageEnd = program.cards[index + 1]?.activationFrame ?? program.terminalFrame;
+    const stageDuration = stageEnd - program.cards[index]!.activationFrame;
+    assert(program.spec.reflow.durationFrames <= stageDuration,
+      `DepthStack reflow exceeds Card ${program.cards[index]!.id} stage.`);
+  }
+}
+
+export function assertDepthStackProgramIdentity(program: DepthStackProgram, space: ProgramSpace): void {
+  assertProgramSpaceIdentity(space);
+  assertDepthStackProgram(program);
+  assert(program.terminalFrame <= programSpaceFrameCount(space), "DepthStack terminal is outside ProgramSpace.");
+}
+
+function modulo(value: number, size: number): number {
+  return ((value % size) + size) % size;
+}
+
+/** Resolve one immutable collection state; no renderer or previous-frame memory participates. */
+export function resolveDepthStackState(program: DepthStackProgram, currentIndex: number): DepthStackState {
+  assert(Number.isSafeInteger(currentIndex) && currentIndex >= 0 && currentIndex < program.cards.length,
+    "DepthStack current index is invalid.");
+  const state = new Map<number, number>([[currentIndex, 0]]);
+  const add = (rawIndex: number, depth: number): void => {
+    const index = program.spec.visibility.wrap ? modulo(rawIndex, program.cards.length) : rawIndex;
+    if (index < 0 || index >= program.cards.length) return;
+    if (depth < 0 && program.cards[index]!.playback.past === "hide") return;
+    assert(!state.has(index), `DepthStack Card ${program.cards[index]!.id} occupies several relative depths.`);
+    state.set(index, depth);
+  };
+  for (let depth = 1; depth <= program.spec.visibility.previous; depth += 1) add(currentIndex - depth, -depth);
+  for (let depth = 1; depth <= program.spec.visibility.next; depth += 1) add(currentIndex + depth, depth);
+  return state;
+}
+
+function power(value: number, exponent: number): number {
+  return Math.round((value ** exponent) * 1_000_000) / 1_000_000;
+}
+
+function clean(value: number): number {
+  const rounded = Math.round(value * 1_000_000) / 1_000_000;
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+export function resolveDepthStackPose(spec: DepthStackSpec, relativeDepth: number): DepthStackPose {
+  assertDepthStackSpec(spec);
+  assert(Number.isSafeInteger(relativeDepth), "DepthStack relative depth must be an integer.");
+  if (relativeDepth === 0) return structuredClone(spec.poses.current);
+  const magnitude = Math.abs(relativeDepth);
+  const step = relativeDepth < 0 ? spec.poses.previous : spec.poses.next;
+  const rotationFactor = step.rotationMode === "linear" ? magnitude : magnitude % 2 === 1 ? 1 : -1;
+  const current = spec.poses.current;
+  return {
+    xPx: clean(current.xPx + (step.xPerDepthPx * magnitude)),
+    yPx: clean(current.yPx + (step.yPerDepthPx * magnitude)),
+    scale: clean(current.scale * power(step.scalePerDepth, magnitude)),
+    rotationDeg: clean(current.rotationDeg + (step.rotationPerDepthDeg * rotationFactor)),
+    opacity: clean(current.opacity * power(step.opacityPerDepth, magnitude)),
+    stacking: current.stacking + (step.stackingPerDepth * magnitude),
+    tone: {
+      brightness: clean(current.tone.brightness * power(step.tonePerDepth.brightness, magnitude)),
+      contrast: clean(current.tone.contrast * power(step.tonePerDepth.contrast, magnitude)),
+      saturation: clean(current.tone.saturation * power(step.tonePerDepth.saturation, magnitude)),
+    },
+  };
+}

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

@@ -0,0 +1,286 @@
+import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { artifactTypes } from "@hypit/artifact";
+import { mediaTypes } from "@hypit/media";
+import type { FontStackRef } from "@hypit/media";
+import { mediaTrackTypes } from "@hypit/media-track";
+import type { TypeRef } from "@hypit/protocol";
+import { spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import { createTemporalInstantProjection, temporalInstantAttributeNames } from "@hypit/temporal-markup";
+import type { SvsRecipe } from "@hypit/svs";
+import { sealText, textTypes } from "@hypit/text";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { AuthorValueRef } from "@hypit/elaborator";
+import type {
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceComponentDraft,
+  SurfaceRecordDraft,
+  SurfaceResolvedReference,
+  MarkupAttributeValue,
+} from "@hypit/markup";
+
+import {
+  decodeDepthStackCardSpec,
+  decodeDepthStackMaterial,
+  decodeDepthStackSpec,
+} from "./author.js";
+import {
+  createDepthStackFragment,
+} from "./fragment.js";
+import type { DepthStackFragmentCard } from "./fragment.js";
+import { depthStackProducers, depthStackTypes } from "./manifest.js";
+import {
+  noDepthStackCardLabel,
+  sealDepthStackCardLabelStyle,
+  sealDepthStackHeader,
+} from "./program.js";
+import type { DepthStackCardLabelStyle } from "./types.js";
+
+function sameType(left: TypeRef, right: TypeRef): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function allowed(element: StructuredElement, names: readonly string[]): void {
+  const permit = new Set(names);
+  const unknown = Object.keys(element.attributes).filter((name) => !permit.has(name));
+  if (unknown.length > 0) throw new Error(`${element.name} has unsupported attributes ${unknown.join(", ")}.`);
+}
+
+function empty(element: StructuredElement): void {
+  if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
+    throw new Error(`${element.name} must be empty.`);
+  }
+}
+
+function text(element: StructuredElement, name: string, fallback?: string): string {
+  const value = element.attributes[name];
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+  return value.trim();
+}
+
+function optionalText(element: StructuredElement, name: string): string | undefined {
+  const value = element.attributes[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be text.`);
+  return value.trim();
+}
+
+function numeric(element: StructuredElement, name: string, fallback: number): number {
+  const raw = optionalText(element, name);
+  if (raw === undefined) return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be numeric.`);
+  return value;
+}
+
+function reference(
+  raw: MarkupAttributeValue | undefined,
+  label: string,
+  expected: TypeRef,
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+  const value = resolve(raw.path);
+  if (value === undefined || !sameType(value.type, expected)) throw new Error(`${label} has the wrong Type.`);
+  return value;
+}
+
+function oneOfReference(
+  raw: MarkupAttributeValue | undefined,
+  label: string,
+  expected: readonly TypeRef[],
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${label} must be a reference.`);
+  const value = resolve(raw.path);
+  if (value === undefined || !expected.some((type) => sameType(value.type, type))) throw new Error(`${label} has the wrong Type.`);
+  return value;
+}
+
+function inline<T>(value: SurfaceResolvedReference, label: string): T {
+  if (value.record?.value.kind !== "inline") throw new Error(`${label} must resolve during author compilation.`);
+  return value.record.value.value as unknown as T;
+}
+
+function recipe(
+  raw: MarkupAttributeValue | undefined,
+  label: string,
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SvsRecipe {
+  return inline<SvsRecipe>(reference(raw, label, svsRecipeType, resolve), label);
+}
+
+function labelText(element: StructuredElement): string {
+  if (element.children.some((child) => child.kind === "element")) throw new Error(`${element.name} accepts plain label text only.`);
+  const value = element.children.map((child) => child.kind === "text" ? child.value : "").join("").trim();
+  if (value.length === 0) throw new Error(`${element.name} label text is empty.`);
+  return value;
+}
+
+function labelFragment(id: string) {
+  const input = (name: string) => ({ kind: "fragment-input" as const, name });
+  const operation = { kind: "fragment-operation" as const, operation: "bind" };
+  return sealGraphFragment({
+    inputs: [{ name: "style", type: depthStackTypes.cardLabelStyle }, { name: "content", type: textTypes.text }],
+    operations: [{
+      id: "bind", producer: depthStackProducers.bindLabelText,
+      inputs: { style: input("style"), content: input("content") }, result: { kind: "output", name: "label" },
+    }],
+    exports: [{ name: "label", type: depthStackTypes.cardLabel, root: operation }],
+  });
+}
+
+export const decodeDepthStackLabelSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  allowed(element, ["id", "content", "font", "size", "color", "align", "block", "padding"]);
+  const id = text(element, "id");
+  const stack = inline<FontStackRef>(reference(element.attributes.font, `${element.name}.font`, mediaTypes.fontStack, resolveReference), `${element.name}.font`);
+  const primary = stack.faces[0];
+  if (primary === undefined) throw new Error(`${element.name}.font stack is empty.`);
+  const align = text(element, "align", "center");
+  const block = text(element, "block", "end");
+  if (!["start", "center", "end", "justify"].includes(align)) throw new Error(`${element.name}.align is invalid.`);
+  if (!["start", "center", "end"].includes(block)) throw new Error(`${element.name}.block is invalid.`);
+  const padding = numeric(element, "padding", 20);
+  const style: DepthStackCardLabelStyle = sealDepthStackCardLabelStyle({
+
+    typography: {
+      fonts: structuredClone(stack.faces), sizePx: numeric(element, "size", 34), weight: primary.weight, style: primary.style,
+      axes: [], features: [], synthesis: "none", kerning: "normal", trackingPx: 0, wordSpacingPx: 0,
+      lineHeight: 1.15, direction: "auto", writingMode: "horizontal-tb", baselineShiftPx: 0, tabSize: 4,
+      indentationPx: 0, paragraphBeforePx: 0, paragraphAfterPx: 0, transform: "none", variantCaps: "normal",
+      verticalAlign: "baseline", decorations: [], cjk: { textSpacing: "normal", punctuationTrim: "none" },
+    },
+    paints: [{ kind: "fill", paint: { kind: "solid", color: text(element, "color", "#ffffff") } }],
+    flow: {
+      form: { kind: "area" }, inlineSize: "fixed", blockSize: "fixed",
+      paddingPx: { inlineStart: padding, inlineEnd: padding, blockStart: padding, blockEnd: padding },
+      inlineAlign: align as "start" | "center" | "end" | "justify",
+      blockAlign: block as "start" | "center" | "end",
+      wrap: "word", overflow: "clip", clipToFrame: true, columns: 1, columnGapPx: 0, metricEdge: "line-box",
+    },
+  });
+  const styleId = `${id}.__style`;
+  const records: SurfaceRecordDraft[] = [{ id: styleId, type: depthStackTypes.cardLabelStyle, value: { kind: "inline", value: style }, range: element.range }];
+  let contentRef: AuthorValueRef;
+  if (element.attributes.content === undefined) {
+    const contentId = `${id}.__content`;
+    records.push({ id: contentId, type: textTypes.text, value: { kind: "inline", value: sealText(labelText(element)) }, range: element.range });
+    contentRef = { kind: "record", id: contentId };
+  } else {
+    empty(element);
+    contentRef = reference(element.attributes.content, `${element.name}.content`, textTypes.text, resolveReference).ref;
+  }
+  const fragment = labelFragment(id);
+  return {
+    records,
+    components: [{ id, fragment: fragment.id, inputs: { style: { kind: "record", id: styleId }, content: contentRef }, outputs: { label: id }, range: element.range }],
+    fragments: [fragment],
+  };
+};
+
+export const decodeDepthStackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  allowed(element, ["id", "semantic", "space", "canvas", "frame", "appearance", "until", "until-boundary"]);
+  const id = text(element, "id");
+  const context = resolveTemporalContext({ element, resolveReference });
+  const time = createTemporalSpace({ id: id, element, ...context });
+  const canvas = reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference);
+  const frame = reference(element.attributes.frame, `${element.name}.frame`, spatialTypes.frame, resolveReference);
+  const appearance = recipe(element.attributes.appearance, `${element.name}.appearance`, resolveReference);
+  const terminal = createTemporalInstantProjection({
+    id: `${id}.terminal`, subjectId: id, element, ...context, space: time.space, resolveReference,
+    semanticAttribute: "until", boundaryAttribute: "until-boundary", boundaryFallback: "end", projectedAttribute: false,
+  });
+  const records: SurfaceRecordDraft[] = [...terminal.records];
+  const temporalComponents: SurfaceComponentDraft[] = [...time.components, ...terminal.components];
+  const temporalFragments = [...time.fragments, ...terminal.fragments];
+  const headerId = `${id}.header`;
+  const specId = `${id}.spec`;
+  records.push(
+    { id: headerId, type: depthStackTypes.header, value: { kind: "inline", value: sealDepthStackHeader({ id }) }, range: element.range },
+    { id: specId, type: depthStackTypes.spec, value: { kind: "inline", value: decodeDepthStackSpec(appearance) }, range: element.range },
+  );
+  const inputs: Record<string, typeof time.space.ref> = {
+    canvas: canvas.ref, frame: frame.ref, header: { kind: "record", id: headerId }, space: time.space.ref,
+    spec: { kind: "record", id: specId }, terminal: terminal.ref,
+  };
+  const cards: DepthStackFragmentCard[] = [];
+  let cardIndex = 0;
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim().length > 0) throw new Error(`${element.name} accepts Card children only.`);
+      continue;
+    }
+    if (child.name.split(":").at(-1) !== "Card") throw new Error(`${element.name} accepts Card children only.`);
+    allowed(child, ["id", "source", "extent", ...temporalInstantAttributeNames, "appearance", "label"]);
+    empty(child);
+    cardIndex += 1;
+    const suffix = String(cardIndex).padStart(4, "0");
+    const cardId = text(child, "id");
+    const source = oneOfReference(child.attributes.source, `${child.name}.source`, [artifactTypes.blob, mediaTypes.synchronized, mediaTypes.compositableSurface], resolveReference);
+    const sourceKind = sameType(source.type, artifactTypes.blob) ? "still"
+      : sameType(source.type, mediaTypes.synchronized) ? "timed" : "surface";
+    const extent = child.attributes.extent === undefined ? undefined
+      : reference(child.attributes.extent, `${child.name}.extent`, spatialTypes.extent, resolveReference);
+    if (sourceKind === "still" && extent === undefined) throw new Error(`${child.name}.extent is required for a still image.`);
+    if (sourceKind !== "still" && extent !== undefined) throw new Error(`${child.name}.extent belongs only to a still image.`);
+    const activation = createTemporalInstantProjection({ id: `${id}.${cardId}`, subjectId: cardId, element: child, ...context, space: time.space, resolveReference });
+    records.push(...activation.records); temporalComponents.push(...activation.components); temporalFragments.push(...activation.fragments);
+    const cardAppearance = child.attributes.appearance === undefined
+      ? appearance : recipe(child.attributes.appearance, `${child.name}.appearance`, resolveReference);
+    const material = decodeDepthStackMaterial(cardAppearance, `${id}.${cardId}`, sourceKind);
+    const fitId = `${id}.card.${suffix}.fit`;
+    const sampleId = `${id}.card.${suffix}.sample-spec`;
+    const cardSpecId = `${id}.card.${suffix}.card-spec`;
+    records.push(
+      { id: fitId, type: spatialTypes.fit, value: { kind: "inline", value: material.fit }, range: child.range },
+      { id: sampleId, type: mediaTrackTypes.sampleLayerSpec, value: { kind: "inline", value: material.sample }, range: child.range },
+      { id: cardSpecId, type: depthStackTypes.cardSpec, value: { kind: "inline", value: decodeDepthStackCardSpec(cardAppearance, cardId) }, range: child.range },
+    );
+    const sourceName = `card-${suffix}-source`;
+    const fitName = `card-${suffix}-fit`;
+    const sampleSpecName = `card-${suffix}-sample-spec`;
+    const cardSpecName = `card-${suffix}-spec`;
+    const activationName = `card-${suffix}-activation`;
+    const labelName = `card-${suffix}-label`;
+    inputs[sourceName] = source.ref;
+    inputs[fitName] = { kind: "record", id: fitId };
+    inputs[sampleSpecName] = { kind: "record", id: sampleId };
+    inputs[cardSpecName] = { kind: "record", id: cardSpecId };
+    inputs[activationName] = activation.ref;
+    let labelRef: typeof time.space.ref;
+    if (child.attributes.label === undefined) {
+      const labelId = `${id}.card.${suffix}.label-none`;
+      records.push({ id: labelId, type: depthStackTypes.cardLabel, value: { kind: "inline", value: noDepthStackCardLabel() }, range: child.range });
+      labelRef = { kind: "record", id: labelId };
+    } else {
+      labelRef = reference(child.attributes.label, `${child.name}.label`, depthStackTypes.cardLabel, resolveReference).ref;
+    }
+    inputs[labelName] = labelRef;
+    let extentName: string | undefined;
+    if (extent !== undefined) {
+      extentName = `card-${suffix}-extent`;
+      inputs[extentName] = extent.ref;
+    }
+    let framePaintSpecName: string | undefined;
+    if (material.framePaint !== undefined) {
+      framePaintSpecName = `card-${suffix}-frame-paint`;
+      const paintId = `${id}.card.${suffix}.frame-paint`;
+      records.push({ id: paintId, type: mediaTrackTypes.paintLayerSpec, value: { kind: "inline", value: material.framePaint }, range: child.range });
+      inputs[framePaintSpecName] = { kind: "record", id: paintId };
+    }
+    cards.push({
+      suffix, sourceKind, sourceName, ...(extentName === undefined ? {} : { extentName }), fitName, sampleSpecName,
+      ...(framePaintSpecName === undefined ? {} : { framePaintSpecName }), labelName, cardSpecName, activationName,
+    });
+  }
+  if (cards.length === 0) throw new Error(`${element.name} requires at least one Card.`);
+  const fragment = createDepthStackFragment(cards, "terminal");
+  return {
+    records,
+    components: [...temporalComponents, { id, fragment: fragment.id, inputs, outputs: { program: `${id}.program`, track: `${id}.track` }, range: element.range }],
+    fragments: [...temporalFragments, fragment],
+    exports: [`${id}.program`, `${id}.track`],
+  };
+};