wyuc 7c19ab8f1e
feat(dsl): JSON Schema artifacts + pure validators (#787 Part B-1) (#817)
* 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>
2026-07-01 01:04:34 +08:00
..

@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:

  1. JSON Schema artifacts (cross-language mirror) — Stage, the default Scene<Action, SceneContent>, and Action are 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.

  2. 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. a spotlight's elementId), known discriminants, and the scene type <-> content binding the public Scene type 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('; '));
    

    ValidationResult is { 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; vendored openmaic/types/slides.ts deleted. The importer emits complete DSL Slide objects directly (the old partial "draft slide" + post-fill step is gone).
  • @openmaic/renderer: imports all slide types from @openmaic/dsl; vendored types/slides.ts deleted. @openmaic/dsl is a regular dependency, kept external in the rollup build so consumers share one copy. The public @openmaic/renderer/types surface now re-exports the DSL types.

Roadmap

  • Wire @openmaic/importer to import types from @openmaic/dsl (vendored copy deleted).
  • Wire @openmaic/renderer to import types from @openmaic/dsl (vendored copy deleted).
  • Add the JSON Schema for the slide contract + a pure schema validator (build-time dist/schema/*.json via a devDep generator; zero-dep validate* functions). See Runtime layer below.
  • Promote the stage / scene / scene-content types into the DSL (the universal skeleton now lives in stage.ts).
  • 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 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.