@flux-lang/core 0.1.2 → 0.1.4-canary.078fd1eea

package/dist/parser.js

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 /**
  * Token types for the Flux lexer.
  * We keep keywords mostly as identifiers, except for a few special literals.
@@ -506,8 +508,10 @@ class Lexer {
 class Parser {
     tokens;
     current = 0;
-    constructor(tokens) {
+    allowBodyFragments = false;
+    constructor(tokens, options = {}) {
         this.tokens = tokens;
+        this.allowBodyFragments = options.allowBodyFragments ?? false;
     }
     parseDocument() {
         // document { ... }
@@ -519,6 +523,12 @@ class Parser {
         const grids = [];
         const rules = [];
         let runtime;
+        let materials;
+        let assets;
+        let tokens;
+        let styles;
+        const themes = [];
+        let body;
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
             if (this.checkIdentifier("meta")) {
                 const blockMeta = this.parseMetaBlock();
@@ -540,6 +550,24 @@ class Parser {
             else if (this.checkIdentifier("runtime")) {
                 runtime = this.parseRuntimeBlock();
             }
+            else if (this.checkIdentifier("assets")) {
+                assets = this.parseAssetsBlock();
+            }
+            else if (this.checkIdentifier("materials")) {
+                materials = this.parseMaterialsBlock();
+            }
+            else if (this.checkIdentifier("tokens")) {
+                tokens = this.parseTokensBlock();
+            }
+            else if (this.checkIdentifier("styles")) {
+                styles = this.parseStylesBlock();
+            }
+            else if (this.checkIdentifier("theme")) {
+                themes.push(this.parseThemeBlock());
+            }
+            else if (this.checkIdentifier("body")) {
+                body = this.parseBodyBlock();
+            }
             else {
                 const tok = this.peek();
                 throw this.errorAtToken(tok, `Unexpected top-level construct '${tok.lexeme}'`);
@@ -553,6 +581,12 @@ class Parser {
             grids,
             rules,
             runtime,
+            materials,
+            assets,
+            tokens,
+            styles,
+            themes,
+            body,
         };
         return doc;
     }
@@ -562,8 +596,7 @@ class Parser {
         this.consume(TokenType.LBrace, "Expected '{' after 'meta'");
         const meta = { version: "0.1.0" };
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
-            const keyTok = this.consume(TokenType.Identifier, "Expected meta field name");
-            const key = String(keyTok.value);
+            const key = this.parseKeyPath("Expected meta field name");
             this.consume(TokenType.Equals, "Expected '=' after meta field name");
             const valueTok = this.consume(TokenType.String, "Expected string value for meta field");
             meta[key] = String(valueTok.value);
@@ -813,6 +846,818 @@ class Parser {
         this.consume(TokenType.RBrace, "Expected '}' after cell block");
         return cell;
     }
+    // --- Materials ---
+    parseMaterialsBlock() {
+        this.expectIdentifier("materials", "Expected 'materials'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'materials'");
+        const materials = [];
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("material")) {
+                materials.push(this.parseMaterialDecl());
+            }
+            else {
+                this.skipStatement();
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after materials block");
+        return { materials };
+    }
+    parseMaterialDecl() {
+        this.expectIdentifier("material", "Expected 'material'");
+        const nameTok = this.consume(TokenType.Identifier, "Expected material name");
+        const name = String(nameTok.value);
+        this.consume(TokenType.LBrace, "Expected '{' after material name");
+        const material = { name, tags: [] };
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("tags")) {
+                material.tags = this.parseIdentifierList();
+            }
+            else if (this.checkIdentifier("label")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'label'");
+                const tok = this.consume(TokenType.String, "Expected string for label");
+                material.label = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("description")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'description'");
+                const tok = this.consume(TokenType.String, "Expected string for description");
+                material.description = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("color")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'color'");
+                const tok = this.consume(TokenType.String, "Expected string for color");
+                material.color = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("score")) {
+                material.score = this.parseMaterialScoreBlock();
+            }
+            else if (this.checkIdentifier("midi")) {
+                material.midi = this.parseMaterialMidiBlock();
+            }
+            else if (this.checkIdentifier("video")) {
+                material.video = this.parseMaterialVideoBlock();
+            }
+            else {
+                this.skipStatement();
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after material block");
+        return material;
+    }
+    parseMaterialScoreBlock() {
+        this.expectIdentifier("score", "Expected 'score'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'score'");
+        const score = {};
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("text")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'text'");
+                const tok = this.consume(TokenType.String, "Expected string for text");
+                score.text = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("staff")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'staff'");
+                const tok = this.consume(TokenType.String, "Expected string for staff");
+                score.staff = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("clef")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'clef'");
+                const tok = this.consume(TokenType.String, "Expected string for clef");
+                score.clef = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else {
+                this.skipStatement();
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after score block");
+        return score;
+    }
+    parseMaterialMidiBlock() {
+        this.expectIdentifier("midi", "Expected 'midi'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'midi'");
+        const midi = {};
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("channel")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'channel'");
+                const tok = this.consumeNumber("Expected numeric channel");
+                midi.channel = Number(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("pitch")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'pitch'");
+                const tok = this.consumeNumber("Expected numeric pitch");
+                midi.pitch = Number(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("velocity")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'velocity'");
+                const tok = this.consumeNumber("Expected numeric velocity");
+                midi.velocity = Number(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("durationSeconds")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'durationSeconds'");
+                const tok = this.consumeNumber("Expected numeric durationSeconds");
+                midi.durationSeconds = Number(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else {
+                this.skipStatement();
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after midi block");
+        return midi;
+    }
+    parseMaterialVideoBlock() {
+        this.expectIdentifier("video", "Expected 'video'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'video'");
+        const video = { clip: "" };
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("clip")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'clip'");
+                const tok = this.consume(TokenType.String, "Expected string for clip");
+                video.clip = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("inSeconds")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'inSeconds'");
+                const tok = this.consumeNumber("Expected numeric inSeconds");
+                video.inSeconds = Number(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("outSeconds")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'outSeconds'");
+                const tok = this.consumeNumber("Expected numeric outSeconds");
+                video.outSeconds = Number(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("layer")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'layer'");
+                const tok = this.consume(TokenType.String, "Expected string for layer");
+                video.layer = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else {
+                this.skipStatement();
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after video block");
+        return video;
+    }
+    // --- Assets (v0.2) ---
+    parseAssetsBlock() {
+        this.expectIdentifier("assets", "Expected 'assets'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'assets'");
+        const assets = [];
+        const banks = [];
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("asset")) {
+                assets.push(this.parseAssetDecl());
+            }
+            else if (this.checkIdentifier("bank")) {
+                banks.push(this.parseAssetBankDecl());
+            }
+            else {
+                this.skipStatement();
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after assets block");
+        return { assets, banks };
+    }
+    parseAssetDecl() {
+        this.expectIdentifier("asset", "Expected 'asset'");
+        const nameTok = this.consume(TokenType.Identifier, "Expected asset name");
+        const name = String(nameTok.value);
+        this.consume(TokenType.LBrace, "Expected '{' after asset name");
+        const asset = {
+            name,
+            kind: "",
+            path: "",
+            tags: [],
+        };
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("kind")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'kind'");
+                const tok = this.peek();
+                if (tok.type === TokenType.String || tok.type === TokenType.Identifier) {
+                    this.advance();
+                    asset.kind = String(tok.value ?? tok.lexeme);
+                }
+                else {
+                    throw this.errorAtToken(tok, "Expected kind identifier or string");
+                }
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("path")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'path'");
+                const tok = this.consume(TokenType.String, "Expected string for path");
+                asset.path = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("tags")) {
+                asset.tags = this.parseIdentifierList();
+            }
+            else if (this.checkIdentifier("weight")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'weight'");
+                const tok = this.consumeNumber("Expected numeric weight");
+                asset.weight = Number(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("meta")) {
+                asset.meta = this.parseMetaMapBlock();
+            }
+            else {
+                this.skipStatement();
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after asset block");
+        return asset;
+    }
+    parseAssetBankDecl() {
+        this.expectIdentifier("bank", "Expected 'bank'");
+        const nameTok = this.consume(TokenType.Identifier, "Expected bank name");
+        const name = String(nameTok.value);
+        this.consume(TokenType.LBrace, "Expected '{' after bank name");
+        const bank = {
+            name,
+            kind: "",
+            root: "",
+            include: "",
+            tags: [],
+        };
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("kind")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'kind'");
+                const tok = this.peek();
+                if (tok.type === TokenType.String || tok.type === TokenType.Identifier) {
+                    this.advance();
+                    bank.kind = String(tok.value ?? tok.lexeme);
+                }
+                else {
+                    throw this.errorAtToken(tok, "Expected kind identifier or string");
+                }
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("root")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'root'");
+                const tok = this.consume(TokenType.String, "Expected string for root");
+                bank.root = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("include")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'include'");
+                const tok = this.consume(TokenType.String, "Expected string for include");
+                bank.include = String(tok.value);
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else if (this.checkIdentifier("tags")) {
+                bank.tags = this.parseIdentifierList();
+            }
+            else if (this.checkIdentifier("strategy")) {
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'strategy'");
+                const tok = this.peek();
+                if (tok.type !== TokenType.Identifier && tok.type !== TokenType.String) {
+                    throw this.errorAtToken(tok, "Expected strategy identifier or string");
+                }
+                this.advance();
+                const raw = String(tok.value ?? tok.lexeme);
+                if (raw !== "weighted" && raw !== "uniform") {
+                    throw this.errorAtToken(tok, `Unknown asset strategy '${raw}'`);
+                }
+                bank.strategy = raw;
+                this.consumeOptional(TokenType.Semicolon);
+            }
+            else {
+                this.skipStatement();
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after bank block");
+        return bank;
+    }
+    parseMetaMapBlock() {
+        this.expectIdentifier("meta", "Expected 'meta'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'meta'");
+        const meta = {};
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const key = this.parseKeyPath("Expected meta field name");
+            this.consume(TokenType.Equals, "Expected '=' after meta field name");
+            const value = this.parseValueLiteral();
+            meta[key] = value;
+            this.consumeOptional(TokenType.Semicolon);
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after meta block");
+        return meta;
+    }
+    // --- Body (v0.2) ---
+    parseBodyBlock() {
+        this.expectIdentifier("body", "Expected 'body'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'body'");
+        const nodes = [];
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const node = this.parseDocumentNode();
+            if (!this.allowBodyFragments && node.kind !== "page") {
+                throw this.errorAtToken(this.peek(), "Body block must contain page nodes at the top level");
+            }
+            nodes.push(node);
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after body block");
+        return { nodes };
+    }
+    parseDocumentNode() {
+        const kindTok = this.consume(TokenType.Identifier, "Expected node kind");
+        const kind = String(kindTok.value);
+        const idTok = this.consume(TokenType.Identifier, "Expected node id");
+        const id = String(idTok.value);
+        this.consume(TokenType.LBrace, "Expected '{' after node id");
+        const props = {};
+        const children = [];
+        let refresh;
+        let transition;
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("refresh")) {
+                refresh = this.parseRefreshPolicy();
+                continue;
+            }
+            if (this.checkIdentifier("transition")) {
+                transition = this.parseTransitionSpec();
+                continue;
+            }
+            if (this.looksLikeNodeDecl()) {
+                children.push(this.parseDocumentNode());
+                continue;
+            }
+            if (this.check(TokenType.Identifier)) {
+                const key = this.parseKeyPath("Expected property name");
+                this.consume(TokenType.Equals, "Expected '=' after property name");
+                if (this.match(TokenType.At)) {
+                    const expr = this.parseExpr();
+                    props[key] = { kind: "DynamicValue", expr };
+                }
+                else {
+                    const value = this.parseValueLiteral();
+                    props[key] = { kind: "LiteralValue", value };
+                }
+                this.consumeOptional(TokenType.Semicolon);
+                continue;
+            }
+            this.skipStatement();
+        }
+        const endTok = this.consume(TokenType.RBrace, "Expected '}' after node block");
+        return {
+            id,
+            kind,
+            props,
+            children,
+            refresh,
+            transition,
+            loc: { line: kindTok.line, column: kindTok.column, endLine: endTok.line, endColumn: endTok.column },
+        };
+    }
+    parseTokensBlock() {
+        this.expectIdentifier("tokens", "Expected 'tokens'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'tokens'");
+        const tokens = {};
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const key = this.parseKeyPath("Expected token name");
+            this.consume(TokenType.Equals, "Expected '=' after token name");
+            const value = this.parseValueLiteral();
+            tokens[key] = value;
+            this.consumeOptional(TokenType.Semicolon);
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after tokens block");
+        return { tokens };
+    }
+    parseStylesBlock() {
+        this.expectIdentifier("styles", "Expected 'styles'");
+        this.consume(TokenType.LBrace, "Expected '{' after 'styles'");
+        const styles = [];
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const nameTok = this.consume(TokenType.Identifier, "Expected style name");
+            const name = String(nameTok.value);
+            let extendsName;
+            if (this.match(TokenType.Colon)) {
+                const baseTok = this.consume(TokenType.Identifier, "Expected base style name");
+                extendsName = String(baseTok.value);
+            }
+            this.consume(TokenType.LBrace, "Expected '{' after style name");
+            const props = this.parsePropertyMap();
+            this.consume(TokenType.RBrace, "Expected '}' after style block");
+            styles.push({ name, extends: extendsName, props });
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after styles block");
+        return { styles };
+    }
+    parseThemeBlock() {
+        this.expectIdentifier("theme", "Expected 'theme'");
+        let name;
+        if (this.check(TokenType.String)) {
+            name = String(this.advance().value);
+        }
+        else if (this.check(TokenType.Identifier)) {
+            name = String(this.advance().value);
+        }
+        else {
+            throw this.errorAtToken(this.peek(), "Expected theme name");
+        }
+        this.consume(TokenType.LBrace, "Expected '{' after theme name");
+        let tokens;
+        let styles;
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            if (this.checkIdentifier("tokens")) {
+                tokens = this.parseTokensBlock();
+            }
+            else if (this.checkIdentifier("styles")) {
+                styles = this.parseStylesBlock();
+            }
+            else {
+                const tok = this.peek();
+                throw this.errorAtToken(tok, `Unexpected theme field '${tok.lexeme}'`);
+            }
+        }
+        this.consume(TokenType.RBrace, "Expected '}' after theme block");
+        return { name, tokens, styles };
+    }
+    parseRefreshPolicy() {
+        this.expectIdentifier("refresh", "Expected 'refresh'");
+        this.consume(TokenType.Equals, "Expected '=' after 'refresh'");
+        if (this.checkIdentifier("never")) {
+            this.advance();
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "never" };
+        }
+        if (this.checkIdentifier("docstep") || this.checkIdentifier("onDocstep")) {
+            this.advance();
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "docstep" };
+        }
+        if (this.checkIdentifier("onLoad")) {
+            this.advance();
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "never" };
+        }
+        if (this.checkIdentifier("every")) {
+            this.advance();
+            this.consume(TokenType.LParen, "Expected '(' after 'every'");
+            const intervalSec = this.parseTimeSeconds("Expected refresh interval");
+            let phaseSec = 0;
+            if (this.match(TokenType.Comma)) {
+                if (!this.checkIdentifier("phase")) {
+                    throw this.errorAtToken(this.peek(), "Expected 'phase' in every(...)");
+                }
+                this.advance();
+                this.consume(TokenType.Equals, "Expected '=' after 'phase'");
+                phaseSec = this.parseTimeSeconds("Expected phase duration", true);
+            }
+            this.consume(TokenType.RParen, "Expected ')' after every(...)");
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "every", intervalSec, phaseSec };
+        }
+        if (this.checkIdentifier("atEach")) {
+            this.advance();
+            this.consume(TokenType.LParen, "Expected '(' after 'atEach'");
+            this.consume(TokenType.LBracket, "Expected '[' to start atEach list");
+            const timesSec = [];
+            if (!this.check(TokenType.RBracket)) {
+                timesSec.push(this.parseTimeSeconds("Expected atEach time", true));
+                while (this.match(TokenType.Comma)) {
+                    timesSec.push(this.parseTimeSeconds("Expected atEach time", true));
+                }
+            }
+            this.consume(TokenType.RBracket, "Expected ']' after atEach list");
+            this.consume(TokenType.RParen, "Expected ')' after atEach(...)");
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "atEach", timesSec };
+        }
+        if (this.checkIdentifier("at")) {
+            this.advance();
+            this.consume(TokenType.LParen, "Expected '(' after 'at'");
+            const timeSec = this.parseTimeSeconds("Expected at(...) time", true);
+            this.consume(TokenType.RParen, "Expected ')' after at(...)");
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "at", timeSec };
+        }
+        if (this.checkIdentifier("poisson")) {
+            this.advance();
+            this.consume(TokenType.LParen, "Expected '(' after 'poisson'");
+            let ratePerSec = null;
+            while (!this.check(TokenType.RParen) && !this.isAtEnd()) {
+                if (this.check(TokenType.Identifier) && this.peek(1).type === TokenType.Equals) {
+                    const nameTok = this.advance();
+                    this.consume(TokenType.Equals, "Expected '=' after argument name");
+                    if (nameTok.lexeme !== "ratePerSec") {
+                        throw this.errorAtToken(nameTok, `Unknown poisson argument '${nameTok.lexeme}'`);
+                    }
+                    const valueTok = this.consumeNumber("Expected numeric ratePerSec");
+                    ratePerSec = Number(valueTok.value);
+                }
+                else {
+                    const valueTok = this.consumeNumber("Expected numeric ratePerSec");
+                    ratePerSec = Number(valueTok.value);
+                }
+                if (!this.match(TokenType.Comma))
+                    break;
+            }
+            this.consume(TokenType.RParen, "Expected ')' after poisson(...)");
+            this.consumeOptional(TokenType.Semicolon);
+            if (ratePerSec == null) {
+                throw this.errorAtToken(this.peek(), "poisson(ratePerSec=...) requires ratePerSec");
+            }
+            return { kind: "poisson", ratePerSec };
+        }
+        if (this.checkIdentifier("chance")) {
+            this.advance();
+            this.consume(TokenType.LParen, "Expected '(' after 'chance'");
+            let p = null;
+            let every = null;
+            while (!this.check(TokenType.RParen) && !this.isAtEnd()) {
+                if (this.check(TokenType.Identifier) && this.peek(1).type === TokenType.Equals) {
+                    const nameTok = this.advance();
+                    this.consume(TokenType.Equals, "Expected '=' after argument name");
+                    if (nameTok.lexeme === "p") {
+                        const valueTok = this.consumeNumber("Expected numeric p");
+                        p = Number(valueTok.value);
+                    }
+                    else if (nameTok.lexeme === "every") {
+                        every = this.parseChanceEvery();
+                    }
+                    else {
+                        throw this.errorAtToken(nameTok, `Unknown chance argument '${nameTok.lexeme}'`);
+                    }
+                }
+                else if (p == null) {
+                    const valueTok = this.consumeNumber("Expected numeric p");
+                    p = Number(valueTok.value);
+                }
+                else {
+                    throw this.errorAtToken(this.peek(), "Unexpected chance(...) argument");
+                }
+                if (!this.match(TokenType.Comma))
+                    break;
+            }
+            this.consume(TokenType.RParen, "Expected ')' after chance(...)");
+            this.consumeOptional(TokenType.Semicolon);
+            if (p == null) {
+                throw this.errorAtToken(this.peek(), "chance(p=..., every=...) requires p");
+            }
+            if (!every) {
+                every = { kind: "docstep" };
+            }
+            return { kind: "chance", p, every };
+        }
+        if (this.checkIdentifier("beat")) {
+            throw this.errorAtToken(this.peek(), "beat(...) refresh is not supported yet");
+        }
+        throw this.errorAtToken(this.peek(), "Invalid refresh policy");
+    }
+    parseTransitionSpec() {
+        this.expectIdentifier("transition", "Expected 'transition'");
+        this.consume(TokenType.Equals, "Expected '=' after 'transition'");
+        if (this.checkIdentifier("none")) {
+            this.advance();
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "none" };
+        }
+        if (this.checkIdentifier("appear")) {
+            this.advance();
+            if (this.match(TokenType.LParen)) {
+                this.consume(TokenType.RParen, "Expected ')' after appear(");
+            }
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "appear" };
+        }
+        if (this.checkIdentifier("fade")) {
+            this.advance();
+            const args = this.parseTransitionArgs(["duration", "ease"]);
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "fade", durationMs: args.durationMs, ease: args.ease };
+        }
+        if (this.checkIdentifier("wipe")) {
+            this.advance();
+            const args = this.parseTransitionArgs(["duration", "ease", "direction"]);
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "wipe", durationMs: args.durationMs, ease: args.ease, direction: args.direction };
+        }
+        if (this.checkIdentifier("flash")) {
+            this.advance();
+            const args = this.parseTransitionArgs(["duration"]);
+            this.consumeOptional(TokenType.Semicolon);
+            return { kind: "flash", durationMs: args.durationMs };
+        }
+        throw this.errorAtToken(this.peek(), "Invalid transition spec");
+    }
+    parseTransitionArgs(allowed) {
+        const args = {};
+        this.consume(TokenType.LParen, "Expected '(' after transition");
+        while (!this.check(TokenType.RParen) && !this.isAtEnd()) {
+            if (this.check(TokenType.Identifier) && this.peek(1).type === TokenType.Equals) {
+                const nameTok = this.advance();
+                const name = nameTok.lexeme;
+                this.consume(TokenType.Equals, "Expected '=' after argument name");
+                if (!allowed.includes(name)) {
+                    throw this.errorAtToken(nameTok, `Unknown transition argument '${name}'`);
+                }
+                if (name === "duration") {
+                    args.durationMs = this.parseDurationMs("Expected transition duration");
+                }
+                else if (name === "ease") {
+                    const ease = this.parseTransitionString("Expected transition ease");
+                    if (!isTransitionEase(ease)) {
+                        throw this.errorAtToken(nameTok, `Unknown transition ease '${ease}'`);
+                    }
+                    args.ease = ease;
+                }
+                else if (name === "direction") {
+                    const direction = this.parseTransitionString("Expected wipe direction");
+                    if (!isTransitionDirection(direction)) {
+                        throw this.errorAtToken(nameTok, `Unknown wipe direction '${direction}'`);
+                    }
+                    args.direction = direction;
+                }
+            }
+            else {
+                throw this.errorAtToken(this.peek(), "Expected named transition argument");
+            }
+            if (!this.match(TokenType.Comma))
+                break;
+        }
+        this.consume(TokenType.RParen, "Expected ')' after transition arguments");
+        return args;
+    }
+    parseTransitionString(message) {
+        const tok = this.peek();
+        if (tok.type === TokenType.String || tok.type === TokenType.Identifier) {
+            this.advance();
+            return String(tok.value ?? tok.lexeme);
+        }
+        throw this.errorAtToken(tok, message);
+    }
+    parseChanceEvery() {
+        if (this.check(TokenType.Identifier)) {
+            const tok = this.peek();
+            if (tok.lexeme === "docstep") {
+                this.advance();
+                return { kind: "docstep" };
+            }
+        }
+        if (this.check(TokenType.String)) {
+            const tok = this.advance();
+            const raw = String(tok.value ?? tok.lexeme);
+            if (raw === "docstep") {
+                return { kind: "docstep" };
+            }
+            const seconds = parseTimeString(raw);
+            if (seconds == null) {
+                throw this.errorAtToken(tok, `Invalid duration '${raw}'`);
+            }
+            if (seconds <= 0) {
+                throw this.errorAtToken(tok, "Duration must be positive");
+            }
+            return { kind: "time", intervalSec: seconds };
+        }
+        if (this.check(TokenType.Int) || this.check(TokenType.Float)) {
+            const seconds = this.parseTimeSeconds("Expected duration");
+            return { kind: "time", intervalSec: seconds };
+        }
+        throw this.errorAtToken(this.peek(), "Expected 'docstep' or duration for chance every");
+    }
+    parseTimeSeconds(message, allowZero = false) {
+        const tok = this.peek();
+        if (tok.type === TokenType.String) {
+            this.advance();
+            const raw = String(tok.value ?? tok.lexeme);
+            const seconds = parseTimeString(raw);
+            if (seconds == null) {
+                throw this.errorAtToken(tok, `Invalid duration '${raw}'`);
+            }
+            if (seconds < 0 || (!allowZero && seconds === 0)) {
+                throw this.errorAtToken(tok, allowZero ? "Duration must be non-negative" : "Duration must be positive");
+            }
+            return seconds;
+        }
+        if (tok.type === TokenType.Int || tok.type === TokenType.Float) {
+            const { amount, unit } = this.parseDurationSpec();
+            const seconds = durationToSeconds(amount, unit);
+            if (seconds == null) {
+                throw this.errorAtToken(tok, `Unsupported duration unit '${unit}'`);
+            }
+            if (seconds < 0 || (!allowZero && seconds === 0)) {
+                throw this.errorAtToken(tok, allowZero ? "Duration must be non-negative" : "Duration must be positive");
+            }
+            return seconds;
+        }
+        throw this.errorAtToken(tok, message);
+    }
+    parseDurationMs(message) {
+        const tok = this.peek();
+        if (tok.type === TokenType.String) {
+            this.advance();
+            const raw = String(tok.value ?? tok.lexeme);
+            const seconds = parseTimeString(raw);
+            if (seconds == null) {
+                throw this.errorAtToken(tok, `Invalid duration '${raw}'`);
+            }
+            if (seconds < 0) {
+                throw this.errorAtToken(tok, "Duration must be non-negative");
+            }
+            return seconds * 1000;
+        }
+        if (tok.type === TokenType.Int || tok.type === TokenType.Float) {
+            if (this.peek(1).type === TokenType.Identifier) {
+                const { amount, unit } = this.parseDurationSpec();
+                const seconds = durationToSeconds(amount, unit);
+                if (seconds == null) {
+                    throw this.errorAtToken(tok, `Unsupported duration unit '${unit}'`);
+                }
+                if (seconds < 0) {
+                    throw this.errorAtToken(tok, "Duration must be non-negative");
+                }
+                return seconds * 1000;
+            }
+            this.advance();
+            const amount = Number(tok.value);
+            if (!Number.isFinite(amount)) {
+                throw this.errorAtToken(tok, message);
+            }
+            if (amount < 0) {
+                throw this.errorAtToken(tok, "Duration must be non-negative");
+            }
+            return amount;
+        }
+        throw this.errorAtToken(tok, message);
+    }
+    looksLikeNodeDecl() {
+        return (this.check(TokenType.Identifier) &&
+            this.peek(1).type === TokenType.Identifier &&
+            this.peek(2).type === TokenType.LBrace);
+    }
+    parseIdentifierList() {
+        this.advance(); // identifier keyword already checked
+        this.consume(TokenType.Equals, "Expected '=' after identifier list key");
+        this.consume(TokenType.LBracket, "Expected '[' to start identifier list");
+        const values = [];
+        if (!this.check(TokenType.RBracket)) {
+            const first = this.consume(TokenType.Identifier, "Expected identifier");
+            values.push(String(first.value));
+            while (this.match(TokenType.Comma)) {
+                const t = this.consume(TokenType.Identifier, "Expected identifier");
+                values.push(String(t.value));
+            }
+        }
+        this.consume(TokenType.RBracket, "Expected ']' after identifier list");
+        this.consumeOptional(TokenType.Semicolon);
+        return values;
+    }
+    parseKeyPath(message) {
+        const first = this.consume(TokenType.Identifier, message);
+        const parts = [String(first.value)];
+        while (this.match(TokenType.Dot)) {
+            const next = this.consume(TokenType.Identifier, "Expected identifier after '.'");
+            parts.push(String(next.value));
+        }
+        return parts.join(".");
+    }
+    parsePropertyMap() {
+        const props = {};
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const key = this.parseKeyPath("Expected property name");
+            this.consume(TokenType.Equals, "Expected '=' after property name");
+            if (this.match(TokenType.At)) {
+                const expr = this.parseExpr();
+                props[key] = { kind: "DynamicValue", expr };
+            }
+            else {
+                const value = this.parseValueLiteral();
+                props[key] = { kind: "LiteralValue", value };
+            }
+            this.consumeOptional(TokenType.Semicolon);
+        }
+        return props;
+    }
     // --- Expressions ---
     parseExpr() {
         return this.parseOr();
@@ -935,6 +1780,7 @@ class Parser {
                 kind: "UnaryExpression",
                 op,
                 argument,
+                loc: argument?.loc,
             };
         }
         if (this.match(TokenType.Minus)) {
@@ -944,6 +1790,7 @@ class Parser {
                 kind: "UnaryExpression",
                 op,
                 argument,
+                loc: argument?.loc,
             };
         }
         return this.parsePostfix();
@@ -958,11 +1805,14 @@ class Parser {
                     kind: "MemberExpression",
                     object: expr,
                     property,
+                    loc: expr?.loc,
                 };
             }
             else if (this.match(TokenType.LParen)) {
                 const args = this.parseArgumentList();
-                expr = this.maybeNeighborsCall(expr, args);
+                const callExpr = this.maybeNeighborsCall(expr, args);
+                callExpr.loc = expr?.loc;
+                expr = callExpr;
             }
             else {
                 break;
@@ -979,6 +1829,7 @@ class Parser {
                 return {
                     kind: "Literal",
                     value: tok.value,
+                    loc: { line: tok.line, column: tok.column },
                 };
             }
             case TokenType.String: {
@@ -986,6 +1837,7 @@ class Parser {
                 return {
                     kind: "Literal",
                     value: tok.value,
+                    loc: { line: tok.line, column: tok.column },
                 };
             }
             case TokenType.Bool: {
@@ -993,6 +1845,23 @@ class Parser {
                 return {
                     kind: "Literal",
                     value: tok.value,
+                    loc: { line: tok.line, column: tok.column },
+                };
+            }
+            case TokenType.LBracket: {
+                this.advance(); // '['
+                const items = [];
+                if (!this.check(TokenType.RBracket)) {
+                    items.push(this.parseExpr());
+                    while (this.match(TokenType.Comma)) {
+                        items.push(this.parseExpr());
+                    }
+                }
+                this.consume(TokenType.RBracket, "Expected ']' after list literal");
+                return {
+                    kind: "ListExpression",
+                    items,
+                    loc: { line: tok.line, column: tok.column },
                 };
             }
             case TokenType.Identifier: {
@@ -1000,6 +1869,7 @@ class Parser {
                 return {
                     kind: "Identifier",
                     name: tok.lexeme,
+                    loc: { line: tok.line, column: tok.column },
                 };
             }
             case TokenType.LBrace: {
@@ -1026,13 +1896,23 @@ class Parser {
             this.consume(TokenType.RParen, "Expected ')' after argument list");
             return args;
         }
-        args.push(this.parseExpr());
+        args.push(this.parseCallArg());
         while (this.match(TokenType.Comma)) {
-            args.push(this.parseExpr());
+            args.push(this.parseCallArg());
         }
         this.consume(TokenType.RParen, "Expected ')' after argument list");
         return args;
     }
+    parseCallArg() {
+        if (this.check(TokenType.Identifier) && this.peek(1).type === TokenType.Equals) {
+            const nameTok = this.advance();
+            const name = String(nameTok.value);
+            this.consume(TokenType.Equals, "Expected '=' after argument name");
+            const value = this.parseExpr();
+            return { kind: "NamedArg", name, value };
+        }
+        return this.parseExpr();
+    }
     maybeNeighborsCall(callee, args) {
         if (callee.kind === "MemberExpression" &&
             callee.object.kind === "Identifier" &&
@@ -1056,6 +1936,7 @@ class Parser {
             op,
             left,
             right,
+            loc: left?.loc,
         };
     }
     // --- Rule & Runtime (placeholders for now) ---
@@ -1267,27 +2148,43 @@ class Parser {
             const unitTok = this.advance();
             const raw = String(unitTok.value);
             const lowered = raw.toLowerCase();
-            // seconds
-            if (lowered === "s" ||
-                lowered === "sec" ||
-                lowered === "secs" ||
-                lowered === "second" ||
-                lowered === "seconds") {
-                unit = "s";
-            }
-            // milliseconds
-            else if (lowered === "ms" ||
-                lowered === "millisecond" ||
-                lowered === "milliseconds") {
-                unit = "ms";
-            }
-            // beats (musical)
-            else if (lowered === "beat" || lowered === "beats") {
-                unit = "beats";
-            }
-            else {
+            const unitMap = {
+                s: "s",
+                sec: "s",
+                secs: "s",
+                second: "s",
+                seconds: "s",
+                ms: "ms",
+                millisecond: "ms",
+                milliseconds: "ms",
+                m: "m",
+                min: "m",
+                mins: "m",
+                minute: "m",
+                minutes: "m",
+                h: "h",
+                hr: "h",
+                hrs: "h",
+                hour: "h",
+                hours: "h",
+                beat: "beats",
+                beats: "beats",
+                bar: "bars",
+                bars: "bars",
+                measure: "bars",
+                measures: "bars",
+                sub: "subs",
+                subs: "subs",
+                subdivision: "subs",
+                subdivisions: "subs",
+                tick: "ticks",
+                ticks: "ticks",
+            };
+            const mapped = unitMap[lowered];
+            if (!mapped) {
                 throw this.errorAtToken(unitTok, `Unknown duration unit '${unitTok.lexeme}'`);
             }
+            unit = mapped;
         }
         return { amount, unit };
     }
@@ -1370,6 +2267,38 @@ class Parser {
                 throw this.errorAtToken(tok, "Expected literal");
         }
     }
+    parseValueLiteral() {
+        const tok = this.peek();
+        switch (tok.type) {
+            case TokenType.Int:
+            case TokenType.Float:
+                this.advance();
+                return tok.value;
+            case TokenType.String:
+                this.advance();
+                return tok.value;
+            case TokenType.Bool:
+                this.advance();
+                return tok.value;
+            case TokenType.Identifier:
+                this.advance();
+                return tok.lexeme;
+            case TokenType.LBracket: {
+                this.advance();
+                const items = [];
+                if (!this.check(TokenType.RBracket)) {
+                    items.push(this.parseValueLiteral());
+                    while (this.match(TokenType.Comma)) {
+                        items.push(this.parseValueLiteral());
+                    }
+                }
+                this.consume(TokenType.RBracket, "Expected ']' after list literal");
+                return items;
+            }
+            default:
+                throw this.errorAtToken(tok, "Expected literal value");
+        }
+    }
     consumeNumber(message) {
         const tok = this.peek();
         if (tok.type === TokenType.Int || tok.type === TokenType.Float) {
@@ -1442,11 +2371,190 @@ class Parser {
         return new Error(`Parse error at ${token.line}:${token.column} near '${token.lexeme}': ${message}`);
     }
 }
-// Public API
-export function parseDocument(source) {
+function isTransitionEase(value) {
+    return value === "linear" || value === "inOut" || value === "in" || value === "out";
+}
+function isTransitionDirection(value) {
+    return value === "left" || value === "right" || value === "up" || value === "down";
+}
+const DEFAULT_INCLUDE_BYTES = 1024 * 1024;
+const DEFAULT_INCLUDE_DEPTH = 8;
+export function parseDocument(source, options = {}) {
     const lexer = new Lexer(source);
     const tokens = lexer.tokenize();
-    const parser = new Parser(tokens);
-    return parser.parseDocument();
+    const parser = new Parser(tokens, { allowBodyFragments: options.allowBodyFragments });
+    const doc = parser.parseDocument();
+    const shouldResolve = options.resolveIncludes || options.sourcePath || options.docRoot;
+    if (!shouldResolve)
+        return doc;
+    const root = options.docRoot ?? (options.sourcePath ? path.dirname(options.sourcePath) : null);
+    if (!root)
+        return doc;
+    return resolveIncludes(doc, {
+        docRoot: root,
+        sourcePath: options.sourcePath ?? "<buffer>",
+        maxIncludeBytes: options.maxIncludeBytes ?? DEFAULT_INCLUDE_BYTES,
+        includeDepthLimit: options.includeDepthLimit ?? DEFAULT_INCLUDE_DEPTH,
+    });
+}
+function resolveIncludes(doc, options) {
+    const context = { ...options, seen: new Set() };
+    const body = doc.body;
+    if (!body?.nodes?.length)
+        return doc;
+    const nodes = resolveIncludeNodes(body.nodes, context, "root", 0);
+    return { ...doc, body: { nodes } };
+}
+function resolveIncludeNodes(nodes, ctx, parentPath, depth) {
+    if (depth > ctx.includeDepthLimit) {
+        throw new Error(`Include depth exceeds limit (${ctx.includeDepthLimit}) at ${parentPath}`);
+    }
+    const result = [];
+    for (let index = 0; index < nodes.length; index += 1) {
+        const node = nodes[index];
+        const nodePath = `${parentPath}/${node.kind}:${node.id}:${index}`;
+        if (node.kind === "include") {
+            const includePath = resolveIncludePath(node, ctx, nodePath);
+            const included = loadIncludedDocument(includePath, ctx, depth + 1);
+            const includeNodes = included.body?.nodes ?? [];
+            const rewritten = rewriteNodeIds(includeNodes, includePath, nodePath);
+            result.push(...rewritten);
+            continue;
+        }
+        const children = node.children?.length
+            ? resolveIncludeNodes(node.children, ctx, nodePath, depth)
+            : [];
+        result.push({ ...node, children });
+    }
+    return result;
+}
+function resolveIncludePath(node, ctx, nodePath) {
+    const raw = node.props?.path?.kind === "LiteralValue"
+        ? String(node.props.path.value)
+        : node.props?.src?.kind === "LiteralValue"
+            ? String(node.props.src.value)
+            : null;
+    if (!raw) {
+        throw new Error(`Include at ${nodePath} requires a literal 'path' (or 'src') string`);
+    }
+    if (path.isAbsolute(raw)) {
+        throw new Error(`Include path must be relative: '${raw}'`);
+    }
+    if (raw.split(/[\\/]+/).some((part) => part === "..")) {
+        throw new Error(`Include path cannot contain '..': '${raw}'`);
+    }
+    const resolved = path.resolve(ctx.docRoot, raw);
+    if (!resolved.startsWith(ctx.docRoot)) {
+        throw new Error(`Include path escapes doc root: '${raw}'`);
+    }
+    if (path.extname(resolved) !== ".flux") {
+        throw new Error(`Include path must target a .flux file: '${raw}'`);
+    }
+    return resolved;
+}
+function parseTimeString(raw) {
+    const trimmed = raw.trim();
+    const match = trimmed.match(/^([0-9]*\.?[0-9]+)\s*(ms|s|m)$/i);
+    if (!match)
+        return null;
+    const value = Number(match[1]);
+    if (!Number.isFinite(value) || value < 0)
+        return null;
+    const unit = match[2].toLowerCase();
+    switch (unit) {
+        case "ms":
+            return value / 1000;
+        case "s":
+            return value;
+        case "m":
+            return value * 60;
+        default:
+            return null;
+    }
+}
+function durationToSeconds(amount, unit) {
+    switch (unit) {
+        case "ms":
+            return amount / 1000;
+        case "s":
+        case "sec":
+        case "secs":
+        case "second":
+        case "seconds":
+            return amount;
+        case "m":
+        case "min":
+        case "mins":
+        case "minute":
+        case "minutes":
+            return amount * 60;
+        case "h":
+        case "hr":
+        case "hrs":
+        case "hour":
+        case "hours":
+            return amount * 3600;
+        default:
+            return null;
+    }
+}
+function loadIncludedDocument(filePath, ctx, depth) {
+    if (ctx.seen.has(filePath)) {
+        throw new Error(`Include cycle detected at '${filePath}'`);
+    }
+    ctx.seen.add(filePath);
+    const stat = fs.statSync(filePath);
+    if (stat.size > ctx.maxIncludeBytes) {
+        throw new Error(`Include file too large (${stat.size} bytes): '${filePath}'`);
+    }
+    const source = fs.readFileSync(filePath, "utf8");
+    const doc = parseDocument(source, {
+        sourcePath: filePath,
+        docRoot: ctx.docRoot,
+        resolveIncludes: true,
+        maxIncludeBytes: ctx.maxIncludeBytes,
+        includeDepthLimit: ctx.includeDepthLimit - depth,
+        allowBodyFragments: true,
+    });
+    ctx.seen.delete(filePath);
+    return doc;
+}
+function rewriteNodeIds(nodes, includePath, parentPath) {
+    return nodes.map((node, index) => {
+        const nodePath = `${parentPath}/${node.kind}:${node.id}:${index}`;
+        const hash = stableHash(includePath, nodePath).toString(16).padStart(6, "0");
+        const nextId = `${node.id}_${hash}`;
+        const children = rewriteNodeIds(node.children ?? [], includePath, nodePath);
+        return { ...node, id: nextId, children };
+    });
+}
+function stableHash(...values) {
+    const serialized = values.map((value) => stableSerialize(value)).join("|");
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < serialized.length; i += 1) {
+        hash ^= serialized.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+function stableSerialize(value) {
+    if (value == null)
+        return "null";
+    if (typeof value === "number")
+        return `n:${String(value)}`;
+    if (typeof value === "string")
+        return `s:${value}`;
+    if (typeof value === "boolean")
+        return `b:${value}`;
+    if (Array.isArray(value)) {
+        return `a:[${value.map((item) => stableSerialize(item)).join(",")}]`;
+    }
+    if (typeof value === "object") {
+        const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+        return `o:{${entries
+            .map(([key, val]) => `${key}:${stableSerialize(val)}`)
+            .join(",")}}`;
+    }
+    return `u:${String(value)}`;
 }
 //# sourceMappingURL=parser.js.map