@reticlehq/init 3.2.0 → 3.4.0

package/dist/patch/static-page.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The connect snippet, written INTO a static page rather than printed beside it.
+ *
+ * A page with no package.json has no build, so the pasted `<script type="module">` is the whole
+ * install — proven end to end on a page served by `python3 -m http.server`. `init` used to print it
+ * and exit 1 with `no_package_json`, which made the one path that works read as a failure, and left
+ * the step to a human who then had to be told where to put it.
+ *
+ * Two things differ from the printed recipe, both because the file is the deployable artifact:
+ *
+ * - It runs only on a loopback host. A static file has no development build to strip it, so the
+ *   host is the only line between this snippet and a published page; guarded, a published copy
+ *   does not even fetch the SDK. The printed bundled-app recipe deliberately does NOT do this
+ *   (a hosts-file dev alias defeats it, see html-no-build.test.ts) — that recipe has NODE_ENV.
+ * - It is marked, so a re-run recognises its own block and never writes a second one.
+ * - It carries no pairing token. The token used to be a literal in the page, so committing or
+ *   publishing index.html published it; it now sits in a module beside the page that `init`
+ *   gitignores, which the block imports and any static server serves. Absent — a teammate's
+ *   checkout, a published copy — the connect goes without one, and the bridge says why it refused.
+ */
+/** The page a static site serves at its root, and the one file `init` will write the snippet into. */
+export declare const HTML_INDEX_PATH = "index.html";
+/** The gitignored module beside the page that holds this machine's pairing token. */
+export declare const STATIC_TOKEN_MODULE = "reticle.local.js";
+/** Opens the block `init` writes; a re-run looks for it. */
+export declare const STATIC_SNIPPET_MARKER = "<!-- reticle:connect (dev only, written by reticle init) -->";
+/** Whether this page already carries a Reticle connect. */
+export declare function hasStaticSnippet(html: string): boolean;
+/** The token module's content. Rewritten on every run, so a re-minted token is picked up. */
+export declare function staticTokenModule(pairingToken: string): string;
+/** The files to write so the token module exists and git ignores it; only what actually changes. */
+export declare function staticTokenFiles(pairingToken: string | undefined, readFile: (path: string) => string | null): Record<string, string>;
+/**
+ * The page with the snippet added, or null when it already connects.
+ *
+ * Before `</body>` so the SDK starts on a parsed document; before `</head>` for a page with no body
+ * tag, and at the end for a fragment with neither.
+ */
+export declare function withStaticSnippet(html: string, connectArgLiteral: string): string | null;

package/dist/patch/static-page.js

@@ -0,0 +1,102 @@
+/**
+ * The connect snippet, written INTO a static page rather than printed beside it.
+ *
+ * A page with no package.json has no build, so the pasted `<script type="module">` is the whole
+ * install — proven end to end on a page served by `python3 -m http.server`. `init` used to print it
+ * and exit 1 with `no_package_json`, which made the one path that works read as a failure, and left
+ * the step to a human who then had to be told where to put it.
+ *
+ * Two things differ from the printed recipe, both because the file is the deployable artifact:
+ *
+ * - It runs only on a loopback host. A static file has no development build to strip it, so the
+ *   host is the only line between this snippet and a published page; guarded, a published copy
+ *   does not even fetch the SDK. The printed bundled-app recipe deliberately does NOT do this
+ *   (a hosts-file dev alias defeats it, see html-no-build.test.ts) — that recipe has NODE_ENV.
+ * - It is marked, so a re-run recognises its own block and never writes a second one.
+ * - It carries no pairing token. The token used to be a literal in the page, so committing or
+ *   publishing index.html published it; it now sits in a module beside the page that `init`
+ *   gitignores, which the block imports and any static server serves. Absent — a teammate's
+ *   checkout, a published copy — the connect goes without one, and the bridge says why it refused.
+ */
+import { CDN_SDK_URL } from './snippets.js';
+/** The page a static site serves at its root, and the one file `init` will write the snippet into. */
+export const HTML_INDEX_PATH = 'index.html';
+/** The gitignored module beside the page that holds this machine's pairing token. */
+export const STATIC_TOKEN_MODULE = 'reticle.local.js';
+const GITIGNORE_PATH = '.gitignore';
+/** Opens the block `init` writes; a re-run looks for it. */
+export const STATIC_SNIPPET_MARKER = '<!-- reticle:connect (dev only, written by reticle init) -->';
+const STATIC_SNIPPET_END = '<!-- /reticle:connect -->';
+/** Hostnames a developer's own machine serves a page on. */
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
+/**
+ * Signs that the page already connects, whoever put the snippet there — the printed recipe pasted
+ * by hand counts as much as our own block.
+ */
+const ALREADY_CONNECTS = [STATIC_SNIPPET_MARKER, '@reticlehq/browser'];
+const BODY_CLOSE = /<\/body>/i;
+const HEAD_CLOSE = /<\/head>/i;
+/** Whether this page already carries a Reticle connect. */
+export function hasStaticSnippet(html) {
+    return ALREADY_CONNECTS.some((sign) => html.includes(sign));
+}
+function block(connectArgLiteral) {
+    const hosts = LOOPBACK_HOSTS.map((h) => `'${h}'`).join(', ');
+    const arg = '' === connectArgLiteral
+        ? '{ token: local.token }'
+        : `{ ...${connectArgLiteral}, token: local.token }`;
+    return `    ${STATIC_SNIPPET_MARKER}
+    <script type="module">
+      if ([${hosts}].includes(location.hostname)) {
+        Promise.all([
+          import('${CDN_SDK_URL}'),
+          import('./${STATIC_TOKEN_MODULE}').catch(() => ({})),
+        ]).then(([{ reticle }, local]) => reticle.connect(${arg}));
+      }
+    </script>
+    ${STATIC_SNIPPET_END}
+`;
+}
+/** The token module's content. Rewritten on every run, so a re-minted token is picked up. */
+export function staticTokenModule(pairingToken) {
+    return (`// This machine's Reticle pairing token, written by \`reticle init\`. Gitignored: never commit\n` +
+        `// or publish it — each machine runs \`reticle init\` for its own.\n` +
+        `export const token = '${pairingToken}';\n`);
+}
+/** The files to write so the token module exists and git ignores it; only what actually changes. */
+export function staticTokenFiles(pairingToken, readFile) {
+    if (pairingToken === undefined || 0 === pairingToken.length)
+        return {};
+    const files = {};
+    const module = staticTokenModule(pairingToken);
+    if (readFile(STATIC_TOKEN_MODULE) !== module)
+        files[STATIC_TOKEN_MODULE] = module;
+    const ignore = readFile(GITIGNORE_PATH) ?? '';
+    const covered = ignore
+        .split('\n')
+        .some((l) => [STATIC_TOKEN_MODULE, `/${STATIC_TOKEN_MODULE}`].includes(l.trim()));
+    if (!covered) {
+        files[GITIGNORE_PATH] =
+            `${'' === ignore ? '' : ignore.replace(/\n*$/, '\n')}${STATIC_TOKEN_MODULE}\n`;
+    }
+    return files;
+}
+/**
+ * The page with the snippet added, or null when it already connects.
+ *
+ * Before `</body>` so the SDK starts on a parsed document; before `</head>` for a page with no body
+ * tag, and at the end for a fragment with neither.
+ */
+export function withStaticSnippet(html, connectArgLiteral) {
+    if (hasStaticSnippet(html))
+        return null;
+    const snippet = block(connectArgLiteral);
+    const anchor = BODY_CLOSE.exec(html) ?? HEAD_CLOSE.exec(html);
+    if (null === anchor)
+        return `${html.trimEnd()}\n${snippet}`;
+    // At the start of the closing tag's own line when it sits alone on one, so its indentation stays
+    // with it rather than moving onto the first line of the snippet.
+    const lineStart = html.lastIndexOf('\n', anchor.index - 1) + 1;
+    const at = '' === html.slice(lineStart, anchor.index).trim() ? lineStart : anchor.index;
+    return `${html.slice(0, at)}${snippet}${html.slice(at)}`;
+}

package/dist/patch/tanstack-start.d.ts

@@ -1,17 +1,45 @@
 /**
- * The TanStack Start connect recipe.
+ * The TanStack Start connect: a client-only component, rendered in the document the root route SSRs.
  *
- * Its own module because Start is the one framework whose document module `init` deliberately
- * refuses to write, so the recipe and the reasoning behind that refusal are a unit.
+ * Its own module because Start is the one framework whose document module is ALSO the server
+ * render, so what may be written into it — and what must stay out — is a unit.
  */
+import { type SourcePatch } from './patch-kind.js';
 /** TanStack Start's document module — the file that SSRs `<html>`. */
 export declare const TANSTACK_START_ROOT_PATH = "src/routes/__root.tsx";
 /**
- * The TanStack Start recipe, printed rather than written.
+ * Where the connect component goes: beside the `routes/` directory, never inside it — a file under
+ * `routes/` is a route to Start's file-based router.
+ */
+export declare function tanstackStartConnectPath(rootPath?: string): string;
+/**
+ * The connect component.
+ *
+ * A dynamic SDK import inside `useEffect`, because a static import on anything the root document
+ * imports is evaluated during the server render and 500s the page. Effects never run on the server.
+ * The pairing token is the one the Vite plugin inlines as `__RETICLE_TOKEN__`, declared here so the
+ * file passes the scaffold's strict `tsc` — the recipe this replaced used the name undeclared and
+ * failed with `TS2304: Cannot find name '__RETICLE_TOKEN__'`.
+ *
+ * It also loads the app's `src/reticle-dev.ts` after connecting. Start is written `inject: false`,
+ * and the plugin's injected connect is the only other thing that imports that file, so without this
+ * line every store and capability registered there silently never ran.
+ */
+export declare function tanstackStartConnectFile(port: number | undefined, projectId?: string, rootPath?: string): string;
+/**
+ * Render the component in the root document, just before `<Scripts />`.
+ *
+ * `<Scripts />` is the anchor because every Start root has to render it — it is how the client
+ * bundle reaches the page — whatever the component around it is called (`RootDocument` as the
+ * route's `shellComponent` in the current template; `RootComponent` in older ones). A root without
+ * one is a shape we do not recognise, and a half-edited document is worse than a documented step.
+ */
+export declare function patchTanstackStartRoot(source: string, rootPath: string): SourcePatch;
+/**
+ * The recipe, for a root `patchTanstackStartRoot` would not edit.
  *
- * `__root.tsx` is the document. A static import of the SDK on that module SSRs and 500s, so `init`
- * does not write one. The connect has to be a client-only dynamic import inside `useEffect`, with
- * the pairing token the plugin inlines as `__RETICLE_TOKEN__`. Same judgement React Router already
- * makes about `app/entry.client.tsx`: a half-written document is worse than a documented manual step.
+ * The same two edits it makes, stated as edits: create the component, render it before
+ * `<Scripts />`. It used to say "add this useEffect to the App component", naming a component the
+ * current template does not have, and its snippet used `__RETICLE_TOKEN__` undeclared.
  */
 export declare function tanstackStartManual(port: number | undefined, projectId?: string, rootPath?: string): string;

package/dist/patch/tanstack-start.js

@@ -1,52 +1,141 @@
 /**
- * The TanStack Start connect recipe.
+ * The TanStack Start connect: a client-only component, rendered in the document the root route SSRs.
  *
- * Its own module because Start is the one framework whose document module `init` deliberately
- * refuses to write, so the recipe and the reasoning behind that refusal are a unit.
+ * Its own module because Start is the one framework whose document module is ALSO the server
+ * render, so what may be written into it — and what must stay out — is a unit.
  */
+import { posix } from 'node:path';
 import { UiLibrary } from '../detect/detect.js';
-import { connectArg, sdkImport, UNVERIFIED_TANSTACK_START_NOTE } from './snippets.js';
+import { connectArg, devModuleSpecifier, sdkImport, UNVERIFIED_TANSTACK_START_NOTE, } from './snippets.js';
+import { PatchKind } from './patch-kind.js';
+import { VITE_ENV_DEV_DECLARATION } from './vite-env-types.js';
 /** TanStack Start's document module — the file that SSRs `<html>`. */
 export const TANSTACK_START_ROOT_PATH = 'src/routes/__root.tsx';
+/** The component `init` writes, and renders in the root document. */
+const CONNECT_COMPONENT = 'ReticleConnect';
+const CONNECT_FILE_BASENAME = 'reticle-connect';
+/** `<Scripts />` — Start's own client-script outlet, which every root document has to render. */
+const SCRIPTS_OUTLET = /^([ \t]*)<Scripts\s*\/>/m;
 /**
- * The TanStack Start recipe, printed rather than written.
+ * Where the connect component goes: beside the `routes/` directory, never inside it — a file under
+ * `routes/` is a route to Start's file-based router.
+ */
+export function tanstackStartConnectPath(rootPath = TANSTACK_START_ROOT_PATH) {
+    return posix.join(posix.dirname(posix.dirname(rootPath)), `${CONNECT_FILE_BASENAME}.tsx`);
+}
+/**
+ * The connect component.
+ *
+ * A dynamic SDK import inside `useEffect`, because a static import on anything the root document
+ * imports is evaluated during the server render and 500s the page. Effects never run on the server.
+ * The pairing token is the one the Vite plugin inlines as `__RETICLE_TOKEN__`, declared here so the
+ * file passes the scaffold's strict `tsc` — the recipe this replaced used the name undeclared and
+ * failed with `TS2304: Cannot find name '__RETICLE_TOKEN__'`.
  *
- * `__root.tsx` is the document. A static import of the SDK on that module SSRs and 500s, so `init`
- * does not write one. The connect has to be a client-only dynamic import inside `useEffect`, with
- * the pairing token the plugin inlines as `__RETICLE_TOKEN__`. Same judgement React Router already
- * makes about `app/entry.client.tsx`: a half-written document is worse than a documented manual step.
+ * It also loads the app's `src/reticle-dev.ts` after connecting. Start is written `inject: false`,
+ * and the plugin's injected connect is the only other thing that imports that file, so without this
+ * line every store and capability registered there silently never ran.
  */
-export function tanstackStartManual(port, projectId, rootPath = TANSTACK_START_ROOT_PATH) {
+export function tanstackStartConnectFile(port, projectId, rootPath = TANSTACK_START_ROOT_PATH) {
     const sdk = sdkImport(UiLibrary.REACT);
     const base = connectArg(port, projectId);
     const fields = '' === base ? '' : `${base.slice(1, -1).trim()}, `;
-    const installLine = sdk.usesInstall
-        ? '        install();'
-        : '        // No React adapter here: the sensor has no install() to call.';
     const imports = sdk.usesInstall ? 'reticle, install' : 'reticle';
+    const installLine = sdk.usesInstall
+        ? '      install();'
+        : '      // No React adapter here: the sensor has no install() to call.';
+    const devModule = devModuleSpecifier(tanstackStartConnectPath(rootPath));
+    return `import { useEffect } from 'react';
+
+/**
+ * Dev-only: connect Reticle from the client. Start SSRs its own <html> and never sends Vite's
+ * index.html, so the plugin's injection cannot do it. Rendered once in the root document.
+ */
+export function ${CONNECT_COMPONENT}() {
+  useEffect(() => {
+    if (!import.meta.env.DEV) return;
+    // Inlined by @reticlehq/vite-plugin. The bridge refuses a connect without it, even on localhost.
+    const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
+    const root = typeof __RETICLE_ROOT__ !== 'undefined' ? __RETICLE_ROOT__ : '';
+    void import('${sdk.specifier}').then(({ ${imports} }) => {
+${installLine}
+      reticle.connect({
+        ${fields}...(token.length > 0 ? { token } : {}),
+        ...(root.length > 0 ? { root } : {}),
+      });
+      // Your stores and capabilities live here; nothing else loads this file under Start.
+      void import('${devModule}');
+    });
+  }, []);
+  return null;
+}
+
+declare const __RETICLE_TOKEN__: string | undefined;
+declare const __RETICLE_ROOT__: string | undefined;
+
+${VITE_ENV_DEV_DECLARATION}`;
+}
+/** The import the root document gets, relative to where it lives. */
+function connectImport(rootPath) {
+    const target = tanstackStartConnectPath(rootPath).replace(/\.tsx$/, '');
+    const rel = posix.relative(posix.dirname(rootPath), target);
+    return `import { ${CONNECT_COMPONENT} } from '${rel.startsWith('.') ? rel : `./${rel}`}';`;
+}
+/**
+ * Render the component in the root document, just before `<Scripts />`.
+ *
+ * `<Scripts />` is the anchor because every Start root has to render it — it is how the client
+ * bundle reaches the page — whatever the component around it is called (`RootDocument` as the
+ * route's `shellComponent` in the current template; `RootComponent` in older ones). A root without
+ * one is a shape we do not recognise, and a half-edited document is worse than a documented step.
+ */
+export function patchTanstackStartRoot(source, rootPath) {
+    if (source.includes(CONNECT_COMPONENT))
+        return { kind: PatchKind.ALREADY };
+    if (!rootPath.endsWith('.tsx')) {
+        return { kind: PatchKind.MANUAL, reason: `${rootPath} is not TypeScript` };
+    }
+    const outlet = SCRIPTS_OUTLET.exec(source);
+    if (null === outlet) {
+        return { kind: PatchKind.MANUAL, reason: `no <Scripts /> found in ${rootPath}` };
+    }
+    const indent = outlet[1] ?? '';
+    const rendered = source.replace(SCRIPTS_OUTLET, `${indent}<${CONNECT_COMPONENT} />\n$&`);
+    const lines = rendered.split('\n');
+    let lastImport = -1;
+    for (const [index, line] of lines.entries()) {
+        if (/^import\s/.test(line))
+            lastImport = index;
+    }
+    lines.splice(lastImport + 1, 0, connectImport(rootPath));
+    return { kind: PatchKind.APPLY, code: lines.join('\n') };
+}
+/**
+ * The recipe, for a root `patchTanstackStartRoot` would not edit.
+ *
+ * The same two edits it makes, stated as edits: create the component, render it before
+ * `<Scripts />`. It used to say "add this useEffect to the App component", naming a component the
+ * current template does not have, and its snippet used `__RETICLE_TOKEN__` undeclared.
+ */
+export function tanstackStartManual(port, projectId, rootPath = TANSTACK_START_ROOT_PATH) {
+    const component = tanstackStartConnectFile(port, projectId, rootPath)
+        .split('\n')
+        .map((line) => (0 === line.length ? line : `      ${line}`))
+        .join('\n');
     return `TanStack Start SSRs <html> from ${rootPath} (HeadContent / Scripts) and never sends Vite's
   index.html, so the plugin's connect injection never fires. Keep the plugin anyway, with
   reticle({ inject: false }): only the injection half is inapplicable, and the stamping half is
   what puts data-reticle-source on the JSX. Dropping the plugin because one of its two jobs did
   not apply is how Remix lost file:line.
 
-  Connect from a CLIENT-ONLY effect in ${rootPath}. A static SDK import on that module SSRs and
-  500s. Do not guard on window.location.hostname === 'localhost' — import.meta.env.DEV is the
-  correct guard, and it does not care what host you develop on.
-
-  Add this useEffect to the App component (import useEffect from react if it is not already there):
+  1. Create ${tanstackStartConnectPath(rootPath)}. It connects from a CLIENT-ONLY effect: a static SDK
+     import on anything the root document imports SSRs and 500s.
+     Do not guard on window.location.hostname === 'localhost' — import.meta.env.DEV is the correct
+     guard, and it does not care what host you develop on.
 
-      useEffect(() => {
-        if (import.meta.env.DEV) {
-          const token = typeof __RETICLE_TOKEN__ !== 'undefined' ? __RETICLE_TOKEN__ : '';
-          void import('${sdk.specifier}').then(({ ${imports} }) => {
-${installLine}
-            reticle.connect({
-              ${fields}...(token.length > 0 ? { token } : {}),
-            });
-          });
-        }
-      }, []);
+${component}
+  2. In ${rootPath}, add \`${connectImport(rootPath)}\` and render <${CONNECT_COMPONENT} /> in the
+     component that renders <html> (the route's shellComponent), just before <Scripts />.
 
   The plugin inlines __RETICLE_TOKEN__ when Vite resolves its config. Start the daemon BEFORE the
   dev server so that file exists; a server that started first froze an empty token and the page

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

@@ -14,5 +14,10 @@ export declare const VitePatchKind: {
 };
 export type VitePatchKind = PatchKind;
 type VitePatch = SourcePatch;
+/**
+ * A whole config for a plain Vite app that has none: Vite's defaults plus the plugin. Written out
+ * rather than patched from an empty one, because it is a file the person will open and read.
+ */
+export declare function newViteConfig(port?: number, captureBodies?: boolean, inject?: boolean, sourceMapping?: boolean): string;
 export declare function patchViteConfig(source: string, port?: number, captureBodies?: boolean, inject?: boolean, sourceMapping?: boolean): VitePatch;
 export {};

package/dist/patch/vite-config.js

@@ -98,6 +98,14 @@ function insertPluginsKey(source, call) {
         return multiline ? `${prefix}{\n${indent}${key}` : `${prefix}{ ${key}`;
     });
 }
+/**
+ * A whole config for a plain Vite app that has none: Vite's defaults plus the plugin. Written out
+ * rather than patched from an empty one, because it is a file the person will open and read.
+ */
+export function newViteConfig(port, captureBodies = false, inject = true, sourceMapping = true) {
+    const call = reticlePluginCall({ port, captureBodies, inject, sourceMapping });
+    return `import { defineConfig } from 'vite';\n${VITE_IMPORT}\n\nexport default defineConfig({\n  plugins: [${call}],\n});\n`;
+}
 export function patchViteConfig(source, port, captureBodies = false, inject = true, sourceMapping = true) {
     if (source.includes(RETICLE_MARKER)) {
         return { kind: VitePatchKind.ALREADY };

package/dist/patch/vite-env-types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The generated dev module must compile even when the host excludes `vite/client` ambient types.
+ * Keep the guard itself as `import.meta.env.DEV` so Vite can remove dev-only code from production.
+ *
+ * These declarations must merge with Vite's existing interfaces: DEV is mutable there, while env
+ * is readonly and refers to the named ImportMetaEnv interface. A triple-slash package reference
+ * would also require vite to be directly resolvable, which electron-vite-only projects need not have.
+ */
+export declare const VITE_ENV_DEV_DECLARATION = "// Supply the dev flag type when the host does not include vite/client.\n// These interfaces merge with vite/client when it is already present.\ndeclare global {\n  interface ImportMetaEnv {\n    DEV: boolean;\n  }\n  interface ImportMeta {\n    readonly env: ImportMetaEnv;\n  }\n}\n";

package/dist/patch/vite-env-types.js

@@ -0,0 +1,19 @@
+/**
+ * The generated dev module must compile even when the host excludes `vite/client` ambient types.
+ * Keep the guard itself as `import.meta.env.DEV` so Vite can remove dev-only code from production.
+ *
+ * These declarations must merge with Vite's existing interfaces: DEV is mutable there, while env
+ * is readonly and refers to the named ImportMetaEnv interface. A triple-slash package reference
+ * would also require vite to be directly resolvable, which electron-vite-only projects need not have.
+ */
+export const VITE_ENV_DEV_DECLARATION = `// Supply the dev flag type when the host does not include vite/client.
+// These interfaces merge with vite/client when it is already present.
+declare global {
+  interface ImportMetaEnv {
+    DEV: boolean;
+  }
+  interface ImportMeta {
+    readonly env: ImportMetaEnv;
+  }
+}
+`;

package/dist/patch/vite-owning-config.d.ts

@@ -21,5 +21,52 @@ export interface ViteOwningConfig {
     readonly defineCall: RegExp;
     /** The SDK package this framework's connect imports, declared so Vite pre-bundles it. */
     readonly sdkSpecifier: string;
+    /**
+     * When true (default), inline the pairing token and project root via `vite.define`.
+     *
+     * Nuxt still needs this: its client plugin reads `__RETICLE_TOKEN__` from the define. Astro 7.2+
+     * no longer substitutes `define` into the client pipeline (#1008), so Astro sets this false and
+     * puts the token on a frontmatter `<meta>` instead.
+     */
+    readonly defineToken?: boolean;
+    /**
+     * Present once this patch has applied. Defaults to `__RETICLE_TOKEN__`, which is what the define
+     * path writes. Astro's path never writes that name into the config, so it supplies its own.
+     */
+    readonly alreadyMarker?: string;
+    /**
+     * The installed Vite's major (see `installedViteMajor`), or null when nothing on disk said.
+     *
+     * Decides whether the dep-optimizer target is written at all. Vite 7 moved the optimizer to
+     * rolldown and deprecated `optimizeDeps.esbuildOptions`: on Nuxt 4.5 / Vite 8 the key printed a
+     * deprecation warning on every dev start and build. The target exists for esbuild, which cannot
+     * lower some of the SDK's syntax to Vite's older default; rolldown has no such gap, so on 7+ there
+     * is nothing to write under either key.
+     */
+    readonly viteMajor?: number | null | undefined;
 }
 export declare function patchViteOwningConfig(source: string, config: ViteOwningConfig): SourcePatch;
+/**
+ * The major version of the Vite this app will actually run, read from disk.
+ *
+ * Needed by the configs `init` patches for frameworks that own their Vite instance (Nuxt, Astro):
+ * Vite 7 moved the dep optimizer to rolldown and deprecated `optimizeDeps.esbuildOptions`, so the
+ * key `init` wrote printed a deprecation warning on every dev start and build there. The Vite
+ * plugin answers the same question for itself (`optimizerOptionsKey` in @reticlehq/vite-plugin),
+ * but these frameworks never load the plugin.
+ *
+ * Nuxt and Astro do not list `vite` in the app's package.json — it comes with the framework — so the
+ * declared range is the last resort, after the hoisted package and pnpm's store. Null when none
+ * says: the caller keeps the older key, as the plugin does, because a deprecation notice is a much
+ * smaller failure than an option the installed Vite has never heard of.
+ */
+interface ViteReader {
+    readFile(relPath: string): string | null;
+    listDirs(relPath: string): readonly string[];
+}
+interface DeclaredDeps {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+export declare function installedViteMajor(io: ViteReader, pkg: DeclaredDeps): number | null;
+export {};