feat(dsl): bring the Action playback verbs into @openmaic/dsl (#787)

Promote the Action contract (Action union + variants, ActionType, the action-category lists, PercentageGeometry) into @openmaic/dsl/src/action.ts, zero-runtime-dep. Widget interaction actions graduate into the contract; Scene<TAction> defaults to the standard Action union; lib/types/action.ts becomes a re-export shim. Part A of #787 (Phase 2 under #720).
This commit is contained in:
wyuc 2026-06-29 23:38:28 -04:00 committed by GitHub
parent 261fddb062
commit b122ca30d3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 400 additions and 325 deletions

View File

@ -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<string, unknown>;
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';

View File

@ -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<TAction, TContent>`, `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<TAction, TContent>`).
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<TAction>` 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<TAction = never, TContent extends { type: SceneType } = SlideContent | QuizContent>
interface Scene<TAction = Action, TContent extends { type: SceneType } = SlideContent | QuizContent>
```
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<never, …>`. 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<AppAction, SlideContent | QuizContent | InteractiveContent | PBLContent>;
import type { Scene, Action } from '@openmaic/dsl';
type AppScene = Scene<Action, SlideContent | QuizContent | InteractiveContent | PBLContent>;
```
`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)

View File

@ -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<string, unknown>;
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
}

View File

@ -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';

View File

@ -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<Action, AppSceneContent>;
* ```
*
* 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<never, …>`. 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;

View File

@ -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<TAction, TContent> 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<TAction, TContent> 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<DefaultScene['actions']>().toEqualTypeOf<never[] | undefined>();
expectTypeOf<DefaultScene['actions']>().toEqualTypeOf<Action[] | undefined>();
});
it('skeleton-only consumers can still opt out of actions with Scene<never>', () => {
// Renderers / importers that only care about the lesson skeleton reject
// concrete actions by pinning `never`.
type SkeletonScene = Scene<never>;
expectTypeOf<SkeletonScene['actions']>().toEqualTypeOf<never[] | undefined>();
});
});