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:
parent
261fddb062
commit
b122ca30d3
@ -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';
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
292
packages/@openmaic/dsl/src/action.ts
Normal file
292
packages/@openmaic/dsl/src/action.ts
Normal 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
|
||||
}
|
||||
@ -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';
|
||||
|
||||
@ -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;
|
||||
|
||||
@ -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>();
|
||||
});
|
||||
});
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user