macroforge 0.1.79 → 0.1.80

package/README.md

@@ -5,9 +5,13 @@ TypeScript macro expansion engine - write compile-time macros in Rust
 [![Crates.io](https://img.shields.io/crates/v/macroforge_ts.svg)](https://crates.io/crates/macroforge_ts)
 [![Documentation](https://docs.rs/macroforge_ts/badge.svg)](https://docs.rs/macroforge_ts)
 
+## Overview
+
 This crate provides a TypeScript macro expansion engine that brings Rust-like derive macros to
-TypeScript. It is designed to be used via NAPI bindings from Node.js, enabling compile-time code
-generation for TypeScript projects.
+TypeScript. It supports multiple output targets via feature flags:
+
+- `wasm`: (Default) Universal WebAssembly module via wasm-bindgen for browser and edge environments.
+- `node`: Optional native Node.js bindings via NAPI-RS.
 
 ## Overview
 
@@ -19,31 +23,30 @@ concrete implementations. For example, a class decorated with `@derive(Debug, Cl
 
 The crate is organized into several key components:
 
-- **NAPI Bindings** (`NativePlugin`, `expand_sync`, `transform_sync`): Entry points for Node.js
-- **Position Mapping** (`NativePositionMapper`, `NativeMapper`): Bidirectional source mapping for
-  IDE integration
-- **Macro Host** (`host` module): Core expansion engine with registry and dispatcher
-- **Built-in Macros** (`builtin` module): Standard derive macros (Debug, Clone, Serialize, etc.)
-
-## Performance Considerations
+- **Unified API** (`api` module): An output-agnostic trait-based interface (`MacroforgeApi`) that
+  defines all macro operations.
+- **Target Bindings**:
+  - `bindings_napi`: Node.js specific entry points using NAPI-RS.
+  - `bindings_wasm`: Universal entry points using `wasm-bindgen`.
+- **Position Mapping** (`api_types::SourceMappingResult`): Bidirectional source mapping for IDE
+  integration.
+- **Macro Host** (`host` module): Core expansion engine with registry and dispatcher.
+- **Built-in Macros** (`builtin` module): Standard derive macros (Debug, Clone, Serialize, etc.).
 
-- Uses a 32MB thread stack to prevent stack overflow during deep SWC AST recursion
-- Implements early bailout for files without `@derive` decorators
-- Caches expansion results keyed by filepath and version
-- Uses binary search for O(log n) position mapping lookups
+## Usage
 
-## Usage from Node.js
+### From Node.js
 
 ```javascript
-const { NativePlugin, expand_sync } = require('macroforge-ts');
-
-// Create a plugin instance with caching
-const plugin = new NativePlugin();
+const { expandSync } = require('macroforge');
+const result = expandSync(code, filepath, { keep_decorators: false });
+```
 
-// Process a file (uses cache if version matches)
-const result = plugin.process_file(filepath, code, { version: '1.0' });
+### From WASM
 
-// Or use the sync function directly
+```javascript
+import init, { expand_sync } from './pkg/macroforge_ts.js';
+await init();
 const result = expand_sync(code, filepath, { keep_decorators: false });
 ```
 
@@ -53,7 +56,7 @@ This crate re-exports several dependencies for convenience when writing custom m
 
 - `ts_syn`: TypeScript syntax types for AST manipulation
 - `macros`: Macro attributes and quote templates
-- `swc_core`, `swc_common`, `swc_ecma_ast`: SWC compiler infrastructure
+- `swc_core`, `swc_common`, `swc_ecma_ast`: SWC compatibility infrastructure
 
 ## Installation
 
@@ -61,41 +64,15 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-macroforge_ts = "0.1.38"
+macroforge_ts = "0.1.79"
 ```
 
 ## Key Exports
 
-### Structs
-
-- **`TransformResult`** - Result of transforming TypeScript code through the macro system.
-- **`MacroDiagnostic`** - A diagnostic message produced during macro expansion.
-- **`MappingSegmentResult`** - A segment mapping a range in the original source to a range in the
-  expanded source.
-- **`GeneratedRegionResult`** - A region in the expanded source that was generated by a macro.
-- **`SourceMappingResult`** - Complete source mapping information for a macro expansion.
-- **`ExpandResult`** - Result of expanding macros in TypeScript source code.
-- **`ImportSourceResult`** - Information about an imported identifier from a TypeScript module.
-- **`SyntaxCheckResult`** - Result of checking TypeScript syntax validity.
-- **`SpanResult`** - A span (range) in source code, represented as start position and length.
-- **`JsDiagnostic`** - A diagnostic from the TypeScript/JavaScript compiler or IDE.
-- ... and 8 more
-
 ### Functions
 
-- **`unchanged`** - Creates a no-op result with the original code unchanged.
-- **`new`** - Creates a new position mapper from source mapping data.
-- **`is_empty`** - Checks if this mapper has no mapping data.
-- **`original_to_expanded`** - Converts a position in the original source to the corresponding
-  position in expanded source.
-- **`expanded_to_original`** - Converts a position in the expanded source back to the original
-  source position.
-- **`generated_by`** - Returns the name of the macro that generated code at the given position.
-- **`map_span_to_original`** - Maps a span (start + length) from expanded source to original source.
-- **`map_span_to_expanded`** - Maps a span (start + length) from original source to expanded source.
-- **`is_in_generated`** - Checks if a position is inside macro-generated code.
-- **`new`** - Creates a new mapper wrapping the given source mapping.
-- ... and 23 more
+- **`__macroforge_ffi_free`** - Free a buffer allocated by an FFI function.
+- **`__macroforge_ffi_get_manifest`** - Returns the full MacroManifest as JSON via FFI.
 
 ## API Reference
 

package/js/buildtime/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * # Macroforge Buildtime Module
+ *
+ * Compile-time JavaScript evaluation — the Zig-comptime primitive for
+ * TypeScript. Annotate a top-level `const` or `function` declaration with
+ * `/** @buildtime *\/` and the macroforge build pass evaluates it in a
+ * sandboxed JS context, serializes the result, and splices a plain TS
+ * literal back into the module.
+ *
+ * ```ts
+ * /** @buildtime *\/
+ * const BUILT_AT = buildtime.time.iso();
+ *
+ * /** @buildtime *\/
+ * const SCHEMA = buildtime.fs.readJson("./schema.json");
+ *
+ * /** @buildtime *\/
+ * function generateValidators() {
+ *   const schema = buildtime.fs.readJson("./schema.json");
+ *   return schema.fields.map(f =>
+ *     `export function is_${f.name}(v: unknown): v is ${f.type} {
+ *        return typeof v === "${f.jsType}";
+ *      }`
+ *   ).join("\n");
+ * }
+ * ```
+ *
+ * ## Runtime behavior
+ *
+ * Every export from this module is a sentinel. Calling any of them at
+ * runtime throws — they should have been resolved by the macroforge
+ * build pass and no longer exist in the output. If you see the runtime
+ * error, the build pass is not running on this file.
+ *
+ * @module macroforge/buildtime
+ */
+export interface BuildtimeFs {
+    /** Read a file as UTF-8 text. Path is resolved relative to the file the
+     *  @buildtime declaration lives in. Throws if the path is not in the
+     *  `buildtime.capabilities.filesystem.read` allowlist. */
+    readText(path: string): string;
+    /** Read a file and parse its content as JSON. Same capability rules
+     *  as `readText`. */
+    readJson(path: string): unknown;
+    /** Return whether the path exists on disk. Counts as a read for
+     *  dependency tracking — if the file appears later, the cache
+     *  invalidates. */
+    exists(path: string): boolean;
+    /** Return the names of the entries in a directory, sorted. Counts as
+     *  a read. */
+    listDir(path: string): string[];
+}
+export interface BuildtimeCrypto {
+    /** SHA-256 of the input, lowercase hex. Pure — always allowed. */
+    sha256(input: string): string;
+    /** SHA-512 of the input, lowercase hex. Pure — always allowed. */
+    sha512(input: string): string;
+}
+export interface BuildtimeTime {
+    /** Current wall-clock time as an ISO 8601 string. Makes builds
+     *  non-deterministic — prefer recording a fixed timestamp if
+     *  determinism matters. */
+    now(): string;
+    /** Current wall-clock time in unix seconds. */
+    unix(): number;
+    /** Alias for {@link BuildtimeTime.now}. */
+    iso(): string;
+}
+export interface BuildtimeFlags {
+    /** True if the named flag was passed to the build (e.g. from a
+     *  `--define` argument or from `config.buildtime.flags`). */
+    has(flag: string): boolean;
+    /** Value of the named flag, or undefined if not set. */
+    get(flag: string): string | undefined;
+}
+export interface BuildtimeLocation {
+    /** Absolute path of the source file the @buildtime declaration
+     *  lives in. */
+    readonly file: string;
+    /** 1-based line number of the `/** @buildtime *\/` annotation. */
+    readonly line: number;
+    /** 1-based column number of the annotation. */
+    readonly column: number;
+}
+export interface Buildtime {
+    readonly fs: BuildtimeFs;
+    readonly crypto: BuildtimeCrypto;
+    readonly time: BuildtimeTime;
+    /** Environment variables the build was allowed to read. Populated
+     *  from `buildtime.capabilities.env` in macroforge.config.js. Reads
+     *  of variables not in the allowlist return `undefined`. */
+    readonly env: Record<string, string | undefined>;
+    readonly flags: BuildtimeFlags;
+    readonly location: BuildtimeLocation;
+}
+/**
+ * The compile-time API. Inside a `@buildtime` declaration, calls
+ * against this object are routed to native implementations. At
+ * runtime, every access throws — see module docs for why.
+ */
+export declare const buildtime: Buildtime;
+/**
+ * Re-export with the name `$buildtime` for users who prefer the macroforge
+ * convention of prefixing compile-time identifiers with `$`. Points at the
+ * same object.
+ */
+export declare const $buildtime: Buildtime;

package/js/buildtime/index.mjs

@@ -0,0 +1,65 @@
+// js/buildtime/index.ts
+var runtimeError = (method) => new Error(
+  `macroforge/buildtime.${method}: @buildtime APIs are only available inside @buildtime declarations evaluated by macroforge. If you're seeing this at runtime, the macroforge plugin is not installed or not running on this file.`
+);
+var buildtime = {
+  fs: {
+    readText(_path) {
+      throw runtimeError("fs.readText");
+    },
+    readJson(_path) {
+      throw runtimeError("fs.readJson");
+    },
+    exists(_path) {
+      throw runtimeError("fs.exists");
+    },
+    listDir(_path) {
+      throw runtimeError("fs.listDir");
+    }
+  },
+  crypto: {
+    sha256(_input) {
+      throw runtimeError("crypto.sha256");
+    },
+    sha512(_input) {
+      throw runtimeError("crypto.sha512");
+    }
+  },
+  time: {
+    now() {
+      throw runtimeError("time.now");
+    },
+    unix() {
+      throw runtimeError("time.unix");
+    },
+    iso() {
+      throw runtimeError("time.iso");
+    }
+  },
+  env: new Proxy(
+    {},
+    {
+      get(_target, _prop) {
+        throw runtimeError("env");
+      }
+    }
+  ),
+  flags: {
+    has(_flag) {
+      throw runtimeError("flags.has");
+    },
+    get(_flag) {
+      throw runtimeError("flags.get");
+    }
+  },
+  location: new Proxy({}, {
+    get(_target, _prop) {
+      throw runtimeError("location");
+    }
+  })
+};
+var $buildtime = buildtime;
+export {
+  $buildtime,
+  buildtime
+};

package/js/buildtime/index.ts

@@ -0,0 +1,176 @@
+/**
+ * # Macroforge Buildtime Module
+ *
+ * Compile-time JavaScript evaluation — the Zig-comptime primitive for
+ * TypeScript. Annotate a top-level `const` or `function` declaration with
+ * `/** @buildtime *\/` and the macroforge build pass evaluates it in a
+ * sandboxed JS context, serializes the result, and splices a plain TS
+ * literal back into the module.
+ *
+ * ```ts
+ * /** @buildtime *\/
+ * const BUILT_AT = buildtime.time.iso();
+ *
+ * /** @buildtime *\/
+ * const SCHEMA = buildtime.fs.readJson("./schema.json");
+ *
+ * /** @buildtime *\/
+ * function generateValidators() {
+ *   const schema = buildtime.fs.readJson("./schema.json");
+ *   return schema.fields.map(f =>
+ *     `export function is_${f.name}(v: unknown): v is ${f.type} {
+ *        return typeof v === "${f.jsType}";
+ *      }`
+ *   ).join("\n");
+ * }
+ * ```
+ *
+ * ## Runtime behavior
+ *
+ * Every export from this module is a sentinel. Calling any of them at
+ * runtime throws — they should have been resolved by the macroforge
+ * build pass and no longer exist in the output. If you see the runtime
+ * error, the build pass is not running on this file.
+ *
+ * @module macroforge/buildtime
+ */
+
+const runtimeError = (method: string) =>
+  new Error(
+    `macroforge/buildtime.${method}: @buildtime APIs are only available inside @buildtime declarations evaluated by macroforge. ` +
+      `If you're seeing this at runtime, the macroforge plugin is not installed or not running on this file.`,
+  );
+
+export interface BuildtimeFs {
+  /** Read a file as UTF-8 text. Path is resolved relative to the file the
+   *  @buildtime declaration lives in. Throws if the path is not in the
+   *  `buildtime.capabilities.filesystem.read` allowlist. */
+  readText(path: string): string;
+  /** Read a file and parse its content as JSON. Same capability rules
+   *  as `readText`. */
+  readJson(path: string): unknown;
+  /** Return whether the path exists on disk. Counts as a read for
+   *  dependency tracking — if the file appears later, the cache
+   *  invalidates. */
+  exists(path: string): boolean;
+  /** Return the names of the entries in a directory, sorted. Counts as
+   *  a read. */
+  listDir(path: string): string[];
+}
+
+export interface BuildtimeCrypto {
+  /** SHA-256 of the input, lowercase hex. Pure — always allowed. */
+  sha256(input: string): string;
+  /** SHA-512 of the input, lowercase hex. Pure — always allowed. */
+  sha512(input: string): string;
+}
+
+export interface BuildtimeTime {
+  /** Current wall-clock time as an ISO 8601 string. Makes builds
+   *  non-deterministic — prefer recording a fixed timestamp if
+   *  determinism matters. */
+  now(): string;
+  /** Current wall-clock time in unix seconds. */
+  unix(): number;
+  /** Alias for {@link BuildtimeTime.now}. */
+  iso(): string;
+}
+
+export interface BuildtimeFlags {
+  /** True if the named flag was passed to the build (e.g. from a
+   *  `--define` argument or from `config.buildtime.flags`). */
+  has(flag: string): boolean;
+  /** Value of the named flag, or undefined if not set. */
+  get(flag: string): string | undefined;
+}
+
+export interface BuildtimeLocation {
+  /** Absolute path of the source file the @buildtime declaration
+   *  lives in. */
+  readonly file: string;
+  /** 1-based line number of the `/** @buildtime *\/` annotation. */
+  readonly line: number;
+  /** 1-based column number of the annotation. */
+  readonly column: number;
+}
+
+export interface Buildtime {
+  readonly fs: BuildtimeFs;
+  readonly crypto: BuildtimeCrypto;
+  readonly time: BuildtimeTime;
+  /** Environment variables the build was allowed to read. Populated
+   *  from `buildtime.capabilities.env` in macroforge.config.js. Reads
+   *  of variables not in the allowlist return `undefined`. */
+  readonly env: Record<string, string | undefined>;
+  readonly flags: BuildtimeFlags;
+  readonly location: BuildtimeLocation;
+}
+
+/**
+ * The compile-time API. Inside a `@buildtime` declaration, calls
+ * against this object are routed to native implementations. At
+ * runtime, every access throws — see module docs for why.
+ */
+export const buildtime: Buildtime = {
+  fs: {
+    readText(_path: string): string {
+      throw runtimeError("fs.readText");
+    },
+    readJson(_path: string): unknown {
+      throw runtimeError("fs.readJson");
+    },
+    exists(_path: string): boolean {
+      throw runtimeError("fs.exists");
+    },
+    listDir(_path: string): string[] {
+      throw runtimeError("fs.listDir");
+    },
+  },
+  crypto: {
+    sha256(_input: string): string {
+      throw runtimeError("crypto.sha256");
+    },
+    sha512(_input: string): string {
+      throw runtimeError("crypto.sha512");
+    },
+  },
+  time: {
+    now(): string {
+      throw runtimeError("time.now");
+    },
+    unix(): number {
+      throw runtimeError("time.unix");
+    },
+    iso(): string {
+      throw runtimeError("time.iso");
+    },
+  },
+  env: new Proxy(
+    {},
+    {
+      get(_target, _prop): never {
+        throw runtimeError("env");
+      },
+    },
+  ),
+  flags: {
+    has(_flag: string): boolean {
+      throw runtimeError("flags.has");
+    },
+    get(_flag: string): string | undefined {
+      throw runtimeError("flags.get");
+    },
+  },
+  location: new Proxy({} as BuildtimeLocation, {
+    get(_target, _prop): never {
+      throw runtimeError("location");
+    },
+  }),
+};
+
+/**
+ * Re-export with the name `$buildtime` for users who prefer the macroforge
+ * convention of prefixing compile-time identifiers with `$`. Points at the
+ * same object.
+ */
+export const $buildtime = buildtime;

package/js/cli/svelte-check-wrapper.js

@@ -115,12 +115,32 @@ if (typeRegistryPath) {
     typeRegistryJson = fs.readFileSync(typeRegistryPath, "utf8");
   } catch {}
 }
+const declarativeRegistryPath =
+  process.env.MACROFORGE_DECLARATIVE_REGISTRY_PATH;
+let declarativeRegistryJson = void 0;
+if (declarativeRegistryPath) {
+  try {
+    declarativeRegistryJson = fs.readFileSync(declarativeRegistryPath, "utf8");
+  } catch {}
+}
 const plugin = new macros.NativePlugin();
 const expandOpts = {};
 if (macroConfigPath) expandOpts.configPath = macroConfigPath;
 if (typeRegistryJson) expandOpts.typeRegistryJson = typeRegistryJson;
+if (declarativeRegistryJson) {
+  expandOpts.declarativeRegistryJson = declarativeRegistryJson;
+}
 const tsSys = ts.sys;
 const origReadFile = tsSys.readFile.bind(tsSys);
+// Text-level fast path matching the tsc wrapper — covers derive macros
+// plus both sides of the declarative macro system (defining and consuming).
+function hasMacroMarkers(sourceText) {
+  if (!sourceText) return false;
+  if (sourceText.includes("@derive")) return true;
+  if (sourceText.includes("macroforge/rules")) return true;
+  if (sourceText.includes("import macro")) return true;
+  return false;
+}
 tsSys.readFile = (filePath, encoding) => {
   const content = origReadFile(filePath, encoding);
   if (content == null) return content;
@@ -128,7 +148,7 @@ tsSys.readFile = (filePath, encoding) => {
     if (
       (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) &&
       !filePath.endsWith(".d.ts") &&
-      content.includes("@derive")
+      hasMacroMarkers(content)
     ) {
       const result = plugin.processFile(filePath, content, expandOpts);
       return result.code || content;

package/js/cli/tsc-wrapper.js

@@ -108,6 +108,14 @@ if (typeRegistryPath) {
     typeRegistryJson = fs.readFileSync(typeRegistryPath, "utf8");
   } catch {}
 }
+const declarativeRegistryPath =
+  process.env.MACROFORGE_DECLARATIVE_REGISTRY_PATH;
+let declarativeRegistryJson = void 0;
+if (declarativeRegistryPath) {
+  try {
+    declarativeRegistryJson = fs.readFileSync(declarativeRegistryPath, "utf8");
+  } catch {}
+}
 const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
 if (configFile.error) {
   console.error(
@@ -134,8 +142,25 @@ const plugin = new macros.NativePlugin();
 const tscExpandOpts = {};
 if (macroConfigPath) tscExpandOpts.configPath = macroConfigPath;
 if (typeRegistryJson) tscExpandOpts.typeRegistryJson = typeRegistryJson;
+if (declarativeRegistryJson) {
+  tscExpandOpts.declarativeRegistryJson = declarativeRegistryJson;
+}
 const host = ts.createCompilerHost(options);
 const origGetSourceFile = host.getSourceFile.bind(host);
+// Text-level fast path: skip files that don't contain any macro markers.
+// Matches:
+//   - `@derive` (derive macros)
+//   - `macroforge/rules` (declarative-macro-defining files that
+//     `import { macroRules } from "macroforge/rules"`)
+//   - `import macro` inside a JSDoc comment (declarative-macro-consuming
+//     files that use `/** import macro { $name } from "./file" */`)
+function hasMacroMarkers(sourceText) {
+  if (!sourceText) return false;
+  if (sourceText.includes("@derive")) return true;
+  if (sourceText.includes("macroforge/rules")) return true;
+  if (sourceText.includes("import macro")) return true;
+  return false;
+}
 host.getSourceFile = (fileName, languageVersion, ...rest) => {
   try {
     if (
@@ -143,13 +168,20 @@ host.getSourceFile = (fileName, languageVersion, ...rest) => {
       !fileName.endsWith(".d.ts")
     ) {
       const sourceText = ts.sys.readFile(fileName);
-      if (sourceText && sourceText.includes("@derive")) {
+      if (hasMacroMarkers(sourceText)) {
         const result = plugin.processFile(fileName, sourceText, tscExpandOpts);
         const text = result.code || sourceText;
         return ts.createSourceFile(fileName, text, languageVersion, true);
       }
     }
-  } catch {}
+  } catch (e) {
+    if (process.env.MACROFORGE_DEBUG_WRAPPER) {
+      console.error(
+        `[macroforge tsc wrapper] expand failed for ${fileName}:`,
+        e,
+      );
+    }
+  }
   return origGetSourceFile(fileName, languageVersion, ...rest);
 };
 const program = ts.createProgram(parsed.fileNames, options, host);

package/js/rules/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * # Macroforge Rules Module
+ *
+ * Declarative pattern-matching macros for TypeScript. Define macros with
+ * `` const $name = macroRules`...` ``, invoke them as `$name(args)`, and the
+ * macroforge build pass rewrites call sites at compile time.
+ *
+ * Example:
+ *
+ * ```typescript
+ * import { macroRules } from "macroforge/rules";
+ *
+ * const $vec = macroRules`
+ *   () => []
+ *
+ *   ($($x:Expr),+ $(,)?) => {
+ *     const __v = [];
+ *     $( __v.push($x); )+
+ *     __v
+ *   }
+ * `;
+ *
+ * const empty = $vec();
+ * const xs = $vec(1, 2, 3);
+ * ```
+ *
+ * ## Runtime behavior
+ *
+ * `macroRules` is a sentinel tag function. It throws at runtime if the
+ * macroforge build pass is not installed — if you see the runtime error,
+ * your build toolchain is not running macroforge on this file.
+ *
+ * @module macroforge/rules
+ */
+/**
+ * A macro invocation — a function that takes any arguments and may produce
+ * any value. The exact return type depends on the macro body; for accurate
+ * types, the macroforge build pass is responsible for erasing the macro
+ * definition and inlining the expansion at each call site. Only this
+ * placeholder shape is visible to the TypeScript type checker.
+ */
+export type MacroInvocation = (...args: any[]) => any;
+/**
+ * The macro definition tag function.
+ *
+ * At build time, `` const $name = macroRules`...` `` is recognized by
+ * macroforge, the template body is parsed as a macro definition, and the
+ * declaration is erased from the output. Call sites of `$name(...)` are
+ * rewritten in place with the matching arm's body.
+ *
+ * The return type is a generic callable, so TypeScript lets users invoke
+ * `$name(...)` without complaint. At runtime (if the build pass did not
+ * run) the tag itself throws — any caller would already have seen the
+ * compile-time rewrite.
+ */
+export declare function macroRules(_strings: TemplateStringsArray, ..._values: unknown[]): MacroInvocation;
+/**
+ * Configuration for a macro's reverse-monomorphization behavior.
+ *
+ * Currently a type-only declaration — the object form
+ * `macroRules({ expand, runtime, call, mode })` is part of the reverse-mono
+ * follow-up and is not yet wired through the build pass. The type is
+ * exported now so consumer code can start using the shape.
+ */
+export interface MacroConfig {
+    /**
+     * Controls how the macro emits in dev vs. prod builds.
+     *
+     * - `"auto"` (default): dev expands inline, prod shares runtime when safe.
+     * - `"expand-only"`: always expand inline at every call site.
+     * - `"share-only"`: always emit calls to a shared runtime helper.
+     * - `"share-anyway"`: share even past the megamorphism threshold.
+     */
+    readonly mode?: "auto" | "expand-only" | "share-only" | "share-anyway";
+    /**
+     * The expand-form macro template (used for dev + `expand-only` + type-check).
+     */
+    readonly expand?: unknown;
+    /**
+     * The shared runtime body, emitted once per module when the macro
+     * is in a sharing mode.
+     */
+    readonly runtime?: string;
+    /**
+     * The call-form template that replaces call sites when the macro
+     * is in a sharing mode.
+     */
+    readonly call?: unknown;
+    /**
+     * Above this count of distinct types calling the shared runtime,
+     * the megamorphism analyzer emits a warning. Default: 4.
+     */
+    readonly megamorphismThreshold?: number;
+}

package/js/rules/index.mjs

@@ -0,0 +1,9 @@
+// js/rules/index.ts
+function macroRules(_strings, ..._values) {
+  throw new Error(
+    "macroforge/rules: macros are compile-time only \u2014 they should have been erased by the macroforge build pass. If you're seeing this at runtime, the macroforge plugin is not installed or not running on this file."
+  );
+}
+export {
+  macroRules
+};

package/js/rules/index.ts

@@ -0,0 +1,109 @@
+/**
+ * # Macroforge Rules Module
+ *
+ * Declarative pattern-matching macros for TypeScript. Define macros with
+ * `` const $name = macroRules`...` ``, invoke them as `$name(args)`, and the
+ * macroforge build pass rewrites call sites at compile time.
+ *
+ * Example:
+ *
+ * ```typescript
+ * import { macroRules } from "macroforge/rules";
+ *
+ * const $vec = macroRules`
+ *   () => []
+ *
+ *   ($($x:Expr),+ $(,)?) => {
+ *     const __v = [];
+ *     $( __v.push($x); )+
+ *     __v
+ *   }
+ * `;
+ *
+ * const empty = $vec();
+ * const xs = $vec(1, 2, 3);
+ * ```
+ *
+ * ## Runtime behavior
+ *
+ * `macroRules` is a sentinel tag function. It throws at runtime if the
+ * macroforge build pass is not installed — if you see the runtime error,
+ * your build toolchain is not running macroforge on this file.
+ *
+ * @module macroforge/rules
+ */
+
+/**
+ * A macro invocation — a function that takes any arguments and may produce
+ * any value. The exact return type depends on the macro body; for accurate
+ * types, the macroforge build pass is responsible for erasing the macro
+ * definition and inlining the expansion at each call site. Only this
+ * placeholder shape is visible to the TypeScript type checker.
+ */
+export type MacroInvocation = (...args: any[]) => any;
+
+/**
+ * The macro definition tag function.
+ *
+ * At build time, `` const $name = macroRules`...` `` is recognized by
+ * macroforge, the template body is parsed as a macro definition, and the
+ * declaration is erased from the output. Call sites of `$name(...)` are
+ * rewritten in place with the matching arm's body.
+ *
+ * The return type is a generic callable, so TypeScript lets users invoke
+ * `$name(...)` without complaint. At runtime (if the build pass did not
+ * run) the tag itself throws — any caller would already have seen the
+ * compile-time rewrite.
+ */
+export function macroRules(
+  _strings: TemplateStringsArray,
+  ..._values: unknown[]
+): MacroInvocation {
+  throw new Error(
+    "macroforge/rules: macros are compile-time only — they should have been erased by the macroforge build pass. " +
+      "If you're seeing this at runtime, the macroforge plugin is not installed or not running on this file.",
+  );
+}
+
+/**
+ * Configuration for a macro's reverse-monomorphization behavior.
+ *
+ * Currently a type-only declaration — the object form
+ * `macroRules({ expand, runtime, call, mode })` is part of the reverse-mono
+ * follow-up and is not yet wired through the build pass. The type is
+ * exported now so consumer code can start using the shape.
+ */
+export interface MacroConfig {
+  /**
+   * Controls how the macro emits in dev vs. prod builds.
+   *
+   * - `"auto"` (default): dev expands inline, prod shares runtime when safe.
+   * - `"expand-only"`: always expand inline at every call site.
+   * - `"share-only"`: always emit calls to a shared runtime helper.
+   * - `"share-anyway"`: share even past the megamorphism threshold.
+   */
+  readonly mode?: "auto" | "expand-only" | "share-only" | "share-anyway";
+
+  /**
+   * The expand-form macro template (used for dev + `expand-only` + type-check).
+   */
+  readonly expand?: unknown;
+
+  /**
+   * The shared runtime body, emitted once per module when the macro
+   * is in a sharing mode.
+   */
+  readonly runtime?: string;
+
+  /**
+   * The call-form template that replaces call sites when the macro
+   * is in a sharing mode.
+   */
+  readonly call?: unknown;
+
+  /**
+   * Above this count of distinct types calling the shared runtime,
+   * the megamorphism analyzer emits a warning. Default: 4.
+   */
+  readonly megamorphismThreshold?: number;
+}

package/package.json

@@ -1,67 +1,79 @@
 {
-  "author": "macroforge contributors",
-  "bugs": {
-    "url": "https://github.com/macroforge-ts/macroforge-ts/issues"
-  },
-  "description": "TypeScript macro expansion engine powered by Rust, Oxc, and WebAssembly",
-  "exports": {
-    ".": {
-      "types": "./pkg/macroforge_ts.d.ts",
-      "require": "./pkg/macroforge_ts.js",
-      "default": "./pkg/macroforge_ts.js"
+    "author": "macroforge contributors",
+    "bugs": {
+        "url": "https://github.com/macroforge-ts/macroforge-ts/issues"
     },
-    "./reexports": {
-      "types": "./js/reexports/index.d.ts",
-      "import": "./js/reexports/index.mjs",
-      "default": "./js/reexports/index.mjs"
+    "description": "TypeScript macro expansion engine powered by Rust, Oxc, and WebAssembly",
+    "exports": {
+        ".": {
+            "require": "./pkg/macroforge_ts.js",
+            "types": "./pkg/macroforge_ts.d.ts",
+            "default": "./pkg/macroforge_ts.js"
+        },
+        "./buildtime": {
+            "import": "./js/buildtime/index.mjs",
+            "types": "./js/buildtime/index.d.ts",
+            "default": "./js/buildtime/index.mjs"
+        },
+        "./reexports": {
+            "import": "./js/reexports/index.mjs",
+            "types": "./js/reexports/index.d.ts",
+            "default": "./js/reexports/index.mjs"
+        },
+        "./reexports/effect": {
+            "import": "./js/reexports/effect.mjs",
+            "types": "./js/reexports/effect.d.ts",
+            "default": "./js/reexports/effect.mjs"
+        },
+        "./rules": {
+            "import": "./js/rules/index.mjs",
+            "types": "./js/rules/index.d.ts",
+            "default": "./js/rules/index.mjs"
+        },
+        "./serde": {
+            "import": "./js/serde/index.mjs",
+            "types": "./js/serde/index.d.ts",
+            "default": "./js/serde/index.mjs"
+        },
+        "./traits": {
+            "import": "./js/traits/index.mjs",
+            "types": "./js/traits/index.d.ts",
+            "default": "./js/traits/index.mjs"
+        }
     },
-    "./reexports/effect": {
-      "types": "./js/reexports/effect.d.ts",
-      "import": "./js/reexports/effect.mjs",
-      "default": "./js/reexports/effect.mjs"
+    "files": [
+        "js",
+        "pkg"
+    ],
+    "homepage": "https://github.com/macroforge-ts/macroforge-ts#readme",
+    "keywords": [
+        "typescript",
+        "macros",
+        "derive",
+        "codegen",
+        "oxc",
+        "wasm",
+        "webassembly"
+    ],
+    "license": "MIT",
+    "main": "./pkg/macroforge_ts.js",
+    "name": "macroforge",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/macroforge-ts/macroforge-ts.git"
     },
-    "./serde": {
-      "types": "./js/serde/index.d.ts",
-      "import": "./js/serde/index.mjs",
-      "default": "./js/serde/index.mjs"
+    "scripts": {
+        "build": "deno task build:wasm",
+        "build:buildtime": "deno run -A npm:esbuild js/buildtime/index.ts --bundle --outfile=js/buildtime/index.mjs --format=esm && deno run -A npm:typescript/tsc js/buildtime/index.ts --declaration --emitDeclarationOnly --outDir js/buildtime --lib ES2024 --skipLibCheck",
+        "build:js": "deno task build:serde && deno task build:traits && deno task build:rules && deno task build:buildtime",
+        "build:rules": "deno run -A npm:esbuild js/rules/index.ts --bundle --outfile=js/rules/index.mjs --format=esm && deno run -A npm:typescript/tsc js/rules/index.ts --declaration --emitDeclarationOnly --outDir js/rules --lib ES2024 --skipLibCheck",
+        "build:serde": "deno run -A npm:esbuild js/serde/index.ts --bundle --outfile=js/serde/index.mjs --format=esm && deno run -A npm:typescript/tsc js/serde/index.ts --declaration --emitDeclarationOnly --outDir js/serde --lib ES2024 --skipLibCheck",
+        "build:traits": "deno run -A npm:esbuild js/traits/index.ts --bundle --outfile=js/traits/index.mjs --format=esm && deno run -A npm:typescript/tsc js/traits/index.ts --declaration --emitDeclarationOnly --outDir js/traits --lib ES2024 --skipLibCheck",
+        "build:wasm": "deno install --node-modules-dir && deno task build:js && cargo build --release --target wasm32-unknown-unknown && deno run -A ../../tooling/scripts/bench.mjs --wasm-bindgen ../target/wasm32-unknown-unknown/release/macroforge_ts.wasm pkg",
+        "clean": "rm -rf pkg node_modules",
+        "cleanbuild": "deno task clean && deno task build"
     },
-    "./traits": {
-      "types": "./js/traits/index.d.ts",
-      "import": "./js/traits/index.mjs",
-      "default": "./js/traits/index.mjs"
-    }
-  },
-  "files": [
-    "js",
-    "pkg"
-  ],
-  "homepage": "https://github.com/macroforge-ts/macroforge-ts#readme",
-  "keywords": [
-    "typescript",
-    "macros",
-    "derive",
-    "codegen",
-    "oxc",
-    "wasm",
-    "webassembly"
-  ],
-  "license": "MIT",
-  "main": "./pkg/macroforge_ts.js",
-  "name": "macroforge",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/macroforge-ts/macroforge-ts.git"
-  },
-  "scripts": {
-    "build": "deno task build:wasm",
-    "build:js": "deno task build:serde && deno task build:traits",
-    "build:serde": "deno run -A npm:esbuild js/serde/index.ts --bundle --outfile=js/serde/index.mjs --format=esm && deno run -A npm:typescript/tsc js/serde/index.ts --declaration --emitDeclarationOnly --outDir js/serde --lib ES2024 --skipLibCheck",
-    "build:traits": "deno run -A npm:esbuild js/traits/index.ts --bundle --outfile=js/traits/index.mjs --format=esm && deno run -A npm:typescript/tsc js/traits/index.ts --declaration --emitDeclarationOnly --outDir js/traits --lib ES2024 --skipLibCheck",
-    "build:wasm": "deno install --node-modules-dir && deno task build:js && cargo build --release --target wasm32-unknown-unknown && deno run -A ../../tooling/scripts/bench.mjs --wasm-bindgen target/wasm32-unknown-unknown/release/macroforge_ts.wasm pkg",
-    "clean": "rm -rf pkg node_modules",
-    "cleanbuild": "deno task clean && deno task build"
-  },
-  "type": "commonjs",
-  "types": "./pkg/macroforge_ts.d.ts",
-  "version": "0.1.79"
+    "type": "commonjs",
+    "types": "./pkg/macroforge_ts.d.ts",
+    "version": "0.1.80"
 }

package/pkg/macroforge_ts.d.ts

@@ -1,8 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
 
+export function Clone(): void;
+
+export function Debug(): void;
+
+export function Default(): void;
+
 export function Derive(): void;
 
+export function Deserialize(): void;
+
+export function Hash(): void;
+
 export class NativeMapper {
     private constructor();
     free(): void;
@@ -36,6 +46,14 @@ export class NativePositionMapper {
     constructor(_mapping: any);
 }
 
+export function Ord(): void;
+
+export function PartialEq(): void;
+
+export function PartialOrd(): void;
+
+export function Serialize(): void;
+
 export function __macroforgeDebugDescriptors(): any;
 
 export function __macroforgeDebugGetModules(): any;
@@ -70,14 +88,31 @@ export function checkSyntax(code: string, filepath: string): any;
 
 export function clearConfigCache(): void;
 
+export function clearScanCache(): void;
+
 export function expandSync(code: string, filepath: string, options: any): any;
 
+/**
+ * Phase 17 — scan cache invalidation. WASM cannot access the
+ * filesystem, so there is no scan cache to invalidate on that
+ * target. These shims are here so the JS side of the plugin can
+ * call them uniformly across NAPI and WASM backends.
+ */
+export function invalidateScanCacheEntry(path: string): boolean;
+
 export function loadConfig(content: string, filepath: string): any;
 
 export function parseImportSources(code: string, filepath: string): any;
 
 export function scanProjectSync(root_dir: string, options: any): any;
 
+/**
+ * Register JS callbacks that bridge `buildtime.fs.*` to the host
+ * filesystem. Called once at startup by the Vite plugin (and any
+ * other JS host). Subsequent calls are ignored.
+ */
+export function setupBuildtimeFs(read_text: Function, exists: Function, list_dir: Function): void;
+
 /**
  * Register JS callbacks for resolving and running external (user-defined) macros.
  *

package/pkg/macroforge_ts.js

@@ -1,10 +1,35 @@
 /* @ts-self-types="./macroforge_ts.d.ts" */
 
+function Clone() {
+    wasm.Clone();
+}
+exports.Clone = Clone;
+
+function Debug() {
+    wasm.Debug();
+}
+exports.Debug = Debug;
+
+function Default() {
+    wasm.Default();
+}
+exports.Default = Default;
+
 function Derive() {
     wasm.Derive();
 }
 exports.Derive = Derive;
 
+function Deserialize() {
+    wasm.Deserialize();
+}
+exports.Deserialize = Deserialize;
+
+function Hash() {
+    wasm.Hash();
+}
+exports.Hash = Hash;
+
 class NativeMapper {
     static __wrap(ptr) {
         ptr = ptr >>> 0;
@@ -234,6 +259,26 @@ class NativePositionMapper {
 if (Symbol.dispose) NativePositionMapper.prototype[Symbol.dispose] = NativePositionMapper.prototype.free;
 exports.NativePositionMapper = NativePositionMapper;
 
+function Ord() {
+    wasm.Ord();
+}
+exports.Ord = Ord;
+
+function PartialEq() {
+    wasm.PartialEq();
+}
+exports.PartialEq = PartialEq;
+
+function PartialOrd() {
+    wasm.PartialOrd();
+}
+exports.PartialOrd = PartialOrd;
+
+function Serialize() {
+    wasm.Serialize();
+}
+exports.Serialize = Serialize;
+
 /**
  * @returns {any}
  */
@@ -571,6 +616,11 @@ function clearConfigCache() {
 }
 exports.clearConfigCache = clearConfigCache;
 
+function clearScanCache() {
+    wasm.clearScanCache();
+}
+exports.clearScanCache = clearScanCache;
+
 /**
  * @param {string} code
  * @param {string} filepath
@@ -590,6 +640,22 @@ function expandSync(code, filepath, options) {
 }
 exports.expandSync = expandSync;
 
+/**
+ * Phase 17 — scan cache invalidation. WASM cannot access the
+ * filesystem, so there is no scan cache to invalidate on that
+ * target. These shims are here so the JS side of the plugin can
+ * call them uniformly across NAPI and WASM backends.
+ * @param {string} path
+ * @returns {boolean}
+ */
+function invalidateScanCacheEntry(path) {
+    const ptr0 = passStringToWasm0(path, wasm.__wbindgen_malloc_command_export, wasm.__wbindgen_realloc_command_export);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.invalidateScanCacheEntry(ptr0, len0);
+    return ret !== 0;
+}
+exports.invalidateScanCacheEntry = invalidateScanCacheEntry;
+
 /**
  * @param {string} content
  * @param {string} filepath
@@ -642,6 +708,19 @@ function scanProjectSync(root_dir, options) {
 }
 exports.scanProjectSync = scanProjectSync;
 
+/**
+ * Register JS callbacks that bridge `buildtime.fs.*` to the host
+ * filesystem. Called once at startup by the Vite plugin (and any
+ * other JS host). Subsequent calls are ignored.
+ * @param {Function} read_text
+ * @param {Function} exists
+ * @param {Function} list_dir
+ */
+function setupBuildtimeFs(read_text, exists, list_dir) {
+    wasm.setupBuildtimeFs(read_text, exists, list_dir);
+}
+exports.setupBuildtimeFs = setupBuildtimeFs;
+
 /**
  * Register JS callbacks for resolving and running external (user-defined) macros.
  *
@@ -773,6 +852,13 @@ function __wbg_get_imports() {
             const ret = Object.entries(arg0);
             return ret;
         },
+        __wbg_from_741da0f916ab74aa: function(arg0) {
+            const ret = Array.from(arg0);
+            return ret;
+        },
+        __wbg_getRandomValues_3f44b700395062e5: function() { return handleError(function (arg0, arg1) {
+            globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
+        }, arguments); },
         __wbg_get_4848e350b40afc16: function(arg0, arg1) {
             const ret = arg0[arg1 >>> 0];
             return ret;
@@ -849,6 +935,18 @@ function __wbg_get_imports() {
             const ret = arg0.next();
             return ret;
         }, arguments); },
+        __wbg_now_88621c9c9a4f3ffc: function() {
+            const ret = Date.now();
+            return ret;
+        },
+        __wbg_now_e7c6795a7f81e10f: function(arg0) {
+            const ret = arg0.now();
+            return ret;
+        },
+        __wbg_performance_3fcf6e32a7e1ed0a: function(arg0) {
+            const ret = arg0.performance;
+            return ret;
+        },
         __wbg_prototypesetcall_3e05eb9545565046: function(arg0, arg1, arg2) {
             Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
         },
@@ -862,6 +960,22 @@ function __wbg_get_imports() {
             const ret = Reflect.set(arg0, arg1, arg2);
             return ret;
         }, arguments); },
+        __wbg_static_accessor_GLOBAL_THIS_a1248013d790bf5f: function() {
+            const ret = typeof globalThis === 'undefined' ? null : globalThis;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_GLOBAL_f2e0f995a21329ff: function() {
+            const ret = typeof global === 'undefined' ? null : global;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_SELF_24f78b6d23f286ea: function() {
+            const ret = typeof self === 'undefined' ? null : self;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
+        __wbg_static_accessor_WINDOW_59fd959c540fe405: function() {
+            const ret = typeof window === 'undefined' ? null : window;
+            return isLikeNone(ret) ? 0 : addToExternrefTable0(ret);
+        },
         __wbg_value_7f6052747ccf940f: function(arg0) {
             const ret = arg0.value;
             return ret;

package/pkg/macroforge_ts_bg.wasm.d.ts

@@ -1,6 +1,8 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const Default: () => void;
+export const __macroforgeRunDefault: (a: number, b: number) => [number, number, number, number];
 export const Derive: () => void;
 export const __macroforgeDebugDescriptors: () => [number, number, number];
 export const __macroforgeDebugGetModules: () => [number, number, number];
@@ -8,12 +10,12 @@ export const __macroforgeDebugLookup: (a: number, b: number, c: number, d: numbe
 export const __macroforgeGetMacroNames: () => [number, number, number];
 export const __macroforgeGetManifest: () => [number, number, number];
 export const __macroforgeIsMacroPackage: () => number;
-export const __macroforgeRunDeserialize: (a: number, b: number) => [number, number, number, number];
 export const __wbg_nativemapper_free: (a: number, b: number) => void;
 export const __wbg_nativeplugin_free: (a: number, b: number) => void;
 export const __wbg_nativepositionmapper_free: (a: number, b: number) => void;
 export const checkSyntax: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const expandSync: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
+export const invalidateScanCacheEntry: (a: number, b: number) => number;
 export const loadConfig: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const nativemapper_expandedToOriginal: (a: number, b: number) => number;
 export const nativemapper_generatedBy: (a: number, b: number) => [number, number];
@@ -34,19 +36,29 @@ export const nativepositionmapper_new: (a: any) => number;
 export const parseImportSources: (a: number, b: number, c: number, d: number) => [number, number, number];
 export const scanProjectSync: (a: number, b: number, c: any) => [number, number, number];
 export const transformSync: (a: number, b: number, c: number, d: number) => [number, number, number];
+export const clearScanCache: () => void;
 export const clearConfigCache: () => void;
 export const nativepositionmapper_mapToOriginal: (a: number, b: number, c: number) => any;
-export const __macroforgeRunClone: (a: number, b: number) => [number, number, number, number];
-export const __macroforgeRunOrd: (a: number, b: number) => [number, number, number, number];
-export const setupExternalMacros: (a: any, b: any) => void;
-export const __macroforgeRunPartialEq: (a: number, b: number) => [number, number, number, number];
+export const PartialOrd: () => void;
 export const __macroforgeRunPartialOrd: (a: number, b: number) => [number, number, number, number];
+export const Deserialize: () => void;
+export const __macroforgeRunDeserialize: (a: number, b: number) => [number, number, number, number];
 export const __macroforgeRunSerialize: (a: number, b: number) => [number, number, number, number];
-export const __macroforgeRunDebug: (a: number, b: number) => [number, number, number, number];
-export const __macroforgeRunDefault: (a: number, b: number) => [number, number, number, number];
-export const __macroforgeRunHash: (a: number, b: number) => [number, number, number, number];
 export const __macroforge_ffi_free: (a: number, b: number) => void;
 export const __macroforge_ffi_get_manifest: (a: number, b: number) => number;
+export const Serialize: () => void;
+export const Hash: () => void;
+export const __macroforgeRunHash: (a: number, b: number) => [number, number, number, number];
+export const Debug: () => void;
+export const __macroforgeRunDebug: (a: number, b: number) => [number, number, number, number];
+export const __macroforgeRunOrd: (a: number, b: number) => [number, number, number, number];
+export const setupBuildtimeFs: (a: any, b: any, c: any) => void;
+export const setupExternalMacros: (a: any, b: any) => void;
+export const Ord: () => void;
+export const Clone: () => void;
+export const __macroforgeRunClone: (a: number, b: number) => [number, number, number, number];
+export const __macroforgeRunPartialEq: (a: number, b: number) => [number, number, number, number];
+export const PartialEq: () => void;
 export const __wbindgen_malloc_command_export: (a: number, b: number) => number;
 export const __wbindgen_realloc_command_export: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_exn_store_command_export: (a: number) => void;