@markdy/core 0.5.8 → 0.7.0

package/dist/index.d.ts

@@ -7,8 +7,8 @@ type AssetDef = {
     value: string;
 };
 type ActorDef = {
-    type: "sprite" | "text" | "box" | "figure";
-    /** Constructor arguments: asset name for sprite, display text for text actors. */
+    type: "sprite" | "text" | "box" | "figure" | "caption";
+    /** Constructor arguments: asset name for sprite, display text for text/caption actors. */
     args: string[];
     x: number;
     y: number;
@@ -17,6 +17,14 @@ type ActorDef = {
     opacity?: number;
     /** Font size in pixels; applies to text actors (via the `size` modifier). */
     size?: number;
+    /** Z-index for layering control (via the `z` modifier). */
+    z?: number;
+    /**
+     * Semantic anchor for captions (`top`, `bottom`, `center`). Absent for
+     * non-caption actors. The parser also fills `x` and `y` from the anchor
+     * so renderers that don't understand the field still place the caption.
+     */
+    anchor?: "top" | "bottom" | "center";
 };
 type TimelineEvent = {
     time: number;
@@ -24,6 +32,11 @@ type TimelineEvent = {
     action: string;
     params: Record<string, unknown>;
     line: number;
+    /**
+     * The `scene "title" { ... }` block this event belongs to, if any.
+     * Undefined for events in the top-level scope.
+     */
+    chapter?: string;
 };
 type SceneMeta = {
     width: number;
@@ -59,6 +72,37 @@ type SequenceDef = {
         paramsRaw: string;
     }>;
 };
+/**
+ * A `scene "title" { ... }` block — a named grouping of timeline events.
+ * Start/end times are inclusive wall-clock seconds so renderers and
+ * tooling can highlight the active chapter without re-walking events.
+ */
+type Chapter = {
+    name: string;
+    startTime: number;
+    endTime: number;
+    startLine: number;
+};
+/**
+ * A non-fatal parse issue. Renderers should surface these via
+ * `onWarning` so the author can fix the underlying cause; the
+ * renderer otherwise no-ops the offending statement.
+ */
+type ParseWarning = {
+    kind: "unknown-action" | "unknown-modifier" | "unknown-scene-key" | "unknown-camera-action" | "unknown-preset" | "import-unresolved" | "preset-mixed";
+    message: string;
+    line: number;
+};
+/**
+ * An `import "path.markdy" as ns` declaration. Parsing records the
+ * intent; the host (CLI, bundler) resolves the path and may supply
+ * pre-parsed ASTs via the `parse(..., { imports })` option.
+ */
+type ImportDecl = {
+    path: string;
+    namespace: string;
+    line: number;
+};
 type SceneAST = {
     meta: SceneMeta;
     assets: Record<string, AssetDef>;
@@ -70,12 +114,57 @@ type SceneAST = {
     seqs: Record<string, SequenceDef>;
     /** User-defined variables — kept in AST for tooling/inspection. */
     vars: Record<string, string>;
+    /** Named chapter blocks in author order. Empty when no chapters were used. */
+    chapters: Chapter[];
+    /** Soft parse issues. Always present; empty in the happy path. */
+    warnings: ParseWarning[];
+    /** `import` declarations in author order. Always present; empty when none were used. */
+    imports: ImportDecl[];
 };
 
 declare class ParseError extends Error {
     readonly line: number;
     constructor(message: string, line: number);
 }
-declare function parse(source: string): SceneAST;
+interface ParseOptions {
+    /**
+     * Pre-parsed ASTs for `import "path" as ns` declarations. The host
+     * (CLI, bundler) is responsible for reading files from disk and
+     * parsing them; the parser itself is pure.
+     *
+     * When an import's namespace is present here, its `vars`, `defs`,
+     * and `seqs` are merged into the importing AST under the
+     * `<ns>.<name>` prefix. Missing namespaces produce a soft warning.
+     */
+    imports?: Record<string, SceneAST>;
+    /**
+     * Internal flag — distinguishes a top-level call from a recursive
+     * call used to expand a `preset`. Preset expansion bypasses the
+     * "mixed preset and other statements" warning because the expanded
+     * source is the only content.
+     */
+    _fromPreset?: boolean;
+}
+declare function parse(source: string, opts?: ParseOptions): SceneAST;
+
+/**
+ * MarkdyScript built-in presets.
+ *
+ * A preset is a string template that expands at parse time into canonical
+ * MarkdyScript. The renderer never sees preset statements — by the time
+ * parsing reaches the actor/event stage, the preset has been replaced
+ * with its expansion.
+ *
+ * Design rules:
+ *   1. Each preset is self-contained — it declares its own `scene`,
+ *      actors, and timeline.
+ *   2. Presets are short. The value is in `preset <name>` being a
+ *      one-liner that expands to a scaffold the user can then tweak.
+ *   3. Presets share a common visual grammar so a feed of them feels
+ *      like a family, not a collage.
+ */
+type PresetFn = (args: string[]) => string;
+declare const PRESETS: Record<string, PresetFn>;
+declare const PRESET_NAMES: readonly string[];
 
-export { type ActorDef, type AssetDef, ParseError, type SceneAST, type SceneMeta, type SequenceDef, type TemplateDef, type TimelineEvent, parse };
+export { type ActorDef, type AssetDef, type Chapter, type ImportDecl, PRESETS, PRESET_NAMES, ParseError, type ParseOptions, type ParseWarning, type PresetFn, type SceneAST, type SceneMeta, type SequenceDef, type TemplateDef, type TimelineEvent, parse };

package/dist/index.js

@@ -1,3 +1,229 @@
+// src/presets.ts
+function quote(s) {
+  const stripped = s.replace(/^"|"$/g, "");
+  return `"${stripped.replace(/"/g, '\\"')}"`;
+}
+var PRESETS = {
+  meme: (args) => {
+    const top = quote(args[0] ?? "when the code works");
+    const bottom = quote(args[1] ?? "and you don't know why");
+    return `scene width=720 height=720 bg=#111
+
+actor top    = caption(${top}) at top
+actor hero   = figure(#c68642, m, \u{1F60E}) at (360, 430)
+actor bottom = caption(${bottom}) at bottom
+
+@0.0: top.fade_in(dur=0.4)
+@0.4: hero.enter(from=bottom, dur=0.6)
+@1.2: hero.face("\u{1F602}")
+@1.8: bottom.fade_in(dur=0.4)
+@3.2: hero.bounce(intensity=20, count=2, dur=0.8)
+`;
+  },
+  explainer: (args) => {
+    const title = quote(args[0] ?? "how it works");
+    return `scene width=960 height=540 bg=#0d1117
+
+actor title = caption(${title}) at top
+actor hero  = figure(#c68642, m, \u{1F60E}) at (480, 360)
+
+scene "intro" {
+  @+0.0: title.fade_in(dur=0.5)
+  @+1.0: hero.enter(from=bottom, dur=0.5)
+}
+
+scene "body" {
+  @+0.0: camera.zoom(to=1.2, dur=0.8)
+  @+1.0: hero.wave(side=right, dur=0.5)
+}
+`;
+  },
+  reaction: (args) => {
+    const line = quote(args[0] ?? "wait, what?");
+    return `scene width=720 height=720 bg=#fff5f9
+
+actor hero = figure(#c68642, m, \u{1F642}) at (360, 380)
+
+@0.0: hero.enter(from=left, dur=0.4)
+@0.5: hero.face("\u{1F633}")
+@0.5: hero.say(${line}, dur=1.4)
+@2.0: hero.face("\u{1F602}")
+@2.0: hero.shake(intensity=6, dur=0.5)
+`;
+  },
+  pov: (args) => {
+    const pov = quote(args[0] ?? "POV: you hit ship");
+    return `scene width=720 height=960 bg=#0d1117
+
+actor label = caption(${pov}) at top
+actor hero  = figure(#c68642, m, \u{1F60E}) at (360, 600)
+
+@0.0: label.fade_in(dur=0.4)
+@0.4: hero.enter(from=bottom, dur=0.6)
+@1.2: hero.pose(arm_left=70, arm_right=-70, dur=0.3)
+@1.2: hero.face("\u{1F525}")
+`;
+  },
+  typing: (args) => {
+    const text = quote(args[0] ?? "hello world");
+    return `scene width=800 height=300 bg=#0f1115
+
+actor cursor = text("|") at (120, 150) size 40 opacity 0
+actor line   = text(${text}) at (140, 150) size 32 opacity 0
+
+@0.0:  cursor.fade_in(dur=0.15)
+@+0.1: cursor.fade_out(dur=0.15)
+@+0.0: cursor.fade_in(dur=0.15)
+@+0.1: cursor.fade_out(dur=0.15)
+@+0.0: cursor.fade_in(dur=0.15)
+@+0.0: line.fade_in(dur=0.8)
+@+0.3: cursor.fade_out(dur=0.3)
+`;
+  },
+  terminal: (args) => {
+    const cmd = quote(args[0] ?? "$ npx markdy");
+    const output = quote(args[1] ?? "playground ready at http://localhost:4242");
+    return `scene width=960 height=420 bg=#0d1117
+
+actor prompt = text(${cmd})    at (60, 140) size 24 opacity 0
+actor result = text(${output}) at (60, 200) size 22 opacity 0
+
+@0.0: prompt.fade_in(dur=0.4)
+@1.0: result.fade_in(dur=0.4)
+`;
+  },
+  chat_bubble: (args) => {
+    const a = quote(args[0] ?? "how do I animate this?");
+    const b = quote(args[1] ?? "ask markdy.");
+    return `scene width=800 height=400 bg=#f6f7fb
+
+actor alice = figure(#fad4c0, f, \u{1F642}) at (180, 240)
+actor bob   = figure(#c68642, m, \u{1F642}) at (620, 240)
+
+@0.0: alice.enter(from=left, dur=0.4)
+@0.2: bob.enter(from=right, dur=0.4)
+@0.8: alice.say(${a}, dur=1.8)
+@2.6: bob.face("\u{1F60E}")
+@2.6: bob.say(${b}, dur=1.6)
+`;
+  },
+  vs: (args) => {
+    const left = quote(args[0] ?? "team a");
+    const right = quote(args[1] ?? "team b");
+    return `scene width=960 height=540 bg=#111
+
+actor a = caption(${left})  at top
+actor b = caption(${right}) at bottom
+actor lf = figure(#c68642, m, \u{1F624}) at (260, 320)
+actor rf = figure(#8d5524, m, \u{1F60F}) at (700, 320)
+
+@0.0: a.fade_in(dur=0.3)
+@0.0: b.fade_in(dur=0.3)
+@0.3: lf.enter(from=left, dur=0.5)
+@0.3: rf.enter(from=right, dur=0.5)
+@1.2: lf.punch(side=right, dur=0.3)
+@1.3: rf.shake(intensity=8, dur=0.4)
+`;
+  },
+  tutorial_step: (args) => {
+    const n = quote(args[0] ?? "Step 1");
+    const body = quote(args[1] ?? "open your editor");
+    return `scene width=960 height=420 bg=white
+
+actor step  = caption(${n}) at top
+actor descr = text(${body}) at (100, 220) size 32 opacity 0
+
+@0.0: step.fade_in(dur=0.4)
+@0.5: descr.fade_in(dur=0.4)
+@1.2: descr.move(to=(120, 220), dur=0.5, ease=out)
+`;
+  },
+  countdown: (args) => {
+    const to = quote(args[0] ?? "launch");
+    return `scene width=600 height=600 bg=#0d1117
+
+actor three = text("3") at (270, 280) size 120 opacity 0
+actor two   = text("2") at (270, 280) size 120 opacity 0
+actor one   = text("1") at (270, 280) size 120 opacity 0
+actor go    = caption(${to}) at center
+
+@0.0: three.fade_in(dur=0.2)
+@0.9: three.fade_out(dur=0.2)
+@0.9: two.fade_in(dur=0.2)
+@1.8: two.fade_out(dur=0.2)
+@1.8: one.fade_in(dur=0.2)
+@2.7: one.fade_out(dur=0.2)
+@2.7: go.fade_in(dur=0.4)
+`;
+  },
+  reveal: (args) => {
+    const secret = quote(args[0] ?? "and that's the trick");
+    return `scene width=800 height=450 bg=#0d1117
+
+actor cover  = box() at (350, 175) scale 10 opacity 1
+actor reveal = caption(${secret}) at center
+
+@0.4: cover.fade_out(dur=0.5)
+@0.4: reveal.fade_in(dur=0.5)
+`;
+  },
+  glitch: (_args) => {
+    const txt = quote("GLITCH");
+    return `scene width=800 height=400 bg=#000
+
+actor t = text(${txt}) at (260, 170) size 72
+
+@0.0: t.fade_in(dur=0.2)
+@0.4: t.shake(intensity=10, dur=0.3)
+@0.8: t.shake(intensity=6, dur=0.3)
+@1.3: t.fade_out(dur=0.3)
+`;
+  },
+  zoom_punchline: (args) => {
+    const line = quote(args[0] ?? "the punchline");
+    return `scene width=800 height=450 bg=#0d1117
+
+actor line = caption(${line}) at center
+
+@0.0: line.fade_in(dur=0.4)
+@0.6: camera.zoom(to=1.4, dur=0.8, ease=out)
+@1.6: camera.shake(intensity=6, dur=0.4)
+`;
+  },
+  before_after: (args) => {
+    const before = quote(args[0] ?? "before");
+    const after = quote(args[1] ?? "after");
+    return `scene width=960 height=420 bg=#f6f7fb
+
+actor a    = caption(${before}) at top
+actor b    = caption(${after})  at bottom
+actor dude = figure(#c68642, m, \u{1F635}) at (480, 240)
+
+@0.0: a.fade_in(dur=0.3)
+@0.0: dude.enter(from=left, dur=0.5)
+@1.4: dude.face("\u{1F60E}")
+@1.4: b.fade_in(dur=0.3)
+`;
+  },
+  tier_list: (_args) => {
+    return `scene width=960 height=540 bg=#111
+
+actor s     = text("S") at (60, 90)  size 72 opacity 0
+actor a     = text("A") at (60, 200) size 72 opacity 0
+actor b     = text("B") at (60, 310) size 72 opacity 0
+actor c     = text("C") at (60, 420) size 72 opacity 0
+actor title = caption("tier list") at top
+
+@0.0: title.fade_in(dur=0.3)
+@0.3: s.fade_in(dur=0.2)
+@0.6: a.fade_in(dur=0.2)
+@0.9: b.fade_in(dur=0.2)
+@1.2: c.fade_in(dur=0.2)
+`;
+  }
+};
+var PRESET_NAMES = Object.keys(PRESETS);
+
 // src/parser.ts
 var ParseError = class extends Error {
   constructor(message, line) {
@@ -37,9 +263,15 @@ function stripComment(line) {
 function splitByComma(s) {
   const parts = [];
   let depth = 0;
+  let inString = false;
   let start = 0;
   for (let i = 0; i < s.length; i++) {
     const ch = s[i];
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
     if (ch === "(") depth++;
     else if (ch === ")") depth--;
     else if (ch === "," && depth === 0) {
@@ -93,31 +325,124 @@ function parseActionParams(action, raw) {
   }
   return params;
 }
-function parseModifiers(raw) {
+var UNIVERSAL_ACTIONS = /* @__PURE__ */ new Set([
+  "enter",
+  "exit",
+  "move",
+  "fade_in",
+  "fade_out",
+  "scale",
+  "rotate",
+  "shake",
+  "say",
+  "throw",
+  "play"
+]);
+var FIGURE_ONLY_ACTIONS = /* @__PURE__ */ new Set([
+  "punch",
+  "kick",
+  "wave",
+  "nod",
+  "jump",
+  "bounce",
+  "face",
+  "rotate_part",
+  "pose"
+]);
+var CAMERA_ACTIONS = /* @__PURE__ */ new Set(["pan", "zoom", "shake"]);
+function isKnownAction(actorType, action) {
+  if (actorType === "camera") return CAMERA_ACTIONS.has(action);
+  if (UNIVERSAL_ACTIONS.has(action)) return true;
+  return FIGURE_ONLY_ACTIONS.has(action);
+}
+var MODIFIER_KEYS = /* @__PURE__ */ new Set(["scale", "rotate", "opacity", "size", "z"]);
+function parseSpaceModifiers(raw, lineNum, warnings) {
   const result = {};
   const tokens = raw.trim().split(/\s+/).filter(Boolean);
   for (let i = 0; i + 1 < tokens.length; i += 2) {
     const key = tokens[i];
     const val = Number(tokens[i + 1]);
     if (Number.isNaN(val)) continue;
-    if (key === "scale") result.scale = val;
-    else if (key === "rotate") result.rotate = val;
-    else if (key === "opacity") result.opacity = val;
-    else if (key === "size") result.size = val;
+    if (MODIFIER_KEYS.has(key)) {
+      result[key] = val;
+    } else {
+      warnings.push({
+        kind: "unknown-modifier",
+        message: `unknown modifier "${key}" \u2014 ignored`,
+        line: lineNum
+      });
+    }
+  }
+  return result;
+}
+function parseWithModifiers(raw, lineNum, warnings) {
+  const result = {};
+  for (const token of splitByComma(raw)) {
+    const t = token.trim();
+    if (!t) continue;
+    const eqIdx = t.indexOf("=");
+    if (eqIdx === -1) {
+      warnings.push({
+        kind: "unknown-modifier",
+        message: `expected "key=value" in with-clause, got "${t}"`,
+        line: lineNum
+      });
+      continue;
+    }
+    const key = t.slice(0, eqIdx).trim();
+    const val = Number(t.slice(eqIdx + 1).trim());
+    if (Number.isNaN(val)) {
+      warnings.push({
+        kind: "unknown-modifier",
+        message: `modifier "${key}" needs a numeric value \u2014 ignored`,
+        line: lineNum
+      });
+      continue;
+    }
+    if (MODIFIER_KEYS.has(key)) {
+      result[key] = val;
+    } else {
+      warnings.push({
+        kind: "unknown-modifier",
+        message: `unknown modifier "${key}" \u2014 ignored`,
+        line: lineNum
+      });
+    }
   }
   return result;
 }
+function parseActorTrailer(trailerRaw, lineNum, warnings) {
+  const trimmed = trailerRaw.trim();
+  if (!trimmed) return {};
+  const withMatch = /(^|\s)with(\s|$)/.exec(trimmed);
+  if (!withMatch) {
+    return parseSpaceModifiers(trimmed, lineNum, warnings);
+  }
+  const before = trimmed.slice(0, withMatch.index).trim();
+  const after = trimmed.slice(withMatch.index + withMatch[0].length).trim();
+  const fromSpace = before ? parseSpaceModifiers(before, lineNum, warnings) : {};
+  const fromWith = after ? parseWithModifiers(after, lineNum, warnings) : {};
+  return { ...fromSpace, ...fromWith };
+}
 var ASSET_RE = /^asset\s+(\w+)\s*=\s*(image|icon)\("([^"]+)"\)$/;
-var BUILTIN_ACTOR_TYPES = /* @__PURE__ */ new Set(["sprite", "text", "box", "figure"]);
-var ACTOR_RE = /^actor\s+(\w+)\s*=\s*(\w+)\(([^)]*)\)\s+at\s+\(\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*\)(.*)$/;
-var EVENT_RE = /^@([\d.]+):\s+(\w+)\.(\w+)\((.*)\)$/;
+var BUILTIN_ACTOR_TYPES = /* @__PURE__ */ new Set(["sprite", "text", "box", "figure", "caption"]);
+var ACTOR_NUM_POS_RE = /^actor\s+(\w+)\s*=\s*([\w.]+)\(([^)]*)\)\s+at\s+\(\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*\)(.*)$/;
+var ACTOR_ANCHOR_POS_RE = /^actor\s+(\w+)\s*=\s*([\w.]+)\(([^)]*)\)\s+at\s+(top|bottom|center)\b(.*)$/;
+var EVENT_RE = /^@([\d.]+):\s+(\w+)\.(!?\w+)\((.*)\)$/;
+var REL_EVENT_RE = /^@\+([\d.]+):\s+(\w+)\.(!?\w+)\((.*)\)$/;
 var VAR_RE = /^var\s+(\w+)\s*=\s*(.+)$/;
 var DEF_HEADER_RE = /^def\s+(\w+)\(([^)]*)\)\s*\{$/;
-var DEF_BODY_RE = /^\s*(sprite|text|box|figure)\(([^)]*)\)\s*$/;
+var DEF_BODY_RE = /^\s*(sprite|text|box|figure|caption)\(([^)]*)\)\s*$/;
 var SEQ_HEADER_RE = /^seq\s+(\w+)(?:\(([^)]*)\))?\s*\{$/;
-var SEQ_EVENT_RE = /^@\+([\d.]+):\s+\$\.(\w+)\((.*)\)$/;
+var SEQ_EVENT_RE = /^@\+([\d.]+):\s+\$\.(!?\w+)\((.*)\)$/;
+var CHAPTER_HEADER_RE = /^scene\s+"([^"]+)"\s*\{$/;
+var IMPORT_RE = /^import\s+"([^"]+)"\s+as\s+(\w+)\s*$/;
+var PRESET_RE = /^preset\s+(\w+)(?:\s*\((.*)\))?\s*$/;
 function interpolate(s, vars) {
-  return s.replace(/\\?\$\{(\w+)\}/g, (_, name) => vars[name] ?? `\${${name}}`);
+  return s.replace(
+    /\\?\$\{([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)\}/g,
+    (_, name) => vars[name] ?? `\${${name}}`
+  );
 }
 var DEFAULTS = {
   width: 800,
@@ -125,6 +450,10 @@ var DEFAULTS = {
   fps: 30,
   bg: "white"
 };
+var CAPTION_TOP_Y_FRAC = 0.12;
+var CAPTION_BOTTOM_Y_FRAC = 0.88;
+var CAPTION_CENTER_Y_FRAC = 0.5;
+var KNOWN_SCENE_KEYS = /* @__PURE__ */ new Set(["width", "height", "fps", "bg", "duration"]);
 function validateMoveTarget(action, params, meta, actor, line) {
   if (action !== "move") return;
   const to = params.to;
@@ -137,7 +466,11 @@ function validateMoveTarget(action, params, meta, actor, line) {
     );
   }
 }
-function parse(source) {
+function parse(source, opts = {}) {
+  if (!opts._fromPreset) {
+    const expansion = tryExpandSolePreset(source);
+    if (expansion) return parse(expansion, { ...opts, _fromPreset: true });
+  }
   const ast = {
     meta: { ...DEFAULTS },
     assets: {},
@@ -145,13 +478,18 @@ function parse(source) {
     events: [],
     defs: {},
     seqs: {},
-    vars: {}
+    vars: {},
+    chapters: [],
+    warnings: [],
+    imports: []
   };
   let sceneFound = false;
   const lines = source.split(/\r?\n/);
   let inDef = null;
   let defNeedsClose = false;
   let inSeq = null;
+  let inChapter = null;
+  const topScope = { name: "", prevEnd: 0 };
   for (let i = 0; i < lines.length; i++) {
     const lineNum = i + 1;
     const rawUntouched = lines[i].trim();
@@ -181,6 +519,19 @@ function parse(source) {
         inSeq = null;
         continue;
       }
+      if (inChapter) {
+        const endTime = inChapter.scope.prevEnd;
+        const startTime = inChapter.earliestEventTime === Infinity ? inChapter.openedAt : Math.min(inChapter.openedAt, inChapter.earliestEventTime);
+        ast.chapters.push({
+          name: inChapter.name,
+          startLine: inChapter.startLine,
+          startTime,
+          endTime
+        });
+        if (endTime > topScope.prevEnd) topScope.prevEnd = endTime;
+        inChapter = null;
+        continue;
+      }
       throw new ParseError("Unexpected '}'", lineNum);
     }
     if (inDef) {
@@ -206,11 +557,35 @@ function parse(source) {
         throw new ParseError(`Invalid seq event (expected "@+offset: $.action(params)"): ${raw}`, lineNum);
       }
       const [, offsetStr, action, paramsRaw] = sm;
-      inSeq.events.push({
-        offset: Number(offsetStr),
-        action,
-        paramsRaw
-      });
+      inSeq.events.push({ offset: Number(offsetStr), action, paramsRaw });
+      continue;
+    }
+    if (raw.startsWith("import ")) {
+      const im = IMPORT_RE.exec(raw);
+      if (!im) {
+        throw new ParseError(`Invalid import declaration: ${raw}`, lineNum);
+      }
+      const [, path, namespace] = im;
+      const decl = { path, namespace, line: lineNum };
+      ast.imports.push(decl);
+      const resolved = opts.imports?.[namespace];
+      if (!resolved) {
+        ast.warnings.push({
+          kind: "import-unresolved",
+          message: `import "${path}" as ${namespace} \u2014 no pre-parsed AST supplied by host`,
+          line: lineNum
+        });
+      } else {
+        for (const [k, v] of Object.entries(resolved.vars)) {
+          ast.vars[`${namespace}.${k}`] = v;
+        }
+        for (const [k, v] of Object.entries(resolved.defs)) {
+          ast.defs[`${namespace}.${k}`] = v;
+        }
+        for (const [k, v] of Object.entries(resolved.seqs)) {
+          ast.seqs[`${namespace}.${k}`] = v;
+        }
+      }
       continue;
     }
     if (raw.startsWith("def ")) {
@@ -234,6 +609,30 @@ function parse(source) {
       continue;
     }
     if (/^scene(\s|$)/.test(raw)) {
+      const chm = CHAPTER_HEADER_RE.exec(raw);
+      if (chm) {
+        if (inChapter) {
+          throw new ParseError(
+            `Nested chapters are not supported; close chapter "${inChapter.name}" first`,
+            lineNum
+          );
+        }
+        const chapterName = chm[1];
+        inChapter = {
+          name: chapterName,
+          startLine: lineNum,
+          openedAt: topScope.prevEnd,
+          earliestEventTime: Infinity,
+          scope: { name: chapterName, prevEnd: topScope.prevEnd }
+        };
+        continue;
+      }
+      if (inChapter) {
+        throw new ParseError(
+          `scene header inside chapter "${inChapter.name}" is not allowed; close the chapter first or use 'scene "title" { ... }' for a nested section`,
+          lineNum
+        );
+      }
       if (sceneFound) {
         throw new ParseError("Duplicate scene declaration", lineNum);
       }
@@ -256,7 +655,12 @@ function parse(source) {
             ast.meta.duration = Number(val);
             break;
           default:
-            throw new ParseError(`Unknown scene property: ${key}`, lineNum);
+            if (KNOWN_SCENE_KEYS.has(key)) break;
+            ast.warnings.push({
+              kind: "unknown-scene-key",
+              message: `unknown scene property "${key}" \u2014 ignored`,
+              line: lineNum
+            });
         }
       }
       continue;
@@ -270,107 +674,31 @@ function parse(source) {
       ast.assets[name] = { type, value };
       continue;
     }
-    if (raw.startsWith("actor")) {
-      const m = ACTOR_RE.exec(raw);
-      if (!m) {
-        throw new ParseError(`Invalid actor declaration: ${raw}`, lineNum);
-      }
-      const [, name, typeName, argsRaw, xStr, yStr, modifiersRaw] = m;
-      let resolvedType;
-      let resolvedArgs;
-      if (BUILTIN_ACTOR_TYPES.has(typeName)) {
-        resolvedType = typeName;
-        resolvedArgs = argsRaw.trim() ? splitByComma(argsRaw).map((a) => {
-          const t = a.trim();
-          return t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1) : t;
-        }) : [];
-      } else if (ast.defs[typeName]) {
-        const tmpl = ast.defs[typeName];
-        const callArgs = argsRaw.trim() ? splitByComma(argsRaw).map((a) => {
-          const t = a.trim();
-          return t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1) : t;
-        }) : [];
-        const localVars = {};
-        for (let pi = 0; pi < tmpl.params.length; pi++) {
-          localVars[tmpl.params[pi]] = callArgs[pi] ?? "";
-        }
-        resolvedType = tmpl.actorType;
-        resolvedArgs = tmpl.bodyArgs.map((a) => interpolate(a, localVars));
+    if (raw.startsWith("preset ")) {
+      const pm = PRESET_RE.exec(raw);
+      const maybeName = pm?.[1];
+      if (maybeName && !PRESETS[maybeName]) {
+        const nameList = Object.keys(PRESETS).sort().join(", ");
+        ast.warnings.push({
+          kind: "unknown-preset",
+          message: `unknown preset "${maybeName}" \u2014 available: ${nameList}`,
+          line: lineNum
+        });
       } else {
-        throw new ParseError(`Unknown actor type or template: "${typeName}"`, lineNum);
+        ast.warnings.push({
+          kind: "preset-mixed",
+          message: "`preset` is a whole-file shorthand; mid-file presets are ignored",
+          line: lineNum
+        });
       }
-      const modifiers = parseModifiers(modifiersRaw);
-      const x = Number(xStr);
-      const y = Number(yStr);
-      if (x < 0 || x > ast.meta.width || y < 0 || y > ast.meta.height) {
-        throw new ParseError(
-          `Actor "${name}" position (${x}, ${y}) is outside scene bounds (0\u2013${ast.meta.width}, 0\u2013${ast.meta.height})`,
-          lineNum
-        );
-      }
-      ast.actors[name] = {
-        type: resolvedType,
-        args: resolvedArgs,
-        x,
-        y,
-        ...modifiers
-      };
+      continue;
+    }
+    if (raw.startsWith("actor ")) {
+      parseActorLine(raw, lineNum, ast);
       continue;
     }
     if (raw.startsWith("@")) {
-      const m = EVENT_RE.exec(raw);
-      if (!m) {
-        throw new ParseError(`Invalid event: ${raw}`, lineNum);
-      }
-      const [, timeStr, actor, action, paramsRaw] = m;
-      const time = Number(timeStr);
-      if (Number.isNaN(time)) {
-        throw new ParseError(`Invalid time value: ${timeStr}`, lineNum);
-      }
-      if (!ast.actors[actor]) {
-        throw new ParseError(`Unknown actor: "${actor}"`, lineNum);
-      }
-      if (action === "play") {
-        const playParts = splitByComma(paramsRaw);
-        const seqName = playParts[0]?.trim();
-        if (!seqName || !ast.seqs[seqName]) {
-          throw new ParseError(`Unknown sequence: "${seqName}"`, lineNum);
-        }
-        const seq = ast.seqs[seqName];
-        const playVars = {};
-        for (let pi = 1; pi < playParts.length; pi++) {
-          const eqIdx = playParts[pi].indexOf("=");
-          if (eqIdx !== -1) {
-            const k = playParts[pi].slice(0, eqIdx).trim();
-            const v = playParts[pi].slice(eqIdx + 1).trim();
-            playVars[k] = v;
-          }
-        }
-        let posIdx = 0;
-        for (let pi = 1; pi < playParts.length; pi++) {
-          if (!playParts[pi].includes("=") && posIdx < seq.params.length) {
-            playVars[seq.params[posIdx]] = playParts[pi].trim();
-            posIdx++;
-          }
-        }
-        for (const sev of seq.events) {
-          const expandedParams = interpolate(sev.paramsRaw, playVars);
-          const absTime = Math.round((time + sev.offset) * 1e3) / 1e3;
-          const params2 = parseActionParams(sev.action, expandedParams);
-          validateMoveTarget(sev.action, params2, ast.meta, actor, lineNum);
-          ast.events.push({
-            time: absTime,
-            actor,
-            action: sev.action,
-            params: params2,
-            line: lineNum
-          });
-        }
-        continue;
-      }
-      const params = parseActionParams(action, paramsRaw);
-      validateMoveTarget(action, params, ast.meta, actor, lineNum);
-      ast.events.push({ time, actor, action, params, line: lineNum });
+      parseEventLine(raw, lineNum, ast, inChapter, topScope);
       continue;
     }
     throw new ParseError(`Unrecognized statement: ${raw}`, lineNum);
@@ -384,17 +712,297 @@ function parse(source) {
   if (inSeq) {
     throw new ParseError(`Unclosed seq block "${inSeq.name}"`, inSeq.startLine);
   }
+  if (inChapter) {
+    throw new ParseError(`Unclosed chapter "${inChapter.name}"`, inChapter.startLine);
+  }
   if (ast.meta.duration === void 0) {
     let maxEnd = 0;
     for (const ev of ast.events) {
       const dur = typeof ev.params.dur === "number" ? ev.params.dur : 0;
       maxEnd = Math.max(maxEnd, ev.time + dur);
     }
-    if (maxEnd > 0) ast.meta.duration = maxEnd;
+    if (maxEnd > 0) ast.meta.duration = round3(maxEnd);
   }
   return ast;
 }
+function parseActorCallArgs(argsRaw) {
+  if (!argsRaw.trim()) return [];
+  return splitByComma(argsRaw).map((a) => {
+    const t = a.trim();
+    return t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1) : t;
+  });
+}
+function parseActorLine(raw, lineNum, ast) {
+  const amAnchor = ACTOR_ANCHOR_POS_RE.exec(raw);
+  const amNum = amAnchor ? null : ACTOR_NUM_POS_RE.exec(raw);
+  if (!amAnchor && !amNum) {
+    throw new ParseError(`Invalid actor declaration: ${raw}`, lineNum);
+  }
+  let name;
+  let typeName;
+  let argsRaw;
+  let x;
+  let y;
+  let anchor;
+  let trailer;
+  if (amAnchor) {
+    const [, nm, tn, ar, an, tr] = amAnchor;
+    name = nm;
+    typeName = tn;
+    argsRaw = ar;
+    anchor = an;
+    trailer = tr;
+    x = ast.meta.width / 2;
+    switch (anchor) {
+      case "top":
+        y = Math.round(ast.meta.height * CAPTION_TOP_Y_FRAC);
+        break;
+      case "bottom":
+        y = Math.round(ast.meta.height * CAPTION_BOTTOM_Y_FRAC);
+        break;
+      default:
+        y = Math.round(ast.meta.height * CAPTION_CENTER_Y_FRAC);
+        break;
+    }
+  } else {
+    const [, nm, tn, ar, xs, ys, tr] = amNum;
+    name = nm;
+    typeName = tn;
+    argsRaw = ar;
+    x = Number(xs);
+    y = Number(ys);
+    trailer = tr;
+  }
+  if (name === "camera") {
+    throw new ParseError(
+      `"camera" is a reserved actor name; drop this declaration and use camera.pan/zoom/shake directly`,
+      lineNum
+    );
+  }
+  const rawArgs = parseActorCallArgs(argsRaw);
+  let resolvedType;
+  let resolvedArgs;
+  if (BUILTIN_ACTOR_TYPES.has(typeName)) {
+    resolvedType = typeName;
+    resolvedArgs = rawArgs;
+  } else if (ast.defs[typeName]) {
+    const tmpl = ast.defs[typeName];
+    const localVars = {};
+    for (let pi = 0; pi < tmpl.params.length; pi++) {
+      localVars[tmpl.params[pi]] = rawArgs[pi] ?? "";
+    }
+    resolvedType = tmpl.actorType;
+    resolvedArgs = tmpl.bodyArgs.map((a) => interpolate(a, localVars));
+  } else {
+    throw new ParseError(`Unknown actor type or template: "${typeName}"`, lineNum);
+  }
+  const modifiers = parseActorTrailer(trailer, lineNum, ast.warnings);
+  if (anchor && resolvedType !== "caption") {
+    throw new ParseError(
+      `anchor syntax "at ${anchor}" only applies to caption actors; got ${typeName}`,
+      lineNum
+    );
+  }
+  if (resolvedType === "caption" && !anchor) {
+    throw new ParseError(
+      `Caption actors require anchor syntax (\`at top | bottom | center\`); got numeric position (${x}, ${y}) for "${name}"`,
+      lineNum
+    );
+  }
+  if (!anchor && (x < 0 || x > ast.meta.width || y < 0 || y > ast.meta.height)) {
+    throw new ParseError(
+      `Actor "${name}" position (${x}, ${y}) is outside scene bounds (0\u2013${ast.meta.width}, 0\u2013${ast.meta.height})`,
+      lineNum
+    );
+  }
+  ast.actors[name] = {
+    type: resolvedType,
+    args: resolvedArgs,
+    x,
+    y,
+    ...modifiers,
+    ...anchor ? { anchor } : {}
+  };
+}
+function parseEventLine(raw, lineNum, ast, inChapter, topScope) {
+  const scope = inChapter?.scope ?? topScope;
+  const recordEventTime = (t) => {
+    if (inChapter && t < inChapter.earliestEventTime) {
+      inChapter.earliestEventTime = t;
+    }
+  };
+  const rel = REL_EVENT_RE.exec(raw);
+  const abs = rel ? null : EVENT_RE.exec(raw);
+  if (!rel && !abs) {
+    throw new ParseError(`Invalid event: ${raw}`, lineNum);
+  }
+  let time;
+  let actor;
+  let actionToken;
+  let paramsRaw;
+  if (rel) {
+    const [, offsetStr, act, action2, pr] = rel;
+    const offset = Number(offsetStr);
+    if (Number.isNaN(offset)) {
+      throw new ParseError(`Invalid @+offset value: ${offsetStr}`, lineNum);
+    }
+    time = round3(scope.prevEnd + offset);
+    actor = act;
+    actionToken = action2;
+    paramsRaw = pr;
+  } else {
+    const [, timeStr, act, action2, pr] = abs;
+    const t = Number(timeStr);
+    if (Number.isNaN(t)) {
+      throw new ParseError(`Invalid time value: ${timeStr}`, lineNum);
+    }
+    time = t;
+    actor = act;
+    actionToken = action2;
+    paramsRaw = pr;
+  }
+  const mustUnderstand = actionToken.startsWith("!");
+  const action = mustUnderstand ? actionToken.slice(1) : actionToken;
+  if (actor === "camera") {
+    if (!CAMERA_ACTIONS.has(action)) {
+      if (mustUnderstand) {
+        throw new ParseError(`Unknown camera action "${action}"`, lineNum);
+      }
+      ast.warnings.push({
+        kind: "unknown-camera-action",
+        message: `unknown camera action "${action}" \u2014 renderer will no-op`,
+        line: lineNum
+      });
+    }
+    const params2 = parseActionParams(action, paramsRaw);
+    recordEventTime(time);
+    pushEvent(ast, scope, {
+      time,
+      actor: "camera",
+      action,
+      params: params2,
+      line: lineNum,
+      ...inChapter ? { chapter: inChapter.name } : {}
+    });
+    return;
+  }
+  const actorDef = ast.actors[actor];
+  if (!actorDef) {
+    throw new ParseError(`Unknown actor: "${actor}"`, lineNum);
+  }
+  if (action === "play") {
+    const playParts = splitByComma(paramsRaw);
+    const seqName = playParts[0]?.trim();
+    if (!seqName || !ast.seqs[seqName]) {
+      throw new ParseError(`Unknown sequence: "${seqName}"`, lineNum);
+    }
+    const seq = ast.seqs[seqName];
+    const playVars = {};
+    for (let pi = 1; pi < playParts.length; pi++) {
+      const eqIdx = playParts[pi].indexOf("=");
+      if (eqIdx !== -1) {
+        const k = playParts[pi].slice(0, eqIdx).trim();
+        const v = playParts[pi].slice(eqIdx + 1).trim();
+        playVars[k] = v;
+      }
+    }
+    let posIdx = 0;
+    for (let pi = 1; pi < playParts.length; pi++) {
+      if (!playParts[pi].includes("=") && posIdx < seq.params.length) {
+        playVars[seq.params[posIdx]] = playParts[pi].trim();
+        posIdx++;
+      }
+    }
+    for (const sev of seq.events) {
+      const expandedParams = interpolate(sev.paramsRaw, playVars);
+      const absTime = round3(time + sev.offset);
+      const sevMustUnderstand = sev.action.startsWith("!");
+      const sevAction = sevMustUnderstand ? sev.action.slice(1) : sev.action;
+      validateActionForActor(sevAction, actorDef, sevMustUnderstand, lineNum, ast.warnings);
+      const params2 = parseActionParams(sevAction, expandedParams);
+      validateMoveTarget(sevAction, params2, ast.meta, actor, lineNum);
+      recordEventTime(absTime);
+      pushEvent(ast, scope, {
+        time: absTime,
+        actor,
+        action: sevAction,
+        params: params2,
+        line: lineNum,
+        ...inChapter ? { chapter: inChapter.name } : {}
+      });
+    }
+    return;
+  }
+  validateActionForActor(action, actorDef, mustUnderstand, lineNum, ast.warnings);
+  const params = parseActionParams(action, paramsRaw);
+  validateMoveTarget(action, params, ast.meta, actor, lineNum);
+  recordEventTime(time);
+  pushEvent(ast, scope, {
+    time,
+    actor,
+    action,
+    params,
+    line: lineNum,
+    ...inChapter ? { chapter: inChapter.name } : {}
+  });
+}
+function pushEvent(ast, scope, ev) {
+  ast.events.push(ev);
+  const dur = typeof ev.params.dur === "number" ? ev.params.dur : 0;
+  const endTime = round3(ev.time + dur);
+  if (endTime > scope.prevEnd) scope.prevEnd = endTime;
+}
+function validateActionForActor(action, actorDef, mustUnderstand, lineNum, warnings) {
+  if (FIGURE_ONLY_ACTIONS.has(action)) {
+    if (actorDef.type !== "figure") {
+      throw new ParseError(
+        `action "${action}" is figure-only; actor type is "${actorDef.type}"`,
+        lineNum
+      );
+    }
+    return;
+  }
+  if (isKnownAction(actorDef.type, action)) return;
+  if (mustUnderstand) {
+    throw new ParseError(`Unknown action "${action}" (must-understand form)`, lineNum);
+  }
+  warnings.push({
+    kind: "unknown-action",
+    message: `unknown action "${action}" on ${actorDef.type} actor \u2014 renderer will no-op`,
+    line: lineNum
+  });
+}
+function tryExpandSolePreset(source) {
+  const lines = source.split(/\r?\n/);
+  let presetLine = null;
+  for (const raw of lines) {
+    const stripped = stripComment(raw).trim();
+    if (!stripped) continue;
+    if (stripped.startsWith("preset ")) {
+      if (presetLine) return null;
+      presetLine = stripped;
+    } else {
+      return null;
+    }
+  }
+  if (!presetLine) return null;
+  const pm = PRESET_RE.exec(presetLine);
+  if (!pm) return null;
+  const [, name, argsRaw] = pm;
+  const fn = PRESETS[name];
+  if (!fn) return null;
+  const args = argsRaw ? splitByComma(argsRaw).map((a) => {
+    const t = a.trim();
+    return t.startsWith('"') && t.endsWith('"') ? t.slice(1, -1) : t;
+  }) : [];
+  return fn(args);
+}
+function round3(n) {
+  return Math.round(n * 1e3) / 1e3;
+}
 export {
+  PRESETS,
+  PRESET_NAMES,
   ParseError,
   parse
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdy/core",
-  "version": "0.5.8",
+  "version": "0.7.0",
   "description": "MarkdyScript parser and AST types — zero runtime dependencies.",
   "license": "MIT",
   "type": "module",