@hypit/hypit 0.0.1 → 0.1.0

package/packages/interview-emoji-reveal/src/component.ts

@@ -0,0 +1,45 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef, StoredValue } from "@hypit/protocol";
+import type { ProgramSpace } from "@hypit/program-space";
+import type { CanvasSpace } from "@hypit/spatial";
+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
+
+import { emojiRevealProducers, emojiRevealTypes } from "./manifest.js";
+import { appendEmojiRevealItem, appendPresetEmojiRevealItem, assertEmojiRevealProgram, createEmojiRevealSet, finalizeEmojiReveal, renderEmojiReveal } from "./program.js";
+import type { EmojiRevealHeader, EmojiRevealItemSpec, EmojiRevealProgram, EmojiRevealSet, EmojiRevealStyle } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, label: string): T {
+  if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
+  return value.value as unknown as T;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+function blob(value: StoredValue | undefined, label: string): BlobRef {
+  if (value?.kind !== "blob") throw new Error(`${label} must be a blob Artifact.`);
+  return value;
+}
+
+export const emojiRevealComponent = {
+  producers: [
+    { producer: emojiRevealProducers.createSet, handler: () => ({ outputs: { set: output(createEmojiRevealSet()) }, needs: {} }) },
+    { producer: emojiRevealProducers.appendItem, handler: ({ inputs }) => ({ outputs: { set: output(appendEmojiRevealItem(
+      inline<EmojiRevealSet>(inputs.set?.value, "EmojiRevealSet"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+      inline<EmojiRevealItemSpec>(inputs.spec?.value, "EmojiRevealItemSpec"), blob(inputs.icon?.value, "Emoji Reveal icon"),
+      inline<TemporalInstant>(inputs.activation?.value, "TemporalInstant"),
+    )) }, needs: {} }) },
+    { producer: emojiRevealProducers.appendPresetItem, handler: ({ inputs }) => ({ outputs: { set: output(appendPresetEmojiRevealItem(
+      inline<EmojiRevealSet>(inputs.set?.value, "EmojiRevealSet"),
+      inline<EmojiRevealItemSpec>(inputs.spec?.value, "EmojiRevealItemSpec"), blob(inputs.icon?.value, "Emoji Reveal icon"),
+    )) }, needs: {} }) },
+    { producer: emojiRevealProducers.finalize, handler: ({ inputs }) => ({ outputs: { program: output(finalizeEmojiReveal(
+      inline<EmojiRevealHeader>(inputs.header?.value, "EmojiRevealHeader"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+      inline<TemporalWindow>(inputs.outer?.value, "TemporalWindow"), inline<EmojiRevealStyle>(inputs.style?.value, "EmojiRevealStyle"),
+      blob(inputs.placeholder?.value, "Emoji Reveal placeholder"), inline<EmojiRevealSet>(inputs.set?.value, "EmojiRevealSet"),
+    )) }, needs: {} }) },
+    { producer: emojiRevealProducers.render, handler: ({ inputs }) => ({ outputs: { track: output(renderEmojiReveal(
+      inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"), inline<ProgramSpace>(inputs.space?.value, "ProgramSpace"),
+      inline<EmojiRevealProgram>(inputs.program?.value, "EmojiRevealProgram"),
+    )) }, needs: {} }) },
+  ],
+  validators: [{ type: emojiRevealTypes.program, handler: ({ value }) => assertEmojiRevealProgram(inline<EmojiRevealProgram>(value, "EmojiRevealProgram")) }],
+} satisfies ComponentPackage;

package/packages/interview-emoji-reveal/src/fragment.ts

@@ -0,0 +1,62 @@
+import { programSpaceTypes } from "@hypit/program-space";
+import { compositionTypes } from "@hypit/composition";
+import { artifactTypes } from "@hypit/artifact";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation } from "@hypit/elaborator";
+import { spatialTypes } from "@hypit/spatial";
+import { temporalTypes } from "@hypit/temporal";
+
+import { emojiRevealProducers, emojiRevealTypes } from "./manifest.js";
+
+export type EmojiRevealFragmentItem = {
+  readonly specName: string;
+  readonly iconName: string;
+  readonly activationName?: string;
+};
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export function createEmojiRevealFragment(items: readonly EmojiRevealFragmentItem[]) {
+  if (items.length === 0) throw new Error("Emoji Reveal Fragment requires at least one Item.");
+  const operations: FragmentOperation[] = [
+    { id: "emoji:set:empty", producer: emojiRevealProducers.createSet, inputs: {}, result: { kind: "output", name: "set" } },
+  ];
+  let current = "emoji:set:empty";
+  items.forEach((item, index) => {
+    const id = `emoji:set:append:${String(index + 1).padStart(4, "0")}`;
+    operations.push({ id, producer: item.activationName === undefined
+      ? emojiRevealProducers.appendPresetItem
+      : emojiRevealProducers.appendItem, inputs: {
+      set: operation(current), spec: input(item.specName), icon: input(item.iconName),
+      ...(item.activationName === undefined ? {} : {
+        space: input("space"), activation: input(item.activationName),
+      }),
+    }, result: { kind: "output", name: "set" } });
+    current = id;
+  });
+  operations.push(
+    { id: "emoji:program", producer: emojiRevealProducers.finalize, inputs: {
+      header: input("header"), space: input("space"), outer: input("outer"), style: input("style"),
+      placeholder: input("placeholder"), set: operation(current),
+    }, result: { kind: "output", name: "program" } },
+    { id: "emoji:track", producer: emojiRevealProducers.render, inputs: {
+      canvas: input("canvas"), space: input("space"), program: operation("emoji:program"),
+    }, result: { kind: "output", name: "track" } },
+  );
+  return sealGraphFragment({
+    inputs: [
+      { name: "header", type: emojiRevealTypes.header }, { name: "space", type: programSpaceTypes.programSpace },
+      { name: "canvas", type: spatialTypes.canvas }, { name: "outer", type: temporalTypes.window }, { name: "style", type: emojiRevealTypes.style },
+      { name: "placeholder", type: artifactTypes.blob },
+      ...items.flatMap((item) => [
+        { name: item.specName, type: emojiRevealTypes.itemSpec }, { name: item.iconName, type: artifactTypes.blob },
+        ...(item.activationName === undefined ? [] : [{ name: item.activationName, type: temporalTypes.instant }]),
+      ]),
+    ],
+    operations,
+    exports: [
+      { name: "program", type: emojiRevealTypes.program, root: operation("emoji:program") },
+      { name: "track", type: compositionTypes.visualTrack, root: operation("emoji:track") },
+    ],
+  });
+}

package/packages/interview-emoji-reveal/src/index.ts

@@ -0,0 +1,16 @@
+export { emojiRevealComponent } from "./component.js";
+export { createEmojiRevealFragment } from "./fragment.js";
+export type { EmojiRevealFragmentItem } from "./fragment.js";
+export {
+  emojiRevealDependency, emojiRevealHeaderSchema, emojiRevealItemSpecSchema, emojiRevealManifest,
+  emojiRevealMarkupSurfaces, emojiRevealModuleRef, emojiRevealProducers, emojiRevealProgramSchema,
+  emojiRevealSetSchema, emojiRevealStyleSchema, emojiRevealTypes,
+} from "./manifest.js";
+export {
+  appendEmojiRevealItem, appendPresetEmojiRevealItem, assertEmojiRevealHeader, assertEmojiRevealItemSpec, assertEmojiRevealProgram,
+  assertEmojiRevealSet, assertEmojiRevealStyle, createEmojiRevealSet, finalizeEmojiReveal,
+  renderEmojiReveal, sealEmojiRevealHeader, sealEmojiRevealItemSpec,
+} from "./program.js";
+export { decodeEmojiRevealStyle } from "./style.js";
+export { decodeEmojiRevealStyleSurface, decodeEmojiRevealTrackSurface } from "./surface.js";
+export type * from "./types.js";

package/packages/interview-emoji-reveal/src/manifest.ts

@@ -0,0 +1,174 @@
+import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
+import { readFile } from "node:fs/promises";
+
+import { artifactDependency, artifactTypes } from "@hypit/artifact";
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { semanticTrackDependency } from "@hypit/semantic-track";
+import { spatialDependency, spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+import { temporalDependency, temporalInstantSchema, temporalTypes, temporalWindowSchema } from "@hypit/temporal";
+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+
+const previewImage = (file: string) => ({
+  mediaType: "image/png",
+  path: `preview/${file}`,
+  open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
+});
+
+export const emojiRevealModuleRef = { name: "@hypit/interview-emoji-reveal", version: "1" } as const;
+
+export const emojiRevealTypes = {
+  header: { module: emojiRevealModuleRef, name: "EmojiRevealHeader" },
+  style: { module: emojiRevealModuleRef, name: "EmojiRevealStyle" },
+  itemSpec: { module: emojiRevealModuleRef, name: "EmojiRevealItemSpec" },
+  set: { module: emojiRevealModuleRef, name: "EmojiRevealSet" },
+  program: { module: emojiRevealModuleRef, name: "EmojiRevealProgram" },
+} satisfies Record<string, TypeRef>;
+
+export const emojiRevealProducers = {
+  createSet: { module: emojiRevealModuleRef, name: "create-emoji-reveal-set" },
+  appendItem: { module: emojiRevealModuleRef, name: "append-emoji-reveal-item" },
+  appendPresetItem: { module: emojiRevealModuleRef, name: "append-preset-emoji-reveal-item" },
+  finalize: { module: emojiRevealModuleRef, name: "finalize-emoji-reveal" },
+  render: { module: emojiRevealModuleRef, name: "render-emoji-reveal" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const integer = { kind: "number", integer: true } as const;
+const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
+const positive = { kind: "number", minimum: 0.000001 } as const;
+const nonNegative = { kind: "number", minimum: 0 } as const;
+const number = { kind: "number" } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const blob = object({
+  kind: { schema: { kind: "literal", value: "blob" } },
+  digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
+  size: { schema: { kind: "number", integer: true, minimum: 0 } },
+  mediaType: { schema: string },
+});
+
+export const emojiRevealHeaderSchema: ValueSchema = object({ id: { schema: string } });
+export const emojiRevealItemSpecSchema: ValueSchema = object({
+  id: { schema: string }, preset: { schema: { kind: "boolean" } },
+});
+export const emojiRevealStyleSchema: ValueSchema = object({
+  id: { schema: string },
+  centerX: { schema: number }, topY: { schema: number },
+  slotSizePx: { schema: positive }, gapPx: { schema: nonNegative },
+  paddingXPx: { schema: nonNegative }, paddingYPx: { schema: nonNegative },
+  background: { schema: string }, borderColor: { schema: string }, borderWidthPx: { schema: nonNegative }, radiusPx: { schema: nonNegative },
+  shadowColor: { schema: string }, shadowXPx: { schema: number }, shadowYPx: { schema: number }, shadowBlurPx: { schema: nonNegative }, shadowSpreadPx: { schema: number },
+  iconSizePx: { schema: positive }, revealFrames: { schema: positiveInteger }, stackingOrder: { schema: integer },
+});
+const emojiRevealItemSchema: ValueSchema = object({
+  spec: { schema: emojiRevealItemSpecSchema }, icon: { schema: blob }, activation: { schema: temporalInstantSchema, optional: true },
+});
+export const emojiRevealSetSchema: ValueSchema = object({
+  items: { schema: { kind: "array", items: emojiRevealItemSchema } },
+});
+export const emojiRevealProgramSchema: ValueSchema = object({
+  id: { schema: string }, programSpaceId: { schema: string }, outer: { schema: temporalWindowSchema },
+  style: { schema: emojiRevealStyleSchema }, placeholder: { schema: blob },
+  items: { schema: { kind: "array", minItems: 1, items: emojiRevealItemSchema } },
+});
+
+const recipe = [
+  ["center-x", "0.5", "Places the adaptive strip by its horizontal centre as a fraction of Canvas width."],
+  ["top-y", "0.07", "Places the strip's top edge as a fraction of Canvas height."],
+  ["slot-size", "72", "Sets the fixed width and height of each SVG slot in pixels."],
+  ["slot-gap", "10", "Sets the gap between adjacent slots in pixels."],
+  ["padding-x", "18", "Insets the first and last slots from the board's horizontal edges."],
+  ["padding-y", "14", "Insets every slot from the board's top and bottom edges."],
+  ["background", "#FFFDF7", "Fills the single board behind all slots."],
+  ["border-color", "#161616", "Colors the board outline."],
+  ["border-width", "4", "Sets the board outline thickness in pixels."],
+  ["radius", "22", "Rounds the board corners in pixels."],
+  ["shadow-color", "#000000B8", "Colors the board's external shadow."],
+  ["shadow-x", "9", "Offsets the board shadow to the right in pixels."],
+  ["shadow-y", "10", "Offsets the board shadow down in pixels."],
+  ["shadow-blur", "0", "Sets the board shadow blur in pixels; zero makes the meme-style hard shadow."],
+  ["shadow-spread", "0", "Grows or shrinks the board shadow in pixels."],
+  ["icon-size", "48", "Sets the square SVG viewport size in pixels."],
+  ["reveal-frames", "6", "Sets the duration of one icon's overshoot-and-settle reveal."],
+  ["stack-order", "66", "Sets the strip's absolute visual stacking order."],
+] as const;
+
+export const emojiRevealMarkupSurfaces = [
+  { name: "style", tag: "Style", mode: "structured", outputs: [emojiRevealTypes.style],
+    vocabulary: {
+      summary: "Compiles one Recipe into the visual Style shared by an SVG Reveal strip.",
+      attributes: [
+        { name: "id", kind: "identifier", required: true, summary: "Names this Style." },
+        { name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
+          summary: "Chooses the Recipe that controls placement, board paint, slot geometry and reveal motion.",
+          recipe: recipe.map(([name, fallback, summary]) => ({ name, required: false, fallback, summary })) },
+      ],
+      example: `<emoji:Style id="emoji-strip" recipe={styles.emoji-strip}/>` ,
+      notes: ["The Style owns appearance and placement, but never semantic timing."],
+    } },
+  { name: "track", tag: "Track", mode: "structured",
+    outputs: [emojiRevealTypes.header, emojiRevealTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, emojiRevealTypes.program, compositionTypes.visualTrack],
+    vocabulary: {
+      summary: "Draws one adaptive row of preset or progressively revealed icon slots.",
+      appearance: "A compact rounded rectangle centered near the top of the frame, with a dark outline and a hard lower-right shadow. Its width is computed from the number of fixed-size slots. Preset slots are settled from the first frame. Every other slot starts with the same supplied placeholder icon, then its semantic Moment replaces that slot with a brief overshoot and settle while earlier answers remain visible and later slots remain unanswered.",
+      preview: previewImage("Track.png"),
+      attributes: [
+        { name: "id", kind: "identifier", required: true, summary: "Names the reveal Program and Track." },
+        ...temporalContextAttributeVocabulary,
+        { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas], summary: "Chooses the Canvas used for normalized top placement." },
+        { name: "style", kind: "reference", required: true, accepts: [emojiRevealTypes.style], summary: "Chooses the strip Style." },
+        { name: "placeholder", kind: "reference", required: true, accepts: [artifactTypes.blob], summary: "Supplies the one image drawn in every unrevealed slot." },
+        ...temporalWindowAttributeVocabulary,
+      ],
+      children: [{ tag: "Item", cardinality: "many", summary: "One answer slot, either settled from the start or revealed at one event.", attributes: [
+        { name: "id", kind: "identifier", required: true, summary: "Names this answer slot and the timing subject it owns." },
+        { name: "icon", kind: "reference", required: true, accepts: [artifactTypes.blob], summary: "Supplies this answer as an image Artifact from the same visual icon family as the placeholder." },
+        { name: "preset", kind: "literal", required: false, values: ["true", "false"], summary: "Settles this Item from the start of the Track Window; preset Items have no at." },
+        { name: "at", kind: "expression", required: false, accepts: [narrativeTypes.moment], summary: "Chooses this non-preset Item's reveal Moment or authored time, such as 2s or 12f; required unless preset is true." },
+      ] }],
+      ports: [
+        { name: "program", type: emojiRevealTypes.program, summary: "The adaptive strip with its projected outer Window and fully traced Moment activations." },
+        { name: "track", type: compositionTypes.visualTrack, summary: "That Program rendered as an ordinary VisualTrack." },
+      ],
+      example: `<emoji:Track id="rules" semantic={speech.semantic} canvas={vertical} style={emoji-strip} placeholder={question-icon} during="program">
+  <emoji:Item id="manifest" icon={manifest-icon} preset="true"/>
+  <emoji:Item id="real-estate" icon={real-estate-icon} at={story.moment.real-estate}/>
+  <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story.moment.bitcoin}/>
+</emoji:Track>`,
+      notes: [
+        "Item order is display order: preset Items come first, then non-preset Items in strict chronological reveal order.",
+        "A non-preset Item.at chooses one reveal trigger: a Script Moment or an authored time. The answer then persists to the outer Window's end.",
+        "The outer Track Window is separate from the child reveal Moments and uses the shared temporal Window protocol.",
+      ],
+    } },
+] as const;
+
+export const emojiRevealManifest: ModuleManifest = {
+  format: "hypit.module@1", name: emojiRevealModuleRef.name, version: emojiRevealModuleRef.version,
+  dependencies: [artifactDependency, narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, compositionDependency],
+  types: [
+    { name: emojiRevealTypes.header.name }, { name: emojiRevealTypes.style.name },
+    { name: emojiRevealTypes.itemSpec.name }, { name: emojiRevealTypes.set.name }, { name: emojiRevealTypes.program.name },
+  ],
+  capabilities: [],
+  producers: [
+    { name: emojiRevealProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: emojiRevealTypes.set }], needs: [] },
+    { name: emojiRevealProducers.appendItem.name,
+      inputs: [{ name: "set", type: emojiRevealTypes.set }, { name: "space", type: programSpaceTypes.programSpace }, { name: "spec", type: emojiRevealTypes.itemSpec }, { name: "icon", type: artifactTypes.blob }, { name: "activation", type: temporalTypes.instant }],
+      outputs: [{ name: "set", type: emojiRevealTypes.set }], needs: [] },
+    { name: emojiRevealProducers.appendPresetItem.name,
+      inputs: [{ name: "set", type: emojiRevealTypes.set }, { name: "spec", type: emojiRevealTypes.itemSpec }, { name: "icon", type: artifactTypes.blob }],
+      outputs: [{ name: "set", type: emojiRevealTypes.set }], needs: [] },
+    { name: emojiRevealProducers.finalize.name,
+      inputs: [{ name: "header", type: emojiRevealTypes.header }, { name: "space", type: programSpaceTypes.programSpace }, { name: "outer", type: temporalTypes.window }, { name: "style", type: emojiRevealTypes.style }, { name: "placeholder", type: artifactTypes.blob }, { name: "set", type: emojiRevealTypes.set }],
+      outputs: [{ name: "program", type: emojiRevealTypes.program }], needs: [] },
+    { name: emojiRevealProducers.render.name,
+      inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: emojiRevealTypes.program }],
+      outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+  ],
+};
+
+export const emojiRevealDependency = { module: emojiRevealModuleRef } as const;

package/packages/interview-emoji-reveal/src/program.ts

@@ -0,0 +1,242 @@
+import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
+import type { VisualAnimation, VisualElement, VisualTrack } from "@hypit/composition";
+import { assertProgramSpaceIdentity } from "@hypit/program-space";
+import type { ProgramSpace } from "@hypit/program-space";
+import { canonicalize } from "@hypit/protocol";
+import type { BlobRef } from "@hypit/protocol";
+import { assertCanvasSpace } from "@hypit/spatial";
+import type { CanvasSpace } from "@hypit/spatial";
+import { assertTemporalInstantFor, assertTemporalWindowFor } from "@hypit/temporal";
+import type { TemporalInstant, TemporalWindow } from "@hypit/temporal";
+
+import type { EmojiRevealHeader, EmojiRevealItemSpec, EmojiRevealProgram, EmojiRevealSet, EmojiRevealStyle } 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} is invalid.`); }
+function nonNegative(value: number, label: string): void { finite(value, label); assert(value >= 0, `${label} must be non-negative.`); }
+function positive(value: number, label: string): void { finite(value, label); assert(value > 0, `${label} must be positive.`); }
+function ratio(value: number, label: string): void { finite(value, label); assert(value >= 0 && value <= 1, `${label} must be between 0 and 1.`); }
+function color(value: string, label: string): void { assert(/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(value), `${label} must be a hexadecimal color.`); }
+
+export function sealEmojiRevealHeader(value: EmojiRevealHeader): EmojiRevealHeader {
+  assertEmojiRevealHeader(value); return canonicalize(value) as unknown as EmojiRevealHeader;
+}
+export function assertEmojiRevealHeader(value: EmojiRevealHeader): void { identity(value.id, "EmojiRevealHeader.id"); }
+
+export function sealEmojiRevealItemSpec(value: EmojiRevealItemSpec): EmojiRevealItemSpec {
+  assertEmojiRevealItemSpec(value); return canonicalize(value) as unknown as EmojiRevealItemSpec;
+}
+export function assertEmojiRevealItemSpec(value: EmojiRevealItemSpec): void {
+  identity(value.id, "EmojiRevealItemSpec.id");
+  assert(typeof value.preset === "boolean", "EmojiRevealItemSpec.preset is invalid.");
+}
+
+function assertIconImage(value: BlobRef, label: string): void {
+  assert(value.kind === "blob" && value.mediaType.startsWith("image/") && Number.isSafeInteger(value.size) && value.size > 0,
+    `${label} must be an Image Artifact.`);
+}
+
+export function assertEmojiRevealStyle(value: EmojiRevealStyle): void {
+  identity(value.id, "EmojiRevealStyle.id");
+  ratio(value.centerX, "EmojiRevealStyle.centerX"); ratio(value.topY, "EmojiRevealStyle.topY");
+  positive(value.slotSizePx, "EmojiRevealStyle.slotSizePx"); nonNegative(value.gapPx, "EmojiRevealStyle.gapPx");
+  nonNegative(value.paddingXPx, "EmojiRevealStyle.paddingXPx"); nonNegative(value.paddingYPx, "EmojiRevealStyle.paddingYPx");
+  color(value.background, "EmojiRevealStyle.background"); color(value.borderColor, "EmojiRevealStyle.borderColor");
+  nonNegative(value.borderWidthPx, "EmojiRevealStyle.borderWidthPx"); nonNegative(value.radiusPx, "EmojiRevealStyle.radiusPx");
+  color(value.shadowColor, "EmojiRevealStyle.shadowColor"); finite(value.shadowXPx, "EmojiRevealStyle.shadowXPx");
+  finite(value.shadowYPx, "EmojiRevealStyle.shadowYPx"); nonNegative(value.shadowBlurPx, "EmojiRevealStyle.shadowBlurPx");
+  finite(value.shadowSpreadPx, "EmojiRevealStyle.shadowSpreadPx"); positive(value.iconSizePx, "EmojiRevealStyle.iconSizePx");
+  assert(value.iconSizePx <= value.slotSizePx, "EmojiRevealStyle.iconSizePx cannot exceed its slot.");
+  assert(Number.isSafeInteger(value.revealFrames) && value.revealFrames > 0, "EmojiRevealStyle.revealFrames must be a positive integer.");
+  assert(Number.isSafeInteger(value.stackingOrder), "EmojiRevealStyle.stackingOrder must be an integer.");
+}
+
+export function createEmojiRevealSet(): EmojiRevealSet { return { items: [] }; }
+export function assertEmojiRevealSet(value: EmojiRevealSet): void {
+  assert(Array.isArray(value.items), "EmojiRevealSet is invalid.");
+  const ids = new Set<string>();
+  for (const item of value.items) {
+    assertEmojiRevealItemSpec(item.spec); assertIconImage(item.icon, `Emoji Reveal Item ${item.spec.id} icon`);
+    if (item.spec.preset) assert(!("activation" in item), `Preset Emoji Reveal Item ${item.spec.id} cannot have an activation.`);
+    else {
+      assert("activation" in item, `Emoji Reveal Item ${item.spec.id} requires an activation.`);
+      identity(item.activation.id, "Emoji Reveal activation id");
+    }
+    assert(!ids.has(item.spec.id), `Duplicate Emoji Reveal Item ${item.spec.id}.`); ids.add(item.spec.id);
+  }
+}
+
+export function appendEmojiRevealItem(set: EmojiRevealSet, space: ProgramSpace, spec: EmojiRevealItemSpec, icon: BlobRef, activation: TemporalInstant): EmojiRevealSet {
+  assertEmojiRevealSet(set); assertProgramSpaceIdentity(space); assertEmojiRevealItemSpec(spec);
+  assert(!spec.preset, `Emoji Reveal Item ${spec.id} with preset=true cannot have an activation.`);
+  assertIconImage(icon, `Emoji Reveal Item ${spec.id} icon`);
+  assertTemporalInstantFor(activation, { subjectId: spec.id, space });
+  assert(!set.items.some((item) => item.spec.id === spec.id), `Duplicate Emoji Reveal Item ${spec.id}.`);
+  return { items: [...set.items, { spec: structuredClone(spec), icon: structuredClone(icon), activation: structuredClone(activation) }] };
+}
+
+export function appendPresetEmojiRevealItem(set: EmojiRevealSet, spec: EmojiRevealItemSpec, icon: BlobRef): EmojiRevealSet {
+  assertEmojiRevealSet(set); assertEmojiRevealItemSpec(spec);
+  assert(spec.preset, `Preset Emoji Reveal Item ${spec.id} requires preset=true.`);
+  assertIconImage(icon, `Emoji Reveal Item ${spec.id} icon`);
+  assert(!set.items.some((item) => item.spec.id === spec.id), `Duplicate Emoji Reveal Item ${spec.id}.`);
+  return { items: [...set.items, { spec: structuredClone(spec), icon: structuredClone(icon) }] };
+}
+
+export function finalizeEmojiReveal(
+  header: EmojiRevealHeader, space: ProgramSpace, outer: TemporalWindow, style: EmojiRevealStyle, placeholder: BlobRef, set: EmojiRevealSet,
+): EmojiRevealProgram {
+  assertEmojiRevealHeader(header); assertProgramSpaceIdentity(space); assertEmojiRevealStyle(style); assertEmojiRevealSet(set);
+  assertIconImage(placeholder, "Emoji Reveal placeholder");
+  assertTemporalWindowFor(outer, { subjectId: header.id, space });
+  assert(set.items.length > 0, "Emoji Reveal requires at least one Item.");
+  let previous = outer.span.startFrame - 1;
+  let revealStarted = false;
+  for (const item of set.items) {
+    if (!("activation" in item)) {
+      assert(!revealStarted, `Preset Emoji Reveal Item ${item.spec.id} cannot appear after a reveal Item.`);
+      continue;
+    }
+    revealStarted = true;
+    const frame = item.activation.frame;
+    assert(frame >= outer.span.startFrame && frame < outer.span.endFrameExclusive,
+      `Emoji Reveal Item ${item.spec.id} must activate inside the Track Window.`);
+    assert(frame > previous, `Emoji Reveal Item ${item.spec.id} must activate after the previous Item.`);
+    previous = frame;
+  }
+  const program: EmojiRevealProgram = {
+    id: header.id, programSpaceId: space.id, outer: structuredClone(outer), style: structuredClone(style),
+    placeholder: structuredClone(placeholder), items: structuredClone(set.items),
+  };
+  assertEmojiRevealProgram(program);
+  return canonicalize(program) as unknown as EmojiRevealProgram;
+}
+
+export function assertEmojiRevealProgram(value: EmojiRevealProgram): void {
+  identity(value.id, "EmojiRevealProgram.id"); identity(value.programSpaceId, "EmojiRevealProgram.programSpaceId");
+  assertEmojiRevealStyle(value.style); assertEmojiRevealSet({ items: value.items });
+  assertIconImage(value.placeholder, "EmojiRevealProgram.placeholder");
+  assert(value.items.length > 0, "EmojiRevealProgram requires Items.");
+  assert(value.outer.span.endFrameExclusive > value.outer.span.startFrame, "EmojiRevealProgram outer Window is empty.");
+  let previous = value.outer.span.startFrame - 1;
+  let revealStarted = false;
+  for (const item of value.items) {
+    if (!("activation" in item)) {
+      assert(!revealStarted, `EmojiRevealProgram preset Item ${item.spec.id} appears after a reveal Item.`);
+      continue;
+    }
+    revealStarted = true;
+    assert(item.activation.frame >= value.outer.span.startFrame && item.activation.frame < value.outer.span.endFrameExclusive,
+      `Emoji Reveal Item ${item.spec.id} is outside the outer Window.`);
+    assert(item.activation.frame > previous, `Emoji Reveal Item ${item.spec.id} is not in strict reveal order.`);
+    previous = item.activation.frame;
+  }
+}
+
+function px(value: number): string { return `${Number(value.toFixed(6))}px`; }
+function scale(value: number): string { return `scale(${Number(value.toFixed(6))})`; }
+
+function revealAnimation(atFrame: number, duration: number, revealFrames: number): VisualAnimation {
+  const marks = new Map<number, { opacity: number; scale: number }>();
+  marks.set(0, { opacity: atFrame === 0 ? 1 : 0, scale: 0.72 });
+  if (atFrame > 0) marks.set(atFrame - 1, { opacity: 0, scale: 0.72 });
+  marks.set(atFrame, { opacity: 1, scale: 0.72 });
+  marks.set(Math.min(duration, atFrame + Math.max(1, Math.round(revealFrames * 0.34))), { opacity: 1, scale: 1.14 });
+  marks.set(Math.min(duration, atFrame + Math.max(2, Math.round(revealFrames * 0.68))), { opacity: 1, scale: 0.95 });
+  marks.set(Math.min(duration, atFrame + revealFrames), { opacity: 1, scale: 1 });
+  marks.set(duration, { opacity: 1, scale: 1 });
+  return { keyframes: [...marks].sort(([left], [right]) => left - right).map(([frame, value]) => ({
+    atFrame: frame, easing: "linear", style: [{ name: "opacity", value: value.opacity }, { name: "transform", value: scale(value.scale) }],
+  })) };
+}
+
+function questionAnimation(atFrame: number, duration: number): VisualAnimation {
+  const marks = new Map<number, { opacity: number; scale: number }>();
+  marks.set(0, { opacity: atFrame === 0 ? 0 : 1, scale: 1 });
+  if (atFrame > 0) marks.set(atFrame - 1, { opacity: 1, scale: 1 });
+  marks.set(atFrame, { opacity: 0, scale: 0.72 }); marks.set(duration, { opacity: 0, scale: 0.72 });
+  return { keyframes: [...marks].sort(([left], [right]) => left - right).map(([frame, value]) => ({
+    atFrame: frame, easing: "linear", style: [{ name: "opacity", value: value.opacity }, { name: "transform", value: scale(value.scale) }],
+  })) };
+}
+
+function settledAnimation(duration: number, visible: boolean): VisualAnimation {
+  const style = [{ name: "opacity", value: visible ? 1 : 0 }, { name: "transform", value: scale(1) }];
+  return { keyframes: [
+    { atFrame: 0, easing: "linear", style },
+    { atFrame: duration, easing: "linear", style },
+  ] };
+}
+
+function iconElement(input: {
+  readonly id: string; readonly parent: string; readonly order: number; readonly artifact: BlobRef;
+  readonly x: number; readonly y: number; readonly size: number; readonly animation: VisualAnimation;
+}): VisualElement {
+  return {
+    id: input.id, parent: input.parent, order: input.order, kind: "image", artifact: structuredClone(input.artifact), animation: input.animation,
+    style: [
+      { name: "height", value: px(input.size) }, { name: "left", value: px(input.x) }, { name: "object-fit", value: "contain" },
+      { name: "overflow", value: "visible" }, { name: "position", value: "absolute" }, { name: "top", value: px(input.y) },
+      { name: "transform-origin", value: "center center" }, { name: "width", value: px(input.size) },
+    ],
+  };
+}
+
+export function renderEmojiReveal(canvas: CanvasSpace, space: ProgramSpace, program: EmojiRevealProgram): VisualTrack {
+  assertCanvasSpace(canvas); assertProgramSpaceIdentity(space); assertEmojiRevealProgram(program);
+  assert(program.programSpaceId === space.id, "EmojiRevealProgram belongs to another ProgramSpace.");
+  assertTemporalWindowFor(program.outer, { subjectId: program.id, space });
+  const { style } = program;
+  const count = program.items.length;
+  const width = style.paddingXPx * 2 + style.slotSizePx * count + style.gapPx * (count - 1);
+  const height = style.paddingYPx * 2 + style.slotSizePx;
+  const left = canvas.widthPx * style.centerX - width / 2;
+  const top = canvas.heightPx * style.topY;
+  assert(left - Math.max(0, -style.shadowXPx) >= 0 && left + width + Math.max(0, style.shadowXPx) <= canvas.widthPx,
+    "Emoji Reveal strip is wider than the Canvas at this placement.");
+  assert(top >= 0 && top + height + Math.max(0, style.shadowYPx) <= canvas.heightPx,
+    "Emoji Reveal strip is outside the Canvas at this placement.");
+  const duration = program.outer.span.endFrameExclusive - program.outer.span.startFrame;
+  const elements: VisualElement[] = [{
+    id: "root", order: 0, kind: "box", style: [
+      { name: "height", value: px(height) }, { name: "left", value: px(left) }, { name: "overflow", value: "visible" },
+      { name: "position", value: "absolute" }, { name: "top", value: px(top) }, { name: "width", value: px(width) },
+    ],
+  }, {
+    id: "board", parent: "root", order: 1, kind: "box", style: [
+      { name: "background-color", value: style.background },
+      { name: "border", value: `${px(style.borderWidthPx)} solid ${style.borderColor}` },
+      { name: "border-radius", value: px(style.radiusPx) },
+      { name: "box-shadow", value: `${px(style.shadowXPx)} ${px(style.shadowYPx)} ${px(style.shadowBlurPx)} ${px(style.shadowSpreadPx)} ${style.shadowColor}` },
+      { name: "box-sizing", value: "border-box" }, { name: "height", value: "100%" }, { name: "inset", value: "0" },
+      { name: "overflow", value: "visible" }, { name: "position", value: "absolute" }, { name: "width", value: "100%" },
+    ],
+  }];
+  program.items.forEach((item, index) => {
+    const x = style.paddingXPx + index * (style.slotSizePx + style.gapPx);
+    const preset = !("activation" in item);
+    const atFrame = preset ? 0 : item.activation.frame - program.outer.span.startFrame;
+    const parentId = `slot-${index + 1}`;
+    elements.push({
+      id: parentId, parent: "root", order: 2 + index * 3, kind: "box", style: [
+        { name: "height", value: px(style.slotSizePx) }, { name: "left", value: px(x) }, { name: "overflow", value: "visible" },
+        { name: "position", value: "absolute" }, { name: "top", value: px(style.paddingYPx) }, { name: "width", value: px(style.slotSizePx) },
+      ],
+    });
+    elements.push(
+      iconElement({ id: `${parentId}-placeholder`, parent: parentId, order: 3 + index * 3, artifact: program.placeholder,
+        x: (style.slotSizePx - style.iconSizePx) / 2, y: (style.slotSizePx - style.iconSizePx) / 2,
+        size: style.iconSizePx, animation: preset ? settledAnimation(duration, false) : questionAnimation(atFrame, duration) }),
+      iconElement({ id: `${parentId}-icon`, parent: parentId, order: 4 + index * 3, artifact: item.icon,
+        x: (style.slotSizePx - style.iconSizePx) / 2, y: (style.slotSizePx - style.iconSizePx) / 2,
+        size: style.iconSizePx, animation: preset ? settledAnimation(duration, true) : revealAnimation(atFrame, duration, style.revealFrames) }),
+    );
+  });
+  const track = sealVisualTrack({
+    programSpaceId: space.id, visualIr: "hypit.visual-ir@1", id: program.id,
+    presents: [{ id: program.id, subjectId: program.id, span: { ...program.outer.span },
+      stacking: { order: style.stackingOrder, tieBreak: program.id }, elements }],
+  });
+  assertVisualTrackIdentity(track, space); return track;
+}

package/packages/interview-emoji-reveal/src/style.ts

@@ -0,0 +1,47 @@
+import { canonicalize } from "@hypit/protocol";
+import type { SvsRecipe } from "@hypit/svs";
+
+import { assertEmojiRevealStyle } from "./program.js";
+import type { EmojiRevealStyle } from "./types.js";
+
+const KEYS = new Set([
+  "center-x", "top-y", "slot-size", "slot-gap", "padding-x", "padding-y",
+  "background", "border-color", "border-width", "radius",
+  "shadow-color", "shadow-x", "shadow-y", "shadow-blur", "shadow-spread",
+  "icon-size", "reveal-frames", "stack-order",
+]);
+
+function fail(recipe: SvsRecipe, message: string): never { throw new Error(`Emoji Reveal Recipe ${recipe.path} ${message}`); }
+function numeric(recipe: SvsRecipe, name: string, fallback: number): number {
+  const value = recipe.properties[name] ?? fallback;
+  if (typeof value !== "number" || !Number.isFinite(value)) fail(recipe, `${name} must be a finite number.`);
+  return value;
+}
+function integer(recipe: SvsRecipe, name: string, fallback: number): number {
+  const value = numeric(recipe, name, fallback);
+  if (!Number.isSafeInteger(value)) fail(recipe, `${name} must be an integer.`);
+  return value;
+}
+function text(recipe: SvsRecipe, name: string, fallback: string): string {
+  const value = recipe.properties[name] ?? fallback;
+  if (typeof value !== "string" || value.trim().length === 0) fail(recipe, `${name} must be text.`);
+  return value.trim();
+}
+export function decodeEmojiRevealStyle(id: string, recipe: SvsRecipe): EmojiRevealStyle {
+  const unknown = Object.keys(recipe.properties).filter((key) => !KEYS.has(key));
+  if (unknown.length > 0) fail(recipe, `does not accept ${unknown.join(", ")}.`);
+  const style: EmojiRevealStyle = {
+    id,
+    centerX: numeric(recipe, "center-x", 0.5), topY: numeric(recipe, "top-y", 0.07),
+    slotSizePx: numeric(recipe, "slot-size", 72), gapPx: numeric(recipe, "slot-gap", 10),
+    paddingXPx: numeric(recipe, "padding-x", 18), paddingYPx: numeric(recipe, "padding-y", 14),
+    background: text(recipe, "background", "#FFFDF7"), borderColor: text(recipe, "border-color", "#161616"),
+    borderWidthPx: numeric(recipe, "border-width", 4), radiusPx: numeric(recipe, "radius", 22),
+    shadowColor: text(recipe, "shadow-color", "#000000B8"), shadowXPx: numeric(recipe, "shadow-x", 9),
+    shadowYPx: numeric(recipe, "shadow-y", 10), shadowBlurPx: numeric(recipe, "shadow-blur", 0),
+    shadowSpreadPx: numeric(recipe, "shadow-spread", 0), iconSizePx: numeric(recipe, "icon-size", 48),
+    revealFrames: integer(recipe, "reveal-frames", 6), stackingOrder: integer(recipe, "stack-order", 66),
+  };
+  assertEmojiRevealStyle(style);
+  return canonicalize(style) as unknown as EmojiRevealStyle;
+}