@reticlehq/server 2.3.0 → 2.5.0

package/dist/init/snippets.d.ts

@@ -6,8 +6,39 @@
 export declare function viteManual(port: number | undefined): string;
 /** Next.js config wrap — always printed (we never auto-rewrite next.config). */
 export declare function nextConfigManual(configFile: string): string;
-/** The dev-only client component that connects Reticle after hydration. */
-export declare function nextReticleDevFile(port: number | undefined, projectId?: string): string;
+/**
+ * The dev-only client component that connects Reticle after hydration.
+ *
+ * The token is not optional. The bridge requires a pairing token even on localhost, and unlike Vite
+ * (where the plugin injects it) a Next app has to carry it through `withReticle`, which publishes it
+ * as `NEXT_PUBLIC_RETICLE_TOKEN`. This file used to connect with only a projectId, so every Next
+ * setup ended at `bridge refused the connection: authentication failed` and no session ever appeared.
+ */
+export declare function nextReticleDevFile(port: number | undefined, projectId?: string, testids?: readonly string[], stores?: readonly string[]): string;
+export declare function astroManual(port: number | undefined, projectId?: string, 
+/**
+ * A layout file that actually exists, when one does.
+ *
+ * Reported from the field: on `examples/framework-react` — which has no layout at all, only
+ * `src/pages/index.astro` — init printed thirty lines telling the user to paste into "your
+ * layout". Instructions that name a file the project does not have read as a mistake by the
+ * reader, and cost them the time it takes to go and confirm it is missing.
+ */
+layoutPath?: string): string;
+/**
+ * The app-side dev module the Vite plugin imports by convention.
+ *
+ * `registerCapabilities` tells the agent what it can drive without guessing; `registerStore` is the
+ * one that matters most and the one we cannot write for you — detecting that an app depends on
+ * zustand is easy, knowing which module exports the store instance is not, and a wrong import here
+ * breaks the module everything else hangs off. So the store lines are generated COMMENTED, naming
+ * the libraries actually found in package.json, with the exact call to uncomment.
+ */
+export declare function viteDevModuleFile(testids: readonly string[], stores: readonly string[]): string;
+/** Where that module goes. Matches @reticlehq/vite-plugin's convention list. */
+export declare const VITE_DEV_MODULE_PATH = "src/reticle-dev.ts";
+/** Default root-layout path, used when no layout was found on disk (reporting only). */
+export declare const NEXT_LAYOUT_PATH = "app/layout.tsx";
 /** Mount instruction for the root layout. */
 export declare const NEXT_LAYOUT_MANUAL = "Mount <ReticleDev /> in your root layout (app/layout.tsx), dev-only:\n\n  import { ReticleDev } from './reticle-dev';\n  // inside <body>:\n  {process.env.NODE_ENV === 'development' ? <ReticleDev /> : null}";
 /**
@@ -23,7 +54,14 @@ export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
  * Said to the user's face rather than discovered later. React, Next, Remix and Astro each have an
  * app and a CI gate; SvelteKit has neither, so "it generated some wiring" is not evidence it works.
  */
-export declare const UNVERIFIED_FRAMEWORK_NOTE = "Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested \u2014 it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix, Astro, and plain HTML. If the hook does not register a session, please open an issue.";
+/**
+ * Said out loud when the app does not render through React. The SDK is framework-agnostic — DOM,
+ * network, console and routing all still work — but `@reticlehq/react` is a React adapter, so
+ * component names and source mapping do not, and no CI gate covers this stack. Reporting all-green
+ * here is the one thing this project exists not to do.
+ */
+export declare function unverifiedUiLibraryNote(library: string): string;
+export declare const UNVERIFIED_FRAMEWORK_NOTE = "Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested \u2014 it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix and Astro. If the hook does not register a session, please open an issue.";
 /**
  * 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 —

package/dist/init/snippets.js

@@ -37,8 +37,21 @@ export function nextConfigManual(configFile) {
 
   export default withReticle(nextConfig);`;
 }
-/** The dev-only client component that connects Reticle after hydration. */
-export function nextReticleDevFile(port, projectId) {
+/**
+ * The dev-only client component that connects Reticle after hydration.
+ *
+ * The token is not optional. The bridge requires a pairing token even on localhost, and unlike Vite
+ * (where the plugin injects it) a Next app has to carry it through `withReticle`, which publishes it
+ * as `NEXT_PUBLIC_RETICLE_TOKEN`. This file used to connect with only a projectId, so every Next
+ * setup ended at `bridge refused the connection: authentication failed` and no session ever appeared.
+ */
+export function nextReticleDevFile(port, projectId, testids = [], stores = []) {
+    const base = connectArg(port, projectId);
+    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
+    const ids = testids.map((t) => `'${t}'`).join(', ');
+    const storeBlock = 0 === stores.length
+        ? '      // No state library detected. If you add one, register it here — see docs/usage.md.'
+        : stores.map((h) => `      // import your store, then: ${h}`).join('\n');
     return `'use client';
 import { useEffect } from 'react';
 
@@ -46,15 +59,151 @@ import { useEffect } from 'react';
 export function ReticleDev() {
   useEffect(() => {
     if (process.env.NODE_ENV !== 'development') return;
-    void import('@reticlehq/react').then(({ reticle, install }) => {
+    void import('@reticlehq/react').then(({ reticle, install, registerCapabilities }) => {
       install();
-      reticle.connect(${connectArg(port, projectId)});
+      // Both provided by withReticle() in next.config. The bridge rejects a connect with no token;
+      // the root makes source paths repo-relative instead of absolute.
+      const token = process.env.NEXT_PUBLIC_RETICLE_TOKEN;
+      const root = process.env.NEXT_PUBLIC_RETICLE_ROOT;
+      reticle.connect({ ${fields}...(token ? { token } : {}), ...(root ? { root } : {}) });
+
+      // ── Start with ONE flow. ──────────────────────────────────────────────────────────────────
+      // Registering a store is the highest-value line here: it lets the agent check what the app
+      // BELIEVES, not just what it rendered. Pass the STORE, not \`() => store.getState()\` — the store
+      // form wires \`subscribe\` too, so every mutation emits a diff; the getter form is read-only.
+${storeBlock}
+      registerCapabilities({
+        testids: [${ids}],${0 === testids.length ? ' // none found — add data-testid to your key elements' : ''}
+        signals: [], // names you pass to reticle.signal()
+        stores: [], // the keys you registered above
+      });
     });
   }, []);
   return null;
 }
 `;
 }
+/**
+ * Astro connect instructions.
+ *
+ * Astro is Vite-based but SSRs its own HTML, so the plugin's index.html injection never fires, and
+ * `vite` is not a direct dependency — so this used to fall through to the generic HTML advice, which
+ * tells you to add a connect to an "entry module" Astro does not have, or to bundle the SDK with
+ * esbuild. Both are wrong for Astro, and following either gets you nothing.
+ *
+ * Astro bundles a page `<script>`, so the bare import resolves there. The token has to be inlined by
+ * the config because there is no plugin in the page's path to inject it, and `build.target` has to be
+ * raised or Astro down-levels the modern SDK bundle and dies on a destructuring transform.
+ */
+/**
+ * Name the file the connect <script> should go in — the layout when one exists, otherwise the page,
+ * because a project with no layout has nowhere else to put it and should not be told otherwise.
+ */
+function layoutHost(layoutPath) {
+    return layoutPath === undefined
+        ? '2. This project has no layout, so put it in the page you want instrumented (e.g.\n   src/pages/index.astro) — every page you want a session from needs it — inside <body>:'
+        : `2. In ${layoutPath} (or any other page you want instrumented), inside <body>:`;
+}
+export function astroManual(port, projectId, 
+/**
+ * A layout file that actually exists, when one does.
+ *
+ * Reported from the field: on `examples/framework-react` — which has no layout at all, only
+ * `src/pages/index.astro` — init printed thirty lines telling the user to paste into "your
+ * layout". Instructions that name a file the project does not have read as a mistake by the
+ * reader, and cost them the time it takes to go and confirm it is missing.
+ */
+layoutPath) {
+    const extra = port !== undefined && port !== RETICLE_DEFAULT_PORT
+        ? `\n          url: '${bridgeWsUrl(port)}',`
+        : '';
+    const id = projectId !== undefined && projectId.length > 0 ? `\n          projectId: '${projectId}',` : '';
+    return `Astro renders its own HTML, so the connect goes in a page <script> and the pairing token is inlined by the config.
+
+1. In astro.config.mjs — inline the daemon's token and raise the build target:
+
+  import { readFileSync } from 'node:fs';
+  import { homedir } from 'node:os';
+  import { join } from 'node:path';
+
+  function reticleToken() {
+    const dir = process.env['RETICLE_PAIRING_TOKEN_DIR'] || join(homedir(), '.reticle');
+    try { return readFileSync(join(dir, 'pairing-token'), 'utf8').trim(); } catch { return ''; }
+  }
+
+  export default defineConfig({
+    vite: {
+      // Astro's default target down-levels the modern SDK bundle and fails on a destructuring transform.
+      build: { target: 'es2022' },
+      optimizeDeps: { esbuildOptions: { target: 'es2022' } },
+      define: {
+        __RETICLE_TOKEN__: JSON.stringify(reticleToken()),
+        // Without this, source pointers come back as absolute paths from YOUR machine — useless in a
+        // report. Every other framework gets it from its build plugin; Astro owns its Vite instance.
+        __RETICLE_ROOT__: JSON.stringify(process.cwd()),
+      },
+    },
+  });
+
+${layoutHost(layoutPath)}
+
+  <script>
+    if (import.meta.env.DEV) {
+      const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+      const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+      const { reticle, install } = await import('@reticlehq/react');
+      install();
+      reticle.connect({${id}${extra}
+          ...(token.length > 0 ? { token } : {}),
+          ...(root.length > 0 ? { root } : {}),
+      });
+    }
+  </script>
+
+Start the daemon BEFORE \`astro dev\`, so the token file exists when the config is read. Until it does the token is empty and the page reloads once the daemon is up.`;
+}
+/**
+ * The app-side dev module the Vite plugin imports by convention.
+ *
+ * `registerCapabilities` tells the agent what it can drive without guessing; `registerStore` is the
+ * one that matters most and the one we cannot write for you — detecting that an app depends on
+ * zustand is easy, knowing which module exports the store instance is not, and a wrong import here
+ * breaks the module everything else hangs off. So the store lines are generated COMMENTED, naming
+ * the libraries actually found in package.json, with the exact call to uncomment.
+ */
+export function viteDevModuleFile(testids, stores) {
+    const ids = testids.map((t) => `'${t}'`).join(', ');
+    const storeBlock = 0 === stores.length
+        ? '  // No state library detected. If you add one, register it here — see docs/usage.md.'
+        : stores.map((h) => `  // import your store, then: ${h}`).join('\n');
+    return `// Dev-only. Imported automatically by @reticlehq/vite-plugin — you do not need to import it.
+// Self-guards on import.meta.env.DEV, so it is a no-op in a production build.
+import { registerCapabilities } from '@reticlehq/react';
+
+if (import.meta.env.DEV) {
+  // ── Start with ONE flow. ─────────────────────────────────────────────────────────────────────
+  // You do not need to describe the whole app to get value, and trying to is the slow path. Register
+  // the store your most important flow reads, and list the testids that flow touches. Add more later,
+  // when a flow you actually replay needs them.
+  //
+  // Registering a store is the highest-value line in this file: it lets the agent check what the app
+  // BELIEVES, not just what it rendered — the class of bug a screenshot cannot see. Pass the STORE,
+  // not \`() => store.getState()\`: the store form wires \`subscribe\` too, so every mutation emits a
+  // state diff; the getter form is read-only and silently produces empty diffs.
+${storeBlock}
+
+  registerCapabilities({
+    testids: [${ids}],${0 === testids.length ? ' // none found — add data-testid to your key elements' : ''}
+    signals: [], // names you pass to reticle.signal()
+    stores: [], // the keys you registered above
+  });
+}
+`;
+}
+/** Where that module goes. Matches @reticlehq/vite-plugin's convention list. */
+export const VITE_DEV_MODULE_PATH = 'src/reticle-dev.ts';
+/** Default root-layout path, used when no layout was found on disk (reporting only). */
+export const NEXT_LAYOUT_PATH = 'app/layout.tsx';
 /** Mount instruction for the root layout. */
 export const NEXT_LAYOUT_MANUAL = `Mount <ReticleDev /> in your root layout (app/layout.tsx), dev-only:
 
@@ -74,10 +223,11 @@ export function htmlManual(port, projectId) {
   • 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});
+      if (window.location.hostname === 'localhost') {
+        void import('@reticlehq/react').then(({ reticle, install }) => {
+          install();
+          reticle.connect(${arg});
+        });
       }
 
   • Plain static HTML with no build step — the browser can't resolve the bare '@reticlehq/react' import, so
@@ -90,21 +240,46 @@ export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
  * Said to the user's face rather than discovered later. React, Next, Remix and Astro each have an
  * app and a CI gate; SvelteKit has neither, so "it generated some wiring" is not evidence it works.
  */
-export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested — it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix, Astro, and plain HTML. If the hook does not register a session, please open an issue.';
+/**
+ * Said out loud when the app does not render through React. The SDK is framework-agnostic — DOM,
+ * network, console and routing all still work — but `@reticlehq/react` is a React adapter, so
+ * component names and source mapping do not, and no CI gate covers this stack. Reporting all-green
+ * here is the one thing this project exists not to do.
+ */
+export function unverifiedUiLibraryNote(library) {
+    return `Detected a ${library} app. Reticle's DOM, network, console and state tools work here, and source file:line does too — the build plugin stamps data-reticle-source regardless of UI library (measured on preact and svelte). What @reticlehq/react adds and you will NOT get is React component identity: component names and component stacks. No CI gate covers ${library}. Gated today: Vite + React, Next.js, Remix, Astro. If something doesn't work, please open an issue.`;
+}
+export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested — it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix and Astro. If the hook does not register a session, please open an issue.';
 /**
  * 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) {
+    const base = connectArg(port, projectId);
+    const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
     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)});
+    // The bridge requires the pairing token even on localhost. Nothing in a browser can read the
+    // file it lives in, so @reticlehq/vite-plugin inlines it here at build time. Without it the
+    // console reads "bridge refused the connection: authentication failed" and no session appears.
+    const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+    const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+    const sdkVersion = typeof __RETICLE_SDK_VERSION__ !== 'undefined' ? __RETICLE_SDK_VERSION__ : '';
+    reticle.connect({
+      ${fields}...(token.length > 0 ? { token } : {}),
+      ...(root.length > 0 ? { root } : {}),
+      ...(sdkVersion.length > 0 ? { sdkVersion } : {}),
+    });
   });
 }
+
+declare const __RETICLE_TOKEN__: string | undefined;
+declare const __RETICLE_ROOT__: string | undefined;
+declare const __RETICLE_SDK_VERSION__: string | undefined;
 `;
 }
 /**

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

@@ -4,21 +4,15 @@
  * bails to a `manual` result so we never half-edit a build config (a broken config is worse than a
  * documented manual step).
  */
+import { PatchKind, type SourcePatch } from './patch-kind.js';
 export declare const VITE_IMPORT = "import { reticle } from '@reticlehq/vite-plugin';";
+/** Alias kept so existing call sites read in Vite terms; the vocabulary is shared (see patch-kind). */
 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 type VitePatchKind = PatchKind;
+type VitePatch = SourcePatch;
 export declare function patchViteConfig(source: string, port?: number): VitePatch;
 export {};

package/dist/init/vite-config.js

@@ -4,6 +4,7 @@
  * bails to a `manual` result so we never half-edit a build config (a broken config is worse than a
  * documented manual step).
  */
+import { PatchKind } from './patch-kind.js';
 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. */
@@ -14,11 +15,8 @@ function reticlePluginCall(port) {
 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',
-};
+/** Alias kept so existing call sites read in Vite terms; the vocabulary is shared (see patch-kind). */
+export const VitePatchKind = PatchKind;
 const NO_PLUGINS_REASON = "couldn't find a `plugins: [...]` array to extend";
 function insertImport(source) {
     const matches = [...source.matchAll(IMPORT_LINE)];
@@ -29,9 +27,19 @@ function insertImport(source) {
     const end = last.index + last[0].length;
     return `${source.slice(0, end)}\n${VITE_IMPORT}${source.slice(end)}`;
 }
+/**
+ * Insert right after the opening `[` of the plugins array, spaced the way the surrounding line is.
+ *
+ * A multi-line array puts a newline next, and `[reticle(), \n` leaves trailing whitespace — exactly
+ * what a formatter rewrites, turning a one-line install into a diff against the user's own style. A
+ * single-line array needs the space, or the result reads `[reticle(),react()]`.
+ */
 function insertPlugin(source, port) {
-    // Insert right after the opening `[` of the plugins array.
-    return source.replace(PLUGINS_ARRAY, (match) => `${match}${reticlePluginCall(port)}, `);
+    return source.replace(PLUGINS_ARRAY, (match, _g, offset) => {
+        const next = source[offset + match.length] ?? '';
+        const separator = '' === next || /\s/.test(next) ? '' : ' ';
+        return `${match}${reticlePluginCall(port)},${separator}`;
+    });
 }
 export function patchViteConfig(source, port) {
     if (source.includes(RETICLE_MARKER)) {

package/dist/init/workspace-apps.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
+ *
+ * This used to be the literal list `['apps', 'packages']`. Measured on a real repo with three Next
+ * apps at `web/`, `admin/` and `space/`, it found none — so the redirect never fired, init ran
+ * against the root, and it reported ✓ for writing `app/reticle-dev.tsx` into a directory Next never
+ * compiles. A ⚠ tells a human to act; a ✓ tells them it is handled.
+ *
+ * A workspace DECLARES its packages, so that declaration is used first and directory names are not
+ * guessed at all. Where nothing is declared, every top-level directory is a better candidate than two
+ * hardcoded ones — filtered by the usual non-source suspects, and still subject to the `looksLikeApp`
+ * check that follows, so a wrong guess here costs a `package.json` read.
+ */
+interface WorkspaceSources {
+    /** Raw contents of pnpm-workspace.yaml, when present. */
+    pnpmWorkspace?: string;
+    /** The `workspaces` field of package.json — array form or the yarn/npm object form. */
+    pkgWorkspaces?: unknown;
+    /** Directory names at the repo root, used when nothing is declared. */
+    topLevelDirs?: readonly string[];
+}
+export declare function workspaceParents(sources: WorkspaceSources): string[];
+export {};

package/dist/init/workspace-apps.js

@@ -0,0 +1,68 @@
+/**
+ * Which directories to look in for the app, when `reticle init` runs at a monorepo root.
+ *
+ * This used to be the literal list `['apps', 'packages']`. Measured on a real repo with three Next
+ * apps at `web/`, `admin/` and `space/`, it found none — so the redirect never fired, init ran
+ * against the root, and it reported ✓ for writing `app/reticle-dev.tsx` into a directory Next never
+ * compiles. A ⚠ tells a human to act; a ✓ tells them it is handled.
+ *
+ * A workspace DECLARES its packages, so that declaration is used first and directory names are not
+ * guessed at all. Where nothing is declared, every top-level directory is a better candidate than two
+ * hardcoded ones — filtered by the usual non-source suspects, and still subject to the `looksLikeApp`
+ * check that follows, so a wrong guess here costs a `package.json` read.
+ */
+/** Directories that are never a workspace package, whatever the layout. */
+const NEVER_A_PACKAGE = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', 'target']);
+/** `packages/*` -> `packages`; `web` -> `web`. The base directory a glob searches. */
+function globBase(pattern) {
+    const base = pattern
+        .split('/')[0]
+        ?.trim()
+        .replace(/^['"]|['"]$/g, '');
+    return base === undefined || '' === base || '.' === base || base.includes('*') ? undefined : base;
+}
+function fromPnpm(yaml) {
+    // A deliberately small reader rather than a YAML dependency: this file is a list of globs, and the
+    // only shape that matters is `- 'pattern'` under `packages:`. A malformed file yields nothing,
+    // which falls through to the top-level scan rather than failing the install.
+    const out = [];
+    let inPackages = false;
+    for (const line of yaml.split('\n')) {
+        if (/^packages\s*:/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages && /^\S/.test(line))
+            break;
+        const item = /^\s*-\s*(.+)$/.exec(line);
+        if (inPackages && item?.[1] !== undefined) {
+            const base = globBase(item[1]);
+            if (base !== undefined)
+                out.push(base);
+        }
+    }
+    return out;
+}
+function fromPkg(workspaces) {
+    const list = Array.isArray(workspaces)
+        ? workspaces
+        : 'object' === typeof workspaces && workspaces !== null
+            ? workspaces.packages
+            : undefined;
+    if (!Array.isArray(list))
+        return [];
+    return list
+        .filter((p) => 'string' === typeof p)
+        .map(globBase)
+        .filter((p) => p !== undefined);
+}
+export function workspaceParents(sources) {
+    const declared = [
+        ...(sources.pnpmWorkspace === undefined ? [] : fromPnpm(sources.pnpmWorkspace)),
+        ...fromPkg(sources.pkgWorkspaces),
+    ];
+    const candidates = declared.length > 0
+        ? declared
+        : (sources.topLevelDirs ?? []).filter((d) => !d.startsWith('.') && !NEVER_A_PACKAGE.has(d));
+    return [...new Set(candidates)];
+}

package/dist/input/driven-redaction.d.ts

@@ -0,0 +1,15 @@
+import { type RedactionPolicy } from '@reticlehq/core';
+/** Record what a session declared sensitive. Called when its hello lands. */
+export declare function declareDrivenRedactionKeys(sessionId: string, keys: readonly string[]): void;
+/** Drop a session's declarations when it disconnects, so a closed tab stops widening the union. */
+export declare function forgetDrivenRedactionKeys(sessionId: string): void;
+/** Every key declared by any connected session, sorted so the memo signature is stable. */
+export declare function drivenRedactionKeys(): string[];
+/**
+ * The rule in force for driven-path captures: the built-in rule plus every declared key. Identical
+ * to the built-in rule when no session declared anything, which is the overwhelmingly common case
+ * and the one that must stay byte-identical to before this feature existed.
+ */
+export declare function drivenRedactionPolicy(): RedactionPolicy;
+/** Test seam: drop every declaration. Not used in production — sessions unregister themselves. */
+export declare function resetDrivenRedaction(): void;

package/dist/input/driven-redaction.js

@@ -0,0 +1,76 @@
+import { buildRedactionPolicy } from '@reticlehq/core';
+/**
+ * The redaction rule the DRIVEN path uses — the one place in the daemon that redacts a payload the
+ * browser SDK never saw.
+ *
+ * ## Why this exists at all
+ *
+ * `connect({ redact: { keys } })` is configured in the page, and the SDK redacts everything it
+ * observes. But a driven session's request bodies and response headers are captured by the daemon
+ * straight from the network stack (`page.on('response')`), so they never pass through the SDK. An app
+ * that declared `licenceKey` sensitive would see it redacted everywhere the developer looked, and
+ * find it in cleartext in the on-disk journal — a leak on precisely the path they cannot inspect.
+ * So a session's declared keys are announced in its hello and land here.
+ *
+ * ## Why a daemon-wide UNION rather than a per-session rule
+ *
+ * A NET_DETAIL is redacted at capture time and only routed to a session afterwards, by `pageUrl`.
+ * At the moment of redaction there is no session in hand, and there is a real window in which there
+ * is no session at all yet. Resolving one first would mean either delaying redaction (holding a raw
+ * credential in memory until routing succeeds) or dropping the detail.
+ *
+ * The union sidesteps that, and is only safe because of an asymmetry that is enforced upstream:
+ * declared keys can ONLY add redaction. The worst case is that one local app's declared key
+ * over-redacts a same-named field in another local app on the same daemon — an inconvenience, in the
+ * safe direction, between two apps belonging to the same developer on the same machine. The
+ * dangerous direction is closed by construction: `allow` never crosses the bridge, so nothing a page
+ * sends can lower this floor below the built-in rule.
+ */
+/** Declared keys per session id, so a disconnect narrows the union back down. */
+const declaredBySession = new Map();
+/** Memoized policy + the key set it was built from, so the hot path does not rebuild per response. */
+let cached;
+function invalidate() {
+    cached = undefined;
+}
+/** Record what a session declared sensitive. Called when its hello lands. */
+export function declareDrivenRedactionKeys(sessionId, keys) {
+    if (0 === keys.length) {
+        if (declaredBySession.delete(sessionId))
+            invalidate();
+        return;
+    }
+    declaredBySession.set(sessionId, [...keys]);
+    invalidate();
+}
+/** Drop a session's declarations when it disconnects, so a closed tab stops widening the union. */
+export function forgetDrivenRedactionKeys(sessionId) {
+    if (declaredBySession.delete(sessionId))
+        invalidate();
+}
+/** Every key declared by any connected session, sorted so the memo signature is stable. */
+export function drivenRedactionKeys() {
+    const all = new Set();
+    for (const keys of declaredBySession.values())
+        for (const key of keys)
+            all.add(key);
+    return [...all].sort();
+}
+/**
+ * The rule in force for driven-path captures: the built-in rule plus every declared key. Identical
+ * to the built-in rule when no session declared anything, which is the overwhelmingly common case
+ * and the one that must stay byte-identical to before this feature existed.
+ */
+export function drivenRedactionPolicy() {
+    const keys = drivenRedactionKeys();
+    const signature = keys.join('\u0000');
+    if (cached?.signature !== signature) {
+        cached = { signature, policy: buildRedactionPolicy({ keys }) };
+    }
+    return cached.policy;
+}
+/** Test seam: drop every declaration. Not used in production — sessions unregister themselves. */
+export function resetDrivenRedaction() {
+    declaredBySession.clear();
+    invalidate();
+}

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

@@ -1,4 +1,4 @@
-import { type ReticleEvent } from '@reticlehq/core';
+import { type RedactionPolicy, type ReticleEvent } from '@reticlehq/core';
 /**
  * CDP-authoritative network detail. Wherever the daemon has a CDP connection — whether it launched
  * the browser or attached to one someone else started — `page.on('response')` sees the FULL response:
@@ -34,7 +34,13 @@ export interface NetworkDetail {
      */
     pageUrl?: string;
 }
-/** Shape a raw authoritative response into a NET_DETAIL payload (lower-cased headers). */
+/**
+ * Shape a raw authoritative response into a NET_DETAIL payload (lower-cased headers).
+ *
+ * `policy` defaults to the built-in rule so this stays a PURE builder — the driven-path union is
+ * resolved by `attachNetworkDetail`, at the glue layer, where reading process state is not a lie
+ * about the function's inputs.
+ */
 export declare function buildNetworkDetail(raw: {
     url: string;
     method?: string;
@@ -43,7 +49,7 @@ export declare function buildNetworkDetail(raw: {
     resourceType?: string;
     requestBody?: string;
     pageUrl?: string;
-}): NetworkDetail;
+}, policy?: RedactionPolicy): NetworkDetail;
 /**
  * Fold each NET_DETAIL onto the matching in-page NET_REQUEST (by method+url), enriching it with the
  * authoritative headers/resourceType the page-side wrapper couldn't see — WITHOUT clobbering fields the