@ohtaman/washi 0.1.2 → 0.2.0

package/README.ja.md

@@ -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" });
 
@@ -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 最適化スクリプトをスムーズに移植：
 
@@ -341,7 +365,48 @@ await model.solve();
 
 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 へ切り替わることはありません。
 
-ブラウザ用ビルドに含まれるエンジンは HiGHS です。GLPK / Z3 エンジンの連携には npm パッケージと任意依存を使ってください。完結した利用例は `examples/distribution/` にあります。
+### ブラウザ環境でのソルバープラグイン（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、自前配信
 
@@ -364,6 +429,14 @@ setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
 
 ---
 
+## 🛠️ カスタムソルバー開発と拡張性
+
+WaSHI は疎結合なプラグイン方式のソルバーアーキテクチャを採用しています。独自の最適化エンジン（クラウド REST ソルバー、WebAssembly エンジン、商用ソルバーアダプターなど）を容易に構築・登録できます：
+
+- 詳細な開発手順、API コントラクト仕様（`Solver`, `LpModelData`, `SolverResult`）、およびテスト手法については [Custom Solver Developer Guide](docs/custom-solver-guide.md) をご覧ください。
+
+---
+
 ## 💻 サンプルスクリプト & インタラクティブ Web デモ
 
 `examples/node/` 配下に実行可能なスタンドアロンスクリプトを用意しています：
@@ -375,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

@@ -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" });
 
@@ -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:
 
@@ -341,7 +365,48 @@ 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**:
+> 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
 
@@ -364,6 +429,14 @@ Failed initialization reports the attempted URL and does not try a different hos
 
 ---
 
+## 🛠️ 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
 
 Ready-to-run standalone examples are available in `examples/node/`:
@@ -375,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

@@ -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" });
 
@@ -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 代码资产，可零摩擦迁移：
 
@@ -341,7 +365,48 @@ await model.solve();
 
 若通过 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。
 
-浏览器构建包含 HiGHS 引擎，不包含可选的 GLPK / Z3 引擎。其他引擎集成请使用 npm 包及可选依赖。完整示例位于 `examples/distribution/`。
+### 浏览器环境中的求解器插件（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
 
@@ -364,6 +429,14 @@ setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
 
 ---
 
+## 🛠️ 自定义求解器开发与架构扩展
+
+WaSHI 采用完全解耦的插件式求解器架构。你可以轻松编写并注册自定义求解器适配器（如云端 REST 求解服务、定制 WebAssembly 引擎或商业求解器）：
+
+- 完整开发指南、接口契约（`Solver`, `LpModelData`, `SolverResult`）与测试实践详见 [Custom Solver Developer Guide](docs/custom-solver-guide.md)。
+
+---
+
 ## 💻 本地脚本与交互式 Web 演示
 
 在 `examples/node/` 中提供了即开即用的独立脚本：
@@ -375,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`)：

package/dist/browser/highs-worker.js

@@ -1,5 +1,5 @@
-import { c as e } from "./highs-loader-T47YOyos.js";
-//#region src/highs-worker.ts
+import { c as e } from "./loader-CVt4CloI.js";
+//#region src/modeler/solvers/highs/worker.ts
 self.onmessage = async (t) => {
 	let { type: n, id: r, lpString: i, options: a } = t.data;
 	if (n === "SOLVE") try {

package/dist/browser/{highs-loader-T47YOyos.js → loader-CVt4CloI.js}

@@ -8,7 +8,7 @@ function n() {
 	return t("highs.wasm");
 }
 //#endregion
-//#region src/highs-loader.ts
+//#region src/modeler/solvers/highs/loader.ts
 var r = "https://cdn.jsdelivr.net/npm/highs@1.15.3/build/highs.wasm", i = null, a = null, o = null;
 function s(e) {
 	o = e, i = null, a = null;
@@ -38,7 +38,7 @@ async function f(e = {}) {
 	if (i && a === n) return i;
 	a = n;
 	let r = (async () => {
-		let e = (await import("./highs-browser-runtime-D13gHOT5.js")).default;
+		let e = (await import("./browser-runtime-D13gHOT5.js")).default;
 		return await e({ locateFile: (e) => e.endsWith(".wasm") ? t : e });
 	})().catch((e) => {
 		i === r && (i = null, a = null);