@scenar/sdk 0.0.1

package/proto/proto-types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Structural types mirroring the proto-generated TypeScript stubs.
+ *
+ * The SDK accepts values matching these shapes via structural subtyping.
+ * This avoids a hard dependency on the generated stubs — consumers
+ * pass proto-generated objects directly and TypeScript validates
+ * compatibility structurally.
+ *
+ * Field names match protoc-gen-es v2 output (camelCase).
+ */
+/** Mirrors generated `ActionType` enum values. */
+export declare const PROTO_ACTION_TYPE: {
+    readonly unspecified: 0;
+    readonly set_cursor: 1;
+    readonly clear_cursor: 2;
+    readonly click: 3;
+    readonly type: 4;
+    readonly hover: 5;
+    readonly drag: 6;
+    readonly scroll_to: 7;
+    readonly viewport_transition: 8;
+};
+export type ProtoActionTypeValue = (typeof PROTO_ACTION_TYPE)[keyof typeof PROTO_ACTION_TYPE];
+/** Structural shape of a proto `ViewportConfig` message. */
+export interface ProtoViewportConfig {
+    readonly width: number;
+    readonly height: number;
+}
+/** Structural shape of a proto `TypeConfig` message. */
+export interface ProtoTypeConfig {
+    readonly text: string;
+    readonly typeDelayMs: number;
+}
+/** Structural shape of a proto `HoverConfig` message. */
+export interface ProtoHoverConfig {
+    readonly hoverDurationMs: number;
+}
+/** Structural shape of a proto `DragConfig` message. */
+export interface ProtoDragConfig {
+    readonly dragTarget: string;
+}
+/** Structural shape of a proto `ViewportTransitionConfig` message. */
+export interface ProtoViewportTransitionConfig {
+    readonly viewportZoom: number;
+    readonly viewportReset: boolean;
+}
+/**
+ * Structural shape of the proto `StepAction.config` oneof.
+ * Matches protoc-gen-es v2's discriminated union output.
+ */
+export type ProtoStepActionConfig = {
+    case: "clickConfig";
+    value: object;
+} | {
+    case: "typeConfig";
+    value: ProtoTypeConfig;
+} | {
+    case: "hoverConfig";
+    value: ProtoHoverConfig;
+} | {
+    case: "dragConfig";
+    value: ProtoDragConfig;
+} | {
+    case: "scrollToConfig";
+    value: object;
+} | {
+    case: "viewportTransitionConfig";
+    value: ProtoViewportTransitionConfig;
+} | {
+    case: undefined;
+    value?: undefined;
+};
+/** Structural shape of a proto `StepAction` message. */
+export interface ProtoStepAction {
+    readonly atPercent: number;
+    readonly type: number;
+    readonly target: string;
+    readonly config: ProtoStepActionConfig;
+}
+/**
+ * Structural shape of a proto `Step` message.
+ * `props` is `JsonObject` (protoc-gen-es v2 auto-converts `Struct`).
+ */
+export interface ProtoStep {
+    readonly view: string;
+    readonly delayMs: number;
+    readonly caption: string;
+    readonly narrationText: string;
+    readonly props?: Record<string, unknown>;
+    readonly interactions: readonly ProtoStepAction[];
+}
+/** Structural shape of the proto `Scenario` message. */
+export interface ProtoScenario {
+    readonly viewport?: ProtoViewportConfig;
+    readonly steps: readonly ProtoStep[];
+}
+//# sourceMappingURL=proto-types.d.ts.map

package/proto/proto-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proto-types.d.ts","sourceRoot":"","sources":["../../src/proto/proto-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kDAAkD;AAClD,eAAO,MAAM,iBAAiB;;;;;;;;;;CAUpB,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE9F,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,sEAAsE;AACtE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,eAAe,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,0BAA0B,CAAC;IAAC,KAAK,EAAE,6BAA6B,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAE3C,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,SAAS,eAAe,EAAE,CAAC;CACnD;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC"}

package/proto/proto-types.js

@@ -0,0 +1,23 @@
+/**
+ * Structural types mirroring the proto-generated TypeScript stubs.
+ *
+ * The SDK accepts values matching these shapes via structural subtyping.
+ * This avoids a hard dependency on the generated stubs — consumers
+ * pass proto-generated objects directly and TypeScript validates
+ * compatibility structurally.
+ *
+ * Field names match protoc-gen-es v2 output (camelCase).
+ */
+/** Mirrors generated `ActionType` enum values. */
+export const PROTO_ACTION_TYPE = {
+    unspecified: 0,
+    set_cursor: 1,
+    clear_cursor: 2,
+    click: 3,
+    type: 4,
+    hover: 5,
+    drag: 6,
+    scroll_to: 7,
+    viewport_transition: 8,
+};
+//# sourceMappingURL=proto-types.js.map

package/proto/proto-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proto-types.js","sourceRoot":"","sources":["../../src/proto/proto-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kDAAkD;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,WAAW,EAAE,CAAC;IACd,UAAU,EAAE,CAAC;IACb,YAAY,EAAE,CAAC;IACf,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,SAAS,EAAE,CAAC;IACZ,mBAAmB,EAAE,CAAC;CACd,CAAC"}

package/src/__tests__/action-mapper.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "vitest";
+import { mapProtoAction } from "../proto/action-mapper.js";
+import { PROTO_ACTION_TYPE, type ProtoStepAction } from "../proto/proto-types.js";
+
+function makeAction(overrides: Partial<ProtoStepAction>): ProtoStepAction {
+  return {
+    atPercent: 0.5,
+    type: PROTO_ACTION_TYPE.click,
+    target: "btn",
+    config: { case: undefined },
+    ...overrides,
+  };
+}
+
+describe("mapProtoAction", () => {
+  it("maps set_cursor", () => {
+    const result = mapProtoAction(
+      makeAction({ type: PROTO_ACTION_TYPE.set_cursor, target: "el" }),
+      "test",
+    );
+    expect(result.type).toBe("set_cursor");
+    expect(result.target).toBe("el");
+    expect(result.atPercent).toBe(0.5);
+  });
+
+  it("maps clear_cursor", () => {
+    const result = mapProtoAction(
+      makeAction({ type: PROTO_ACTION_TYPE.clear_cursor, target: "" }),
+      "test",
+    );
+    expect(result.type).toBe("clear_cursor");
+    expect(result.target).toBeUndefined();
+  });
+
+  it("maps click", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.click,
+        config: { case: "clickConfig", value: {} },
+      }),
+      "test",
+    );
+    expect(result.type).toBe("click");
+    expect(result.target).toBe("btn");
+  });
+
+  it("maps type with typeConfig", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.type,
+        config: {
+          case: "typeConfig",
+          value: { text: "hello", typeDelayMs: 80 },
+        },
+      }),
+      "test",
+    );
+    expect(result.type).toBe("type");
+    expect(result.text).toBe("hello");
+    expect(result.typeDelay).toBe(80);
+  });
+
+  it("maps type with zero typeDelayMs as undefined (engine default)", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.type,
+        config: {
+          case: "typeConfig",
+          value: { text: "hi", typeDelayMs: 0 },
+        },
+      }),
+      "test",
+    );
+    expect(result.typeDelay).toBeUndefined();
+  });
+
+  it("maps hover with hoverConfig", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.hover,
+        config: {
+          case: "hoverConfig",
+          value: { hoverDurationMs: 2000 },
+        },
+      }),
+      "test",
+    );
+    expect(result.type).toBe("hover");
+    expect(result.hoverDuration).toBe(2000);
+  });
+
+  it("maps hover with zero hoverDurationMs as undefined (engine default)", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.hover,
+        config: {
+          case: "hoverConfig",
+          value: { hoverDurationMs: 0 },
+        },
+      }),
+      "test",
+    );
+    expect(result.hoverDuration).toBeUndefined();
+  });
+
+  it("maps drag with dragConfig", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.drag,
+        target: "card",
+        config: {
+          case: "dragConfig",
+          value: { dragTarget: "slot" },
+        },
+      }),
+      "test",
+    );
+    expect(result.type).toBe("drag");
+    expect(result.target).toBe("card");
+    expect(result.dragTarget).toBe("slot");
+  });
+
+  it("maps scroll_to", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.scroll_to,
+        target: "section",
+        config: { case: "scrollToConfig", value: {} },
+      }),
+      "test",
+    );
+    expect(result.type).toBe("scroll_to");
+    expect(result.target).toBe("section");
+  });
+
+  it("maps viewport_transition with config", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.viewport_transition,
+        target: "panel",
+        config: {
+          case: "viewportTransitionConfig",
+          value: { viewportZoom: 2.0, viewportReset: false },
+        },
+      }),
+      "test",
+    );
+    expect(result.type).toBe("viewport_transition");
+    expect(result.viewportZoom).toBe(2.0);
+    expect(result.viewportReset).toBeUndefined();
+  });
+
+  it("maps viewport_transition with reset", () => {
+    const result = mapProtoAction(
+      makeAction({
+        type: PROTO_ACTION_TYPE.viewport_transition,
+        config: {
+          case: "viewportTransitionConfig",
+          value: { viewportZoom: 0, viewportReset: true },
+        },
+      }),
+      "test",
+    );
+    expect(result.viewportReset).toBe(true);
+  });
+
+  it("throws InvalidScenarioError for unspecified action type", () => {
+    expect(() =>
+      mapProtoAction(
+        makeAction({ type: PROTO_ACTION_TYPE.unspecified }),
+        "spec.steps[2].interactions[0]",
+      ),
+    ).toThrow(/unknown ActionType value 0/);
+  });
+
+  it("throws InvalidScenarioError for unknown numeric type", () => {
+    expect(() =>
+      mapProtoAction(makeAction({ type: 99 }), "spec.steps[0].interactions[0]"),
+    ).toThrow(/unknown ActionType value 99/);
+  });
+
+  it("error includes the provided path", () => {
+    try {
+      mapProtoAction(
+        makeAction({ type: PROTO_ACTION_TYPE.unspecified }),
+        "spec.steps[3].interactions[1]",
+      );
+      expect.fail("should have thrown");
+    } catch (e) {
+      expect((e as { path: string }).path).toBe(
+        "spec.steps[3].interactions[1].type",
+      );
+    }
+  });
+});

package/src/__tests__/createScenario.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { createScenario } from "../author/createScenario.js";
+
+interface SettingsProps {
+  readonly org: string;
+}
+
+interface FormProps {
+  readonly defaultName: string;
+}
+
+function SettingsView(_props: SettingsProps): unknown {
+  return null;
+}
+
+function FormView(_props: FormProps): unknown {
+  return null;
+}
+
+describe("createScenario", () => {
+  it("builds an AuthoredScenario from valid input", () => {
+    const scenario = createScenario({
+      viewport: { width: 896, height: 540 },
+      views: { settings: SettingsView, form: FormView },
+      steps: [
+        { view: "settings", delayMs: 0, caption: "Start", props: { org: "acme" } },
+        {
+          view: "form",
+          delayMs: 1500,
+          caption: "Fill",
+          narrationText: "Enter your key name.",
+          props: { defaultName: "demo" },
+          interactions: [
+            { atPercent: 0.2, type: "type", target: "name-input", text: "quickstart" },
+          ],
+        },
+      ],
+    });
+
+    expect(scenario.viewport).toEqual({ width: 896, height: 540 });
+    expect(scenario.steps).toHaveLength(2);
+
+    expect(scenario.steps[0]!.delayMs).toBe(0);
+    expect(scenario.steps[0]!.data.view).toBe("settings");
+    expect(scenario.steps[0]!.data.props).toEqual({ org: "acme" });
+    expect(scenario.steps[0]!.caption).toBe("Start");
+    expect(scenario.steps[0]!.interactions).toBeUndefined();
+
+    expect(scenario.steps[1]!.delayMs).toBe(1500);
+    expect(scenario.steps[1]!.data.view).toBe("form");
+    expect(scenario.steps[1]!.data.props).toEqual({ defaultName: "demo" });
+    expect(scenario.steps[1]!.narration).toBe("Enter your key name.");
+    expect(scenario.steps[1]!.interactions).toHaveLength(1);
+    expect(scenario.steps[1]!.interactions![0]!.type).toBe("type");
+    expect(scenario.steps[1]!.interactions![0]!.text).toBe("quickstart");
+  });
+
+  it("preserves view registry on the output", () => {
+    const views = { settings: SettingsView };
+    const scenario = createScenario({
+      views,
+      steps: [{ view: "settings", delayMs: 0, props: { org: "a" } }],
+    });
+
+    expect(scenario.views).toBe(views);
+  });
+
+  it("accepts undefined viewport", () => {
+    const scenario = createScenario({
+      views: { settings: SettingsView },
+      steps: [{ view: "settings", delayMs: 0, props: { org: "a" } }],
+    });
+
+    expect(scenario.viewport).toBeUndefined();
+  });
+
+  it("throws when steps array is empty", () => {
+    expect(() =>
+      createScenario({
+        views: { settings: SettingsView },
+        steps: [],
+      }),
+    ).toThrow("steps array must not be empty");
+  });
+
+  it("throws when a step references an unregistered view", () => {
+    expect(() =>
+      createScenario({
+        views: { settings: SettingsView },
+        steps: [
+          // @ts-expect-error — intentional runtime error test
+          { view: "nonexistent", delayMs: 0, props: {} },
+        ],
+      }),
+    ).toThrow(/step\[0\]\.view "nonexistent" is not in the views registry/);
+  });
+
+  it("maps narrationText to the engine narration field", () => {
+    const scenario = createScenario({
+      views: { settings: SettingsView },
+      steps: [
+        { view: "settings", delayMs: 0, narrationText: "Hello", props: { org: "a" } },
+      ],
+    });
+
+    expect(scenario.steps[0]!.narration).toBe("Hello");
+  });
+});

package/src/__tests__/load-scenario.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from "vitest";
+import { loadScenarioFromProto } from "../proto/load-scenario.js";
+import { InvalidScenarioError } from "../proto/errors.js";
+import { PROTO_ACTION_TYPE, type ProtoScenario } from "../proto/proto-types.js";
+
+interface SettingsProps {
+  readonly org: string;
+}
+
+interface FormProps {
+  readonly defaultName: string;
+}
+
+function SettingsView(_props: SettingsProps): unknown {
+  return null;
+}
+
+function FormView(_props: FormProps): unknown {
+  return null;
+}
+
+const views = { settings: SettingsView, form: FormView };
+
+function makeValidScenario(): ProtoScenario {
+  return {
+    viewport: { width: 896, height: 540 },
+    steps: [
+      {
+        view: "settings",
+        delayMs: 0,
+        caption: "Start here",
+        narrationText: "Welcome.",
+        props: { org: "acme" },
+        interactions: [],
+      },
+      {
+        view: "form",
+        delayMs: 1500,
+        caption: "Fill the form",
+        narrationText: "",
+        props: { defaultName: "demo" },
+        interactions: [
+          {
+            atPercent: 0.2,
+            type: PROTO_ACTION_TYPE.type,
+            target: "name-input",
+            config: {
+              case: "typeConfig" as const,
+              value: { text: "quickstart", typeDelayMs: 0 },
+            },
+          },
+        ],
+      },
+    ],
+  };
+}
+
+describe("loadScenarioFromProto", () => {
+  it("loads a valid proto scenario into an AuthoredScenario", () => {
+    const scenario = loadScenarioFromProto(makeValidScenario(), { views });
+
+    expect(scenario.viewport).toEqual({ width: 896, height: 540 });
+    expect(scenario.steps).toHaveLength(2);
+    expect(scenario.views).toBe(views);
+
+    expect(scenario.steps[0]!.data.view).toBe("settings");
+    expect(scenario.steps[0]!.delayMs).toBe(0);
+    expect(scenario.steps[0]!.caption).toBe("Start here");
+    expect(scenario.steps[0]!.narration).toBe("Welcome.");
+    expect(scenario.steps[0]!.interactions).toBeUndefined();
+
+    expect(scenario.steps[1]!.data.view).toBe("form");
+    expect(scenario.steps[1]!.delayMs).toBe(1500);
+    expect(scenario.steps[1]!.interactions).toHaveLength(1);
+    expect(scenario.steps[1]!.interactions![0]!.type).toBe("type");
+    expect(scenario.steps[1]!.interactions![0]!.text).toBe("quickstart");
+  });
+
+  it("passes through props from proto Struct as plain object", () => {
+    const scenario = loadScenarioFromProto(makeValidScenario(), { views });
+
+    expect(scenario.steps[0]!.data.props).toEqual({ org: "acme" });
+    expect(scenario.steps[1]!.data.props).toEqual({ defaultName: "demo" });
+  });
+
+  it("defaults props to empty object when proto props is undefined", () => {
+    const proto = makeValidScenario();
+    const step = { ...proto.steps[0]!, props: undefined };
+    const modified: ProtoScenario = {
+      ...proto,
+      steps: [step],
+    };
+
+    const scenario = loadScenarioFromProto(modified, { views });
+    expect(scenario.steps[0]!.data.props).toEqual({});
+  });
+
+  it("handles scenario with no viewport", () => {
+    const proto = makeValidScenario();
+    const modified: ProtoScenario = {
+      ...proto,
+      viewport: undefined,
+    };
+
+    const scenario = loadScenarioFromProto(modified, { views });
+    expect(scenario.viewport).toBeUndefined();
+  });
+
+  it("throws when steps array is empty", () => {
+    const proto: ProtoScenario = { steps: [] };
+
+    expect(() => loadScenarioFromProto(proto, { views })).toThrow(
+      /steps array must not be empty/,
+    );
+  });
+
+  it("throws when a step references an unregistered view", () => {
+    const modified: ProtoScenario = {
+      steps: [
+        {
+          view: "unknown-view",
+          delayMs: 0,
+          caption: "",
+          narrationText: "",
+          interactions: [],
+        },
+      ],
+    };
+
+    try {
+      loadScenarioFromProto(modified, { views });
+      expect.fail("should have thrown");
+    } catch (e) {
+      const err = e as InvalidScenarioError;
+      expect(err.path).toBe("steps[0].view");
+      expect(err.reason).toContain("unknown-view");
+      expect(err.reason).toContain("settings");
+      expect(err.reason).toContain("form");
+    }
+  });
+
+  it("throws when an action has unspecified type", () => {
+    const proto = makeValidScenario();
+    const modified: ProtoScenario = {
+      ...proto,
+      steps: [
+        {
+          ...proto.steps[0]!,
+          interactions: [
+            {
+              atPercent: 0.5,
+              type: PROTO_ACTION_TYPE.unspecified,
+              target: "x",
+              config: { case: undefined },
+            },
+          ],
+        },
+      ],
+    };
+
+    try {
+      loadScenarioFromProto(modified, { views });
+      expect.fail("should have thrown");
+    } catch (e) {
+      const err = e as InvalidScenarioError;
+      expect(err.path).toBe("steps[0].interactions[0].type");
+    }
+  });
+
+  it("omits empty narration and caption strings", () => {
+    const modified: ProtoScenario = {
+      steps: [
+        {
+          view: "settings",
+          delayMs: 0,
+          caption: "",
+          narrationText: "",
+          interactions: [],
+        },
+      ],
+    };
+
+    const scenario = loadScenarioFromProto(modified, { views });
+    expect(scenario.steps[0]!.caption).toBeUndefined();
+    expect(scenario.steps[0]!.narration).toBeUndefined();
+  });
+});

package/src/author/createScenario.ts

@@ -0,0 +1,64 @@
+import type { ScenarioStep } from "@scenar/core";
+import type {
+  AuthoredScenario,
+  AuthoredStepData,
+  ScenarioInput,
+  StepInput,
+  ViewRegistry,
+} from "./types.js";
+
+/**
+ * Build a type-safe scenario from a view registry and step definitions.
+ *
+ * Each step's `props` is statically validated against the component
+ * registered under its `view` name — no `any`, no `JsonObject`.
+ *
+ * ```ts
+ * const scenario = createScenario({
+ *   viewport: { width: 896, height: 540 },
+ *   views: { settings: SettingsView, form: FormView },
+ *   steps: [
+ *     { view: "settings", delayMs: 0, props: { org: "acme" } },
+ *     { view: "form", delayMs: 1500, props: { defaultName: "demo" } },
+ *   ],
+ * });
+ * ```
+ *
+ * @throws {Error} if `steps` is empty or a step references an
+ *   unregistered view name.
+ */
+export function createScenario<Views extends ViewRegistry>(
+  input: ScenarioInput<Views>,
+): AuthoredScenario<Views> {
+  if (input.steps.length === 0) {
+    throw new Error("[scenar] createScenario: steps array must not be empty.");
+  }
+
+  const viewNames = new Set(Object.keys(input.views));
+  const steps: ScenarioStep<AuthoredStepData<Views>>[] = [];
+
+  for (let i = 0; i < input.steps.length; i++) {
+    const step = input.steps[i] as StepInput<Views>;
+
+    if (!viewNames.has(step.view)) {
+      throw new Error(
+        `[scenar] createScenario: step[${i}].view "${step.view}" is not in the views registry. ` +
+        `Registered views: ${[...viewNames].join(", ")}.`,
+      );
+    }
+
+    steps.push({
+      delayMs: step.delayMs,
+      data: { view: step.view, props: step.props } as AuthoredStepData<Views>,
+      caption: step.caption,
+      narration: step.narrationText,
+      interactions: step.interactions,
+    });
+  }
+
+  return {
+    viewport: input.viewport,
+    views: input.views,
+    steps,
+  };
+}