@botfather/units 1.0.0

package/LICENSE

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

package/incremental.js

@@ -0,0 +1,64 @@
+// Incremental parsing sketch using node start/end offsets.
+// This is a reference strategy; it falls back to full parse today.
+
+import { parseUnits } from "./units-parser.js";
+
+export function findChangedRange(prev, next) {
+  const prevLen = prev.length;
+  const nextLen = next.length;
+
+  let start = 0;
+  while (start < prevLen && start < nextLen && prev[start] === next[start]) start++;
+
+  if (start === prevLen && start === nextLen) {
+    return { start, endPrev: start, endNext: start };
+  }
+
+  let endPrev = prevLen - 1;
+  let endNext = nextLen - 1;
+  while (endPrev >= start && endNext >= start && prev[endPrev] === next[endNext]) {
+    endPrev--;
+    endNext--;
+  }
+
+  return { start, endPrev: endPrev + 1, endNext: endNext + 1 };
+}
+
+export function findSmallestEnclosingNode(ast, start, end) {
+  let best = null;
+
+  function visit(node) {
+    if (!node || node.start == null || node.end == null) return;
+    if (node.start <= start && node.end >= end) {
+      if (!best || (node.end - node.start) < (best.end - best.start)) best = node;
+      if (node.children) node.children.forEach(visit);
+      if (node.body) node.body.forEach(visit);
+    }
+  }
+
+  visit(ast);
+  return best;
+}
+
+export function incrementalParse(prevAst, prevSource, nextSource) {
+  const change = findChangedRange(prevSource, nextSource);
+
+  // If no change, return previous AST.
+  if (change.start === change.endPrev && change.start === change.endNext) return prevAst;
+
+  // Strategy sketch:
+  // 1) Find smallest node in prevAst enclosing the change range.
+  // 2) Reparse just that slice of text into a temporary AST.
+  // 3) Splice the new subtree into the previous AST, adjusting offsets by delta.
+  // 4) Recalculate parent node end offsets above the splice point.
+  //
+  // This yields near-O(changed-region) for edits localized to a small subtree.
+  const enclosing = findSmallestEnclosingNode(prevAst, change.start, change.endPrev);
+
+  if (!enclosing) {
+    return parseUnits(nextSource);
+  }
+
+  // TODO: Implement subtree reparse and splice. For now, fall back.
+  return parseUnits(nextSource);
+}

package/index.d.ts

@@ -0,0 +1,8 @@
+export function parseUnits(input: string): any;
+export function formatUnits(source: string): string;
+export function createUnitsEvaluator(): (raw: string, scope: any, locals?: any) => any;
+export function renderUnits(ast: any, scope: any, options?: any): any;
+export function createUnitsRenderer(host: any): { render: (ast: any, scope: any, options?: any) => any };
+export function findChangedRange(prev: string, next: string): { start: number; endPrev: number; endNext: number };
+export function findSmallestEnclosingNode(ast: any, start: number, end: number): any;
+export function incrementalParse(prevAst: any, prevSource: string, nextSource: string): any;

package/index.js

@@ -0,0 +1,9 @@
+export { parseUnits } from "./units-parser.js";
+export { formatUnits } from "./units-print.js";
+export { createUnitsEvaluator, renderUnits } from "./units-runtime.js";
+export { createUnitsRenderer } from "./units-custom-renderer.js";
+export {
+  findChangedRange,
+  findSmallestEnclosingNode,
+  incrementalParse,
+} from "./incremental.js";

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@botfather/units",
+  "version": "1.0.0",
+  "description": "Lightweight DSL for building interactive UIs.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Botfather/units.git",
+    "directory": "packages/units"
+  },
+  "homepage": "https://github.com/Botfather/units/tree/main/packages/units",
+  "bugs": {
+    "url": "https://github.com/Botfather/units/issues"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": "./index.js",
+    "./parser": "./units-parser.js",
+    "./print": "./units-print.js",
+    "./runtime": "./units-runtime.js",
+    "./custom-renderer": "./units-custom-renderer.js",
+    "./incremental": "./incremental.js",
+    "./ui": {
+      "types": "./ui.d.ts",
+      "default": "./ui.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "*.d.ts"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/ui.d.ts

@@ -0,0 +1,24 @@
+declare module "*.ui" {
+  export const source: string;
+  export const ast: {
+    type: "document" | "tag" | "text" | "expr" | "directive";
+    [key: string]: unknown;
+  };
+  const _default: typeof ast;
+  export default _default;
+}
+
+declare module "*.ui?format" {
+  const formatted: string;
+  export default formatted;
+}
+
+declare module "*.ui?tokens" {
+  const tokens: Array<{ type: string; value: string }>;
+  export default tokens;
+}
+
+declare module "*.ui?highlight" {
+  const html: string;
+  export default html;
+}

package/ui.js

@@ -0,0 +1 @@
+export {};

package/units-custom-renderer.js

@@ -0,0 +1,165 @@
+// Custom renderer skeleton for Units AST.
+// Provide host callbacks to build your own UI tree.
+
+export function createUnitsRenderer(host) {
+  const evalExpr = host.evalExpr || ((raw, scope, locals) => {
+    const normalized = raw.replace(/@([A-Za-z_$][\\w.$]*)/g, "$1");
+    const fn = new Function("scope", "locals", `with(scope){with(locals||{}){return (${normalized});}}`);
+    return fn(scope, locals || {});
+  });
+
+  function splitInterpolations(value) {
+    const text = String(value ?? "");
+    const parts = [];
+    if (!text.includes("@{")) return [{ type: "text", value: text }];
+    let i = 0;
+    while (i < text.length) {
+      const idx = text.indexOf("@{", i);
+      if (idx === -1) {
+        if (i < text.length) parts.push({ type: "text", value: text.slice(i) });
+        break;
+      }
+      if (idx > i) parts.push({ type: "text", value: text.slice(i, idx) });
+      let j = idx + 2;
+      let depth = 1;
+      while (j < text.length) {
+        const ch = text[j];
+        if (ch === "'" || ch === "\"") {
+          const quote = ch;
+          j++;
+          while (j < text.length) {
+            const qch = text[j];
+            if (qch === "\\") {
+              j += 2;
+              continue;
+            }
+            if (qch === quote) {
+              j++;
+              break;
+            }
+            j++;
+          }
+          continue;
+        }
+        if (ch === "{") depth++;
+        else if (ch === "}") depth--;
+        if (depth === 0) break;
+        j++;
+      }
+      if (depth !== 0) {
+        parts.push({ type: "text", value: text.slice(idx) });
+        break;
+      }
+      const expr = text.slice(idx + 2, j).trim();
+      parts.push({ type: "expr", value: expr });
+      i = j + 1;
+    }
+    return parts;
+  }
+
+  function renderText(value, locals) {
+    const parts = splitInterpolations(value);
+    if (parts.length === 1 && parts[0].type === "text") return host.text(parts[0].value);
+    return host.fragment(
+      parts.map((part) => {
+        if (part.type === "text") return host.text(part.value);
+        return host.text(String(evalExpr(part.value, scope, locals)));
+      }),
+    );
+  }
+
+  function pushChild(out, value) {
+    if (Array.isArray(value)) out.push(...value);
+    else out.push(value);
+  }
+
+  function render(ast, scope, options = {}) {
+    const slots = options.slots || {};
+    const set = options.set || scope?.set || (() => {});
+
+    function renderNode(node, locals) {
+      if (!node) return null;
+      if (node.type === "text") return renderText(node.value, locals);
+      if (node.type === "expr") return host.text(String(evalExpr(node.value.raw, scope, locals)));
+      if (node.type === "directive") return renderDirective(node, locals);
+      if (node.type === "tag") return renderTag(node, locals);
+      return null;
+    }
+
+    function renderDirective(node, locals) {
+      const name = node.name;
+      const args = node.args || "";
+      if (name === "if") {
+        const cond = evalExpr(args, scope, locals);
+        if (!cond) return null;
+        return renderChildren(node.children, locals);
+      }
+      if (name === "for") {
+        const m = args.match(/^\s*([A-Za-z_$][\w$]*)\s*(?:,\s*([A-Za-z_$][\w$]*))?\s+in\s+(.+)$/);
+        if (!m) return null;
+        const itemName = m[1];
+        const idxName = m[2] || "index";
+        const listExpr = m[3].trim();
+        const list = evalExpr(listExpr, scope, locals) || [];
+        const out = [];
+        for (let idx = 0; idx < list.length; idx++) {
+          const childLocals = { ...locals, [itemName]: list[idx], [idxName]: idx };
+          out.push(renderChildren(node.children, childLocals));
+        }
+        return out;
+      }
+      if (name === "slot") {
+        const slotName = args.trim();
+        const slot = slots[slotName];
+        if (slot == null) return null;
+        return typeof slot === "function" ? slot(locals) : slot;
+      }
+      return renderChildren(node.children, locals);
+    }
+
+    function renderTag(node, locals) {
+      const props = {};
+      const events = {};
+      for (const prop of node.props || []) {
+        if (prop.kind === "value") props[prop.key] = prop.value;
+        else if (prop.kind === "expr") props[prop.key] = evalExpr(prop.expr.raw, scope, locals);
+        else if (prop.kind === "bool") {
+          const v = evalExpr(prop.expr.raw, scope, locals);
+          if (v) props[prop.key] = true;
+        } else if (prop.kind === "event") {
+          const eventName = prop.key.startsWith("on:") ? prop.key.slice(3) : prop.key;
+          events[eventName] = (event) => {
+            const handlerLocals = { ...locals, event, set };
+            return evalExpr(prop.expr.raw, scope, handlerLocals);
+          };
+        }
+      }
+
+      const children = renderChildren(node.children, locals);
+      return host.element(node.name, props, events, children);
+    }
+
+    function renderChildren(children, locals) {
+      const out = [];
+      for (let idx = 0; idx < (children || []).length; idx++) {
+        const child = children[idx];
+        pushChild(out, renderNode(child, locals));
+      }
+      return host.fragment(out);
+    }
+
+    if (ast.type === "document") return renderChildren(ast.body, {});
+    return renderNode(ast, {});
+  }
+
+  return { render };
+}
+
+/*
+Host interface example:
+const host = {
+  element: (name, props, events, children) => ({ type: name, props, events, children }),
+  text: (value) => ({ type: "text", value }),
+  fragment: (children) => children,
+};
+*/

package/units-parser.js

@@ -0,0 +1,389 @@
+// Minimal, dependency-free parser for Units.
+// Single-pass, O(n) over input size.
+
+export function parseUnits(input) {
+  const s = String(input ?? "");
+  const len = s.length;
+  let i = 0;
+
+  function isWS(ch) {
+    return ch === " " || ch === "\n" || ch === "\t" || ch === "\r";
+  }
+
+  function isIdentStart(ch) {
+    return (ch >= "A" && ch <= "Z") || (ch >= "a" && ch <= "z") || ch === "_";
+  }
+
+  function isIdent(ch) {
+    return isIdentStart(ch) || (ch >= "0" && ch <= "9") || ch === ":" || ch === "." || ch === "-";
+  }
+
+  function skipWS() {
+    while (i < len) {
+      const ch = s[i];
+      if (isWS(ch)) {
+        i++;
+        continue;
+      }
+      // line comments: //...
+      if (ch === "/" && s[i + 1] === "/") {
+        i += 2;
+        while (i < len && s[i] !== "\n") i++;
+        continue;
+      }
+      break;
+    }
+  }
+
+  function error(msg) {
+    const snippet = s.slice(Math.max(0, i - 20), Math.min(len, i + 20));
+    throw new Error(`${msg} at ${i}: ...${snippet}...`);
+  }
+
+  function readIdent() {
+    if (!isIdentStart(s[i])) error("Expected identifier");
+    const start = i;
+    i++;
+    while (i < len && isIdent(s[i])) i++;
+    return s.slice(start, i);
+  }
+
+  function isValueStart(ch, idx) {
+    if (!ch) return false;
+    if (ch === "'" || ch === "@" || ch === "{" || ch === "-" || (ch >= "0" && ch <= "9")) return true;
+    if (s.startsWith("true", idx)) return true;
+    if (s.startsWith("false", idx)) return true;
+    if (s.startsWith("null", idx)) return true;
+    return false;
+  }
+
+  function readPropKey() {
+    if (!isIdentStart(s[i])) error("Expected identifier");
+    const start = i;
+    i++;
+    while (i < len) {
+      const ch = s[i];
+      if (!isIdent(ch)) break;
+      if (ch === ":") {
+        // If ":" is followed by a value (after optional whitespace), treat as separator.
+        let j = i + 1;
+        while (j < len && isWS(s[j])) j++;
+        if (isValueStart(s[j], j)) break;
+      }
+      i++;
+    }
+    return s.slice(start, i);
+  }
+
+  function readString() {
+    if (s[i] !== "'") error("Expected string");
+    i++; // skip '
+    let out = "";
+    while (i < len) {
+      const ch = s[i];
+      if (ch === "'") {
+        i++;
+        return out;
+      }
+      if (ch === "\\") {
+        const next = s[i + 1];
+        if (next === "'" || next === "\\") {
+          out += next;
+          i += 2;
+          continue;
+        }
+      }
+      out += ch;
+      i++;
+    }
+    error("Unterminated string");
+  }
+
+  function readNumber() {
+    const start = i;
+    if (s[i] === "-") i++;
+    while (i < len && s[i] >= "0" && s[i] <= "9") i++;
+    if (s[i] === ".") {
+      i++;
+      while (i < len && s[i] >= "0" && s[i] <= "9") i++;
+    }
+    const raw = s.slice(start, i);
+    const n = Number(raw);
+    if (Number.isNaN(n)) error("Invalid number");
+    return n;
+  }
+
+  function readExprUntil(delims) {
+    // Read raw expression until encountering a delimiter (one of delims) at depth 0.
+    // This keeps parsing fast and leaves expression semantics to runtime.
+    let depthParen = 0;
+    let depthBrack = 0;
+    let depthBrace = 0;
+    let hadParen = false;
+    const start = i;
+    while (i < len) {
+      const ch = s[i];
+      if (ch === "'" ) {
+        // skip strings inside expressions
+        i++; while (i < len && s[i] !== "'") {
+          if (s[i] === "\\" && i + 1 < len) i += 2; else i++;
+        }
+        if (s[i] === "'") i++;
+        continue;
+      }
+      if (ch === "(" ) {
+        depthParen++;
+        hadParen = true;
+      } else if (ch === ")") {
+        if (depthParen > 0) {
+          depthParen--;
+          if (depthParen === 0 && hadParen) {
+            i++;
+            continue;
+          }
+        }
+      }
+      else if (ch === "[") depthBrack++;
+      else if (ch === "]") depthBrack = Math.max(0, depthBrack - 1);
+      else if (ch === "{") depthBrace++;
+      else if (ch === "}") depthBrace = Math.max(0, depthBrace - 1);
+
+      if (depthParen === 0 && depthBrack === 0 && depthBrace === 0) {
+        if (delims.includes(ch)) {
+          if (ch === ")") {
+            // If followed by chaining, treat ')' as part of the expression.
+            let j = i + 1;
+            while (j < len && isWS(s[j])) j++;
+            const next = s[j];
+            if (next === "." || next === "?" || next === "[" || next === "(") {
+              i++;
+              continue;
+            }
+          }
+          break;
+        }
+      }
+      i++;
+    }
+    return s.slice(start, i).trim();
+  }
+
+  function readBracedRaw() {
+    if (s[i] !== "{") error("Expected '{' block");
+    i++; // skip '{'
+    const start = i;
+    let depth = 1;
+    while (i < len) {
+      const ch = s[i];
+      if (ch === "'") {
+        i++; while (i < len && s[i] !== "'") {
+          if (s[i] === "\\" && i + 1 < len) i += 2; else i++;
+        }
+        if (s[i] === "'") i++;
+        continue;
+      }
+      if (ch === "{") depth++;
+      else if (ch === "}") depth--;
+      if (depth === 0) {
+        const raw = s.slice(start, i).trim();
+        i++; // consume '}'
+        return raw;
+      }
+      i++;
+    }
+    error("Unterminated '{' block");
+  }
+
+  function parseValue() {
+    skipWS();
+    const ch = s[i];
+    if (ch === "'") return { kind: "value", value: readString() };
+    if (ch === "-" || (ch >= "0" && ch <= "9")) return { kind: "value", value: readNumber() };
+    if (ch === "@") {
+      i++;
+      return { kind: "expr", expr: { raw: readExprUntil([",", ")", "}"]) } };
+    }
+    if (s.startsWith("true", i)) { i += 4; return { kind: "value", value: true }; }
+    if (s.startsWith("false", i)) { i += 5; return { kind: "value", value: false }; }
+    if (s.startsWith("null", i)) { i += 4; return { kind: "value", value: null }; }
+    error("Unexpected value");
+  }
+
+  function parseProp(delims) {
+    skipWS();
+    const exprDelims = delims.includes(",") ? delims : [...delims, ","];
+    if (s[i] === "!") {
+      i++;
+      const eventName = readIdent();
+      skipWS();
+      const body = readBracedRaw();
+      return { kind: "event", key: eventName, expr: { raw: body } };
+    }
+    const key = readPropKey();
+    skipWS();
+    if (s[i] === "?" && s[i + 1] === "=") {
+      i += 2;
+      const raw = readExprUntil(exprDelims);
+      return { kind: "bool", key, expr: { raw } };
+    }
+    if (s[i] === "=") {
+      i++;
+      skipWS();
+      if (s[i] === "{" && key.startsWith("on:")) {
+        const body = readBracedRaw();
+        return { kind: "event", key, expr: { raw: body } };
+      }
+      const raw = readExprUntil(exprDelims);
+      return { kind: "expr", key, expr: { raw } };
+    }
+    if (s[i] === ":") {
+      i++;
+      skipWS();
+      if (s[i] === "{") {
+        const body = readBracedRaw();
+        return { kind: "event", key, expr: { raw: body } };
+      }
+      const val = parseValue();
+      return { kind: val.kind, key, value: val.value, expr: val.expr };
+    }
+    // bare boolean true prop (present implies true)
+    return { kind: "value", key, value: true };
+  }
+
+  function parsePropsInline(stopChars) {
+    const props = [];
+    while (i < len) {
+      skipWS();
+      if (i >= len) break;
+      // DEBUG: uncomment to trace
+      // console.log("parsePropsInline at", i, JSON.stringify(s.slice(i, i + 20)));
+      const ch = s[i];
+      if (stopChars.includes(ch)) break;
+      // Props must start with an identifier or event shorthand.
+      if (!(isIdentStart(ch) || ch === "!")) break;
+      props.push(parseProp(stopChars));
+      skipWS();
+      if (s[i] === ",") i++;
+    }
+    return props;
+  }
+
+  function parsePropsParen() {
+    if (s[i] !== "(") error("Expected '('");
+    i++;
+    const props = parsePropsInline([")"]);
+    if (s[i] !== ")") error("Expected ')'");
+    i++;
+    return props;
+  }
+
+  function parseChildren() {
+    if (s[i] !== "{") error("Expected '{'");
+    i++;
+    const children = [];
+    while (i < len) {
+      skipWS();
+      if (s[i] === "}") { i++; break; }
+      children.push(parseNode());
+    }
+    return children;
+  }
+
+  function parseDirective() {
+    if (s[i] !== "#") error("Expected '#'");
+    const start = i;
+    i++;
+    const name = readIdent();
+    skipWS();
+    let args = "";
+    if (s[i] === "(") {
+      i++;
+      const start = i;
+      let depth = 1;
+      while (i < len && depth > 0) {
+        const ch = s[i];
+        if (ch === "'") {
+          i++; while (i < len && s[i] !== "'") {
+            if (s[i] === "\\" && i + 1 < len) i += 2; else i++;
+          }
+          if (s[i] === "'") i++;
+          continue;
+        }
+        if (ch === "(") depth++;
+        else if (ch === ")") depth--;
+        if (depth === 0) break;
+        i++;
+      }
+      args = s.slice(start, i).trim();
+      if (s[i] === ")") i++;
+    }
+    skipWS();
+    let children = [];
+    if (s[i] === "{") children = parseChildren();
+    return { type: "directive", name, args, children, start, end: i };
+  }
+
+  function parseTextNode() {
+    const start = i;
+    const ident = readIdent();
+    if (ident !== "text") error("Unknown keyword");
+    skipWS();
+    const value = readString();
+    return { type: "text", value, start, end: i };
+  }
+
+  function parseExprNode() {
+    if (s[i] !== "@") error("Expected '@'");
+    const start = i;
+    i++;
+    const raw = readExprUntil(["}", "\n"]);
+    return { type: "expr", value: { raw }, start, end: i };
+  }
+
+  function parseTagNode() {
+    const start = i;
+    const name = readIdent();
+    skipWS();
+    let props = [];
+    if (s[i] === "(") {
+      props = parsePropsParen();
+      skipWS();
+    } else if (s[i] !== "{" && s[i] !== "}" && i < len) {
+      // inline props until '{' or '}' or end
+      props = parsePropsInline(["{", "}"]);
+      skipWS();
+    }
+    let children = [];
+    if (s[i] === "{") children = parseChildren();
+    return { type: "tag", name, props, children, start, end: i };
+  }
+
+  function parseNode() {
+    skipWS();
+    const ch = s[i];
+    if (ch === "#") return parseDirective();
+    if (ch === "@") return parseExprNode();
+    if (isIdentStart(ch)) {
+      // 'text' keyword or tag
+      const save = i;
+      const ident = readIdent();
+      i = save;
+      if (ident === "text") return parseTextNode();
+      return parseTagNode();
+    }
+    error("Unexpected token");
+  }
+
+  const body = [];
+  while (i < len) {
+    skipWS();
+    if (i >= len) break;
+    body.push(parseNode());
+  }
+
+  return { type: "document", body, start: 0, end: len };
+}
+
+export function parseUnitsOrThrow(input) {
+  return parseUnits(input);
+}

package/units-print.js

@@ -0,0 +1,63 @@
+import { parseUnits } from "./units-parser.js";
+
+function escapeString(value) {
+  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+
+function printProp(prop) {
+  if (prop.kind === "event") {
+    if (prop.key.startsWith("on:")) return `${prop.key}={ ${prop.expr.raw} }`;
+    return `!${prop.key} { ${prop.expr.raw} }`;
+  }
+  if (prop.kind === "bool") {
+    const raw = prop.expr.raw.startsWith("@") ? prop.expr.raw.slice(1) : prop.expr.raw;
+    return `${prop.key}?=@${raw}`;
+  }
+  if (prop.kind === "expr") {
+    const raw = prop.expr.raw.startsWith("@") ? prop.expr.raw.slice(1) : prop.expr.raw;
+    return `${prop.key}=@${raw}`;
+  }
+  if (prop.kind === "value") {
+    const v = prop.value;
+    if (typeof v === "string") return `${prop.key}:'${escapeString(v)}'`;
+    if (v === null) return `${prop.key}:null`;
+    return `${prop.key}:${String(v)}`;
+  }
+  return "";
+}
+
+const PRINT_WIDTH = Number(process.env.UNITS_PRINT_WIDTH || process.env.RDL_PRINT_WIDTH || 100);
+
+function printNode(node, indent) {
+  const pad = "  ".repeat(indent);
+  if (node.type === "text") return `${pad}text '${escapeString(node.value)}'`;
+  if (node.type === "expr") return `${pad}@${node.value.raw}`;
+  if (node.type === "directive") {
+    const args = node.args ? ` (${node.args})` : "";
+    if (!node.children || node.children.length === 0) return `${pad}#${node.name}${args}`;
+    const inner = node.children.map((n) => printNode(n, indent + 1)).join("\n");
+    return `${pad}#${node.name}${args} {\n${inner}\n${pad}}`;
+  }
+  if (node.type === "tag") {
+    let props = "";
+    if (node.props && node.props.length) {
+      const parts = node.props.map(printProp);
+      const inline = ` (${parts.join(", ")})`;
+      if ((pad.length + node.name.length + inline.length) > PRINT_WIDTH && parts.length > 1) {
+        const inner = parts.map((p) => `${pad}  ${p}`).join(",\n");
+        props = ` (\n${inner}\n${pad})`;
+      } else {
+        props = inline;
+      }
+    }
+    if (!node.children || node.children.length === 0) return `${pad}${node.name}${props}`;
+    const inner = node.children.map((n) => printNode(n, indent + 1)).join("\n");
+    return `${pad}${node.name}${props} {\n${inner}\n${pad}}`;
+  }
+  return "";
+}
+
+export function formatUnits(source) {
+  const ast = parseUnits(source);
+  return ast.body.map((n) => printNode(n, 0)).join("\n") + "\n";
+}

package/units-runtime.js

@@ -0,0 +1,247 @@
+// React renderer for Units AST.
+// Requires React as a peer dependency.
+
+import React from "react";
+
+export function createUnitsEvaluator() {
+  const cache = new Map();
+  return function evalExpr(raw, scope, locals) {
+    const key = raw;
+    let fn = cache.get(key);
+    if (!fn) {
+      // Allow a simple := transform inside set(...) calls.
+      let normalized = raw.replace(/@\(/g, "(");
+      normalized = normalized.replace(/@([A-Za-z_$][\w.$]*)/g, "$1");
+      const transformed = normalized.replace(
+        /set\s*\(\s*([A-Za-z_$][\w.$]*)\s*:=/g,
+        "set('$1',",
+      );
+      fn = new Function(
+        "scope",
+        "locals",
+        "event",
+        "set",
+        `with(scope){with(locals||{}){return (${transformed});}}`,
+      );
+      cache.set(key, fn);
+    }
+    return fn(scope, locals || {}, locals?.event, locals?.set || scope?.set);
+  };
+}
+
+export function renderUnits(ast, scope, options = {}) {
+  const evalExpr = options.evalExpr || createUnitsEvaluator();
+  const components = options.components || {};
+  const slots = options.slots || {};
+  const set = options.set || scope?.set || (() => {});
+
+  function splitInterpolations(value) {
+    const text = String(value ?? "");
+    const parts = [];
+    if (!text.includes("@{")) return [{ type: "text", value: text }];
+    let i = 0;
+    while (i < text.length) {
+      const idx = text.indexOf("@{", i);
+      if (idx === -1) {
+        if (i < text.length) parts.push({ type: "text", value: text.slice(i) });
+        break;
+      }
+      if (idx > i) parts.push({ type: "text", value: text.slice(i, idx) });
+      let j = idx + 2;
+      let depth = 1;
+      while (j < text.length) {
+        const ch = text[j];
+        if (ch === "'" || ch === "\"") {
+          const quote = ch;
+          j++;
+          while (j < text.length) {
+            const qch = text[j];
+            if (qch === "\\") {
+              j += 2;
+              continue;
+            }
+            if (qch === quote) {
+              j++;
+              break;
+            }
+            j++;
+          }
+          continue;
+        }
+        if (ch === "{") depth++;
+        else if (ch === "}") depth--;
+        if (depth === 0) break;
+        j++;
+      }
+      if (depth !== 0) {
+        parts.push({ type: "text", value: text.slice(idx) });
+        break;
+      }
+      const expr = text.slice(idx + 2, j).trim();
+      parts.push({ type: "expr", value: expr });
+      i = j + 1;
+    }
+    return parts;
+  }
+
+  function renderText(value, locals) {
+    const parts = splitInterpolations(value);
+    if (parts.length === 1 && parts[0].type === "text") return parts[0].value;
+    return parts.map((part) => {
+      if (part.type === "text") return part.value;
+      return String(evalExpr(part.value, scope, locals));
+    });
+  }
+
+  function pushChild(out, value) {
+    if (Array.isArray(value)) out.push(...value);
+    else out.push(value);
+  }
+
+  function renderNode(node, locals) {
+    if (!node) return null;
+    if (node.type === "text") return renderText(node.value, locals);
+    if (node.type === "expr") return evalExpr(node.value.raw, scope, locals);
+    if (node.type === "directive") return renderDirective(node, locals);
+    if (node.type === "tag") return renderTag(node, locals);
+    return null;
+  }
+
+  function renderDirective(node, locals) {
+    const name = node.name;
+    const args = node.args || "";
+    if (name === "for") {
+      const m = args.match(
+        /^\s*([A-Za-z_$][\w$]*)\s*(?:,\s*([A-Za-z_$][\w$]*))?\s+in\s+(.+)$/,
+      );
+      if (!m) return null;
+      const itemName = m[1];
+      const idxName = m[2] || "index";
+      const listExpr = m[3].trim();
+      const list = evalExpr(listExpr, scope, locals) || [];
+      const out = [];
+      for (let idx = 0; idx < list.length; idx++) {
+        const childLocals = {
+          ...locals,
+          [itemName]: list[idx],
+          [idxName]: idx,
+        };
+        out.push(renderChildren(node.children, childLocals));
+      }
+      return out;
+    }
+    if (name === "slot") {
+      const slotName = args.trim();
+      const slot = slots[slotName];
+      if (slot == null) return null;
+      return typeof slot === "function" ? slot(locals) : slot;
+    }
+    if (name === "key" || name === "elif" || name === "else") {
+      return null;
+    }
+    return renderChildren(node.children, locals);
+  }
+
+  function renderTag(node, locals) {
+    const props = {};
+    const eventHandlers = {};
+    for (const prop of node.props || []) {
+      if (prop.kind === "value") props[prop.key] = prop.value;
+      else if (prop.kind === "expr")
+        props[prop.key] = evalExpr(prop.expr.raw, scope, locals);
+      else if (prop.kind === "bool") {
+        const v = evalExpr(prop.expr.raw, scope, locals);
+        if (v) props[prop.key] = true;
+      } else if (prop.kind === "event") {
+        const eventName = prop.key.startsWith("on:")
+          ? prop.key.slice(3)
+          : prop.key;
+        const handler = (event) => {
+          const handlerLocals = { ...locals, event, set };
+          return evalExpr(prop.expr.raw, scope, handlerLocals);
+        };
+        eventHandlers[`on${eventName[0].toUpperCase()}${eventName.slice(1)}`] =
+          handler;
+      }
+    }
+
+    const children = renderChildren(node.children, locals);
+    const Component = components[node.name] || node.name;
+    const elProps = { ...props, ...eventHandlers };
+    if (typeof Component !== "string" && elProps.__scope == null) {
+      elProps.__scope = scope;
+    }
+    return React.createElement(
+      Component,
+      elProps,
+      ...(Array.isArray(children) ? children : [children]),
+    );
+  }
+
+  function renderChildren(children, locals) {
+    const out = [];
+    for (let idx = 0; idx < (children || []).length; idx++) {
+      const child = children[idx];
+      if (child.type === "directive" && child.name === "key") {
+        const next = children[idx + 1];
+        if (next && next.type === "tag") {
+          const key = evalExpr(child.args || "", scope, locals);
+          const rendered = renderNode(
+            {
+              ...next,
+              props: [
+                ...(next.props || []),
+                { kind: "value", key: "key", value: key },
+              ],
+            },
+            locals,
+          );
+          out.push(rendered);
+          idx++;
+          continue;
+        }
+      }
+      if (child.type === "directive" && child.name === "if") {
+        let matched = false;
+        if (evalExpr(child.args || "", scope, locals)) {
+          pushChild(out, renderChildren(child.children, locals));
+          matched = true;
+        }
+
+        let next = idx + 1;
+        while (next < children.length && children[next].type === "directive") {
+          if (children[next].name === "elif") {
+            if (
+              !matched &&
+              evalExpr(children[next].args || "", scope, locals)
+            ) {
+              pushChild(out, renderChildren(children[next].children, locals));
+              matched = true;
+            }
+            next++;
+            continue;
+          } else if (children[next].name === "else") {
+            if (!matched) {
+              pushChild(out, renderChildren(children[next].children, locals));
+              matched = true;
+            }
+            next++;
+            break;
+          } else {
+            break;
+          }
+        }
+        if (!matched) {
+          out.push(null);
+        }
+        idx = next - 1;
+        continue;
+      }
+      pushChild(out, renderNode(child, locals));
+    }
+    return out;
+  }
+
+  if (ast.type === "document") return renderChildren(ast.body, {});
+  return renderNode(ast, {});
+}