+ 
+ 
+ 
+ 
+
+
+**CoverTable** is a powerful tool for generating pairwise (and N-wise) combinations of input factors, designed for both **Node.js** and **browser** environments. It makes it easy to create comprehensive test cases that cover all factor interactions while keeping the number of test cases minimal.
+
+:::tip[What is Pairwise Testing?]
+Pairwise testing is a combinatorial testing technique that generates test cases covering all possible pairs of input parameters. Instead of testing every combination (which can be enormous), pairwise testing ensures that every pair of factor values appears in at least one test case, dramatically reducing the number of required tests while maintaining high defect detection rates.
+:::
+
+## Installation
+
+```bash
+npm install covertable --save
+```
+
+## Quick Start
+
+### Array format
+
+Pass an array of factor arrays to get results as arrays:
+
+```typescript
+import { make } from "covertable";
+
+const machine = ["iPhone", "Pixel", "XPERIA", "ZenFone", "Galaxy"];
+const os = ["iOS", "Android"];
+const browser = ["FireFox", "Chrome", "Safari"];
+
+const rows = make([machine, os, browser]);
+console.log(rows);
+```
+
+**Output:**
+```javascript
+[
+ [ 'Pixel', 'iOS', 'Chrome' ],
+ [ 'ZenFone', 'iOS', 'FireFox' ],
+ [ 'Pixel', 'Android', 'Safari' ],
+ [ 'Galaxy', 'Android', 'Chrome' ],
+ [ 'XPERIA', 'Android', 'FireFox' ],
+ [ 'Pixel', 'iOS', 'FireFox' ],
+ [ 'iPhone', 'iOS', 'Safari' ],
+ [ 'Galaxy', 'iOS', 'Safari' ],
+ [ 'XPERIA', 'iOS', 'Chrome' ],
+ [ 'ZenFone', 'Android', 'Chrome' ],
+ [ 'Galaxy', 'iOS', 'FireFox' ],
+ [ 'iPhone', 'Android', 'Chrome' ],
+ [ 'iPhone', 'iOS', 'FireFox' ],
+ [ 'ZenFone', 'iOS', 'Safari' ],
+ [ 'XPERIA', 'iOS', 'Safari' ]
+]
+```
+
+### Object format
+
+Pass an object of named factors to get results as objects:
+
+```typescript
+import { make } from "covertable";
+
+const rows = make({
+ machine: ["iPhone", "Pixel", "XPERIA", "ZenFone", "Galaxy"],
+ os: ["iOS", "Android"],
+ browser: ["FireFox", "Chrome", "Safari"],
+});
+
+console.log(rows);
+// [
+// { machine: 'Pixel', os: 'iOS', browser: 'Chrome' },
+// { machine: 'ZenFone', os: 'iOS', browser: 'FireFox' },
+// ...
+// ]
+```
+
+:::info
+When factors are given as an **object**, each result row will also be an object with the same keys.
+:::
+
+## Controller and Statistics
+
+The `make` function is a convenient shortcut. For access to generation statistics, use `Controller` directly:
+
+```typescript
+import { Controller } from "covertable";
+
+const factors = { machine, os, browser };
+const ctrl = new Controller(factors, { constraints: [...] });
+const rows = ctrl.make();
+
+console.log(ctrl.stats);
+// {
+// totalPairs: 30, // all pairs before pruning
+// prunedPairs: 4, // removed by constraint propagation
+// coveredPairs: 26, // pairs covered in output rows
+// progress: 1, // coverage ratio (1 = 100%)
+// rowCount: 8, // number of generated rows
+// uncoveredPairs: [], // pairs that couldn't be covered
+// completions: { ... } // values filled by backtracking
+// }
+```
+
+See [Constraint Logic](/development/constraint-logic#statistics) for full details on each field.
+
+## Async Generation
+
+Use `makeAsync` to generate rows one at a time via a generator:
+
+```typescript
+import { makeAsync } from "covertable";
+
+const machine = ["iPhone", "Pixel", "XPERIA", "ZenFone", "Galaxy"];
+const os = ["iOS", "Android"];
+const browser = ["FireFox", "Chrome", "Safari"];
+
+for (const row of makeAsync([machine, os, browser])) {
+ console.log(row);
+}
+```
+
+## Requirements
+
+ES2015 or later. The following features are used:
+
+- [Generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators)
+- [for...of](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of)
+- [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
+- [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)
+- [Object.keys](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys)
+- [Object.entries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries)
+
+## Next Steps
+
+- Learn about [**Options**](./reference/options) including constraints, sorters, criteria, sub-models, and weights
+- Use the [**PictModel**](./reference/pict) to parse and run full PICT-format models (parameters + constraints + sub-models + invalid values + weights)
+- Try the [**Compatible PICT**](/tools/pict) tool
+- Check the [**History**](./history/) for release notes and [**Migration Guide**](./history/migration)
+
+:::caution[Migrating from v2]
+v3 introduces breaking changes including renamed options, declarative constraints replacing `preFilter`/`postFilter`, and a new `PictModel` class. See the [**Migration Guide**](./history/migration) for full details.
+:::
diff --git a/docs/contents/reference/options.mdx b/docs/contents/reference/options.mdx
new file mode 100644
index 0000000..96cab65
--- /dev/null
+++ b/docs/contents/reference/options.mdx
@@ -0,0 +1,198 @@
+---
+sidebar_position: 1
+title: Options
+---
+
+# Options
+
+The `make` function accepts an options object as its second argument:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `strength` | `number` | `2` | Number of factors to be covered (N-wise). |
+| `subModels` | `SubModelType[]` | `undefined` | Apply a different combination strength to a specific group of factors. |
+| `weights` | `WeightsType` | `undefined` | Index-keyed weights that bias value selection during row completion. |
+| `presets` | `PresetRowType[]` | `undefined` | Rows that must be included in the output. Equivalent to PICT's seeding feature. |
+| `constraints` | `Expression[]` | `undefined` | Declarative constraints evaluated under three-valued logic. |
+| `comparer` | `Comparer` | `undefined` | Custom comparison functions for constraint evaluation. |
+| `sorter` | `Function` | `sorters.hash` | Determines the order of combinations. |
+| `criterion` | `Function` | `criteria.greedy` | Determines the algorithm for generating combinations. |
+| `salt` | `string \| number` | `""` | Value mixed into `sorters.hash` to control the ordering of pairs. |
+| `tolerance` | `number` | `0` | Tolerance used by `criteria.greedy` to trade optimality for speed. |
+
+See also: [PictModel](./pict) for the PICT-compatible model parser, or [Constraint Shortcuts](/reference/shortcuts/constraint) for a concise constraint builder API.
+
+---
+
+## `strength`
+
+Number of factors to be covered. Default is `2` (pairwise).
+
+:::caution
+The more `strength` increases, the more the number of combinations increases exponentially. Use values greater than 2 only when truly needed.
+:::
+
+:::info[Renamed from `length`]
+In versions prior to 3.0, this option was called `length`. The semantics are unchanged.
+:::
+
+## `subModels`
+
+`subModels` lets you apply a different N-wise strength to a specific group of factors, while the rest of the factors stay at the default `strength`. This is the same concept as PICT's [sub-models](https://github.com/microsoft/pict/blob/main/doc/pict.md#sub-models).
+
+```typescript
+import { make } from "covertable";
+
+const factors = {
+ PLATFORM: ["Win", "Mac", "Linux"],
+ CPUS: ["1", "2", "4"],
+ RAM: ["512", "1024"],
+ HDD: ["SATA", "SSD"],
+};
+
+make(factors, {
+ strength: 2,
+ subModels: [
+ { fields: ["PLATFORM", "CPUS", "RAM"], strength: 3 },
+ ],
+});
+```
+
+In this example:
+- All combinations of `PLATFORM`, `CPUS`, and `RAM` are covered at strength 3.
+- Pairs that span the sub-model and other factors (e.g. `PLATFORM x HDD`) are still covered at the default strength of 2.
+
+## `weights`
+
+`weights` biases the **completion phase** — the moment CoverTable picks a value to fill in a column once all required pairs have been satisfied. Higher-weighted values are tried first, so they tend to appear in more rows.
+
+```typescript
+import { make } from "covertable";
+
+const factors = {
+ OS: ["Windows", "Linux", "Mac"],
+ Browser: ["Chrome", "Firefox", "Safari"],
+};
+
+make(factors, {
+ weights: {
+ Browser: { 0: 10 }, // index 0 = "Chrome" gets weight 10 (default is 1)
+ },
+});
+```
+
+The keys of the inner object are **indices into the factor's value array**. To express weights by value instead, use the [`weightsByValue`](./pict#weightsbyvalue) helper from `covertable/pict`.
+
+:::info[How weights interact with coverage]
+Weights only affect the **completion phase**. The pairwise (or N-wise) coverage requirement is always satisfied first; weights only influence which values are picked when the algorithm has free choice. Setting a weight does not change the minimum number of generated rows.
+:::
+
+## `presets`
+
+`presets` lets you specify rows that **must appear in the output**. CoverTable processes them before normal generation, so the pairs they cover are subtracted from the work that the generator has to do — often reducing the total number of generated rows.
+
+```typescript
+import { make } from "covertable";
+
+const factors = {
+ OS: ["iOS", "Android"],
+ Browser: ["Safari", "Chrome", "Firefox"],
+ Locale: ["en", "ja", "fr"],
+};
+
+make(factors, {
+ presets: [
+ { OS: "iOS", Browser: "Safari", Locale: "en" },
+ { OS: "Android", Browser: "Chrome" },
+ { Browser: "Firefox" },
+ ],
+});
+```
+
+**Behavior:**
+
+| Case | Result |
+|------|--------|
+| Full row, satisfies constraints | Output as-is, covered pairs are consumed |
+| Partial row, can be completed within constraints | Completed via the normal fill-in logic, then output |
+| Row violates constraints (or contains an unknown value) | Silently dropped |
+| Row cannot be completed (e.g. constraints leave no valid filler) | Silently dropped |
+
+:::info[Equivalent to PICT's seeding (`/e:file`)]
+PICT calls this feature **seeding** and reads the seed rows from a tab-separated file via the `/e:file.txt` CLI option. CoverTable's `presets` is the same concept, expressed as plain JavaScript objects so you can compose them programmatically.
+:::
+
+## `constraints`
+
+Declarative constraints evaluated under Kleene three-valued logic. See [Constraint Logic](/development/constraint-logic) for full documentation.
+
+```typescript
+make(factors, {
+ constraints: [
+ // IF machine = iPhone THEN os = iOS
+ { operator: 'or', conditions: [
+ { operator: 'ne', left: 'machine', value: 'iPhone' },
+ { operator: 'eq', left: 'os', value: 'iOS' },
+ ]},
+ ],
+});
+```
+
+:::tip
+Writing constraint objects by hand can be verbose. The [`Constraint` shortcut class](/reference/shortcuts/constraint) provides a concise builder API:
+
+```typescript
+import { Constraint } from "covertable/shortcuts";
+const c = new Constraint
+
+
+
+
+
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Sub-components
+// ---------------------------------------------------------------------------
+
+function Stat({
+ label,
+ value,
+ sub,
+ variant,
+}: {
+ label: string;
+ value: number | string;
+ sub?: string;
+ variant?: "success" | "warning";
+}) {
+ return (
+
+
+
+ Samples
+
+ {SAMPLES.map((s) => (
+
+ ))}
+
+
+
+ {/* LEFT: editor + parsed metadata */}
+
+
+
+
+ {/* RIGHT: output */}
+
+
+ PICT model
+ +
+
+ {showOptions && (
+
+
+
+
+ )}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {model.issues.length > 0 &&
+
+
+
+ )}
+
+ {model.subModels.length > 0 && (
+ <>
+
+
+
+
+ )}
+
+ {negativeEntries.length > 0 && (
+ <>
+
+
+
+
+ )}
+
+ {weightEntries.length > 0 && (
+ <>
+
+
+
+
+ )}
+
+ {model.constraints.length > 0 && (
+ <>
+
+ Parsed factors ({factorKeys.length})
+ {factorKeys.length === 0 ? ( +No parameters parsed yet.
+ ) : ( +| Factor | +Values | +
|---|---|
+ {key}
+ |
+ {values.join(", ")} | +
Sub-models ({model.subModels.length})
+| Keys | +Strength | +
|---|---|
| {sm.fields.join(", ")} | +{sm.strength} | +
Negative values
+| Factor | +Values | +
|---|---|
+ {key}
+ |
+ {Array.from(set).join(", ")} | +
Weights
+| Factor | +Value → Weight | +
|---|---|
+ {key}
+ |
+
+ {Object.entries(weights as Record |
+
Constraints ({model.constraints.length})
++ {model.constraints.filter((c) => c != null).length} compiled,{" "} + {model.constraints.filter((c) => c == null).length} failed +
+ + )} +
+
+
+
+
+ Combinations{isDirty && *}
+
+ setOutputView("table")}>
+ Table
+
+ setOutputView("tsv")}>
+ TSV
+
+ setOutputView("json")}>
+ JSON
+
+
+
+ {generatedKeys.length === 0 ? (
+
+
+ {/* Progress bar (visible while generating) */}
+ {isGenerating && (
+ + Click Generate to produce combinations. +
+ ) : outputView === "table" ? ( +
+
+
+
+
+ ) : outputView === "tsv" ? (
+ | # | + {generatedKeys.map((key) => ( +{key} | + ))} +
|---|---|
| {i + 1} | + {generatedKeys.map((key) => ( +{String(row[key])} | + ))} +
{rowsToTsv(rows, generatedKeys)}
+ ) : (
+ {JSON.stringify(rows, null, 2)}
+ )}
+ {outputFull ? (
+
+ ) : generatedKeys.length > 0 && (
+
+ )}
+
+
+ Generating… Greedy row construction in progress. The percentage reflects pairs consumed or pruned out of total. + + +
+ )}
+
+ {/* Copy / Download */}
+ {rows.length > 0 && (
+
+
+
+ {statusMessage
+ ? statusMessage
+ : `Generating… ${rows.length} rows (${Math.round(Math.sqrt(progress) * 100)}%)${eta !== null && eta > 0 ? ` — ~${eta}s left` : ""}`}
+
+
+
+ ?
+
+ Preparing… Building pair combinations and pruning infeasible pairs via constraint propagation. Can take a few seconds for large models or higher strengths.+ Generating… Greedy row construction in progress. The percentage reflects pairs consumed or pruned out of total. + + +
+
+
+
+ )}
+
+ {/* Stats below the grid */}
+ {generatedKeys.length > 0 && (
+
+
+ )}
+
+ 0 ? `${reduction}%` : "—"}
+ sub={total > 0 ? `vs ${total >= 1e6 ? total.toExponential(1) : total.toLocaleString()} total` : undefined}
+ />
+
+ {generatedStats && (
+
+ = 1 ? "success" : "warning"}
+ />
+
+ )}
+ {generatedStats && generatedStats.completions && Object.keys(generatedStats.completions).length > 0 && (
+
+
+ )}
+ Completions (factors filled by backtracking)
+
+ {Object.entries(generatedStats.completions)
+ .map(([k, v]) => [k, Object.values(v).reduce((a, b) => a + b, 0)] as [string, number])
+ .sort((a, b) => b[1] - a[1])
+ .map(([factor, count]) => (
+
+
+
+
+
+ {factor}
+ {count}
+
+ ))}
+
+
+ );
+}
+
+function SegmentButton({
+ active,
+ onClick,
+ children,
+}: {
+ active: boolean;
+ onClick: () => void;
+ children: React.ReactNode;
+}) {
+ return (
+
+ );
+}
+
+function IssueList({ issues }: { issues: PictModelIssue[] }) {
+ return (
+ {value}
+ {label}
+ {sub && {sub}
}
+
+ {issues.length} issue(s):
+
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+function DemoStyles() {
+ return (
+
+ );
+}
diff --git a/docs/contents/tools/vscode.mdx b/docs/contents/tools/vscode.mdx
new file mode 100644
index 0000000..443b03a
--- /dev/null
+++ b/docs/contents/tools/vscode.mdx
@@ -0,0 +1,72 @@
+---
+sidebar_position: 2
+slug: /tools/vscode
+title: "VS Code Extension"
+---
+
+# PICT VS Code Extension
+
+[](https://marketplace.visualstudio.com/items?itemName=walkframe.pict-covertable)
+[](https://marketplace.visualstudio.com/items?itemName=walkframe.pict-covertable)
+[](https://open-vsx.org/extension/walkframe/pict-covertable)
+
+**PICT Pairwise Testing with CoverTable** brings PICT support directly into your
+editor — syntax highlighting, live diagnostics, and covering-array generation —
+powered by the same [CoverTable](/) engine as the online tool. No external binary
+is required.
+
+## Install
+
+- **VS Code**: [Marketplace page](https://marketplace.visualstudio.com/items?itemName=walkframe.pict-covertable), or run in the Quick Open bar (`Cmd`/`Ctrl` + `P`):
+
+ ```
+ ext install walkframe.pict-covertable
+ ```
+
+- **Cursor / VSCodium / Windsurf / Gitpod** (Open VSX): [Open VSX page](https://open-vsx.org/extension/walkframe/pict-covertable)
+
+- **CLI**:
+
+ ```bash
+ code --install-extension walkframe.pict-covertable
+ ```
+
+## Features
+
+- **Syntax highlighting** for `.pict` files: parameters, values, weights `(N)`,
+ negatives `~`, aliases `a|b`, parameter references `-
+ {issues.map((issue, i) => (
+
-
+
+ [{issue.source}#{issue.index} line {issue.line}] +{" "} + {issue.message} +
+ ))}
+