@wenathlan/saddle 1.8.8 → 1.8.9

package/dist/browser/recorder.d.ts

@@ -0,0 +1,27 @@
+/**
+ * browser recorder captures action and snapshot boundaries for deterministic replay.
+ */
+/** Creates a bounded recorder that links actions to the snapshot used before execution. */
+export declare function actionrecorder(options?: {}): {
+    snapshot: (snapshot: any) => any;
+    action: (input?: {}) => {
+        type: string;
+        t: number;
+        action: string;
+        snapshotid: any;
+        tabid: any;
+        frameid: any;
+        windowid: any;
+        context: {};
+        payload: any;
+    };
+    list: () => any[];
+    manifest: () => {
+        version: number;
+        startedat: number;
+        eventcount: number;
+        lastsnapshotid: any;
+        events: any[];
+    };
+};
+//# sourceMappingURL=recorder.d.ts.map

package/dist/browser/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../browser/recorder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,OAAO,KAAK;;;;;;;;;;;;;;;;;;;;;EAS1C"}

package/dist/browser/recorder.js

@@ -0,0 +1,22 @@
+/**
+ * browser recorder captures action and snapshot boundaries for deterministic replay.
+ */
+/** Creates a bounded recorder that links actions to the snapshot used before execution. */
+export function actionrecorder(options = {}) {
+    const startedat = Number(options.startedat ?? Date.now());
+    const events = [];
+    let lastsnapshotid;
+    function snapshot(snapshot) { lastsnapshotid = snapshot?.snapshotid; const context = recordercontext(snapshot); events.push({ type: "snapshot", t: Date.now() - startedat, snapshotid: lastsnapshotid, tabid: snapshot?.tabid, frameid: snapshot?.frameid, context }); return snapshot; }
+    function action(input = {}) { const context = recordercontext(input.context ?? input); const event = { type: "action", t: Date.now() - startedat, action: String(input.action), snapshotid: input.snapshotid ?? lastsnapshotid, tabid: input.tabid, frameid: input.frameid, windowid: input.windowid, context, payload: input.payload ?? {} }; events.push(event); return { ...event }; }
+    function list() { return events.map((event) => ({ ...event, payload: { ...event.payload } })); }
+    function manifest() { return { version: 1, startedat, eventcount: events.length, lastsnapshotid, events: list() }; }
+    return { snapshot, action, list, manifest };
+}
+function recordercontext(value = {}) {
+    const context = {};
+    for (const name of ["windowid", "tabid", "frameid"])
+        if (value[name] !== undefined)
+            context[name] = String(value[name]);
+    return Object.keys(context).length ? context : undefined;
+}
+//# sourceMappingURL=recorder.js.map

package/dist/browser/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../browser/recorder.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,2FAA2F;AAC3F,MAAM,UAAU,cAAc,CAAC,OAAO,GAAG,EAAE;IACzC,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,EAAE,CAAC;IAClB,IAAI,cAAc,CAAC;IACnB,SAAS,QAAQ,CAAC,QAAQ,IAAI,cAAc,GAAG,QAAQ,EAAE,UAAU,CAAC,CAAC,MAAM,OAAO,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC;IACzR,SAAS,MAAM,CAAC,KAAK,GAAG,EAAE,IAAI,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,cAAc,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC;IACzX,SAAS,IAAI,KAAK,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAChG,SAAS,QAAQ,KAAK,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IACpH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC9C,CAAC;AAED,SAAS,eAAe,CAAC,KAAK,GAAG,EAAE;IACjC,MAAM,OAAO,GAAG,EAAE,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC;QAAE,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACxH,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC"}

package/dist/browser/session.d.ts

@@ -0,0 +1,14 @@
+export declare function browsersession(options?: {}): {
+    id: any;
+    fingerprint: any;
+    proxy: any;
+    record(event: any): any;
+    events(): any[];
+    manifest(): {
+        id: any;
+        fingerprint: any;
+        proxy: any;
+        eventcount: number;
+    };
+};
+//# sourceMappingURL=session.d.ts.map

package/dist/browser/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../browser/session.ts"],"names":[],"mappings":"AAKA,wBAAgB,cAAc,CAAC,OAAO,KAAK;;;;;;;;;;;;EAa1C"}

package/dist/browser/session.js

@@ -0,0 +1,21 @@
+/**
+ * browser sessions bind one fingerprint to one proxy and one event recorder.
+ */
+import { fingerprintfor, fingerprintvalidate } from "./fingerprint.js";
+export function browsersession(options = {}) {
+    const id = options.id ?? `browsersession${Date.now().toString(36)}`;
+    const fingerprint = options.fingerprint ?? fingerprintfor(id, options);
+    if (!fingerprintvalidate(fingerprint))
+        throw new TypeError("browser fingerprint is incoherent");
+    const events = [];
+    return {
+        id,
+        fingerprint,
+        proxy: options.proxy,
+        record(event) { if (!event || !Number.isFinite(event.t) || event.t < 0 || typeof event.type !== "string")
+            throw new TypeError("browser event is invalid"); events.push({ ...event }); return event; },
+        events() { return events.map((event) => ({ ...event })); },
+        manifest() { return { id, fingerprint: { ...fingerprint }, proxy: options.proxy?.id ?? options.proxy, eventcount: events.length }; }
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/browser/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../browser/session.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvE,MAAM,UAAU,cAAc,CAAC,OAAO,GAAG,EAAE;IACzC,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,iBAAiB,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;IACpE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,cAAc,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACvE,IAAI,CAAC,mBAAmB,CAAC,WAAW,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAC;IAChG,MAAM,MAAM,GAAG,EAAE,CAAC;IAClB,OAAO;QACL,EAAE;QACF,WAAW;QACX,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,SAAS,CAAC,0BAA0B,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC;QACrM,MAAM,KAAK,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,QAAQ,KAAK,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,GAAG,WAAW,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,EAAE,IAAI,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;KACrI,CAAC;AACJ,CAAC"}

package/dist/browser/snapshot.d.ts

@@ -0,0 +1,57 @@
+/**
+ * browser snapshots turn page state into bounded serializable data with stable references.
+ */
+/** Creates a validated page snapshot for browser, MCP and extension adapters. */
+export declare function pagesnapshot(input?: {}): {
+    version: number;
+    snapshotid: string;
+    tabid: string;
+    frameid: string;
+    url: string;
+    title: string;
+    text: string;
+    elements: {
+        ref: string;
+        role: string;
+        name: string;
+        value: string;
+        disabled: boolean;
+    }[];
+};
+/** Creates an element reference bound to a snapshot and browser context. */
+export declare function snapshotref(snapshot: any, input?: {}): {
+    version: number;
+    snapshotid: string;
+    tabid: string;
+    frameid: string;
+    ref: string;
+};
+/** Throws a stable error when an action uses a reference from a previous page state. */
+export declare function assertfreshsnapshot(snapshot: any, reference: any): boolean;
+/** Computes additions, removals and changed labels between two snapshots. */
+export declare function snapshotdiff(previous: any, current: any): {
+    from: string;
+    to: string;
+    added: {
+        ref: string;
+        role: string;
+        name: string;
+        value: string;
+        disabled: boolean;
+    }[];
+    removed: {
+        ref: string;
+        role: string;
+        name: string;
+        value: string;
+        disabled: boolean;
+    }[];
+    changed: {
+        ref: string;
+        role: string;
+        name: string;
+        value: string;
+        disabled: boolean;
+    }[];
+};
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/browser/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../browser/snapshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,KAAK,KAAK;;;;;;;;;;;;;;;EActC;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,QAAQ,KAAA,EAAE,KAAK,KAAK;;;;;;EAK/C;AAED,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,QAAQ,KAAA,EAAE,SAAS,KAAA,WAStD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,QAAQ,KAAA,EAAE,OAAO,KAAA;;;;;;;;;;;;;;;;;;;;;;;;EAS7C"}

package/dist/browser/snapshot.js

@@ -0,0 +1,57 @@
+/**
+ * browser snapshots turn page state into bounded serializable data with stable references.
+ */
+/** Creates a validated page snapshot for browser, MCP and extension adapters. */
+export function pagesnapshot(input = {}) {
+    if (!input || typeof input !== "object")
+        throw new TypeError("page snapshot must be an object");
+    const snapshot = {
+        version: 1,
+        snapshotid: String(input.snapshotid ?? `snapshot${Date.now().toString(36)}`),
+        tabid: input.tabid === undefined ? undefined : String(input.tabid),
+        frameid: input.frameid === undefined ? undefined : String(input.frameid),
+        url: String(input.url ?? ""),
+        title: String(input.title ?? ""),
+        text: String(input.text ?? "").slice(0, input.maxtext ?? 100000),
+        elements: normalizeelements(input.elements)
+    };
+    if (!snapshot.snapshotid || !snapshot.url)
+        throw new TypeError("page snapshot requires snapshotid and url");
+    return snapshot;
+}
+/** Creates an element reference bound to a snapshot and browser context. */
+export function snapshotref(snapshot, input = {}) {
+    const current = pagesnapshot(snapshot);
+    const ref = String(input.ref ?? "");
+    if (!current.elements.some((element) => element.ref === ref))
+        throw new TypeError(`snapshot reference not found: ${ref}`);
+    return { version: 1, snapshotid: current.snapshotid, tabid: current.tabid, frameid: current.frameid, ref };
+}
+/** Throws a stable error when an action uses a reference from a previous page state. */
+export function assertfreshsnapshot(snapshot, reference) {
+    const current = pagesnapshot(snapshot);
+    if (!reference || reference.snapshotid !== current.snapshotid || (reference.tabid !== undefined && reference.tabid !== current.tabid) || (reference.frameid !== undefined && reference.frameid !== current.frameid)) {
+        const error = new Error("browser snapshot is stale");
+        error.code = "STALE_SNAPSHOT";
+        error.retryable = true;
+        throw error;
+    }
+    return true;
+}
+/** Computes additions, removals and changed labels between two snapshots. */
+export function snapshotdiff(previous, current) {
+    const before = pagesnapshot(previous);
+    const after = pagesnapshot(current);
+    const oldmap = new Map(before.elements.map((element) => [element.ref, element]));
+    const newmap = new Map(after.elements.map((element) => [element.ref, element]));
+    const added = after.elements.filter((element) => !oldmap.has(element.ref));
+    const removed = before.elements.filter((element) => !newmap.has(element.ref));
+    const changed = after.elements.filter((element) => oldmap.has(element.ref) && JSON.stringify(oldmap.get(element.ref)) !== JSON.stringify(element));
+    return { from: before.snapshotid, to: after.snapshotid, added, removed, changed };
+}
+function normalizeelements(elements) {
+    if (!Array.isArray(elements))
+        return [];
+    return elements.slice(0, 500).map((element, index) => ({ ref: String(element?.ref ?? `e${index + 1}`), role: String(element?.role ?? "generic"), name: String(element?.name ?? "").trim().slice(0, 200), value: element?.value === undefined ? undefined : String(element.value).slice(0, 500), disabled: Boolean(element?.disabled) }));
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/browser/snapshot.js.map

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

package/dist/captcha/contract.d.ts

@@ -0,0 +1,35 @@
+/**
+ * captcha contracts separate detection and evidence from any solver provider.
+ */
+export declare const captchatypes: readonly string[];
+export declare function captchacontract(options?: {}): {
+    detect(context: any): Promise<{
+        kind: any;
+        detected: boolean;
+        sitekey: any;
+        evidenceurl: any;
+    }>;
+    request(context: any): Promise<{
+        status: string;
+        kind: any;
+        message: string;
+        context: any;
+    }>;
+    solve(context: any): Promise<{
+        status: string;
+        reason: string;
+        passed?: undefined;
+        solver?: undefined;
+        token?: undefined;
+        evidenceurl?: undefined;
+    } | {
+        reason?: undefined;
+        status: string;
+        passed: boolean;
+        solver: any;
+        token: any;
+        evidenceurl: any;
+    }>;
+    assert(result: any): any;
+};
+//# sourceMappingURL=contract.d.ts.map

package/dist/captcha/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../captcha/contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,YAAY,mBAAmE,CAAC;AAE7F,wBAAgB,eAAe,CAAC,OAAO,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS3C"}

package/dist/captcha/contract.js

@@ -0,0 +1,17 @@
+/**
+ * captcha contracts separate detection and evidence from any solver provider.
+ */
+export const captchatypes = Object.freeze(["hcaptcha", "turnstile", "recaptcha", "unknown"]);
+export function captchacontract(options = {}) {
+    const detect = options.detect ?? (() => ({ kind: "unknown", detected: false }));
+    const solve = options.solve;
+    return {
+        async detect(context) { const result = await detect(context); return { kind: captchatypes.includes(result.kind) ? result.kind : "unknown", detected: Boolean(result.detected), sitekey: result.sitekey, evidenceurl: result.evidenceurl }; },
+        async request(context) { return { status: "reviewrequired", kind: context.kind ?? "unknown", message: "captcha requires explicit human or external solver review", context }; },
+        async solve(context) { if (typeof solve !== "function")
+            return { status: "unavailable", reason: "no external solver configured" }; const result = await solve(context); return { status: result?.passed ? "passed" : "failed", passed: Boolean(result?.passed), solver: result?.solver ?? "external", token: result?.token, evidenceurl: result?.evidenceurl }; },
+        assert(result) { if (!result?.passed)
+            throw new Error("captcha assertion failed"); return result; }
+    };
+}
+//# sourceMappingURL=contract.js.map

package/dist/captcha/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../captcha/contract.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;AAE7F,MAAM,UAAU,eAAe,CAAC,OAAO,GAAG,EAAE;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IAChF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QAC5O,KAAK,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,SAAS,EAAE,OAAO,EAAE,2DAA2D,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;QAC/K,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,OAAO,KAAK,KAAK,UAAU;YAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC,CAAC,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;QACjW,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC;KACpG,CAAC;AACJ,CAAC"}

package/dist/captcha/evidence.d.ts

@@ -0,0 +1,10 @@
+export declare function evidence(options?: {}): {
+    kind: any;
+    passed: boolean;
+    solver: any;
+    evidenceurl: any;
+    sha256: any;
+    createdat: any;
+    metadata: any;
+};
+//# sourceMappingURL=evidence.d.ts.map

package/dist/captcha/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../captcha/evidence.ts"],"names":[],"mappings":"AAKA,wBAAgB,QAAQ,CAAC,OAAO,KAAK;IAE1B,IAAI;IAA6B,MAAM;IAA2B,MAAM;IAA8B,WAAW;IAAuB,MAAM;IAA8C,SAAS;IAAmC,QAAQ;EAC1P"}

package/dist/captcha/evidence.js

@@ -0,0 +1,9 @@
+/**
+ * captcha evidence stores references and hashes, never raw secrets or tokens by default.
+ */
+import { sha256 } from "../core/hash.js";
+export function evidence(options = {}) {
+    const payload = options.data instanceof Uint8Array ? options.data : options.data ? new TextEncoder().encode(String(options.data)) : null;
+    return { kind: options.kind ?? "unknown", passed: Boolean(options.passed), solver: options.solver ?? "manual", evidenceurl: options.evidenceurl, sha256: payload ? sha256(payload) : options.sha256, createdat: options.createdat ?? Date.now(), metadata: { ...(options.metadata ?? {}) } };
+}
+//# sourceMappingURL=evidence.js.map

package/dist/captcha/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../captcha/evidence.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,UAAU,QAAQ,CAAC,OAAO,GAAG,EAAE;IACnC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,YAAY,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzI,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;AAC/R,CAAC"}

package/dist/captcha/guard.d.ts

@@ -0,0 +1,23 @@
+/**
+ * captcha guard blocks silent automation and records a review event for audit.
+ */
+export declare function captchaguard(options?: {}): {
+    check(context: any): Promise<{
+        allowed: boolean;
+        result: any;
+        event?: undefined;
+        action?: undefined;
+    } | {
+        allowed: boolean;
+        result: any;
+        event: {
+            type: string;
+            at: number;
+            kind: any;
+            sitekey: any;
+        };
+        action: string;
+    }>;
+    events(): any[];
+};
+//# sourceMappingURL=guard.d.ts.map

package/dist/captcha/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../captcha/guard.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,KAAK;;;;;;;;;;;;;;;;;;EAMxC"}

package/dist/captcha/guard.js

@@ -0,0 +1,12 @@
+/**
+ * captcha guard blocks silent automation and records a review event for audit.
+ */
+export function captchaguard(options = {}) {
+    const events = [];
+    return {
+        async check(context) { const result = await options.contract.detect(context); if (!result.detected)
+            return { allowed: true, result }; const event = { type: "captcha.detected", at: Date.now(), kind: result.kind, sitekey: result.sitekey }; events.push(event); return { allowed: false, result, event, action: "reviewrequired" }; },
+        events() { return events.map((event) => ({ ...event })); }
+    };
+}
+//# sourceMappingURL=guard.js.map

package/dist/captcha/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../captcha/guard.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAAO,GAAG,EAAE;IACvC,MAAM,MAAM,GAAG,EAAE,CAAC;IAClB,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,KAAK,GAAG,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;QACvU,MAAM,KAAK,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;KAC3D,CAAC;AACJ,CAAC"}

package/dist/cli/main.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+/** Runs one CLI command and keeps external services behind adapters. */
+export declare function main(args?: string[]): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/dist/cli/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../cli/main.ts"],"names":[],"mappings":";AAiBA,wEAAwE;AACxE,wBAAsB,IAAI,CAAC,IAAI,WAAgB,iBAe9C"}

package/dist/cli/main.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * the cli keeps local execution explicit and leaves remote dispatch to adapters.
+ */
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { argv } from "node:process";
+import { eventbus } from "../core/events.js";
+import { localmemory } from "../memory/bridge.js";
+import { inprocess } from "../runners/inprocess.js";
+import { scheduler } from "../runners/scheduler.js";
+import { engine } from "../runtime/engine.js";
+import { localstorage } from "../storage/local.js";
+import { mcpserver } from "../mcp/server.js";
+import { modecatalog } from "../modes/matrix.js";
+/** Runs one CLI command and keeps external services behind adapters. */
+export async function main(args = argv.slice(2)) {
+    const command = args[0] ?? "help";
+    /* Help stays short and lists only stable local commands. */
+    if (["help", "--help", "-h"].includes(command)) {
+        console.log("saddle <command>\n\ncommands\n  help\n  modes\n  runexample\n  mcp");
+        return;
+    }
+    if (command === "modes") {
+        console.log(JSON.stringify(modecatalog(), null, 2));
+        return;
+    }
+    if (command === "runexample") {
+        const root = await mkdtemp(join(tmpdir(), "saddlecli"));
+        const events = eventbus();
+        const run = engine({ storage: localstorage(root), memory: localmemory(), scheduler: scheduler([inprocess()]), events });
+        const result = await run.run({ name: "cliexample", input: { hello: "saddle" } }, ({ job }) => ({ jobid: job.id, ok: true, message: "storage to working set to result" }));
+        console.log(JSON.stringify({ jobid: result.job.id, artifact: result.artifact, events: events.all().length }, null, 2));
+        return;
+    }
+    if (command === "mcp") {
+        const server = mcpserver({ scrape: async (url) => ({ url, links: [] }) });
+        console.log(JSON.stringify({ tools: server.listtools() }, null, 2));
+        return;
+    }
+    throw new Error(`unknown command: ${command}`);
+}
+if (import.meta.url === `file://${argv[1]}`)
+    main().catch((error) => { console.error(error); process.exitCode = 1; });
+//# sourceMappingURL=main.js.map

package/dist/cli/main.js.map

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

package/dist/core/errors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * typed engine errors keep recovery decisions explicit.
+ */
+export declare const errorcodes: Readonly<{
+    invalidinput: "INVALID_INPUT";
+    artifactnotfound: "ARTIFACT_NOT_FOUND";
+    storagefailure: "STORAGE_FAILURE";
+    runnerunavailable: "RUNNER_UNAVAILABLE";
+    jobfailed: "JOB_FAILED";
+    sessioninvalid: "SESSION_INVALID";
+}>;
+export declare function saddleerror(message: any, options?: {}): Error;
+export declare function validationerror(message: any, details?: {}): Error;
+export declare function artifactnotfound(key: any): Error;
+export declare function runnerunavailable(jobid: any): Error;
+export declare function aserror(error: any, jobid: any): any;
+/** Scrape error presets keep status, recovery and retry decisions explicit. */
+export declare const errorcatalog: Readonly<{
+    timeout: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    connectionrefused: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    dns: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    ratelimited: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    forbidden: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    notfound: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    parse: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    captcha: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    session: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+    config: {
+        code: string;
+        statuscode: number;
+        retryable: boolean;
+        recovery: string;
+    };
+}>;
+/** Creates a stable scrape error with recovery metadata. */
+export declare function webscrapeerror(kind: any, message: any, options?: {}): Error;
+/** Converts unknown failures into the stable scrape taxonomy. */
+export declare function classifyerror(error: any): any;
+//# sourceMappingURL=errors.d.ts.map

package/dist/core/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../core/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;EAOrB,CAAC;AAEH,wBAAgB,WAAW,CAAC,OAAO,KAAA,EAAE,OAAO,KAAK,SAOhD;AAED,wBAAgB,eAAe,CAAC,OAAO,KAAA,EAAE,OAAO,KAAK,SAEpD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,KAAA,SAEnC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,KAAA,SAEtC;AAED,wBAAgB,OAAO,CAAC,KAAK,KAAA,EAAE,KAAK,KAAA,OAGnC;AAED,+EAA+E;AAC/E,eAAO,MAAM,YAAY;;QACZ,IAAI;QAAW,UAAU;QAAO,SAAS;QAAQ,QAAQ;;;QAC/C,IAAI;QAAW,UAAU;QAAO,SAAS;QAAQ,QAAQ;;;QACvE,IAAI;QAAW,UAAU;QAAO,SAAS;QAAQ,QAAQ;;;QACjD,IAAI;QAAW,UAAU;QAAO,SAAS;QAAQ,QAAQ;;;QAC3D,IAAI;QAAW,UAAU;QAAO,SAAS;QAAS,QAAQ;;;QAC3D,IAAI;QAAW,UAAU;QAAO,SAAS;QAAS,QAAQ;;;QAC7D,IAAI;QAAW,UAAU;QAAO,SAAS;QAAS,QAAQ;;;QACxD,IAAI;QAAW,UAAU;QAAO,SAAS;QAAS,QAAQ;;;QAC1D,IAAI;QAAW,UAAU;QAAO,SAAS;QAAQ,QAAQ;;;QAC1D,IAAI;QAAW,UAAU;QAAO,SAAS;QAAS,QAAQ;;EACpE,CAAC;AAEH,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,IAAI,KAAA,EAAE,OAAO,KAAA,EAAE,OAAO,KAAK,SAAwf;AAEljB,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,KAAK,KAAA,OAAsW"}

package/dist/core/errors.js

@@ -0,0 +1,54 @@
+/**
+ * typed engine errors keep recovery decisions explicit.
+ */
+export const errorcodes = Object.freeze({
+    invalidinput: "INVALID_INPUT",
+    artifactnotfound: "ARTIFACT_NOT_FOUND",
+    storagefailure: "STORAGE_FAILURE",
+    runnerunavailable: "RUNNER_UNAVAILABLE",
+    jobfailed: "JOB_FAILED",
+    sessioninvalid: "SESSION_INVALID"
+});
+export function saddleerror(message, options = {}) {
+    const error = new Error(message, { cause: options.cause });
+    error.name = "saddleerror";
+    error.code = options.code ?? errorcodes.jobfailed;
+    error.retryable = options.retryable ?? false;
+    error.details = options.details ?? {};
+    return error;
+}
+export function validationerror(message, details = {}) {
+    return saddleerror(message, { code: errorcodes.invalidinput, details });
+}
+export function artifactnotfound(key) {
+    return saddleerror(`artifact not found: ${key}`, { code: errorcodes.artifactnotfound, details: { key } });
+}
+export function runnerunavailable(jobid) {
+    return saddleerror(`no runner is available for job ${jobid}`, { code: errorcodes.runnerunavailable, retryable: true, details: { jobid } });
+}
+export function aserror(error, jobid) {
+    if (error?.name === "saddleerror")
+        return error;
+    return saddleerror(`job ${jobid} failed`, { code: errorcodes.jobfailed, cause: error, details: { jobid } });
+}
+/** Scrape error presets keep status, recovery and retry decisions explicit. */
+export const errorcatalog = Object.freeze({
+    timeout: { code: "E1001", statuscode: 504, retryable: true, recovery: "WAIT_AND_RETRY" },
+    connectionrefused: { code: "E1002", statuscode: 503, retryable: true, recovery: "WAIT_AND_RETRY" },
+    dns: { code: "E1003", statuscode: 503, retryable: true, recovery: "ROTATE_PROXY" },
+    ratelimited: { code: "E2001", statuscode: 429, retryable: true, recovery: "WAIT_AND_RETRY" },
+    forbidden: { code: "E2002", statuscode: 403, retryable: false, recovery: "REVIEW_ROBOTS_TXT" },
+    notfound: { code: "E2003", statuscode: 404, retryable: false, recovery: "STOP_CRAWLING" },
+    parse: { code: "E4002", statuscode: 422, retryable: false, recovery: "STOP_CRAWLING" },
+    captcha: { code: "E4003", statuscode: 403, retryable: false, recovery: "REVIEW_ROBOTS_TXT" },
+    session: { code: "E5001", statuscode: 401, retryable: true, recovery: "ROTATE_USER_AGENT" },
+    config: { code: "E6001", statuscode: 400, retryable: false, recovery: "STOP_CRAWLING" }
+});
+/** Creates a stable scrape error with recovery metadata. */
+export function webscrapeerror(kind, message, options = {}) { const preset = errorcatalog[kind] ?? errorcatalog.config; const error = new Error(message, { cause: options.cause }); error.name = "webscrapeerror"; error.code = options.code ?? preset.code; error.statuscode = options.statuscode ?? preset.statuscode; error.retryable = options.retryable ?? preset.retryable; error.recovery = options.recovery ?? preset.recovery; error.severity = options.severity ?? (error.statuscode >= 500 ? "high" : "medium"); error.details = options.details ?? {}; return error; }
+/** Converts unknown failures into the stable scrape taxonomy. */
+export function classifyerror(error) { if (error?.name === "webscrapeerror")
+    return error; const message = String(error?.message ?? error); if (/timeout|aborted/i.test(message))
+    return webscrapeerror("timeout", message, { cause: error }); if (/dns|enotfound/i.test(message))
+    return webscrapeerror("dns", message, { cause: error }); return webscrapeerror("config", message, { cause: error }); }
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

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

package/dist/core/events.d.ts

@@ -0,0 +1,9 @@
+/**
+ * append only events are the small protocol shared by adapters.
+ */
+export declare const eventtypes: readonly string[];
+export declare function eventbus(): {
+    emit(event: any): void;
+    all(): any[];
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/core/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../core/events.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,UAAU,mBASrB,CAAC;AAEH,wBAAgB,QAAQ;;;EAMvB"}

package/dist/core/events.js

@@ -0,0 +1,21 @@
+/**
+ * append only events are the small protocol shared by adapters.
+ */
+export const eventtypes = Object.freeze([
+    "jobqueued",
+    "jobpreparing",
+    "runnerselected",
+    "jobrunning",
+    "jobsyncing",
+    "storagecommitted",
+    "jobcompleted",
+    "jobfailed"
+]);
+export function eventbus() {
+    const recorded = [];
+    return {
+        emit(event) { recorded.push(Object.freeze({ ...event })); },
+        all() { return [...recorded]; }
+    };
+}
+//# sourceMappingURL=events.js.map