@scenar/sdk 0.0.1

package/src/author/types.ts

@@ -0,0 +1,76 @@
+import type { ScenarioStep, StepAction } from "@scenar/core";
+
+/**
+ * A view registry maps opaque view identifiers (strings) to
+ * "anything that accepts props." The SDK is framework-agnostic:
+ * values do NOT have to be React components — any callable with
+ * a single-parameter signature satisfies the constraint.
+ *
+ * The player's render prop is what actually calls the component.
+ * The SDK only uses the registry for type-level prop inference.
+ */
+export type ViewRegistry = Record<string, (props: never) => unknown>;
+
+/**
+ * Extract the props type from a view entry in the registry.
+ * Falls back to `Record<string, never>` for entries that accept
+ * no parameters (zero-prop components).
+ */
+export type PropsOf<V> = V extends (props: infer P) => unknown ? P : Record<string, never>;
+
+/** Viewport dimensions for deterministic rendering. */
+export interface ViewportConfig {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The data payload on each `ScenarioStep` produced by `createScenario`.
+ * This is a discriminated union keyed on `view`, where `props` is
+ * statically typed against the component registered under that view name.
+ */
+export type AuthoredStepData<Views extends ViewRegistry> = {
+  [K in keyof Views & string]: {
+    readonly view: K;
+    readonly props: PropsOf<Views[K]>;
+  };
+}[keyof Views & string];
+
+/**
+ * A single step as the author writes it in `createScenario({ steps: [...] })`.
+ *
+ * The generic parameter distributes over view keys so TypeScript
+ * narrows `props` based on the `view` discriminant.
+ */
+export type StepInput<Views extends ViewRegistry> = {
+  [K in keyof Views & string]: {
+    readonly view: K;
+    readonly delayMs: number;
+    readonly caption?: string;
+    readonly narrationText?: string;
+    readonly props: PropsOf<Views[K]>;
+    readonly interactions?: readonly StepAction[];
+  };
+}[keyof Views & string];
+
+/**
+ * Input to `createScenario()`.
+ */
+export interface ScenarioInput<Views extends ViewRegistry> {
+  /** Canonical viewport dimensions. Optional — the engine has defaults. */
+  readonly viewport?: ViewportConfig;
+  /** Map of view identifiers to components / callables. */
+  readonly views: Views;
+  /** Ordered sequence of steps. Must contain at least one entry. */
+  readonly steps: readonly StepInput<Views>[];
+}
+
+/**
+ * The output of `createScenario()` — ready to feed into
+ * `<ScenarioPlayer>` with a trivial render prop.
+ */
+export interface AuthoredScenario<Views extends ViewRegistry> {
+  readonly viewport: ViewportConfig | undefined;
+  readonly views: Views;
+  readonly steps: readonly ScenarioStep<AuthoredStepData<Views>>[];
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// @scenar/sdk — public API
+// Typed authoring surface for Scenar scenarios.
+
+// TS-first builder
+export { createScenario } from "./author/createScenario.js";
+export type {
+  AuthoredScenario,
+  AuthoredStepData,
+  ViewRegistry,
+  ViewportConfig,
+  StepInput,
+  ScenarioInput,
+  PropsOf,
+} from "./author/types.js";
+
+// Proto adapter
+export { loadScenarioFromProto } from "./proto/load-scenario.js";
+export type { LoadScenarioOptions } from "./proto/load-scenario.js";
+export { InvalidScenarioError } from "./proto/errors.js";
+
+// Proto structural types (for consumers building custom loaders)
+export { PROTO_ACTION_TYPE } from "./proto/proto-types.js";
+export type {
+  ProtoActionTypeValue,
+  ProtoScenario,
+  ProtoStep,
+  ProtoStepAction,
+  ProtoStepActionConfig,
+  ProtoViewportConfig,
+} from "./proto/proto-types.js";

package/src/proto/action-mapper.ts

@@ -0,0 +1,82 @@
+import type { ActionType, StepAction } from "@scenar/core";
+import { InvalidScenarioError } from "./errors.js";
+import { PROTO_ACTION_TYPE, type ProtoStepAction } from "./proto-types.js";
+
+const NUMERIC_TO_ACTION_TYPE: ReadonlyMap<number, ActionType> = new Map([
+  [PROTO_ACTION_TYPE.set_cursor, "set_cursor"],
+  [PROTO_ACTION_TYPE.clear_cursor, "clear_cursor"],
+  [PROTO_ACTION_TYPE.click, "click"],
+  [PROTO_ACTION_TYPE.type, "type"],
+  [PROTO_ACTION_TYPE.hover, "hover"],
+  [PROTO_ACTION_TYPE.drag, "drag"],
+  [PROTO_ACTION_TYPE.scroll_to, "scroll_to"],
+  [PROTO_ACTION_TYPE.viewport_transition, "viewport_transition"],
+]);
+
+/**
+ * Map a proto `StepAction` message to the engine's `StepAction` type.
+ *
+ * Expands the proto `config` oneof into flat optional fields on the
+ * engine action. ActionType numeric enum → string literal. Since we
+ * aligned the engine's ActionType strings with proto enum names in
+ * Phase 1, this is a direct name copy.
+ *
+ * @param proto - The proto StepAction message (structural shape).
+ * @param path  - JSON-path prefix for error reporting.
+ */
+export function mapProtoAction(proto: ProtoStepAction, path: string): StepAction {
+  const actionType = NUMERIC_TO_ACTION_TYPE.get(proto.type);
+
+  if (actionType === undefined) {
+    throw new InvalidScenarioError(
+      `${path}.type`,
+      `unknown ActionType value ${proto.type}. Expected one of: ${[...NUMERIC_TO_ACTION_TYPE.keys()].join(", ")}.`,
+    );
+  }
+
+  const base: StepAction = {
+    atPercent: proto.atPercent,
+    type: actionType,
+    target: proto.target || undefined,
+  };
+
+  const config = proto.config;
+  if (!config.case) return base;
+
+  switch (config.case) {
+    case "clickConfig":
+    case "scrollToConfig":
+      return base;
+
+    case "typeConfig":
+      return {
+        ...base,
+        text: config.value.text,
+        typeDelay: config.value.typeDelayMs || undefined,
+      };
+
+    case "hoverConfig":
+      return {
+        ...base,
+        hoverDuration: config.value.hoverDurationMs || undefined,
+      };
+
+    case "dragConfig":
+      return {
+        ...base,
+        dragTarget: config.value.dragTarget,
+      };
+
+    case "viewportTransitionConfig":
+      return {
+        ...base,
+        viewportZoom: config.value.viewportZoom || undefined,
+        viewportReset: config.value.viewportReset || undefined,
+      };
+
+    default: {
+      const _exhaustive: never = config;
+      return _exhaustive;
+    }
+  }
+}

package/src/proto/errors.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown when a proto `Scenario` message fails validation during
+ * `loadScenarioFromProto`. Includes the JSON-path to the offending
+ * field and a human-readable reason.
+ */
+export class InvalidScenarioError extends Error {
+  readonly path: string;
+  readonly reason: string;
+
+  constructor(path: string, reason: string) {
+    super(`[scenar] Invalid scenario at ${path}: ${reason}`);
+    this.name = "InvalidScenarioError";
+    this.path = path;
+    this.reason = reason;
+  }
+}

package/src/proto/load-scenario.ts

@@ -0,0 +1,81 @@
+import type { ScenarioStep } from "@scenar/core";
+import type {
+  AuthoredScenario,
+  AuthoredStepData,
+  ViewRegistry,
+} from "../author/types.js";
+import { InvalidScenarioError } from "./errors.js";
+import type { ProtoScenario } from "./proto-types.js";
+import { mapProtoAction } from "./action-mapper.js";
+
+/**
+ * Options for {@link loadScenarioFromProto}.
+ */
+export interface LoadScenarioOptions<Views extends ViewRegistry> {
+  /** Map of view identifiers to components / callables. */
+  readonly views: Views;
+}
+
+/**
+ * Convert a proto `Scenario` message into an `AuthoredScenario`
+ * ready for `<ScenarioPlayer>`.
+ *
+ * This is the YAML ingestion path: a scenario parsed from protobuf
+ * (or proto-JSON) enters here and comes out as the same shape that
+ * `createScenario()` produces.
+ *
+ * Ensures every step's `view` exists in the views registry and maps
+ * proto `StepAction` messages to engine `StepAction` values.
+ *
+ * @throws {InvalidScenarioError} with a path and reason on any
+ *   structural or semantic validation failure.
+ */
+export function loadScenarioFromProto<Views extends ViewRegistry>(
+  scenario: ProtoScenario,
+  options: LoadScenarioOptions<Views>,
+): AuthoredScenario<Views> {
+  if (scenario.steps.length === 0) {
+    throw new InvalidScenarioError("steps", "steps array must not be empty.");
+  }
+
+  const viewNames = new Set(Object.keys(options.views));
+  const steps: ScenarioStep<AuthoredStepData<Views>>[] = [];
+
+  for (let i = 0; i < scenario.steps.length; i++) {
+    const protoStep = scenario.steps[i]!;
+    const stepPath = `steps[${i}]`;
+
+    if (!protoStep.view) {
+      throw new InvalidScenarioError(`${stepPath}.view`, "view is required.");
+    }
+
+    if (!viewNames.has(protoStep.view)) {
+      throw new InvalidScenarioError(
+        `${stepPath}.view`,
+        `"${protoStep.view}" is not in the views registry. ` +
+        `Registered views: ${[...viewNames].join(", ")}.`,
+      );
+    }
+
+    const interactions = protoStep.interactions.map((protoAction, j) =>
+      mapProtoAction(protoAction, `${stepPath}.interactions[${j}]`),
+    );
+
+    steps.push({
+      delayMs: protoStep.delayMs,
+      data: {
+        view: protoStep.view,
+        props: (protoStep.props ?? {}) as AuthoredStepData<Views>["props"],
+      } as AuthoredStepData<Views>,
+      caption: protoStep.caption || undefined,
+      narration: protoStep.narrationText || undefined,
+      interactions: interactions.length > 0 ? interactions : undefined,
+    });
+  }
+
+  return {
+    viewport: scenario.viewport ? { width: scenario.viewport.width, height: scenario.viewport.height } : undefined,
+    views: options.views,
+    steps,
+  };
+}

package/src/proto/proto-types.ts

@@ -0,0 +1,93 @@
+/**
+ * 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,
+} as const;
+
+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[];
+}