@gatherround/sdk 0.4.1

package/dist/runtime-types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * runtime-types.ts
+ *
+ * Node-level runtime types: nodes, transitions, conditions, mutations.
+ * These define the structure of individual story graph nodes within a RuntimeEpisode.
+ */
+export interface RuntimeNode {
+    id: string;
+    kind: string;
+    /** Author's label for this node (debugging / game-log use). */
+    label?: string;
+    /**
+     * Kind-specific payload. Shape varies by kind:
+     *   play_video:   { url, loop, pipTarget, onPlay, timeEvents }
+     *   hero_action:  { prompt, choices: { text, mutations? }[], targetRoles, timer? }
+     *   trigger_qte:  { text, timeLimit, targetRoles, qteType, difficulty }
+     *   vote:         { prompt, options, timeLimit, tallyMode, targetRoles }
+     *   explore:      { options: { text, image?, showOnce }[], target_roles, locationLabel?, locationImage? }
+     *   set_variable: absent (uses mutations)
+     *   logic:        absent (uses conditions + mutations)
+     *   end_episode:  absent (terminal node — no payload, no transitions)
+     */
+    payload?: Record<string, unknown>;
+    /** Logic-kind conditions — evaluated top-to-bottom, first match wins.
+     *  Each element is a branch: either a single RuntimeCondition (legacy)
+     *  or a RuntimeConditionGroup (compound boolean logic). */
+    conditions?: (RuntimeCondition | RuntimeConditionGroup)[];
+    /** Variable mutations — executed on node entry. */
+    mutations?: RuntimeMutation[];
+    /** Compiled transitions from graph edges. */
+    transitions: RuntimeTransition[];
+}
+export interface RuntimeTransition {
+    /** The event that fires this transition. */
+    on: string;
+    /** For choice-based transitions: index into the choices array. */
+    choiceIndex?: number;
+    /** For condition-based transitions: index into the conditions array. */
+    conditionIndex?: number;
+    /** For cue-based transitions: index into the timeEvents array. */
+    cueIndex?: number;
+    /** For exit-based transitions: index into the exits array (explore node). */
+    exitIndex?: number;
+    /** Destination node ID. */
+    target: string;
+}
+export interface RuntimeCondition {
+    variable: string;
+    operator: "eq" | "neq" | "gt" | "lt" | "gte" | "lte";
+    value: string | number | boolean;
+}
+/**
+ * A compound condition branch — multiple atomic conditions combined with
+ * a boolean operator (AND/OR) or an arbitrary formula.
+ */
+export interface RuntimeConditionGroup {
+    conditions: RuntimeCondition[];
+    /** "and" | "or" — uniform inline join. "formula" — uses the `formula` field. */
+    mode: "and" | "or" | "formula";
+    /** Boolean formula string (e.g. "(A & B) | !C"). Only present when mode === "formula". */
+    formula?: string;
+}
+export interface RuntimeMutation {
+    target: string;
+    operation: "set" | "increment" | "decrement";
+    value: string | number | boolean;
+}
+//# sourceMappingURL=runtime-types.d.ts.map

package/dist/runtime-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-types.d.ts","sourceRoot":"","sources":["../src/runtime-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElC;;+DAE2D;IAC3D,UAAU,CAAC,EAAE,CAAC,gBAAgB,GAAG,qBAAqB,CAAC,EAAE,CAAC;IAE1D,mDAAmD;IACnD,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAE9B,6CAA6C;IAC7C,WAAW,EAAE,iBAAiB,EAAE,CAAC;CAClC;AAID,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,CAAC;IACrD,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,gBAAgB,EAAE,CAAC;IAC/B,gFAAgF;IAChF,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;IAC/B,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,KAAK,GAAG,WAAW,GAAG,WAAW,CAAC;IAC7C,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAClC"}

package/dist/runtime-types.js

@@ -0,0 +1,8 @@
+/**
+ * runtime-types.ts
+ *
+ * Node-level runtime types: nodes, transitions, conditions, mutations.
+ * These define the structure of individual story graph nodes within a RuntimeEpisode.
+ */
+export {};
+//# sourceMappingURL=runtime-types.js.map

package/dist/runtime-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-types.js","sourceRoot":"","sources":["../src/runtime-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@gatherround/sdk",
+  "version": "0.4.1",
+  "description": "Shared types, interfaces, and JSON schemas for the Gather Round ecosystem",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stremblay4/gather-round-sdk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "rimraf": "^6.0.0"
+  }
+}

package/src/adapters/i-client-adapter.ts

@@ -0,0 +1,63 @@
+/**
+ * i-client-adapter.ts
+ *
+ * TV engine ↔ platform adapter for session lifecycle and messaging.
+ * The TV app uses this to create sessions, send display instructions
+ * to phone controllers, and receive controller messages.
+ */
+
+import type { ControllerMessage } from "../controller-message.js";
+import type { DisplayInstruction } from "../display-instruction.js";
+
+// ── Supporting types ────────────────────────────────────────────────────────
+
+export interface GameSessionOptions {
+  /** Published episode ID to play. */
+  episodeId: string;
+  /** Published version ID (optional — uses latest if omitted). */
+  versionId?: string;
+  /** Maximum number of players (excluding the TV host). */
+  maxPlayers: number;
+}
+
+export interface GameSessionResult {
+  /** Unique session identifier. */
+  sessionId: string;
+  /** Short alphanumeric code for manual entry (e.g. "A3F9K2"). */
+  sessionCode: string;
+  /** Full URL for phone controller join (embedded in QR code). */
+  controllerUrl: string;
+}
+
+export interface PlayerSessionResult {
+  /** The player's unique ID within this session. */
+  playerId: string;
+  /** The session they joined. */
+  sessionId: string;
+}
+
+// ── Adapter interface ───────────────────────────────────────────────────────
+
+/**
+ * Engine-side adapter for session management and bidirectional messaging.
+ */
+export interface IClientAdapter {
+  // ── Session lifecycle ─────────────────────────────────────────────────
+  createGameSession(options: GameSessionOptions): Promise<GameSessionResult>;
+  joinGameSession(sessionId: string): Promise<PlayerSessionResult>;
+  disconnect(): void;
+
+  // ── Outbound: TV engine → phone controller(s) ────────────────────────
+  sendToController(
+    playerId: string,
+    instruction: DisplayInstruction,
+  ): Promise<void>;
+  broadcastToAll(instruction: DisplayInstruction): Promise<void>;
+
+  // ── Inbound: phone controller → TV engine ────────────────────────────
+  onControllerMessage(
+    cb: (playerId: string, message: ControllerMessage) => void,
+  ): void;
+  onPlayerConnected(cb: (playerId: string) => void): void;
+  onPlayerDisconnected(cb: (playerId: string) => void): void;
+}

package/src/adapters/i-content-adapter.ts

@@ -0,0 +1,28 @@
+/**
+ * i-content-adapter.ts
+ *
+ * TV engine ↔ episode content adapter.
+ * Resolves published episode JSON from whatever storage backend is active
+ * (Firestore registry → GCS for GRG, embedded build for Luna, etc.).
+ */
+
+import type { RuntimeEpisode } from "../runtime-episode.js";
+
+/**
+ * Adapter for loading published episode content at runtime.
+ */
+export interface IContentAdapter {
+  /**
+   * Fetch the latest published episode.
+   * Resolution: platform registry → storage path → parsed JSON.
+   */
+  loadEpisode(episodeId: string): Promise<RuntimeEpisode>;
+
+  /**
+   * Fetch a specific published version (for rollback / pinned builds).
+   */
+  loadEpisodeVersion(
+    episodeId: string,
+    versionId: string,
+  ): Promise<RuntimeEpisode>;
+}

package/src/adapters/i-controller-transport.ts

@@ -0,0 +1,35 @@
+/**
+ * i-controller-transport.ts
+ *
+ * Controller-side transport interface.
+ * The phone controller app uses this to communicate with the TV game engine.
+ * GRG implements this over Firebase RTDB; Luna uses GameLift Realtime JS SDK.
+ */
+
+import type { ControllerMessage } from "../controller-message.js";
+import type { DisplayInstruction } from "../display-instruction.js";
+
+/**
+ * Transport layer for phone controller ↔ TV engine communication.
+ */
+export interface IControllerTransport {
+  /**
+   * Connect to an active session (called after scanning QR / reading URL param).
+   */
+  joinSession(sessionId: string): Promise<void>;
+
+  /**
+   * Send a player input event to the TV engine.
+   */
+  sendInput(message: ControllerMessage): Promise<void>;
+
+  /**
+   * Register a callback for display instructions from the TV engine.
+   */
+  onDisplayInstruction(cb: (instruction: DisplayInstruction) => void): void;
+
+  /**
+   * Tear down transport connection.
+   */
+  disconnect(): void;
+}

package/src/adapters/i-session-adapter.ts

@@ -0,0 +1,67 @@
+/**
+ * i-session-adapter.ts
+ *
+ * TV engine ↔ session persistence adapter.
+ * Manages game session state (variables, scene checkpoints) in whatever
+ * persistence layer the platform provides (RTDB for GRG, save system for Luna, etc.).
+ */
+
+// ── Supporting types ────────────────────────────────────────────────────────
+
+export interface PlayerConfig {
+  /** Player's unique ID (e.g. Firebase UID). */
+  playerId: string;
+  /** Display name. */
+  name: string;
+  /** Assigned hero role slot (0 = host, 1–4 = players). */
+  role: number;
+}
+
+/**
+ * Runtime variable state for an episode session.
+ * Keys are variable names; values are their current runtime values.
+ */
+export type EpisodeVariables = Record<string, boolean | number | string>;
+
+/**
+ * Serializable checkpoint for a scene's execution state.
+ * Shape is intentionally loose — the engine defines what goes in here.
+ */
+export interface SceneCheckpoint {
+  /** Current node ID within the scene. */
+  currentNodeId: string;
+  /** Any additional engine state needed to resume. */
+  [key: string]: unknown;
+}
+
+// ── Adapter interface ───────────────────────────────────────────────────────
+
+/**
+ * Engine-side adapter for session state persistence.
+ */
+export interface ISessionAdapter {
+  createSession(
+    episodeId: string,
+    players: PlayerConfig[],
+  ): Promise<string>;
+
+  getSessionVariables(sessionId: string): Promise<EpisodeVariables>;
+
+  updateSessionVariables(
+    sessionId: string,
+    vars: Partial<EpisodeVariables>,
+  ): Promise<void>;
+
+  saveSceneState(
+    sessionId: string,
+    sceneId: string,
+    state: SceneCheckpoint,
+  ): Promise<void>;
+
+  loadSceneState(
+    sessionId: string,
+    sceneId: string,
+  ): Promise<SceneCheckpoint | null>;
+
+  advanceScene(sessionId: string, nextSceneId: string): Promise<void>;
+}

package/src/controller-message.ts

@@ -0,0 +1,82 @@
+/**
+ * controller-message.ts
+ *
+ * Phone → TV typed event union.
+ * Sent by the phone controller to the TV game engine via IControllerTransport.sendInput().
+ */
+
+// ── Individual message types ────────────────────────────────────────────────
+
+export interface HeroSelected {
+  type: "HeroSelected";
+  /** The hero role slot chosen by this player. */
+  role: number;
+}
+
+export interface QTEResponse {
+  type: "QTEResponse";
+  /** Whether the player succeeded the QTE within the time limit. */
+  success: boolean;
+  /** Reaction time in milliseconds, or null if timed out. */
+  reactionTimeMs: number | null;
+}
+
+export interface ChoiceSelected {
+  type: "ChoiceSelected";
+  /** Index into the node's choices array. */
+  choiceIndex: number;
+}
+
+export interface VoteSubmitted {
+  type: "VoteSubmitted";
+  /** Index into the node's vote options array. */
+  optionIndex: number;
+}
+
+export interface ReadyConfirmed {
+  type: "ReadyConfirmed";
+}
+
+export interface ExploreOptionSelected {
+  type: "ExploreOptionSelected";
+  /** Index into the explore node's options array. */
+  optionIndex: number;
+}
+
+export interface ExploreExitSelected {
+  type: "ExploreExitSelected";
+  /** Index into the explore node's exits array. */
+  exitIndex: number;
+}
+
+export interface ExploreExitVote {
+  type: "ExploreExitVote";
+  /** Whether this player accepts the proposed exit. */
+  accepted: boolean;
+}
+
+export interface PlayerPing {
+  type: "PlayerPing";
+  /** ISO-8601 timestamp from the controller. */
+  timestamp: string;
+}
+
+// ── Union ───────────────────────────────────────────────────────────────────
+
+/**
+ * Discriminated union of all messages a phone controller can send to the TV engine.
+ * Discriminant field: `type`.
+ */
+export type ControllerMessage =
+  | HeroSelected
+  | QTEResponse
+  | ChoiceSelected
+  | VoteSubmitted
+  | ExploreOptionSelected
+  | ExploreExitSelected
+  | ExploreExitVote
+  | ReadyConfirmed
+  | PlayerPing;
+
+/** All possible `type` values for ControllerMessage. */
+export type ControllerMessageType = ControllerMessage["type"];

package/src/display-instruction.ts

@@ -0,0 +1,105 @@
+/**
+ * display-instruction.ts
+ *
+ * TV → Phone typed payload union.
+ * Sent by the TV game engine to phone controllers via IClientAdapter.sendToController().
+ */
+
+// ── Individual instruction types ────────────────────────────────────────────
+
+export interface RenderLayout {
+  type: "RenderLayout";
+  /** Layout template identifier (e.g. "choice_prompt", "qte_tap", "vote_grid"). */
+  template: string;
+  /** Template-specific data — shape varies by template. */
+  data: Record<string, unknown>;
+}
+
+export interface ShowPrompt {
+  type: "ShowPrompt";
+  /** Prompt text to display. */
+  text: string;
+  /** Optional choices for the player. */
+  choices?: string[];
+  /** Optional timer duration in seconds. */
+  timerSeconds?: number;
+  /** Hero profile image URL for the controller top bar, or null if unset. */
+  heroProfileImg?: string | null;
+}
+
+export interface ShowFeedback {
+  type: "ShowFeedback";
+  /** Feedback message (e.g. "Correct!", "Time's up!"). */
+  text: string;
+  /** Visual style hint. */
+  style: "success" | "failure" | "neutral";
+}
+
+export interface ApplyTheme {
+  type: "ApplyTheme";
+  /** CSS custom properties to apply on the controller. */
+  properties: Record<string, string>;
+}
+
+export interface ShowCountdown {
+  type: "ShowCountdown";
+  /** Duration in seconds. */
+  durationSeconds: number;
+  /** Optional label (e.g. "Get ready!"). */
+  label?: string;
+}
+
+export interface ClearScreen {
+  type: "ClearScreen";
+}
+
+export interface GameTerminated {
+  type: "GameTerminated";
+  /** Optional reason for termination. */
+  reason?: string;
+}
+
+export interface UpdateMeters {
+  type: "UpdateMeters";
+  /** Meter ID → current value. */
+  meters: Record<string, number>;
+}
+
+export interface ScheduledCue {
+  /** Milliseconds from playStartServerTime to show this QTE. */
+  atMs: number;
+  /** Cue index (matches the timeEvent index on the play_video node). */
+  cueIndex: number;
+  /** QTE template (e.g. "qte_tap"). */
+  template: string;
+  /** Template-specific data (text, timeLimit, difficulty, heroProfileImg). */
+  data: Record<string, unknown>;
+}
+
+export interface ScheduleQTE {
+  type: "ScheduleQTE";
+  /** Server timestamp (Date.now() on app) when the video started playing. */
+  playStartServerTime: number;
+  /** Cues to schedule, sorted by atMs ascending. */
+  cues: ScheduledCue[];
+}
+
+// ── Union ───────────────────────────────────────────────────────────────────
+
+/**
+ * Discriminated union of all instructions the TV engine can send to phone controllers.
+ * Discriminant field: `type`.
+ */
+export type DisplayInstruction =
+  | RenderLayout
+  | ShowPrompt
+  | ShowFeedback
+  | ApplyTheme
+  | ShowCountdown
+  | ClearScreen
+  | GameTerminated
+  | UpdateMeters
+  | ScheduleQTE;
+
+/** All possible `type` values for DisplayInstruction. */
+export type DisplayInstructionType = DisplayInstruction["type"];

package/src/index.ts

@@ -0,0 +1,81 @@
+/**
+ * @grg/sdk — Gather Round SDK
+ *
+ * Shared types, interfaces, and schemas for the Gather Round ecosystem.
+ * This package contains contracts only — no business logic, no platform
+ * imports, no React.
+ */
+
+// ── Runtime types (episode.json, strings.en.json, assets.json) ──────────────
+
+export type {
+  RuntimeEpisode,
+  RuntimeHero,
+  RuntimeHeroAttribute,
+  RuntimeMeterDefinition,
+  RuntimeVariable,
+  RuntimeEpisodeAssets,
+} from "./runtime-episode.js";
+
+export type {
+  RuntimeNode,
+  RuntimeTransition,
+  RuntimeCondition,
+  RuntimeConditionGroup,
+  RuntimeMutation,
+} from "./runtime-types.js";
+
+export type { RuntimeStrings } from "./runtime-strings.js";
+
+export type { AssetEntry, RuntimeAssetManifest } from "./runtime-assets.js";
+
+// ── Message protocol ────────────────────────────────────────────────────────
+
+export type {
+  ControllerMessage,
+  ControllerMessageType,
+  HeroSelected,
+  QTEResponse,
+  ChoiceSelected,
+  VoteSubmitted,
+  ExploreOptionSelected,
+  ExploreExitSelected,
+  ExploreExitVote,
+  ReadyConfirmed,
+  PlayerPing,
+} from "./controller-message.js";
+
+export type {
+  DisplayInstruction,
+  DisplayInstructionType,
+  RenderLayout,
+  ShowPrompt,
+  ShowFeedback,
+  ApplyTheme,
+  ShowCountdown,
+  ClearScreen,
+  GameTerminated,
+  UpdateMeters,
+  ScheduledCue,
+  ScheduleQTE,
+} from "./display-instruction.js";
+
+// ── Adapter interfaces ──────────────────────────────────────────────────────
+
+export type { IContentAdapter } from "./adapters/i-content-adapter.js";
+
+export type {
+  IClientAdapter,
+  GameSessionOptions,
+  GameSessionResult,
+  PlayerSessionResult,
+} from "./adapters/i-client-adapter.js";
+
+export type {
+  ISessionAdapter,
+  PlayerConfig,
+  EpisodeVariables,
+  SceneCheckpoint,
+} from "./adapters/i-session-adapter.js";
+
+export type { IControllerTransport } from "./adapters/i-controller-transport.js";

package/src/runtime-assets.ts

@@ -0,0 +1,18 @@
+/**
+ * runtime-assets.ts
+ *
+ * Asset manifest artifact (assets.json).
+ * Lists all media files referenced by the episode for pre-loading.
+ */
+
+export interface AssetEntry {
+  /** GCS bucket name. */
+  bucket: string;
+  /** Object path within the bucket. */
+  path: string;
+  /** Asset type for pre-loading strategy. */
+  type: "video" | "image" | "audio";
+}
+
+/** Keyed by a logical ID (e.g. "hero.1.cardImg", "node-abc.url"). */
+export type RuntimeAssetManifest = Record<string, AssetEntry>;