@cssints/apg-specs 0.0.0-stage → 0.5.1

package/dist/canvas/canvas.bridge.d.mts

@@ -0,0 +1,190 @@
+import { ActionStep, Probe, ScenarioConfig, SpecBridge } from "../scenario.mjs";
+import { QuintModelValue } from "@quint-machine/core";
+import { Schema } from "effect";
+//#region src/canvas/canvas.bridge.d.ts
+/**
+ * Canvas vocabulary <-> `specs/canvas/camera.qnt` and `specs/canvas/pointer.qnt`.
+ *
+ * Two machines, so two bridges (`cameraBridge`, `pointerBridge`). Both parse a scenario step into
+ * a typed, library-neutral OP (`parseCameraOp`, `parsePointerOp`); the spec side turns the op into
+ * spec events, the DOM driver (packages/headless/test) turns the same op into real input. Anything
+ * outside the model's pools throws `Unsupported`, which skips the scenario on every target.
+ *
+ * Why steps are pool-shaped: the specs pick every selector from a small fixed pool (one nondet per
+ * action), so a step may only name a pool member - a palette position `p0..p11`, a pan delta from
+ * {-9e6, -400, 0, 5, 9e6}, a zoom factor from {1/2, 3/4, 5/4, 3/2, 2, 16, 1/16}, a named anchor.
+ *
+ * Observation targets (probe / `expect.attrs`):
+ *   `layer`   `--canvas-x` `--canvas-y` `--canvas-zoom`   the rendered camera custom properties
+ *   `node<i>` `aria-selected` `--node-x` `--node-y` `content-visibility`
+ *   `live`    `text`                                      the live region
+ *   `state`   `mode owner selection cursor editing guides culled announcements`  (pointer)
+ *             `camera viewport tweening reducedMotion`                           (camera)
+ * `state` reads the primitive's own snapshot (`Canvas.peek()`), JSON-formatted by `formatValue`.
+ *
+ * Not an oracle: `culled` is an independent TS port of the spec's `culled` def (defs are not
+ * callable from the reference model), so it checks the primitive against the port, not the spec.
+ */
+/** pointer.qnt's three nodes, bottom of the z-order first. */
+export declare const NODES: readonly [{
+  readonly id: "0";
+  readonly x: 100;
+  readonly y: 100;
+  readonly width: 200;
+  readonly height: 100;
+  readonly label: "Node A";
+}, {
+  readonly id: "1";
+  readonly x: 250;
+  readonly y: 150;
+  readonly width: 200;
+  readonly height: 150;
+  readonly label: "Node B";
+}, {
+  readonly id: "2";
+  readonly x: 600;
+  readonly y: 400;
+  readonly width: 100;
+  readonly height: 100;
+  readonly label: "Node C";
+}];
+/** pointer.qnt's VW / VH: the viewport its culling predicate uses. */
+export declare const POINTER_VIEWPORT: {
+  readonly width: 1024;
+  readonly height: 768;
+};
+/** pointer.qnt's screen palette (px): `p<k>` is `PALETTE[k]`. */
+export declare const PALETTE: ReadonlyArray<readonly [x: number, y: number]>;
+/** pointer.qnt's `extX(k)` / `extY(k)`: the positions a host move can set (the last is far past the world bound). */
+export declare const HOST_POSITIONS: ReadonlyArray<readonly [x: number, y: number]>;
+/** pointer.qnt's `zoomPreset(level)`, as zoom values. */
+export declare const ZOOM_LEVELS: ReadonlyArray<number>;
+export declare const VIEWPORTS: ReadonlyArray<readonly [width: number, height: number]>;
+export declare const PAN_DELTAS: ReadonlyArray<number>;
+export declare const ZOOM_FACTORS: ReadonlyArray<number>;
+export declare const ANCHORS: readonly ["top-left", "centre", "bottom-right", "quarter"];
+export type AnchorName = (typeof ANCHORS)[number];
+export declare const CENTRE_POINTS: ReadonlyArray<readonly [x: number, y: number]>;
+/** camera.qnt's `anchorX` / `anchorY`: where an anchor name sits in a viewport of this size. */
+export declare const anchorPoint: (anchor: AnchorName, width: number, height: number) => readonly [x: number, y: number];
+type Json = Schema.Json;
+export type CameraOp = {
+  readonly op: "resize";
+  readonly viewport: number;
+} | {
+  readonly op: "motion";
+  readonly reduced: boolean;
+} | {
+  readonly op: "pan";
+  readonly dx: number;
+  readonly dy: number;
+} | {
+  readonly op: "zoom";
+  /** Fixed point (4096 = x1). */
+  readonly factor: number;
+  readonly anchor: AnchorName;
+} | {
+  readonly op: "zoomLimit";
+  readonly limit: "min" | "max";
+  readonly anchor: AnchorName;
+} | {
+  readonly op: "tween";
+  readonly goal: {
+    readonly kind: "zoom";
+    readonly zoom: number;
+    readonly anchor: AnchorName;
+  } | {
+    readonly kind: "centre";
+    readonly x: number;
+    readonly y: number;
+  };
+} | {
+  readonly op: "tick";
+} | {
+  readonly op: "cancelTween";
+};
+/** A camera step -> an op; `Unsupported` for anything the camera machine does not model. */
+export declare const parseCameraOp: (step: ActionStep) => CameraOp;
+export type PointerId = 1 | 2;
+export type PointerOp = {
+  readonly op: "down" | "move";
+  readonly pointer: PointerId;
+  readonly at: number;
+} | {
+  readonly op: "up" | "cancel";
+  readonly pointer: PointerId;
+} | {
+  readonly op: "shift" | "space" | "snap";
+  readonly on: boolean;
+} | {
+  readonly op: "marquee";
+  readonly mode: "contain" | "overlap";
+} | {
+  readonly op: "zoom";
+  readonly level: number;
+} | {
+  readonly op: "edit";
+} |
+/** A host sets node `node`'s committed position to `HOST_POSITIONS[position]`. */
+{
+  readonly op: "place";
+  readonly node: number;
+  readonly position: number;
+};
+/**
+ * A pointer step -> an op. Pointer input is `{ event: pointerdown | pointermove | pointerup |
+ * pointercancel, target: "p<k>", value: <pointer id, default 1> }`; modifiers and parameters are
+ * `prop` steps (`shift`, `space`, `snap`, `marquee`, `zoom`, `edit`).
+ */
+export declare const parsePointerOp: (step: ActionStep) => PointerOp;
+export interface CameraConfig {
+  readonly reducedMotion: boolean;
+}
+/** Scenario `config` -> what both targets are mounted with. */
+export declare const cameraConfig: (config: ScenarioConfig) => CameraConfig;
+export interface PointerConfig {
+  readonly marquee: "contain" | "overlap";
+  readonly snap: boolean;
+}
+export declare const pointerConfig: (config: ScenarioConfig) => PointerConfig;
+/** How a `state` value is read as an attribute: a string as is, `null` = absent, the rest JSON. */
+export declare const formatValue: (value: Json | undefined) => string | null;
+type CameraValue = {
+  readonly camera: {
+    readonly tx: number;
+    readonly ty: number;
+    readonly z: number;
+  };
+  readonly viewport: {
+    readonly width: number;
+    readonly height: number;
+  };
+  readonly tweening: boolean;
+  readonly reducedMotion: boolean;
+};
+export declare const cameraValue: (state: QuintModelValue) => CameraValue;
+export declare const cameraBridge: SpecBridge;
+type PointerValue = {
+  readonly mode: string;
+  readonly owner: number | null;
+  readonly selection: ReadonlyArray<string>;
+  readonly cursor: string | null;
+  readonly editing: string | null;
+  readonly guides: {
+    readonly x: boolean;
+    readonly y: boolean;
+  };
+  readonly culled: ReadonlyArray<string>;
+  readonly announcements: number;
+};
+export declare const pointerValue: (state: QuintModelValue) => PointerValue;
+/** The text the primitive's default messages give a settled selection. */
+export declare const selectionText: (ids: ReadonlyArray<string>) => string;
+export declare const pointerBridge: SpecBridge;
+/** The user-level steps a pointer differential walk draws from. */
+export declare const pointerSteps: ReadonlyArray<ActionStep>;
+export declare const pointerProbe: Probe;
+/** The user-level steps a camera differential walk draws from. */
+export declare const cameraSteps: ReadonlyArray<ActionStep>;
+export declare const cameraProbe: Probe;
+//#endregion