@reticlehq/init 3.2.0 → 3.4.0

package/dist/patch/remix.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Remix v2's client entry, and the one honest answer for the classic compiler.
+ *
+ * Remix on Vite is React Router framework mode under its old name: it SSRs its own HTML, so the
+ * Vite plugin's `index.html` injection never reaches the page, and the connect has to come from
+ * `app/entry.client.tsx` — the same line, the same file, verified by hand to connect.
+ */
+/**
+ * The client entry `init` writes when a Remix app has none.
+ *
+ * Like React Router's, `app/entry.client.tsx` is an OVERRIDE of a default Remix supplies — it only
+ * exists once somebody runs `remix reveal`. So the written file has to hydrate as well as connect:
+ * one holding only our import would replace the default with an app that renders nothing. This is
+ * Remix v2's own default entry with one line added.
+ */
+export declare function remixEntryFile(): string;
+/**
+ * The classic compiler has no Vite, so nothing serves `/@reticle-connect` and nothing stamps source.
+ *
+ * Said plainly and left as a ⚠ rather than papered over: writing the entry line here would import a
+ * module no dev server serves, and the app would log a failed import on every page load instead of
+ * connecting.
+ */
+export declare const REMIX_CLASSIC_MANUAL = "This is Remix on the classic compiler (remix.config.js, no Vite), and Reticle cannot wire it:\nthe connect module and the source stamping both come from @reticlehq/vite-plugin, and this build\nnever runs Vite.\n\n  \u2022 Recommended: move to Remix's Vite plugin (https://remix.run/docs/en/main/guides/vite), or on to\n    React Router v7+ framework mode, then re-run `reticle init` \u2014 both are wired automatically.\n  \u2022 Or connect by hand from app/entry.client.tsx, dev-only, through the React kit init installed:\n\n      if (process.env.NODE_ENV === 'development') {\n        void import('@reticlehq/react').then(({ reticle, install }) => {\n          install();\n          reticle.connect({ token: '<the contents of ~/.reticle/pairing-token>' });\n        });\n      }\n\n    The token is per-machine: keep it out of version control.";

package/dist/patch/remix.js

@@ -0,0 +1,59 @@
+/**
+ * Remix v2's client entry, and the one honest answer for the classic compiler.
+ *
+ * Remix on Vite is React Router framework mode under its old name: it SSRs its own HTML, so the
+ * Vite plugin's `index.html` injection never reaches the page, and the connect has to come from
+ * `app/entry.client.tsx` — the same line, the same file, verified by hand to connect.
+ */
+import { REACT_ROUTER_CONNECT_LINE } from './snippets.js';
+/**
+ * The client entry `init` writes when a Remix app has none.
+ *
+ * Like React Router's, `app/entry.client.tsx` is an OVERRIDE of a default Remix supplies — it only
+ * exists once somebody runs `remix reveal`. So the written file has to hydrate as well as connect:
+ * one holding only our import would replace the default with an app that renders nothing. This is
+ * Remix v2's own default entry with one line added.
+ */
+export function remixEntryFile() {
+    return `import { RemixBrowser } from '@remix-run/react';
+import { startTransition, StrictMode } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+
+// Dev-only: Remix renders HTML through its own request handler, so the Vite plugin's index.html
+// injection never fires and the connect script never reaches the page. The plugin is still doing
+// the other half of the job — it stamps data-reticle-source, which puts file:line on every verdict.
+${REACT_ROUTER_CONNECT_LINE}
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <RemixBrowser />
+    </StrictMode>,
+  );
+});
+`;
+}
+/**
+ * The classic compiler has no Vite, so nothing serves `/@reticle-connect` and nothing stamps source.
+ *
+ * Said plainly and left as a ⚠ rather than papered over: writing the entry line here would import a
+ * module no dev server serves, and the app would log a failed import on every page load instead of
+ * connecting.
+ */
+export const REMIX_CLASSIC_MANUAL = `This is Remix on the classic compiler (remix.config.js, no Vite), and Reticle cannot wire it:
+the connect module and the source stamping both come from @reticlehq/vite-plugin, and this build
+never runs Vite.
+
+  • Recommended: move to Remix's Vite plugin (https://remix.run/docs/en/main/guides/vite), or on to
+    React Router v7+ framework mode, then re-run \`reticle init\` — both are wired automatically.
+  • Or connect by hand from app/entry.client.tsx, dev-only, through the React kit init installed:
+
+      if (process.env.NODE_ENV === 'development') {
+        void import('@reticlehq/react').then(({ reticle, install }) => {
+          install();
+          reticle.connect({ token: '<the contents of ~/.reticle/pairing-token>' });
+        });
+      }
+
+    The token is per-machine: keep it out of version control.`;

package/dist/patch/snippets.d.ts

@@ -2,8 +2,34 @@
  * Generated file contents and copy-paste snippets for `reticle init`. Kept as named constants/builders
  * so the runner never inlines free strings.
  */
-import { UiLibrary } from '../detect/detect.js';
+import { Framework, UiLibrary } from '../detect/detect.js';
 import type { FoundStore } from '../detect/capabilities.js';
+/**
+ * The SDK as one import a plain page can actually resolve.
+ *
+ * `init` used to tell static-HTML users that a page with no build step could not load the SDK, and
+ * to go and stand up a bundler. That is true of a BARE specifier and false of a URL, and the
+ * difference was the whole road for every server-rendered app we hear from: FastAPI, Flask, Django,
+ * Streamlit, Rails. Proven end to end before this shipped, on a page served by `python3 -m
+ * http.server`: a session connected, a snapshot returned, and two act_and_wait calls came back
+ * `verified: "yes"`.
+ *
+ * jsDelivr rather than esm.sh, measured: a third of the requests and a third of the bytes for the
+ * same result. `/+esm` is what makes it work, and the bare package URL does NOT: every file in
+ * `dist` still carries bare workspace specifiers such as `@reticlehq/core`, so an unbundled entry
+ * point dies on the first import. That is also why adding `unpkg`/`jsdelivr` fields to package.json
+ * would not help.
+ *
+ * PINNED to this server's version on purpose. A floating import upgrades the page SDK underneath a
+ * daemon that did not move, which is `version_skew` arriving by a route nothing checks.
+ */
+/**
+ * Where a generated file sends someone to learn `registerStore`. A URL, not a path into
+ * `node_modules/@reticlehq/server`: the server is never installed into the app, so the path the
+ * generated files used to name did not exist in any project they were written into.
+ */
+export declare const STATE_DOCS_URL = "https://docs.reticle.sh/state-management";
+export declare const CDN_SDK_URL: string;
 /**
  * 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.
@@ -22,6 +48,7 @@ export declare function connectArg(port: number | undefined, projectId?: string)
  * one that does hold a token.
  */
 export declare function connectArgWithToken(port: number | undefined, projectId: string | undefined, pairingToken: string | undefined): string;
+export declare function usesReactKit(uiLibrary: UiLibrary, framework?: Framework): boolean;
 /**
  * Which SDK package the GENERATED code should import, and whether `install()` applies.
  *
@@ -33,7 +60,7 @@ export declare function connectArgWithToken(port: number | undefined, projectId:
  * `install()` is the React adapter's, not the sensor's: `@reticlehq/browser` exports `reticle` and no
  * `install`, so swapping the specifier alone would trade a missing module for a missing export.
  */
-export declare function sdkImport(uiLibrary: UiLibrary): {
+export declare function sdkImport(uiLibrary: UiLibrary, framework?: Framework): {
     specifier: string;
     usesInstall: boolean;
 };
@@ -42,8 +69,11 @@ export declare function viteManual(port: number | undefined, uiLibrary?: UiLibra
 /**
  * The electron-vite recipe: the plugin belongs in `renderer`, never in `main` or `preload`.
  *
- * `desktop: true` is load-bearing. Without it the plugin is serve-only, so a packaged renderer
- * (a production build with no dev server) ships with no connect() at all.
+ * `desktop: true` is load-bearing: it injects connect() into the entry module and passes
+ * `allowInProduction`, because a packaged renderer has no dev server and reports
+ * `NODE_ENV=production`, so without it the SDK's production backstop refuses to start. It does not
+ * instrument a release — a production-mode `electron-vite build` is stubbed like a web bundle — so
+ * a packaged renderer that should be driven is built with `--mode development`.
  */
 export declare function electronViteManual(port: number | undefined, uiLibrary?: UiLibrary): string;
 /** Next.js config wrap — always printed (we never auto-rewrite next.config). */
@@ -89,9 +119,14 @@ export declare function registerCapabilitiesCall(testids: readonly string[], ind
  * 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[], found?: readonly FoundStore[], uiLibrary?: UiLibrary): string;
+export declare function viteDevModuleFile(testids: readonly string[], stores: readonly string[], found?: readonly FoundStore[], uiLibrary?: UiLibrary, framework?: Framework): string;
 /** Where that module goes. Matches @reticlehq/vite-plugin's convention list. */
 export declare const VITE_DEV_MODULE_PATH = "src/reticle-dev.ts";
+/**
+ * The dev module as a relative import from `fromFile` — for the frameworks that connect themselves
+ * and so have to load it themselves (see svelteKitHooksFile, tanstackStartConnectFile).
+ */
+export declare function devModuleSpecifier(fromFile: string): string;
 /**
  * electron-vite's renderer Vite root is `src/renderer`, so the plugin looks for
  * `src/renderer/src/reticle-dev.ts` — not the package-root path a plain Vite app uses.
@@ -137,7 +172,7 @@ export declare function streamlitPageSnippet(connectArgLiteral: string): string;
  * `<head>`, so the SDK sees a parsed document.
  */
 export declare function djangoMiddlewareSnippet(connectArgLiteral: string): string;
-export declare function htmlManual(port: number | undefined, projectId?: string, pairingToken?: string): string;
+export declare function htmlManual(port: number | undefined, projectId?: string, pairingToken?: string, uiLibrary?: UiLibrary): string;
 export declare const NEXT_RETICLE_DEV_PATH = "app/reticle-dev.tsx";
 export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
 /**
@@ -146,9 +181,9 @@ export declare const SVELTEKIT_HOOKS_PATH = "src/hooks.client.ts";
  * component names and source mapping do not, and no CI gate covers this stack. Saying so beats
  * reporting all-green.
  */
-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.";
-export declare const UNVERIFIED_TANSTACK_START_NOTE = "Reticle has no TanStack Start 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 client effect does not register a session, please open an issue.";
+export declare function unverifiedUiLibraryNote(library: string, installGated?: boolean): string;
+export declare const SVELTEKIT_SETUP_GATED_NOTE = "The install gate scaffolds a SvelteKit app on every release and requires this hook to connect a session, so the wiring is proven; driving flows on SvelteKit to a verdict is not. If the hook does not register a session, please open an issue.";
+export declare const UNVERIFIED_TANSTACK_START_NOTE = "Reticle has no TanStack Start 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. Gated today: Vite (React, Vue), Next.js, Nuxt, React Router, Remix, Astro, SvelteKit, Create React App and Angular. If the client effect does not register a session, please open an issue.";
 /**
  * Printed when init detects react-three-fiber. Reticle's model is DOM + store + network; a WebGL
  * canvas is none of those. Without this line, init succeeds, sessions connect, and surrounding UI
@@ -181,8 +216,19 @@ export declare const WEBPACK4_REACT_SCRIPTS_MAJOR = 5;
 export declare function webpack4TranspileNote(reactScriptsMajor: number): string;
 /** React Router's client-entry override point, in framework mode. */
 export declare const REACT_ROUTER_ENTRY_PATH = "app/entry.client.tsx";
-/** The one line that puts Reticle in a React Router client entry. */
-export declare const REACT_ROUTER_CONNECT_LINE = "if (import.meta.env.DEV) void import('/@reticle-connect');";
+/**
+ * The one line that puts Reticle in a React Router client entry — and in a Remix one.
+ *
+ * The specifier is BUILT, not written as a literal. `import('/@reticle-connect')` is a module only
+ * the Vite dev server can answer, so `tsc` cannot resolve it: a fresh framework-mode scaffold went
+ * red on `npm run typecheck` (`TS2307: Cannot find module '/@reticle-connect'`) the moment `init`
+ * wrote it. A computed specifier is typed `Promise<any>` and never resolved, so no declaration, no
+ * suppression comment and no tsconfig edit is needed. The browser still asks the dev server for the
+ * same URL, which the plugin serves; `BASE_URL` keeps it right under a non-root `base`. `@vite-ignore`
+ * is Vite's own marker for a dynamic import it should not try to analyse, not a lint suppression. In
+ * a production build `import.meta.env.DEV` is false and the whole line is dropped.
+ */
+export declare const REACT_ROUTER_CONNECT_LINE = "if (import.meta.env.DEV) void import(/* @vite-ignore */ `${import.meta.env.BASE_URL}@reticle-connect`);";
 /**
  * The client entry `init` writes when React Router framework mode has none.
  *
@@ -204,52 +250,7 @@ export declare function reactRouterEntryFile(): string;
  * still be evaluated first, and this is a side-effect import.
  */
 export declare function reactRouterEntryPatch(source: string): string | null;
-/** Where a Nuxt dev-only client plugin belongs. `.client` keeps it out of SSR; Nuxt auto-registers it. */
-export declare const NUXT_PLUGIN_PATH = "app/plugins/reticle.client.ts";
-/**
- * The plugin directory Nuxt actually scans, which is not the same on 3 and 4.
- *
- * Nuxt 4's default `srcDir` is `app/`, so plugins live in `app/plugins/`. Nuxt 3's is the project
- * root, so they live in `plugins/`. Writing to the wrong one is the silent failure this whole change
- * exists to remove: the file is on disk, `init` reports it green, Nuxt never scans that directory,
- * and no plugin is ever registered. Keyed on whether the app HAS an `app/` directory, which is the
- * same signal Nuxt itself uses to pick its srcDir.
- */
-export declare function nuxtPluginPath(hasAppDir: boolean): string;
-/**
- * The dev-only Nuxt client plugin `init` writes.
- *
- * Every trap in it is one somebody actually hit. `import.meta.dev` rather than a hostname check: the
- * reported failure was a snippet guarded on `window.location.hostname === 'localhost'`, which is
- * false on any hosts-file alias or LAN address and throws during SSR, so the connect never ran with
- * no error and no log line. `.client.ts` rather than an SSR guard, because that suffix is what keeps
- * this out of the server bundle. `@reticlehq/browser` rather than the React kit, because installing
- * a package named `@reticlehq/react` into a Vue codebase is the single thing most likely to make
- * somebody abandon the setup.
- *
- * The token is inlined by `nuxt.config`'s `vite.define` (see nuxt-patch.ts). The bridge requires it
- * even on localhost, and nothing in a browser can read the file it lives in.
- */
-export declare function nuxtPluginFile(port: number | undefined, projectId?: string, testids?: readonly string[]): string;
-/**
- * Said as its own NOTICE beside the write, not inside it: a running dev server does not pick up a
- * new plugin, and off localhost the connect needs two more arguments.
- *
- * A ✓ line is one SKILL.md tells the reader to skip, so a caveat carried on the ✓ is a caveat nobody
- * reads — and both of these end with an app that boots, looks correct and never pairs.
- */
-export declare const NUXT_PLUGIN_NOTICE: string;
-/**
- * The Nuxt recipe, written out in full because each trap in it is one a Nuxt 4 app actually hit:
- * a Vue codebase classified as `html` and handed `@reticlehq/react`, a connect guarded on
- * `window.location.hostname === 'localhost'` (false on any hosts-file alias, and `window` does not
- * exist during SSR), and a running dev server that never picked up the new plugin.
- *
- * So: `import.meta.dev` instead of a hostname check, `.client.ts` instead of an SSR guard, the
- * framework-neutral sensor instead of the React kit, the non-localhost flag named up front, and the
- * restart said out loud.
- */
-export declare function nuxtManual(port: number | undefined, projectId?: string): string;
+export { nuxtPluginPath, nuxtPluginFile, NUXT_PLUGIN_NOTICE, nuxtManual } from './nuxt-snippets.js';
 /**
  * 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).