@reticlehq/server 2.2.1 → 2.4.0

package/dist/init/detect.d.ts

@@ -6,6 +6,7 @@ export declare const Framework: {
     readonly NEXT: "next";
     readonly VITE: "vite";
     readonly SVELTEKIT: "sveltekit";
+    readonly ASTRO: "astro";
     readonly HTML: "html";
 };
 export type Framework = (typeof Framework)[keyof typeof Framework];
@@ -27,9 +28,31 @@ export interface DetectInput {
     configFiles: ReadonlySet<string>;
     /** Lockfile basenames present in the project root. */
     lockfiles: ReadonlySet<string>;
+    /** Marker basenames inside `node_modules` (`.modules.yaml`, `.yarn-state.yml`, …), if installed. */
+    nodeModulesMarkers?: ReadonlySet<string>;
 }
+/**
+ * The UI library the app renders with. Detection used to key on "vite is in package.json" and stop
+ * there, so a Vue or Preact app got `@reticlehq/react` installed and an all-green report with no
+ * mention that the React adapter has nothing to attach to.
+ */
+export declare const UiLibrary: {
+    readonly REACT: "react";
+    readonly PREACT: "preact";
+    readonly VUE: "vue";
+    readonly SVELTE: "svelte";
+    readonly UNKNOWN: "unknown";
+};
+export type UiLibrary = (typeof UiLibrary)[keyof typeof UiLibrary];
 export interface Detection {
     framework: Framework;
+    uiLibrary: UiLibrary;
+    /**
+     * Whether the project is TypeScript. Not cosmetic: generating a `.tsx` file into a JavaScript
+     * project makes Next auto-install TypeScript on the next `next dev`, which on Next 13 takes its
+     * require-hook down with it and the dev server never starts.
+     */
+    typescript: boolean;
     reactMajor: number | undefined;
     /** React 19 dropped _debugSource, so it needs the build-time source-map stamp. */
     needsSourceMapping: boolean;
@@ -37,6 +60,8 @@ export interface Detection {
 }
 /** Extract the leading major version from a semver range like "^19.0.0" or "19.1.1". */
 export declare function parseMajor(range: string | undefined): number | undefined;
+/** Marker basenames present inside the project's `node_modules`, if it has one. */
+export declare function packageManagerFromNodeModules(markers: ReadonlySet<string>): PackageManager | undefined;
 export declare function detect(input: DetectInput): Detection;
 interface InstallCommand {
     command: string;
@@ -46,4 +71,3 @@ interface InstallCommand {
 export declare function installCommandParts(pm: PackageManager, pkgs: string | readonly string[]): InstallCommand;
 export declare function installCommand(pm: PackageManager, pkgs: string | readonly string[]): string;
 export {};
-//# sourceMappingURL=detect.d.ts.map

package/dist/init/detect.js

@@ -6,6 +6,7 @@ export const Framework = {
     NEXT: 'next',
     VITE: 'vite',
     SVELTEKIT: 'sveltekit',
+    ASTRO: 'astro',
     HTML: 'html',
 };
 export const PackageManager = {
@@ -14,9 +15,22 @@ export const PackageManager = {
     BUN: 'bun',
     NPM: 'npm',
 };
+/**
+ * The UI library the app renders with. Detection used to key on "vite is in package.json" and stop
+ * there, so a Vue or Preact app got `@reticlehq/react` installed and an all-green report with no
+ * mention that the React adapter has nothing to attach to.
+ */
+export const UiLibrary = {
+    REACT: 'react',
+    PREACT: 'preact',
+    VUE: 'vue',
+    SVELTE: 'svelte',
+    UNKNOWN: 'unknown',
+};
 const NEXT_CONFIGS = ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs'];
 const VITE_CONFIGS = ['vite.config.js', 'vite.config.ts', 'vite.config.mjs', 'vite.config.mts'];
 const SVELTE_CONFIGS = ['svelte.config.js', 'svelte.config.ts', 'svelte.config.mjs'];
+const ASTRO_CONFIGS = ['astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.cjs'];
 function depVersion(pkg, name) {
     return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name] ?? pkg.peerDependencies?.[name];
 }
@@ -33,14 +47,36 @@ export function parseMajor(range) {
     const major = parseInt(match[1], 10);
     return isNaN(major) ? undefined : major;
 }
-function detectPackageManager(lockfiles) {
+/**
+ * Markers each package manager leaves INSIDE `node_modules`. An installed tree is the strongest
+ * evidence there is — stronger than a lockfile, which may simply not be committed.
+ *
+ * Without this, a pnpm-installed project with no committed lockfile was read as npm, and `npm i -D`
+ * then died on pnpm's symlink layout with `Cannot read properties of null (reading 'matches')`. Worse,
+ * it left the package present in `node_modules` but absent from `package.json`, so every later run
+ * reported the same failure — a setup that could not be retried into working.
+ */
+const NODE_MODULES_MARKERS = [
+    ['.modules.yaml', PackageManager.PNPM],
+    ['.yarn-state.yml', PackageManager.YARN],
+    ['.package-lock.json', PackageManager.NPM],
+];
+/** Marker basenames present inside the project's `node_modules`, if it has one. */
+export function packageManagerFromNodeModules(markers) {
+    for (const [name, pm] of NODE_MODULES_MARKERS)
+        if (markers.has(name))
+            return pm;
+    return undefined;
+}
+function detectPackageManager(lockfiles, nodeModulesMarkers) {
     if (lockfiles.has('pnpm-lock.yaml'))
         return PackageManager.PNPM;
     if (lockfiles.has('yarn.lock'))
         return PackageManager.YARN;
     if (lockfiles.has('bun.lockb') || lockfiles.has('bun.lock'))
         return PackageManager.BUN;
-    return PackageManager.NPM;
+    // No lockfile is not the same as "npm". An already-installed tree says which manager built it.
+    return packageManagerFromNodeModules(nodeModulesMarkers) ?? PackageManager.NPM;
 }
 function detectFramework(input) {
     const { pkg, configFiles } = input;
@@ -52,18 +88,44 @@ function detectFramework(input) {
     if (depVersion(pkg, '@sveltejs/kit') !== undefined || hasAnyConfig(configFiles, SVELTE_CONFIGS)) {
         return Framework.SVELTEKIT;
     }
+    // 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 — it used to fall all the way through to HTML and be handed
+    // connect instructions for a bundler it does not have. Check BEFORE the generic Vite branch.
+    if (depVersion(pkg, 'astro') !== undefined || hasAnyConfig(configFiles, ASTRO_CONFIGS)) {
+        return Framework.ASTRO;
+    }
     if (depVersion(pkg, 'vite') !== undefined || hasAnyConfig(configFiles, VITE_CONFIGS)) {
         return Framework.VITE;
     }
     return Framework.HTML;
 }
+/**
+ * React first: a Preact app using preact/compat aliases React, and Next/Remix apps list both. The
+ * order is the precedence — whichever the app actually renders through is the one it depends on
+ * directly.
+ */
+function detectUiLibrary(pkg) {
+    if (depVersion(pkg, 'react') !== undefined)
+        return UiLibrary.REACT;
+    if (depVersion(pkg, 'preact') !== undefined)
+        return UiLibrary.PREACT;
+    if (depVersion(pkg, 'vue') !== undefined)
+        return UiLibrary.VUE;
+    if (depVersion(pkg, 'svelte') !== undefined)
+        return UiLibrary.SVELTE;
+    return UiLibrary.UNKNOWN;
+}
+const TS_CONFIGS = ['tsconfig.json'];
 export function detect(input) {
     const reactMajor = parseMajor(depVersion(input.pkg, 'react'));
     return {
         framework: detectFramework(input),
+        uiLibrary: detectUiLibrary(input.pkg),
+        typescript: hasAnyConfig(input.configFiles, TS_CONFIGS) ||
+            depVersion(input.pkg, 'typescript') !== undefined,
         reactMajor,
         needsSourceMapping: reactMajor !== undefined && reactMajor >= 19,
-        packageManager: detectPackageManager(input.lockfiles),
+        packageManager: detectPackageManager(input.lockfiles, input.nodeModulesMarkers ?? new Set()),
     };
 }
 const INSTALL_ARGS = {
@@ -81,4 +143,3 @@ export function installCommand(pm, pkgs) {
     const { command, args } = installCommandParts(pm, pkgs);
     return `${command} ${args.join(' ')}`;
 }
-//# sourceMappingURL=detect.js.map

package/dist/init/mcp.d.ts

@@ -37,4 +37,3 @@ export declare function claudeAvailableProbe(): {
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
 export declare function mcpManual(): string;
 export {};
-//# sourceMappingURL=mcp.d.ts.map

package/dist/init/mcp.js

@@ -53,4 +53,3 @@ Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.curso
 
   "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }`;
 }
-//# sourceMappingURL=mcp.js.map

package/dist/init/next-patch.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure, conservative patchers for the two files a Next app needed edited BY HAND: `next.config.*`
+ * (wrap the export in `withReticle`) and `app/layout.tsx` (mount `<ReticleDev />`). Same contract as
+ * the Vite patcher — recognise the obvious shape, bail to `manual` on anything ambiguous, never
+ * half-edit. Leaving these manual is why Next connected 0% of the time: both edits are silent when
+ * skipped, and one of them is JSX.
+ */
+import { type SourcePatch } from './patch-kind.js';
+export declare const NEXT_CONFIG_IMPORT = "import { withReticle } from '@reticlehq/next';";
+export declare const NEXT_CONFIG_REQUIRE = "const { withReticle } = require('@reticlehq/next');";
+export declare const RETICLE_DEV_IMPORT: string;
+/** Where the generated connect component goes, and how the mount file should import it. */
+export interface ReticleDevLocation {
+    /** Project-relative path to write. */
+    path: string;
+    /** What the mount file (`app/layout.*` or `pages/_app.*`) should import. */
+    importSpecifier: string;
+}
+/**
+ * Decide where the connect component lives, from the file that will mount it.
+ *
+ * Two things this gets wrong if hardcoded, both of which broke real apps:
+ *
+ * - **Pages Router routes on presence.** EVERY file under `pages/` is a route, so a component
+ *   dropped there has no default export: `/reticle-dev` 500s and `next build` fails. It has to go
+ *   somewhere that is not a route directory. App Router routes on FILENAME (`page`/`layout`/
+ *   `route`), so an extra file beside the layout is inert and can stay there.
+ * - **The extension is not cosmetic.** A `.tsx` file in a JavaScript project makes Next auto-install
+ *   TypeScript on the next `next dev` — and on Next 13 that takes its require-hook down with it, so
+ *   the dev server never starts. The install then looks like it broke the app, because it did.
+ */
+export declare function reticleDevLocation(mountPath: string, typescript: boolean): ReticleDevLocation;
+export declare function patchNextConfig(source: string): SourcePatch;
+/**
+ * Pages Router has no root layout to mount into — `app/layout.tsx` does not exist — so the connect
+ * rides in `pages/_app` instead, wrapped in a fragment alongside the page. Without this, `init`
+ * wrote `app/reticle-dev.tsx` into a directory the app does not have and nothing ever connected,
+ * with no error to say so.
+ */
+export declare function patchPagesApp(source: string, importSpecifier?: string): SourcePatch;
+export declare function patchRootLayout(source: string): SourcePatch;

package/dist/init/next-patch.js

@@ -0,0 +1,106 @@
+/**
+ * Pure, conservative patchers for the two files a Next app needed edited BY HAND: `next.config.*`
+ * (wrap the export in `withReticle`) and `app/layout.tsx` (mount `<ReticleDev />`). Same contract as
+ * the Vite patcher — recognise the obvious shape, bail to `manual` on anything ambiguous, never
+ * half-edit. Leaving these manual is why Next connected 0% of the time: both edits are silent when
+ * skipped, and one of them is JSX.
+ */
+import { PatchKind } from './patch-kind.js';
+const RETICLE_NEXT_PACKAGE = '@reticlehq/next';
+export const NEXT_CONFIG_IMPORT = `import { withReticle } from '${RETICLE_NEXT_PACKAGE}';`;
+export const NEXT_CONFIG_REQUIRE = `const { withReticle } = require('${RETICLE_NEXT_PACKAGE}');`;
+const RETICLE_DEV_COMPONENT = 'ReticleDev';
+const RETICLE_DEV_BASENAME = 'reticle-dev';
+/** Default import specifier: the component sits beside the file importing it (App Router). */
+const RETICLE_DEV_SIBLING = `./${RETICLE_DEV_BASENAME}`;
+const reticleDevImport = (specifier) => `import { ${RETICLE_DEV_COMPONENT} } from '${specifier}';`;
+export const RETICLE_DEV_IMPORT = reticleDevImport(RETICLE_DEV_SIBLING);
+/**
+ * Decide where the connect component lives, from the file that will mount it.
+ *
+ * Two things this gets wrong if hardcoded, both of which broke real apps:
+ *
+ * - **Pages Router routes on presence.** EVERY file under `pages/` is a route, so a component
+ *   dropped there has no default export: `/reticle-dev` 500s and `next build` fails. It has to go
+ *   somewhere that is not a route directory. App Router routes on FILENAME (`page`/`layout`/
+ *   `route`), so an extra file beside the layout is inert and can stay there.
+ * - **The extension is not cosmetic.** A `.tsx` file in a JavaScript project makes Next auto-install
+ *   TypeScript on the next `next dev` — and on Next 13 that takes its require-hook down with it, so
+ *   the dev server never starts. The install then looks like it broke the app, because it did.
+ */
+export function reticleDevLocation(mountPath, typescript) {
+    const ext = typescript ? '.tsx' : '.jsx';
+    const slash = mountPath.lastIndexOf('/');
+    const dir = slash === -1 ? '' : mountPath.slice(0, slash);
+    const isPagesRouter = /(^|\/)pages$/.test(dir);
+    if (!isPagesRouter) {
+        return {
+            path: `${dir === '' ? '' : `${dir}/`}${RETICLE_DEV_BASENAME}${ext}`,
+            importSpecifier: RETICLE_DEV_SIBLING,
+        };
+    }
+    // Siblings of `pages/`, so `src/pages/_app.js` → `src/components/…` and `pages/_app.js` → `components/…`.
+    const parent = dir.slice(0, Math.max(0, dir.length - 'pages'.length));
+    return {
+        path: `${parent}components/${RETICLE_DEV_BASENAME}${ext}`,
+        importSpecifier: `../components/${RETICLE_DEV_BASENAME}`,
+    };
+}
+/** The dev-guarded mount. Production strips it — `process.env.NODE_ENV` is inlined at build time. */
+const RETICLE_DEV_MOUNT = `{process.env.NODE_ENV === 'development' ? <${RETICLE_DEV_COMPONENT} /> : null}`;
+/** `export default <expr>;` — the ESM shape every `create-next-app` config uses. */
+const ESM_DEFAULT_EXPORT = /export\s+default\s+([\s\S]+?);?\s*$/;
+/** `module.exports = <expr>;` — the CJS shape older configs use. */
+const CJS_EXPORT = /module\.exports\s*=\s*([\s\S]+?);?\s*$/;
+/** The opening `<body ...>` tag, whose first child is where the mount goes. */
+const BODY_OPEN_TAG = /<body(\s[^>]*)?>/g;
+const NO_EXPORT_REASON = "couldn't find an `export default` or `module.exports` to wrap";
+const NO_BODY_REASON = "couldn't find a single <body> tag to mount <ReticleDev /> inside";
+export function patchNextConfig(source) {
+    if (source.includes(RETICLE_NEXT_PACKAGE))
+        return { kind: PatchKind.ALREADY };
+    const esm = ESM_DEFAULT_EXPORT.exec(source);
+    if (esm?.[1] !== undefined) {
+        const wrapped = source.replace(ESM_DEFAULT_EXPORT, `export default withReticle(${esm[1]});\n`);
+        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_IMPORT}\n${wrapped}` };
+    }
+    const cjs = CJS_EXPORT.exec(source);
+    if (cjs?.[1] !== undefined) {
+        const wrapped = source.replace(CJS_EXPORT, `module.exports = withReticle(${cjs[1]});\n`);
+        return { kind: PatchKind.APPLY, code: `${NEXT_CONFIG_REQUIRE}\n${wrapped}` };
+    }
+    return { kind: PatchKind.MANUAL, reason: NO_EXPORT_REASON };
+}
+/** `<Component {...pageProps} />` — the one element every `pages/_app` renders. */
+const PAGES_APP_COMPONENT = /<Component\b[^>]*\/>/g;
+const NO_PAGES_COMPONENT_REASON = "couldn't find a single <Component {...pageProps} /> to wrap in pages/_app";
+/**
+ * Pages Router has no root layout to mount into — `app/layout.tsx` does not exist — so the connect
+ * rides in `pages/_app` instead, wrapped in a fragment alongside the page. Without this, `init`
+ * wrote `app/reticle-dev.tsx` into a directory the app does not have and nothing ever connected,
+ * with no error to say so.
+ */
+export function patchPagesApp(source, importSpecifier = RETICLE_DEV_SIBLING) {
+    if (source.includes(RETICLE_DEV_COMPONENT))
+        return { kind: PatchKind.ALREADY };
+    const matches = [...source.matchAll(PAGES_APP_COMPONENT)];
+    const match = matches.length === 1 ? matches[0] : undefined;
+    if (match?.index === undefined)
+        return { kind: PatchKind.MANUAL, reason: NO_PAGES_COMPONENT_REASON };
+    const wrapped = `<>${RETICLE_DEV_MOUNT}${match[0]}</>`;
+    const code = source.slice(0, match.index) + wrapped + source.slice(match.index + match[0].length);
+    return { kind: PatchKind.APPLY, code: `${reticleDevImport(importSpecifier)}\n${code}` };
+}
+export function patchRootLayout(source) {
+    if (source.includes(RETICLE_DEV_COMPONENT))
+        return { kind: PatchKind.ALREADY };
+    const tags = [...source.matchAll(BODY_OPEN_TAG)];
+    // Exactly one <body> or we cannot tell which one actually renders — and mounting into the wrong
+    // one is the same silent no-connect as not mounting at all.
+    const tag = tags.length === 1 ? tags[0] : undefined;
+    if (tag?.index === undefined)
+        return { kind: PatchKind.MANUAL, reason: NO_BODY_REASON };
+    const insertAt = tag.index + tag[0].length;
+    const mounted = `${source.slice(0, insertAt)}${RETICLE_DEV_MOUNT}${source.slice(insertAt)}`;
+    return { kind: PatchKind.APPLY, code: `${RETICLE_DEV_IMPORT}\n${mounted}` };
+}

package/dist/init/node-io.d.ts

@@ -5,4 +5,3 @@
  */
 import type { InitIo } from './run.js';
 export declare function buildNodeIo(cwd: string): InitIo;
-//# sourceMappingURL=node-io.d.ts.map

package/dist/init/node-io.js

@@ -38,6 +38,31 @@ export function buildNodeIo(cwd) {
                 }
             });
         },
+        listDirs(rel) {
+            const path = abs(rel);
+            if (!existsSync(path))
+                return [];
+            try {
+                return readdirSync(path).filter((name) => statSync(join(path, name)).isDirectory());
+            }
+            catch {
+                return [];
+            }
+        },
+        listFiles(rel) {
+            const path = abs(rel);
+            if (!existsSync(path))
+                return [];
+            try {
+                return readdirSync(path).filter((name) => !statSync(join(path, name)).isDirectory());
+            }
+            catch {
+                return [];
+            }
+        },
+        scoped(rel) {
+            return buildNodeIo(abs(rel));
+        },
         exec(command, args) {
             // `shell: true` lets package-manager shims (pnpm.cmd, etc.) resolve on Windows; inherit
             // stdio so the install's own progress is visible to the user.
@@ -54,4 +79,3 @@ export function buildNodeIo(cwd) {
         },
     };
 }
-//# sourceMappingURL=node-io.js.map

package/dist/init/patch-kind.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The outcome vocabulary shared by every conservative source patcher in `init` (Vite config, Next
+ * config, Next root layout). One enum so a new patcher cannot invent a fourth status the reporter
+ * has no symbol for.
+ */
+export declare const PatchKind: {
+    readonly APPLY: "apply";
+    readonly ALREADY: "already";
+    readonly MANUAL: "manual";
+};
+export type PatchKind = (typeof PatchKind)[keyof typeof PatchKind];
+export type SourcePatch = {
+    kind: typeof PatchKind.APPLY;
+    code: string;
+} | {
+    kind: typeof PatchKind.ALREADY;
+} | {
+    kind: typeof PatchKind.MANUAL;
+    reason: string;
+};

package/dist/init/patch-kind.js

@@ -0,0 +1,10 @@
+/**
+ * The outcome vocabulary shared by every conservative source patcher in `init` (Vite config, Next
+ * config, Next root layout). One enum so a new patcher cannot invent a fourth status the reporter
+ * has no symbol for.
+ */
+export const PatchKind = {
+    APPLY: 'apply',
+    ALREADY: 'already',
+    MANUAL: 'manual',
+};

package/dist/init/plan-framework.d.ts

@@ -0,0 +1,35 @@
+/**
+ * How each framework gets wired: the Vite plugin, the three Next files, the SvelteKit client hook.
+ * Split out of `plan.ts` — that file is the plan's SHAPE (statuses, ordering, the agent/MCP steps),
+ * this one is the per-framework detail, and they grow for different reasons.
+ */
+import { type PlanInput, type Step } from './plan.js';
+/** What adding `reticle()` to a Vite config buys, which differs by framework. */
+export declare const VITE_PLUGIN_DETAIL: {
+    /** A plain Vite app gets both halves from the plugin. */
+    readonly VITE: "add reticle() to plugins (also injects connect())";
+    /**
+     * SvelteKit renders through app.html, so the plugin's HTML injection never fires and connect()
+     * comes from the client hook instead. The plugin is still required: it is what stamps
+     * data-reticle-source into .svelte components, and without it every verdict on a SvelteKit app
+     * comes back with no file:line at all.
+     */
+    readonly SVELTEKIT: "add reticle() to plugins (stamps data-reticle-source in .svelte components)";
+};
+export declare const CAPABILITIES_TITLE = "Capabilities + store";
+export declare function viteSteps(input: PlanInput, detail?: string): Step[];
+/**
+ * Next used to be the ONLY stack with hand edits left over — and both of them fail silently when
+ * skipped, so a Next user's app booted, connected to nothing, and said nothing about why. Both are
+ * now patched by the same conservative rules the Vite config gets.
+ */
+export declare function nextSteps(input: PlanInput): Step[];
+/**
+ * SvelteKit is WIRED but not SUPPORTED, and the plan says so out loud.
+ *
+ * There is no SvelteKit app in `apps/` and no CI gate for one, so nothing proves this hook still
+ * registers a session — every other framework init offers (React, Next, Remix, Astro) has both. The
+ * wiring is real and may well work; what is missing is anything that would tell us when it stops.
+ * Silently emitting it reads as a support claim, which is the thing this project exists to not do.
+ */
+export declare function svelteKitSteps(input: PlanInput): Step[];

package/dist/init/plan-framework.js

@@ -0,0 +1,217 @@
+/**
+ * How each framework gets wired: the Vite plugin, the three Next files, the SvelteKit client hook.
+ * Split out of `plan.ts` — that file is the plan's SHAPE (statuses, ordering, the agent/MCP steps),
+ * this one is the per-framework detail, and they grow for different reasons.
+ */
+import { patchViteConfig, VitePatchKind } from './vite-config.js';
+import { patchNextConfig, patchRootLayout, patchPagesApp } from './next-patch.js';
+import { PatchKind } from './patch-kind.js';
+import { viteManual, NEXT_LAYOUT_MANUAL, NEXT_LAYOUT_PATH, viteDevModuleFile, VITE_DEV_MODULE_PATH, nextReticleDevFile, NEXT_RETICLE_DEV_PATH, nextConfigManual, svelteKitHooksFile, SVELTEKIT_HOOKS_PATH, UNVERIFIED_FRAMEWORK_NOTE, } from './snippets.js';
+import { StepStatus } from './plan.js';
+/** What adding `reticle()` to a Vite config buys, which differs by framework. */
+export const VITE_PLUGIN_DETAIL = {
+    /** A plain Vite app gets both halves from the plugin. */
+    VITE: 'add reticle() to plugins (also injects connect())',
+    /**
+     * SvelteKit renders through app.html, so the plugin's HTML injection never fires and connect()
+     * comes from the client hook instead. The plugin is still required: it is what stamps
+     * data-reticle-source into .svelte components, and without it every verdict on a SvelteKit app
+     * comes back with no file:line at all.
+     */
+    SVELTEKIT: 'add reticle() to plugins (stamps data-reticle-source in .svelte components)',
+};
+export const CAPABILITIES_TITLE = 'Capabilities + store';
+/**
+ * The dev module carrying `registerCapabilities` / `registerStore`.
+ *
+ * Without it every app came up `hasCapabilities: false` with a `reticle_state` holding nothing but
+ * `__reticle_renders` — the state-truth read was unavailable on every app out of the box. Written
+ * only when absent, because it is the one generated file a user is expected to EDIT.
+ */
+function capabilitiesStep(input) {
+    if (input.viteDevModuleExists === true) {
+        return [
+            {
+                title: CAPABILITIES_TITLE,
+                target: VITE_DEV_MODULE_PATH,
+                status: StepStatus.ALREADY,
+                detail: 'file exists — left alone, it is yours to edit',
+            },
+        ];
+    }
+    const testids = input.testids ?? [];
+    const stores = input.storeHints ?? [];
+    const found = testids.length > 0 ? `${String(testids.length)} data-testid values` : 'no data-testid values yet';
+    return [
+        {
+            title: CAPABILITIES_TITLE,
+            target: VITE_DEV_MODULE_PATH,
+            status: StepStatus.APPLY,
+            detail: `${found}; ${stores.length > 0 ? `store: uncomment the ${String(stores.length)} suggested line(s)` : 'no state library detected'}`,
+            write: { path: VITE_DEV_MODULE_PATH, content: viteDevModuleFile(testids, stores) },
+            dependsOnInstall: true,
+        },
+    ];
+}
+export function viteSteps(input, detail = VITE_PLUGIN_DETAIL.VITE) {
+    // Capabilities are independent of whether the config needed patching. Attaching them to the APPLY
+    // branch meant a re-run on an already-wired app silently never created the module.
+    return [...viteConfigSteps(input, detail), ...capabilitiesStep(input)];
+}
+function viteConfigSteps(input, detail) {
+    const cfg = input.viteConfig;
+    const port = input.options.port;
+    if (cfg === null) {
+        return [
+            {
+                title: 'Vite plugin',
+                target: 'vite.config',
+                status: StepStatus.MANUAL,
+                detail: viteManual(port),
+            },
+        ];
+    }
+    const patch = patchViteConfig(cfg.source, port);
+    if (patch.kind === VitePatchKind.ALREADY) {
+        return [
+            {
+                title: 'Vite plugin',
+                target: cfg.path,
+                status: StepStatus.ALREADY,
+                detail: 'reticle() already in plugins',
+            },
+        ];
+    }
+    if (patch.kind === VitePatchKind.MANUAL) {
+        return [
+            {
+                title: 'Vite plugin',
+                target: cfg.path,
+                status: StepStatus.MANUAL,
+                detail: `${patch.reason}\n\n${viteManual(port)}`,
+            },
+        ];
+    }
+    return [
+        {
+            title: 'Vite plugin',
+            target: cfg.path,
+            status: StepStatus.APPLY,
+            detail,
+            write: { path: cfg.path, content: patch.code },
+            dependsOnInstall: true,
+        },
+    ];
+}
+/**
+ * Turn a conservative source patch into a step: applied when it patched, already when the wiring is
+ * there, and the hand-edit instructions when the file shape wasn't one we recognise.
+ */
+function patchStep(title, path, patch, applyDetail, manualDetail) {
+    if (patch.kind === PatchKind.ALREADY) {
+        return { title, target: path, status: StepStatus.ALREADY, detail: 'already wired' };
+    }
+    if (patch.kind === PatchKind.MANUAL) {
+        return {
+            title,
+            target: path,
+            status: StepStatus.MANUAL,
+            detail: `${patch.reason}\n\n${manualDetail}`,
+        };
+    }
+    return {
+        title,
+        target: path,
+        status: StepStatus.APPLY,
+        detail: applyDetail,
+        write: { path, content: patch.code },
+        dependsOnInstall: true,
+    };
+}
+/**
+ * Next used to be the ONLY stack with hand edits left over — and both of them fail silently when
+ * skipped, so a Next user's app booted, connected to nothing, and said nothing about why. Both are
+ * now patched by the same conservative rules the Vite config gets.
+ */
+export function nextSteps(input) {
+    const configFile = input.nextConfigFile ?? 'next.config.mjs';
+    const devPath = input.nextReticleDevPath ?? NEXT_RETICLE_DEV_PATH;
+    const devFile = input.nextReticleDevExists
+        ? {
+            title: 'ReticleDev component',
+            target: devPath,
+            status: StepStatus.ALREADY,
+            detail: 'file exists',
+        }
+        : {
+            title: 'ReticleDev component',
+            target: devPath,
+            status: StepStatus.APPLY,
+            detail: 'create dev-only connect component',
+            write: {
+                path: devPath,
+                content: nextReticleDevFile(input.options.port, input.options.projectId, input.testids ?? [], input.storeHints ?? []),
+            },
+            dependsOnInstall: true,
+        };
+    const configPatch = input.nextConfigSource === null || input.nextConfigSource === undefined
+        ? { kind: PatchKind.MANUAL, reason: `no ${configFile} found` }
+        : patchNextConfig(input.nextConfigSource);
+    const layout = input.nextLayout ?? null;
+    // Pages Router mounts through pages/_app, App Router through the root layout — different edits,
+    // and picking by path is what stops a Pages app being handed the layout patch that cannot apply.
+    const isPagesRouter = layout !== null && /(^|\/)pages\/_app\.[jt]sx?$/.test(layout.path);
+    const layoutPatch = layout === null
+        ? { kind: PatchKind.MANUAL, reason: 'no root layout (app/layout.tsx) or pages/_app found' }
+        : isPagesRouter
+            ? patchPagesApp(layout.source, input.nextReticleDevImport)
+            : patchRootLayout(layout.source);
+    return [
+        devFile,
+        patchStep('Next config (withReticle)', configFile, configPatch, 'wrap the export in withReticle (source mapping, dev-only)', nextConfigManual(configFile)),
+        patchStep('Mount ReticleDev', layout?.path ?? NEXT_LAYOUT_PATH, layoutPatch, 'mount <ReticleDev /> in the root layout (dev-only)', NEXT_LAYOUT_MANUAL),
+    ];
+}
+/**
+ * SvelteKit is WIRED but not SUPPORTED, and the plan says so out loud.
+ *
+ * There is no SvelteKit app in `apps/` and no CI gate for one, so nothing proves this hook still
+ * registers a session — every other framework init offers (React, Next, Remix, Astro) has both. The
+ * wiring is real and may well work; what is missing is anything that would tell us when it stops.
+ * Silently emitting it reads as a support claim, which is the thing this project exists to not do.
+ */
+export function svelteKitSteps(input) {
+    const unverified = {
+        title: 'SvelteKit is UNVERIFIED',
+        target: SVELTEKIT_HOOKS_PATH,
+        status: StepStatus.NOTICE,
+        detail: UNVERIFIED_FRAMEWORK_NOTE,
+    };
+    // SvelteKit can't use the Vite-plugin injection (it renders via app.html) — wire a client hook
+    // that SvelteKit runs on startup, which is the path that can register a session at all.
+    if (input.svelteKitHooksExists === true) {
+        return [
+            unverified,
+            {
+                title: 'Reticle client hook',
+                target: SVELTEKIT_HOOKS_PATH,
+                status: StepStatus.ALREADY,
+                detail: 'file exists',
+            },
+        ];
+    }
+    return [
+        unverified,
+        {
+            title: 'Reticle client hook',
+            target: SVELTEKIT_HOOKS_PATH,
+            status: StepStatus.APPLY,
+            detail: 'create dev-only client connect (SvelteKit renders via app.html)',
+            write: {
+                path: SVELTEKIT_HOOKS_PATH,
+                content: svelteKitHooksFile(input.options.port, input.options.projectId),
+            },
+            dependsOnInstall: true,
+        },
+    ];
+}