@markdy/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hoang Yell (https://hoangyell.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @markdy/core
+
+The parser and AST types for [MarkdyScript](../../docs/SYNTAX.md) — a DSL for describing 2D animated scenes.
+
+## Features
+
+- **Zero runtime dependencies** — pure TypeScript, no DOM or platform APIs
+- **Single-pass parser** — line-by-line state machine with strict `ParseError` diagnostics
+- **Rich type system** — `var`, `def`, `seq` expanded at parse time for composable scene authoring
+- **Isomorphic** — runs in Node.js, Deno, Bun, edge runtimes, and the browser
+
+## Installation
+
+```sh
+pnpm add @markdy/core
+```
+
+## Usage
+
+```typescript
+import { parse, ParseError } from "@markdy/core";
+import type { SceneAST } from "@markdy/core";
+
+const source = `
+  scene width=600 height=300 bg=white
+  actor label = text("Hello") at (50, 130) size 40 opacity 0
+  @0.3: label.fade_in(dur=0.6)
+`;
+
+try {
+  const ast: SceneAST = parse(source);
+
+  console.log(ast.meta);     // { width: 600, height: 300, fps: 30, bg: "white", duration: 0.9 }
+  console.log(ast.actors);   // { label: { type: "text", args: ["Hello"], x: 50, y: 130, ... } }
+  console.log(ast.events);   // [{ time: 0.3, actor: "label", action: "fade_in", ... }]
+} catch (e) {
+  if (e instanceof ParseError) {
+    console.error(`Line ${e.line}: ${e.message}`);
+  }
+}
+```
+
+## Exports
+
+| Export | Type | Description |
+|---|---|---|
+| `parse` | `(source: string) => SceneAST` | Parse MarkdyScript source into an AST |
+| `ParseError` | class | Error with `.line` number for diagnostics |
+| `SceneAST` | type | Complete scene representation |
+| `SceneMeta` | type | Scene configuration (width, height, bg, etc.) |
+| `AssetDef` | type | Asset declaration (image or icon) |
+| `ActorDef` | type | Actor declaration (type, position, modifiers) |
+| `TimelineEvent` | type | Timeline event (time, actor, action, params) |
+| `TemplateDef` | type | User-defined actor template |
+| `SequenceDef` | type | User-defined animation sequence |
+
+## Documentation
+
+- **[Syntax Reference](../../docs/SYNTAX.md)** — complete DSL language spec
+- **[Tutorial](../../docs/TUTORIAL.md)** — step-by-step guide
+- **[Agent Guide](../../docs/AGENT.md)** — structured reference for AI/LLM code generation
+- **[Architecture](../../docs/ARCHITECTURE.md)** — parser internals and design decisions
+
+## License
+
+[MIT](../../LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * AST types for MarkdyScript — the complete output of the parser.
+ * Zero runtime dependencies.
+ */
+type AssetDef = {
+    type: "image" | "icon";
+    value: string;
+};
+type ActorDef = {
+    type: "sprite" | "text" | "box" | "figure";
+    /** Constructor arguments: asset name for sprite, display text for text actors. */
+    args: string[];
+    x: number;
+    y: number;
+    scale?: number;
+    rotate?: number;
+    opacity?: number;
+    /** Font size in pixels; applies to text actors (via the `size` modifier). */
+    size?: number;
+};
+type TimelineEvent = {
+    time: number;
+    actor: string;
+    action: string;
+    params: Record<string, unknown>;
+    line: number;
+};
+type SceneMeta = {
+    width: number;
+    height: number;
+    fps: number;
+    bg: string;
+    /** Auto-computed from the last event + its dur param when not explicitly set. */
+    duration?: number;
+};
+/**
+ * A user-defined actor template (`def`).
+ * Expands to an actor type + args at parse time — the renderer never sees it.
+ */
+type TemplateDef = {
+    /** Parameter names declared on the def line. */
+    params: string[];
+    /** The actor type this def expands to (e.g. "figure", "sprite"). */
+    actorType: ActorDef["type"];
+    /** Raw constructor arg tokens (may contain `${param}` references). */
+    bodyArgs: string[];
+};
+/**
+ * A user-defined reusable animation sequence (`seq`).
+ * Expanded inline wherever `actor.play(seqName)` appears.
+ */
+type SequenceDef = {
+    /** Parameter names (excluding the implicit `$` target actor). */
+    params: string[];
+    /** Raw event lines with `@+offset` and `$` actor placeholder. */
+    events: Array<{
+        offset: number;
+        action: string;
+        paramsRaw: string;
+    }>;
+};
+type SceneAST = {
+    meta: SceneMeta;
+    assets: Record<string, AssetDef>;
+    actors: Record<string, ActorDef>;
+    events: TimelineEvent[];
+    /** User-defined actor templates — kept in AST for tooling/inspection. */
+    defs: Record<string, TemplateDef>;
+    /** User-defined sequences — kept in AST for tooling/inspection. */
+    seqs: Record<string, SequenceDef>;
+    /** User-defined variables — kept in AST for tooling/inspection. */
+    vars: Record<string, string>;
+};
+
+declare class ParseError extends Error {
+    readonly line: number;
+    constructor(message: string, line: number);
+}
+declare function parse(source: string): SceneAST;
+
+export { type ActorDef, type AssetDef, ParseError, type SceneAST, type SceneMeta, type SequenceDef, type TemplateDef, type TimelineEvent, parse };

package/dist/index.js

@@ -0,0 +1,373 @@
+// src/parser.ts
+var ParseError = class extends Error {
+  constructor(message, line) {
+    super(`Line ${line}: ${message}`);
+    this.line = line;
+    this.name = "ParseError";
+  }
+  line;
+};
+function stripComment(line) {
+  let depth = 0;
+  let inString = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === ")") {
+      depth--;
+      continue;
+    }
+    if (ch === "#" && depth === 0) return line.slice(0, i);
+  }
+  return line;
+}
+function splitByComma(s) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === "(") depth++;
+    else if (ch === ")") depth--;
+    else if (ch === "," && depth === 0) {
+      parts.push(s.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts;
+}
+function parseValue(s) {
+  const t = s.trim();
+  if (t.startsWith('"') && t.endsWith('"')) {
+    return t.slice(1, -1);
+  }
+  if (t.startsWith("(") && t.endsWith(")")) {
+    const inner = t.slice(1, -1);
+    return inner.split(",").map((p) => {
+      const v = p.trim();
+      const n2 = Number(v);
+      return Number.isNaN(n2) ? v : n2;
+    });
+  }
+  const n = Number(t);
+  if (!Number.isNaN(n) && t !== "") return n;
+  return t;
+}
+var POSITIONAL_KEYS = {
+  say: ["text"],
+  throw: ["asset"]
+};
+function parseActionParams(action, raw) {
+  const params = {};
+  const trimmed = raw.trim();
+  if (!trimmed) return params;
+  const positionalKeys = POSITIONAL_KEYS[action] ?? [];
+  let positionalIndex = 0;
+  for (const token of splitByComma(trimmed)) {
+    const t = token.trim();
+    if (!t) continue;
+    const eqIdx = t.indexOf("=");
+    if (eqIdx === -1) {
+      const key = positionalKeys[positionalIndex] ?? `_${positionalIndex}`;
+      positionalIndex++;
+      params[key] = parseValue(t);
+    } else {
+      const key = t.slice(0, eqIdx).trim();
+      const val = t.slice(eqIdx + 1).trim();
+      params[key] = parseValue(val);
+    }
+  }
+  return params;
+}
+function parseModifiers(raw) {
+  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;
+  }
+  return result;
+}
+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 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 SEQ_HEADER_RE = /^seq\s+(\w+)(?:\(([^)]*)\))?\s*\{$/;
+var SEQ_EVENT_RE = /^@\+([\d.]+):\s+\$\.(\w+)\((.*)\)$/;
+function interpolate(s, vars) {
+  return s.replace(/\$\{(\w+)\}/g, (_, name) => vars[name] ?? `\${${name}}`);
+}
+var DEFAULTS = {
+  width: 800,
+  height: 400,
+  fps: 30,
+  bg: "white"
+};
+function parse(source) {
+  const ast = {
+    meta: { ...DEFAULTS },
+    assets: {},
+    actors: {},
+    events: [],
+    defs: {},
+    seqs: {},
+    vars: {}
+  };
+  let sceneFound = false;
+  const lines = source.split(/\r?\n/);
+  let inDef = null;
+  let defNeedsClose = false;
+  let inSeq = null;
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const rawUntouched = lines[i].trim();
+    if (!inDef && !defNeedsClose && !inSeq && rawUntouched.startsWith("var ")) {
+      const varLine = interpolate(rawUntouched, ast.vars);
+      const vm = VAR_RE.exec(varLine);
+      if (!vm) {
+        throw new ParseError(`Invalid var declaration: ${varLine}`, lineNum);
+      }
+      const [, name, value] = vm;
+      ast.vars[name] = value.trim();
+      continue;
+    }
+    let raw = stripComment(lines[i]).trim();
+    if (!raw) continue;
+    raw = interpolate(raw, ast.vars);
+    if (raw === "}") {
+      if (defNeedsClose) {
+        defNeedsClose = false;
+        continue;
+      }
+      if (inDef) {
+        throw new ParseError(`Empty def body for "${inDef.name}"`, lineNum);
+      }
+      if (inSeq) {
+        ast.seqs[inSeq.name] = { params: inSeq.params, events: inSeq.events };
+        inSeq = null;
+        continue;
+      }
+      throw new ParseError("Unexpected '}'", lineNum);
+    }
+    if (inDef) {
+      const bm = DEF_BODY_RE.exec(raw);
+      if (!bm) {
+        throw new ParseError(`Invalid def body (expected "type(args)"): ${raw}`, lineNum);
+      }
+      const [, actorType, bodyArgsRaw] = bm;
+      const bodyArgs = bodyArgsRaw.trim() ? splitByComma(bodyArgsRaw).map((a) => a.trim()) : [];
+      ast.defs[inDef.name] = {
+        params: inDef.params,
+        actorType,
+        bodyArgs
+      };
+      inDef = null;
+      defNeedsClose = true;
+      continue;
+    }
+    if (inSeq) {
+      const interpolatedSeq = interpolate(raw, ast.vars);
+      const sm = SEQ_EVENT_RE.exec(interpolatedSeq);
+      if (!sm) {
+        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
+      });
+      continue;
+    }
+    if (raw.startsWith("def ")) {
+      const dm = DEF_HEADER_RE.exec(raw);
+      if (!dm) {
+        throw new ParseError(`Invalid def declaration: ${raw}`, lineNum);
+      }
+      const [, name, paramsRaw] = dm;
+      const params = paramsRaw.split(",").map((p) => p.trim()).filter(Boolean);
+      inDef = { name, params, startLine: lineNum };
+      continue;
+    }
+    if (raw.startsWith("seq ")) {
+      const sm = SEQ_HEADER_RE.exec(raw);
+      if (!sm) {
+        throw new ParseError(`Invalid seq declaration: ${raw}`, lineNum);
+      }
+      const [, name, paramsRaw] = sm;
+      const params = paramsRaw ? paramsRaw.split(",").map((p) => p.trim()).filter(Boolean) : [];
+      inSeq = { name, params, events: [], startLine: lineNum };
+      continue;
+    }
+    if (/^scene(\s|$)/.test(raw)) {
+      if (sceneFound) {
+        throw new ParseError("Duplicate scene declaration", lineNum);
+      }
+      sceneFound = true;
+      for (const [, key, val] of raw.matchAll(/(\w+)=([\S]+)/g)) {
+        switch (key) {
+          case "width":
+            ast.meta.width = Number(val);
+            break;
+          case "height":
+            ast.meta.height = Number(val);
+            break;
+          case "fps":
+            ast.meta.fps = Number(val);
+            break;
+          case "bg":
+            ast.meta.bg = val;
+            break;
+          case "duration":
+            ast.meta.duration = Number(val);
+            break;
+          default:
+            throw new ParseError(`Unknown scene property: ${key}`, lineNum);
+        }
+      }
+      continue;
+    }
+    if (raw.startsWith("asset")) {
+      const m = ASSET_RE.exec(raw);
+      if (!m) {
+        throw new ParseError(`Invalid asset declaration: ${raw}`, lineNum);
+      }
+      const [, name, type, value] = m;
+      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));
+      } else {
+        throw new ParseError(`Unknown actor type or template: "${typeName}"`, lineNum);
+      }
+      const modifiers = parseModifiers(modifiersRaw);
+      ast.actors[name] = {
+        type: resolvedType,
+        args: resolvedArgs,
+        x: Number(xStr),
+        y: Number(yStr),
+        ...modifiers
+      };
+      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);
+          ast.events.push({
+            time: absTime,
+            actor,
+            action: sev.action,
+            params: params2,
+            line: lineNum
+          });
+        }
+        continue;
+      }
+      const params = parseActionParams(action, paramsRaw);
+      ast.events.push({ time, actor, action, params, line: lineNum });
+      continue;
+    }
+    throw new ParseError(`Unrecognized statement: ${raw}`, lineNum);
+  }
+  if (inDef) {
+    throw new ParseError(`Unclosed def block "${inDef.name}"`, inDef.startLine);
+  }
+  if (defNeedsClose) {
+    throw new ParseError("Unclosed def block (missing '}')", lines.length);
+  }
+  if (inSeq) {
+    throw new ParseError(`Unclosed seq block "${inSeq.name}"`, inSeq.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;
+  }
+  return ast;
+}
+export {
+  ParseError,
+  parse
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@markdy/core",
+  "version": "0.1.0",
+  "description": "MarkdyScript parser and AST types — zero runtime dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "markdy",
+    "markdyscript",
+    "animation",
+    "dsl",
+    "parser",
+    "ast"
+  ],
+  "author": "Hoang Yell <hoangyell@gmail.com> (https://hoangyell.com)",
+  "homepage": "https://markdy.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HoangYell/markdy-com.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/HoangYell/markdy-com/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
+}