@ohtaman/washi 0.1.1 → 0.2.0

package/README.ja.md

@@ -51,7 +51,7 @@ console.log(`生産量: x=${x.value}, y=${y.value} (最大利益: $${m.objective
 2. 📦 **ゼロ依存・単一パッケージでの圧倒的な配布容易性**: Python のランタイム管理や仮想環境、OS 別の C/C++ ネイティブソルバーバイナリの同梱に悩まされることはありません。`npm install @ohtaman/washi` だけで WebAssembly ソルバーを含めて即座に動作します。
 3. ✍️ **直感的な代数モデリング DX（PuLP / python-mip 互換）**: 泥臭い行列のインデックス操作は不要。テンプレートリテラル記法（`c`${x} + 2 * ${y} <= 40``）や、Python 最適化開発者におなじみの構文（`LpProblem`, `lpSum`）で、教科書そのままの数式を記述できます。
 4. 🔄 **統一マルチソルバー API（HiGHS / Z3 / GLPK）**: 定式化したモデルコードはそのまま、産業用 MIP/QP に強い **HiGHS**、論理制約・SMT に強い **Z3**、学術用途の **GLPK** をオプション1つで柔軟に切り替え可能です。
-5. 🔍 **実行不可能（Infeasible）時の矛盾原因自動診断**: ルール同士が矛盾して解なしになった場合、どの制約同士が衝突しているかの最小部分集合（Unsat Core）を Z3 エンジン経由で瞬時に特定・診断します。
+5. 🔍 **実行不可能（Infeasible）時の矛盾原因自動診断**: ルール同士が矛盾して解なしになった場合、衝突している制約の部分集合（Unsat Core）を Z3 エンジン経由で特定・診断します。
 6. ⚡ **WebAssembly 上での本格的な産業規模パフォーマンス**: 線形時間 $O(N)$ の高速式ビルダーにより、20,000 変数を超える大規模 MIP を約100msで定式化し、WebAssembly 版 HiGHS で約15秒で高速に求解します。
 
 ---
@@ -200,6 +200,7 @@ assets.forEach((name, i) => {
 
 ```ts
 import { Model, not } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
 
 const m = new Model({ name: "SmartSecurityRules" });
 
@@ -229,7 +230,7 @@ console.log(`サイレン作動？ ${m.values.get("siren")}`); // true
 
 ### 4. 矛盾原因の自動特定 (`unsatCore`)
 
-業務ルールや制約群が互いに矛盾している場合、**矛盾を引き起こしている最小の制約サブセット**を特定してデバッグ（Z3 が必要）：
+業務ルールや制約群が互いに矛盾している場合、**矛盾を引き起こしている制約の部分集合**（Unsat Core。最小性は保証しません）を特定してデバッグ（Z3 が必要）：
 
 ```ts
 import { Model } from "@ohtaman/washi";
@@ -265,7 +266,30 @@ console.log("矛盾している制約:", res.unsatCore);
 
 ---
 
-### 5. Python PuLP 互換レイヤー
+### 5. GLPK ソルバーの利用 (GPL-3.0)
+
+GNU Linear Programming Kit (GLPK) ソルバープラグインを利用する場合：
+
+```ts
+import { Model, expr, c } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/glpk";
+
+const m = new Model({ sense: "Maximize", solver: "glpk" });
+const x = m.addVar({ type: "Integer", lb: 0 });
+const y = m.addVar({ type: "Integer", 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");
+
+const status = await m.solve();
+console.log(`ステータス: ${status}`); // "Optimal"
+console.log(`目的関数値: ${m.objectiveValue}`); // 1100
+```
+
+---
+
+### 6. Python PuLP 互換レイヤー
 
 既存の Python PuLP 最適化スクリプトをスムーズに移植：
 
@@ -300,40 +324,117 @@ console.log(`x = ${value(x)}, y = ${value(y)}`);
 
 ## 🌐 ブラウザ & Web Worker での利用方法
 
-WaSHI は、モダンなブラウザ、フロントエンドフレームワーク（Vite, Next.js, React, Vue, Svelte）、および Web Worker 上でゼロコンフィグで動作するように設計されています。
+HiGHS はデフォルトでパッケージ同梱 WASM を使います。**CDN への自動フォールバックはありません。** Node.js はインストールされた HiGHS を使い、Vite / webpack 5 はパッケージ内の WASM・Worker 参照から配布ファイルを生成します。
 
-### 1. ゼロコンフィグ動作（公式 CDN 自動フォールバック）
-ブラウザ環境において、オリジンルートに `highs.wasm` が配置されていない場合、WaSHI は自動的に公式 jsDelivr CDN から安全にバイナリを取得します。追加の設定コードやファイルコピーは一切不要です：
+### npm とバンドラー
 
 ```typescript
 import { Model } from "@ohtaman/washi";
-
 const model = new Model();
-// ... 変数・制約の定義
-await model.solve(); // 設定なしで即座に動作！
+// 変数・目的関数・制約を定義
+await model.solve();
 ```
 
-### 2. モダンバンドラーでの自前アセット管理（Vite / Webpack / Rollup）
-`highs.wasm` を自分のアプリケーションの静的アセット（ハッシュ付き配信）として自前ホストしたい場合：
+検証対象の Vite / webpack ビルドでは WASM の手動コピー・URL 指定は不要です。その他のバンドラーや SSR は個別に確認し、ブラウザの求解はクライアントで実行してください。ブラウザでは Worker をデフォルトで使用します。簡単なデモは `model.solve({ useWorker: false })` でも動きますが、長い計算中は UI が止まります。
 
-```typescript
-import wasmUrl from "@ohtaman/washi/highs.wasm?url";
-import { setHighsWasmUrl } from "@ohtaman/washi";
+### ブラウザ標準 ESM（利用者側のビルド不要）
 
-// アプリ起動時に一度だけ設定
-setHighsWasmUrl(wasmUrl);
+`dist/browser` 一式（JS の分割ファイル・`highs.wasm`・Worker を含む）を HTTP 配信します。Import Maps は不要です。
+
+```html
+<script type="module">
+  import { Model } from "./washi/washi.js";
+  const model = new Model();
+  // 変数・目的関数・制約を定義
+  await model.solve({ useWorker: false });
+</script>
 ```
 
-### 3. 社内イントラ・完全オフライン（Air-gapped）環境での利用
-外部 CDN への通信が禁止されている社内イントラやオフライン環境の場合：
+### 通常の script / CodePen
 
-```typescript
-import { setHighsWasmUrl } from "@ohtaman/washi";
+`dist/browser/washi.min.js` はグローバル API `Washi` を公開します。CodePen の External Scripts にその URL を追加するか、次のように読み込みます。
+
+```html
+<script src="./washi/washi.min.js"></script>
+<script>
+  const model = new Washi.Model();
+  // 変数・目的関数・制約を定義
+  model.solve({ useWorker: false }).then(status => console.log(status));
+</script>
+```
+
+CDN から直接読み込む場合は、URL を `https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.1.2/dist/browser/washi.min.js`（`0.1.2` 以降のバージョンを固定）に指定できます。ESM は同じ版の `dist/browser/washi.js` を指定します。CDN の URL を選ぶことが明示的な CDN 利用になり、ローカル配信が勝手に CDN へ切り替わることはありません。
+
+### ブラウザ環境でのソルバープラグイン（GLPK & Z3）
+
+ブラウザ配布物には、`dist/browser/solvers/` 配下に事前バンドルされたスタンドアロンソルバープラグインが含まれています（CDN 利用時は `>= 0.2.0` または `@latest` で利用可能）：
+- **GLPK**: `dist/browser/solvers/glpk.js` (ESM) および `dist/browser/solvers/glpk.min.js` (IIFE、グローバル `WashiGLPK` を登録)
+- **Z3**: `dist/browser/solvers/z3.js` (ESM) および `dist/browser/solvers/z3.min.js` (IIFE、グローバル `WashiZ3` を登録)、ならびに `z3-built.js` / `z3-built.wasm`
+
+#### ブラウザ ESM での 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 ステータス:", model.status);
+</script>
+```
+
+#### スクリプトタグでの 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));
+</script>
+```
+
+> [!NOTE]
+> **ブラウザ環境での Z3 利用について**:
+> Z3 の WebAssembly エンジンはマルチスレッド（`SharedArrayBuffer`）を必要とするため、配信 Web サーバーがドキュメントレスポンスに以下の Cross-Origin-Isolation ヘッダーを送信する必要があります：
+> ```http
+> Cross-Origin-Opener-Policy: same-origin
+> Cross-Origin-Embedder-Policy: require-corp
+> ```
+> また、別オリジン（CDN など）からアセットを読み込む場合は `Cross-Origin-Resource-Policy: cross-origin` の返却が必要です。
+
+完全なスタンドアロンサンプル（ESM、スクリプトタグ、CodePen）は `examples/distribution/` に用意されています。
+
+### 工場内・オフライン配布、Worker、自前配信
 
-// 自前の静的ファイル配信パスを指定（外部 CDN へのフォールバックは完全無効化されます）
-setHighsWasmUrl("/static/highs.wasm");
+アプリのビルド出力一式、または `dist/browser` 一式をローカル HTTP サーバー・社内サーバーに配布します。必要なアセットがローカルにあれば、ブラウザのキャッシュが空でも外部ネットワークは不要です。HTML や最初の JS だけでは不足します。`file://` 実行や PWA の自動キャッシュは対象外です。
+
+ESM はモジュール URL、script 版は読み込み時に保持した script URL からアセットを解決します。CDN の Worker は Blob のモジュールから起動します。配信元の CORS と、CSP の script・通信先許可が必要です。CDN Worker では `worker-src blob:` も許可してください。使えない場合は `useWorker: false` を指定します。Worker の読み込み・メッセージ処理に失敗した場合は、求解 Promise がエラーになります。
+
+自前 URL は `setHighsWasmUrl(url)` / `options.wasmUrl` で指定できます。従来の HiGHS CDN を明示的に選ぶ場合：
+
+```typescript
+import { setHighsWasmUrl, OFFICIAL_HIGHS_CDN_WASM_URL } from "@ohtaman/washi";
+setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
 ```
 
+初期化に失敗すると取得先を含むエラーを返し、別ホストには切り替えません。従来のオリジンルート / CDN 自動フォールバックを利用していた場合は、生成アセットを配布するか URL を明示してください。
+
+### 配布物の検証
+
+`npm run test:distribution` は実際の npm tarball をインストールし、任意依存なしの Vite / webpack アプリをビルドして、生成 JS と実 WASM を VM で実行します。ブラウザ・CORS の検証とは別です。`npx playwright install chromium` 後に `RUN_DISTRIBUTION_BROWSER=1 npm run test:distribution` で Chromium の検証も実行できます。CI はそのモードを使い、別オリジン配信と外部ネットワーク遮断も確認します。
+
+---
+
+## 🛠️ カスタムソルバー開発と拡張性
+
+WaSHI は疎結合なプラグイン方式のソルバーアーキテクチャを採用しています。独自の最適化エンジン（クラウド REST ソルバー、WebAssembly エンジン、商用ソルバーアダプターなど）を容易に構築・登録できます：
+
+- 詳細な開発手順、API コントラクト仕様（`Solver`, `LpModelData`, `SolverResult`）、およびテスト手法については [Custom Solver Developer Guide](docs/custom-solver-guide.md) をご覧ください。
+
 ---
 
 ## 💻 サンプルスクリプト & インタラクティブ Web デモ
@@ -347,6 +448,7 @@ 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
+npx tsx examples/node/08-glpk-solver-plugin.ts
 ```
 
 ブラウザで動く Web デモ (`examples/web-demo`) を起動するには：

package/README.md

@@ -51,7 +51,7 @@ console.log(`Produce: x=${x.value}, y=${y.value} (Profit: $${m.objectiveValue})`
 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 instantly by extracting the minimal conflicting constraint subset via the Z3 engine.
+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.
 
 ---
@@ -200,6 +200,7 @@ Express boolean variables, propositional connectives (`and`, `or`, `implies`, `n
 
 ```ts
 import { Model, not } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
 
 const m = new Model({ name: "SmartSecurityRules" });
 
@@ -229,7 +230,7 @@ console.log(`Siren active? ${m.values.get("siren")}`); // true
 
 ### 4. Conflict Diagnosis (`unsatCore`)
 
-When business rules or constraints contradict each other, extract the **minimal conflicting subset** for instant troubleshooting (requires Z3):
+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";
@@ -265,7 +266,30 @@ 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, c } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/glpk";
+
+const m = new Model({ sense: "Maximize", solver: "glpk" });
+const x = m.addVar({ type: "Integer", lb: 0 });
+const y = m.addVar({ type: "Integer", 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");
+
+const status = await m.solve();
+console.log(`Status: ${status}`); // "Optimal"
+console.log(`Objective: ${m.objectiveValue}`); // 1100
+```
+
+---
+
+### 6. Python PuLP Compatibility Layer
 
 If you have existing Python PuLP code, port it with near zero friction:
 
@@ -300,40 +324,117 @@ console.log(`x = ${value(x)}, y = ${value(y)}`);
 
 ## 🌐 Browser & Web Worker Usage
 
-WaSHI is engineered for seamless execution in modern browsers, frontend frameworks (Vite, Next.js, React, Vue, Svelte), and Web Workers.
+The default HiGHS engine uses the package's WASM asset. There is **no automatic CDN fallback**. Node.js uses the installed HiGHS runtime; Vite and webpack 5 can discover the package-relative WASM and Worker references when building a browser application.
 
-### 1. Zero-Config Mode (Automatic CDN Fallback)
-In browser environments, if `highs.wasm` is not found on your local origin, WaSHI automatically falls back to the official jsDelivr CDN. You can optimize without copying files or writing boilerplate:
+### npm with a bundler
 
 ```typescript
 import { Model } from "@ohtaman/washi";
-
 const model = new Model();
-// ... define variables & constraints
-await model.solve(); // Works instantly with zero setup!
+// Define variables, objective and constraints.
+await model.solve();
 ```
 
-### 2. Bundler-Native Asset Hosting (Vite / Webpack / Rollup)
-To bundle and self-host `highs.wasm` as a versioned, hashed static asset with your application:
+No manual WASM copy or URL configuration is needed in the tested Vite / webpack builds. Other bundlers and SSR need their own integration checks; call the browser solver on the client. Worker execution is the browser default. Use `model.solve({ useWorker: false })` for a simple main-thread demo; a long solve will block the UI.
 
-```typescript
-import wasmUrl from "@ohtaman/washi/highs.wasm?url";
-import { setHighsWasmUrl } from "@ohtaman/washi";
+### Browser ESM without an application build
 
-// Configure once at app startup
-setHighsWasmUrl(wasmUrl);
+Serve the **entire `dist/browser` directory**, including its JS chunks, `highs.wasm` and Worker. No import map is needed:
+
+```html
+<script type="module">
+  import { Model } from "./washi/washi.js";
+  const model = new Model();
+  // Define variables, objective and constraints.
+  await model.solve({ useWorker: false });
+</script>
 ```
 
-### 3. Air-Gapped & Enterprise Offline Environments
-In strict enterprise intranet or air-gapped environments where external CDN network access is disallowed:
+### Plain script / CodePen
 
-```typescript
-import { setHighsWasmUrl } from "@ohtaman/washi";
+The package also includes `dist/browser/washi.min.js`, which exports the `Washi` global. Put that file's URL in CodePen's External Scripts, or use a script tag:
+
+```html
+<script src="./washi/washi.min.js"></script>
+<script>
+  const model = new Washi.Model();
+  // Define variables, objective and constraints.
+  model.solve({ useWorker: false }).then(status => console.log(status));
+</script>
+```
+
+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.
+
+### 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**:
+> Because the Z3 WebAssembly engine uses multithreading (`SharedArrayBuffer`), the hosting web server must send Cross-Origin-Isolation delivery headers on the document response:
+> ```http
+> Cross-Origin-Opener-Policy: same-origin
+> Cross-Origin-Embedder-Policy: require-corp
+> ```
+> And any cross-origin assets (e.g. from a CDN) must serve `Cross-Origin-Resource-Policy: cross-origin`.
+
+Complete standalone examples for ESM, script tags, and CodePen are available in `examples/distribution/`.
+
+### Offline distribution, Workers and custom hosting
 
-// Point strictly to your internal assets (completely disables CDN fallback)
-setHighsWasmUrl("/static/highs.wasm");
+Deploy the full application build or the entire browser distribution to a local HTTP / intranet server. With all assets locally available, an empty browser cache does not require access to the internet. Saving only the HTML or the first JS file is insufficient. `file://` execution and automatic PWA caching are not supported by this distribution.
+
+ESM assets resolve relative to their module URL; the script build captures its own script URL at load time. CDN Workers use a Blob module bootstrap. The server must permit cross-origin JS / WASM loading; CSP must permit the selected script / connection origins and `worker-src blob:` for CDN Workers. If that is unavailable, use `useWorker: false`. Worker load / message failures reject pending solves rather than leaving them unresolved.
+
+For custom hosting, `setHighsWasmUrl(url)` and `options.wasmUrl` remain available. To explicitly use the existing HiGHS CDN:
+
+```typescript
+import { setHighsWasmUrl, OFFICIAL_HIGHS_CDN_WASM_URL } from "@ohtaman/washi";
+setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
 ```
 
+Failed initialization reports the attempted URL and does not try a different host. This changes the previous local-root/CDN fallback behavior: deploy the generated assets or configure an explicit URL.
+
+### Verify the distributable
+
+`npm run test:distribution` packs and installs the actual npm tarball, builds Vite / webpack consumers without optional peers, and runs their emitted JS with real WASM in a VM. This is not a browser/CORS test. For Playwright Chromium checks, run `npx playwright install chromium` and `RUN_DISTRIBUTION_BROWSER=1 npm run test:distribution`. CI also runs that browser mode, including separate-origin browser bundles with external network requests blocked.
+
+---
+
+## 🛠️ Custom Solvers & Extensibility
+
+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):
+
+- 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.
+
 ---
 
 ## 💻 CLI & Interactive Demos
@@ -347,6 +448,7 @@ 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
+npx tsx examples/node/08-glpk-solver-plugin.ts
 ```
 
 To run the interactive browser showcase (`examples/web-demo`):

package/README.zh-CN.md

@@ -51,7 +51,7 @@ console.log(`生产计划: x=${x.value}, y=${y.value} (最大利润: $${m.object
 2. 📦 **零依赖・单一包分发**：告别 Python 环境配置与繁重的跨平台 C/C++ 原生求解器编译绑定。只需 `npm install @ohtaman/washi`，包括 WebAssembly 求解器在内的所有组件即可开箱即用。
 3. ✍️ **极简现代代数建模 DX（兼容 PuLP / python-mip）**：无需编写晦涩低级的矩阵索引。使用直观的模板字面量（`c`${x} + 2 * ${y} <= 40``）或熟悉的 Python 风格抽象（`LpProblem`, `lpSum`），像在草稿纸上写公式一样自然。
 4. 🔄 **统一多求解器接口（HiGHS / Z3 / GLPK）**：模型代码一次编写，即可通过统一 API 自由切换：擅长工业级 MIP/QP 的 **HiGHS**、擅长逻辑求解与冲突分析的 **Z3**，以及经典学术求解器 **GLPK**。
-5. 🔍 **不可行模型（Infeasible）冲突根因诊断**：当业务规则出现矛盾导致无解时，可通过 Z3 引擎快速定位并提取冲突约束的最小子集（Unsat Core）。
+5. 🔍 **不可行模型（Infeasible）冲突根因诊断**：当业务规则出现矛盾导致无解时，可通过 Z3 引擎快速定位并提取冲突约束子集（Unsat Core）。
 6. ⚡ **WebAssembly 原生工业级大规模性能**：搭载 $O(N)$ 线性时间高速表达式构建器，仅需约 100ms 即可构建 20,000+ 变量的大规模 MIP，并在浏览器 WebAssembly 中由 HiGHS 在约 15 秒内高效求解。
 
 ---
@@ -200,6 +200,7 @@ assets.forEach((name, i) => {
 
 ```ts
 import { Model, not } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
 
 const m = new Model({ name: "SmartSecurityRules" });
 
@@ -229,7 +230,7 @@ console.log(`警报响起？ ${m.values.get("siren")}`); // true
 
 ### 4. 约束冲突根因诊断 (`unsatCore`)
 
-当规则或约束之间存在矛盾时，Z3 能够精准指出引发冲突的**最小冲突约束子集**（需使用 Z3）：
+当规则或约束之间存在矛盾时，Z3 能够提取引发冲突的**矛盾约束子集**（Unsat Core，不保证最小性；需使用 Z3）：
 
 ```ts
 import { Model } from "@ohtaman/washi";
@@ -265,7 +266,30 @@ console.log("冲突约束子集:", res.unsatCore);
 
 ---
 
-### 5. Python PuLP 兼容层
+### 5. 使用 GLPK 求解器 (GPL-3.0)
+
+使用 GNU Linear Programming Kit (GLPK) 求解器插件：
+
+```ts
+import { Model, expr, c } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/glpk";
+
+const m = new Model({ sense: "Maximize", solver: "glpk" });
+const x = m.addVar({ type: "Integer", lb: 0 });
+const y = m.addVar({ type: "Integer", 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");
+
+const status = await m.solve();
+console.log(`求解状态: ${status}`); // "Optimal"
+console.log(`目标函数值: ${m.objectiveValue}`); // 1100
+```
+
+---
+
+### 6. Python PuLP 兼容层
 
 若你已有 Python PuLP 代码资产，可零摩擦迁移：
 
@@ -300,40 +324,117 @@ console.log(`x = ${value(x)}, y = ${value(y)}`);
 
 ## 🌐 浏览器与 Web Worker 使用指南
 
-WaSHI 原生支持在现代网页浏览器、前端主流框架（Vite、Next.js、React、Vue、Svelte）以及 Web Worker 中运行。
+HiGHS 默认使用包内的 WASM，**不会自动回退到 CDN**。Node.js 使用已安装的 HiGHS；Vite / webpack 5 可以根据包内的 WASM 和 Worker 引用生成部署文件。
 
-### 1. 零配置模式（官方 CDN 智能回退）
-在浏览器环境下，若当前域名根路径未部署 `highs.wasm`，WaSHI 会自动从官方 jsDelivr 高速 CDN 安全拉取二进制文件。您无需任何额外配置或文件复制：
+### npm 与构建工具
 
 ```typescript
 import { Model } from "@ohtaman/washi";
-
 const model = new Model();
-// ... 定义变量与约束
-await model.solve(); // 零配置即可直接运行！
+// 定义变量、目标函数和约束
+await model.solve();
 ```
 
-### 2. 现代打包工具自托管（Vite / Webpack / Rollup）
-如果您希望将 `highs.wasm` 作为项目打包产物的一部分进行自托管与版本哈希管理：
+在验证的 Vite / webpack 构建中，不需要手动复制 WASM 或配置 URL。其他构建工具及 SSR 需要单独验证；浏览器求解应在客户端执行。浏览器默认使用 Worker。简单演示可以使用 `model.solve({ useWorker: false })`，但较长的计算会阻塞 UI。
 
-```typescript
-import wasmUrl from "@ohtaman/washi/highs.wasm?url";
-import { setHighsWasmUrl } from "@ohtaman/washi";
+### 浏览器原生 ESM（无需应用构建）
 
-// 在应用入口处配置一次
-setHighsWasmUrl(wasmUrl);
+通过 HTTP 提供整个 `dist/browser` 目录，包括 JS 分块、`highs.wasm` 和 Worker。不需要 Import Maps。
+
+```html
+<script type="module">
+  import { Model } from "./washi/washi.js";
+  const model = new Model();
+  // 定义变量、目标函数和约束
+  await model.solve({ useWorker: false });
+</script>
 ```
 
-### 3. 企业内网与完全离线（Air-gapped）环境
-针对严禁外部 CDN 请求的企业内网或纯离线环境：
+### 普通 script / CodePen
 
-```typescript
-import { setHighsWasmUrl } from "@ohtaman/washi";
+`dist/browser/washi.min.js` 导出全局 API `Washi`。将其 URL 添加到 CodePen 的 External Scripts，或使用：
+
+```html
+<script src="./washi/washi.min.js"></script>
+<script>
+  const model = new Washi.Model();
+  // 定义变量、目标函数和约束
+  model.solve({ useWorker: false }).then(status => console.log(status));
+</script>
+```
+
+若通过 CDN 加载，可使用 `https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.1.2/dist/browser/washi.min.js`（请固定 `0.1.2` 及以上版本号）。ESM 使用同版本的 `dist/browser/washi.js`。选择 CDN URL 就是显式使用 CDN；本地部署不会自动改用外部 CDN。
+
+### 浏览器环境中的求解器插件（GLPK & Z3）
+
+浏览器发布包在 `dist/browser/solvers/` 下提供了开箱即用的独立求解器插件（通过 CDN 引入时适用于 `>= 0.2.0` 或 `@latest`）：
+- **GLPK**: `dist/browser/solvers/glpk.js` (ESM) 与 `dist/browser/solvers/glpk.min.js` (IIFE，挂载全局 `WashiGLPK`)
+- **Z3**: `dist/browser/solvers/z3.js` (ESM) 与 `dist/browser/solvers/z3.min.js` (IIFE，挂载全局 `WashiZ3`)，附带 `z3-built.js` 和 `z3-built.wasm`
+
+#### 浏览器 ESM 使用 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 求解状态:", model.status);
+</script>
+```
+
+#### 原生脚本标签使用 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));
+</script>
+```
+
+> [!NOTE]
+> **浏览器环境中使用 Z3 的配置要求**：
+> 由于 Z3 的 WebAssembly 引擎依托多线程 (`SharedArrayBuffer`)，承载页面的 Web 服务器必须在文档响应头中附带以下 Cross-Origin-Isolation 标头：
+> ```http
+> Cross-Origin-Opener-Policy: same-origin
+> Cross-Origin-Embedder-Policy: require-corp
+> ```
+> 此外，任何跨源静态资源（如来自 CDN）都必须返回 `Cross-Origin-Resource-Policy: cross-origin` 响应头。
+
+完整独立的 ESM、Script 标签与 CodePen 示例请参阅 `examples/distribution/`。
+
+### 工厂内网、离线部署、Worker 与自定义 URL
 
-// 指定内部静态资源路径（将完全禁用外部 CDN 回退）
-setHighsWasmUrl("/static/highs.wasm");
+将应用构建产物或整个 `dist/browser` 目录部署到本地 HTTP / 内网服务器。所有资源可在本地访问时，即使浏览器缓存为空也不需要外部网络。仅保存 HTML 或第一个 JS 文件是不够的。不保证 `file://` 执行，也不自动提供 PWA 缓存。
+
+ESM 根据模块 URL 解析资源；script 构建在加载时保存自身的 URL。CDN Worker 使用 Blob 模块启动，需要服务端的跨域资源许可及相应 CSP。CDN Worker 还需允许 `worker-src blob:`。不支持时可使用 `useWorker: false`。Worker 加载或消息处理失败会拒绝求解 Promise。
+
+自定义地址仍可通过 `setHighsWasmUrl(url)` 或 `options.wasmUrl` 指定。显式选择现有 HiGHS CDN：
+
+```typescript
+import { setHighsWasmUrl, OFFICIAL_HIGHS_CDN_WASM_URL } from "@ohtaman/washi";
+setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
 ```
 
+初始化失败会返回包含请求地址的错误，不会尝试其他主机。依赖旧的域名根目录 / CDN 自动回退的应用需部署生成资源或显式配置 URL。
+
+### 验证发布产物
+
+`npm run test:distribution` 安装实际 npm tarball，在没有可选依赖时构建 Vite / webpack 应用，并通过 VM 执行生成的 JS 和真实 WASM。这不等同于浏览器 / CORS 验证。安装 `npx playwright install chromium` 后，运行 `RUN_DISTRIBUTION_BROWSER=1 npm run test:distribution` 以验证 Chromium。CI 使用该模式，验证跨域部署及外部网络请求阻断。
+
+---
+
+## 🛠️ 自定义求解器开发与架构扩展
+
+WaSHI 采用完全解耦的插件式求解器架构。你可以轻松编写并注册自定义求解器适配器（如云端 REST 求解服务、定制 WebAssembly 引擎或商业求解器）：
+
+- 完整开发指南、接口契约（`Solver`, `LpModelData`, `SolverResult`）与测试实践详见 [Custom Solver Developer Guide](docs/custom-solver-guide.md)。
+
 ---
 
 ## 💻 本地脚本与交互式 Web 演示
@@ -347,6 +448,7 @@ 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
+npx tsx examples/node/08-glpk-solver-plugin.ts
 ```
 
 启动浏览器端交互式可视化演示 (`examples/web-demo`)：