@reticlehq/server 2.0.0

package/dist/init/snippets.js

@@ -0,0 +1,117 @@
+/**
+ * Generated file contents and copy-paste snippets for `reticle init`. Kept as named constants/builders
+ * so the runner never inlines free strings.
+ */
+import { RETICLE_DEFAULT_PORT, RETICLE_WS_PATH } from '@reticlehq/core';
+/**
+ * The connect() argument literal: a non-default port adds a `url`, and a projectId is always passed
+ * (so the app is identifiable across port changes). Empty string only when neither applies.
+ */
+function connectArg(port, projectId) {
+    const parts = [];
+    if (port !== undefined && port !== RETICLE_DEFAULT_PORT) {
+        parts.push(`url: 'ws://localhost:${String(port)}${RETICLE_WS_PATH}'`);
+    }
+    if (projectId !== undefined && projectId.length > 0)
+        parts.push(`projectId: '${projectId}'`);
+    return parts.length > 0 ? `{ ${parts.join(', ')} }` : '';
+}
+/** The Vite-config snippet printed when we can't safely auto-patch the config. */
+export function viteManual(port) {
+    const call = port === undefined ? 'reticle()' : `reticle({ port: ${String(port)} })`;
+    return `Add the Reticle plugin to your Vite config:
+
+  import { reticle } from '@reticlehq/vite-plugin';
+
+  export default defineConfig({
+    plugins: [react(), ${call}],
+  });
+
+The plugin only applies during \`vite\` (dev) — it is dropped from \`vite build\`.`;
+}
+/** Next.js config wrap — always printed (we never auto-rewrite next.config). */
+export function nextConfigManual(configFile) {
+    return `Wrap your ${configFile} export with withReticle (keeps SWC, dev-only):
+
+  import { withReticle } from '@reticlehq/next';
+
+  export default withReticle(nextConfig);`;
+}
+/** The dev-only client component that connects Reticle after hydration. */
+export function nextReticleDevFile(port, projectId) {
+    return `'use client';
+import { useEffect } from 'react';
+
+/** Dev-only: connect Reticle + install the React adapter, after hydration. */
+export function ReticleDev() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') return;
+    void import('@reticlehq/react').then(({ reticle, install }) => {
+      install();
+      reticle.connect(${connectArg(port, projectId)});
+    });
+  }, []);
+  return null;
+}
+`;
+}
+/** Mount instruction for the root layout. */
+export const NEXT_LAYOUT_MANUAL = `Mount <ReticleDev /> in your root layout (app/layout.tsx), dev-only:
+
+  import { ReticleDev } from './reticle-dev';
+  // inside <body>:
+  {process.env.NODE_ENV === 'development' ? <ReticleDev /> : null}`;
+/**
+ * Manual connect guidance for projects without a Vite/Next plugin. Most such projects still use a
+ * BUNDLER (CRA, webpack, Parcel, Vue/Svelte CLIs) — for those, the connect goes in the entry MODULE,
+ * where a bare `@reticlehq/react` import resolves. A bare import in a plain index.html does NOT resolve in
+ * the browser, so we never tell a bundled app to do that (the old advice silently failed for CRA).
+ */
+export function htmlManual(port, projectId) {
+    const arg = connectArg(port, projectId);
+    return `No Vite/Next plugin detected — wire the dev-only connect by hand. Pick the form for your setup:
+
+  • Bundled app (Create React App, webpack, Parcel, Vue/Svelte CLI, etc.) — add to your ENTRY module
+    (e.g. src/index.js or src/main.js), where '@reticlehq/react' resolves through your bundler:
+
+      if (location.hostname === 'localhost') {
+        const { reticle, install } = await import('@reticlehq/react');
+        install();
+        reticle.connect(${arg});
+      }
+
+  • Plain static HTML with no build step — the browser can't resolve the bare '@reticlehq/react' import, so
+    bundle the SDK once (e.g. \`npx esbuild\`) and point a dev-only <script type="module"> at the output,
+    or serve the page through a dev server (Vite) that resolves bare imports.`;
+}
+export const NEXT_RETICLE_DEV_PATH = 'app/reticle-dev.tsx';
+export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
+/**
+ * Dev-only client hook that connects Reticle in a SvelteKit app. SvelteKit renders through app.html and
+ * never triggers Vite's index.html injection (verified), so the standard plugin can't auto-connect —
+ * a client hook is the reliable path. SvelteKit runs src/hooks.client.ts on the client at startup.
+ */
+export function svelteKitHooksFile(port, projectId) {
+    return `// Dev-only: connect Reticle on the client. SvelteKit renders via app.html, so the Vite-plugin
+// index.html injection doesn't fire — connect from this client hook instead.
+if (import.meta.env.DEV) {
+  void import('@reticlehq/react').then(({ reticle, install }) => {
+    install();
+    reticle.connect(${connectArg(port, projectId)});
+  });
+}
+`;
+}
+/**
+ * Root-level project config for Reticle. Written by `reticle init`; read by `reticle mcp` for the port
+ * and by tooling for the stable projectId (the app's identity across port changes).
+ */
+export function reticleConfigContent(framework, port, projectId) {
+    const fields = { framework };
+    if (projectId !== undefined && projectId.length > 0)
+        fields['projectId'] = projectId;
+    if (port !== undefined && port !== RETICLE_DEFAULT_PORT)
+        fields['port'] = port;
+    return `${JSON.stringify(fields, null, 2)}\n`;
+}
+//# sourceMappingURL=snippets.js.map

package/dist/init/snippets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippets.js","sourceRoot":"","sources":["../../src/init/snippets.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAExE;;;GAGG;AACH,SAAS,UAAU,CAAC,IAAwB,EAAE,SAAkB;IAC9D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,oBAAoB,EAAE,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,wBAAwB,MAAM,CAAC,IAAI,CAAC,GAAG,eAAe,GAAG,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,KAAK,CAAC,IAAI,CAAC,eAAe,SAAS,GAAG,CAAC,CAAC;IAC7F,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3D,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,IAAwB;IACjD,MAAM,IAAI,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;IACrF,OAAO;;;;;yBAKgB,IAAI;;;mFAGsD,CAAC;AACpF,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,OAAO,aAAa,UAAU;;;;0CAIU,CAAC;AAC3C,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,kBAAkB,CAAC,IAAwB,EAAE,SAAkB;IAC7E,OAAO;;;;;;;;;wBASe,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC;;;;;CAKlD,CAAC;AACF,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;mEAIiC,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAwB,EAAE,SAAkB;IACrE,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO;;;;;;;;0BAQiB,GAAG;;;;;8EAKiD,CAAC;AAC/E,CAAC;AAED,MAAM,CAAC,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAwB,EAAE,SAAkB;IAC7E,OAAO;;;;;sBAKa,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC;;;CAGhD,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,IAAwB,EACxB,SAAkB;IAElB,MAAM,MAAM,GAA4B,EAAE,SAAS,EAAE,CAAC;IACtD,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC;IACrF,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,oBAAoB;QAAE,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IAC/E,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC"}

package/dist/init/vite-config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure, conservative patcher for a Vite config: add the `@reticlehq/vite-plugin` import and drop
+ * `reticle()` into the `plugins` array. Only handles the obvious, common shape — anything ambiguous
+ * bails to a `manual` result so we never half-edit a build config (a broken config is worse than a
+ * documented manual step).
+ */
+export declare const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
+export declare const VitePatchKind: {
+    readonly APPLY: "apply";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+};
+export type VitePatchKind = (typeof VitePatchKind)[keyof typeof VitePatchKind];
+type VitePatch = {
+    kind: typeof VitePatchKind.APPLY;
+    code: string;
+} | {
+    kind: typeof VitePatchKind.ALREADY;
+} | {
+    kind: typeof VitePatchKind.MANUAL;
+    reason: string;
+};
+export declare function patchViteConfig(source: string, port?: number): VitePatch;
+export {};
+//# sourceMappingURL=vite-config.d.ts.map

package/dist/init/vite-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-config.d.ts","sourceRoot":"","sources":["../../src/init/vite-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,WAAW,sDAAsD,CAAC;AAY/E,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAE/E,KAAK,SAAS,GACV;IAAE,IAAI,EAAE,OAAO,aAAa,CAAC,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,OAAO,aAAa,CAAC,OAAO,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,OAAO,aAAa,CAAC,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAmB1D,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAQxE"}

package/dist/init/vite-config.js

@@ -0,0 +1,45 @@
+/**
+ * Pure, conservative patcher for a Vite config: add the `@reticlehq/vite-plugin` import and drop
+ * `reticle()` into the `plugins` array. Only handles the obvious, common shape — anything ambiguous
+ * bails to a `manual` result so we never half-edit a build config (a broken config is worse than a
+ * documented manual step).
+ */
+export const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
+const RETICLE_MARKER = '@reticlehq/vite-plugin';
+/** The `reticle(...)` call — carries the bridge port so the injected connect() targets it. */
+function reticlePluginCall(port) {
+    return port === undefined ? 'reticle()' : `reticle({ port: ${String(port)} })`;
+}
+/** Matches the start of a `plugins: [` array literal. */
+const PLUGINS_ARRAY = /plugins\s*:\s*\[/;
+/** Matches an ES import statement (used to place our import after the last one). */
+const IMPORT_LINE = /^import\s.+from\s+['"][^'"]+['"];?\s*$/gm;
+export const VitePatchKind = {
+    APPLY: 'apply',
+    ALREADY: 'already',
+    MANUAL: 'manual',
+};
+const NO_PLUGINS_REASON = "couldn't find a `plugins: [...]` array to extend";
+function insertImport(source) {
+    const matches = [...source.matchAll(IMPORT_LINE)];
+    const last = matches[matches.length - 1];
+    if (last?.index === undefined) {
+        return `${VITE_IMPORT}\n${source}`;
+    }
+    const end = last.index + last[0].length;
+    return `${source.slice(0, end)}\n${VITE_IMPORT}${source.slice(end)}`;
+}
+function insertPlugin(source, port) {
+    // Insert right after the opening `[` of the plugins array.
+    return source.replace(PLUGINS_ARRAY, (match) => `${match}${reticlePluginCall(port)}, `);
+}
+export function patchViteConfig(source, port) {
+    if (source.includes(RETICLE_MARKER)) {
+        return { kind: VitePatchKind.ALREADY };
+    }
+    if (!PLUGINS_ARRAY.test(source)) {
+        return { kind: VitePatchKind.MANUAL, reason: NO_PLUGINS_REASON };
+    }
+    return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
+}
+//# sourceMappingURL=vite-config.js.map

package/dist/init/vite-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-config.js","sourceRoot":"","sources":["../../src/init/vite-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,mDAAmD,CAAC;AAC/E,MAAM,cAAc,GAAG,wBAAwB,CAAC;AAEhD,8FAA8F;AAC9F,SAAS,iBAAiB,CAAC,IAAwB;IACjD,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;AACjF,CAAC;AACD,yDAAyD;AACzD,MAAM,aAAa,GAAG,kBAAkB,CAAC;AACzC,oFAAoF;AACpF,MAAM,WAAW,GAAG,0CAA0C,CAAC;AAE/D,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,KAAK,EAAE,OAAO;IACd,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;CACR,CAAC;AAQX,MAAM,iBAAiB,GAAG,kDAAkD,CAAC;AAE7E,SAAS,YAAY,CAAC,MAAc;IAClC,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,IAAI,IAAI,EAAE,KAAK,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,GAAG,WAAW,KAAK,MAAM,EAAE,CAAC;IACrC,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;AACvE,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,IAAwB;IAC5D,2DAA2D;IAC3D,OAAO,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,IAAa;IAC3D,IAAI,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,OAAO,EAAE,CAAC;IACzC,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;AACvF,CAAC"}

package/dist/input/network-mock-tools.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDef } from '../tools/tools.js';
+export declare const NETWORK_MOCK_TOOLS: ToolDef[];
+//# sourceMappingURL=network-mock-tools.d.ts.map

package/dist/input/network-mock-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-mock-tools.d.ts","sourceRoot":"","sources":["../../src/input/network-mock-tools.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAY,MAAM,mBAAmB,CAAC;AAyD3D,eAAO,MAAM,kBAAkB,EAAE,OAAO,EAsCvC,CAAC"}

package/dist/input/network-mock-tools.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason } from '@reticlehq/core';
+import { ReticleTool } from '../tools/tool-names.js';
+import { asString } from '../tools/tools-helpers.js';
+const sessionIdShape = {
+    sessionId: z
+        .string()
+        .optional()
+        .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+};
+function mockProvider(deps) {
+    const p = deps.realInput;
+    return p !== undefined && typeof p.setMocks === 'function' ? p : undefined;
+}
+const ruleShape = z.object({
+    urlContains: z
+        .string()
+        .min(1)
+        .describe('Substring the request URL must contain, e.g. "/api/pay".'),
+    method: z.string().optional().describe('Optional method filter (GET/POST/…), case-insensitive.'),
+    status: z.number().int().optional().describe('Fulfill with this HTTP status (default 200).'),
+    body: z.string().optional().describe('Response body to fulfill with.'),
+    contentType: z.string().optional().describe('Response content type (default application/json).'),
+    delayMs: z
+        .number()
+        .int()
+        .optional()
+        .describe('Delay (ms) before fulfilling — simulate a slow API.'),
+    abort: z
+        .boolean()
+        .optional()
+        .describe('Simulate a network failure (offline) instead of a response.'),
+});
+/** Narrow the validated tool args into MockRule[], omitting undefined keys (exactOptionalPropertyTypes). */
+function toRules(value) {
+    const parsed = z.array(ruleShape).safeParse(value);
+    if (!parsed.success)
+        return [];
+    return parsed.data.map((r) => {
+        const rule = { urlContains: r.urlContains };
+        if (r.method !== undefined)
+            rule.method = r.method;
+        if (r.status !== undefined)
+            rule.status = r.status;
+        if (r.body !== undefined)
+            rule.body = r.body;
+        if (r.contentType !== undefined)
+            rule.contentType = r.contentType;
+        if (r.delayMs !== undefined)
+            rule.delayMs = r.delayMs;
+        if (r.abort !== undefined)
+            rule.abort = r.abort;
+        return rule;
+    });
+}
+export const NETWORK_MOCK_TOOLS = [
+    {
+        name: ReticleTool.NETWORK_MOCK,
+        description: 'Stub or intercept network requests on the DRIVEN page (needs `reticle drive`): return a 500, ' +
+            'force offline (abort), or delay a response — so you can deterministically test error and edge ' +
+            'states without touching the backend ("verify the app handles a failed payment"). Pass `mocks` ' +
+            '(first matching rule wins); pass an empty array or `clear: true` to turn mocking off.',
+        inputSchema: {
+            mocks: z.array(ruleShape).optional().describe('Interception rules; omit/empty to clear.'),
+            clear: z.boolean().optional().describe('Clear all active mocks (same as mocks: []).'),
+            ...sessionIdShape,
+        },
+        outputSchema: {
+            applied: z.boolean(),
+            count: z.number(),
+            ok: z.boolean().optional(),
+            reason: z.string().optional(),
+            recommendation: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            const provider = mockProvider(deps);
+            if (provider === undefined) {
+                // Mocking needs a browser Reticle drives; a synthetic in-page session can't intercept the network.
+                return {
+                    applied: false,
+                    count: 0,
+                    ok: false,
+                    reason: VisualReason.NO_PROVIDER,
+                    recommendation: VISUAL_NO_PROVIDER_RECOMMENDATION,
+                };
+            }
+            const session = deps.sessions.resolve(asString(args['sessionId']));
+            const rules = args['clear'] === true ? [] : toRules(args['mocks']);
+            const applied = await provider.setMocks(session.url, rules);
+            return { applied, count: applied ? rules.length : 0 };
+        },
+    },
+];
+//# sourceMappingURL=network-mock-tools.js.map

package/dist/input/network-mock-tools.js.map

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

package/dist/input/network-mock.d.ts

@@ -0,0 +1,55 @@
+import type { Page, Route } from 'playwright';
+/**
+ * CDP network mock/intercept for `reticle drive`. Lets an agent or dev deterministically test error and
+ * edge states — a 500 on checkout, an offline payment, a slow API — without touching the backend.
+ * "Verify the app handles a failed payment" becomes one declared rule.
+ *
+ * Two layers, split for testability:
+ *   - matchMock(): PURE. Given the active rules and a request's url/method, decide the outcome
+ *     (fulfill | abort | continue). Unit-tested directly.
+ *   - installNetworkMocks(): the Playwright wiring. Registers a single catch-all page.route handler
+ *     that consults matchMock and fulfills/aborts/continues. Driven in tests with a fake Page + Route.
+ */
+/** One interception rule. First matching rule (in order) wins for a request. */
+export interface MockRule {
+    /** Substring the request URL must contain to match (e.g. "/api/pay"). */
+    urlContains: string;
+    /** Optional method filter (GET/POST/…); case-insensitive. Omit to match any method. */
+    method?: string;
+    /** Fulfill the request with this HTTP status (default 200). Ignored when `abort` is set. */
+    status?: number;
+    /** Response body to fulfill with. */
+    body?: string;
+    /** Response content type (default application/json). */
+    contentType?: string;
+    /** Delay (ms) before fulfilling — simulate a slow endpoint. */
+    delayMs?: number;
+    /** Simulate a network failure (offline / connection refused) instead of a response. */
+    abort?: boolean;
+}
+/** What to do with a request after matching: fulfill a canned response, abort it, or let it through. */
+interface MockOutcome {
+    kind: 'fulfill' | 'abort' | 'continue';
+    status?: number;
+    body?: string;
+    contentType?: string;
+    delayMs?: number;
+}
+/**
+ * Decide the outcome for a request from the active rules. Pure: no IO, no clock. The first rule
+ * whose url-substring (and optional method) matches wins; no match → continue (let it hit the network).
+ */
+export declare function matchMock(rules: MockRule[], req: {
+    url: string;
+    method: string;
+}): MockOutcome;
+/** Apply a matched outcome to a Playwright Route. Exported so the route handler is testable in isolation. */
+export declare function applyOutcome(route: Route, outcome: MockOutcome, sleep: (ms: number) => Promise<void>): Promise<void>;
+/**
+ * Install (or replace) the network-mock handler on a driven page. Clears any prior Reticle route first,
+ * so calling with a new rule set is idempotent and calling with [] turns mocking off. The handler
+ * consults matchMock per request and fulfills/aborts/continues accordingly.
+ */
+export declare function installNetworkMocks(page: Page, rules: MockRule[], sleep?: (ms: number) => Promise<void>): Promise<void>;
+export {};
+//# sourceMappingURL=network-mock.d.ts.map

package/dist/input/network-mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-mock.d.ts","sourceRoot":"","sources":["../../src/input/network-mock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wGAAwG;AACxG,UAAU,WAAW;IACnB,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAgB9F;AAED,6GAA6G;AAC7G,wBAAsB,YAAY,CAChC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACnC,OAAO,CAAC,IAAI,CAAC,CAef;AAID;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,QAAQ,EAAE,EACjB,KAAK,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAa,GAC/C,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/input/network-mock.js

@@ -0,0 +1,62 @@
+const DEFAULT_STATUS = 200;
+const DEFAULT_CONTENT_TYPE = 'application/json';
+/**
+ * Decide the outcome for a request from the active rules. Pure: no IO, no clock. The first rule
+ * whose url-substring (and optional method) matches wins; no match → continue (let it hit the network).
+ */
+export function matchMock(rules, req) {
+    for (const rule of rules) {
+        if (!req.url.includes(rule.urlContains))
+            continue;
+        if (rule.method !== undefined && rule.method.toUpperCase() !== req.method.toUpperCase())
+            continue;
+        if (rule.abort === true)
+            return { kind: 'abort' };
+        const outcome = {
+            kind: 'fulfill',
+            status: rule.status ?? DEFAULT_STATUS,
+            contentType: rule.contentType ?? DEFAULT_CONTENT_TYPE,
+        };
+        if (rule.body !== undefined)
+            outcome.body = rule.body;
+        if (rule.delayMs !== undefined)
+            outcome.delayMs = rule.delayMs;
+        return outcome;
+    }
+    return { kind: 'continue' };
+}
+/** Apply a matched outcome to a Playwright Route. Exported so the route handler is testable in isolation. */
+export async function applyOutcome(route, outcome, sleep) {
+    if (outcome.kind === 'continue') {
+        await route.continue();
+        return;
+    }
+    if (outcome.kind === 'abort') {
+        await route.abort('failed');
+        return;
+    }
+    if (outcome.delayMs !== undefined && outcome.delayMs > 0)
+        await sleep(outcome.delayMs);
+    await route.fulfill({
+        status: outcome.status ?? DEFAULT_STATUS,
+        contentType: outcome.contentType ?? DEFAULT_CONTENT_TYPE,
+        body: outcome.body ?? '',
+    });
+}
+const realSleep = (ms) => new Promise((res) => setTimeout(res, ms));
+/**
+ * Install (or replace) the network-mock handler on a driven page. Clears any prior Reticle route first,
+ * so calling with a new rule set is idempotent and calling with [] turns mocking off. The handler
+ * consults matchMock per request and fulfills/aborts/continues accordingly.
+ */
+export async function installNetworkMocks(page, rules, sleep = realSleep) {
+    await page.unroute('**/*').catch(() => undefined);
+    if (rules.length === 0)
+        return;
+    await page.route('**/*', (route) => {
+        const req = route.request();
+        const outcome = matchMock(rules, { url: req.url(), method: req.method() });
+        void applyOutcome(route, outcome, sleep);
+    });
+}
+//# sourceMappingURL=network-mock.js.map

package/dist/input/network-mock.js.map

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

package/dist/input/real-input.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Optional CDP/Playwright real-input mode.
+ *
+ * Synthetic `dispatchEvent` cannot drive native hover/pointer state (an onMouseEnter never
+ * fires, hit-testing never runs). When a CDP endpoint is configured, this module connects a
+ * Playwright `Browser` over CDP and drives REAL pointer/keyboard input against the element box
+ * the SDK resolves (viewport CSS px from getBoundingClientRect).
+ *
+ * Node-only. Playwright is loaded via DYNAMIC `import('playwright')` so non-CDP users never
+ * pay for it; the type-only import is elided by `tsc`, so the build stays green without it.
+ */
+import type { Browser, Page } from 'playwright';
+import { DriveErrorCode } from '@reticlehq/core';
+import { type MockRule } from './network-mock.js';
+/** Viewport CSS-px box as returned by the INSPECT command (getBoundingClientRect). */
+export interface ElementBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Args forwarded from reticle_act (fill value, type text, drag drop-target box). */
+export interface RealInputArgs {
+    value?: string;
+    text?: string;
+    /** For drag: the resolved box of the drop-target ref (toRef). */
+    toBox?: ElementBox;
+    steps?: number;
+}
+interface RealInputResult {
+    /** True if a native gesture was actually driven. */
+    performed: boolean;
+    /** Center used, for diagnostics/tests. */
+    center: {
+        cx: number;
+        cy: number;
+    };
+}
+/** Options for a page screenshot — full-page scroll capture and/or a clip box. */
+export interface ScreenshotOpts {
+    fullPage?: boolean;
+    /** Restrict the capture to one element/region (viewport CSS px). */
+    clip?: ElementBox;
+}
+/** The capability surface reticle_act depends on. A FAKE implementing this is injected in tests. */
+export interface RealInputProvider {
+    /** Whether a Playwright Page currently matches this SDK session URL. */
+    isAvailableFor(sessionUrl: string): Promise<boolean>;
+    /** Drive a native gesture for `action` at the element `box`. */
+    perform(sessionUrl: string, action: string, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
+    /**
+     * Capture a PNG of the correlated page, or undefined if no page matches. Optional
+     * so the visual layer stays opt-in — a provider that cannot screenshot simply omits it.
+     */
+    screenshot?(sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
+    /**
+     * Install (or replace, or with [] clear) network-mock rules on the correlated page — stub a 500,
+     * force offline, delay a response — for deterministic error/edge-state testing. Returns true when
+     * a page matched and the rules were applied, false when no driven page matches this session.
+     * Optional: a provider with no owned browser simply omits it.
+     */
+    setMocks?(sessionUrl: string, rules: MockRule[]): Promise<boolean>;
+    /**
+     * Pin the correlated page's viewport to fixed pixel dimensions so a screenshot baseline is
+     * reproducible across machines (the missing piece of CI-stable visual regression, alongside masks
+     * and the frozen clock). Returns true when a page matched, false otherwise. Optional.
+     */
+    setViewport?(sessionUrl: string, size: {
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+}
+/**
+ * Optional lifecycle a provider that OWNS a browser implements (`reticle drive`). The
+ * reticle_act routing still depends only on `RealInputProvider`; the server uses these to boot/tear-down.
+ */
+export interface OwnedRealInputProvider extends RealInputProvider {
+    /** Launch + navigate the owned browser. Must reject (never hang) on failure. */
+    navigate(): Promise<void>;
+    /** Close the owned browser. Idempotent. */
+    dispose(): Promise<void>;
+}
+/** Structured, code-tagged failure so callers branch on cause, not message text. */
+export declare class DriveError extends Error {
+    readonly code: DriveErrorCode;
+    constructor(code: DriveErrorCode, message: string);
+}
+/** Center of a viewport box in CSS px. Pure — unit-tested directly. */
+export declare function boxCenter(box: ElementBox): {
+    cx: number;
+    cy: number;
+};
+/**
+ * Which actions are driven by native pointer input. fill/type stay synthetic unless a
+ * provider explicitly runs them.
+ */
+export declare function isPointerAction(action: string): boolean;
+type SleepFn = (ms: number) => Promise<void>;
+type ConnectFn = (url: string) => Promise<Browser>;
+/**
+ * Shared gesture executor: drive a native gesture on an already-resolved Page. Used by both the
+ * CDP-attached and the launched (drive) providers so the pointer logic lives in one place.
+ */
+export declare function performGesture(page: Page, action: string, box: ElementBox, args: RealInputArgs, sleep: SleepFn): Promise<RealInputResult>;
+/**
+ * Capture a PNG from a Playwright page. Shared by the CDP + launched providers so the
+ * screenshot path lives in one place (mirrors performGesture). Returns the raw PNG bytes.
+ */
+export declare function capturePage(page: Page, opts: ScreenshotOpts): Promise<Uint8Array>;
+interface CdpProviderOptions {
+    cdpUrl: string;
+    /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
+    sleep?: SleepFn;
+    /** Injected connector so unit tests can stub Playwright without import(). */
+    connect?: ConnectFn;
+}
+/** CDP-backed real-input provider. Lazily connects on first availability check / perform. */
+export declare class CdpRealInputProvider implements RealInputProvider {
+    #private;
+    constructor(options: CdpProviderOptions);
+    isAvailableFor(sessionUrl: string): Promise<boolean>;
+    perform(sessionUrl: string, action: string, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
+    /** PNG of the correlated page, or undefined if none matches. */
+    screenshot(sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
+    /** Apply network-mock rules to the correlated page; false when no driven page matches. */
+    setMocks(sessionUrl: string, rules: MockRule[]): Promise<boolean>;
+    /** Pin the correlated page's viewport to fixed dimensions; false when no driven page matches. */
+    setViewport(sessionUrl: string, size: {
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+    /** Best-effort cleanup; idempotent. */
+    dispose(): Promise<void>;
+}
+/** Injected launcher so unit tests stub Playwright without import(). */
+export type LaunchFn = (headless: boolean) => Promise<Browser>;
+/**
+ * Force a driven page's already-loaded SDK to connect to our loopback bridge with a pairing token,
+ * overriding the app's own (often localhost-only) reticle.connect() — so a hosted preview verifies with
+ * no app redeploy. connect() is a no-op once connected, so re-invoking it is safe.
+ */
+export interface InjectConnectOptions {
+    token: string;
+    url: string;
+}
+export interface LaunchedProviderOptions {
+    driveUrl: string;
+    headless: boolean;
+    /** Injected so the settle delay is deterministic in tests; defaults to a real Node timer. */
+    sleep?: SleepFn;
+    /** Injected launcher so unit tests can stub Playwright; defaults to dynamic import('playwright'). */
+    launch?: LaunchFn;
+    /** When set, re-invoke the page's reticle.connect() with these after load (drive-a-hosted-preview). */
+    injectConnect?: InjectConnectOptions;
+    /** Path to a Playwright storageState JSON (cookies/localStorage) — starts the page authenticated. */
+    storageState?: string;
+}
+/**
+ * Launches and OWNS a Playwright Chromium, navigates it to `driveUrl`, then drives native
+ * input on that page. Headless-capable so @reticlehq/test / CI can run hover/drag unattended.
+ */
+export declare class LaunchedRealInputProvider implements OwnedRealInputProvider {
+    #private;
+    constructor(options: LaunchedProviderOptions);
+    navigate(): Promise<void>;
+    isAvailableFor(sessionUrl: string): Promise<boolean>;
+    perform(_sessionUrl: string, action: string, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
+    /** PNG of the owned page, or undefined before navigate / after dispose. */
+    screenshot(_sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
+    /** Close the owned browser once. Idempotent and safe before navigate. */
+    dispose(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=real-input.d.ts.map

package/dist/input/real-input.d.ts.map

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