@markdy/core 0.7.25 → 0.7.27

package/dist/index.d.ts

@@ -116,6 +116,12 @@ type SceneAST = {
     seqs: Record<string, SequenceDef>;
     /** User-defined variables — kept in AST for tooling/inspection. */
     vars: Record<string, string>;
+    /**
+     * Named actor groups, in declaration order, mapping group name to member
+     * actor names. Groups fan out into per-actor events at parse time, so the
+     * renderer never sees them — this is kept for tooling and inspection.
+     */
+    groups: 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. */
@@ -180,6 +186,25 @@ type PresetFn = (args: string[]) => string;
 declare const PRESETS: Record<string, PresetFn>;
 declare const PRESET_NAMES: readonly string[];
 
+/**
+ * The canonical vocabulary of the language.
+ *
+ * These arrays are the single source of truth for every tool that needs to
+ * know what Markdy understands — the parser, the language server, the
+ * playground's syntax highlighter, and the renderer's handler-coverage test.
+ * Anything that hard-codes its own copy will silently drift out of date, so
+ * import from here instead.
+ */
+declare const BUILTIN_ACTOR_TYPES: readonly BuiltinActorType[];
+/** Actions valid on every actor type. */
+declare const UNIVERSAL_ACTION_NAMES: readonly ["enter", "exit", "move", "spring", "follow_path", "fade_in", "fade_out", "scale", "rotate", "shake", "pulse", "glow", "ripple", "blur", "line_reveal", "mask", "parallax", "say", "throw", "play"];
+/**
+ * Actions that require a `figure` actor. Applying one to any other actor
+ * type is a hard `ParseError`, not a soft warning — it's always a mistake.
+ */
+declare const FIGURE_ONLY_ACTION_NAMES: readonly ["punch", "kick", "wave", "nod", "jump", "bounce", "face", "rotate_part", "pose"];
+/** Actions valid on the reserved `camera` actor. */
+declare const CAMERA_ACTION_NAMES: readonly ["pan", "zoom", "shake"];
 type ActorPack = {
     name: string;
     actors: readonly string[];
@@ -187,4 +212,4 @@ type ActorPack = {
 };
 declare function registerActorPack(pack: ActorPack): void;
 
-export { type ActorDef, type ActorPack, type ActorType, type AssetDef, type BuiltinActorType, 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, registerActorPack };
+export { type ActorDef, type ActorPack, type ActorType, type AssetDef, BUILTIN_ACTOR_TYPES, type BuiltinActorType, CAMERA_ACTION_NAMES, type Chapter, FIGURE_ONLY_ACTION_NAMES, type ImportDecl, PRESETS, PRESET_NAMES, ParseError, type ParseOptions, type ParseWarning, type PresetFn, type SceneAST, type SceneMeta, type SequenceDef, type TemplateDef, type TimelineEvent, UNIVERSAL_ACTION_NAMES, parse, registerActorPack };

package/dist/index.js

@@ -232,20 +232,29 @@ var BUILTIN_ACTOR_TYPES = [
   "figure",
   "caption"
 ];
-var UNIVERSAL_ACTIONS = /* @__PURE__ */ new Set([
+var UNIVERSAL_ACTION_NAMES = [
   "enter",
   "exit",
   "move",
+  "spring",
+  "follow_path",
   "fade_in",
   "fade_out",
   "scale",
   "rotate",
   "shake",
+  "pulse",
+  "glow",
+  "ripple",
+  "blur",
+  "line_reveal",
+  "mask",
+  "parallax",
   "say",
   "throw",
   "play"
-]);
-var FIGURE_ONLY_ACTIONS = /* @__PURE__ */ new Set([
+];
+var FIGURE_ONLY_ACTION_NAMES = [
   "punch",
   "kick",
   "wave",
@@ -255,8 +264,11 @@ var FIGURE_ONLY_ACTIONS = /* @__PURE__ */ new Set([
   "face",
   "rotate_part",
   "pose"
-]);
-var CAMERA_ACTIONS = /* @__PURE__ */ new Set(["pan", "zoom", "shake"]);
+];
+var CAMERA_ACTION_NAMES = ["pan", "zoom", "shake"];
+var UNIVERSAL_ACTIONS = new Set(UNIVERSAL_ACTION_NAMES);
+var FIGURE_ONLY_ACTIONS = new Set(FIGURE_ONLY_ACTION_NAMES);
+var CAMERA_ACTIONS = new Set(CAMERA_ACTION_NAMES);
 var actorTypes = new Set(BUILTIN_ACTOR_TYPES);
 var actorActions = /* @__PURE__ */ new Map();
 function registerActorPack(pack) {
@@ -514,6 +526,22 @@ 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*$/;
+var ARCHITECTURE_NODE_RE = /^(service|database|db|queue|cache|api|user|client|cloud|region|container|microservice|cluster)\s+(\w+)(?:\s+("[^"]+"|'[^']+'))?(?:\s+at\s+\(\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*\))?(.*)$/;
+var ARCHITECTURE_ALIAS_TO_TYPE = {
+  api: "service",
+  database: "database",
+  db: "db",
+  user: "client",
+  client: "client",
+  service: "service",
+  queue: "queue",
+  cache: "cache",
+  cloud: "cloud",
+  region: "region",
+  container: "container",
+  microservice: "microservice",
+  cluster: "cluster"
+};
 function interpolate(s, vars) {
   return s.replace(
     /\\?\$\{([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*)\}/g,
@@ -555,6 +583,7 @@ function parse(source, opts = {}) {
     defs: {},
     seqs: {},
     vars: {},
+    groups: {},
     chapters: [],
     warnings: [],
     imports: []
@@ -775,7 +804,7 @@ function parse(source, opts = {}) {
       }
       continue;
     }
-    if (raw.startsWith("actor ")) {
+    if (raw.startsWith("actor ") || isArchitectureNodeLine(raw)) {
       const actorInfo = parseActorLine(raw, lineNum, ast);
       if (!actorCountWarned && actorCountWarningThreshold > 0) {
         const actorCount = Object.keys(ast.actors).length;
@@ -800,6 +829,10 @@ function parse(source, opts = {}) {
       }
       continue;
     }
+    if (raw.startsWith("group ")) {
+      parseGroupLine(raw, lineNum, ast);
+      continue;
+    }
     if (raw.startsWith("@")) {
       parseEventLine(raw, lineNum, ast, inChapter, topScope);
       continue;
@@ -837,6 +870,8 @@ function parseActorCallArgs(argsRaw) {
   });
 }
 function parseActorLine(raw, lineNum, ast) {
+  const architectureNode = parseArchitectureNodeLine(raw, lineNum, ast);
+  if (architectureNode) return architectureNode;
   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);
@@ -927,6 +962,110 @@ function parseActorLine(raw, lineNum, ast) {
   };
   return { name, args: resolvedArgs };
 }
+function isArchitectureNodeLine(raw) {
+  return ARCHITECTURE_NODE_RE.test(raw);
+}
+function parseArchitectureNodeLine(raw, lineNum, ast) {
+  const m = ARCHITECTURE_NODE_RE.exec(raw);
+  if (!m) return null;
+  const [, alias, name, labelRaw, xRaw, yRaw, trailer] = m;
+  if (name === "camera") {
+    throw new ParseError(
+      `"camera" is a reserved actor name; choose a different architecture node name`,
+      lineNum
+    );
+  }
+  const typeName = ARCHITECTURE_ALIAS_TO_TYPE[alias] ?? alias;
+  if (!isKnownActorType(typeName)) {
+    throw new ParseError(
+      `Architecture node "${alias}" requires an actor pack that registers type "${typeName}"`,
+      lineNum
+    );
+  }
+  const actorIndex = Object.keys(ast.actors).length;
+  const x = xRaw === void 0 ? autoNodeX(actorIndex, ast.meta.width) : Number(xRaw);
+  const y = yRaw === void 0 ? autoNodeY(actorIndex, ast.meta.height, ast.meta.width) : Number(yRaw);
+  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
+    );
+  }
+  const quoted = labelRaw ? parseQuotedLiteral(labelRaw.trim()) : null;
+  const label = quoted ?? labelRaw?.trim() ?? name;
+  const modifiers = parseActorTrailer(trailer, lineNum, ast.warnings);
+  ast.actors[name] = {
+    type: typeName,
+    args: [label],
+    x,
+    y,
+    ...modifiers
+  };
+  return { name, args: [label] };
+}
+function autoNodeX(index, width) {
+  const columns = Math.max(1, Math.floor(width / 220));
+  const gutter = width / (columns + 1);
+  return Math.round(gutter * (index % columns + 1));
+}
+function autoNodeY(index, height, width = DEFAULTS.width) {
+  const columns = Math.max(1, Math.floor(width / 220));
+  const row = Math.floor(index / columns);
+  return Math.min(height - 60, 90 + row * 120);
+}
+var GROUP_RE = /^group\s+([A-Za-z_][\w.]*)\s*=\s*(.+)$/;
+function parseGroupLine(raw, lineNum, ast) {
+  const m = GROUP_RE.exec(raw);
+  if (!m) {
+    throw new ParseError(`Invalid group declaration: ${raw}`, lineNum);
+  }
+  const [, name, membersRaw] = m;
+  if (ast.actors[name]) {
+    throw new ParseError(`Group "${name}" collides with an actor of the same name`, lineNum);
+  }
+  if (ast.groups[name]) {
+    throw new ParseError(`Group "${name}" is already defined`, lineNum);
+  }
+  const members = splitByComma(membersRaw).map((part) => part.trim()).filter((part) => part.length > 0);
+  if (members.length === 0) {
+    throw new ParseError(`Group "${name}" has no members`, lineNum);
+  }
+  for (const member of members) {
+    if (!ast.actors[member]) {
+      throw new ParseError(`Unknown actor "${member}" in group "${name}"`, lineNum);
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const member of members) {
+    if (seen.has(member)) {
+      throw new ParseError(`Actor "${member}" listed twice in group "${name}"`, lineNum);
+    }
+    seen.add(member);
+  }
+  ast.groups[name] = members;
+}
+function takeStagger(paramsRaw, lineNum) {
+  if (!paramsRaw.includes("stagger")) return { step: 0, rest: paramsRaw };
+  const kept = [];
+  let step = 0;
+  for (const part of splitByComma(paramsRaw)) {
+    const eq = part.indexOf("=");
+    if (eq !== -1 && part.slice(0, eq).trim() === "stagger") {
+      const rawValue = part.slice(eq + 1).trim();
+      const value = Number(rawValue);
+      if (Number.isNaN(value)) {
+        throw new ParseError(`Invalid stagger value: ${rawValue}`, lineNum);
+      }
+      if (value < 0) {
+        throw new ParseError(`stagger must not be negative (got ${rawValue})`, lineNum);
+      }
+      step = value;
+      continue;
+    }
+    kept.push(part);
+  }
+  return { step, rest: kept.join(",") };
+}
 function parseEventLine(raw, lineNum, ast, inChapter, topScope) {
   const scope = inChapter?.scope ?? topScope;
   const recordEventTime = (t) => {
@@ -977,18 +1116,54 @@ function parseEventLine(raw, lineNum, ast, inChapter, topScope) {
         line: lineNum
       });
     }
-    const params2 = parseActionParams(action, paramsRaw);
+    const params = parseActionParams(action, paramsRaw);
     recordEventTime(time);
     pushEvent(ast, scope, {
       time,
       actor: "camera",
       action,
-      params: params2,
+      params,
       line: lineNum,
       ...inChapter ? { chapter: inChapter.name } : {}
     });
     return;
   }
+  const groupMembers = ast.groups[actor];
+  if (!groupMembers && !ast.actors[actor]) {
+    throw new ParseError(`Unknown actor: "${actor}"`, lineNum);
+  }
+  if (groupMembers) {
+    const { step, rest } = takeStagger(paramsRaw, lineNum);
+    groupMembers.forEach((member, index) => {
+      emitActorEvent(
+        member,
+        round3(time + index * step),
+        action,
+        rest,
+        mustUnderstand,
+        lineNum,
+        ast,
+        scope,
+        inChapter,
+        recordEventTime
+      );
+    });
+    return;
+  }
+  emitActorEvent(
+    actor,
+    time,
+    action,
+    paramsRaw,
+    mustUnderstand,
+    lineNum,
+    ast,
+    scope,
+    inChapter,
+    recordEventTime
+  );
+}
+function emitActorEvent(actor, time, action, paramsRaw, mustUnderstand, lineNum, ast, scope, inChapter, recordEventTime) {
   const actorDef = ast.actors[actor];
   if (!actorDef) {
     throw new ParseError(`Unknown actor: "${actor}"`, lineNum);
@@ -1105,9 +1280,13 @@ function round3(n) {
   return Math.round(n * 1e3) / 1e3;
 }
 export {
+  BUILTIN_ACTOR_TYPES,
+  CAMERA_ACTION_NAMES,
+  FIGURE_ONLY_ACTION_NAMES,
   PRESETS,
   PRESET_NAMES,
   ParseError,
+  UNIVERSAL_ACTION_NAMES,
   parse,
   registerActorPack
 };

package/package.json

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