diff --git a/lib/types/action.ts b/lib/types/action.ts index 33f97a0..484e819 100644 --- a/lib/types/action.ts +++ b/lib/types/action.ts @@ -1,286 +1,44 @@ -/** - * Unified Action System - * - * Actions are the sole mechanism for agents to interact with the presentation. - * Two categories: - * - Fire-and-forget: visual effects on slides (spotlight, laser) - * - Synchronous: must wait for completion before next action (speech, whiteboard, discussion) - * - * Both online (streaming) and offline (playback) paths consume the same Action types. - */ +// Unified Action System. +// +// The Action contract — the playback verb set agents use to drive a +// presentation — now lives in `@openmaic/dsl` and is re-exported below, so the +// runtime engine, renderer, importer, and this app all share one source of +// truth. Both the online (streaming) and offline (playback) paths consume the +// same Action types. +// +// This module is a thin re-export shim (same pattern as `@/lib/types/stage`): +// existing `import { … } from '@/lib/types/action'` callers keep working +// unchanged. -// ==================== Base ==================== +export type { + ActionBase, + SpotlightAction, + LaserAction, + SpeechAction, + WbOpenAction, + WbDrawTextAction, + WbDrawShapeAction, + WbDrawChartAction, + WbDrawLatexAction, + WbDrawTableAction, + WbDrawLineAction, + WbClearAction, + WbDeleteAction, + WbCloseAction, + WbDrawCodeAction, + WbEditCodeAction, + PlayVideoAction, + DiscussionAction, + WidgetHighlightAction, + WidgetSetStateAction, + WidgetAnnotationAction, + WidgetRevealAction, + Action, + ActionType, + PercentageGeometry, +} from '@openmaic/dsl'; -export interface ActionBase { - id: string; - title?: string; - description?: string; -} - -// ==================== Fire-and-forget actions ==================== - -/** Spotlight — focus on a single element, dim everything else */ -export interface SpotlightAction extends ActionBase { - type: 'spotlight'; - elementId: string; - dimOpacity?: number; // default 0.5 -} - -/** Laser — point at an element with a laser effect */ -export interface LaserAction extends ActionBase { - type: 'laser'; - elementId: string; - color?: string; // default '#ff0000' -} - -// ==================== Synchronous actions ==================== - -/** Speech — teacher narration (wait for TTS to finish) */ -export interface SpeechAction extends ActionBase { - type: 'speech'; - text: string; - audioId?: string; - audioUrl?: string; // Server-generated TTS audio URL - voice?: string; - speed?: number; // default 1.0 -} - -/** Open whiteboard (wait for animation) */ -export interface WbOpenAction extends ActionBase { - type: 'wb_open'; -} - -/** Draw text on whiteboard (wait for render) */ -export interface WbDrawTextAction extends ActionBase { - type: 'wb_draw_text'; - elementId?: string; // Custom element ID for later reference (e.g. wb_delete) - content: string; // HTML string or plain text - x: number; - y: number; - width?: number; // default 400 - height?: number; // default 100 - fontSize?: number; // default 18 - color?: string; // default '#333333' -} - -/** Draw shape on whiteboard (wait for render) */ -export interface WbDrawShapeAction extends ActionBase { - type: 'wb_draw_shape'; - elementId?: string; // Custom element ID for later reference (e.g. wb_delete) - shape: 'rectangle' | 'circle' | 'triangle'; - x: number; - y: number; - width: number; - height: number; - fillColor?: string; // default '#5b9bd5' -} - -/** Draw chart on whiteboard (wait for render) */ -export interface WbDrawChartAction extends ActionBase { - type: 'wb_draw_chart'; - elementId?: string; // Custom element ID for later reference (e.g. wb_delete) - chartType: 'bar' | 'column' | 'line' | 'pie' | 'ring' | 'area' | 'radar' | 'scatter'; - x: number; - y: number; - width: number; - height: number; - data: { - labels: string[]; - legends: string[]; - series: number[][]; - }; - themeColors?: string[]; -} - -/** Draw LaTeX formula on whiteboard (wait for render) */ -export interface WbDrawLatexAction extends ActionBase { - type: 'wb_draw_latex'; - elementId?: string; // Custom element ID for later reference (e.g. wb_delete) - latex: string; - x: number; - y: number; - width?: number; // default 400 - height?: number; // auto-calculated based on formula aspect ratio - color?: string; // default '#000000' -} - -/** Draw table on whiteboard (wait for render) */ -export interface WbDrawTableAction extends ActionBase { - type: 'wb_draw_table'; - elementId?: string; // Custom element ID for later reference (e.g. wb_delete) - x: number; - y: number; - width: number; - height: number; - data: string[][]; // Simplified 2D string array, first row is header - outline?: { width: number; style: string; color: string }; - theme?: { color: string }; -} - -/** Draw line/arrow on whiteboard (wait for render) */ -export interface WbDrawLineAction extends ActionBase { - type: 'wb_draw_line'; - elementId?: string; // Custom element ID for later reference (e.g. wb_delete) - startX: number; // Start X position (0-1000) - startY: number; // Start Y position (0-562) - endX: number; // End X position (0-1000) - endY: number; // End Y position (0-562) - color?: string; // Default '#333333' - width?: number; // Line width, default 2 - style?: 'solid' | 'dashed'; // Default 'solid' - points?: ['', 'arrow'] | ['arrow', ''] | ['arrow', 'arrow'] | ['', '']; // Endpoint markers, default ['', ''] -} - -/** Clear all whiteboard elements */ -export interface WbClearAction extends ActionBase { - type: 'wb_clear'; -} - -/** Delete a specific whiteboard element by ID */ -export interface WbDeleteAction extends ActionBase { - type: 'wb_delete'; - elementId: string; -} - -/** Close whiteboard (wait for animation) */ -export interface WbCloseAction extends ActionBase { - type: 'wb_close'; -} - -/** Draw code block on whiteboard (wait for typing animation) */ -export interface WbDrawCodeAction extends ActionBase { - type: 'wb_draw_code'; - elementId?: string; - language: string; - code: string; // Raw code text, lines separated by \n - x: number; - y: number; - width?: number; // Default 500 - height?: number; // Default 300 - fileName?: string; -} - -/** Edit code block on whiteboard (line-level operations) */ -export interface WbEditCodeAction extends ActionBase { - type: 'wb_edit_code'; - elementId: string; // Target code block ID - operation: 'insert_after' | 'insert_before' | 'delete_lines' | 'replace_lines'; - lineId?: string; // Reference line ID for insert operations - lineIds?: string[]; // Target line IDs for delete/replace operations - content?: string; // New content for insert/replace, lines separated by \n -} - -/** Play video — start playback of a video element on the slide */ -export interface PlayVideoAction extends ActionBase { - type: 'play_video'; - elementId: string; -} - -/** Discussion — trigger a roundtable discussion */ -export interface DiscussionAction extends ActionBase { - type: 'discussion'; - topic: string; - prompt?: string; - agentId?: string; -} - -// ==================== Widget Interaction Actions ==================== - -/** Widget Highlight — highlight an element in a widget iframe */ -export interface WidgetHighlightAction extends ActionBase { - type: 'widget_highlight'; - target: string; // CSS selector or element ID in the iframe - content?: string; // Speech text to accompany the highlight -} - -/** Widget SetState — set widget state (e.g., simulation variables) */ -export interface WidgetSetStateAction extends ActionBase { - type: 'widget_setState'; - state: Record; - content?: string; // Speech text to accompany the state change -} - -/** Widget Annotation — add floating annotation to an element */ -export interface WidgetAnnotationAction extends ActionBase { - type: 'widget_annotation'; - target: string; - content?: string; -} - -/** Widget Reveal — reveal hidden content in widget */ -export interface WidgetRevealAction extends ActionBase { - type: 'widget_reveal'; - target: string; - content?: string; -} - -// ==================== Union type ==================== - -export type Action = - | SpotlightAction - | LaserAction - | PlayVideoAction - | SpeechAction - | WbOpenAction - | WbDrawTextAction - | WbDrawShapeAction - | WbDrawChartAction - | WbDrawLatexAction - | WbDrawTableAction - | WbDrawLineAction - | WbClearAction - | WbDeleteAction - | WbCloseAction - | WbDrawCodeAction - | WbEditCodeAction - | DiscussionAction - | WidgetHighlightAction - | WidgetSetStateAction - | WidgetAnnotationAction - | WidgetRevealAction; - -export type ActionType = Action['type']; - -/** Action types that fire immediately without blocking */ -export const FIRE_AND_FORGET_ACTIONS: ActionType[] = ['spotlight', 'laser']; - -/** Action types that only work on slide scenes (require slide canvas elements) */ -export const SLIDE_ONLY_ACTIONS: ActionType[] = ['spotlight', 'laser']; - -/** Action types that must complete before the next action runs */ -export const SYNC_ACTIONS: ActionType[] = [ - 'speech', - 'play_video', - 'wb_open', - 'wb_draw_text', - 'wb_draw_shape', - 'wb_draw_chart', - 'wb_draw_latex', - 'wb_draw_table', - 'wb_draw_line', - 'wb_draw_code', - 'wb_edit_code', - 'wb_clear', - 'wb_delete', - 'wb_close', - 'discussion', - 'widget_highlight', - 'widget_setState', - 'widget_annotation', - 'widget_reveal', -]; - -// ==================== Canvas utility types (non-action) ==================== - -/** - * Percentage-based geometry (0-100 coordinate system) - * Used by spotlight/laser overlays for responsive positioning. - */ -export interface PercentageGeometry { - x: number; // 0-100 - y: number; // 0-100 - w: number; // 0-100 - h: number; // 0-100 - centerX: number; // 0-100 - centerY: number; // 0-100 -} +// The action-category lists are runtime values (plain arrays), so they must be +// value re-exported — a bare `export type {}` would erase them and leave the +// imports as `undefined` at runtime. +export { FIRE_AND_FORGET_ACTIONS, SLIDE_ONLY_ACTIONS, SYNC_ACTIONS } from '@openmaic/dsl'; diff --git a/packages/@openmaic/dsl/README.md b/packages/@openmaic/dsl/README.md index 1cb9410..b9a2ce2 100644 --- a/packages/@openmaic/dsl/README.md +++ b/packages/@openmaic/dsl/README.md @@ -26,12 +26,13 @@ nothing. | ------------- | ------------------------------------------------------------------- | | `slides.ts` | The slide object model: `Slide`, `PPTElement` and all variants, theme, background, animation, table/chart/code types, plus `ElementTypes` / `ShapePathFormulasKeys` enums. | | `stage.ts` | The lesson skeleton: `Stage`, generic `Scene`, `SceneType`, `StageMode`, `Whiteboard`, `VideoManifest`, `SlideContent`, `QuizContent`, `MultiAgentConfig`, `GeneratedAgentConfig`, plus `isSlideContent` / `isQuizContent` guards. | +| `action.ts` | The playback verb set: `Action` and all variants (spotlight, laser, speech, the `Wb*` whiteboard family, `play_video`, `discussion`, and the `widget_*` interaction actions), `ActionType`, the `FIRE_AND_FORGET_ACTIONS` / `SLIDE_ONLY_ACTIONS` / `SYNC_ACTIONS` category lists, plus the `PercentageGeometry` overlay type. | | `guards.ts` | Pure discriminant type-guards (`isTextElement`, …) and `PPT_ELEMENT_TYPES`. | | `version.ts` | `DSL_VERSION` + the `DslMigration` shape and (empty) migration registry. | ```ts -import type { Slide, PPTElement } from '@openmaic/dsl'; -import { isTextElement, DSL_VERSION } from '@openmaic/dsl'; +import type { Slide, PPTElement, Action } from '@openmaic/dsl'; +import { isTextElement, DSL_VERSION, SYNC_ACTIONS } from '@openmaic/dsl'; ``` ## Status @@ -53,31 +54,39 @@ of the slide types: - [x] Wire `@openmaic/renderer` to import types from `@openmaic/dsl` (vendored copy deleted). - [ ] Add the JSON Schema for the slide contract + a pure schema validator. - [x] Promote the `stage` / `scene` / `scene-content` types into the DSL (the - universal skeleton now lives in `stage.ts`; `Action`, Ultra-mode widgets, - and PBL stay app-side and plug in via `Scene`). + universal skeleton now lives in `stage.ts`). +- [x] Bring the `Action` playback verb set into the DSL (`action.ts`); the + widget interaction actions graduated into the contract once they decoupled + from widget configs, so the standard `Action` union now covers them too. + `Scene` defaults to that union; PBL configs and the app's richer + content kinds still plug in via `Scene`'s generics. - [ ] Reserve `@openmaic/exporter` as the 4th family member. ### Stage / Scene split -`stage.ts` owns only the **universal lesson skeleton**: `Stage`, the -discriminated `SceneContent` (`SlideContent | QuizContent`), and a generic +`stage.ts` owns the **universal lesson skeleton**: `Stage`, the discriminated +`SceneContent` (`SlideContent | QuizContent`), and a generic ```ts -interface Scene +interface Scene ``` -so the contract carries no dependency on the playback action set or the richer -feature surfaces. Apps compose their full scene type by injecting their own -types: +`TAction` defaults to the contract's standard `Action` union (defined in +`action.ts`), so a scene carries playback actions out of the box; skeleton-only +consumers that reject actions opt out with `Scene`. Apps widen the +content union (and, if they add their own actions, the action union) by +injecting their own types: ```ts -import type { Scene } from '@openmaic/dsl'; -type AppScene = Scene; +import type { Scene, Action } from '@openmaic/dsl'; +type AppScene = Scene; ``` -`Action`, widget configs (`WidgetType` / `WidgetConfig`), and `PBLProjectConfig` -are deliberately out of scope here — they're faster-moving product surfaces and -may graduate to sibling packages (`@openmaic/actions`, …) later. +Widget *configs* (`WidgetType` / `WidgetConfig`) and `PBLProjectConfig` remain +out of scope here — they're faster-moving product surfaces that stay app-side +and plug in via `Scene`'s generics. The widget *actions* (`widget_highlight`, +`widget_setState`, …), by contrast, are config-free playback verbs and live in +`action.ts` with the rest of the `Action` union. ## Divergence reconciled (seed provenance) diff --git a/packages/@openmaic/dsl/src/action.ts b/packages/@openmaic/dsl/src/action.ts new file mode 100644 index 0000000..cc1c526 --- /dev/null +++ b/packages/@openmaic/dsl/src/action.ts @@ -0,0 +1,292 @@ +/** + * Action — the universal playback verb contract. + * + * Actions are the sole mechanism for agents to drive a presentation. Two + * categories: + * - Fire-and-forget: visual effects on slides (spotlight, laser) + * - Synchronous: must wait for completion before the next action (speech, + * whiteboard, video, discussion, widget interactions) + * + * Both the online (streaming) and offline (playback) paths consume the same + * Action types, so they belong in the contract alongside the lesson skeleton + * (`Stage` / `Scene`): a consumer of `@openmaic/dsl` can now describe both what a + * lesson *looks like* and how it *plays back*. + * + * No runtime dependencies. Pure types + plain data constants only. + */ + +// ==================== Base ==================== + +export interface ActionBase { + id: string; + title?: string; + description?: string; +} + +// ==================== Fire-and-forget actions ==================== + +/** Spotlight — focus on a single element, dim everything else */ +export interface SpotlightAction extends ActionBase { + type: 'spotlight'; + elementId: string; + dimOpacity?: number; // default 0.5 +} + +/** Laser — point at an element with a laser effect */ +export interface LaserAction extends ActionBase { + type: 'laser'; + elementId: string; + color?: string; // default '#ff0000' +} + +// ==================== Synchronous actions ==================== + +/** Speech — teacher narration (wait for TTS to finish) */ +export interface SpeechAction extends ActionBase { + type: 'speech'; + text: string; + audioId?: string; + audioUrl?: string; // Server-generated TTS audio URL + voice?: string; + speed?: number; // default 1.0 +} + +/** Open whiteboard (wait for animation) */ +export interface WbOpenAction extends ActionBase { + type: 'wb_open'; +} + +/** Draw text on whiteboard (wait for render) */ +export interface WbDrawTextAction extends ActionBase { + type: 'wb_draw_text'; + elementId?: string; // Custom element ID for later reference (e.g. wb_delete) + content: string; // HTML string or plain text + x: number; + y: number; + width?: number; // default 400 + height?: number; // default 100 + fontSize?: number; // default 18 + color?: string; // default '#333333' +} + +/** Draw shape on whiteboard (wait for render) */ +export interface WbDrawShapeAction extends ActionBase { + type: 'wb_draw_shape'; + elementId?: string; // Custom element ID for later reference (e.g. wb_delete) + shape: 'rectangle' | 'circle' | 'triangle'; + x: number; + y: number; + width: number; + height: number; + fillColor?: string; // default '#5b9bd5' +} + +/** Draw chart on whiteboard (wait for render) */ +export interface WbDrawChartAction extends ActionBase { + type: 'wb_draw_chart'; + elementId?: string; // Custom element ID for later reference (e.g. wb_delete) + chartType: 'bar' | 'column' | 'line' | 'pie' | 'ring' | 'area' | 'radar' | 'scatter'; + x: number; + y: number; + width: number; + height: number; + data: { + labels: string[]; + legends: string[]; + series: number[][]; + }; + themeColors?: string[]; +} + +/** Draw LaTeX formula on whiteboard (wait for render) */ +export interface WbDrawLatexAction extends ActionBase { + type: 'wb_draw_latex'; + elementId?: string; // Custom element ID for later reference (e.g. wb_delete) + latex: string; + x: number; + y: number; + width?: number; // default 400 + height?: number; // auto-calculated based on formula aspect ratio + color?: string; // default '#000000' +} + +/** Draw table on whiteboard (wait for render) */ +export interface WbDrawTableAction extends ActionBase { + type: 'wb_draw_table'; + elementId?: string; // Custom element ID for later reference (e.g. wb_delete) + x: number; + y: number; + width: number; + height: number; + data: string[][]; // Simplified 2D string array, first row is header + outline?: { width: number; style: string; color: string }; + theme?: { color: string }; +} + +/** Draw line/arrow on whiteboard (wait for render) */ +export interface WbDrawLineAction extends ActionBase { + type: 'wb_draw_line'; + elementId?: string; // Custom element ID for later reference (e.g. wb_delete) + startX: number; // Start X position (0-1000) + startY: number; // Start Y position (0-562) + endX: number; // End X position (0-1000) + endY: number; // End Y position (0-562) + color?: string; // Default '#333333' + width?: number; // Line width, default 2 + style?: 'solid' | 'dashed'; // Default 'solid' + points?: ['', 'arrow'] | ['arrow', ''] | ['arrow', 'arrow'] | ['', '']; // Endpoint markers, default ['', ''] +} + +/** Clear all whiteboard elements */ +export interface WbClearAction extends ActionBase { + type: 'wb_clear'; +} + +/** Delete a specific whiteboard element by ID */ +export interface WbDeleteAction extends ActionBase { + type: 'wb_delete'; + elementId: string; +} + +/** Close whiteboard (wait for animation) */ +export interface WbCloseAction extends ActionBase { + type: 'wb_close'; +} + +/** Draw code block on whiteboard (wait for typing animation) */ +export interface WbDrawCodeAction extends ActionBase { + type: 'wb_draw_code'; + elementId?: string; + language: string; + code: string; // Raw code text, lines separated by \n + x: number; + y: number; + width?: number; // Default 500 + height?: number; // Default 300 + fileName?: string; +} + +/** Edit code block on whiteboard (line-level operations) */ +export interface WbEditCodeAction extends ActionBase { + type: 'wb_edit_code'; + elementId: string; // Target code block ID + operation: 'insert_after' | 'insert_before' | 'delete_lines' | 'replace_lines'; + lineId?: string; // Reference line ID for insert operations + lineIds?: string[]; // Target line IDs for delete/replace operations + content?: string; // New content for insert/replace, lines separated by \n +} + +/** Play video — start playback of a video element on the slide */ +export interface PlayVideoAction extends ActionBase { + type: 'play_video'; + elementId: string; +} + +/** Discussion — trigger a roundtable discussion */ +export interface DiscussionAction extends ActionBase { + type: 'discussion'; + topic: string; + prompt?: string; + agentId?: string; +} + +// ==================== Widget Interaction Actions ==================== + +/** Widget Highlight — highlight an element in a widget iframe */ +export interface WidgetHighlightAction extends ActionBase { + type: 'widget_highlight'; + target: string; // CSS selector or element ID in the iframe + content?: string; // Speech text to accompany the highlight +} + +/** Widget SetState — set widget state (e.g., simulation variables) */ +export interface WidgetSetStateAction extends ActionBase { + type: 'widget_setState'; + state: Record; + content?: string; // Speech text to accompany the state change +} + +/** Widget Annotation — add floating annotation to an element */ +export interface WidgetAnnotationAction extends ActionBase { + type: 'widget_annotation'; + target: string; + content?: string; +} + +/** Widget Reveal — reveal hidden content in widget */ +export interface WidgetRevealAction extends ActionBase { + type: 'widget_reveal'; + target: string; + content?: string; +} + +// ==================== Union type ==================== + +export type Action = + | SpotlightAction + | LaserAction + | PlayVideoAction + | SpeechAction + | WbOpenAction + | WbDrawTextAction + | WbDrawShapeAction + | WbDrawChartAction + | WbDrawLatexAction + | WbDrawTableAction + | WbDrawLineAction + | WbClearAction + | WbDeleteAction + | WbCloseAction + | WbDrawCodeAction + | WbEditCodeAction + | DiscussionAction + | WidgetHighlightAction + | WidgetSetStateAction + | WidgetAnnotationAction + | WidgetRevealAction; + +export type ActionType = Action['type']; + +/** Action types that fire immediately without blocking */ +export const FIRE_AND_FORGET_ACTIONS: ActionType[] = ['spotlight', 'laser']; + +/** Action types that only work on slide scenes (require slide canvas elements) */ +export const SLIDE_ONLY_ACTIONS: ActionType[] = ['spotlight', 'laser']; + +/** Action types that must complete before the next action runs */ +export const SYNC_ACTIONS: ActionType[] = [ + 'speech', + 'play_video', + 'wb_open', + 'wb_draw_text', + 'wb_draw_shape', + 'wb_draw_chart', + 'wb_draw_latex', + 'wb_draw_table', + 'wb_draw_line', + 'wb_draw_code', + 'wb_edit_code', + 'wb_clear', + 'wb_delete', + 'wb_close', + 'discussion', + 'widget_highlight', + 'widget_setState', + 'widget_annotation', + 'widget_reveal', +]; + +// ==================== Canvas utility types (non-action) ==================== + +/** + * Percentage-based geometry (0-100 coordinate system) + * Used by spotlight/laser overlays for responsive positioning. + */ +export interface PercentageGeometry { + x: number; // 0-100 + y: number; // 0-100 + w: number; // 0-100 + h: number; // 0-100 + centerX: number; // 0-100 + centerY: number; // 0-100 +} diff --git a/packages/@openmaic/dsl/src/index.ts b/packages/@openmaic/dsl/src/index.ts index 6774758..faca106 100644 --- a/packages/@openmaic/dsl/src/index.ts +++ b/packages/@openmaic/dsl/src/index.ts @@ -11,13 +11,15 @@ * validators / type-guards, and version/migration helpers. It must never gain * a runtime dependency on React, pptx, echarts, etc. * - * The lesson skeleton (`Stage` / `Scene` / `SceneContent`) lives here. `Scene` - * is generic: the contract owns only the universal structure + the slide/quiz - * content kinds, while playback `Action`s, Ultra-mode widgets, and PBL configs - * are app-side feature surfaces that consumers inject via `Scene`'s type - * parameters. + * The lesson skeleton (`Stage` / `Scene` / `SceneContent`) and the playback + * verb set (`Action` and its variants) both live here. `Scene` is generic: the + * contract owns the universal structure, the slide/quiz content kinds, and the + * standard `Action` union (which `TAction` now defaults to). PBL configs and + * the app's richer content kinds remain app-side feature surfaces that + * consumers inject via `Scene`'s type parameters. */ export * from './slides.js'; export * from './guards.js'; export * from './stage.js'; +export * from './action.js'; export * from './version.js'; diff --git a/packages/@openmaic/dsl/src/stage.ts b/packages/@openmaic/dsl/src/stage.ts index b857a5b..ca118f1 100644 --- a/packages/@openmaic/dsl/src/stage.ts +++ b/packages/@openmaic/dsl/src/stage.ts @@ -3,10 +3,10 @@ * * This module owns the *structural* part of a lesson: the top-level `Stage` * container and a per-page `Scene` whose `content` is a discriminated union of - * the universal content kinds (`SlideContent`, `QuizContent`). Richer, - * faster-moving feature surfaces (playback `Action`s, Ultra-mode widgets, PBL - * project configs) are deliberately *not* defined here — they stay in the - * consuming app and are threaded in through `Scene`'s generic parameters. + * the universal content kinds (`SlideContent`, `QuizContent`). `Scene`'s + * playback `actions` default to the contract's standard {@link Action} union + * (defined in `./action.ts`); apps still thread their own richer content + * kinds (interactive / PBL configs) in through `Scene`'s generic parameters. * * The split keeps `@openmaic/dsl` focused on the lesson skeleton while letting the * runtime engine, renderer, and importer share one source of truth for it. @@ -14,6 +14,7 @@ * No runtime dependencies. Pure types + pure discriminant guards only. */ import type { Slide } from './slides.js'; +import type { Action } from './action.js'; /** All scene kinds the contract is aware of. Feature kinds (interactive/pbl) are still valid `type` values — their *content* shapes live in the app and are composed in via {@link Scene}'s `TContent` parameter. */ export type SceneType = 'slide' | 'quiz' | 'interactive' | 'pbl'; @@ -154,27 +155,31 @@ export type SceneContent = SlideContent | QuizContent; /** * Scene - Represents a single page/scene in the course. * - * Generic so the contract owns only the universal skeleton while the app - * injects its concrete playback action set and full content union: + * Generic so the contract owns the universal skeleton + the standard action + * set, while the app widens the content union (and, if needed, the action + * union) for its richer feature kinds: * * ```ts - * // app side + * // app side — widen content; widen actions only if the app adds its own * type AppScene = Scene; * ``` * - * Defaults (`TAction = never`, `TContent = SlideContent | QuizContent`) yield a - * read-only, feature-free scene — what renderers / importers that only care - * about the skeleton want. The `TContent` constraint is structural — any union - * of objects tagged with a `type: SceneType` discriminant satisfies it — so an - * app can pass its own wider content union (slide | quiz | interactive | pbl). + * Defaults (`TAction = Action`, `TContent = SlideContent | QuizContent`) yield a + * scene whose `actions` are the contract's standard {@link Action} union and + * whose content spans the two universal kinds — what the runtime engine and + * playback consumers want out of the box. Skeleton-only consumers that reject + * actions entirely can still opt out with `Scene`. The `TContent` + * constraint is structural — any union of objects tagged with a `type: + * SceneType` discriminant satisfies it — so an app can pass its own wider + * content union (slide | quiz | interactive | pbl). * - * @template TAction - The playback action type (defaults to `never`, i.e. none). + * @template TAction - The playback action type (defaults to the standard {@link Action} union). * @template TContent - The scene-content union; any object union tagged with a * `type: {@link SceneType}` discriminant (defaults to the * two universal kinds). */ export interface Scene< - TAction = never, + TAction = Action, TContent extends { type: SceneType } = SlideContent | QuizContent, > { id: string; diff --git a/packages/@openmaic/dsl/test/stage.test.ts b/packages/@openmaic/dsl/test/stage.test.ts index d0b58ff..7b6a590 100644 --- a/packages/@openmaic/dsl/test/stage.test.ts +++ b/packages/@openmaic/dsl/test/stage.test.ts @@ -8,6 +8,7 @@ import { type SlideContent, type QuizContent, type Whiteboard, + type Action, } from '@openmaic/dsl'; /** @@ -87,8 +88,9 @@ describe('discriminant guards', () => { }); describe('Scene generic', () => { - it('default Scene is the feature-free skeleton (no actions, slide/quiz content)', () => { - // No type args: actions default to never[], content to slide | quiz. + it('default Scene: optional actions (standard Action union), slide/quiz content', () => { + // No type args: actions default to the standard `Action` union and stay + // optional; content defaults to slide | quiz. const s: Scene = { id: 'sc1', stageId: 'stg1', @@ -122,12 +124,19 @@ describe('Scene generic', () => { expect(appScene.actions?.[0].kind).toBe('speech'); }); - it('TAction defaults to never so the default Scene rejects concrete actions at the type level', () => { - // A default `Scene` with actions supplied must NOT type-check: `never[]` - // accepts no concrete element. Pin the exact type so the default can't - // silently drift to something that would accept a concrete action. + it('TAction defaults to the standard Action union so the default Scene carries playback actions', () => { + // The default `Scene` exposes the contract's standard `Action` union on + // `actions`. Pin the exact type so the default can't silently drift away + // from the promoted action set. type DefaultScene = Scene; - expectTypeOf().toEqualTypeOf(); + expectTypeOf().toEqualTypeOf(); + }); + + it('skeleton-only consumers can still opt out of actions with Scene', () => { + // Renderers / importers that only care about the lesson skeleton reject + // concrete actions by pinning `never`. + type SkeletonScene = Scene; + expectTypeOf().toEqualTypeOf(); }); });