@hypit/hypit 0.0.1 → 0.1.0

package/packages/credential-store-os/runtime/windows-credential.ps1

@@ -0,0 +1,59 @@
+param(
+  [Parameter(Mandatory = $true)]
+  [ValidateSet("read", "write", "delete")]
+  [string]$Operation
+)
+
+$ErrorActionPreference = "Stop"
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+$request = [Console]::In.ReadToEnd() | ConvertFrom-Json
+$null = [Windows.Security.Credentials.PasswordVault, Windows.Security.Credentials, ContentType = WindowsRuntime]
+$null = [Windows.Security.Credentials.PasswordCredential, Windows.Security.Credentials, ContentType = WindowsRuntime]
+$vault = New-Object Windows.Security.Credentials.PasswordVault
+$notFound = -2147023728 # HRESULT_FROM_WIN32(ERROR_NOT_FOUND)
+
+function Find-Credential {
+  try {
+    return $vault.Retrieve([string]$request.service, [string]$request.account)
+  } catch {
+    if ($_.Exception.HResult -eq $notFound -or $_.Exception.InnerException.HResult -eq $notFound) {
+      return $null
+    }
+    throw
+  }
+}
+
+switch ($Operation) {
+  "read" {
+    $credential = Find-Credential
+    if ($null -eq $credential) {
+      @{ found = $false } | ConvertTo-Json -Compress
+      break
+    }
+    $credential.RetrievePassword()
+    $bytes = [System.Text.Encoding]::UTF8.GetBytes($credential.Password)
+    @{ found = $true; secret = [Convert]::ToBase64String($bytes) } | ConvertTo-Json -Compress
+  }
+  "write" {
+    $existing = Find-Credential
+    if ($null -ne $existing) { $vault.Remove($existing) }
+    $bytes = [Convert]::FromBase64String([string]$request.secret)
+    $secret = [System.Text.Encoding]::UTF8.GetString($bytes)
+    $credential = New-Object Windows.Security.Credentials.PasswordCredential(
+      [string]$request.service,
+      [string]$request.account,
+      $secret
+    )
+    $vault.Add($credential)
+    @{ ok = $true } | ConvertTo-Json -Compress
+  }
+  "delete" {
+    $credential = Find-Credential
+    if ($null -eq $credential) {
+      @{ deleted = $false } | ConvertTo-Json -Compress
+      break
+    }
+    $vault.Remove($credential)
+    @{ deleted = $true } | ConvertTo-Json -Compress
+  }
+}

package/packages/credential-store-os/src/activation.ts

@@ -0,0 +1,32 @@
+import {
+  createRuntimeCredentialStoreAdapterFacet,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+
+import { OsCredentialStore } from "./store.js";
+
+const osCredentialStoreRuntimeAdapter = createRuntimeCredentialStoreAdapterFacet({
+  use: "@hypit/credential-store-os",
+  validate(context) {
+    const config = runtimeConfigObject(context.config, "OS CredentialStore");
+    runtimeConfigExact(config, ["service"], "OS CredentialStore");
+    runtimeConfigString(config.service, "OS credential service");
+  },
+  open(context) {
+    const config = runtimeConfigObject(context.config, "OS CredentialStore");
+    runtimeConfigExact(config, ["service"], "OS CredentialStore");
+    return { value: new OsCredentialStore({
+      ...(runtimeConfigString(config.service, "OS credential service") === undefined
+        ? {} : { service: config.service as string }),
+    }) };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [osCredentialStoreRuntimeAdapter],
+};
+
+export default hypitPackage;

package/packages/credential-store-os/src/index.ts

@@ -0,0 +1,2 @@
+export { OsCredentialStore, osCredentialStoreModuleRef } from "./store.js";
+export type { OsCredentialDeleter, OsCredentialReader, OsCredentialWriter } from "./store.js";

package/packages/credential-store-os/src/store.ts

@@ -0,0 +1,196 @@
+import { execFile, spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { verifyCredentialRef } from "@hypit/runtime";
+import type {
+  CredentialRef,
+  CredentialValue,
+  WritableCredentialStore,
+} from "@hypit/runtime";
+
+export const osCredentialStoreModuleRef = {
+  name: "@hypit/credential-store-os",
+  version: "1",
+} as const;
+
+export type OsCredentialReader = (service: string, account: string) => Promise<string | undefined>;
+export type OsCredentialWriter = (service: string, account: string, secret: string) => Promise<void>;
+export type OsCredentialDeleter = (service: string, account: string) => Promise<boolean>;
+
+const DEFAULT_SERVICE = "hypit";
+
+function macosReader(service: string): OsCredentialReader {
+  return async (_service, account) => await new Promise((resolve, reject) => {
+    execFile("/usr/bin/security", ["find-generic-password", "-s", service, "-a", account, "-w"], {
+      timeout: 10_000, shell: false, windowsHide: true,
+    }, (error, stdout) => {
+      if (error === null) resolve(stdout.replace(/\n$/u, ""));
+      else if ((error as { code?: number }).code === 44) resolve(undefined);
+      else reject(new Error(`OS credential lookup for ${account} failed`));
+    });
+  });
+}
+
+function macosWriter(service: string): OsCredentialWriter {
+  return async (_service, account, secret) => await new Promise((resolve, reject) => {
+    // macOS security(1) requires the password as the argument to -w; it does
+    // not read an omitted -w value from stdin. execFile keeps shell expansion
+    // out of the path and the callback never includes the secret in errors.
+    execFile("/usr/bin/security", [
+      "add-generic-password", "-U", "-s", service, "-a", account, "-w", secret,
+    ], {
+      timeout: 10_000, shell: false, windowsHide: true,
+    }, (error) => {
+      if (error === null) resolve();
+      else reject(new Error(`OS credential write for ${account} failed`));
+    });
+  });
+}
+
+function macosDeleter(service: string): OsCredentialDeleter {
+  return async (_service, account) => await new Promise((resolve, reject) => {
+    execFile("/usr/bin/security", ["delete-generic-password", "-s", service, "-a", account], {
+      timeout: 10_000, shell: false, windowsHide: true,
+    }, (error) => {
+      if (error === null) resolve(true);
+      else if ((error as { code?: number }).code === 44) resolve(false);
+      else reject(new Error(`OS credential delete for ${account} failed`));
+    });
+  });
+}
+
+type WindowsCredentialResult = {
+  readonly found?: boolean;
+  readonly deleted?: boolean;
+  readonly secret?: string;
+};
+
+const windowsScript = fileURLToPath(new URL("../runtime/windows-credential.ps1", import.meta.url));
+
+function windowsCredential(
+  operation: "read" | "write" | "delete",
+  service: string,
+  account: string,
+  secret?: string,
+): Promise<WindowsCredentialResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn("powershell.exe", [
+      "-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+      "-File", windowsScript, "-Operation", operation,
+    ], { shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const fail = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+    child.on("error", fail);
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+      if (stdout.length > 4 * 1024 * 1024) fail(new Error("Windows credential response is too large"));
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+      if (stderr.length > 64 * 1024) fail(new Error("Windows credential error is too large"));
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      if (code !== 0) {
+        fail(new Error(`Windows credential ${operation} for ${account} failed${stderr.trim().length === 0 ? "" : `: ${stderr.trim()}`}`));
+        return;
+      }
+      try {
+        const result = JSON.parse(stdout.replace(/^\uFEFF/u, "").trim()) as WindowsCredentialResult;
+        settled = true;
+        resolve(result);
+      } catch {
+        fail(new Error(`Windows credential ${operation} returned an invalid response`));
+      }
+    });
+    child.stdin.end(JSON.stringify({
+      service,
+      account,
+      ...(secret === undefined ? {} : { secret: Buffer.from(secret, "utf8").toString("base64") }),
+    }));
+  });
+}
+
+function windowsBackend(): {
+  readonly read: OsCredentialReader;
+  readonly write: OsCredentialWriter;
+  readonly remove: OsCredentialDeleter;
+} {
+  return {
+    read: async (service, account) => {
+      const result = await windowsCredential("read", service, account);
+      return result.found === true && result.secret !== undefined
+        ? Buffer.from(result.secret, "base64").toString("utf8")
+        : undefined;
+    },
+    write: async (service, account, secret) => {
+      await windowsCredential("write", service, account, secret);
+    },
+    remove: async (service, account) => (await windowsCredential("delete", service, account)).deleted === true,
+  };
+}
+
+function platformBackend(service: string) {
+  if (process.platform === "darwin") {
+    return { read: macosReader(service), write: macosWriter(service), remove: macosDeleter(service) };
+  }
+  if (process.platform === "win32") return windowsBackend();
+  throw new Error("OS CredentialStore supports macOS and Windows only");
+}
+
+/** One logical writable store backed by the current user's OS credential locker. */
+export class OsCredentialStore implements WritableCredentialStore {
+  readonly #read: OsCredentialReader;
+  readonly #write: OsCredentialWriter;
+  readonly #remove: OsCredentialDeleter;
+  readonly #service: string;
+
+  constructor(options: {
+    readonly service?: string;
+    readonly read?: OsCredentialReader;
+    readonly write?: OsCredentialWriter;
+    readonly remove?: OsCredentialDeleter;
+  } = {}) {
+    this.#service = options.service ?? DEFAULT_SERVICE;
+    const supplied = options.read !== undefined || options.write !== undefined || options.remove !== undefined;
+    if (supplied && (options.read === undefined || options.write === undefined || options.remove === undefined)) {
+      throw new Error("OS CredentialStore test backend must provide read, write and remove together");
+    }
+    const backend = supplied
+      ? { read: options.read!, write: options.write!, remove: options.remove! }
+      : platformBackend(this.#service);
+    this.#read = backend.read;
+    this.#write = backend.write;
+    this.#remove = backend.remove;
+  }
+
+  owns(ref: CredentialRef): boolean {
+    return ref.store === "os";
+  }
+
+  async resolve(ref: CredentialRef): Promise<CredentialValue | undefined> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) return undefined;
+    const secret = await this.#read(this.#service, ref.key);
+    return secret === undefined || secret.length === 0 ? undefined : { secret };
+  }
+
+  async put(ref: CredentialRef, value: CredentialValue): Promise<void> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) throw new Error(`OS CredentialStore does not own ${ref.store}`);
+    if (value.secret.length === 0) throw new Error("credential secret is empty");
+    await this.#write(this.#service, ref.key, value.secret);
+  }
+
+  async delete(ref: CredentialRef): Promise<boolean> {
+    verifyCredentialRef(ref);
+    if (!this.owns(ref)) throw new Error(`OS CredentialStore does not own ${ref.store}`);
+    return await this.#remove(this.#service, ref.key);
+  }
+}

package/packages/deck-track/README.md

@@ -0,0 +1,52 @@
+# `@hypit/deck-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.
+
+The official, deliberately narrow depth-stack Deck author package.
+
+`DepthStack` owns ordered Cards, semantic activation points, a finite visible neighborhood,
+relative-depth poses and one deterministic whole-collection reflow. Card pixels reuse the focused
+Media layer lowerer, but Deck is not a Media mode and exports only an ordinary peer `VisualTrack`.
+
+```xml
+<import as="copy" from="@hypit/text@1"/>
+
+<copy:Value id="proof-label">Evidence, not inference</copy:Value>
+<deck:Label id="proof-label-style" content={proof-label}
+  font={fonts.ui} size="34" color="#ffffff"/>
+
+<deck:DepthStack
+  id="proof-stack"
+  semantic={speech.semantic}
+  canvas={vertical}
+  frame={layout.proof-stack}
+  until={story.selection.proof}
+  appearance={recipes.deck.proof}
+>
+  <deck:Card id="proof-1" source={proof1.image} extent={proof1.extent}
+    at={story.moment.proof1} label={proof-label-style}/>
+  <deck:Card id="proof-2" source={proof2.video} at={story.moment.proof2}/>
+</deck:DepthStack>
+```
+
+The parent Recipe owns visibility, relative-depth pose progression, frame Paint, whole-group
+motion and reflow. A Card Recipe may additionally select explicit future/past playback. Timed
+`continue` is legal only with an active `loop-start` clock, so preview and trail sampling can never
+silently depend on renderer playback history.
+
+Optional labels are separate exact-font values and are referenced by Cards. Filenames, URLs and
+media metadata are never treated as label truth.
+
+The Surface projects every Card `at` and the deck terminal to `TemporalInstant` values before the
+Deck component runs. Card append and completion consume those Instants directly; they never locate
+a Moment/Selection or manufacture a one-frame terminal Window internally.
+
+`deck:Label` accepts either literal body copy or `content={Text}`. It binds that copy to exact font
+and label appearance in a small explicit Fragment. The Deck Track receives the resulting label as
+one normal edge; it never reads filenames, URLs or hidden media metadata.
+
+The package has no Provider, Need, queue, credential, global z band or cross-Track input. Another
+Deck family can install independently and lower to the same terminal `VisualTrack` without changing
+this package, Core, Film, Composition or HyperFrames.

package/packages/deck-track/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@hypit/deck-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/media-track": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/spatial": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*",
+    "@hypit/text": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/core": "workspace:*",
+    "@hypit/media-pipeline": "workspace:*"
+  }
+}

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

@@ -0,0 +1,32 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeDepthStackLabelSurface,
+  decodeDepthStackSurface,
+  depthStackComponent,
+  depthStackManifest,
+  depthStackModuleRef,
+  depthStackMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{
+    manifest: depthStackManifest,
+  }],
+  components: [depthStackComponent],
+  hostFacets: [
+    createMarkupSurfaceHostFacet({
+      module: depthStackModuleRef,
+    declaration: depthStackMarkupSurfaces.find((item) => item.name === "label")!,
+      handler: decodeDepthStackLabelSurface,
+    }),
+    createMarkupSurfaceHostFacet({
+      module: depthStackModuleRef,
+    declaration: depthStackMarkupSurfaces.find((item) => item.name === "track")!,
+      handler: decodeDepthStackSurface,
+    }),
+  ],
+};
+
+export default hypitPackage;

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

@@ -0,0 +1,217 @@
+import {
+  decodeMediaFit,
+  decodeMediaFramePaint,
+  decodeMediaMotion,
+  decodeMediaPresentation,
+  decodeMediaSampleSpec,
+  mediaAppearanceKeys,
+} from "@hypit/media-track";
+import type {
+  MediaPaintLayerSpec,
+  MediaSampleLayerSpec,
+} from "@hypit/media-track";
+import type { ContentFit } from "@hypit/spatial";
+import type { SvsRecipe } from "@hypit/svs";
+
+import {
+  sealDepthStackCardSpec,
+  sealDepthStackSpec,
+} from "./program.js";
+import type {
+  DeckCardTone,
+  DepthStackCardSpec,
+  DepthStackPoseStep,
+  DepthStackSpec,
+} from "./types.js";
+
+const DECK_KEYS = [
+  "visible-previous", "visible-next", "wrap",
+  "current-x", "current-y", "current-scale", "current-rotation", "current-opacity", "current-stacking",
+  "current-brightness", "current-contrast", "current-saturation",
+  "previous-x-step", "previous-y-step", "previous-scale-step", "previous-rotation-step",
+  "previous-rotation-mode", "previous-opacity-step", "previous-stacking-step",
+  "previous-brightness-step", "previous-contrast-step", "previous-saturation-step",
+  "next-x-step", "next-y-step", "next-scale-step", "next-rotation-step",
+  "next-rotation-mode", "next-opacity-step", "next-stacking-step",
+  "next-brightness-step", "next-contrast-step", "next-saturation-step",
+  "reflow-frames", "reflow-easing", "playback-future", "playback-past",
+] as const;
+
+function fail(recipe: SvsRecipe, message: string): never {
+  throw new Error(`DepthStack 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 {
+  return optionalNumber(recipe, name) ?? fallback;
+}
+
+function integer(recipe: SvsRecipe, name: string, fallback: number): number {
+  const value = number(recipe, name, fallback);
+  if (!Number.isSafeInteger(value)) fail(recipe, `${name} must be an integer.`);
+  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 oneOf<T extends string>(
+  recipe: SvsRecipe,
+  name: string,
+  values: readonly T[],
+  fallback: T,
+): T {
+  const value = optionalString(recipe, name) ?? fallback;
+  if (!values.includes(value as T)) fail(recipe, `${name} must be ${values.join(" | ")}.`);
+  return value as T;
+}
+
+function boolean(recipe: SvsRecipe, name: string, fallback: boolean): boolean {
+  const value = recipe.properties[name];
+  if (value === undefined) return fallback;
+  if (typeof value !== "boolean") fail(recipe, `${name} must be boolean.`);
+  return value;
+}
+
+function mediaRecipe(recipe: SvsRecipe, keys: readonly string[]): SvsRecipe {
+  const selected: Record<string, SvsRecipe["properties"][string]> = {};
+  for (const key of keys) {
+    const value = recipe.properties[key];
+    if (value !== undefined) selected[key] = value;
+  }
+  return { ...recipe, properties: selected };
+}
+
+function tone(recipe: SvsRecipe, prefix: string, fallback: DeckCardTone): DeckCardTone {
+  return {
+    brightness: number(recipe, `${prefix}-brightness`, fallback.brightness),
+    contrast: number(recipe, `${prefix}-contrast`, fallback.contrast),
+    saturation: number(recipe, `${prefix}-saturation`, fallback.saturation),
+  };
+}
+
+function step(
+  recipe: SvsRecipe,
+  prefix: "previous" | "next",
+  defaults: DepthStackPoseStep,
+): DepthStackPoseStep {
+  return {
+    xPerDepthPx: number(recipe, `${prefix}-x-step`, defaults.xPerDepthPx),
+    yPerDepthPx: number(recipe, `${prefix}-y-step`, defaults.yPerDepthPx),
+    scalePerDepth: number(recipe, `${prefix}-scale-step`, defaults.scalePerDepth),
+    rotationPerDepthDeg: number(recipe, `${prefix}-rotation-step`, defaults.rotationPerDepthDeg),
+    rotationMode: oneOf(recipe, `${prefix}-rotation-mode`, ["linear", "alternate"] as const, defaults.rotationMode),
+    opacityPerDepth: number(recipe, `${prefix}-opacity-step`, defaults.opacityPerDepth),
+    stackingPerDepth: integer(recipe, `${prefix}-stacking-step`, defaults.stackingPerDepth),
+    tonePerDepth: tone(recipe, `${prefix}`, defaults.tonePerDepth),
+  };
+}
+
+function assertKnownKeys(recipe: SvsRecipe): void {
+  const allowed = new Set<string>([
+    ...DECK_KEYS,
+    ...mediaAppearanceKeys.fit,
+    ...mediaAppearanceKeys.sample,
+    ...mediaAppearanceKeys.frame,
+    ...mediaAppearanceKeys.motion,
+  ]);
+  const unknown = Object.keys(recipe.properties).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) fail(recipe, `does not accept ${unknown.join(", ")}.`);
+}
+
+export function decodeDepthStackSpec(recipe: SvsRecipe): DepthStackSpec {
+  assertKnownKeys(recipe);
+  const motionRecipe = mediaRecipe(recipe, mediaAppearanceKeys.motion);
+  const frameRecipe = mediaRecipe(recipe, mediaAppearanceKeys.frame);
+  const previousDefaults: DepthStackPoseStep = {
+    xPerDepthPx: 0,
+    yPerDepthPx: 28,
+    scalePerDepth: 0.94,
+    rotationPerDepthDeg: -2.5,
+    rotationMode: "alternate",
+    opacityPerDepth: 0.82,
+    stackingPerDepth: -1,
+    tonePerDepth: { brightness: 0.92, contrast: 1, saturation: 0.86 },
+  };
+  const nextDefaults: DepthStackPoseStep = {
+    xPerDepthPx: 0,
+    yPerDepthPx: -20,
+    scalePerDepth: 0.92,
+    rotationPerDepthDeg: 2,
+    rotationMode: "alternate",
+    opacityPerDepth: 0.72,
+    stackingPerDepth: -1,
+    tonePerDepth: { brightness: 0.88, contrast: 1, saturation: 0.78 },
+  };
+  return sealDepthStackSpec({
+
+    visibility: {
+      previous: integer(recipe, "visible-previous", 2),
+      next: integer(recipe, "visible-next", 1),
+      wrap: boolean(recipe, "wrap", false),
+    },
+    poses: {
+      current: {
+        xPx: number(recipe, "current-x", 0),
+        yPx: number(recipe, "current-y", 0),
+        scale: number(recipe, "current-scale", 1),
+        rotationDeg: number(recipe, "current-rotation", 0),
+        opacity: number(recipe, "current-opacity", 1),
+        stacking: integer(recipe, "current-stacking", 0),
+        tone: tone(recipe, "current", { brightness: 1, contrast: 1, saturation: 1 }),
+      },
+      previous: step(recipe, "previous", previousDefaults),
+      next: step(recipe, "next", nextDefaults),
+    },
+    reflow: {
+      durationFrames: integer(recipe, "reflow-frames", 8),
+      easing: oneOf(recipe, "reflow-easing", ["linear", "ease-in", "ease-out", "ease-in-out"] as const, "ease-in-out"),
+    },
+    presentation: decodeMediaPresentation(frameRecipe),
+    motion: decodeMediaMotion(motionRecipe),
+    stackingOrder: integer(recipe, "stack-order", 30),
+  });
+}
+
+export function decodeDepthStackCardSpec(recipe: SvsRecipe, id: string): DepthStackCardSpec {
+  assertKnownKeys(recipe);
+  return sealDepthStackCardSpec({
+
+    id,
+    playback: {
+      future: oneOf(recipe, "playback-future", ["hold-head", "continue"] as const, "hold-head"),
+      past: oneOf(recipe, "playback-past", ["hold-tail", "continue", "hide"] as const, "hold-tail"),
+    },
+  });
+}
+
+export function decodeDepthStackMaterial(
+  recipe: SvsRecipe,
+  id: string,
+  sourceKind: "still" | "timed" | "surface",
+): {
+  readonly fit: ContentFit;
+  readonly framePaint?: MediaPaintLayerSpec;
+  readonly sample: MediaSampleLayerSpec;
+} {
+  assertKnownKeys(recipe);
+  const fitRecipe = mediaRecipe(recipe, mediaAppearanceKeys.fit);
+  const sampleRecipe = mediaRecipe(recipe, [...mediaAppearanceKeys.fit, ...mediaAppearanceKeys.sample]);
+  const frameRecipe = mediaRecipe(recipe, mediaAppearanceKeys.frame);
+  const framePaint = decodeMediaFramePaint(frameRecipe, `${id}:frame-paint`);
+  return {
+    fit: decodeMediaFit(fitRecipe),
+    ...(framePaint === undefined ? {} : { framePaint }),
+    sample: decodeMediaSampleSpec(sampleRecipe, `${id}:sample`, sourceKind),
+  };
+}