@autochitect/engine 1.1.2 → 1.1.3

package/README.md

@@ -39,6 +39,17 @@ console.log(result.results);
 
 **`result.errors`** / **`result.warnings`** — with line and column numbers.
 
+## Why use this
+
+| Instead of... | You get... |
+|---|---|
+| Building a calculation backend | 245KB client-side engine, zero infrastructure |
+| Exporting Excel/Google Sheets | Version-controlled DSL, real-time interactivity |
+| Spreadsheet-in-browser libraries | Just the engine — no grid UI overhead |
+| Python/R models behind an API | Embeddable in any web app, no server round-trips |
+
+The engine compiles your model into a directed acyclic graph, topologically sorts it, and estimates in one pass. Switching scenarios just swaps the input context — sub-millisecond.
+
 ## The DSL
 
 The language is deliberately small. It's designed for cost estimation and financial modeling specifically.
@@ -72,7 +83,90 @@ cumulative = SCAN(monthly, 0, LAMBDA(acc, m, acc + m))
 
 **MAP** transforms arrays element-wise. **SCAN** accumulates (like reduce, but returns intermediate results). **LAMBDA** defines inline functions with named parameters.
 
-The engine compiles this into a directed acyclic graph, topologically sorts it, and estimates in one pass. The graph is immutable — switching scenarios just swaps the input context, so it's instant.
+## Real-world examples
+
+### SaaS pricing calculator
+
+```javascript
+const result = engine.estimate(`
+  seats: Input
+  base_price_per_seat = 12
+  storage_gb: Input
+  storage_price_per_gb = 0.50
+
+  seat_cost = seats * base_price_per_seat
+  storage_cost = storage_gb * storage_price_per_gb
+  subtotal = seat_cost + storage_cost
+
+  # Volume discount
+  discount_rate = IF(seats > 50, 0.20, IF(seats > 20, 0.10, 0))
+  discount = subtotal * discount_rate
+  monthly_total = subtotal - discount
+  annual_total = monthly_total * 12
+`, {
+  seats: 35,
+  storage_gb: 200,
+});
+
+console.log(result.results.monthly_total);  // 455
+console.log(result.results.discount_rate);  // 0.1 (10% for 35 seats)
+```
+
+### Construction cost estimation
+
+```javascript
+const result = engine.estimate(`
+  square_footage: Input
+  base_cost_per_sqft: Input
+  num_floors: Input
+
+  material_cost = square_footage * base_cost_per_sqft
+  labor_cost = material_cost * 0.60
+  floor_premium = (material_cost + labor_cost) * ((num_floors - 1) * 0.08)
+
+  permits = (material_cost + labor_cost) * 0.03
+  insurance = (material_cost + labor_cost) * 0.02
+
+  total = material_cost + labor_cost + floor_premium + permits + insurance
+  cost_per_sqft = total / square_footage
+`, {
+  square_footage: 5000,
+  base_cost_per_sqft: 150,
+  num_floors: 3,
+});
+
+console.log(result.results.total);         // 1,452,000
+console.log(result.results.cost_per_sqft); // 290.40
+```
+
+### Loan amortization projection
+
+```javascript
+const result = engine.estimate(`
+  principal: Input
+  annual_rate: Input
+  months: Input
+
+  monthly_rate = annual_rate / 12
+  payment = principal * (monthly_rate * POWER(1 + monthly_rate, months))
+            / (POWER(1 + monthly_rate, months) - 1)
+
+  periods = SEQUENCE(months, 1, 1)
+  balances = SCAN(periods, principal, LAMBDA(bal, p,
+    bal * (1 + monthly_rate) - payment
+  ))
+
+  total_paid = payment * months
+  total_interest = total_paid - principal
+`, {
+  principal: 400000,
+  annual_rate: 0.065,
+  months: 360,
+});
+
+console.log(result.results.payment);        // ~2,528.27/month
+console.log(result.results.total_interest);  // ~510,177
+```
 
 ## Node.js usage
 
@@ -147,6 +241,17 @@ const engine = await createEngine(
 );
 ```
 
+## Framework examples
+
+Working integration examples are available in the [`examples/`](https://github.com/autochitect/engine/tree/main/examples) directory:
+
+| Example | Description |
+|---------|-------------|
+| [Next.js pricing calculator](https://github.com/autochitect/engine/tree/main/examples/nextjs-pricing-calculator) | SaaS pricing page with real-time sliders and volume discounts |
+| [Vue.js cost estimator](https://github.com/autochitect/engine/tree/main/examples/vue-cost-estimator) | Construction cost estimator with dependency graph visualization |
+| [Strapi pricing page](https://github.com/autochitect/engine/tree/main/examples/strapi-pricing-page) | CMS-driven pricing — content in Strapi, calculations in engine |
+| [Vanilla JS](https://github.com/autochitect/engine/tree/main/examples/vanilla-js) | Single HTML file, no build tools, plain DOM |
+
 ## Options
 
 ```javascript

package/index.browser.mjs

@@ -0,0 +1,125 @@
+const WASI_SHIM = {
+  fd_write: (fd, iovs_ptr, iovs_len, nwritten_ptr, mem) => {
+    const view = new DataView(mem.buffer);
+    let written = 0;
+    for (let i = 0; i < iovs_len; i++) {
+      written += view.getUint32(iovs_ptr + i * 8 + 4, true);
+    }
+    view.setUint32(nwritten_ptr, written, true);
+    return 0;
+  },
+  fd_close: () => 0,
+  fd_seek: (fd, lo, hi, whence, ptr, mem) => {
+    new DataView(mem.buffer).setBigUint64(ptr, 0n, true);
+    return 0;
+  },
+  fd_fdstat_get: (fd, buf, mem) => {
+    for (let i = 0; i < 24; i++) new DataView(mem.buffer).setUint8(buf + i, 0);
+    return 0;
+  },
+  environ_sizes_get: (cp, bp, mem) => {
+    const v = new DataView(mem.buffer);
+    v.setUint32(cp, 0, true);
+    v.setUint32(bp, 0, true);
+    return 0;
+  },
+  args_sizes_get: (ap, bp, mem) => {
+    const v = new DataView(mem.buffer);
+    v.setUint32(ap, 0, true);
+    v.setUint32(bp, 0, true);
+    return 0;
+  },
+  clock_time_get: (id, prec, ptr, mem) => {
+    new DataView(mem.buffer).setBigUint64(ptr, BigInt(Date.now()) * 1000000n, true);
+    return 0;
+  },
+  proc_exit: (code) => { throw new Error(`proc_exit(${code})`); },
+};
+
+const STUB_ERRNO = {
+  fd_read: 0, fd_sync: 0, fd_pread: 0, fd_pwrite: 0, fd_readdir: 0,
+  fd_prestat_get: 8, fd_prestat_dir_name: 28,
+  fd_filestat_get: 0, fd_filestat_set_size: 0, fd_filestat_set_times: 0,
+  environ_get: 0, args_get: 0,
+  path_open: 44, path_create_directory: 44, path_filestat_get: 44,
+  path_filestat_set_times: 44, path_link: 44, path_readlink: 44,
+  path_remove_directory: 44, path_rename: 44, path_symlink: 44,
+  path_unlink_file: 44, sched_yield: 0, poll_oneoff: 0,
+  sock_accept: 58, sock_recv: 58, sock_send: 58, sock_shutdown: 58,
+};
+
+function buildWasiImports(memoryRef) {
+  const imports = {};
+  for (const [name, fn] of Object.entries(WASI_SHIM)) {
+    if (typeof fn === 'function') {
+      if (name === 'proc_exit') {
+        imports[name] = fn;
+      } else {
+        imports[name] = (...args) => fn(...args, memoryRef.current);
+      }
+    }
+  }
+  for (const [name, errno] of Object.entries(STUB_ERRNO)) {
+    imports[name] = () => errno;
+  }
+  imports.clock_res_get = (id, ptr) => {
+    new DataView(memoryRef.current.buffer).setBigUint64(ptr, 1000000n, true);
+    return 0;
+  };
+  imports.random_get = (buf, len) => {
+    const view = new Uint8Array(memoryRef.current.buffer, buf, len);
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+      crypto.getRandomValues(view);
+    } else {
+      for (let i = 0; i < len; i++) view[i] = Math.floor(Math.random() * 256);
+    }
+    return 0;
+  };
+  return imports;
+}
+
+export async function createEngine(wasmSource) {
+  const memoryRef = { current: null };
+  const imports = { wasi_snapshot_preview1: buildWasiImports(memoryRef) };
+
+  let bytes;
+  if (wasmSource instanceof ArrayBuffer || ArrayBuffer.isView(wasmSource)) {
+    bytes = wasmSource;
+  } else if (wasmSource instanceof Response || (typeof wasmSource === 'object' && typeof wasmSource.then === 'function')) {
+    const response = await wasmSource;
+    bytes = await response.arrayBuffer();
+  } else if (wasmSource instanceof URL) {
+    bytes = await (await fetch(wasmSource)).arrayBuffer();
+  } else if (typeof wasmSource === 'string') {
+    bytes = await (await fetch(wasmSource)).arrayBuffer();
+  } else {
+    throw new Error('wasmSource must be a URL, URL string, Response, or ArrayBuffer');
+  }
+
+  const { instance } = await WebAssembly.instantiate(bytes, imports);
+  memoryRef.current = instance.exports.memory;
+
+  function writeString(str) {
+    const enc = new TextEncoder().encode(str);
+    const ptr = instance.exports.wasm_alloc(enc.length);
+    if (ptr === 0) throw new Error('WASM allocation failed');
+    new Uint8Array(memoryRef.current.buffer, ptr, enc.length).set(enc);
+    return { ptr, len: enc.length };
+  }
+
+  return {
+    estimate(source, inputs = {}, options = {}) {
+      const includeGraph = options.graph !== false;
+      const src = writeString(source);
+      const json = writeString(JSON.stringify(inputs));
+      const resultLen = instance.exports.wasm_estimate(
+        src.ptr, src.len,
+        json.ptr, json.len,
+        includeGraph ? 1 : 0
+      );
+      const resultPtr = instance.exports.wasm_result_ptr();
+      const resultBytes = new Uint8Array(memoryRef.current.buffer, resultPtr, resultLen);
+      return JSON.parse(new TextDecoder().decode(resultBytes));
+    },
+  };
+}

package/index.d.ts

@@ -21,7 +21,7 @@ export interface EstimateOptions {
 }
 
 export interface Engine {
-  estimate(source: string, inputs?: Record<string, unknown>, options?: EstimateOptions): EstimateResult;
+  estimate(source: string, inputs?: Record<string, unknown> | object, options?: EstimateOptions): EstimateResult;
 }
 
-export function createEngine(wasmSource: string | Response | ArrayBuffer): Promise<Engine>;
+export function createEngine(wasmSource: string | URL | Response | ArrayBuffer): Promise<Engine>;

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "@autochitect/engine",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "A 245KB WebAssembly financial modeling engine. Define cost models in a purpose-built DSL, get instant estimates with full dependency tracing. No server required.",
   "license": "MIT",
   "type": "module",
   "main": "index.mjs",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "browser": "./index.browser.mjs",
+      "import": "./index.mjs",
+      "default": "./index.mjs"
+    },
+    "./engine.wasm": "./engine.wasm"
+  },
   "files": [
     "index.mjs",
+    "index.browser.mjs",
     "index.d.ts",
     "engine.wasm",
     "LICENSE",
@@ -26,7 +36,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git@github.com:autochitect/engine.git"
+    "url": "git+ssh://git@github.com/autochitect/engine.git"
   },
   "homepage": "https://autochitect.com/engine"
 }