@cssints/apg-specs 0.0.0-stage → 0.5.1

package/dist/scenario.d.mts

@@ -0,0 +1,233 @@
+import { QuintEvent, QuintModelValue, QuintReferenceModel } from "@quint-machine/core";
+import { Schema } from "effect";
+//#region src/scenario.d.ts
+/**
+ * Typed step fields a bridge must opt into (`SpecBridge.stepFields`): replaying
+ * a step while ignoring one of these would test a different step.
+ */
+export declare const EXTENDED_STEP_FIELDS: readonly ["position", "modifiers", "phase", "button", "buttons", "pointerType", "pointerId", "detail", "count", "canceled", "defaultPrevented", "isComposing", "inputEvent", "set"];
+export type ExtendedStepField = (typeof EXTENDED_STEP_FIELDS)[number];
+declare const ActionStep: Schema.StructWithRest<Schema.Struct<{
+  readonly event: Schema.String;
+  readonly target: Schema.optionalKey<Schema.String>;
+  readonly key: Schema.optionalKey<Schema.String>;
+  readonly text: Schema.optionalKey<Schema.String>;
+  readonly prop: Schema.optionalKey<Schema.String>;
+  readonly value: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+  readonly repeat: Schema.optionalKey<Schema.Union<readonly [Schema.Boolean, Schema.Number]>>;
+  readonly ms: Schema.optionalKey<Schema.Number>;
+  readonly position: Schema.optionalKey<Schema.Number>;
+  readonly modifiers: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["Alt", "Control", "Meta", "Shift"]>>>;
+  readonly phase: Schema.optionalKey<Schema.Literals<readonly ["down", "up"]>>;
+  readonly button: Schema.optionalKey<Schema.Number>;
+  readonly buttons: Schema.optionalKey<Schema.Number>;
+  readonly pointerType: Schema.optionalKey<Schema.Literals<readonly ["mouse", "pen", "touch"]>>;
+  readonly pointerId: Schema.optionalKey<Schema.Number>;
+  readonly detail: Schema.optionalKey<Schema.Number>;
+  readonly count: Schema.optionalKey<Schema.Number>;
+  readonly canceled: Schema.optionalKey<Schema.Boolean>;
+  readonly defaultPrevented: Schema.optionalKey<Schema.Boolean>;
+  readonly isComposing: Schema.optionalKey<Schema.Boolean>;
+  readonly inputEvent: Schema.optionalKey<Schema.String>;
+  readonly set: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+type ActionStep = typeof ActionStep.Type;
+export type Json = Schema.Json;
+export interface ScenarioConfig {
+  readonly [key: string]: Schema.Json;
+}
+declare const Scenario: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly upstream: Schema.optionalKey<Schema.String>;
+  readonly upstreamTest: Schema.optionalKey<Schema.String>;
+  readonly apg: Schema.optionalKey<Schema.String>;
+  readonly config: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+  readonly steps: Schema.$Array<Schema.Union<readonly [Schema.StructWithRest<Schema.Struct<{
+    readonly event: Schema.String;
+    readonly target: Schema.optionalKey<Schema.String>;
+    readonly key: Schema.optionalKey<Schema.String>;
+    readonly text: Schema.optionalKey<Schema.String>;
+    readonly prop: Schema.optionalKey<Schema.String>;
+    readonly value: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly repeat: Schema.optionalKey<Schema.Union<readonly [Schema.Boolean, Schema.Number]>>;
+    readonly ms: Schema.optionalKey<Schema.Number>;
+    readonly position: Schema.optionalKey<Schema.Number>;
+    readonly modifiers: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["Alt", "Control", "Meta", "Shift"]>>>;
+    readonly phase: Schema.optionalKey<Schema.Literals<readonly ["down", "up"]>>;
+    readonly button: Schema.optionalKey<Schema.Number>;
+    readonly buttons: Schema.optionalKey<Schema.Number>;
+    readonly pointerType: Schema.optionalKey<Schema.Literals<readonly ["mouse", "pen", "touch"]>>;
+    readonly pointerId: Schema.optionalKey<Schema.Number>;
+    readonly detail: Schema.optionalKey<Schema.Number>;
+    readonly count: Schema.optionalKey<Schema.Number>;
+    readonly canceled: Schema.optionalKey<Schema.Boolean>;
+    readonly defaultPrevented: Schema.optionalKey<Schema.Boolean>;
+    readonly isComposing: Schema.optionalKey<Schema.Boolean>;
+    readonly inputEvent: Schema.optionalKey<Schema.String>;
+    readonly set: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+  }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>, Schema.Struct<{
+    readonly expect: Schema.StructWithRest<Schema.Struct<{
+      readonly focus: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+      readonly attrs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>>;
+      readonly visible: Schema.optionalKey<Schema.$Array<Schema.String>>;
+      readonly hidden: Schema.optionalKey<Schema.$Array<Schema.String>>;
+      readonly checked: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+      readonly value: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+      readonly events: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>>>;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+  }>]>>;
+  readonly notes: Schema.optionalKey<Schema.String>;
+}>;
+type Scenario = typeof Scenario.Type;
+/** An upstream behaviour deliberately not ported (`upstream*` when it has a single source). */
+declare const Skipped: Schema.Struct<{
+  readonly id: Schema.optionalKey<Schema.String>;
+  readonly upstream: Schema.optionalKey<Schema.String>;
+  readonly upstreamTest: Schema.optionalKey<Schema.String>;
+  readonly reason: Schema.String;
+}>;
+type Skipped = typeof Skipped.Type;
+declare const ScenarioFile: Schema.Struct<{
+  readonly pattern: Schema.String;
+  readonly source: Schema.String;
+  readonly commit: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+  readonly license: Schema.optionalKey<Schema.String>;
+  readonly upstream: Schema.optionalKey<Schema.String>;
+  readonly retrieved: Schema.optionalKey<Schema.String>;
+  readonly fixture: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+  readonly notes: Schema.optionalKey<Schema.String>;
+  readonly skipped: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+    readonly id: Schema.optionalKey<Schema.String>;
+    readonly upstream: Schema.optionalKey<Schema.String>;
+    readonly upstreamTest: Schema.optionalKey<Schema.String>;
+    readonly reason: Schema.String;
+  }>>>;
+  readonly scenarios: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly upstream: Schema.optionalKey<Schema.String>;
+    readonly upstreamTest: Schema.optionalKey<Schema.String>;
+    readonly apg: Schema.optionalKey<Schema.String>;
+    readonly config: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly steps: Schema.$Array<Schema.Union<readonly [Schema.StructWithRest<Schema.Struct<{
+      readonly event: Schema.String;
+      readonly target: Schema.optionalKey<Schema.String>;
+      readonly key: Schema.optionalKey<Schema.String>;
+      readonly text: Schema.optionalKey<Schema.String>;
+      readonly prop: Schema.optionalKey<Schema.String>;
+      readonly value: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+      readonly repeat: Schema.optionalKey<Schema.Union<readonly [Schema.Boolean, Schema.Number]>>;
+      readonly ms: Schema.optionalKey<Schema.Number>;
+      readonly position: Schema.optionalKey<Schema.Number>;
+      readonly modifiers: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["Alt", "Control", "Meta", "Shift"]>>>;
+      readonly phase: Schema.optionalKey<Schema.Literals<readonly ["down", "up"]>>;
+      readonly button: Schema.optionalKey<Schema.Number>;
+      readonly buttons: Schema.optionalKey<Schema.Number>;
+      readonly pointerType: Schema.optionalKey<Schema.Literals<readonly ["mouse", "pen", "touch"]>>;
+      readonly pointerId: Schema.optionalKey<Schema.Number>;
+      readonly detail: Schema.optionalKey<Schema.Number>;
+      readonly count: Schema.optionalKey<Schema.Number>;
+      readonly canceled: Schema.optionalKey<Schema.Boolean>;
+      readonly defaultPrevented: Schema.optionalKey<Schema.Boolean>;
+      readonly isComposing: Schema.optionalKey<Schema.Boolean>;
+      readonly inputEvent: Schema.optionalKey<Schema.String>;
+      readonly set: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>, Schema.Struct<{
+      readonly expect: Schema.StructWithRest<Schema.Struct<{
+        readonly focus: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly attrs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Record<Schema.String, Schema.NullOr<Schema.String>>>>;
+        readonly visible: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly hidden: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly checked: Schema.optionalKey<Schema.NullOr<Schema.String>>;
+        readonly value: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly events: Schema.optionalKey<Schema.$Record<Schema.String, Schema.$Array<Schema.Codec<Schema.Json, Schema.Json, never, never>>>>;
+      }>, readonly [Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>]>;
+    }>]>>;
+    readonly notes: Schema.optionalKey<Schema.String>;
+  }>>;
+}>;
+type ScenarioFile = typeof ScenarioFile.Type;
+/** Decode a scenario JSON document (the trust boundary for ported data). */
+export declare const parseScenarioFile: (input: Schema.Json) => ScenarioFile;
+/** A step or observation the target does not model. Skips, never fails. */
+export declare class Unsupported extends Error {}
+/** The target disagreed with the scenario (or, in a walk, with the other target). */
+export declare class ScenarioMismatch extends Error {}
+export interface Observer {
+  /** Part target holding focus (`trigger`, `tab:1`), or `null`. */
+  readonly focus: () => string | null;
+  /** Attribute value; `null` = absent. Throw `Unsupported` when not modelled. */
+  readonly attr: (target: string, name: string) => string | null;
+  /** The parts currently visible. */
+  readonly visible: () => ReadonlyArray<string>;
+  /** Callback payloads fired since mount (setup excluded), in order. */
+  readonly events: (name: string) => ReadonlyArray<Schema.Json>;
+  /** The pattern's observable value (`expect.value`), when it has one. */
+  readonly value?: () => Schema.Json;
+}
+export interface Driver {
+  readonly perform: (step: ActionStep) => void | Promise<void>;
+  readonly observer: Observer;
+  readonly dispose?: () => void;
+}
+export type ReplayResult = {
+  readonly status: "passed";
+  readonly skipped: ReadonlyArray<string>;
+} | {
+  readonly status: "unsupported";
+  readonly reason: string;
+};
+/**
+ * Run one scenario against a driver. The bridge is the shared vocabulary gate:
+ * a config or step it cannot translate makes the scenario `unsupported` for
+ * every target alike, before anything runs. Throws `ScenarioMismatch` on a
+ * failed expectation.
+ */
+export declare const replayScenario: (scenario: Scenario, bridge: Pick<SpecBridge, "setup" | "event" | "stepFields">, makeDriver: (config: ScenarioConfig) => Driver | Promise<Driver>) => Promise<ReplayResult>;
+/** What a pattern teaches the spec driver: scenario vocabulary <-> spec events/state. */
+export interface SpecBridge {
+  /** Spec events that bring a fresh model to the scenario's `config` (not observed as events). */
+  readonly setup: (config: ScenarioConfig) => ReadonlyArray<QuintEvent>;
+  /**
+   * The spec events for a step (`[]` = no effect on this pattern; throw
+   * `Unsupported` otherwise). Convention: `key` / `type` on a target first
+   * focuses it, as a user would.
+   */
+  readonly event: (step: ActionStep) => ReadonlyArray<QuintEvent>;
+  /**
+   * The `EXTENDED_STEP_FIELDS` this bridge honours in `event`. A step carrying
+   * any other typed field is `Unsupported` for every target alike.
+   */
+  readonly stepFields?: ReadonlyArray<ExtendedStepField>;
+  /** Canonical callback name (`onOpenChange` -> `onExpandedChange`). */
+  readonly eventName?: (name: string) => string;
+  /** `expect.value` over the model state. */
+  readonly value?: (state: QuintModelValue) => Schema.Json;
+  readonly focus: (state: QuintModelValue) => string | null;
+  readonly attr: (state: QuintModelValue, target: string, name: string) => string | null;
+  readonly visible: (state: QuintModelValue) => ReadonlyArray<string>;
+  /** Callbacks the implementation would have fired during one transition. */
+  readonly events: (before: QuintModelValue, after: QuintModelValue) => ReadonlyArray<readonly [name: string, payload: Schema.Json]>;
+}
+/** A driver over the generated reference model. Checks every invariant after every step. */
+export declare const specDriver: (model: QuintReferenceModel, bridge: SpecBridge, config?: ScenarioConfig) => Driver;
+export interface Probe {
+  readonly attrs: ReadonlyArray<readonly [target: string, name: string]>;
+  readonly events: ReadonlyArray<string>;
+}
+export interface WalkOptions {
+  /** Steps the walk draws from (a pattern's user-level alphabet). */
+  readonly alphabet: ReadonlyArray<ActionStep>;
+  readonly probe: Probe;
+  /** A fresh [reference, candidate] pair per run, both at the same `config`. */
+  readonly makePair: () => Promise<readonly [Driver, Driver]>;
+  readonly runs?: number;
+  readonly steps?: number;
+  readonly seed?: number;
+}
+/**
+ * Differential test: the same random steps into the reference and the
+ * candidate; every probed observation must agree after every step.
+ */
+export declare const differentialWalk: (options: WalkOptions) => Promise<void>;
+//#endregion
+export { ActionStep, Scenario, ScenarioFile, Skipped };

package/dist/scenario.mjs

@@ -0,0 +1,313 @@
+import { violatedInvariants } from "@quint-machine/core";
+import { Schema } from "effect";
+//#region src/scenario.ts
+/**
+* The scenario bridge: one replay engine, two drivers.
+*
+* A scenario (`scenarios/apg/<pattern>.<source>.json`) is a list of user-level
+* steps and expectations. `replayScenario` runs it against any `Driver`:
+*
+*   - `specDriver`  — steps become spec events (via a per-pattern `SpecBridge`),
+*                     the generated reference model is stepped, every spec
+*                     invariant is checked after every step;
+*   - a DOM driver  — lives next to the implementation (packages/headless) and
+*                     performs the same steps on real elements.
+*
+* `differentialWalk` then drives both with the same seeded random steps and
+* compares their observations after each one, so the implementation is checked
+* far beyond the ported scenarios. Pure TypeScript, no DOM: it loads in both
+* Node and the browser.
+*/
+const Rest = [Schema.Record(Schema.String, Schema.Json)];
+/** Expectation keys the replay engine checks against an `Observer`. */
+const CHECKED_EXPECTATION_KEYS = /* @__PURE__ */ new Set([
+	"focus",
+	"attrs",
+	"visible",
+	"value",
+	"events"
+]);
+const Expectation = Schema.StructWithRest(Schema.Struct({
+	focus: Schema.optionalKey(Schema.NullOr(Schema.String)),
+	attrs: Schema.optionalKey(Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.NullOr(Schema.String)))),
+	visible: Schema.optionalKey(Schema.Array(Schema.String)),
+	hidden: Schema.optionalKey(Schema.Array(Schema.String)),
+	checked: Schema.optionalKey(Schema.NullOr(Schema.String)),
+	value: Schema.optionalKey(Schema.Json),
+	events: Schema.optionalKey(Schema.Record(Schema.String, Schema.Array(Schema.Json)))
+}), Rest);
+/** Step fields every bridge understands; `ms` only ever rides on `wait`. */
+const CORE_STEP_FIELDS = /* @__PURE__ */ new Set([
+	"event",
+	"target",
+	"key",
+	"text",
+	"prop",
+	"value",
+	"repeat",
+	"ms"
+]);
+/**
+* Typed step fields a bridge must opt into (`SpecBridge.stepFields`): replaying
+* a step while ignoring one of these would test a different step.
+*/
+const EXTENDED_STEP_FIELDS = [
+	"position",
+	"modifiers",
+	"phase",
+	"button",
+	"buttons",
+	"pointerType",
+	"pointerId",
+	"detail",
+	"count",
+	"canceled",
+	"defaultPrevented",
+	"isComposing",
+	"inputEvent",
+	"set"
+];
+const Modifier = Schema.Literals([
+	"Alt",
+	"Control",
+	"Meta",
+	"Shift"
+]);
+const PointerType = Schema.Literals([
+	"mouse",
+	"pen",
+	"touch"
+]);
+const KeyPhase = Schema.Literals(["down", "up"]);
+const ActionStep = Schema.StructWithRest(Schema.Struct({
+	event: Schema.String,
+	target: Schema.optionalKey(Schema.String),
+	key: Schema.optionalKey(Schema.String),
+	text: Schema.optionalKey(Schema.String),
+	prop: Schema.optionalKey(Schema.String),
+	value: Schema.optionalKey(Schema.Json),
+	repeat: Schema.optionalKey(Schema.Union([Schema.Boolean, Schema.Number])),
+	ms: Schema.optionalKey(Schema.Number),
+	position: Schema.optionalKey(Schema.Number),
+	modifiers: Schema.optionalKey(Schema.Array(Modifier)),
+	phase: Schema.optionalKey(KeyPhase),
+	button: Schema.optionalKey(Schema.Number),
+	buttons: Schema.optionalKey(Schema.Number),
+	pointerType: Schema.optionalKey(PointerType),
+	pointerId: Schema.optionalKey(Schema.Number),
+	detail: Schema.optionalKey(Schema.Number),
+	count: Schema.optionalKey(Schema.Number),
+	canceled: Schema.optionalKey(Schema.Boolean),
+	defaultPrevented: Schema.optionalKey(Schema.Boolean),
+	isComposing: Schema.optionalKey(Schema.Boolean),
+	inputEvent: Schema.optionalKey(Schema.String),
+	set: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json))
+}), Rest);
+const ExpectStep = Schema.Struct({ expect: Expectation });
+const Step = Schema.Union([ActionStep, ExpectStep]);
+const isExpectStep = (step) => !("event" in step);
+const Scenario = Schema.Struct({
+	id: Schema.String,
+	upstream: Schema.optionalKey(Schema.String),
+	upstreamTest: Schema.optionalKey(Schema.String),
+	apg: Schema.optionalKey(Schema.String),
+	config: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+	steps: Schema.Array(Step),
+	notes: Schema.optionalKey(Schema.String)
+});
+/** An upstream behaviour deliberately not ported (`upstream*` when it has a single source). */
+const Skipped = Schema.Struct({
+	id: Schema.optionalKey(Schema.String),
+	upstream: Schema.optionalKey(Schema.String),
+	upstreamTest: Schema.optionalKey(Schema.String),
+	reason: Schema.String
+});
+const ScenarioFile = Schema.Struct({
+	pattern: Schema.String,
+	source: Schema.String,
+	commit: Schema.optionalKey(Schema.NullOr(Schema.String)),
+	license: Schema.optionalKey(Schema.String),
+	upstream: Schema.optionalKey(Schema.String),
+	retrieved: Schema.optionalKey(Schema.String),
+	fixture: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
+	notes: Schema.optionalKey(Schema.String),
+	skipped: Schema.optionalKey(Schema.Array(Skipped)),
+	scenarios: Schema.Array(Scenario)
+});
+/** Decode a scenario JSON document (the trust boundary for ported data). */
+const parseScenarioFile = (input) => Schema.decodeUnknownSync(ScenarioFile)(input);
+/** A step or observation the target does not model. Skips, never fails. */
+var Unsupported = class extends Error {};
+/** The target disagreed with the scenario (or, in a walk, with the other target). */
+var ScenarioMismatch = class extends Error {};
+const normalize = (target) => target === null ? null : target.replace(/:0$/, "");
+const partName = (target) => target.replace(/:0$/, "");
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const mismatch = (what, expected, actual) => {
+	throw new ScenarioMismatch(`${what}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+};
+const check = (expectation, observer, skipped) => {
+	const attempt = (label, run) => {
+		try {
+			run();
+		} catch (error) {
+			if (!(error instanceof Unsupported)) throw error;
+			skipped.push(`${label}: ${error.message}`);
+		}
+	};
+	for (const key of Object.keys(expectation)) if (!CHECKED_EXPECTATION_KEYS.has(key)) skipped.push(`${key}: expectation not supported by the replay engine`);
+	if (expectation.focus !== void 0) {
+		const { focus } = expectation;
+		attempt("focus", () => {
+			const actual = normalize(observer.focus());
+			if (actual !== normalize(focus)) mismatch("focus", focus, actual);
+		});
+	}
+	for (const [target, attrs] of Object.entries(expectation.attrs ?? {})) for (const [name, expected] of Object.entries(attrs)) attempt(`${target}[${name}]`, () => {
+		const actual = observer.attr(target, name);
+		if (actual !== expected) mismatch(`${target}[${name}]`, expected, actual);
+	});
+	if (expectation.visible !== void 0) {
+		const { visible } = expectation;
+		attempt("visible", () => {
+			const expected = visible.map(partName).sort();
+			const actual = observer.visible().map(partName).sort();
+			if (!same(actual, expected)) mismatch("visible", expected, actual);
+		});
+	}
+	for (const [name, expected] of Object.entries(expectation.events ?? {})) attempt(`events.${name}`, () => {
+		const actual = observer.events(name);
+		if (!same(actual, expected)) mismatch(`events.${name}`, expected, actual);
+	});
+	if (expectation.value !== void 0) {
+		const { value } = expectation;
+		attempt("value", () => {
+			if (observer.value === void 0) throw new Unsupported("no observable value");
+			const actual = observer.value();
+			if (!same(actual, value)) mismatch("value", value, actual);
+		});
+	}
+};
+/**
+* Run one scenario against a driver. The bridge is the shared vocabulary gate:
+* a config or step it cannot translate makes the scenario `unsupported` for
+* every target alike, before anything runs. Throws `ScenarioMismatch` on a
+* failed expectation.
+*/
+const replayScenario = async (scenario, bridge, makeDriver) => {
+	const config = scenario.config ?? {};
+	const understood = /* @__PURE__ */ new Set([...CORE_STEP_FIELDS, ...bridge.stepFields ?? []]);
+	try {
+		bridge.setup(config);
+		for (const step of scenario.steps) if (!isExpectStep(step)) {
+			const unknown = Object.keys(step).find((k) => !understood.has(k));
+			if (unknown !== void 0) throw new Unsupported(`step field "${unknown}"`);
+			bridge.event(step);
+		}
+	} catch (error) {
+		if (error instanceof Unsupported) return {
+			status: "unsupported",
+			reason: error.message
+		};
+		throw error;
+	}
+	const driver = await makeDriver(config);
+	const skipped = [];
+	try {
+		for (const [index, step] of scenario.steps.entries()) try {
+			if (isExpectStep(step)) check(step.expect, driver.observer, skipped);
+			else await driver.perform(step);
+		} catch (error) {
+			if (error instanceof ScenarioMismatch) throw new ScenarioMismatch(`${scenario.id} step ${index}: ${error.message}`);
+			throw error;
+		}
+	} finally {
+		driver.dispose?.();
+	}
+	return {
+		status: "passed",
+		skipped
+	};
+};
+/** A driver over the generated reference model. Checks every invariant after every step. */
+const specDriver = (model, bridge, config = {}) => {
+	const apply = (state, event) => {
+		const next = model.transition(state, event);
+		const violated = violatedInvariants(model, next);
+		if (violated.length > 0) throw new ScenarioMismatch(`spec invariant violated after ${JSON.stringify(event)}: ${violated.join(", ")}`);
+		return next;
+	};
+	const { value } = bridge;
+	let state = bridge.setup(config).reduce(apply, model.initial);
+	const fired = /* @__PURE__ */ new Map();
+	return {
+		perform: (step) => {
+			const before = state;
+			state = bridge.event(step).reduce(apply, state);
+			for (const [name, payload] of bridge.events(before, state)) fired.set(name, [...fired.get(name) ?? [], payload]);
+		},
+		observer: {
+			focus: () => bridge.focus(state),
+			attr: (target, name) => bridge.attr(state, target, name),
+			visible: () => bridge.visible(state),
+			events: (name) => fired.get(bridge.eventName?.(name) ?? name) ?? [],
+			...value === void 0 ? {} : { value: () => value(state) }
+		}
+	};
+};
+const observed = (read) => {
+	try {
+		return read();
+	} catch (error) {
+		if (error instanceof Unsupported) return "?";
+		throw error;
+	}
+};
+const snapshot = (observer, probe) => [
+	["focus", observed(() => normalize(observer.focus()))],
+	["visible", observer.visible().map(partName).sort()],
+	...probe.attrs.map(([target, name]) => [`${target}[${name}]`, observed(() => observer.attr(target, name))]),
+	...probe.events.map((name) => [`events.${name}`, [...observer.events(name)]])
+];
+const LCG_MULTIPLIER = 1664525;
+const LCG_INCREMENT = 1013904223;
+const UINT32 = 4294967296;
+const lcg = (seed) => {
+	let state = seed >>> 0;
+	return () => {
+		state = Math.imul(state, LCG_MULTIPLIER) + LCG_INCREMENT >>> 0;
+		return state / UINT32;
+	};
+};
+/**
+* Differential test: the same random steps into the reference and the
+* candidate; every probed observation must agree after every step.
+*/
+const differentialWalk = async (options) => {
+	const rand = lcg(options.seed ?? 0);
+	for (let run = 0; run < (options.runs ?? 20); run += 1) {
+		const [reference, candidate] = await options.makePair();
+		const path = [];
+		try {
+			for (let index = 0; index < (options.steps ?? 30); index += 1) {
+				const step = options.alphabet[Math.floor(rand() * options.alphabet.length)];
+				if (step === void 0) return;
+				path.push(step);
+				await reference.perform(step);
+				await candidate.perform(step);
+				const expected = snapshot(reference.observer, options.probe);
+				const actual = snapshot(candidate.observer, options.probe);
+				const differing = expected.flatMap(([label, value], position) => {
+					const other = actual[position]?.[1] ?? "?";
+					return value !== "?" && other !== "?" && !same(value, other) ? [label] : [];
+				});
+				if (differing.length > 0) throw new ScenarioMismatch(`${differing.join(", ")} differ: spec ${JSON.stringify(expected)} vs implementation ${JSON.stringify(actual)} after ${JSON.stringify(path)}`);
+			}
+		} finally {
+			reference.dispose?.();
+			candidate.dispose?.();
+		}
+	}
+};
+//#endregion
+export { EXTENDED_STEP_FIELDS, ScenarioMismatch, Unsupported, differentialWalk, parseScenarioFile, replayScenario, specDriver };

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@cssints/apg-specs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.1",
+  "description": "APG widget specs: Quint sources, generated models, scenario bridges and ported scenario sets, the test oracle of headless widgets",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/apg-specs"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist",
+    "specs",
+    "shared",
+    "scenarios"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./scenario": {
+      "types": "./dist/scenario.d.mts",
+      "default": "./dist/scenario.mjs"
+    },
+    "./apg/listbox-shared": {
+      "types": "./dist/apg/listbox-shared.d.mts",
+      "default": "./dist/apg/listbox-shared.mjs"
+    },
+    "./apg/*.bridge": {
+      "types": "./dist/apg/*.bridge.d.mts",
+      "default": "./dist/apg/*.bridge.mjs"
+    },
+    "./apg/*.model.json": "./dist/apg/*.model.json",
+    "./canvas/*.bridge": {
+      "types": "./dist/canvas/*.bridge.d.mts",
+      "default": "./dist/canvas/*.bridge.mjs"
+    },
+    "./canvas/*.model.json": "./dist/canvas/*.model.json",
+    "./scenarios/apg/*.json": "./scenarios/apg/*.json",
+    "./scenarios/canvas/*.json": "./scenarios/canvas/*.json",
+    "./scenarios/parts.json": "./scenarios/parts.json",
+    "./specs/apg/*.qnt": "./specs/apg/*.qnt",
+    "./specs/canvas/*.qnt": "./specs/canvas/*.qnt",
+    "./shared/*.qnt": "./shared/*.qnt",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@quint-machine/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}