@ohtaman/washi 0.1.2 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
     <source media="(prefers-color-scheme: light)" srcset="./assets/washi-header-light.png">
     <img alt="WaSHI - Algebraic Modeler for TypeScript &amp; JavaScript" src="./assets/washi-header-light.png" width="420" />
   </picture>
-  <p><strong>Intuitive Mathematical Optimization &amp; Algebraic Modeler for TypeScript &amp; JavaScript</strong></p>
+  <p><strong>Algebraic Modeling for TypeScript &amp; JavaScript</strong></p>
   <p>
     <em>Linear Programming (LP) • Mixed-Integer Programming (MIP) • Quadratic Programming (QP) • SMT &amp; Conflict Diagnosis</em>
   </p>
@@ -14,56 +14,58 @@
     <a href="./README.zh-CN.md">简体中文</a>
   </p>
   <p>
+    <a href="https://www.npmjs.com/package/@ohtaman/washi"><img src="https://img.shields.io/npm/v/@ohtaman/washi?color=crimson&label=npm" alt="npm version" /></a>
+    <a href="https://github.com/ohtaman/washi/actions/workflows/distribution.yml"><img src="https://github.com/ohtaman/washi/actions/workflows/distribution.yml/badge.svg" alt="CI Status" /></a>
     <a href="https://ohtaman.github.io/washi/"><img src="https://img.shields.io/badge/docs-online-blue" alt="docs" /></a>
     <a href="https://ohtaman.github.io/washi/demo/"><img src="https://img.shields.io/badge/demo-playground-brightgreen" alt="live demo" /></a>
-    <a href="https://www.npmjs.com/package/@ohtaman/washi"><img src="https://img.shields.io/npm/v/@ohtaman/washi?color=crimson&label=npm" alt="npm version" /></a>
-    <a href="https://bundlephobia.com/package/@ohtaman/washi"><img src="https://img.shields.io/badge/bundle%20size-7.2%20kB%20(gzip)-blue" alt="bundle size" /></a>
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license" /></a>
-    <img src="https://img.shields.io/badge/types-TypeScript-blue" alt="TypeScript types" />
-    <img src="https://img.shields.io/badge/tests-120%2B%20passing-brightgreen" alt="tests" />
   </p>
 </div>
 
 ---
 
-**WaSHI** is a high-level algebraic modeling library that brings the expressive elegance of Python's **PuLP** and Julia's **JuMP** to the modern TypeScript and JavaScript ecosystem. Formulate mathematical models using natural algebraic equations and solve them instantly across Node.js, browsers, Bun, Deno, and Next.js—powered natively by WebAssembly solvers (**HiGHS**, **Z3**, and **GLPK**) with zero native compilation steps.
+**WaSHI** is an algebraic modeler for TypeScript and JavaScript, inspired by Python's **PuLP** and Julia's **JuMP**. Define variables, objectives, and arithmetic or logical constraints in application code. WaSHI constructs the model, translates it for a solver adapter, and maps results back to your variables. **HiGHS**, **Z3**, and **GLPK** perform the optimization or satisfiability checks.
+
+HiGHS is the default solver; Z3 and GLPK are optional plugins. The package provides Node.js and browser distributions, including WebAssembly assets. See the [browser integration guide](#-browser--web-worker-usage) for deployment requirements.
+
+[Try the browser demo](https://ohtaman.github.io/washi/demo/) · [Browse example source code](https://github.com/ohtaman/washi/blob/main/examples/README.md) · [ESM / script / CodePen examples](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)
 
 ```ts
-import { Model, expr, c } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 
-const m = new Model({ sense: "Maximize" });
-const x = m.addVar({ type: "Integer", lb: 0 });
-const y = m.addVar({ type: "Integer", lb: 0 });
+const m = new Model("WoodworkingProfit");
+const x = m.integer("desks", { lb: 0 });
+const y = m.integer("chairs", { lb: 0 });
 
 m.maximize(expr`30 * ${x} + 50 * ${y}`);
-m.addConstraint(c`${x} + 2 * ${y} <= 40`, "wood_limit");
-m.addConstraint(c`2 * ${x} + ${y} <= 50`, "labor_limit");
+m.constrain(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+m.constrain(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
 
-await m.solve();
+await m.optimize();
 console.log(`Produce: x=${x.value}, y=${y.value} (Profit: $${m.objectiveValue})`);
 ```
 
 ---
 
-## 🎯 Why WaSHI?
+## 🎯 What WaSHI provides
 
-1. 🌐 **100% Client-Side & Zero Server Cost**: Run industrial-grade optimization entirely inside the user's browser, edge worker, or Electron app. Zero backend server costs, offline-ready, and 100% private (confidential business data never leaves the client device).
-2. 📦 **Frictionless Zero-Dependency Distribution**: No Python runtimes, no C/C++ compilation, and no OS-dependent native solver binaries to bundle. Just `npm install @ohtaman/washi`—everything (including WebAssembly solvers) works instantly out of the box.
-3. ✍️ **Familiar Algebraic Modeling (PuLP & python-mip DX)**: Never struggle with low-level matrix indices. Formulate models naturally using tagged template literals (`c`${x} + 2 * ${y} <= 40``) or drop-in PuLP/python-mip syntax (`LpProblem`, `lpSum`).
-4. 🔄 **Pluggable Solvers & Unified API**: Formulate your mathematical model once; solve with **HiGHS** (industrial MIP/QP), **Z3** (SMT logic & Unsat Core diagnosis), or **GLPK** with a single parameter.
-5. 🔍 **Automatic Conflict Diagnosis (`unsatCore`)**: When constraints are contradictory (Infeasible), diagnose root causes by extracting a conflicting constraint subset (unsatisfiable core) via the Z3 engine.
-6. ⚡ **Industrial Scale Performance in WebAssembly**: Built with an $O(N)$ linear-time expression builder. Formulate 20,000+ variable MIPs in ~100ms and solve them in ~15 seconds right inside WebAssembly via HiGHS.
+1. **Algebraic model construction**: Formulate optimization models using domain-specific variable constructors (`m.binary`, `m.integer`, `m.continuous`), tagged template literals (`expr`), vector aggregations (`dot`, `sum`), and first-class constraints (`m.constrain`).
+2. **Solver adapters**: Use a common modeling API with HiGHS, Z3, or GLPK, or [register your own adapter](https://github.com/ohtaman/washi/blob/main/docs/custom-solver-guide.md). Choose an engine that supports the model's problem class; the adapters do not make every solver support every feature.
+3. **Local execution and WebAssembly distribution**: With the local solver adapters, solving runs in the application without a separate Python service or native C/C++ build. Browser deployments must include the generated JS, Worker, and WASM assets. Offline use also requires those resources to be available locally or cached. Z3 has additional browser isolation requirements.
+4. **Named constraints and SMT results**: With Z3, explicitly check satisfiability and inspect an unsatisfiable core to investigate conflicting constraints. A returned core is a conflicting subset, not necessarily the smallest one.
+
+Model construction and translation are WaSHI's responsibility. Supported problem classes, numerical behavior, and solve time depend on the selected solver, its settings, and the problem. Modeling overhead and solver execution time should be measured separately; a result for one model is not a general performance guarantee.
 
 ---
 
-## ⚡ Solvers Matrix
+## ⚙️ Solver adapters and capabilities
 
-| Solver | Engine License | Problem Classes | Best For | Status in WaSHI |
+| Adapter | Engine license | Supported problem classes | Engine role | Integration |
 | :--- | :--- | :--- | :--- | :--- |
-| **HiGHS** | **MIT** | **LP, MIP, Convex QP** | Industrial-scale optimization, production planning, finance | **Built-in default** (zero-config) |
-| **Z3** | **MIT** | **SMT, SAT, Logic, MIP** | Propositional logic, conflict diagnosis (`unsatCore`), rule engines | Optional plugin (`@ohtaman/washi/solvers/z3`) |
-| **GLPK** | **GPL-3.0** | **LP, MIP** | Academic benchmarks, legacy GLPK compatibility | Optional plugin (`@ohtaman/washi/solvers/glpk`) |
-| **Mock** | **MIT** | *Any* | Ultra-fast unit testing in CI without loading WebAssembly | Built-in |
+| **HiGHS** | **MIT** | **LP, MIP, convex QP** | Numerical optimization | Built-in default |
+| **Z3** | **MIT** | **SMT, SAT, logic, MIP** | Satisfiability checks, unsatisfiable cores, optimization | Optional plugin (`@ohtaman/washi/solvers/z3`) |
+| **GLPK** | **GPL-3.0** | **LP, MIP** | Linear and mixed-integer optimization | Optional plugin (`@ohtaman/washi/solvers/glpk`) |
+| **Mock** | **MIT** | — | Simulated solver responses for integration tests | Built-in; does not solve the model |
 
 ---
 
@@ -99,49 +101,49 @@ npm install glpk.js      # For GLPK solver (GPL-3.0)
 Formulate production scheduling, resource allocation, and facility location problems:
 
 ```ts
-import { Model, c, expr } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 
-const m = new Model({ name: "FactoryPlanning", sense: "Maximize" });
+const m = new Model("FactoryPlanning");
 
 // Decision variables (Integer, non-negative)
-const chairs = m.addVar({ name: "chairs", type: "Integer", lb: 0 });
-const tables = m.addVar({ name: "tables", type: "Integer", lb: 0 });
+const chairs = m.integer("chairs", { lb: 0 });
+const tables = m.integer("tables", { lb: 0 });
 
 // Natural formula objective & constraints via Tagged Template Literals
 m.maximize(expr`30 * ${chairs} + 50 * ${tables}`);
-m.addConstraint(c`${chairs} + 2 * ${tables} <= 40`, "wood_limit");
-m.addConstraint(c`2 * ${chairs} + ${tables} <= 50`, "labor_limit");
+m.constrain(expr`${chairs} + 2 * ${tables} <= 40`, "wood_limit");
+m.constrain(expr`2 * ${chairs} + ${tables} <= 50`, "labor_limit");
 
 // Solve using default HiGHS WASM engine
-const status = await m.solve();
+const status = await m.optimize();
 
 console.log(`Status: ${status}`); // "Optimal"
 console.log(`Objective: $${m.objectiveValue}`); // 1100
 console.log(`Chairs: ${chairs.value}, Tables: ${tables.value}`); // 20 chairs, 10 tables
 ```
 
-#### 🗂 Multidimensional Variables Grid (`addVars`)
+#### 🗂 Multidimensional Variables Grid
 
-Construct variable arrays or multi-index matrices in one line (similar to PuLP's `LpVariable.dicts`):
+Construct variable arrays or multi-index matrices in one call:
 
 ```ts
 // 1D dictionary of binary variables
-const openCity = m.addVars(["Tokyo", "Osaka", "Nagoya"], { type: "Binary" });
+const openCity = m.binary(["Tokyo", "Osaka", "Nagoya"]);
 
 // 2D transport flow matrix: [Factory] x [Store]
-const flow = m.addVars(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0 });
+const flow = m.continuous(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0 });
 
 // 2D coordinate grid (e.g. 8x8 chessboard)
-const board = m.addVars(8, 8, { type: "Binary", prefix: "queen" });
+const board = m.binary(8, 8, { prefix: "queen" });
 ```
 
-#### 🔀 Big-M Indicator Constraints (`addIndicator`)
+#### 🔀 Big-M Indicator Constraints (`m.indicator`)
 
 Model conditional activation rules and fixed-charge economics without manual Big-M algebra:
 
 ```ts
 // If factory is closed (openCity['Tokyo'] == 0), its production capacity must be 0
-m.addIndicator(openCity["Tokyo"], flow["F1"]["StoreA"].le(0), {
+m.indicator(openCity["Tokyo"], expr`${flow["F1"]["StoreA"]} <= 0`, {
   activeValue: 0,
   M: 1000,
 });
@@ -154,20 +156,21 @@ m.addIndicator(openCity["Tokyo"], flow["F1"]["StoreA"].le(0), {
 Minimize investment risk based on a covariance matrix subject to return and budget constraints:
 
 ```ts
-import { Model, QuadExpr, sum } from "@ohtaman/washi";
+import { Model, QuadExpr, sum, dot, expr } from "@ohtaman/washi";
 
-const m = new Model({ name: "MarkowitzPortfolio", sense: "Minimize" });
+const m = new Model("MarkowitzPortfolio");
 const assets = ["Tech", "Bonds", "RealEstate"];
 const returns = [0.14, 0.04, 0.08];
 
 // Decision variables: portfolio allocation weights (0 to 1)
-const w = assets.map((a) => m.addVar({ name: `w_${a}`, lb: 0, ub: 1 }));
+const w = m.continuous(assets, { lb: 0, ub: 1 });
 
 // 1. Fully invested budget: sum(w) == 1.0
-m.addConstraint(sum(w).eq(1.0), "budget");
+m.constrain(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget");
 
 // 2. Minimum target return: portfolio return >= 8.5%
-m.addConstraint(sum(w.map((v, i) => v.mul(returns[i]))).ge(0.085), "min_return");
+const retMap = Object.fromEntries(assets.map((a, i) => [a, returns[i]]));
+m.constrain(expr`${dot(retMap, w)} >= 0.085`, "min_return");
 
 // 3. Covariance risk matrix
 const cov = [
@@ -180,15 +183,15 @@ const cov = [
 let risk = new QuadExpr();
 for (let i = 0; i < assets.length; i++) {
   for (let j = 0; j < assets.length; j++) {
-    risk = risk.add(w[i].mul(w[j]).mul(cov[i][j]));
+    risk = risk.add(w[assets[i]].mul(w[assets[j]]).mul(cov[i][j]));
   }
 }
 m.minimize(risk);
 
-await m.solve();
+await m.optimize();
 console.log(`Minimal Variance: ${m.objectiveValue?.toFixed(6)}`);
-assets.forEach((name, i) => {
-  console.log(`  ${name}: ${((w[i].value || 0) * 100).toFixed(2)}%`);
+assets.forEach((name) => {
+  console.log(`  ${name}: ${((w[name].value || 0) * 100).toFixed(2)}%`);
 });
 ```
 
@@ -199,7 +202,8 @@ assets.forEach((name, i) => {
 Express boolean variables, propositional connectives (`and`, `or`, `implies`, `not`, `xor`), and mixed arithmetic rules:
 
 ```ts
-import { Model, not } from "@ohtaman/washi";
+import { Model, not, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
 
 const m = new Model({ name: "SmartSecurityRules" });
 
@@ -207,16 +211,16 @@ const isNight = m.addBoolVar("isNight");
 const motion = m.addBoolVar("motion");
 const alarm = m.addBoolVar("alarm");
 const siren = m.addBoolVar("siren");
-const lux = m.addVar({ name: "lux", type: "Integer", lb: 0 });
+const lux = m.integer("lux", { lb: 0 });
 
 // Logical rules
-m.addConstraint(lux.le(50).implies(isNight), "dark_implies_night");
-m.addConstraint(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
+m.constrain(lux.le(50).implies(isNight), "dark_implies_night");
+m.constrain(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
 
 // Current sensor observations
-m.addConstraint(lux.le(10), "sensor_dark");
-m.addConstraint(motion, "sensor_motion");
-m.addConstraint(alarm, "alarm_on");
+m.constrain(expr`${lux} <= 10`, "sensor_dark");
+m.constrain(motion, "sensor_motion");
+m.constrain(alarm, "alarm_on");
 
 // Check satisfiability and deduce state without an objective function
 const res = await m.check({ solver: "z3" });
@@ -232,28 +236,28 @@ console.log(`Siren active? ${m.values.get("siren")}`); // true
 When business rules or constraints contradict each other, extract a **conflicting constraint subset** (unsatisfiable core; minimality is not guaranteed) for troubleshooting (requires Z3):
 
 ```ts
-import { Model } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/z3";
 
 const m = new Model({ name: "ConflictDiagnosis", solver: "z3" });
-const engineers = m.addVar({ name: "engineers", type: "Integer", lb: 0, ub: 20 });
-const budget = m.addVar({ name: "budget", type: "Continuous", lb: 0, ub: 100000 });
+const engineers = m.integer("engineers", { lb: 0, ub: 20 });
+const budget = m.continuous("budget", { lb: 0, ub: 100000 });
 const rushDelivery = m.addBoolVar("rushDelivery");
 
 // Rule 1: Each engineer costs $8,000
-m.addConstraint(engineers.mul(8000).le(budget), "budget_limit");
+m.constrain(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
 
 // Rule 2: Customer requires rush delivery
-m.addConstraint(rushDelivery, "rush_required");
+m.constrain(rushDelivery, "rush_required");
 
 // Rule 3: Rush delivery requires at least 8 engineers
-m.addConstraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+m.constrain(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
 
 // Rule 4: Hard board budget cap of $50,000 (Conflict: 8 * $8000 = $64,000 > $50,000!)
-m.addConstraint(budget.le(50000), "strict_board_budget_cap");
+m.constrain(expr`${budget} <= 50000`, "strict_board_budget_cap");
 
 // Rule 5: Innocent bystander rule
-m.addConstraint(engineers.ge(1), "minimum_one_employee");
+m.constrain(expr`${engineers} >= 1`, "minimum_one_employee");
 
 const res = await m.check({ solver: "z3" });
 
@@ -265,35 +269,54 @@ console.log("Conflicting constraints:", res.unsatCore);
 
 ---
 
-### 5. Python PuLP Compatibility Layer
+### 5. Solving with GLPK (GPL-3.0)
+
+To use the GNU Linear Programming Kit (GLPK) solver plugin:
+
+```ts
+import { Model, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/glpk";
+
+const m = new Model({ solver: "glpk" });
+const x = m.integer("x", { lb: 0 });
+const y = m.integer("y", { lb: 0 });
+
+m.maximize(expr`30 * ${x} + 50 * ${y}`);
+m.constrain(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+m.constrain(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
+
+const status = await m.optimize();
+console.log(`Status: ${status}`); // "Optimal"
+console.log(`Objective: ${m.objectiveValue}`); // 1100
+```
+
+---
+
+### 6. Vector Operations & Fast Dot Product
 
-If you have existing Python PuLP code, port it with near zero friction:
+Cleanly compute 1D/2D linear combinations without nested loops:
 
 ```ts
-import {
-  LpProblem,
-  LpVariable,
-  LpMaximize,
-  LpInteger,
-  HiGHS,
-  value,
-} from "@ohtaman/washi";
-
-const prob = new LpProblem("PuLPDemo", LpMaximize);
-
-const x = new LpVariable("x", 0, undefined, LpInteger);
-const y = new LpVariable("y", 0, undefined, LpInteger);
-
-// PuLP += equivalent
-prob.add(x.mul(30).add(y.mul(50)));
-prob.add(x.add(y.mul(2)).le(40));
-prob.add(x.mul(2).add(y).le(50));
-
-await prob.solve(new HiGHS());
-
-console.log(`Status: ${prob.status}`);
-console.log(`Objective: ${value(prob.objective)}`);
-console.log(`x = ${value(x)}, y = ${value(y)}`);
+import { Model, dot } from "@ohtaman/washi";
+
+const m = new Model();
+const factories = ["Tokyo", "Osaka"];
+const stores = ["StoreA", "StoreB"];
+
+const costs = {
+  Tokyo: { StoreA: 4, StoreB: 7 },
+  Osaka: { StoreA: 8, StoreB: 3 },
+};
+
+const ship = m.continuous(factories, stores);
+
+// Total transportation cost in one line:
+m.minimize(dot(costs, ship));
+await m.optimize();
+
+// Extract all optimal variable values as a structured object
+const solution = m.getValues(ship);
+console.log(solution);
 ```
 
 ---
@@ -341,7 +364,52 @@ The package also includes `dist/browser/washi.min.js`, which exports the `Washi`
 
 For CDN usage, replace the local URL with `https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.1.2/dist/browser/washi.min.js` (or pin your desired release version `>= 0.1.2`). For ESM use the corresponding `dist/browser/washi.js` URL. Selecting the CDN URL is an explicit choice; local copies never switch to a CDN.
 
-The browser builds include the HiGHS engine, not the optional GLPK/Z3 engines. Use the npm package and optional dependencies for those integrations. `examples/distribution/` contains complete ESM and script examples.
+### Solver Plugins in the Browser (GLPK & Z3)
+
+The browser distribution includes pre-bundled, standalone solver plugins under `dist/browser/solvers/` (available from `>= 0.2.0` or `@latest` on CDN):
+- **GLPK**: `dist/browser/solvers/glpk.js` (ESM) and `dist/browser/solvers/glpk.min.js` (IIFE, registers global `WashiGLPK`)
+- **Z3**: `dist/browser/solvers/z3.js` (ESM) and `dist/browser/solvers/z3.min.js` (IIFE, registers global `WashiZ3`), accompanied by `z3-built.js` and `z3-built.wasm`
+
+#### Browser ESM with GLPK
+```html
+<script type="module">
+  import { Model } from "./washi/washi.js";
+  import "./washi/solvers/glpk.js";
+
+  const model = new Model({ solver: "glpk" });
+  const x = model.addVar({ lb: 0, ub: 10 });
+  model.maximize(x);
+  await model.solve();
+  console.log("GLPK status:", model.status);
+</script>
+```
+
+#### Plain Script with GLPK
+```html
+<script src="./washi/washi.min.js"></script>
+<script src="./washi/solvers/glpk.min.js"></script>
+<script>
+  const model = new Washi.Model({ solver: "glpk" });
+  const x = model.addVar({ lb: 0, ub: 10 });
+  model.maximize(x);
+  model.solve().then(status => console.log("GLPK status:", status));
+</script>
+```
+
+> [!NOTE]
+> **Z3 in Browser Environments & Cross-Origin Isolation**:
+> Because the Z3 WebAssembly engine uses multithreading (`SharedArrayBuffer`), modern browsers require cross-origin isolation. The HTML document response must send:
+> ```http
+> Cross-Origin-Opener-Policy: same-origin
+> Cross-Origin-Embedder-Policy: require-corp
+> ```
+> And any cross-origin assets must serve `Cross-Origin-Resource-Policy: cross-origin`.
+> 
+> General static sites without custom header control (e.g. standard GitHub Pages or preview platforms) and third-party iframe embeds (e.g. CodePen / JSFiddle) do not satisfy these requirements without extra setup. Importing `@ohtaman/washi` never automatically injects or registers a Service Worker into consumer applications.
+> 
+> To enable Z3 on GitHub Pages, the official WaSHI Web Demo bundles a dedicated `coi-serviceworker.js` strictly scoped to `/washi/`. On fresh browser sessions, it registers the worker and reloads once to establish `window.crossOriginIsolated === true` before running Z3. Environments lacking Service Workers or failing isolation abort Z3 execution with a descriptive explanation rather than hanging.
+
+Complete standalone examples for ESM, script tags, and CodePen are available in `examples/distribution/`.
 
 ### Offline distribution, Workers and custom hosting
 
@@ -364,32 +432,54 @@ Failed initialization reports the attempted URL and does not try a different hos
 
 ---
 
-## 💻 CLI & Interactive Demos
+## 🛠️ Custom Solvers & Extensibility
 
-Ready-to-run standalone examples are available in `examples/node/`:
+WaSHI features a decoupled, pluggable solver architecture. You can easily build and register your own custom solver adapter (e.g., for cloud REST optimizers, WebAssembly engines, or proprietary solvers):
 
-```bash
-npx tsx examples/node/01-production-planning.ts
-npx tsx examples/node/02-knapsack-problem.ts
-npx tsx examples/node/03-portfolio-qp.ts
-npx tsx examples/node/04-smt-security-rules.ts
-npx tsx examples/node/05-unsat-core-diagnosis.ts
-npx tsx examples/node/06-pulp-compatibility.ts
-```
+- See the complete [Custom Solver Developer Guide](docs/custom-solver-guide.md) for step-by-step tutorials, complete API contracts (`Solver`, `LpModelData`, `SolverResult`), and testing best practices.
+
+---
+
+## 💻 Examples and browser demo
 
-To run the interactive browser showcase (`examples/web-demo`):
+Start with the [example gallery](https://github.com/ohtaman/washi/blob/main/examples/README.md) or the [online Example & Feature Finder](https://ohtaman.github.io/washi/examples/), which organize examples by problem category and by WaSHI API feature.
+
+| Category | Example | What it demonstrates | Solver |
+| :--- | :--- | :--- | :--- |
+| **Fundamentals** | [Production planning](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) | Integer variables, a profit objective, and resource constraints (`expr`, `c`) | HiGHS |
+| **Fundamentals** | [Transportation network](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) | 2D origin-destination variable matrix (`addVars(rows, cols)`) and flow balance | HiGHS |
+| **Fundamentals** | [Diet & sensitivity analysis](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) | Shadow prices (`constr.dual`), surpluses (`constr.slack`), and reduced costs (`var.reducedCost`) | HiGHS |
+| **Practical** | [Staff shift scheduling](https://github.com/ohtaman/washi/blob/main/examples/node/11-shift-scheduling.ts) | Weekly roster optimization + diagnosing conflicting Saturday vacation requests | HiGHS + Z3 |
+| **Practical** | [E-commerce coupon optimizer](https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts) | Conditional spend thresholds (`addIndicator`), coupon exclusivity, and add-on recommendations | HiGHS |
+| **Practical** | [Portfolio allocation](https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts) | A convex quadratic objective (`QuadExpr`) with allocation constraints | HiGHS |
+| **Logic / SMT** | [Business rule checks](https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts) | Arithmetic and Boolean constraints (`addBoolVar`, `implies`) with satisfiability checking | Z3 |
+| **Logic / SMT** | [Conflict diagnosis](https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts) | Named constraints and an unsatisfiable core (`unsatCore`) | Z3 |
+
+[Open the hosted demo](https://ohtaman.github.io/washi/demo/) to edit and run models in your browser. For browser ESM, classic script tags, and CodePen, see the [distribution examples](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md). Z3 requires cross-origin isolation; see the browser requirements above.
+
+To run examples locally, clone the repository and install its development dependencies first:
 
 ```bash
+git clone https://github.com/ohtaman/washi.git
+cd washi
+npm ci
+npx tsx examples/node/01-production-planning.ts
+npx tsx examples/node/09-transportation-problem.ts
+npx tsx examples/node/10-diet-sensitivity.ts
+npx tsx examples/node/11-shift-scheduling.ts
+npx tsx examples/node/12-ecommerce-coupon-optimizer.ts
+
+# Local browser demo: http://localhost:5173/demo/
 npm run dev
-# Documentation: http://localhost:5173/
-# Interactive Demo: http://localhost:5173/demo/
 ```
 
+The example sources import the repository's `src/` modules. In an application using the published package, import `@ohtaman/washi` and the required solver plugin instead.
+
 ---
 
 ## 🧪 Testing
 
-WaSHI is developed with strict Test-Driven Development (TDD) across 120+ unit, integration, and large-scale test cases:
+Run the repository's unit and integration tests, and build the distributions:
 
 ```bash
 # Run all unit and integration tests