@ohtaman/washi 0.5.0 → 0.7.0

package/docs/getting-started/ai-agents.md

@@ -3,7 +3,10 @@
 > **Scope Note**: This document is the **consumer modeling quick-reference** for AI coding agents and developers building optimization or satisfiability models with `@ohtaman/washi`.
 > - **Portable Agent Skill (`SKILL.md`)**: For an actionable end-to-end modeling, `toLpString()` inspection, `validateSolution()` verification, and Z3 `unsatCore` conflict-diagnosis workflow skill (compatible with Claude Code, Antigravity, Cursor, Codex, and other `SKILL.md`-aware agents), use [`skills/washi/SKILL.md`](https://github.com/ohtaman/washi/blob/main/skills/washi/SKILL.md) (also shipped in the npm package at `node_modules/@ohtaman/washi/skills/washi/SKILL.md`):
 >   ```bash
->   # Link or copy the packaged skill into your project's agent skills directory
+>   # Install directly via the skills CLI (skills.sh / vercel-labs/skills)
+>   npx skills add ohtaman/washi
+>
+>   # Or link/copy the packaged skill into your project's agent skills directory
 >   mkdir -p .agents/skills/washi
 >   cp node_modules/@ohtaman/washi/skills/washi/SKILL.md .agents/skills/washi/SKILL.md
 >   ```
@@ -54,7 +57,7 @@ import "@ohtaman/washi/solvers/glpk";
 1. **Bundled WASM by default (no implicit CDN fallback)**:
    - In Node.js and modern bundlers, WebAssembly assets resolve relative to the module automatically.
    - In browser deployments, deploy the full `dist/browser/` directory (JS, Worker, and `.wasm` files) together. If a local WASM URL is missing or returns an HTML SPA fallback, initialization fails immediately and reports the attempted URL—it **never** silently switches to a public CDN.
-   - In browser runtimes, to load `highs.wasm` from a custom location, call `setHighsWasmUrl("https://.../highs.wasm")` or pass `await m.solve({ wasmUrl: "https://.../highs.wasm" })` (ignored in Node.js, which always loads the local Node `highs` package runtime).
+   - In browser runtimes, to load `highs.wasm` from a custom location, call `setHighsWasmUrl("https://.../highs.wasm")` or pass `await m.solve({ wasmUrl: "https://.../highs.wasm" })` (ignored in Node.js, which always loads WaSHI's bundled local `highs.wasm` runtime).
 2. **Z3 requires a Secure Context, Cross-Origin Isolation, and CORS in browsers**:
    - Z3 WebAssembly uses `SharedArrayBuffer` multithreading. Browser pages running Z3 must run in a secure context (`window.isSecureContext === true`, i.e., HTTPS or `localhost`) and be cross-origin isolated (`window.crossOriginIsolated === true`) by serving:
      - `Cross-Origin-Opener-Policy: same-origin` (on the document)
@@ -63,7 +66,7 @@ import "@ohtaman/washi/solvers/glpk";
    - Importing `@ohtaman/washi` never auto-injects a Service Worker. When a secure context or cross-origin isolation is absent in a browser, Z3 rejects immediately with a descriptive error.
 3. **Web Workers & Cancellation (`AbortSignal`)**:
    - Pre-solve cancellation (`signal.aborted` before execution starts) is supported across all solvers.
-   - In browsers where `Worker` is available, HiGHS runs in a dedicated Web Worker by default (`useWorker: true`). Passing `{ signal }` to `m.solve({ signal })` preemptively terminates an in-flight Worker solve (or cancels queued Worker requests).
+   - In browsers where `Worker` is available on a non-opaque effective origin (`window.origin !== "null"`), HiGHS runs in a dedicated Web Worker by default (`useWorker: true`). On opaque effective origins (`window.origin === "null"`, such as `file:` URLs or `sandbox="allow-scripts"` `<iframe>` embeds without `allow-same-origin`), HiGHS defaults to main-thread execution (`useWorker: false`). Passing `{ signal }` to `m.solve({ signal })` preemptively terminates an in-flight Worker solve (or cancels queued Worker requests).
    - On main-thread HiGHS (`useWorker: false` or in Node.js), cooperative mid-solve cancellation is supported when `abort()` is triggered synchronously inside an `onProgress` callback at a solver interrupt checkpoint; arbitrary asynchronous aborts from outside cannot preempt a blocked synchronous WASM thread until a callback checkpoint or completion. Single-threaded WASM solvers without interrupt hooks (GLPK, Z3) check `signal` before execution starts.
 
 ---
@@ -79,6 +82,7 @@ const m = new Model("ExampleModel");
 
 // Scalar variables
 const x = m.continuous("x", { lb: 0, ub: 100 });
+const y = m.continuous("y", { lb: 0, ub: 100 });
 const n = m.integer("n", { lb: 0, ub: 10 });
 const b = m.binary("b");
 const flag = m.bool("flag"); // Propositional boolean (for Z3 / logical constraints)
@@ -100,12 +104,12 @@ const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
 ### Step 2: Build Expressions (`expr`, `sum`, `dot`)
 
 - **Unified `expr` template tag**:
-  - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${n} - 10` ``
-  - Quadratic expression (`QuadExpr`): `` expr`${x}^2 + 2 * ${x} * ${n} + ${n}^2` `` (variable-by-variable products and squares are supported for convex QP objectives).
-  - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${n} <= 40` `` (supports `<=`, `>=`, `==`, and `=`).
-- **Aggregations**:
-  - `sum(iterable, mapper?)` sums an `Iterable` of `Var` / `LinExpr` / `number` (e.g., `Var[]`, `grid.flat()`, or `Object.values(record)`).
-  - `dot(a, b)` computes the inner product of matching 1D arrays, 2D arrays (`number[][]` / `Var[][]`), plain records (`Record<string, ...>`), or mixed Array/Record containers in either operand order.
+  - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${n} - 10` ``, `` expr`dot(${profit}, ${byItem}) - 20 * ${b}` ``, `` expr`sum((${price} - ${cost}) * ${byItem})` ``
+  - Quadratic expression (`QuadExpr`): `` expr`${x}^2 + 2 * ${x} * ${y} + ${y}^2` ``, `` expr`sum((${vec} - ${target})^2)` `` (supported for convex QP objectives on purely continuous models using `m.continuous`; built-in HiGHS does not support MIQP models containing integer, binary, or boolean variables).
+  - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${n} <= 40` ``, `` expr`sum(${byItem}) <= 100` `` (supports `<=`, `>=`, `==`, and `=`).
+- **Aggregations & Element-Wise Container Arithmetic**:
+  - `sum(containerOrItems, mapper?)` (usable inside `` expr`sum(...)` `` or standalone `sum(...)`) sums a 1D/2D `Array`, `Iterable`, or plain `Record` of `Var` / `LinExpr` / `number` (without needing `Object.values(record)`), or maps over items/counts via `sum(items, (item, i) => ...)`. Inside `` expr`sum(...)` ``, element-wise container arithmetic (`+`, `-`, `*`, `/`, `^2`) is also supported.
+  - `dot(a, b)` (usable inside `` expr`dot(${a}, ${b})` `` or standalone `dot(a, b)`) computes the inner product of matching 1D arrays, 2D arrays (`number[][]` / `Var[][]`, computing the Frobenius inner product $\sum_{i,j} A_{i,j} B_{i,j}$), plain records (`Record<string, ...>`), or mixed Array/Record containers in either operand order.
 - **Fluent methods**:
   - Arithmetic (on `LinExpr` and `QuadExpr`; `Var` supports `.add()`, `.sub()`, `.mul()`, `.neg()`): `.add(other)`, `.sub(other)`, `.mul(other)`, `.div(scalar)`, `.neg()`
   - Comparisons (on `Var` and `LinExpr`): `.le(rhs, name?)`, `.ge(rhs, name?)`, `.eq(rhs, name?)`
@@ -119,8 +123,8 @@ Constructing an `expr` or `.le()` object does **not** attach it to the model unt
 // Set objective using maximize() or minimize()
 m.objective(maximize(expr`30 * ${x} + 50 * ${n}`));
 
-// Register constraints on the model
-m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
+// Register constraints on the model (returns the registered Constraint / BoolExpr or array)
+const limit = m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
 
 // Indicator constraint (MIP Big-M reformulation: b === 1 => x <= 50)
 m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
@@ -132,9 +136,10 @@ m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
   - Returns `SolverStatus` (`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`, `"Sat"`, or `"Unsat"`). Built-in optimization solvers return the optimization statuses (`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`), where a time-, iteration-, or solution-limited run (or an interrupted solve) that found a valid primal incumbent returns `"Feasible"`; `"Sat"` and `"Unsat"` are included in `SolverStatus` for satisfiability/custom solver adapters (such as `MockSolver`).
   - Read values via `x.value`, `expr`...`.value`, `m.getValues(x)`, `m.getValues(container)`, `m.objectiveValue`, `constr.dual`, `constr.slack`, and `x.reducedCost`.
   - Call `m.validateSolution()` after solving to independently verify variable finiteness, variable bounds (`lb`/`ub`), integer/binary/boolean domains, linear constraint residuals, and logical constraints (`SolutionValidationReport`: `{ valid, complete, maxViolation, violations, ... }`). Note that `validateSolution()` checks primal feasibility of variables and constraints; it does not recompute or compare `m.objectiveValue`.
-- **Satisfiability & Unsat Core (`await m.check(options?)`)**:
-  - Returns `CheckResult` (`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`), where `conflicts` and `unsatCore` are optional and populated only when an unsat-core-capable solver (such as Z3) returns `"Unsat"`.
-  - For models containing only linear arithmetic constraints, `m.check()` works with any solver (including the default HiGHS and GLPK) by falling back to a feasibility `solve()`. Logical constraints (`BoolVar`, `and`, `or`, `implies`, etc.) and unsatisfiable-core extraction (`result.conflicts` / `result.unsatCore`) require an SMT-capable solver (`{ solver: "z3" }`). Because Z3 asserts variable bounds (`lb`/`ub`) and binary `{0, 1}` domains directly while tracking registered constraints, `conflicts` / `unsatCore` reports a subset of registered constraint names that conflicts *together with the model's fixed variable bounds/domains* (and is not guaranteed minimal).
+- **Satisfiability & Conflict Diagnosis (`await m.check(options?)`)**:
+  - Returns `CheckResult` (`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`), where `conflicts` is populated when the model is proven `"Unsat"`.
+  - For models containing linear arithmetic constraints or logical constraints (`BoolVar`, `and`, `or`, `implies`, `xor`), `m.check()` works with any solver (including the default HiGHS and GLPK via single-solve elastic slack relaxation, automatically linearizing logical constraints into 0-1 MIP formulation) and diagnoses conflicting constraints as `conflicts` (leaving `unsatCore: undefined` for semantic rigor).
+  - Exact SMT unsatisfiable-core extraction (`result.unsatCore` and `result.conflicts`) is provided when using an SMT-capable solver (`{ solver: "z3" }`). Because Z3 asserts variable bounds (`lb`/`ub`) and binary `{0, 1}` domains directly while tracking registered constraints, `unsatCore` reports a subset of registered constraint names that conflicts *together with the model's fixed variable bounds/domains* (and is not guaranteed minimal).
 - **No concurrent mutation during async solve/check**:
   - Mutating variables, constraints, or the objective while `await m.solve()` or `await m.check()` is pending invalidates the in-flight execution and rejects the stale promise.
 
@@ -157,10 +162,13 @@ export async function runMipExample() {
   const qty = m.integer(products, { lb: 0, ub: 100 });
   const setup = m.binary("setup");
 
-  m.objective(maximize(expr`${dot(profit, qty)} - 20 * ${setup}`));
-  m.constraint(expr`${dot(woodPerUnit, qty)} <= 40`, "wood_cap");
-  m.constraint(expr`${dot(laborPerUnit, qty)} <= 50`, "labor_cap");
-  m.constraint(expr`${sum(Object.values(qty))} <= 30 * ${setup}`, "require_setup");
+  m.objective(maximize(expr`dot(${profit}, ${qty}) - 20 * ${setup}`));
+  m.constraint(expr`dot(${woodPerUnit}, ${qty}) <= 40`, "wood_cap");
+  m.constraint(expr`dot(${laborPerUnit}, ${qty}) <= 50`, "labor_cap");
+  m.indicator(setup, expr`sum(${qty}) <= 0`, {
+    activeValue: 0,
+    name: "require_setup",
+  });
 
   const status = await m.solve();
   const report = m.validateSolution();
@@ -265,3 +273,10 @@ export function verifyNegativePatterns() {
 }
 ```
 
+### Practical OR Modeling Guardrails
+
+- **Prefer inequalities (`>=` / `<=`) over exact equalities (`==`)** for demand coverage and resource limits when objective costs are positive; reserve `==` for physical conservation laws (e.g., flow balance, portfolio weights summing to `1`).
+- **Always provide finite `lb` and `ub` bounds** on variables referenced inside `m.indicator(...)` and omit `M` so WaSHI automatically derives the tightest valid Big-M instead of falling back to `1e6`.
+- **Use soft constraints (elastic slack variables)** for non-rigid business targets (e.g., preferred staffing, safety stock, day-off requests) by adding a non-negative slack variable (`lb: 0`) with a tiered objective penalty, reserving hard constraints for physical or legal invariants.
+
+

package/docs/getting-started/cross-origin.md

@@ -1,47 +1,70 @@
 # Cross-Origin Isolation (Z3 & Browsers)
 
-When running the **Z3** solver engine inside a web browser, special HTTP headers are required due to browser security models.
+When running the **Z3** solver inside a web browser, Cross-Origin Isolation HTTP headers are required so the browser enables `SharedArrayBuffer`.
+
+> [!TIP]
+> **Not needed for HiGHS, GLPK, or Node.js**: The built-in **HiGHS** solver and **GLPK** plugin run in standard browser contexts without Cross-Origin Isolation or `SharedArrayBuffer`. Running Z3 in **Node.js** also requires no HTTP headers. You only need this page when using `@ohtaman/washi/solvers/z3` in the browser.
 
 ---
 
 ## Why is Cross-Origin Isolation Required?
 
-The Z3 WebAssembly engine utilizes multithreading backed by `SharedArrayBuffer` and Web Workers.
-
-In modern browsers (Chrome, Firefox, Safari, Edge), `SharedArrayBuffer` is disabled by default to mitigate Spectre-style timing side-channel attacks. To re-enable it, the hosting page must be **Cross-Origin Isolated**.
+Z3's WebAssembly build uses multithreading (pthreads) backed by `SharedArrayBuffer` and Web Workers. Modern browsers (Chrome, Firefox, Safari, Edge) disable `SharedArrayBuffer` by default to mitigate Spectre-style side-channel attacks unless the top-level document opts into **Cross-Origin Isolation** (`window.crossOriginIsolated === true`).
 
 ---
 
 ## Required HTTP Response Headers
 
-To establish cross-origin isolation, your web server must serve the top-level HTML document with the following HTTP headers:
+Serve the top-level HTML document with:
 
 ```http
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-In addition, any cross-origin assets (e.g. scripts or WASM files loaded from external domains) must send:
+If your page loads cross-origin subresources (such as scripts, images, or WASM files from another domain), those responses must also include `Cross-Origin-Resource-Policy: cross-origin` (or CORS headers).
 
-```http
-Cross-Origin-Resource-Policy: cross-origin
-```
+> [!NOTE]
+> Chromium and Firefox also support `Cross-Origin-Embedder-Policy: credentialless`, which relaxes subresource CORP requirements, **but Safari (WebKit) does not support `credentialless`**. Use `require-corp` if you support Safari / iOS.
 
 ---
 
-## Solutions by Hosting Environment
+## Setup by Environment
 
-### 1. Custom Node.js / Express Server
+### 1. Vite (`vite.config.ts`)
 
-```javascript
-app.use((req, res, next) => {
-  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
-  res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
-  next();
+Configure both the local dev server (`vite`) and production preview server (`vite preview`):
+
+```typescript
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  server: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
+    },
+  },
+  preview: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
+    },
+  },
 });
 ```
 
-### 2. Next.js (`next.config.js`)
+### 2. Cloudflare Pages / Netlify (`public/_headers`)
+
+Place a `_headers` file in `public/` so it is copied to the root of your build output:
+
+```text
+/*
+  Cross-Origin-Opener-Policy: same-origin
+  Cross-Origin-Embedder-Policy: require-corp
+```
+
+### 3. Next.js (`next.config.js`)
 
 ```javascript
 /** @type {import('next').NextConfig} */
@@ -62,26 +85,31 @@ const nextConfig = {
 module.exports = nextConfig;
 ```
 
-### 3. Static Hosting without Header Control (e.g., GitHub Pages)
+### 4. Custom Node.js / Express Server
+
+```javascript
+app.use((req, res, next) => {
+  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+  res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+  next();
+});
+```
 
-Platforms like GitHub Pages or preview environments do not allow customizing response headers directly.
+### 5. Static Hosting without Header Control (e.g., GitHub Pages)
 
-For these environments, you can use **`coi-serviceworker`** (a lightweight Service Worker that injects isolation headers on the client side):
+Platforms like GitHub Pages do not allow customizing HTTP response headers directly. You can use **`coi-serviceworker`** to inject the isolation headers via a client-side Service Worker:
 
-1. Place `coi-serviceworker.js` in your website root.
-2. In your HTML `<head>`, include:
+1. Place `coi-serviceworker.js` at your site root.
+2. Load it in your HTML `<head>`:
 
 ```html
 <script src="/coi-serviceworker.js"></script>
 ```
 
-When a user visits for the first time, the service worker registers and reloads the page once to establish `window.crossOriginIsolated === true`.
+On the first visit, the Service Worker registers and reloads the page once to establish `window.crossOriginIsolated === true`.
 
 ---
 
-## Graceful Degradation in WaSHI
-
-WaSHI's Z3 solver adapter automatically inspects the environment at runtime. If Z3 is invoked in a browser lacking cross-origin isolation, it immediately rejects with a clear, informative error message explaining that COOP/COEP headers or a service worker are required, rather than hanging silently.
+## Runtime Check in WaSHI
 
-> [!TIP]
-> The default **HiGHS** solver engine does not require cross-origin isolation or `SharedArrayBuffer`. It works out of the box in standard browser contexts.
+WaSHI's Z3 adapter checks `crossOriginIsolated` before initializing Z3 in the browser. If Cross-Origin Isolation is missing, `solve()` / `check()` immediately rejects with an actionable error explaining that COOP/COEP headers or a Service Worker are required, rather than hanging silently.

package/docs/getting-started/index.md

@@ -1,19 +1,35 @@
 # Introduction & Installation
 
-Welcome to **WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface).
+**WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface) brings the algebraic modeling style of Python's **PuLP** to the TypeScript and JavaScript ecosystem. Write expressions naturally with tagged templates (`expr`) and solve mathematical optimization problems directly in **Node.js and the browser** using WebAssembly solvers (**HiGHS**, **Z3**, and **GLPK**).
 
-WaSHI brings the algebraic modeling style of Python's **PuLP** and Julia's **JuMP** to the TypeScript and JavaScript ecosystem. You can formulate mathematical optimization problems using algebraic expressions and solve them locally using WebAssembly solvers (**HiGHS**, **Z3**, and **GLPK**)—without a separate Python service or native C/C++ build steps.
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model("production");
 
-### Why TypeScript & WebAssembly?
+// 1. Define decision variables with realistic finite bounds (lb / ub)
+const desks = m.integer("desks", { lb: 0, ub: 100 });
+const chairs = m.integer("chairs", { lb: 0, ub: 100 });
 
-- **Removing the deployment bottleneck**: In traditional optimization workflows (e.g., Python with PuLP or Pyomo), turning a model into an interactive application requires provisioning a backend service and managing native C/C++ solver binaries. As AI-assisted development accelerates UI and application prototyping, backend infrastructure often becomes the primary bottleneck to shipping. Running both the modeler and WebAssembly solvers on standard Web technologies allows an optimization tool to be deployed as static assets (e.g., on GitHub Pages or Cloudflare Pages, serving the generated JS, Worker, and WASM files; with COOP/COEP headers when using Z3)—and makes it straightforward to pair mathematical optimization with in-browser LLMs (e.g., WebGPU / WebLLM) entirely on the client.
-- **Algebraic syntax without operator overloading (`expr`)**: Because JavaScript lacks operator overloading, libraries usually trade off between verbose method chaining (`x.mul(30).add(y.mul(50))`) and untyped strings (`"30 * x + 50 * y"`). WaSHI uses tagged template literals (`` expr`30 * ${x} + 50 * ${y} <= 40` ``) similar to parameterized SQL queries—parsing infix operators while binding `${x}` directly as typed TypeScript object references for static type checking, IDE symbol renaming, and multi-dimensional indexing (`${flow[i][j]}`).
+// 2. Set the objective function and constraints
+m.objective(maximize(expr`30 * ${desks} + 50 * ${chairs}`));
+m.constraint(expr`${desks} + 2 * ${chairs} <= 40`, "wood_capacity");
+m.constraint(expr`2 * ${desks} + ${chairs} <= 50`, "labor_capacity");
+
+// 3. Solve (built-in HiGHS WebAssembly) and validate the solution
+const status = await m.solve();
+if (m.hasPrimalSolution) {
+  const report = m.validateSolution();
+  console.log(status, report.valid); // "Optimal", true
+  console.log(`Profit: ${m.objectiveValue} (desks=${desks.value}, chairs=${chairs.value})`); // 1100 (desks=20, chairs=10)
+}
+```
 
 ---
 
 ## 📦 Installation
 
-Install WaSHI using your preferred package manager:
+The default **HiGHS** solver (LP / MIP / Convex QP) is bundled and works out of the box:
 
 ::: code-group
 
@@ -35,82 +51,37 @@ bun add @ohtaman/washi
 
 :::
 
-### Optional Solver Dependencies
-
-WaSHI ships with **HiGHS** built-in with zero configuration. If you need SMT logic / Unsat Core diagnosis via **Z3**, or compatibility with **GLPK**, install their respective peer dependencies:
+Install optional peer dependencies only if you need **Z3** (SMT logic & Unsat Core diagnosis) or **GLPK**:
 
 ```bash
-# For SMT logic and Unsat Core conflict diagnosis
-npm install z3-solver
-
-# For GLPK solver (GPL-3.0)
-npm install glpk.js
+npm install z3-solver   # For SMT logic and Unsat Core conflict diagnosis
+npm install glpk.js     # For GLPK solver (GPL-3.0)
 ```
 
 ---
 
-## 🚀 Quickstart Walkthrough
-
-Here is a step-by-step example of solving a production allocation problem.
-
-### 1. Import the Core Classes
-
-```typescript
-import { Model, expr, maximize } from "@ohtaman/washi";
-```
-
-### 2. Instantiate a Model
-
-```typescript
-const model = new Model("WoodworkingProfit");
-```
-
-### 3. Add Decision Variables
+## 💡 Why TypeScript & WebAssembly?
 
-Variables represent the unknowns you want to determine. Factory methods (`m.continuous`, `m.integer`, `m.binary`) clearly define their domain:
+- **Zero native setup across Node.js and the browser**: No platform-specific C/C++ builds or separate Python runtimes to manage. A single `npm install` runs the same modeling code across **Node.js APIs, CLIs, and scripts** as well as in the **browser**.
+- **Lightweight embedding with standard Web APIs & UIs**: Go beyond local analysis scripts by shipping **interactive Web tools, mini-games, or Chrome extensions** that anyone can open via a URL with zero backend hosting cost. You can wire mathematical optimization directly into drag-and-drop UIs or **standard browser capabilities**—such as screen/camera capture and speech recognition (Web Speech API)—with no network round-trips or external data transfer.
+- **End-to-end type safety from app data to model**: Prevent common indexing and dictionary-key mistakes with TypeScript's type system. Typed variable dictionaries (`Record<K, Var>`) and variable-reference interpolation (`` expr`30 * ${qty.desk} <= 40` ``) connect directly to your application schemas, preserving compile-time variable/key checks, IDE autocompletion, and symbol renaming.
+- **Strong synergy with AI development & LLM workflows**: Keeping your application and optimization model in a **single TypeScript codebase** lets you validate everything in one test runner—without crossing a Python service boundary—and deploy easily as static assets or a single service. That tight test-and-deploy loop fits AI-assisted coding naturally, while at runtime you can pair flexible LLM extraction with exact solver feasibility and conflict diagnosis (`unsatCore`) in the same runtime.
 
-```typescript
-const x = model.integer("x", { lb: 0 });
-const y = model.integer("y", { lb: 0 });
-```
-
-### 4. Set the Objective Function
-
-Use the `expr` tagged template literal along with `maximize(...)` or `minimize(...)` to define the goal:
-
-```typescript
-// Maximize 30*x + 50*y
-model.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
-```
-
-### 5. Add Constraints
-
-Use `model.constraint()` with the `expr` tagged template to formulate equality and inequality constraints:
-
-```typescript
-model.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_capacity");
-model.constraint(expr`2 * ${x} + ${y} <= 50`, "labor_capacity");
-```
-
-### 6. Solve and Extract Results
+---
 
-Solve the model asynchronously via WebAssembly (HiGHS by default):
+## 🔍 Core Workflow Essentials
 
-```typescript
-const status = await model.solve();
+Three practical habits cover the essentials shown in the snippet above:
 
-console.log("Status:", status); // "Optimal"
-console.log("Optimal Objective Value:", model.objectiveValue); // 1100
-console.log(`Solution: x = ${x.value}, y = ${y.value}`); // x = 20, y = 10
-```
+1. **Set realistic finite bounds (`lb`, `ub`)**: When defining variables with `m.continuous`, `m.integer`, or `m.binary`, finite bounds strengthen MIP presolve and enable automatic tight Big-M derivation for logical constraints.
+2. **Formulate objectives and constraints with `expr`**: Use `` m.objective(maximize(expr`...`)) `` and `` m.constraint(expr`... <= ...`, "name") ``. Naming constraints lets you pinpoint conflicting rules immediately if a model becomes infeasible.
+3. **Check `hasPrimalSolution` and call `validateSolution()`**: After `await m.solve()`, check `m.hasPrimalSolution` before reading `.value` on variables, and call `m.validateSolution()` to independently verify that bounds, integrality, and constraints hold within tolerance.
 
 ---
 
 ## 🧭 Next Steps
 
-- Give AI coding agents a concise API & deployment reference with the [AI Coding Agent Quick-Reference Guide](./ai-agents.md).
-- Learn how to run WaSHI across different environments in [Runtime Environments](./runtimes.md).
-- Understand how to formulate complex expressions in the [Modeling Guide](../guide/expressions.md).
-- Explore built-in and pluggable solvers in the [Solvers Matrix](../solvers/).
-- Browse 9 runnable optimization and SMT recipes in [Examples & API Finder](../examples/).
-
+- **[Modeling Guide](../guide/variables.md)**: Array/dictionary variables, aggregations (`sum`, `dot`), logical constraints, and Unsat Core diagnosis
+- **[Examples & API Finder](../examples/)**: 11 runnable optimization and SMT recipes—from shift scheduling and portfolio QP to vehicle routing
+- **[Solvers Overview](../solvers/)**: Compare built-in HiGHS with optional Z3 and GLPK adapters
+- **[Runtime Environments](./runtimes.md)**: Setup details for Node.js, Vite / Next.js bundlers, CDNs, and static hosting

package/docs/getting-started/runtimes.md

@@ -1,12 +1,14 @@
 # Runtime Environments & Deployment
 
-WaSHI runs across JavaScript and TypeScript runtimes—from Node.js, Bun, and Deno to modern bundlers, vanilla browser `<script>` tags, and air-gapped intranets—without native C/C++ compilation.
+WaSHI runs across JavaScript and TypeScript runtimes—from Node.js, Bun, and Deno to modern bundlers, static hosting, and vanilla browser `<script>` tags—without native C/C++ compilation.
 
 ---
 
-## 🟢 Node.js
+## 🟢 Node.js, Bun & Deno
 
-WaSHI supports Node.js (v18+) out of the box with standard ECMAScript Modules (ESM). The built-in HiGHS WebAssembly binary is loaded directly from the installed package.
+### Node.js
+
+WaSHI supports Node.js (v18+) out of the box with standard ECMAScript Modules (ESM). The built-in HiGHS WebAssembly binary is loaded directly from the installed package:
 
 ```typescript
 import { Model, expr, maximize } from "@ohtaman/washi";
@@ -19,8 +21,10 @@ m.objective(maximize(expr`2 * ${x} + 3 * ${y}`));
 m.constraint(expr`${x} + ${y} <= 15`, "capacity");
 
 await m.solve();
-console.log(`Status: ${m.status}, Objective: ${m.objectiveValue}`);
-console.log(`x = ${x.value}, y = ${y.value}`);
+if (m.hasPrimalSolution) {
+  console.log(`Status: ${m.status}, Objective: ${m.objectiveValue}`);
+  console.log(`x = ${x.value}, y = ${y.value}`);
+}
 ```
 
 Run directly with `tsx` or `node`:
@@ -29,11 +33,33 @@ Run directly with `tsx` or `node`:
 npx tsx app.ts
 ```
 
+### Bun & Deno
+
+```bash
+# Bun
+bun add @ohtaman/washi
+bun run app.ts
+```
+
+In Deno (v1.30+ with `npm:` specifiers):
+
+```typescript
+import { Model, maximize } from "npm:@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0, ub: 10 });
+m.objective(maximize(x));
+await m.solve();
+if (m.hasPrimalSolution) {
+  console.log("x =", x.value);
+}
+```
+
 ---
 
-## 🌐 Bundlers (Vite, Webpack, Rollup, Next.js)
+## 🌐 Bundlers & Static Hosting (Vite, Next.js, Webpack, Rollup)
 
-### Modern Bundlers (Vite / Rollup / Webpack)
+### Modern Bundlers & Static Deployment
 
 When importing `@ohtaman/washi` in a browser bundler, the `browser` export condition resolves automatically:
 
@@ -45,14 +71,16 @@ export async function runOptimization() {
   const x = m.continuous("x", { lb: 0, ub: 100 });
   m.objective(maximize(x));
   await m.solve();
-  return x.value;
+  return m.hasPrimalSolution ? x.value : null;
 }
 ```
 
+Because both the modeler and solver run on WebAssembly, the static output of `vite build` (or your bundler's production build) can be deployed directly to **GitHub Pages, Cloudflare Pages, Vercel, or Netlify** with no backend server required. (The default HiGHS and GLPK solvers require no special HTTP headers; if you use Z3 in the browser, see [Cross-Origin Isolation](./cross-origin.md).)
+
 #### Background Web Worker Execution (Default)
-In browsers, HiGHS automatically runs inside a dedicated **Web Worker** so long-running LP/MIP/QP solves never freeze the main UI thread, animations, or user input, while enabling real-time progress events (`onProgress`) and cancellation (`AbortSignal`).
+In browsers, HiGHS automatically runs inside a dedicated **Web Worker** so LP/MIP/QP solves never freeze the main UI thread, animations, or user input, while enabling real-time progress events (`onProgress`) and cancellation (`AbortSignal`).
 
-If your environment prohibits Web Workers or you explicitly want synchronous main-thread execution, pass `useWorker: false`:
+If your environment prohibits Web Workers or you explicitly want main-thread execution, pass `useWorker: false`:
 
 ```typescript
 await m.solve({ useWorker: false });
@@ -91,7 +119,9 @@ export default function OptimizerComponent() {
     const x = m.continuous("x", { lb: 0, ub: 50 });
     m.objective(maximize(x));
     await m.solve();
-    setVal(x.value);
+    if (m.hasPrimalSolution) {
+      setVal(x.value);
+    }
   };
 
   return (
@@ -107,36 +137,36 @@ export default function OptimizerComponent() {
 
 ## 📦 Browser ESM (`<script type="module">`)
 
-You can import the pre-bundled browser ESM modules directly from a local static server (or from an npm CDN once a compatible release is published) without a build step:
+Without a bundler, you can import the pre-built browser ESM module directly from your own static server or an npm CDN:
 
 ```html
 <script type="module">
-  // Serve from your local static server / dist:
-  import { Model, expr, maximize } from "./dist/browser/washi.js";
-  // Or from an npm CDN once a compatible release is published:
-  // import { Model, expr, maximize } from "https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.js";
+  // From an npm CDN (or "./dist/browser/washi.js" when self-hosted):
+  import { Model, expr, maximize } from "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/washi.js";
   // Optional solver plugins:
-  // import "./dist/browser/solvers/glpk.js";
-  // import "./dist/browser/solvers/z3.js";
+  // import "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/glpk.js";
+  // import "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/z3.js";
 
   const m = new Model("BrowserESM");
-  const x = m.integer("x", { lb: 0 });
-  const y = m.integer("y", { lb: 0 });
+  const x = m.integer("x", { lb: 0, ub: 100 });
+  const y = m.integer("y", { lb: 0, ub: 100 });
 
   m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
   m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
   m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor");
 
   await m.solve();
-  console.log("Optimal Objective:", m.objectiveValue);
+  if (m.hasPrimalSolution) {
+    console.log("Optimal Objective:", m.objectiveValue);
+  }
 </script>
 ```
 
 ---
 
-## 🟨 Classic `<script>` Tags (IIFE / Standalone Build / CDN)
+## 🟨 Classic `<script>` Tags (IIFE / Standalone HTML / CDN)
 
-For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard `<script>` tag. All exports are attached to the global `window.Washi` object:
+For single-file HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard `<script>` tag. All exports are attached to the global `window.Washi` object:
 
 ```html
 <!DOCTYPE html>
@@ -149,13 +179,11 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
     <h1>WaSHI Browser Optimization</h1>
     <pre id="output">Solving...</pre>
 
-    <!-- Core WaSHI + HiGHS (MIT) from local static build / assets -->
-    <script src="./dist/browser/washi.min.js"></script>
-    <!-- Or via CDN once a compatible release is published: -->
-    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.min.js"></script> -->
+    <!-- Core WaSHI + HiGHS (MIT) via CDN (or "./dist/browser/washi.min.js" when self-hosted) -->
+    <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/washi.min.js"></script>
     <!-- Optional plugins (auto-register on window.Washi): -->
-    <!-- <script src="./dist/browser/solvers/glpk.min.js"></script> -->
-    <!-- <script src="./dist/browser/solvers/z3.min.js"></script> -->
+    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/glpk.min.js"></script> -->
+    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/z3.min.js"></script> -->
 
     <script>
       (async () => {
@@ -170,10 +198,12 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
 
         await m.solve();
 
-        document.getElementById("output").textContent =
-          `Status: ${m.status}\n` +
-          `Objective: ${m.objectiveValue}\n` +
-          `x = ${x.value}, y = ${y.value}`;
+        if (m.hasPrimalSolution) {
+          document.getElementById("output").textContent =
+            `Status: ${m.status}\n` +
+            `Objective: ${m.objectiveValue}\n` +
+            `x = ${x.value}, y = ${y.value}`;
+        }
       })();
     </script>
   </body>
@@ -181,7 +211,7 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
 ```
 
 > [!NOTE]
-> When loading `washi.min.js` from a cross-origin CDN (such as jsDelivr or unpkg), browsers block direct `new Worker("https://cdn...")` construction due to the same-origin policy. WaSHI automatically bridges cross-origin workers via a lightweight `Blob` wrapper using `importScripts()`, so Web Worker execution works out of the box from CDNs.
+> When loading from a cross-origin CDN (such as jsDelivr or unpkg), browsers block direct `new Worker("https://cdn...")` construction under the same-origin policy. On standard web origins (`https://` / `http://`), WaSHI automatically bridges cross-origin workers via a lightweight ES module `Blob` bootstrap (`import "https://..."`). On opaque effective origins (`window.origin === "null"`, such as local `file:` URLs or `sandbox="allow-scripts"` `<iframe>` embeds without `allow-same-origin`), WaSHI automatically runs HiGHS on the main thread when `useWorker` is omitted.
 
 ---
 
@@ -195,33 +225,8 @@ WaSHI never phones home or falls back to public CDNs. To self-host in an air-gap
    - Optional Z3: `solvers/z3.js` / `solvers/z3.min.js`, `solvers/z3-built.js`, `solvers/z3-built.wasm`
 2. **Content Security Policy (CSP) Headers**:
    - Allow WebAssembly compilation (`'wasm-unsafe-eval'` in `script-src`).
-   - If using the default Web Worker or cross-origin Blob worker fallback, allow `worker-src 'self' blob:;`.
+   - If using the default Web Worker or cross-origin Blob worker bootstrap, allow `worker-src 'self' blob:;`.
    - If `blob:` workers are prohibited by policy, either serve `highs-worker.js` from `'self'` or run on the main thread with `await m.solve({ useWorker: false })`.
 3. **Cross-Origin Isolation (Z3 Only)**:
    - HiGHS and GLPK run in standard browser contexts without special headers.
-   - Z3 WASM uses pthreads + `SharedArrayBuffer` and requires `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (or `credentialless`). See the [Cross-Origin Isolation Guide](./cross-origin.md) for setup details.
-
----
-
-## ⚡ Bun & Deno
-
-### Bun
-
-```bash
-bun add @ohtaman/washi
-bun run app.ts
-```
-
-### Deno
-
-In Deno (v1.30+ with `npm:` specifiers):
-
-```typescript
-import { Model, maximize } from "npm:@ohtaman/washi";
-
-const m = new Model();
-const x = m.continuous("x", { lb: 0, ub: 10 });
-m.objective(maximize(x));
-await m.solve();
-console.log("x =", x.value);
-```
+   - Z3 WASM uses pthreads + `SharedArrayBuffer` and requires `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (`credentialless` works in Chromium/Firefox, whereas Safari requires `require-corp`). See the [Cross-Origin Isolation Guide](./cross-origin.md) for setup details.