@markdy/core 0.7.29 → 0.8.0

package/README.md

@@ -33,20 +33,23 @@ pnpm add @markdy/core
 
 ```typescript
 import { parse, ParseError } from "@markdy/core";
-import type { SceneAST } from "@markdy/core";
+import type { DiagramAST } 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)
+  scene "Request" theme=midnight
+  browser Web
+  service API
+  beat main:
+    show $nodes
+    Web -> API "GET /users"
 `;
 
 try {
-  const ast: SceneAST = parse(source);
+  const ast: DiagramAST = 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", ... }]
+  console.log(ast.meta);   // { width: 1280, height: 720, fps: 60, theme: "midnight", direction: "LR", title: "Request" }
+  console.log(ast.nodes);  // { Web: { kind: "browser", ... }, API: { kind: "service", ... } }
+  console.log(ast.beats);  // [{ name: "main", cues: [...] }]
 } catch (e) {
   if (e instanceof ParseError) {
     console.error(`Line ${e.line}: ${e.message}`);
@@ -58,15 +61,17 @@ try {
 
 | Export | Type | Description |
 |---|---|---|
-| `parse` | `(source: string) => SceneAST` | Parse MarkdyScript source into an AST |
+| `parse` | `(source, opts?) => DiagramAST` | Parse MarkdyScript source into a diagram AST |
+| `compile` | `(ast) => RenderPlan` | Lay out nodes, route edges, and schedule cues |
+| `parseAndCompile` | `(source) => { ast, plan }` | Parse and compile in one call |
 | `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 |
+| `DiagramAST` | type | Parsed scene: meta, nodes, edges, groups, patterns, beats |
+| `RenderPlan` | type | Positioned nodes, routed edges, timed cues, beat ranges |
+| `SceneMeta` | type | Scene configuration (width, height, fps, theme, direction) |
+| `NodeDecl` | type | Node declaration (kind, id, label, style) |
+| `EdgeDecl` | type | Edge declaration (kind, from, to, label) |
+| `BeatDecl` | type | Named beat with cues |
+| `THEMES` / `resolveTheme` | tokens | Semantic theme palettes (`midnight`, `paper`) |
 
 ## Documentation
 

package/dist/index.d.ts

@@ -1,219 +1,221 @@
 /**
- * AST types for MarkdyScript — the complete output of the parser.
+ * Diagram-native AST and RenderPlan types for MarkdyScript 0.8+.
  * Zero runtime dependencies.
  */
-type AssetDef = {
-    type: "image" | "icon";
-    value: string;
-};
-type ActorDef = {
-    type: ActorType;
-    /** Constructor arguments: asset name for sprite, display text for text/caption 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;
-    /** 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 BuiltinActorType = "sprite" | "text" | "box" | "figure" | "caption";
-type ActorType = BuiltinActorType | (string & {});
-type TimelineEvent = {
-    time: number;
-    actor: string;
-    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 LayoutDirection = "LR" | "RL" | "TB" | "BT";
+type EdgeKind = "request" | "response" | "event" | "dependency";
 type SceneMeta = {
+    title?: string;
     width: number;
     height: number;
     fps: number;
-    bg: string;
-    /** Auto-computed from the last event + its dur param when not explicitly set. */
+    theme: string;
+    direction: LayoutDirection;
     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[];
+type NodeDecl = {
+    kind: string;
+    id: string;
+    label: string;
+    style?: string;
+    props: Record<string, unknown>;
+    line: number;
 };
-/**
- * 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 EdgeDecl = {
+    id: string;
+    kind: EdgeKind;
+    from: string;
+    to: string;
+    label?: string;
+    props: Record<string, unknown>;
+    line: number;
 };
-/**
- * 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 = {
+type GroupDecl = {
+    id: string;
+    label?: string;
+    members: string[];
+    props: Record<string, unknown>;
+    line: number;
+};
+type StyleDecl = {
     name: string;
-    startTime: number;
-    endTime: number;
-    startLine: number;
+    props: Record<string, unknown>;
+    line: 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" | "actor-count-threshold" | "label-overflow";
-    message: string;
+type FlowSegment = {
+    from: string;
+    op: EdgeKind;
+    to: string;
+    label?: string;
+};
+type Cue = {
+    kind: "flow";
+    segments: FlowSegment[];
+    dur?: number;
+    line: number;
+} | {
+    kind: "show";
+    targets: string[];
+    stagger?: number;
+    dur?: number;
+    line: number;
+} | {
+    kind: "hide";
+    targets: string[];
+    dur?: number;
+    line: number;
+} | {
+    kind: "glow";
+    targets: string[];
+    color?: string;
+    strength?: number;
+    dur?: number;
+    line: number;
+} | {
+    kind: "focus";
+    targets: string[];
+    zoom?: number;
+    dur?: number;
+    line: number;
+} | {
+    kind: "use";
+    pattern: string;
+    args: Record<string, string>;
+    line: number;
+} | {
+    kind: "parallel";
+    cues: Cue[];
     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;
+type BeatDecl = {
+    name: string;
+    label?: string;
+    cues: Cue[];
+    dur?: number;
     line: number;
 };
-type SceneAST = {
+type PatternDecl = {
+    name: string;
+    params: string[];
+    body: Cue[];
+    line: number;
+};
+type Diagnostic = {
+    severity: "error" | "warning";
+    message: string;
+    line: number;
+    column?: number;
+};
+type DiagramAST = {
     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>;
-    /**
-     * 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.
-     */
+    styles: Record<string, StyleDecl>;
+    nodes: Record<string, NodeDecl>;
+    edges: EdgeDecl[];
+    groups: Record<string, GroupDecl>;
+    patterns: Record<string, PatternDecl>;
+    beats: BeatDecl[];
+    diagnostics: Diagnostic[];
+};
+type ThemeTokens = {
+    name: string;
+    canvas: string;
+    surface: string;
+    surfaceRaised: string;
+    border: string;
+    text: string;
+    textMuted: string;
+    gridMinor: string;
+    gridMajor: string;
+    vignette: string;
+    accent: string;
+    roles: Record<string, string>;
+    edges: Record<EdgeKind, string>;
+};
+type PositionedNode = {
+    id: string;
+    kind: string;
+    role: string;
+    label: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    style?: Record<string, unknown>;
+    opacity: number;
+};
+type RoutedEdge = {
+    id: string;
+    kind: EdgeKind;
+    from: string;
+    to: string;
+    label?: string;
+};
+type TimedCue = {
+    start: number;
+    duration: number;
+    kind: "show" | "hide" | "flow" | "glow" | "focus";
+    targets: string[];
+    edgeId?: string;
+    segments?: FlowSegment[];
+    params: Record<string, unknown>;
+    beat: string;
+};
+type BeatRange = {
+    name: string;
+    label?: string;
+    start: number;
+    end: number;
+};
+type RenderPlan = {
+    meta: SceneMeta;
+    theme: ThemeTokens;
+    title: string;
+    nodes: PositionedNode[];
+    edges: RoutedEdge[];
+    cues: TimedCue[];
+    beats: BeatRange[];
     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. */
-    warnings: ParseWarning[];
-    /** `import` declarations in author order. Always present; empty when none were used. */
-    imports: ImportDecl[];
+    duration: number;
 };
 
-declare class ParseError extends Error {
-    readonly line: number;
-    constructor(message: string, line: number);
-}
-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>;
-    /**
-     * Emit a non-fatal warning when actor count exceeds this threshold.
-     * Set to <= 0 to disable.
-     */
-    actorCountWarningThreshold?: number;
-    /**
-     * Emit a non-fatal warning when actor labels exceed this length.
-     * Applies to the first constructor arg when it is a string.
-     * Set to <= 0 to disable.
-     */
-    labelLengthWarningThreshold?: number;
-    /**
-     * 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;
+declare function compilePlan(ast: DiagramAST, theme: ThemeTokens): RenderPlan;
 
 /**
- * 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.
+ * Diagram-native MarkdyScript parser and compiler.
  */
-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[];
-    actions?: Record<string, readonly string[]>;
+declare class ParseError extends Error {
+    readonly line: number;
+    readonly column?: number;
+    constructor(message: string, line: number, column?: number);
+}
+type ParseResult = {
+    ast: DiagramAST;
+    plan: RenderPlan;
+};
+type ParseOptions = {
+    /** When true, only parse without compiling layout/schedule. */
+    parseOnly?: boolean;
 };
-declare function registerActorPack(pack: ActorPack): void;
+declare function parse(source: string, opts?: ParseOptions): DiagramAST;
+declare function compile(ast: DiagramAST): RenderPlan;
+declare function parseAndCompile(source: string): ParseResult;
+
+declare const THEMES: Record<string, ThemeTokens>;
+declare function resolveTheme(name: string): ThemeTokens;
+
+declare const NODE_KINDS: Set<string>;
+declare const EDGE_OPERATORS: Record<string, "request" | "response" | "event" | "dependency">;
+declare const BEAT_CUE_KEYWORDS: Set<string>;
+declare const SCENE_KEYS: Set<string>;
+declare function nodeRole(kind: string): string;
+declare function humanizeId(id: string): string;
+/** Node kind aliases for concise authoring. */
+declare const NODE_ALIASES: Record<string, string>;
+declare function canonicalNodeKind(kind: string): string;
 
 declare const TECHNICAL_NODE_TYPES: readonly ["service", "api", "microservice", "backend", "server", "worker", "job", "scheduler", "cron", "batch", "function", "lambda", "edge", "controller", "handler", "repository", "module", "package", "library", "sdk", "cli", "runtime", "process", "client", "user", "browser", "web", "mobile", "desktop", "frontend", "app", "page", "view", "component", "store", "db", "database", "sql", "nosql", "table", "index", "warehouse", "lake", "object_store", "bucket", "blob", "volume", "disk", "search", "cache", "queue", "topic", "stream", "event", "event_bus", "bus", "broker", "pubsub", "kafka", "producer", "consumer", "dead_letter", "dlq", "webhook", "cloud", "region", "vpc", "subnet", "network", "internet", "dns", "cdn", "proxy", "gateway", "api_gateway", "load_balancer", "reverse_proxy", "router", "switch", "nat", "firewall", "waf", "vpn", "bastion", "container", "cluster", "pod", "node", "deployment", "replicaset", "statefulset", "daemonset", "namespace", "ingress", "service_mesh", "sidecar", "image", "registry", "docker", "compose", "helm", "chart", "configmap", "pvc", "auth", "identity", "oauth", "oidc", "jwt", "session", "policy", "role", "permission", "vault", "secret", "key", "certificate", "repo", "branch", "commit", "pipeline", "workflow", "runner", "build", "test", "artifact", "deploy", "release", "environment", "preview", "monitor", "metrics", "logs", "trace", "alert", "dashboard", "probe", "slo", "start", "end", "state", "decision", "condition", "step", "loop", "sequence", "participant", "replica", "shard", "leader", "follower", "quorum", "consensus", "lock", "class", "interface", "method", "object", "enum", "type"];
 declare const VISUAL_PRIMITIVE_TYPES: readonly ["panel", "surface", "terminal", "metric", "stat", "grid", "matrix", "lane", "track", "marker", "dot", "token_strip", "chips", "glyph_card", "glyph"];
 declare const TECHNICAL_NODE_KINDS: Record<(typeof TECHNICAL_NODE_TYPES)[number], string>;
 
-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, TECHNICAL_NODE_KINDS, TECHNICAL_NODE_TYPES, type TemplateDef, type TimelineEvent, UNIVERSAL_ACTION_NAMES, VISUAL_PRIMITIVE_TYPES, parse, registerActorPack };
+export { BEAT_CUE_KEYWORDS, type BeatDecl, type BeatRange, type Cue, type Diagnostic, type DiagramAST, EDGE_OPERATORS, type EdgeDecl, type EdgeKind, type FlowSegment, type GroupDecl, type LayoutDirection, NODE_ALIASES, NODE_KINDS, type NodeDecl, ParseError, type ParseOptions, type ParseResult, type PatternDecl, type PositionedNode, type RenderPlan, type RoutedEdge, SCENE_KEYS, type SceneMeta, type StyleDecl, TECHNICAL_NODE_KINDS, TECHNICAL_NODE_TYPES, THEMES, type ThemeTokens, type TimedCue, VISUAL_PRIMITIVE_TYPES, canonicalNodeKind, compile, compilePlan, humanizeId, nodeRole, parse, parseAndCompile, resolveTheme };