decisium 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrei Letenkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# Decisium
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Semantic UI testing with decision models. Plain-English Gherkin Steps run in a real browser (Playwright): Jev, a decision
+model, picks among the actions the page actually offers, and code decides pass/fail. No selectors, no LLM, no prompts.
+Record/replay cassettes make CI deterministic with zero model calls.
+
+**Requires Jev:** live runs call TypeSafe's Jev model through its API (`TYPESAFE_API_KEY`). Replays (`--record none`)
+make no calls and need no key. Decisium's code is MIT; Jev is TypeSafe's hosted service under its own terms.
+
+## Install
+
+```sh
+npm install --save-dev decisium
+npx playwright install chromium
+export TYPESAFE_API_KEY=...   # Jev; not needed to replay with --record none
+npx decisium doctor my.feature
+npx decisium run my.feature
+```
+
+`npx decisium` prints the full usage.
+
+## Raw cucumber-js
+
+```js
+// cucumber.mjs
+export default {
+  import: ["node_modules/decisium/dist/steps.js"],
+  format: ["decisium/formatter"],
+  worldParameters: { decisium: { record: "new" } },
+};
+```
+
+then `npx cucumber-js my.feature`. Options: [docs/configuration.md](docs/configuration.md).
+Writing steps: [docs/cookbook.md](docs/cookbook.md). Agent skill: `skills/decisium/SKILL.md`.

package/dist/browser.d.ts

@@ -0,0 +1,98 @@
+import { type BrowserContext, type BrowserContextOptions, type Page } from "playwright";
+import { type NetworkReplay } from "./network.ts";
+import { type Observation, type Verb } from "./observation.ts";
+export interface Action {
+    verb: Verb | "SCROLL" | "SCROLL_UP" | "WAIT" | "ENTER" | "PRESS" | "ACCEPT" | "DISMISS" | "GOTO" | "BACK" | "FORWARD" | "RELOAD" | "CLOSE_TAB" | "SWITCH_TAB" | "HOVER" | "UPLOAD" | "DBLCLICK" | "RIGHTCLICK" | "DRAG" | "PASTE";
+    ref?: string;
+    to?: string;
+    value?: string;
+}
+export declare class Browser {
+    private browser;
+    /** Public for client step definitions (`this.context` on the World, task 0048). */
+    readonly context: BrowserContext;
+    /** The tab Steps act on. A tab the page opens (a popup, a target=_blank link) becomes it at once (task 0041). Public as `this.page`. */
+    page: Page;
+    /** `@replay-network` requests missing from the recording, until the Step that made them fails on them (task 0048). */
+    readonly networkMisses: string[];
+    private start;
+    private inflight;
+    private last?;
+    /**
+     * Browser dialogs (task 0040). While one is open the page is blocked (snapshots, evaluate, screenshots and clicks
+     * hang), so the Observation is the page as it was under it; `opened` resolves when one opens.
+     */
+    private open?;
+    private dialog?;
+    private under?;
+    private opened;
+    private signal;
+    readonly consoleErrors: string[];
+    /** Secret placeholders (`$NAME` -> value): typed for the token, masked back to it in every Observation (task 0030). */
+    private secrets;
+    /** A secret was typed: the Playwright trace stores typed text unmasked, so close() keeps none. */
+    typedSecret: boolean;
+    /** Task 0044: UPLOAD paths resolve against `files` (the feature's folder); downloads are saved to `downloads`. */
+    private files;
+    private downloads?;
+    private download?;
+    /** Task 0062: a headed browser may share the OS clipboard; only text copied since the open is shown. */
+    private clipboardAtOpen?;
+    private readClipboard;
+    private mask;
+    private constructor();
+    /** Saves each download; counted in flight until saved, so the action that started it settles after it. */
+    private watchDownloads;
+    private rearm;
+    /** `p`, or undefined once a dialog is open: the page is blocked until it is answered. */
+    private unblocked;
+    /** Owns per-Action-step cleanup, including thrown errors. `execute` keeps cleanup actions in the runtime's trace. */
+    actionStep<T>(run: () => Promise<T>, log?: (...data: any[]) => void, execute?: (a: Action) => Promise<void>): Promise<T>;
+    /**
+     * `trace`: record a Playwright trace, saved by close(tracePath). `secrets`: placeholder token -> value. `files`: the
+     * folder UPLOAD paths are relative to; `downloads`: where downloads are saved (none: not saved, not readable).
+     * `context`: options that must exist before the page opens (tags, task 0048); `network`: `@replay-network`.
+     */
+    static open(url: string, headed?: boolean, trace?: boolean, secrets?: Record<string, string>, files?: string, downloads?: string, context?: BrowserContextOptions, network?: NetworkReplay): Promise<Browser>;
+    /**
+     * Waits until no request is in flight, no work is due soon (see __soon: lazily loaded code runs idle callbacks and
+     * short timers after its scripts arrive, before it renders) and the DOM has not changed for QUIET_MS (capped).
+     */
+    private settle;
+    observe(): Promise<Observation>;
+    private stamp?;
+    /** The DOM changed since the latest Observation (task 0066): the page moved on its own before an action. */
+    stale(): Promise<boolean>;
+    private read;
+    /** Collapsed controls (`aria-expanded=false` + `aria-controls`, closed `<details>`) by name -> hidden entries they hold. */
+    private collapsed;
+    /** `title` attributes of visible elements by name, where the title says more than the name. */
+    private titles;
+    /**
+     * Facts by ref, for elements `factsIn` picks in any frame (open shadow roots included): one DOM read per frame, then
+     * one element snapshot per match. Run before the page snapshot: an element snapshot invalidates older refs, and the
+     * page snapshot after it reuses the refs it gave. Reading per ref instead took ~2 s per Observation on Wikipedia.
+     */
+    private facts;
+    /**
+     * Refs of links marked aria-current (the current page or tab in a navigation). The hrefs of aria-current links pick
+     * the candidates; each candidate is then read by ref, since links that share an href ("#") can differ.
+     */
+    private currentLinks;
+    /**
+     * Executes one action and checks its effect where the effect is deterministic (TYPE/SELECT). An action that opens a
+     * dialog returns once it is open (its effect check is skipped); ACCEPT/DISMISS answer it.
+     */
+    execute(action: Action): Promise<void>;
+    private perform;
+    /**
+     * Waits until the Observation differs from `since` (true), the timeout passes, or the page cannot change on its
+     * own any more (false): no request, timer, animation frame or socket pending on two polls in a row.
+     */
+    waitForChange(since: string, timeoutMs?: number): Promise<boolean>;
+    /** True when nothing pending in the page can change it without user input. */
+    private idle;
+    screenshot(path: string): Promise<unknown>;
+    /** `tracePath`: where to save the Playwright trace started by open(..., trace); omitted, or a secret typed = discard it. */
+    close(tracePath?: string): Promise<void>;
+}