@ohtaman/washi 0.4.0 → 0.5.0

package/docs/solvers/custom-solver.md

@@ -0,0 +1,525 @@
+# WaSHI Custom Solver Developer Guide
+
+This guide describes how to build, test, and distribute custom solver plugins for **WaSHI** (`@ohtaman/washi`).
+
+WaSHI features a pluggable, decoupled solver architecture. Core `@ohtaman/washi` bundles only the zero-config HiGHS WASM engine and a Mock solver. Any third-party solver—whether implemented in WebAssembly, native C++, a Web Worker, or an external cloud REST/RPC backend—can be registered and used through the unified `Model` API.
+
+---
+
+## 1. Pluggable Solvers Architecture Overview
+
+```mermaid
+graph TD
+    A[WaSHI Model] --> B[Solver Registry Map Symbol.for]
+    B --> C[HiGHS WASM Engine Core]
+    B --> D[Mock Solver Core]
+    B --> E[GLPK Plugin @ohtaman/washi/solvers/glpk]
+    B --> F[Z3 SMT Plugin @ohtaman/washi/solvers/z3]
+    B --> G[Your Custom Solver Plugin]
+```
+
+### Key Architectural Characteristics
+1. **Unified Global Registry**: The solver registry is backed by `Symbol.for("washi.solverRegistry")` on `globalThis`. This ensures that even across different ESM chunks, dynamic imports, or `<script>` tags, every bundle accesses the identical solver map.
+2. **Behavioral Symmetry**: Node.js and browser environments share identical error messages, solver naming, and capability handling.
+3. **Decoupled Bundling**: Core WaSHI does not import optional or custom plugins. A plugin only registers itself when explicitly imported.
+
+---
+
+## 2. API Contracts & TypeScript Interfaces
+
+All custom solvers must implement the `Solver` interface defined in `@ohtaman/washi`:
+
+```typescript
+import {
+  generateLpString,
+  buildLpSymbolMaps,
+  isLpExportResult,
+  sanitizeIdentifier,
+  type Solver,
+  type SolverOptions,
+  type SolverResult,
+  type SolverCheckResult,
+  type SolverCapabilities,
+  type SolveModelData,
+  type CheckModelData,
+  type LogicalConstraintItem,
+  type LpModelData,
+  type LpExportResult,
+  type LpSymbolMaps,
+  type SolverStatus,
+  type TerminationStatus,
+  type SolveProgressEvent,
+} from "@ohtaman/washi";
+```
+
+### The `Solver` Interface
+
+```typescript
+export interface Solver {
+  /** Unique human-readable name of the solver (e.g. "GLPK", "AcmeCloudSolver") */
+  readonly name: string;
+
+  /** Solver version string (e.g. "1.2.0") */
+  readonly version?: string;
+
+  /** Capability flags declaring which problem classes the solver supports */
+  readonly capabilities?: SolverCapabilities;
+
+  /**
+   * Main solve method for LP, MIP, QP, and SMT optimization models.
+   *
+   * @param modelData Typed in-memory model structure (variables, constraints, objective, sense, boolVars, logicalConstraints)
+   * @param options Runtime execution options (timeLimit, mipGap, verbose, signal, onProgress, etc.)
+   */
+  solve(
+    modelData: SolveModelData,
+    options?: SolverOptions
+  ): Promise<SolverResult>;
+
+  /**
+   * Optional check method for Pure SAT / SMT or feasibility checking without an objective.
+   *
+   * @param modelData Objective-free in-memory model structure (variables, boolVars, constraints, logicalConstraints)
+   * @param options Runtime execution options
+   */
+  check?(
+    modelData: CheckModelData,
+    options?: SolverOptions
+  ): Promise<SolverCheckResult>;
+}
+```
+
+### `CheckModelData` & `SolveModelData`
+
+`Model.solve()` and `Model.check()` pass the structured model directly to your adapter without serializing an LP string upfront:
+
+```typescript
+export interface CheckModelData {
+  /** Model name */
+  name?: string;
+  /** Decision variables registered in the model */
+  variables: Var[];
+  /** Propositional Boolean variables registered in the model */
+  boolVars?: BoolVar[];
+  /** Linear arithmetic constraints registered in the model */
+  constraints: Constraint[];
+  /** Logical / SMT constraints registered in the model */
+  logicalConstraints?: LogicalConstraintItem[];
+}
+
+export interface SolveModelData extends CheckModelData {
+  /** Optimization direction ("Minimize" | "Maximize") */
+  sense: OptimizationSense;
+  /** Linear or quadratic objective expression */
+  objective: LinExpr | QuadExpr;
+}
+```
+
+### `SolverCapabilities`
+
+Custom solvers declare their supported features using `capabilities`. Before dispatching `solve()` or `check()`, `Model` validates:
+- `supportsQP === false` when the objective contains quadratic terms (`QuadExpr`),
+- `supportsSMT !== true` when the model contains logical constraints (`m.logicalConstraints`), and
+- `supportsWarmStart !== true` when any variable has a primal `initialValue` set.
+
+```typescript
+export interface SolverCapabilities {
+  /** Supports mixed-integer programming (integer/binary variables) */
+  supportsMIP?: boolean;
+
+  /** Supports quadratic objectives (QP: x^T Q x + c^T x) */
+  supportsQP?: boolean;
+
+  /** Supports second-order cone or quadratic constraints */
+  supportsQCQP?: boolean;
+
+  /** Supports satisfiability modulo theories / boolean logic constraints */
+  supportsSMT?: boolean;
+
+  /** Supports extracting an unsatisfiable core (conflicting constraint subset) */
+  supportsUnsatCore?: boolean;
+
+  /** Supports primal initial values / MIP warm starts (Var.initialValue) */
+  supportsWarmStart?: boolean;
+}
+```
+
+### `SolverOptions` & `SolveProgressEvent`
+
+Runtime options passed to `solve` and `check` include cancellation and progress hooks (note that the routing `solver` field from `SolveOptions` is stripped before options are passed to your adapter):
+
+```typescript
+export interface SolverOptions {
+  /** Time limit in seconds */
+  timeLimit?: number;
+
+  /** Relative MIP optimality gap tolerance */
+  mipGap?: number;
+
+  /** Enable solver console logging */
+  verbose?: boolean;
+
+  /** Cooperative cancellation signal; when aborted, return terminationStatus: "Interrupted" */
+  signal?: AbortSignal;
+
+  /** Progress callback invoked with normalized SolveProgressEvent snapshots */
+  onProgress?: (progress: SolveProgressEvent) => void;
+
+  /** Additional solver-specific options */
+  [key: string]: any;
+}
+```
+
+### Optional LP Serialization & Symbol-Mapping Helpers
+
+Solvers that consume structured JS/WASM data (such as `GLPKSolver` and `Z3Solver`) work directly with `SolveModelData` / `CheckModelData`.
+If your adapter targets a backend that requires CPLEX/HiGHS LP text or restricted identifier syntax, WaSHI exports opt-in helpers:
+
+- `generateLpString(modelData): LpExportResult` — serializes `modelData` into a CPLEX LP format string (`lpString`) along with collision-safe symbol lookup maps (`nameToVar`, `nameToConstraint`).
+- `buildLpSymbolMaps(modelData): LpSymbolMaps` — builds collision-safe sanitized symbol maps (`nameToVar`, `varToName`, `nameToConstraint`, `constraintToName`) without serializing an LP string.
+- `isLpExportResult(value): value is LpExportResult` — runtime type guard for `LpExportResult` (useful when supporting legacy 3-argument `solve(modelData, lpResult, options)` overloads).
+- `sanitizeIdentifier(raw, fallbackPrefix = "x", id = 0)` — sanitizes an arbitrary display name into a valid LP identifier.
+
+```typescript
+export interface LpExportResult {
+  /** Standard CPLEX/HiGHS LP formatted string */
+  lpString: string;
+
+  /** Map translating sanitized LP variable identifiers back to WaSHI Var objects */
+  nameToVar: Map<string, Var>;
+
+  /** Map translating sanitized LP constraint identifiers back to WaSHI Constraint objects */
+  nameToConstraint: Map<string, Constraint>;
+}
+```
+
+### `SolverResult` Normalization & Identity Decoding
+
+The `solve` method must return normalized results keyed by the model's canonical variable/constraint names (`v.name`, `bv.name`, `c.name`). Adapters that use `generateLpString(modelData)` or `buildLpSymbolMaps(modelData)` for an LP backend must translate sanitized LP identifiers back to canonical model names using `nameToVar` and `nameToConstraint`:
+
+```typescript
+export interface SolverResult {
+  /** Standardized status string */
+  status: SolverStatus;
+
+  /** Exact termination reason independent of whether a feasible incumbent is available (defaults to status) */
+  terminationStatus?: TerminationStatus;
+
+  /** Whether a feasible primal solution / incumbent is available (inferred from status/values if omitted) */
+  hasPrimalSolution?: boolean;
+
+  /** Optimal or best objective value (null if no primal solution is available) */
+  objectiveValue: number | null;
+
+  /** Best proven dual/objective bound when provided by the solver */
+  objectiveBound?: number;
+
+  /** Relative MIP optimality gap when provided by the solver */
+  relGap?: number;
+
+  /** Alias for relGap: relative MIP optimality gap when provided by the solver */
+  mipGap?: number;
+
+  /** Absolute MIP optimality gap |objectiveValue - objectiveBound| (computed automatically when both are finite) */
+  absGap?: number;
+
+  /** Variable primal values keyed by canonical variable name (non-finite values are ignored) */
+  values: Record<string, number>;
+
+  /** Propositional Boolean variable assignments keyed by BoolVar name (optional, SMT/SAT) */
+  boolValues?: Record<string, boolean>;
+
+  /** Variable reduced costs (optional, LP only) */
+  reducedCosts?: Record<string, number>;
+
+  /** Constraint dual values / shadow prices (optional, LP only) */
+  duals?: Record<string, number>;
+
+  /** Constraint slack values (optional) */
+  slacks?: Record<string, number>;
+
+  /** Solve execution duration in seconds */
+  runTime?: number;
+
+  /** Diagnostic solver logs / text outputs */
+  logs?: string[];
+
+  /** Raw solver response object for inspection */
+  raw?: any;
+}
+```
+
+#### Standardized `SolverStatus` Values
+- `"Optimal"`: Global optimal solution found (for MIP within tolerance, for LP proven optimal).
+- `"Feasible"`: Feasible solution found, but optimality not yet proven (e.g., hit time limit with an incumbent).
+- `"Infeasible"`: Model is proven mathematically infeasible.
+- `"Unbounded"`: Model objective is unbounded.
+- `"TimeLimit"`: Solver terminated due to `timeLimit` without proof of optimality.
+- `"IterationLimit"`: Solver terminated due to iteration limit.
+- `"Sat"` / `"Unsat"`: Satisfiable / unsatisfiable status returned by `check()` or SMT solvers.
+- `"Error"` / `"NotSolved"` / `"Unknown"`: Error, not yet solved, or unrecognized status. **Never convert Unknown/Error to Optimal.**
+
+---
+
+## 3. Step-by-Step Implementation Tutorials
+
+### Tutorial A: In-House Cloud REST Solver Adapter
+
+Here is a complete, production-ready custom solver connecting to an HTTP microservice that accepts LP format strings on demand via `generateLpString(modelData)`:
+
+```typescript
+import {
+  generateLpString,
+  registerSolver,
+  type Solver,
+  type SolverOptions,
+  type SolverResult,
+  type SolverStatus,
+  type SolveModelData,
+} from "@ohtaman/washi";
+
+export interface CloudSolverConfig extends SolverOptions {
+  endpoint?: string;
+  apiKey?: string;
+}
+
+export class CloudSolver implements Solver {
+  public readonly name = "CloudSolver";
+  public readonly version = "1.0.0";
+  public readonly capabilities = {
+    supportsMIP: true,
+    supportsQP: false,
+  };
+
+  private endpoint: string;
+  private apiKey: string;
+
+  constructor(config: CloudSolverConfig = {}) {
+    this.endpoint = config.endpoint || "https://solver.mycompany.internal/v1/solve";
+    this.apiKey = config.apiKey || "";
+  }
+
+  async solve(
+    modelData: SolveModelData,
+    options: SolverOptions = {}
+  ): Promise<SolverResult> {
+    const startTime = performance.now();
+    const { lpString, nameToVar, nameToConstraint } = generateLpString(modelData);
+
+    let payload: any;
+    try {
+      const response = await fetch(this.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+        },
+        body: JSON.stringify({
+          lp: lpString,
+          timeLimit: options.timeLimit,
+          mipGap: options.mipGap,
+        }),
+        signal: options.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`[CloudSolver] Server returned HTTP ${response.status}: ${await response.text()}`);
+      }
+
+      payload = await response.json();
+    } catch (err: any) {
+      if (options.signal?.aborted || err?.name === "AbortError") {
+        return {
+          status: "Unknown",
+          terminationStatus: "Interrupted",
+          objectiveValue: null,
+          values: {},
+          runTime: (performance.now() - startTime) / 1000,
+        };
+      }
+      throw err;
+    }
+
+    const runTime = (performance.now() - startTime) / 1000;
+
+    const values: Record<string, number> = Object.create(null);
+    for (const [k, val] of Object.entries((payload.values || {}) as Record<string, number>)) {
+      values[nameToVar.get(k)?.name ?? k] = val;
+    }
+    const duals: Record<string, number> = Object.create(null);
+    for (const [k, val] of Object.entries((payload.duals || {}) as Record<string, number>)) {
+      duals[nameToConstraint.get(k)?.name ?? k] = val;
+    }
+    const slacks: Record<string, number> = Object.create(null);
+    for (const [k, val] of Object.entries((payload.slacks || {}) as Record<string, number>)) {
+      slacks[nameToConstraint.get(k)?.name ?? k] = val;
+    }
+
+    const statusMap: Record<string, SolverStatus> = {
+      OPTIMAL: "Optimal",
+      FEASIBLE: "Feasible",
+      INFEASIBLE: "Infeasible",
+      UNBOUNDED: "Unbounded",
+      TIME_LIMIT: "TimeLimit",
+      TIMELIMIT: "TimeLimit",
+      ITERATION_LIMIT: "IterationLimit",
+      ERROR: "Error",
+      NOT_SOLVED: "NotSolved",
+      SAT: "Sat",
+      UNSAT: "Unsat",
+    };
+    const rawStatus: SolverStatus = statusMap[String(payload.status).toUpperCase()] ?? "Unknown";
+    const hasIncumbent =
+      (typeof payload.objectiveValue === "number" && Number.isFinite(payload.objectiveValue)) ||
+      Object.values(values).some((val) => typeof val === "number" && Number.isFinite(val));
+    const isLimitStop = rawStatus === "TimeLimit" || rawStatus === "IterationLimit";
+    const status: SolverStatus = isLimitStop && hasIncumbent ? "Feasible" : rawStatus;
+
+    return {
+      status,
+      terminationStatus: rawStatus,
+      objectiveValue: payload.objectiveValue ?? null,
+      values,
+      duals,
+      slacks,
+      runTime: payload.solveDuration || runTime,
+      logs: payload.logs || [],
+      raw: payload,
+    };
+  }
+}
+
+// Auto-register so `import "my-cloud-solver"` enables `solver: "cloud"`
+export function registerCloudSolver(): void {
+  registerSolver("cloud", (opts) => new CloudSolver(opts));
+}
+registerCloudSolver();
+```
+
+---
+
+### Tutorial B: Registering and Using the Custom Solver
+
+Once implemented, the custom solver can be selected in three different ways:
+
+#### Option 1: By Registered Name String
+```typescript
+import { Model } from "@ohtaman/washi";
+import "./cloud-solver.js"; // Auto-registers "cloud"
+
+const model = new Model({ name: "SupplyChain", solver: "cloud" });
+// Or model.solve("cloud")
+```
+
+#### Option 2: By Passing the Solver Instance Directly
+```typescript
+import { Model } from "@ohtaman/washi";
+import { CloudSolver } from "./cloud-solver.js";
+
+const customInstance = new CloudSolver({
+  endpoint: "https://dedicated-gpu-cluster.internal/solve",
+  apiKey: "secret-token",
+});
+
+const model = new Model({ name: "FacilityLocation", solver: customInstance });
+const status = await model.solve();
+```
+
+#### Option 3: Setting Global Default Solver
+```typescript
+import { setDefaultSolver, Model } from "@ohtaman/washi";
+import { CloudSolver } from "./cloud-solver.js";
+
+setDefaultSolver(() => new CloudSolver());
+
+// All subsequent models use CloudSolver by default
+const model = new Model("DefaultedModel");
+```
+
+---
+
+## 4. Distribution: Packaging as a Plugin
+
+To publish your solver as an independent npm package (e.g. `@my-org/washi-solver-cplex`):
+
+### 1. `package.json` Exports Structure
+```json
+{
+  "name": "@my-org/washi-solver-cplex",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/lib/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/lib/index.js",
+      "default": "./dist/lib/index.js"
+    },
+    "./browser": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/browser/index.js",
+      "default": "./dist/browser/index.js"
+    },
+    "./browser/index.min.js": "./dist/browser/index.min.js"
+  },
+  "peerDependencies": {
+    "@ohtaman/washi": ">=0.1.0"
+  }
+}
+```
+
+### 2. Browser IIFE Build
+When building the browser standalone script (`.min.js`), configure your bundler (Vite or Rollup) to:
+- Output format: `iife`
+- Global name: `WashiCplex`
+- Rely on `Symbol.for("washi.solverRegistry")` so that `<script src="washi.min.js"></script><script src="washi-cplex.min.js"></script>` automatically connects.
+
+---
+
+## 5. Testing Your Custom Solver
+
+You can test your solver using Vitest or Jest without bundling:
+
+```typescript
+import { describe, it, expect, vi } from "vitest";
+import { Model, expr, maximize, registerSolver, listAvailableSolvers } from "@ohtaman/washi";
+import { CloudSolver } from "./cloud-solver.js";
+
+describe("Custom Solver Integration", () => {
+  it("registers in available solvers list", () => {
+    registerSolver("cloud-test", () => new CloudSolver());
+    expect(listAvailableSolvers()).toContain("cloud-test");
+  });
+
+  it("propagates primal values and duals into WaSHI Model", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          status: "OPTIMAL",
+          objectiveValue: 34,
+          values: { x: 2, y: 10 },
+          duals: { budget: 2 },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    try {
+      const model = new Model({ solver: new CloudSolver() });
+      const x = model.continuous("x", { lb: 0, ub: 10 });
+      const y = model.continuous("y", { lb: 0, ub: 10 });
+      model.objective(maximize(expr`2 * ${x} + 3 * ${y}`));
+      model.constraint(expr`${x} + ${y} <= 12`, "budget");
+
+      const status = await model.solve();
+      expect(status).toBe("Optimal");
+      expect(x.value).toBe(2);
+      const c1 = model.getConstraintByName("budget");
+      expect(c1?.dual).toBe(2);
+    } finally {
+      fetchSpy.mockRestore();
+    }
+  });
+});
+```

package/docs/solvers/glpk.md

@@ -0,0 +1,66 @@
+# GLPK Solver Engine
+
+The **GNU Linear Programming Kit (GLPK)** is a long-standing, robust simplex and interior-point solver package intended for solving large-scale linear programming (LP) and mixed integer programming (MIP).
+
+---
+
+## Installation
+
+GLPK is provided as an optional peer dependency via `glpk.js`:
+
+```bash
+npm install glpk.js
+```
+
+---
+
+## Licensing Consideration (GPL-3.0)
+
+GLPK is licensed under the **GNU General Public License v3.0 (GPL-3.0)**.
+
+- Because WaSHI is MIT-licensed, `glpk.js` is **never bundled statically** in the core package.
+- It is dynamically imported only if you explicitly register or invoke `@ohtaman/washi/solvers/glpk`.
+- Ensure your project's distribution requirements comply with the GPL-3.0 license when shipping products that bundle GLPK.
+
+---
+
+## Basic Usage
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/glpk";
+
+const model = new Model({ solver: "glpk" });
+
+const x = model.continuous("x", { lb: 0, ub: 10 });
+const y = model.continuous("y", { lb: 0, ub: 20 });
+
+model.objective(maximize(expr`3 * ${x} + 2 * ${y}`));
+model.constraint(expr`${x} + ${y} <= 15`, "cap");
+
+await model.solve();
+
+console.log("GLPK Status:", model.status);
+console.log("Objective:", model.objectiveValue);
+```
+
+---
+
+## Result Semantics & Status Mapping
+
+### Solver Statuses
+GLPK return codes are mapped strictly to WaSHI `SolverStatus`:
+- `GLP_OPT` (5) $\to$ `"Optimal"`
+- `GLP_FEAS` (2) $\to$ `"Feasible"` (feasible MIP incumbent found)
+- `GLP_INFEAS` (3) / `GLP_NOFEAS` (4) $\to$ `"Infeasible"`
+- `GLP_UNBND` (6) $\to$ `"Unbounded"`
+- `GLP_UNDEF` (1) and unrecognized/missing statuses $\to$ `"Unknown"` (never misclassified as `"Optimal"`)
+
+### Solution Availability
+- Variable values (`model.values`, `var.value`) and objective values (`model.objectiveValue`) are exposed **only** when a valid primal solution is available (`"Optimal"` or `"Feasible"`).
+- For unsuccessful or non-optimal solves (`Infeasible`, `Unbounded`, `Unknown`, `Error`), `model.objectiveValue` is `null` and variable values remain `null` without fabricating fake all-zero solutions.
+
+### Differences Between LP and MIP
+- **Linear Programming (LP)**: Solved using the simplex algorithm. Dual values (shadow prices via `constraint.dual`) and slacks are populated for optimal solutions.
+- **Mixed-Integer Programming (MIP)**: Solved using the branch-and-cut algorithm. Produces integer-feasible primal variable solutions; dual values are mathematically undefined for discrete optimization and omitted.
+

package/docs/solvers/highs.md

@@ -0,0 +1,93 @@
+# HiGHS Solver Engine
+
+**HiGHS** is high-performance mathematical optimization software developed at the University of Edinburgh. It is widely recognized as the state-of-the-art open-source solver for Linear Programming (LP), Mixed-Integer Programming (MIP), and Convex Quadratic Programming (QP).
+
+---
+
+## Key Features in WaSHI
+
+- **Built-in & Zero-Config**: Bundled directly with `@ohtaman/washi`. No separate peer dependency or compilation required.
+- **Permissive MIT License**: 100% commercially friendly.
+- **Web Worker Multithreading**: Automatically offloads intensive solving to background Web Workers in browser environments to avoid freezing the UI thread.
+- **Warm-Start Support (`initialValue`)**: Supports passing variable primal initial value hints (`initialValue`) to HiGHS `setSolution` for warm starting.
+- **Fast WASM Execution**: Emscripten-compiled 32-bit WASM runs at near-native speed.
+
+---
+
+## Supported Problem Classes
+
+### 1. Linear Programming (LP)
+Solves continuous problems via Primal and Dual Simplex algorithms or Interior Point (IPM) methods. After solving, you can inspect constraint shadow prices (`c.dual`), slacks (`c.slack`), and variable reduced costs (`v.reducedCost`):
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const model = new Model({ solver: "highs" });
+const x = model.continuous("x", { lb: 0 });
+const y = model.continuous("y", { lb: 0 });
+model.objective(maximize(expr`10 * ${x} + 6 * ${y}`));
+model.constraint(expr`${x} + ${y} <= 100`, "cap");
+await model.solve();
+```
+
+### 2. Mixed-Integer Linear Programming (MIP)
+Solves discrete problems using Branch-and-Bound and cutting plane techniques:
+
+```typescript
+const count = model.integer("count", { lb: 0, ub: 50 });
+```
+
+### 3. Convex Quadratic Programming (QP)
+Solves quadratic objective functions subject to linear constraints:
+
+```typescript
+// Minimize risk/variance uniformly using expr:
+model.objective(minimize(expr`0.5 * ${x}^2 + 0.5 * ${y}^2`));
+
+// Or programmatically with .mul():
+// const quadObj = x.mul(x).mul(0.5).add(y.mul(y).mul(0.5));
+// model.objective(minimize(quadObj));
+```
+
+---
+
+## Solver Options
+
+Pass solver options into `model.solve()`:
+
+```typescript
+const controller = new AbortController();
+
+await model.solve({
+  timeLimit: 60.0,       // Maximum solve time in seconds
+  mipGap: 0.001,         // Terminate when within 0.1% of global optimality (alias: relGap)
+  absGap: 1.0,           // Absolute MIP optimality gap tolerance
+  presolve: "on",        // Presolve control ("on" | "off" | "choose")
+  outputFlag: true,      // Output internal simplex / branch-and-bound logs (output_flag)
+  signal: controller.signal,
+  onProgress: (ev) => {
+    console.log(`Elapsed: ${ev.elapsedTime.toFixed(1)}s, Best: ${ev.objectiveValue}`);
+  },
+});
+```
+
+---
+
+## Worker & WASM Configuration in Browsers
+
+By default in browsers, WaSHI spawns a dedicated Web Worker to execute HiGHS in the background so UI rendering stays responsive and `onProgress` / `AbortSignal` work seamlessly.
+
+If you need to run synchronously on the main thread (or in environments where Web Workers are prohibited), pass `useWorker: false` to `model.solve()` or instantiate `HighsSolver`:
+
+```typescript
+import { Model, HighsSolver } from "@ohtaman/washi";
+
+// Option 1: Per solve call
+await model.solve({ useWorker: false });
+
+// Option 2: When instantiating the solver
+const syncModel = new Model({
+  solver: new HighsSolver({ useWorker: false }),
+});
+```
+