* feat(dsl): add ACTION_TYPES set + isActionType guard
A frozen set of every valid ActionType plus a pure membership guard,
mirroring the PPT_ELEMENT_TYPES / isPPTElementType idiom in guards.ts.
Used by the new validators; useful standalone for narrowing untrusted
action.type values.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(dsl): build-time JSON Schema codegen for stage/scene/action
TS types stay the single source of truth; ts-json-schema-generator (a
devDependency, build-only) emits dist/schema/{stage,scene,action}.schema.json,
shipped under the new ./schema/* export. Serves non-TS / bring-your-own-validator
consumers without adding a runtime dependency.
JSON Schema is not generic, so schema-roots.ts provides a concrete
Scene<Action, SceneContent> entry point (kept internal, not re-exported).
schema.test.ts compiles the generated schema with ajv (devDep) to prove the
artifact is real and self-contained on a clean checkout.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(dsl): add pure structural validators (stage/scene/action)
validateStage / validateScene / validateAction: hand-written, zero-dependency,
fail-loud structural checks layered on the existing guards. They verify
discriminants, required fields, and known nested discriminants — a gate for
untrusted input (LLM/agent output) and persistence boundaries. Exhaustive
per-field validation is delegated to the shipped JSON Schema. Error-collecting
ValidationResult reports every issue with a JSON-pointer-ish path.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(dsl): document the runtime schema + validator layer
Add a Runtime layer section covering the two complementary consumption modes
(schema-as-data via @openmaic/dsl/schema/* and the zero-dep validate* gate),
the validate.ts module row, the build:schema step, and tick the JSON Schema
roadmap box.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(dsl): harden validators per cross-review (exhaustiveness, discriminant agreement)
Addresses cross-review findings on the validator layer:
- Add compile-time exhaustiveness assertions for ACTION_TYPES and SCENE_TYPES.
`satisfies` only proved each entry is valid, not that the tuple covers the
whole union — a newly-added Action/Scene variant could silently be rejected
by the validators. The assertion now fails the build on drift.
- validateScene cross-checks that scene.type agrees with content.type; a
slide-typed scene carrying quiz content (or vice versa) is now rejected.
- Move SCENE_TYPES + add an isSceneType guard to stage.ts, next to SceneType,
matching the PPT_ELEMENT_TYPES / isPPTElementType idiom in guards.ts; validate.ts
reuses them instead of re-encoding the union locally.
- Make the validators' scope honest in the doc comment + README: they check the
structural envelope, known discriminants, and scene/content agreement; they do
NOT exhaustively check per-variant fields, and app-side interactive/pbl content
is validated only at the envelope level (exhaustive checks → the JSON Schema).
- Note the contract-owned content scope in schema-roots.ts.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* perf(dsl): reuse one schema generator + harden direct-invocation guard
Addresses cross-review findings on the codegen path:
- gen-schema.mjs built a fresh ts-json-schema-generator (full TS program parse)
per root type; build one generator over the tsconfig program and reuse it for
every createSchema call — parses once, identical per-type output.
- Harden the `invoked directly` check to compare realpaths, so a symlinked
invocation (bin shim / pnpm link) still runs main() instead of silently
emitting no schema.
- schema.test.ts generates all roots once at module scope, then only compiles
per case — no repeated heavy codegen.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(dsl): bind scene schema discriminants + pin node-20-compatible generator
Addresses round-2 cross-review (codex) findings:
- scene.schema.json now ties scene `type` to the matching `content.type`.
SerializedScene became a discriminated union (SlideScene | QuizScene via
`Omit<Scene<…>, 'type'> & { type }`), so the generator emits a const-narrowed
discriminant per branch. Previously the schema accepted e.g.
{ type: 'quiz', content: { type: 'slide', … } } even though validateScene
rejects it — the schema is now consistent with the validator. Locked with a test.
- Pin ts-json-schema-generator to ~2.4.0. ^2.3.0 resolved to 2.9.0, which
declares `node >=22`, conflicting with the repo's `engines.node >=20.9.0`;
2.4.x supports node >=18, keeping the build runnable on every supported Node.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* style(dsl): prettier formatting + drop unused ts-expect-error for green CI
- Apply repo Prettier (`pnpm check`) formatting to the new/edited files.
- Remove the `@ts-expect-error` on the gen-schema.mjs import: the root
`tsc --noEmit` (which compiles test files; allowJs infers the .mjs exports)
flagged it as an unused directive (TS2578). Plain comment retained.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* refactor(dsl): align validators + schema to the public Scene type (review)
Addresses cosarah's review: the validator, the JSON Schema, and the public TS
type had drifted into three different notions of a valid scene. Realign them so
the TS types stay the single source of truth, and position the two runtime
layers honestly.
- schema-roots.ts: revert SerializedScene to the plain default Scene<Action,
SceneContent>. The schema no longer encodes a stricter type/content binding
that the public Scene type doesn't express (the constraint had effectively
moved into a hidden internal type).
- validate.ts: drop the scene.type<->content.type agreement check (the public
Scene does not bind them, so neither does the validator); restrict content to
the contract-owned kinds (slide/quiz), matching SceneContent and the schema,
so validator and schema no longer disagree on interactive/pbl content.
- Reposition docs (validate.ts header + README): the JSON Schema is the
authoritative, exhaustive per-field validator (it checks variant fields like
an action's elementId) for trust boundaries; validate* are a cheap,
zero-dep structural pre-check and a strict subset of the schema — not a
separate or stricter gate.
- Tests updated to lock the realigned behavior.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* refactor(dsl): bind scene type<->content in the public Scene contract (review)
cosarah's review showed the scene type<->content agreement is a real, load-bearing
invariant: consumers branch on `scene.type` and then read `scene.content` as the
matching shape (e.g. `stage-api-canvas` casts `content as SlideContent` after a
`scene.type === 'slide'` check; `complete-summary` counts by `scene.type` and reads
`content as QuizContent`). A validator/schema that blesses mismatched pairs is unsafe.
So tighten the *exported* contract rather than loosening the runtime checks to match
a hole — and make the pure validators the authoritative, relied-upon boundary.
DSL contract:
- `Scene` becomes a distributive discriminated type binding `type` to `content['type']`
(`SceneCore<TAction> & { type: TContent['type']; content: TContent }` distributed over
TContent). TS itself now rejects mismatched scenes; generic widening still works.
Extract `SceneCore` for the kind-independent fields.
- `validateScene` re-establishes the type<->content agreement check; scene `type` is
the contract's slide/quiz; `scene.schema.json` (from the spelled-out discriminated
`SerializedScene`) binds `type` to content per branch. Type, validator, and schema
now describe the same thing.
- `validateAction` checks each variant's required fields (e.g. spotlight.elementId,
discussion.topic) — closes the false-positive gap. A test pins the hand map to the
generated schema (the TS-derived source of truth) so it cannot drift.
- Reposition docs: `validate*` is the zero-dep in-process boundary producers rely on;
the JSON Schema is the cross-language mirror + exhaustive value checker.
App consumers (the sites the discriminated Scene exposes):
- Add `ScenePatch` (non-distributive partial) + `makeScene(core, content)` helper to
lib/types/stage.ts — one isolated cast, type derived from content. Patch-typed
signatures (`updateScene`, `applyScenePatchInSync`, regenerate plan) and scene
rebuilds (`stage-api-scene`, store `updateScene`, `migrateScene`, stage-storage
deserialize) route through these. Closes two latent desync foot-guns.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(dsl): validate action field types + migrate scene.update; bidirectional drift-guard (review)
Round-2 review of the contract-tightening change (codex + Claude):
- validateAction now checks each variant-required field's TYPE, not just presence
(`{ type:'spotlight', elementId: 123 }` is rejected — elementId must be a string).
ACTION_REQUIRED_FIELDS carries a runtime kind per field.
- The schema lockstep test is now bidirectional and type-aware: it asserts a
fully-typed action is accepted (catches the map OVER-listing an optional field),
every required field flags when missing (under-listing), and flags when present
but mis-typed — all keyed off the generated schema's field names + types.
- Migrate the public `stageApi.scene.update()` to ScenePatch + makeScene (the
create() path was done last commit; update() still did a raw spread that could
desync type<->content — masked from tsc only because StageStore.setState is typed
`any`). Now both public scene-construction paths rebind type to content.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(api): keep scene.create's params.type authoritative over content.type (review)
cosarah's review: `CreateSceneParams` exposes an independent `type` plus
`content?: Partial<SceneContent>`, and after switching create() to makeScene()
(which derives the scene kind from content.type), a call like
`create({ type: 'slide', content: { type: 'interactive', ... } })` would silently
become an interactive scene — params.type ignored — and mix slide defaults into it.
Reject a `content.type` that disagrees with `params.type`, and pin the merged
content's `type` to `params.type` so a partial content override can't flip the
scene's discriminant. params.type stays authoritative. Adds a test both ways.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@openmaic/dsl
The contract keystone of the MAIC SDK family. @openmaic/dsl is pure spec — the
slide object-model types, build-time JSON Schema artifacts, pure validators / type-guards,
and version/migration helpers — with zero runtime dependencies (no React, no
pptx, no echarts).
That purity is the whole point: the renderer, the importer, and any future
package can depend on @openmaic/dsl without pulling in junk.
Dependency arrows (acyclic)
@openmaic/dsl -> (nothing)
@openmaic/renderer -> @openmaic/dsl
@openmaic/importer -> @openmaic/dsl
@openmaic/exporter -> @openmaic/dsl (reserved, future)
@openmaic/dsl is the only package everything else depends on, and it depends on
nothing.
What's in here
| Module | Contents |
|---|---|
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 frozen ACTION_TYPES set + isActionType guard, 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. |
validate.ts |
Pure, zero-dep structural validators — validateStage / validateScene / validateAction returning an error-collecting ValidationResult. |
version.ts |
DSL_VERSION + the DslMigration shape and (empty) migration registry. |
import type { Slide, PPTElement, Action } from '@openmaic/dsl';
import { isTextElement, DSL_VERSION, SYNC_ACTIONS } from '@openmaic/dsl';
Runtime layer (schema + validators)
The contract is enforceable two ways — a zero-dependency in-process validator and a cross-language JSON Schema — both generated from / aligned to the same public TS types, and both honoring the zero-runtime-dependency invariant:
-
JSON Schema artifacts (cross-language mirror) —
Stage, the defaultScene<Action, SceneContent>, andActionare emitted as standalone JSON Schema at build time and shipped. This is the language-neutral mirror of the contract for non-TS consumers, and the place to go for exhaustive value-level (type / format) checking:import stageSchema from '@openmaic/dsl/schema/stage.schema.json' with { type: 'json' }; import sceneSchema from '@openmaic/dsl/schema/scene.schema.json' with { type: 'json' }; import actionSchema from '@openmaic/dsl/schema/action.schema.json' with { type: 'json' }; // feed to any JSON Schema validator (ajv, or a non-TS / non-JS consumer)The schema is generated from the TS types (the single source of truth) by
ts-json-schema-generator, a devDependency — it never enters the runtime dependency set. -
Pure validators (in-process boundary) —
validate*are hand-written, zero-dependency checks layered on the guards: object shape, required fields (including each action variant's, e.g. aspotlight'selementId), known discriminants, and the scenetype<->contentbinding the publicScenetype enforces. Because they add no dependency, in-process (TS / JS) producers and consumers — generators, importers, the runtime engine — can rely on them directly without shipping a schema validator. They are a structural subset of the schema (presence + discriminants; the schema additionally checks each field's value shape), and describe the same contract. Both are kept in lockstep by a test that pins the validators' per-variant required fields to the generated schema.import { validateStage, validateScene, validateAction } from '@openmaic/dsl'; const result = validateScene(input); if (!result.valid) throw new Error(result.errors.map((e) => `${e.path}: ${e.message}`).join('; '));ValidationResultis{ valid: true } | { valid: false; errors: { path; message }[] }— it collects every issue rather than failing on the first.
Status
Both consumers are now wired to @openmaic/dsl and no longer vendor their own copy
of the slide types:
@openmaic/importer: imports all slide types from@openmaic/dsl; vendoredopenmaic/types/slides.tsdeleted. The importer emits complete DSLSlideobjects directly (the old partial "draft slide" + post-fill step is gone).@openmaic/renderer: imports all slide types from@openmaic/dsl; vendoredtypes/slides.tsdeleted.@openmaic/dslis a regular dependency, kept external in the rollup build so consumers share one copy. The public@openmaic/renderer/typessurface now re-exports the DSL types.
Roadmap
- Wire
@openmaic/importerto import types from@openmaic/dsl(vendored copy deleted). - Wire
@openmaic/rendererto import types from@openmaic/dsl(vendored copy deleted). - Add the JSON Schema for the slide contract + a pure schema validator
(build-time
dist/schema/*.jsonvia a devDep generator; zero-depvalidate*functions). See Runtime layer below. - Promote the
stage/scene/scene-contenttypes into the DSL (the universal skeleton now lives instage.ts). - Bring the
Actionplayback verb set into the DSL (action.ts); the widget interaction actions graduated into the contract once they decoupled from widget configs, so the standardActionunion now covers them too.Scene<TAction>defaults to that union; PBL configs and the app's richer content kinds still plug in viaScene's generics. - Reserve
@openmaic/exporteras the 4th family member.
Stage / Scene split
stage.ts owns the universal lesson skeleton: Stage, the discriminated
SceneContent (SlideContent | QuizContent), and a generic
interface Scene<TAction = Action, TContent extends { type: SceneType } = SlideContent | QuizContent>
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:
import type { Scene, Action } from '@openmaic/dsl';
type AppScene = Scene<Action, SlideContent | QuizContent | InteractiveContent | PBLContent>;
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)
The seed is the app's lib/types/slides.ts, but before this package existed the
contract had been copy-pasted into three places that drifted apart. This
package is the canonical superset: every field that existed in any copy is
kept, so consumers can adopt the DSL without losing data. Merged-in fields are
annotated @since-merge in slides.ts.
| Field | app lib/types |
renderer copy | importer copy | DSL decision |
|---|---|---|---|---|
PPTTextElement.vAlign |
— | ✓ | ✓ | kept |
PPTImageElement.softEdge |
— | ✓ | ✓ | kept |
TableCellBorder + TableCell.borders |
— | ✓ | ✓ | kept |
TableCell.padding |
— | ✓ | ✓ | kept |
TableCell.vAlign |
— | top/middle/bottom |
up/mid/down/top/middle/bottom |
canonical = top/middle/bottom; importer already normalizes its up/mid/down aliases in transformParsedToSlides |
PPTTableElement.rowHeights |
— | ✓ | ✓ | kept |
Slide.script (speaker notes) |
— | — | ✓ | kept |
Slide.viewportSize/viewportRatio/theme |
required | required | optional | canonical = required; importer now fills them at construction in transformParsedToSlides (no partial/draft stage) |
SlideData (deprecated) |
✓ | — | ✓ | kept, @deprecated |
The importer conforms to the canonical contract: it normalizes cell vAlign
aliases and emits the required Slide fields on output. The renderer consumes
the same superset (it gains access to script and the importer-origin fields it
didn't previously declare).
Build
Pure TypeScript compiled with tsc to ESM + .d.ts, then the JSON Schema
artifacts are generated into dist/schema/:
pnpm --filter @openmaic/dsl build # -> dist/ (index.js, index.d.ts, …) + dist/schema/*.json
pnpm --filter @openmaic/dsl build:schema # regenerate only dist/schema/*.json
pnpm --filter @openmaic/dsl typecheck
pnpm --filter @openmaic/dsl test
License
MIT, matching the rest of the family (@openmaic/dsl, @openmaic/importer,
@openmaic/renderer) and the OpenMAIC root, so the license policy is uniform
across the SDK.