tina4-nodejs 3.13.85 → 3.13.87

package/packages/core/src/metrics.ts

@@ -1183,7 +1183,14 @@ export function fullAnalysis(root: string = "src"): Record<string, any> {
     total_functions: allFunctions.length,
     avg_complexity: Math.round(avgCC * 100) / 100,
     avg_maintainability: Math.round(avgMI * 10) / 10,
+    // Display-only: the top-15 for the "most complex functions" report.
+    // Do NOT source offenders / --fail-on from this — capping here silently
+    // hides the 16th+ over-threshold function from the gate. offenders()
+    // reads "all_functions" (below) instead.
     most_complex_functions: allFunctions.slice(0, 15),
+    // Full, uncapped, complexity-sorted list — offenders()/--fail-on use this
+    // so no function over the complexity threshold ever escapes the gate.
+    all_functions: allFunctions,
     file_metrics: fileMetrics,
     violations,
     dependency_graph: importGraph,
@@ -1243,8 +1250,10 @@ export function offenders(root: string = "src", top: number = 20): OffendersResu
 
   const items: Offender[] = [];
 
-  // Function-level: cyclomatic complexity.
-  for (const fn of analysis.most_complex_functions || []) {
+  // Function-level: cyclomatic complexity. Use the FULL function list (not the
+  // display-capped most_complex_functions[:15]) so a 16th+ over-threshold
+  // function is never silently dropped from the offenders list or --fail-on.
+  for (const fn of analysis.all_functions || analysis.most_complex_functions || []) {
     const cc: number = fn.complexity;
     if (cc > 10) {
       items.push({

package/packages/core/src/session.ts

@@ -2,7 +2,7 @@
  * Tina4 Session — Pluggable session backends, zero core dependencies.
  *
  * File-based sessions by default. Redis backend available via raw TCP (no ioredis needed).
- * Database (SQLite) backend available via better-sqlite3.
+ * Database (SQLite) backend available via Node's built-in node:sqlite.
  *
  *   import { Session, RedisSessionHandler } from "@tina4/core";
  *
@@ -15,7 +15,7 @@
  *     redisPort: 6379,
  *   });
  *
- *   // Database backend (SQLite via better-sqlite3)
+ *   // Database backend (SQLite via node:sqlite)
  *   const session = new Session("database");
  *   // or: new Session("db");
  *

package/packages/core/src/sessionHandlers/databaseHandler.ts

@@ -1,14 +1,13 @@
 /**
- * Tina4 Database Session Handler — SQLite via better-sqlite3, zero extra dependencies.
+ * Tina4 Database Session Handler — SQLite via Node's built-in node:sqlite,
+ * zero extra dependencies.
  *
- * Uses the same `better-sqlite3` library the ORM already depends on.
+ * Uses the same `node:sqlite` (DatabaseSync) the ORM's SQLite adapter uses —
+ * no third-party driver, nothing to install.
  * Stores sessions in a `tina4_session` table with JSON data and expiry.
  *
  * Configure via environment variables:
  *   TINA4_DATABASE_URL  (default: "sqlite:///data/tina4_sessions.db")
- *
- * The handler dynamically imports `better-sqlite3` and throws a clear
- * error if the package is not installed.
  */
 import { DatabaseSync } from "node:sqlite";
 import type { SessionHandler } from "../session.js";
@@ -35,7 +34,7 @@ export interface DatabaseSessionConfig {
 }
 
 /**
- * Database session handler using better-sqlite3 (synchronous SQLite).
+ * Database session handler using node:sqlite (synchronous SQLite).
  *
  * Stores session data as JSON in a `tina4_session` table.
  * Expiry is checked on read; expired rows are cleaned up lazily.

package/packages/frond/dist/index.js

@@ -101,6 +101,15 @@ function liveAttr(value) {
 }
 var filterChainCache = /* @__PURE__ */ new Map();
 var pathParseCache = /* @__PURE__ */ new Map();
+var TEMPLATE_CACHE_MAX = 256;
+function capCache(cache, maxEntries) {
+  if (cache.size < maxEntries) return;
+  let drop = Math.floor(maxEntries / 2);
+  for (const key of cache.keys()) {
+    cache.delete(key);
+    if (--drop <= 0) break;
+  }
+}
 var TOKEN_RE = /(\{%-?\s*[\s\S]*?\s*-?%\})|(\{\{-?\s*[\s\S]*?\s*-?\}\})|(\{#[\s\S]*?#\})/g;
 var RAW_BLOCK_RE = /\{%-?\s*raw\s*-?%\}([\s\S]*?)\{%-?\s*endraw\s*-?%\}/g;
 function tokenize(source) {
@@ -316,11 +325,14 @@ function resolveVar(expr, context) {
   return value;
 }
 function findOutsideQuotes(expr, needle) {
+  if (!expr.includes(needle)) return -1;
   let inQuote = null;
   let depth = 0;
   let bracketDepth = 0;
   let i = 0;
-  while (i <= expr.length - needle.length) {
+  const needleLen = needle.length;
+  const lastStart = expr.length - needleLen;
+  while (i <= lastStart) {
     const ch = expr[i];
     if ((ch === '"' || ch === "'") && depth === 0 && bracketDepth === 0) {
       if (inQuote === null) {
@@ -339,7 +351,7 @@ function findOutsideQuotes(expr, needle) {
     else if (ch === ")") depth--;
     else if (ch === "[") bracketDepth++;
     else if (ch === "]") bracketDepth--;
-    if (depth === 0 && bracketDepth === 0 && expr.slice(i, i + needle.length) === needle) {
+    if (depth === 0 && bracketDepth === 0 && expr.startsWith(needle, i)) {
       return i;
     }
     i++;
@@ -347,13 +359,16 @@ function findOutsideQuotes(expr, needle) {
   return -1;
 }
 function splitOutsideQuotes(expr, sep) {
+  if (!expr.includes(sep)) return [expr];
   const parts = [];
   let currentStart = 0;
   let inQuote = null;
   let depth = 0;
   let bracketDepth = 0;
   let i = 0;
-  while (i <= expr.length - sep.length) {
+  const sepLen = sep.length;
+  const lastStart = expr.length - sepLen;
+  while (i <= lastStart) {
     const ch = expr[i];
     if ((ch === '"' || ch === "'") && depth === 0 && bracketDepth === 0) {
       if (inQuote === null) {
@@ -372,9 +387,9 @@ function splitOutsideQuotes(expr, sep) {
     else if (ch === ")") depth--;
     else if (ch === "[") bracketDepth++;
     else if (ch === "]") bracketDepth--;
-    if (depth === 0 && bracketDepth === 0 && expr.slice(i, i + sep.length) === sep) {
+    if (depth === 0 && bracketDepth === 0 && expr.startsWith(sep, i)) {
       parts.push(expr.slice(currentStart, i));
-      i += sep.length;
+      i += sepLen;
       currentStart = i;
       continue;
     }
@@ -448,6 +463,9 @@ function evalExpr(expr, context) {
       }).join("");
     }
   }
+  if (expr.startsWith("not ")) {
+    return evalComparison(expr, context);
+  }
   for (const op of [" not in ", " in ", " is not ", " is ", "!=", "==", ">=", "<=", ">", "<", " and ", " or ", " not "]) {
     if (findOutsideQuotes(expr, op) >= 0) {
       return evalComparison(expr, context);
@@ -1403,6 +1421,7 @@ var Frond = class _Frond {
     const source = readFileSync(filePath, "utf-8");
     const mtime = statSync(filePath).mtimeMs;
     const tokens = tokenize(source);
+    capCache(this.compiled, TEMPLATE_CACHE_MAX);
     this.compiled.set(template, { tokens, mtime, cachedAt: Date.now() });
     return this.executeWithSource(source, tokens, context);
   }
@@ -1417,6 +1436,7 @@ var Frond = class _Frond {
       }
     }
     const tokens = tokenize(source);
+    capCache(this.compiledStrings, TEMPLATE_CACHE_MAX);
     this.compiledStrings.set(key, { tokens, cachedAt: Date.now() });
     return this.executeCached(tokens, context);
   }
@@ -1632,6 +1652,9 @@ var Frond = class _Frond {
         } else if (tag === "macro") {
           const skip = this.handleMacro(tokens, i, context);
           i = skip;
+        } else if (tag === "import") {
+          this.handleImportAs(content, context);
+          i++;
         } else if (tag === "from") {
           this.handleFromImport(content, context);
           i++;
@@ -2198,7 +2221,7 @@ var Frond = class _Frond {
       return i2;
     }
     const macroName = m[1];
-    const paramNames = m[2].split(",").map((p) => p.trim()).filter(Boolean);
+    const params = _Frond.parseMacroParams(m[2]);
     const bodyTokens = [];
     let i = start + 1;
     while (i < tokens.length) {
@@ -2213,13 +2236,94 @@ var Frond = class _Frond {
     const capturedContext = { ...context };
     context[macroName] = (...args) => {
       const macroCtx = { ...capturedContext };
-      for (let pi = 0; pi < paramNames.length; pi++) {
-        macroCtx[paramNames[pi]] = pi < args.length ? args[pi] : null;
+      for (let pi = 0; pi < params.length; pi++) {
+        const [pname, pdefault] = params[pi];
+        macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
       }
       return new SafeString(engine.renderTokens([...bodyTokens], macroCtx));
     };
     return i;
   }
+  /**
+   * Parse a macro parameter list into [name, default] pairs.
+   *
+   * Handles: name, name="default", name='default'. Splitting on "," alone left a
+   * defaulted parameter literally NAMED `greeting='Hello'`, so the body's
+   * {{ greeting }} matched nothing (rendered empty) AND the caller's positional
+   * argument was stored under that junk key and lost. Mirrors the Python master's
+   * _parse_macro_params. The default is null when none is declared.
+   */
+  static parseMacroParams(rawParams) {
+    return rawParams.split(",").map((p) => p.trim()).filter(Boolean).map((p) => {
+      const eq = p.indexOf("=");
+      if (eq === -1) return [p, null];
+      const name = p.slice(0, eq).trim();
+      let dflt = p.slice(eq + 1).trim();
+      if (dflt.length >= 2 && (dflt.startsWith('"') && dflt.endsWith('"') || dflt.startsWith("'") && dflt.endsWith("'"))) {
+        dflt = dflt.slice(1, -1);
+      }
+      return [name, dflt];
+    });
+  }
+  /**
+   * {% import "file" as alias %} -- load EVERY macro in a file under one namespace.
+   *
+   * The alias is bound as a plain object of macro functions, so {{ alias.greet(x) }}
+   * resolves through the engine's existing dotted-call path and each macro keeps the
+   * same argument binding, default handling and SafeString output as any other macro.
+   * A namespace object (not a class) is deliberate: a function stored as a class
+   * attribute binds as a method and would inject the namespace as the first argument,
+   * which is exactly the argument-shift bug the Python master carried (fixed there
+   * with types.SimpleNamespace). Both import forms must render identically.
+   */
+  handleImportAs(content, context) {
+    const m = content.match(/^import\s+["'](.+?)["']\s+as\s+(\w+)/);
+    if (!m) return;
+    const filename = m[1];
+    const alias = m[2];
+    const namespace = {};
+    const source = this.load(filename);
+    const tokens = tokenize(source);
+    let i = 0;
+    while (i < tokens.length) {
+      const [ttype, raw] = tokens[i];
+      if (ttype === "BLOCK") {
+        const [tagContent] = stripTag(raw);
+        if ((tagContent.split(/\s+/)[0] || "") === "macro") {
+          const macroM = tagContent.match(/^macro\s+(\w+)\s*\(([^)]*)\)/);
+          if (macroM) {
+            const macroName = macroM[1];
+            const params = _Frond.parseMacroParams(macroM[2]);
+            const bodyTokens = [];
+            i++;
+            while (i < tokens.length) {
+              if (tokens[i][0] === "BLOCK" && tokens[i][1].includes("endmacro")) {
+                i++;
+                break;
+              }
+              bodyTokens.push(tokens[i]);
+              i++;
+            }
+            const capturedBody = [...bodyTokens];
+            const capturedParams = [...params];
+            const capturedCtx = { ...context };
+            const engine = this;
+            namespace[macroName] = (...args) => {
+              const macroCtx = { ...capturedCtx };
+              for (let pi = 0; pi < capturedParams.length; pi++) {
+                const [pname, pdefault] = capturedParams[pi];
+                macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
+              }
+              return new SafeString(engine.renderTokens([...capturedBody], macroCtx));
+            };
+            continue;
+          }
+        }
+      }
+      i++;
+    }
+    context[alias] = namespace;
+  }
   handleFromImport(content, context) {
     const m = content.match(/^from\s+["'](.+?)["']\s+import\s+(.+)/);
     if (!m) return;
@@ -2237,7 +2341,7 @@ var Frond = class _Frond {
           const macroM = tagContent.match(/^macro\s+(\w+)\s*\(([^)]*)\)/);
           if (macroM && names.includes(macroM[1])) {
             const macroName = macroM[1];
-            const paramNames = macroM[2].split(",").map((p) => p.trim()).filter(Boolean);
+            const paramNames = _Frond.parseMacroParams(macroM[2]);
             const bodyTokens = [];
             i++;
             while (i < tokens.length) {
@@ -2255,7 +2359,8 @@ var Frond = class _Frond {
             context[macroName] = (...args) => {
               const macroCtx = { ...capturedCtx };
               for (let pi = 0; pi < capturedParams.length; pi++) {
-                macroCtx[capturedParams[pi]] = pi < args.length ? args[pi] : null;
+                const [pname, pdefault] = capturedParams[pi];
+                macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
               }
               return new SafeString(engine.renderTokens([...capturedBody], macroCtx));
             };

package/packages/frond/src/engine.ts

@@ -202,6 +202,40 @@ const filterChainCache = new Map<string, [string, [string, unknown[]][]]>();
 /** Cache for parsed dotted/bracket paths: expr string -> [parts, fromBracket] */
 const pathParseCache = new Map<string, [string[], boolean[]]>();
 
+/**
+ * Hard cap on the template caches — `compiled` and `compiledStrings`
+ * (ADR-0004, parity with PHP/Python/Ruby TEMPLATE_CACHE_MAX).
+ *
+ * An entry here is a whole token list, so the cap sits well below what a
+ * per-expression memo would justify. 256 is far above any real application's
+ * template count, so a normal app never evicts. The cap exists for the
+ * workload that genuinely grows without limit for the life of a worker:
+ * `renderString` keys on md5(source), so an app that builds template strings
+ * dynamically adds an entry per distinct string.
+ */
+export const TEMPLATE_CACHE_MAX = 256;
+
+/**
+ * Keep a memo cache bounded. Call immediately before inserting a new entry.
+ *
+ * Eviction is insertion-ordered (oldest first), not true LRU: a `Map`
+ * preserves insertion order, so dropping from the front is cheap, whereas
+ * refreshing recency on every cache HIT would add writes to the hottest path
+ * in a render and cost more than it saves. Half the cache is dropped at once
+ * so the sweep amortises to O(1) per insert.
+ *
+ * Evicting can never change what a render produces: every read site treats a
+ * miss as "recompute", so a swept entry is rebuilt on next use.
+ */
+function capCache(cache: Map<string, unknown>, maxEntries: number): void {
+  if (cache.size < maxEntries) return;
+  let drop = Math.floor(maxEntries / 2);
+  for (const key of cache.keys()) {
+    cache.delete(key);
+    if (--drop <= 0) break;
+  }
+}
+
 // ── Lexer ──────────────────────────────────────────────────────
 
 const TOKEN_RE = /(\{%-?\s*[\s\S]*?\s*-?%\})|(\{\{-?\s*[\s\S]*?\s*-?\}\})|(\{#[\s\S]*?#\})/g;
@@ -444,11 +478,23 @@ function resolveVar(expr: string, context: Record<string, unknown>): unknown {
 }
 
 function findOutsideQuotes(expr: string, needle: string): number {
+  // Fast path. This is the hottest function in a render: profiling the Python
+  // twin showed 415,200 calls and 53% of render time for one 20-row loop
+  // template, and the overwhelming majority return -1 because the needle simply
+  // is not in the expression. includes() is a native scan, so bailing here skips
+  // the whole JS character loop. Exact, not a heuristic: a needle absent from
+  // the string cannot be present outside quotes either.
+  if (!expr.includes(needle)) return -1;
+
   let inQuote: string | null = null;
   let depth = 0;
   let bracketDepth = 0;
   let i = 0;
-  while (i <= expr.length - needle.length) {
+  // Hoisted out of the loop condition -- both lengths were recomputed on every
+  // single iteration.
+  const needleLen = needle.length;
+  const lastStart = expr.length - needleLen;
+  while (i <= lastStart) {
     const ch = expr[i];
     if ((ch === '"' || ch === "'") && depth === 0 && bracketDepth === 0) {
       if (inQuote === null) {
@@ -464,7 +510,9 @@ function findOutsideQuotes(expr: string, needle: string): number {
     else if (ch === ")") depth--;
     else if (ch === "[") bracketDepth++;
     else if (ch === "]") bracketDepth--;
-    if (depth === 0 && bracketDepth === 0 && expr.slice(i, i + needle.length) === needle) {
+    // startsWith(needle, i) rather than slice(i, i + needleLen) === needle: the
+    // slice allocated a throwaway string at every character position.
+    if (depth === 0 && bracketDepth === 0 && expr.startsWith(needle, i)) {
       return i;
     }
     i++;
@@ -473,13 +521,20 @@ function findOutsideQuotes(expr: string, needle: string): number {
 }
 
 function splitOutsideQuotes(expr: string, sep: string): string[] {
+  // Fast path, same reasoning as findOutsideQuotes: no separator anywhere means
+  // no split, and includes() is a native scan versus a JS character loop.
+  if (!expr.includes(sep)) return [expr];
+
   const parts: string[] = [];
   let currentStart = 0;
   let inQuote: string | null = null;
   let depth = 0;
   let bracketDepth = 0;
   let i = 0;
-  while (i <= expr.length - sep.length) {
+  // Hoisted out of the loop condition -- recomputed every iteration before.
+  const sepLen = sep.length;
+  const lastStart = expr.length - sepLen;
+  while (i <= lastStart) {
     const ch = expr[i];
     if ((ch === '"' || ch === "'") && depth === 0 && bracketDepth === 0) {
       if (inQuote === null) {
@@ -495,9 +550,10 @@ function splitOutsideQuotes(expr: string, sep: string): string[] {
     else if (ch === ")") depth--;
     else if (ch === "[") bracketDepth++;
     else if (ch === "]") bracketDepth--;
-    if (depth === 0 && bracketDepth === 0 && expr.slice(i, i + sep.length) === sep) {
+    // startsWith avoids allocating a throwaway slice at every position.
+    if (depth === 0 && bracketDepth === 0 && expr.startsWith(sep, i)) {
       parts.push(expr.slice(currentStart, i));
-      i += sep.length;
+      i += sepLen;
       currentStart = i;
       continue;
     }
@@ -587,7 +643,21 @@ function evalExpr(expr: string, context: Record<string, unknown>): unknown {
     }
   }
 
-  // Check for comparison/logical operators
+  // Comparison/logical operators -> evalComparison, the SAME evaluator {% if %}
+  // uses, so a condition means the same thing in a condition and in an output
+  // expression.
+  //
+  // The LEADING unary `not` needs its own check: every operator below is matched
+  // WITH surrounding spaces, so `not x` (nothing to its left) matched none of
+  // them, fell through to the variable-resolution tail, and was looked up as a
+  // variable literally named "not x" -- found nothing, rendered EMPTY.
+  // `{% if not x %}` and `x and not y` always worked; only the standalone
+  // `{{ not x }}` was dropped, and before booleans rendered lowercase a dropped
+  // expression and `false -> ''` looked identical, which is why it survived.
+  // Fixed in 3.13.87 alongside the boolean contract.
+  if (expr.startsWith("not ")) {
+    return evalComparison(expr, context);
+  }
   for (const op of [" not in ", " in ", " is not ", " is ", "!=", "==", ">=", "<=", ">", "<", " and ", " or ", " not "]) {
     if (findOutsideQuotes(expr, op) >= 0) {
       return evalComparison(expr, context);
@@ -1663,6 +1733,7 @@ export class Frond {
     const source = readFileSync(filePath, "utf-8");
     const mtime = statSync(filePath).mtimeMs;
     const tokens = tokenize(source);
+    capCache(this.compiled as Map<string, unknown>, TEMPLATE_CACHE_MAX);
     this.compiled.set(template, { tokens, mtime, cachedAt: Date.now() });
     return this.executeWithSource(source, tokens, context);
   }
@@ -1680,6 +1751,7 @@ export class Frond {
     }
 
     const tokens = tokenize(source);
+    capCache(this.compiledStrings as Map<string, unknown>, TEMPLATE_CACHE_MAX);
     this.compiledStrings.set(key, { tokens, cachedAt: Date.now() });
     return this.executeCached(tokens, context);
   }
@@ -1955,6 +2027,9 @@ export class Frond {
         } else if (tag === "macro") {
           const skip = this.handleMacro(tokens, i, context);
           i = skip;
+        } else if (tag === "import") {
+          this.handleImportAs(content, context);
+          i++;
         } else if (tag === "from") {
           this.handleFromImport(content, context);
           i++;
@@ -2565,7 +2640,7 @@ export class Frond {
     }
 
     const macroName = m[1];
-    const paramNames = m[2].split(",").map(p => p.trim()).filter(Boolean);
+    const params = Frond.parseMacroParams(m[2]);
 
     // Collect body tokens
     const bodyTokens: Token[] = [];
@@ -2584,8 +2659,9 @@ export class Frond {
     const capturedContext = { ...context };
     context[macroName] = (...args: unknown[]) => {
       const macroCtx: Record<string, unknown> = { ...capturedContext };
-      for (let pi = 0; pi < paramNames.length; pi++) {
-        macroCtx[paramNames[pi]] = pi < args.length ? args[pi] : null;
+      for (let pi = 0; pi < params.length; pi++) {
+        const [pname, pdefault] = params[pi];
+        macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
       }
       return new SafeString(engine.renderTokens([...bodyTokens], macroCtx));
     };
@@ -2593,6 +2669,104 @@ export class Frond {
     return i;
   }
 
+  /**
+   * Parse a macro parameter list into [name, default] pairs.
+   *
+   * Handles: name, name="default", name='default'. Splitting on "," alone left a
+   * defaulted parameter literally NAMED `greeting='Hello'`, so the body's
+   * {{ greeting }} matched nothing (rendered empty) AND the caller's positional
+   * argument was stored under that junk key and lost. Mirrors the Python master's
+   * _parse_macro_params. The default is null when none is declared.
+   */
+  static parseMacroParams(rawParams: string): Array<[string, string | null]> {
+    return rawParams
+      .split(",")
+      .map(p => p.trim())
+      .filter(Boolean)
+      .map(p => {
+        const eq = p.indexOf("=");
+        if (eq === -1) return [p, null] as [string, string | null];
+        const name = p.slice(0, eq).trim();
+        let dflt = p.slice(eq + 1).trim();
+        if (
+          dflt.length >= 2 &&
+          ((dflt.startsWith('"') && dflt.endsWith('"')) ||
+            (dflt.startsWith("'") && dflt.endsWith("'")))
+        ) {
+          dflt = dflt.slice(1, -1);
+        }
+        return [name, dflt] as [string, string | null];
+      });
+  }
+
+  /**
+   * {% import "file" as alias %} -- load EVERY macro in a file under one namespace.
+   *
+   * The alias is bound as a plain object of macro functions, so {{ alias.greet(x) }}
+   * resolves through the engine's existing dotted-call path and each macro keeps the
+   * same argument binding, default handling and SafeString output as any other macro.
+   * A namespace object (not a class) is deliberate: a function stored as a class
+   * attribute binds as a method and would inject the namespace as the first argument,
+   * which is exactly the argument-shift bug the Python master carried (fixed there
+   * with types.SimpleNamespace). Both import forms must render identically.
+   */
+  private handleImportAs(content: string, context: Record<string, unknown>): void {
+    const m = content.match(/^import\s+["'](.+?)["']\s+as\s+(\w+)/);
+    if (!m) return;
+
+    const filename = m[1];
+    const alias = m[2];
+    const namespace: Record<string, unknown> = {};
+
+    const source = this.load(filename);
+    const tokens = tokenize(source);
+
+    let i = 0;
+    while (i < tokens.length) {
+      const [ttype, raw] = tokens[i];
+      if (ttype === "BLOCK") {
+        const [tagContent] = stripTag(raw);
+        if ((tagContent.split(/\s+/)[0] || "") === "macro") {
+          const macroM = tagContent.match(/^macro\s+(\w+)\s*\(([^)]*)\)/);
+          if (macroM) {
+            const macroName = macroM[1];
+            const params = Frond.parseMacroParams(macroM[2]);
+
+            const bodyTokens: Token[] = [];
+            i++;
+            while (i < tokens.length) {
+              if (tokens[i][0] === "BLOCK" && tokens[i][1].includes("endmacro")) {
+                i++;
+                break;
+              }
+              bodyTokens.push(tokens[i]);
+              i++;
+            }
+
+            // Own copies per macro — avoids closure-over-loop-variable sharing.
+            const capturedBody = [...bodyTokens];
+            const capturedParams = [...params];
+            const capturedCtx = { ...context };
+            const engine = this;
+
+            namespace[macroName] = (...args: unknown[]) => {
+              const macroCtx: Record<string, unknown> = { ...capturedCtx };
+              for (let pi = 0; pi < capturedParams.length; pi++) {
+                const [pname, pdefault] = capturedParams[pi];
+                macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
+              }
+              return new SafeString(engine.renderTokens([...capturedBody], macroCtx));
+            };
+            continue;
+          }
+        }
+      }
+      i++;
+    }
+
+    context[alias] = namespace;
+  }
+
   private handleFromImport(content: string, context: Record<string, unknown>): void {
     const m = content.match(/^from\s+["'](.+?)["']\s+import\s+(.+)/);
     if (!m) return;
@@ -2613,7 +2787,7 @@ export class Frond {
           const macroM = tagContent.match(/^macro\s+(\w+)\s*\(([^)]*)\)/);
           if (macroM && names.includes(macroM[1])) {
             const macroName = macroM[1];
-            const paramNames = macroM[2].split(",").map(p => p.trim()).filter(Boolean);
+            const paramNames = Frond.parseMacroParams(macroM[2]);
 
             const bodyTokens: Token[] = [];
             i++;
@@ -2635,7 +2809,8 @@ export class Frond {
             context[macroName] = (...args: unknown[]) => {
               const macroCtx: Record<string, unknown> = { ...capturedCtx };
               for (let pi = 0; pi < capturedParams.length; pi++) {
-                macroCtx[capturedParams[pi]] = pi < args.length ? args[pi] : null;
+                const [pname, pdefault] = capturedParams[pi];
+                macroCtx[pname] = pi < args.length ? args[pi] : pdefault;
               }
               return new SafeString(engine.renderTokens([...capturedBody], macroCtx));
             };