@kraken-e2e/contracts 0.1.0

package/dist/session.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The core session surface (ADR-0001 §5.4 Option C, exact list fixed by
+ * ADR-0002 D1): locator-driven, stateless operations every platform can offer,
+ * plus a typed native escape hatch. This surface grows ONLY through the parity
+ * gate (RFC + CTK case + passing Android AND iOS implementations).
+ */
+/** Portable locator strategies; `native` is explicitly non-portable and CTK-exempt. */
+export type TargetLocator = {
+    readonly by: 'testId';
+    readonly value: string;
+} | {
+    readonly by: 'text';
+    readonly value: string;
+    readonly exact?: boolean;
+} | {
+    readonly by: 'a11y';
+    readonly value: string;
+} | {
+    readonly by: 'native';
+    readonly value: string;
+};
+/**
+ * Cross-platform semantic keys — FAITHFUL on both mobile platforms (contract
+ * 2.0, ratified 2026-07-04): Android via system keycodes, iOS via HID
+ * keyboard events (live-verified). Android's BACK is deliberately NOT here:
+ * it is an Android platform concept, not a key anywhere else (live-tested:
+ * iOS ignores even the HID 'AC Back' consumer event) — reach it via native()
+ * or a future Android-specific capability.
+ */
+export type SemanticKey = 'enter' | 'escape' | 'tab';
+export type WaitState = 'visible' | 'hidden' | 'attached';
+export interface SessionWaitOptions {
+    readonly timeoutMs?: number;
+    readonly pollMs?: number;
+}
+export interface ArtifactRef {
+    readonly kind: 'screenshot' | 'log' | 'video' | 'source';
+    readonly path: string;
+}
+/** The operations the parity report is generated over (ADR-0002 D1). */
+export declare const CORE_OPERATIONS: readonly ["tap", "typeText", "readText", "waitFor", "isDisplayed", "scrollIntoView", "pressKey", "navigate", "screenshot", "source", "dispose"];
+export type CoreOperation = (typeof CORE_OPERATIONS)[number];
+/**
+ * Typed escape hatch registry. Driver packages augment it via declaration
+ * merging (zero core→driver imports — ADR-0001 §5.4):
+ *
+ *   declare module '@kraken-e2e/contracts' {
+ *     interface KrakenNativeSessions { web: WebdriverIO.Browser }
+ *   }
+ */
+export interface KrakenNativeSessions {
+}
+export interface UserSession {
+    readonly actorId: string;
+    readonly driverId: string;
+    readonly platform: string;
+    /** Feeds the parity report; an unsupported op throws KRK-SESSION-OP-UNSUPPORTED. */
+    readonly capabilities: Readonly<Record<CoreOperation, 'supported' | 'unsupported'>>;
+    tap(target: TargetLocator): Promise<void>;
+    typeText(target: TargetLocator, text: string): Promise<void>;
+    readText(target: TargetLocator): Promise<string>;
+    waitFor(target: TargetLocator, state: WaitState, opts?: SessionWaitOptions): Promise<void>;
+    isDisplayed(target: TargetLocator): Promise<boolean>;
+    /** Intent-level (bring element into view) — not a raw gesture (ADR-0002 D1). */
+    scrollIntoView(target: TargetLocator): Promise<void>;
+    pressKey(key: SemanticKey): Promise<void>;
+    /** URL (web) or deep link (mobile). */
+    navigate(destination: string): Promise<void>;
+    /** Path ref, never bytes. */
+    screenshot(): Promise<ArtifactRef>;
+    /** DOM / view-hierarchy dump. */
+    source(): Promise<string>;
+    /** Idempotent — SIGINT teardown may call it more than once. */
+    dispose(): Promise<void>;
+    /** Typed platform-native session (declaration merging; throws if kind mismatches). */
+    native<K extends keyof KrakenNativeSessions>(kind: K): KrakenNativeSessions[K];
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/session.js

@@ -0,0 +1,21 @@
+/**
+ * The core session surface (ADR-0001 §5.4 Option C, exact list fixed by
+ * ADR-0002 D1): locator-driven, stateless operations every platform can offer,
+ * plus a typed native escape hatch. This surface grows ONLY through the parity
+ * gate (RFC + CTK case + passing Android AND iOS implementations).
+ */
+/** The operations the parity report is generated over (ADR-0002 D1). */
+export const CORE_OPERATIONS = [
+    'tap',
+    'typeText',
+    'readText',
+    'waitFor',
+    'isDisplayed',
+    'scrollIntoView',
+    'pressKey',
+    'navigate',
+    'screenshot',
+    'source',
+    'dispose',
+];
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA+BH,wEAAwE;AACxE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,KAAK;IACL,UAAU;IACV,UAAU;IACV,SAAS;IACT,aAAa;IACb,gBAAgB;IAChB,UAAU;IACV,UAAU;IACV,YAAY;IACZ,QAAQ;IACR,SAAS;CACD,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,22 @@
+export interface ContractVersion {
+    readonly major: number;
+    readonly minor: number;
+}
+/**
+ * Version of the driver/reporter SPI this package describes. Baked into every
+ * plugin by defineDriver() and checked by core's registry at load time.
+ * 1.0 froze with ADR-0002's acceptance (2026-07-03). 2.0 (2026-07-04):
+ * BREAKING — SemanticKey narrowed to enter|escape|tab ('back' removed: an
+ * Android-only concept, proven not-a-key on iOS by live HID probing; see the
+ * ADR-0002 amendment). Breaking SPI change = major bump, addition = minor
+ * bump; the API-surface snapshot test enforces the discipline.
+ */
+export declare const CONTRACT_VERSION: ContractVersion;
+/**
+ * The load-time compatibility rule (ADR-0001 §5.10): same major, and the
+ * plugin must not have been compiled against a NEWER minor than the host
+ * supports (it may call capabilities the host lacks). Older plugin on newer
+ * host is fine.
+ */
+export declare function isContractCompatible(plugin: ContractVersion, host: ContractVersion): boolean;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAAwC,CAAC;AAExE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAE5F"}

package/dist/version.js

@@ -0,0 +1,20 @@
+/**
+ * Version of the driver/reporter SPI this package describes. Baked into every
+ * plugin by defineDriver() and checked by core's registry at load time.
+ * 1.0 froze with ADR-0002's acceptance (2026-07-03). 2.0 (2026-07-04):
+ * BREAKING — SemanticKey narrowed to enter|escape|tab ('back' removed: an
+ * Android-only concept, proven not-a-key on iOS by live HID probing; see the
+ * ADR-0002 amendment). Breaking SPI change = major bump, addition = minor
+ * bump; the API-surface snapshot test enforces the discipline.
+ */
+export const CONTRACT_VERSION = { major: 2, minor: 0 };
+/**
+ * The load-time compatibility rule (ADR-0001 §5.10): same major, and the
+ * plugin must not have been compiled against a NEWER minor than the host
+ * supports (it may call capabilities the host lacks). Older plugin on newer
+ * host is fine.
+ */
+export function isContractCompatible(plugin, host) {
+    return plugin.major === host.major && plugin.minor <= host.minor;
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAoB,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;AAExE;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAuB,EAAE,IAAqB;IACjF,OAAO,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC;AACnE,CAAC"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@kraken-e2e/contracts",
+  "version": "0.1.0",
+  "description": "Zero-runtime-dependency SPI: driver/reporter interfaces, event types, error codes, defineDriver/defineReporter, CONTRACT_VERSION",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "dependencies": {
+    "@kraken-e2e/signaling": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "license": "GPL-3.0-only",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}