wyuc fcdb6d62b3
feat(dsl): own element-level normalization & defaults; wire the generator (#787) (#832)
* feat(dsl): own element defaults + normalize(); wire the generator (#787)

Bring element-level normalization into the @openmaic/dsl contract, so producers
stop carrying their own imperative "fix up the output" pass. Companion to the
#817 validators: where validate* reports on a document, normalize* repairs one.

- src/normalize.ts: pure, zero-dep normalizeElement / normalizeSlide /
  normalizeScene / normalizeStage + canonical ELEMENT_DEFAULTS. Fills missing
  required content fields, derives geometry (a line's start/end, a shape's
  viewBox/path from its box), and FAILS LOUD on a present-but-wrong-typed field
  instead of silently resetting it. Pure, non-mutating, idempotent. Scope is
  element content — base identity/geometry (id, left/top/width/height/rotate) is
  producer-supplied (the id is assigned downstream) and left to validate*/schema.
- slides.ts: static defaults ride out on the generated JSON Schema as @default
  annotations (so non-TS consumers ship them too); ELEMENT_DEFAULTS is the
  single source of truth, pinned to the schema by a lockstep test.
- generator: fixElementDefaults drops its per-type fixups for normalizeElement,
  wrapped in try/catch so a malformed element degrades gracefully (log + keep
  raw) rather than aborting a whole scene/course — generation runs on unreliable
  model output and on legacy slides the old pass itself produced. Image
  aspect-ratio reconciliation stays (it needs the resolved asset's real
  dimensions — a producer concern the DSL does not own).

Two latent bugs fixed while canonicalizing into the contract:
- shape viewBox: the old missing-viewBox fallback emitted a string "0 0 w h",
  which every consumer reads as viewBox[0]/[1]; normalize emits the contract's
  [w, h] pair.
- line start/end: the old fallback derived ABSOLUTE [left, top] coordinates, but
  the renderer positions the line container at (left, top) and reads start/end
  as LOCAL offsets (getLineElementPath / getElementRange) — double-offsetting
  the line. normalize derives them in the local frame ([0,0] .. [w, h]).

Minor bump @openmaic/dsl 0.2.0 -> 0.3.0. test/normalize.test.ts covers the
defaults, derivation (incl. the local-frame line regression), fail-loud
coercion, purity/idempotency, generic app-widened normalizeScene, schema
conformance of normalized output, and the ELEMENT_DEFAULTS <-> schema lockstep.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* style: format normalize.ts / normalize.test.ts with prettier

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(dsl): normalize nested ShapeText; repair-or-drop malformed elements in the generator

Address review on #832:

- normalizeShape now normalizes a present `text` overlay (ShapeText): fills
  content / defaultFontName / defaultColor / align with canonical defaults
  (align 'middle' per the renderers' convention), fails loud on a malformed
  overlay. Consumers read `text.content` unguarded (the PPTX exporter feeds it
  to formatHTML), so a present overlay gets the same repair semantics as the
  element's own required fields. Defaults ride the schema as @default and are
  pinned by the lockstep test.
- The generator's fixElementDefaults no longer keeps a raw element when
  normalization fails — repair or drop: JSON nulls from the model are stripped
  first (null means absent; normalize then fills/derives the field), and an
  element that still fails is discarded with a warning. Keeping the raw payload
  handed malformed lines (start/end null) to consumers that index straight into
  start[0] (getElementRange / BaseLineElement / export), crashing playback or
  export over one bad element.

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-03 14:19:38 +08:00
..