@markdy/cli 0.7.15

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,30 @@
+# @markdy/cli
+
+First-party command-line tooling for MarkdyScript.
+
+## Install
+
+```bash
+npm i -D @markdy/cli
+```
+
+## Commands
+
+```bash
+markdy                 # launch a local browser playground on http://127.0.0.1:4242
+markdy lint scene.markdy
+markdy fmt scene.markdy
+markdy fmt scene.markdy --write
+markdy render scene.markdy --out dist/scene.html
+markdy explain scene.markdy
+markdy new explainer demo.markdy
+markdy docs
+markdy ai
+markdy check-all .
+```
+
+## Notes
+
+- The CLI resolves `import "file.markdy" as ns` from disk before parsing.
+- `fmt` prints a canonicalized scene and may expand higher-level sugar into its parsed form.
+- `render --out` writes a self-contained HTML preview you can open in a browser.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { SceneAST } from '@markdy/core';
+import { Server } from 'node:http';
+
+interface CliIo {
+    stdout(message: string): void;
+    stderr(message: string): void;
+}
+interface CliRuntime {
+    openBrowser(url: string): Promise<void>;
+}
+interface RunResult {
+    exitCode: number;
+    server?: Server;
+}
+type LoadedScene = {
+    filePath: string;
+    source: string;
+    ast: SceneAST;
+    imports: Record<string, SceneAST>;
+};
+declare function runCli(argv: string[], io?: CliIo, runtime?: CliRuntime): Promise<RunResult>;
+declare function buildStandaloneHtml(scene: LoadedScene): Promise<string>;
+
+export { type CliIo, type CliRuntime, type RunResult, buildStandaloneHtml, runCli };

package/dist/index.js

@@ -0,0 +1,940 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { PRESETS, PRESET_NAMES, parse } from "@markdy/core";
+import { createRequire } from "module";
+import { basename, dirname, extname, join, resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { createServer } from "http";
+import { readdir, readFile, stat, writeFile } from "fs/promises";
+import { spawn } from "child_process";
+
+// src/format.ts
+var BARE_TOKEN_RE = /^[\p{L}\p{N}_.$#/+:-]+$/u;
+var MODIFIER_KEYS = ["scale", "rotate", "opacity", "size", "z"];
+function formatScene(ast) {
+  const sections = [];
+  sections.push(formatSceneHeader(ast));
+  const vars = Object.entries(ast.vars);
+  if (vars.length > 0) {
+    sections.push(vars.map(([name, value]) => `var ${name} = ${value}`).join("\n"));
+  }
+  if (ast.imports.length > 0) {
+    sections.push(ast.imports.map(formatImportDecl).join("\n"));
+  }
+  const assets = Object.entries(ast.assets);
+  if (assets.length > 0) {
+    sections.push(
+      assets.map(([name, def]) => `asset ${name} = ${def.type}(${formatToken(def.value)})`).join("\n")
+    );
+  }
+  const actors = Object.entries(ast.actors);
+  if (actors.length > 0) {
+    sections.push(actors.map(([name, actor]) => formatActorDecl(name, actor)).join("\n"));
+  }
+  const defs = Object.entries(ast.defs);
+  if (defs.length > 0) {
+    sections.push(defs.map(([name, def]) => formatTemplateDef(name, def)).join("\n\n"));
+  }
+  const seqs = Object.entries(ast.seqs);
+  if (seqs.length > 0) {
+    sections.push(seqs.map(([name, seq]) => formatSequenceDef(name, seq)).join("\n\n"));
+  }
+  const timeline = formatTimeline(ast);
+  if (timeline) {
+    sections.push(timeline);
+  }
+  return `${sections.filter(Boolean).join("\n\n")}
+`;
+}
+function formatSceneHeader(ast) {
+  const parts = [
+    `scene width=${formatNumber(ast.meta.width)}`,
+    `height=${formatNumber(ast.meta.height)}`,
+    `fps=${formatNumber(ast.meta.fps)}`,
+    `bg=${ast.meta.bg}`
+  ];
+  if (ast.meta.duration !== void 0) {
+    parts.push(`duration=${formatNumber(ast.meta.duration)}`);
+  }
+  return parts.join(" ");
+}
+function formatImportDecl(decl) {
+  return `import ${JSON.stringify(decl.path)} as ${decl.namespace}`;
+}
+function formatActorDecl(name, actor) {
+  const ctor = `${actor.type}(${actor.args.map(formatToken).join(", ")})`;
+  const position = actor.anchor ? `at ${actor.anchor}` : `at (${formatNumber(actor.x)}, ${formatNumber(actor.y)})`;
+  const modifiers = MODIFIER_KEYS.flatMap((key) => {
+    const value = actor[key];
+    return value === void 0 ? [] : [`${key}=${formatNumber(value)}`];
+  }).join(", ");
+  return modifiers.length > 0 ? `actor ${name} = ${ctor} ${position} with ${modifiers}` : `actor ${name} = ${ctor} ${position}`;
+}
+function formatTemplateDef(name, def) {
+  const args = def.bodyArgs.map(formatTemplateArg).join(", ");
+  return `def ${name}(${def.params.join(", ")}) {
+  ${def.actorType}(${args})
+}`;
+}
+function formatTemplateArg(arg) {
+  return arg.startsWith("${") && arg.endsWith("}") ? arg : formatToken(arg);
+}
+function formatSequenceDef(name, seq) {
+  const lines = seq.events.map((event) => {
+    const params = event.paramsRaw.trim();
+    const suffix = params ? `(${params})` : "()";
+    return `  @+${formatNumber(event.offset)}: $.${event.action}${suffix}`;
+  });
+  return `seq ${name}(${seq.params.join(", ")}) {
+${lines.join("\n")}
+}`;
+}
+function formatTimeline(ast) {
+  if (ast.events.length === 0 && ast.chapters.length === 0) {
+    return "";
+  }
+  const blocks = [];
+  const topLevelEvents = ast.events.filter((event) => event.chapter === void 0);
+  for (const event of topLevelEvents) {
+    blocks.push({ line: event.line, text: formatEvent(event) });
+  }
+  const chaptersByLine = [...ast.chapters].sort((a, b) => a.startLine - b.startLine);
+  for (let index = 0; index < chaptersByLine.length; index++) {
+    const chapter = chaptersByLine[index];
+    const nextStartLine = chaptersByLine[index + 1]?.startLine ?? Number.POSITIVE_INFINITY;
+    const events = ast.events.filter(
+      (event) => event.chapter === chapter.name && event.line > chapter.startLine && event.line < nextStartLine
+    ).sort((a, b) => a.line - b.line);
+    blocks.push({ line: chapter.startLine, text: formatChapter(chapter, events) });
+  }
+  return blocks.sort((a, b) => a.line - b.line).map((block) => block.text).join("\n\n");
+}
+function formatChapter(chapter, events) {
+  const body = events.length > 0 ? `
+${events.map((event) => `  ${formatEvent(event)}`).join("\n")}
+` : "\n";
+  return `scene ${JSON.stringify(chapter.name)} {${body}}`;
+}
+function formatEvent(event) {
+  const params = Object.entries(event.params).map(([key, value]) => `${key}=${formatParamValue(value)}`).join(", ");
+  return `@${formatNumber(event.time)}: ${event.actor}.${event.action}(${params})`;
+}
+function formatParamValue(value) {
+  if (Array.isArray(value)) {
+    return `(${value.map(formatTupleValue).join(", ")})`;
+  }
+  if (typeof value === "number") {
+    return formatNumber(value);
+  }
+  if (typeof value === "string") {
+    return formatToken(value);
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return JSON.stringify(value);
+}
+function formatTupleValue(value) {
+  if (typeof value === "number") return formatNumber(value);
+  if (typeof value === "string") return formatToken(value);
+  return JSON.stringify(value);
+}
+function formatToken(value) {
+  return BARE_TOKEN_RE.test(value) ? value : JSON.stringify(value);
+}
+function formatNumber(value) {
+  return Number.isInteger(value) ? String(value) : String(round3(value));
+}
+function round3(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
+
+// src/index.ts
+var DEFAULT_PORT = 4242;
+var IMPORT_RE = /^import\s+"([^"]+)"\s+as\s+(\w+)\s*$/;
+var MARKDY_EXT = ".markdy";
+var PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+async function runCli(argv, io = defaultIo(), runtime = defaultRuntime()) {
+  const parsed = parseArgv(argv);
+  if (!parsed.command && hasFlag(parsed, "help")) {
+    io.stdout(helpText());
+    return { exitCode: 0 };
+  }
+  if (!parsed.command) {
+    return launchPlayground(parsed, io, runtime);
+  }
+  const command = parsed.command;
+  if (command === "--help" || command === "-h") {
+    io.stdout(helpText());
+    return { exitCode: 0 };
+  }
+  switch (command) {
+    case "lint":
+      return lintCommand(parsed, io);
+    case "fmt":
+      return fmtCommand(parsed, io);
+    case "render":
+      return renderCommand(parsed, io, runtime);
+    case "explain":
+      return explainCommand(parsed, io);
+    case "new":
+      return newCommand(parsed, io);
+    case "docs":
+      return docsCommand(parsed, io, runtime);
+    case "ai":
+      return aiCommand(parsed, io, runtime);
+    case "check-all":
+      return checkAllCommand(parsed, io);
+    default:
+      io.stderr(`Unknown command: ${command}
+
+${helpText()}`);
+      return { exitCode: 1 };
+  }
+}
+async function lintCommand(parsed, io) {
+  const files = await collectSceneFiles(parsed.positionals);
+  if (files.length === 0) {
+    io.stderr("markdy lint: expected at least one .markdy file or directory");
+    return { exitCode: 1 };
+  }
+  const strict = hasFlag(parsed, "strict");
+  const cache = /* @__PURE__ */ new Map();
+  let warningCount = 0;
+  let errorCount = 0;
+  for (const file of files) {
+    try {
+      const scene = await loadSceneFromFile(file, cache);
+      io.stdout(`OK   ${file}`);
+      warningCount += printWarnings(scene.ast.warnings, file, io);
+    } catch (error) {
+      errorCount++;
+      io.stderr(`FAIL ${file}`);
+      io.stderr(`     ${describeError(error)}`);
+    }
+  }
+  if (strict && warningCount > 0) {
+    io.stderr(`markdy lint: ${warningCount} warning(s) treated as failures.`);
+    return { exitCode: 1 };
+  }
+  if (errorCount > 0) {
+    io.stderr(`markdy lint: ${errorCount} file(s) failed.`);
+    return { exitCode: 1 };
+  }
+  io.stdout(`markdy lint: PASS \u2014 ${files.length} file(s), ${warningCount} warning(s).`);
+  return { exitCode: 0 };
+}
+async function fmtCommand(parsed, io) {
+  const files = await collectSceneFiles(parsed.positionals);
+  if (files.length === 0) {
+    io.stderr("markdy fmt: expected at least one .markdy file or directory");
+    return { exitCode: 1 };
+  }
+  const write = hasFlag(parsed, "write");
+  const check = hasFlag(parsed, "check");
+  const cache = /* @__PURE__ */ new Map();
+  let changed = 0;
+  if (!write && !check && files.length > 1) {
+    io.stderr("markdy fmt: pass exactly one file when printing to stdout, or use --write / --check");
+    return { exitCode: 1 };
+  }
+  for (const file of files) {
+    const scene = await loadSceneFromFile(file, cache);
+    const formatted = formatScene(scene.ast);
+    const isChanged = normalizeNewlines(scene.source) !== normalizeNewlines(formatted);
+    if (write) {
+      if (isChanged) {
+        await writeFile(file, formatted, "utf8");
+        changed++;
+        io.stdout(`WROTE ${file}`);
+      } else {
+        io.stdout(`OK    ${file}`);
+      }
+      continue;
+    }
+    if (check) {
+      if (isChanged) {
+        changed++;
+        io.stderr(`DIFF  ${file}`);
+      } else {
+        io.stdout(`OK    ${file}`);
+      }
+      continue;
+    }
+    io.stdout(formatted);
+  }
+  if (check) {
+    if (changed > 0) {
+      io.stderr(`markdy fmt: ${changed} file(s) need formatting.`);
+      return { exitCode: 1 };
+    }
+    io.stdout(`markdy fmt: PASS \u2014 ${files.length} file(s) already formatted.`);
+  }
+  return { exitCode: 0 };
+}
+async function renderCommand(parsed, io, runtime) {
+  const file = parsed.positionals[0];
+  if (!file) {
+    io.stderr("markdy render: expected a .markdy input file");
+    return { exitCode: 1 };
+  }
+  const scene = await loadSceneFromFile(file);
+  const outPath = getStringFlag(parsed, "out");
+  if (outPath) {
+    const html = await buildStandaloneHtml(scene);
+    const resolvedOut = resolve(outPath);
+    await writeFile(resolvedOut, html, "utf8");
+    io.stdout(`Wrote ${resolvedOut}`);
+    return { exitCode: 0 };
+  }
+  return launchPlayground(parsed, io, runtime, scene);
+}
+async function explainCommand(parsed, io) {
+  const file = parsed.positionals[0];
+  if (!file) {
+    io.stderr("markdy explain: expected a .markdy input file");
+    return { exitCode: 1 };
+  }
+  const scene = await loadSceneFromFile(file);
+  if (hasFlag(parsed, "json")) {
+    io.stdout(stableStringify(scene.ast));
+    return { exitCode: 0 };
+  }
+  const summary = [
+    `File: ${scene.filePath}`,
+    `Viewport: ${scene.ast.meta.width}\xD7${scene.ast.meta.height} @ ${scene.ast.meta.fps}fps`,
+    `Background: ${scene.ast.meta.bg}`,
+    `Duration: ${scene.ast.meta.duration ?? 0}s`,
+    `Actors: ${Object.keys(scene.ast.actors).length}`,
+    `Events: ${scene.ast.events.length}`,
+    `Chapters: ${scene.ast.chapters.length > 0 ? scene.ast.chapters.map((chapter) => chapter.name).join(", ") : "(none)"}`,
+    `Imports: ${scene.ast.imports.length > 0 ? scene.ast.imports.map((item) => `${item.namespace} -> ${item.path}`).join(", ") : "(none)"}`,
+    `Warnings: ${scene.ast.warnings.length}`
+  ];
+  io.stdout(summary.join("\n"));
+  if (scene.ast.warnings.length > 0) {
+    printWarnings(scene.ast.warnings, scene.filePath, io);
+  }
+  return { exitCode: 0 };
+}
+async function newCommand(parsed, io) {
+  const presetOrTarget = parsed.positionals[0];
+  const second = parsed.positionals[1];
+  const force = hasFlag(parsed, "force");
+  let presetName = "basic";
+  let target = "scene.markdy";
+  if (presetOrTarget) {
+    if (PRESET_NAMES.includes(presetOrTarget)) {
+      presetName = presetOrTarget;
+      target = second ?? target;
+    } else {
+      target = presetOrTarget;
+    }
+  }
+  const resolvedTarget = resolve(target);
+  const content = presetName === "basic" ? defaultSceneTemplate() : `preset ${presetName}
+`;
+  if (!force && await exists(resolvedTarget)) {
+    io.stderr(`markdy new: target already exists: ${resolvedTarget} (pass --force to overwrite)`);
+    return { exitCode: 1 };
+  }
+  await writeFile(resolvedTarget, content, "utf8");
+  io.stdout(`Created ${resolvedTarget}`);
+  return { exitCode: 0 };
+}
+async function docsCommand(parsed, io, runtime) {
+  const docsUrl = "https://markdy.com";
+  const links = [
+    "Markdy docs",
+    "  Website: https://markdy.com",
+    "  Syntax:  https://github.com/HoangYell/markdy-com/blob/main/docs/SYNTAX.md",
+    "  Agent:   https://github.com/HoangYell/markdy-com/blob/main/docs/AGENT.md",
+    "  Tutorial:https://github.com/HoangYell/markdy-com/blob/main/docs/TUTORIAL.md"
+  ];
+  io.stdout(links.join("\n"));
+  if (hasFlag(parsed, "open")) {
+    await runtime.openBrowser(docsUrl);
+  }
+  return { exitCode: 0 };
+}
+async function aiCommand(parsed, io, runtime) {
+  const agentUrl = "https://github.com/HoangYell/markdy-com/blob/main/docs/AGENT.md";
+  io.stdout(
+    [
+      "Share this with your AI agent:",
+      agentUrl,
+      "",
+      "Starter prompt:",
+      "Write a Markdy scene for a short explainer video. Use the AGENT.md grammar exactly and keep the result self-contained."
+    ].join("\n")
+  );
+  if (hasFlag(parsed, "open")) {
+    await runtime.openBrowser(agentUrl);
+  }
+  return { exitCode: 0 };
+}
+async function checkAllCommand(parsed, io) {
+  const root = resolve(parsed.positionals[0] ?? process.cwd());
+  const files = await collectSceneFiles([root]);
+  if (files.length === 0) {
+    io.stderr(`markdy check-all: no .markdy files found under ${root}`);
+    return { exitCode: 1 };
+  }
+  const result = await lintCommand(
+    {
+      command: "lint",
+      positionals: files,
+      flags: parsed.flags
+    },
+    io
+  );
+  if (result.exitCode === 0) {
+    io.stdout(`markdy check-all: PASS \u2014 scanned ${files.length} file(s).`);
+  }
+  return result;
+}
+async function launchPlayground(parsed, io, runtime, scene) {
+  const portFlag = getStringFlag(parsed, "port");
+  const preferredPort = portFlag ? Number(portFlag) : DEFAULT_PORT;
+  const code = scene?.source ?? PRESETS.explainer([]);
+  const imports = scene?.imports ?? {};
+  const sourcePath = scene?.filePath;
+  const server = await startPreviewServer(code, imports, sourcePath, preferredPort);
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : preferredPort;
+  const url = `http://127.0.0.1:${port}`;
+  io.stdout(`Markdy playground ready at ${url}`);
+  if (!hasFlag(parsed, "no-open")) {
+    await runtime.openBrowser(url);
+  }
+  return { exitCode: 0, server };
+}
+async function startPreviewServer(code, imports, sourcePath, preferredPort) {
+  const coreDist = resolvePackageDist("@markdy/core");
+  const rendererDist = resolvePackageDist("@markdy/renderer-dom");
+  const html = buildPlaygroundHtml(code, imports, sourcePath);
+  const server = createServer(async (request, response) => {
+    try {
+      const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+      if (requestUrl.pathname === "/") {
+        sendText(response, 200, html, "text/html; charset=utf-8");
+        return;
+      }
+      if (requestUrl.pathname.startsWith("/pkg/core/")) {
+        await servePackageFile(response, coreDist, requestUrl.pathname.slice("/pkg/core/".length));
+        return;
+      }
+      if (requestUrl.pathname.startsWith("/pkg/renderer-dom/")) {
+        await servePackageFile(response, rendererDist, requestUrl.pathname.slice("/pkg/renderer-dom/".length));
+        return;
+      }
+      sendText(response, 404, "Not found", "text/plain; charset=utf-8");
+    } catch (error) {
+      sendText(response, 500, describeError(error), "text/plain; charset=utf-8");
+    }
+  });
+  await new Promise((resolvePromise, rejectPromise) => {
+    server.once("error", rejectPromise);
+    server.listen(preferredPort, "127.0.0.1", () => {
+      server.off("error", rejectPromise);
+      resolvePromise();
+    });
+  }).catch(async () => {
+    await new Promise((resolvePromise, rejectPromise) => {
+      server.once("error", rejectPromise);
+      server.listen(0, "127.0.0.1", () => {
+        server.off("error", rejectPromise);
+        resolvePromise();
+      });
+    });
+  });
+  return server;
+}
+async function servePackageFile(response, distDir, relativePath) {
+  const safePath = relativePath.replace(/^\/+/, "");
+  const fullPath = resolve(distDir, safePath);
+  if (!fullPath.startsWith(distDir)) {
+    sendText(response, 403, "Forbidden", "text/plain; charset=utf-8");
+    return;
+  }
+  const body = await readFile(fullPath);
+  sendBuffer(response, 200, body, contentType(fullPath));
+}
+async function loadSceneFromFile(filePath, cache = /* @__PURE__ */ new Map(), stack = []) {
+  const resolvedPath = resolve(filePath);
+  const cached = cache.get(resolvedPath);
+  if (cached) return cached;
+  if (stack.includes(resolvedPath)) {
+    const chain = [...stack, resolvedPath].map((entry) => basename(entry)).join(" -> ");
+    throw new Error(`Import cycle detected: ${chain}`);
+  }
+  const source = await readFile(resolvedPath, "utf8").catch((error) => {
+    throw new Error(`Unable to read ${resolvedPath}: ${describeError(error)}`);
+  });
+  const imports = await resolveSceneImports(source, resolvedPath, cache, [...stack, resolvedPath]);
+  const ast = parse(source, Object.keys(imports).length > 0 ? { imports } : void 0);
+  const loaded = { filePath: resolvedPath, source, ast, imports };
+  cache.set(resolvedPath, loaded);
+  return loaded;
+}
+async function resolveSceneImports(source, filePath, cache, stack) {
+  const imports = {};
+  for (const declaration of scanImports(source)) {
+    const childPath = resolve(dirname(filePath), declaration.path);
+    const child = await loadSceneFromFile(childPath, cache, stack);
+    imports[declaration.namespace] = child.ast;
+  }
+  return imports;
+}
+function scanImports(source) {
+  const imports = [];
+  for (const line of source.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("import ")) continue;
+    const match = IMPORT_RE.exec(trimmed);
+    if (!match) continue;
+    imports.push({ path: match[1], namespace: match[2] });
+  }
+  return imports;
+}
+async function collectSceneFiles(inputs) {
+  const candidates = inputs.length > 0 ? inputs : [process.cwd()];
+  const out = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    const resolved = resolve(candidate);
+    const info = await stat(resolved).catch(() => null);
+    if (!info) continue;
+    if (info.isDirectory()) {
+      for (const file of await walkMarkdyFiles(resolved)) {
+        out.add(file);
+      }
+      continue;
+    }
+    if (info.isFile() && extname(resolved) === MARKDY_EXT) {
+      out.add(resolved);
+    }
+  }
+  return [...out].sort();
+}
+async function walkMarkdyFiles(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name === ".git" || entry.name === "node_modules" || entry.name === "dist") {
+      continue;
+    }
+    const fullPath = join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkMarkdyFiles(fullPath));
+      continue;
+    }
+    if (entry.isFile() && extname(entry.name) === MARKDY_EXT) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function buildPlaygroundHtml(code, imports, sourcePath) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Markdy Playground</title>
+    <style>
+      :root { color-scheme: dark; }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        background: #0d1117;
+        color: #e6edf3;
+      }
+      header {
+        padding: 16px 20px;
+        border-bottom: 1px solid #30363d;
+        display: flex;
+        justify-content: space-between;
+        gap: 16px;
+        align-items: center;
+      }
+      main {
+        display: grid;
+        grid-template-columns: minmax(320px, 460px) 1fr;
+        min-height: calc(100vh - 66px);
+      }
+      textarea {
+        width: 100%;
+        height: 100%;
+        border: 0;
+        resize: none;
+        padding: 20px;
+        background: #010409;
+        color: #c9d1d9;
+        font: 14px/1.55 ui-monospace, SFMono-Regular, SFMono-Regular, Menlo, Consolas, monospace;
+      }
+      .editor {
+        border-right: 1px solid #30363d;
+        display: flex;
+        flex-direction: column;
+      }
+      .preview {
+        padding: 20px;
+        overflow: auto;
+      }
+      .actions {
+        display: flex;
+        gap: 8px;
+        padding: 12px 20px;
+        border-top: 1px solid #30363d;
+        background: #0d1117;
+      }
+      button {
+        border: 1px solid #30363d;
+        border-radius: 8px;
+        background: #161b22;
+        color: #e6edf3;
+        padding: 8px 12px;
+        cursor: pointer;
+      }
+      #warnings {
+        margin: 0 0 16px;
+        padding: 0;
+        list-style: none;
+      }
+      #warnings li {
+        margin-bottom: 8px;
+        padding: 10px 12px;
+        border-radius: 8px;
+        background: rgba(255, 183, 77, 0.12);
+        color: #ffd38a;
+      }
+      #viewport {
+        max-width: 960px;
+        margin: 0 auto;
+      }
+      code { color: #8b949e; }
+    </style>
+    <script type="importmap">
+      {
+        "imports": {
+          "@markdy/core": "/pkg/core/index.js",
+          "@markdy/renderer-dom": "/pkg/renderer-dom/index.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <header>
+      <div>
+        <strong>Markdy Playground</strong>
+        <div><code>${escapeHtml(sourcePath ?? "scratch scene")}</code></div>
+      </div>
+      <div>Resolved imports: ${Object.keys(imports).length}</div>
+    </header>
+    <main>
+      <section class="editor">
+        <textarea id="code">${escapeHtml(code)}</textarea>
+        <div class="actions">
+          <button id="run" type="button">Run</button>
+          <button id="pause" type="button">Pause</button>
+          <button id="play" type="button">Play</button>
+        </div>
+      </section>
+      <section class="preview">
+        <ul id="warnings"></ul>
+        <div id="viewport"></div>
+      </section>
+    </main>
+    <script type="module">
+      import { createPlayer } from "@markdy/renderer-dom";
+
+      const imports = ${JSON.stringify(imports)};
+      const textarea = document.getElementById("code");
+      const viewport = document.getElementById("viewport");
+      const warnings = document.getElementById("warnings");
+      const runButton = document.getElementById("run");
+      const pauseButton = document.getElementById("pause");
+      const playButton = document.getElementById("play");
+      let player;
+
+      function render() {
+        warnings.innerHTML = "";
+        viewport.innerHTML = "";
+        player?.destroy?.();
+        try {
+          player = createPlayer({
+            container: viewport,
+            code: textarea.value,
+            imports,
+            onWarning(warning) {
+              const item = document.createElement("li");
+              item.textContent = \`line \${warning.line}: \${warning.message} (\${warning.kind})\`;
+              warnings.appendChild(item);
+            }
+          });
+        } catch (error) {
+          const item = document.createElement("li");
+          item.textContent = error instanceof Error ? error.message : String(error);
+          warnings.appendChild(item);
+        }
+      }
+
+      runButton.addEventListener("click", render);
+      pauseButton.addEventListener("click", () => player?.pause?.());
+      playButton.addEventListener("click", () => player?.play?.());
+      render();
+    </script>
+  </body>
+</html>`;
+}
+async function buildStandaloneHtml(scene) {
+  const version = await getPackageVersion();
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(basename(scene.filePath))} \u2014 Markdy</title>
+    <style>
+      body {
+        margin: 0;
+        padding: 24px;
+        background: #0d1117;
+        color: #e6edf3;
+        font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      }
+      main {
+        max-width: 980px;
+        margin: 0 auto;
+      }
+      #app {
+        max-width: 960px;
+        margin: 0 auto;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div id="app"></div>
+    </main>
+    <script type="importmap">
+      {
+        "imports": {
+          "@markdy/core": "https://esm.sh/@markdy/core@${version}",
+          "@markdy/renderer-dom": "https://esm.sh/@markdy/renderer-dom@${version}"
+        }
+      }
+    </script>
+    <script type="module">
+      import { createPlayer } from "@markdy/renderer-dom";
+
+      createPlayer({
+        container: document.getElementById("app"),
+        code: ${JSON.stringify(scene.source)},
+        imports: ${JSON.stringify(scene.imports)},
+        onWarning(warning) {
+          console.warn(\`[markdy] line \${warning.line}: \${warning.message} (\${warning.kind})\`);
+        }
+      });
+    </script>
+  </body>
+</html>`;
+}
+function helpText() {
+  return [
+    "markdy \u2014 MarkdyScript command-line tools",
+    "",
+    "Usage:",
+    "  markdy",
+    "  markdy lint <file-or-dir> [--strict]",
+    "  markdy fmt <file-or-dir> [--write | --check]",
+    "  markdy render <file.markdy> [--out file.html] [--port 4242] [--no-open]",
+    "  markdy explain <file.markdy> [--json]",
+    "  markdy new [preset-name] [target.markdy] [--force]",
+    "  markdy docs [--open]",
+    "  markdy ai [--open]",
+    "  markdy check-all [dir] [--strict]",
+    "",
+    `Built-in presets: ${PRESET_NAMES.join(", ")}`
+  ].join("\n");
+}
+function parseArgv(argv) {
+  const flags = /* @__PURE__ */ new Map();
+  const positionals = [];
+  let command;
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (!command && !arg.startsWith("-")) {
+      command = arg;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const [rawKey, rawValue] = arg.slice(2).split("=", 2);
+      if (rawValue !== void 0) {
+        flags.set(rawKey, rawValue);
+        continue;
+      }
+      const next = argv[index + 1];
+      if (next && !next.startsWith("-") && expectsValue(rawKey)) {
+        flags.set(rawKey, next);
+        index++;
+      } else {
+        flags.set(rawKey, true);
+      }
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      const short = arg.slice(1);
+      if (short === "w") flags.set("write", true);
+      else if (short === "c") flags.set("check", true);
+      else if (short === "j") flags.set("json", true);
+      else if (short === "s") flags.set("strict", true);
+      else if (short === "f") flags.set("force", true);
+      else if (short === "o") {
+        const next = argv[index + 1];
+        if (!next || next.startsWith("-")) throw new Error("Expected a value after -o");
+        flags.set("out", next);
+        index++;
+      } else if (short === "p") {
+        const next = argv[index + 1];
+        if (!next || next.startsWith("-")) throw new Error("Expected a value after -p");
+        flags.set("port", next);
+        index++;
+      } else if (short === "h") {
+        flags.set("help", true);
+      } else {
+        flags.set(short, true);
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return { command, positionals, flags };
+}
+function expectsValue(flag) {
+  return flag === "out" || flag === "port";
+}
+function hasFlag(parsed, name) {
+  return parsed.flags.get(name) === true;
+}
+function getStringFlag(parsed, name) {
+  const value = parsed.flags.get(name);
+  return typeof value === "string" ? value : void 0;
+}
+function printWarnings(warnings, file, io) {
+  for (const warning of warnings) {
+    io.stderr(`WARN ${file}:${warning.line} ${warning.kind} ${warning.message}`);
+  }
+  return warnings.length;
+}
+function stableStringify(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const walk = (current) => {
+    if (current === null || typeof current !== "object") return current;
+    if (seen.has(current)) return "[circular]";
+    seen.add(current);
+    if (Array.isArray(current)) return current.map(walk);
+    const sorted = {};
+    for (const key of Object.keys(current).sort()) {
+      sorted[key] = walk(current[key]);
+    }
+    return sorted;
+  };
+  return `${JSON.stringify(walk(value), null, 2)}
+`;
+}
+function normalizeNewlines(value) {
+  return value.replace(/\r\n/g, "\n");
+}
+async function getPackageVersion() {
+  const pkg = JSON.parse(await readFile(join(PACKAGE_ROOT, "package.json"), "utf8"));
+  return pkg.version;
+}
+function resolvePackageDist(packageName) {
+  const require2 = createRequire(import.meta.url);
+  const packageJson = require2.resolve(`${packageName}/package.json`);
+  return join(dirname(packageJson), "dist");
+}
+function contentType(path) {
+  if (path.endsWith(".js")) return "text/javascript; charset=utf-8";
+  if (path.endsWith(".d.ts")) return "text/plain; charset=utf-8";
+  if (path.endsWith(".json")) return "application/json; charset=utf-8";
+  if (path.endsWith(".css")) return "text/css; charset=utf-8";
+  return "application/octet-stream";
+}
+function sendText(response, status, body, type) {
+  response.writeHead(status, { "content-type": type });
+  response.end(body);
+}
+function sendBuffer(response, status, body, type) {
+  response.writeHead(status, { "content-type": type });
+  response.end(body);
+}
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function describeError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function defaultSceneTemplate() {
+  return [
+    "scene width=960 height=540 fps=30 bg=#0d1117",
+    "",
+    'actor title = caption("hello, markdy") at top',
+    "actor hero = figure(#c68642, m, \u{1F60E}) at (480, 360)",
+    "",
+    "@0.0: title.fade_in(dur=0.4)",
+    "@0.4: hero.enter(from=bottom, dur=0.5)",
+    '@1.2: hero.say("ship it", dur=1.4)',
+    ""
+  ].join("\n");
+}
+function defaultIo() {
+  return {
+    stdout(message) {
+      process.stdout.write(`${message}
+`);
+    },
+    stderr(message) {
+      process.stderr.write(`${message}
+`);
+    }
+  };
+}
+function defaultRuntime() {
+  return {
+    async openBrowser(url) {
+      const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+      const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+      const child = spawn(command, args, {
+        detached: true,
+        stdio: "ignore"
+      });
+      child.unref();
+    }
+  };
+}
+var isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  runCli(process.argv.slice(2)).then(({ exitCode }) => {
+    process.exitCode = exitCode;
+  }).catch((error) => {
+    process.stderr.write(`${describeError(error)}
+`);
+    process.exitCode = 1;
+  });
+}
+export {
+  buildStandaloneHtml,
+  runCli
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@markdy/cli",
+  "version": "0.7.15",
+  "description": "First-party CLI for MarkdyScript: lint, format, explain, render, and local playground tooling.",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "markdy": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "markdy",
+    "cli",
+    "animation",
+    "dsl",
+    "text-to-motion"
+  ],
+  "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/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/HoangYell/markdy-com/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@markdy/core": "0.7.15",
+    "@markdy/renderer-dom": "0.7.15"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
+}