@sumly/wizard 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Primož Cigoj s.p.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @sumly/wizard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Adds [Sumly](https://sumly.dev) to your project in one command:
+
+```sh
+npx @sumly/wizard --key sl_…
+```
+
+It finds how the project is built, shows the one change Sumly needs as a diff, writes it when you say yes, and waits until the first visit arrives. Your project's key (`sl_…`) is on Sumly's Visitors page; leave `--key` out and the wizard asks for it and opens that page.
+
+| Project | What changes |
+|---|---|
+| Next.js, App Router | `<Script>` in `app/layout.tsx` |
+| Next.js, Pages Router | `<Script>` in `pages/_app.tsx` (made if missing) |
+| React or Vue with Vite, Create React App, Angular | the line in `index.html` |
+| Nuxt | `app.head.script` in `nuxt.config.ts` |
+| SvelteKit | the line in `src/app.html` |
+| Astro | the line, `is:inline`, in each layout with its own `<head>` |
+| React Router (framework mode), Remix | the line after `<Links />` in `app/root.tsx` |
+| Laravel | the line in each Blade layout with its own `<head>` (not e-mails) |
+| Plain HTML | the line in every page |
+| React Native, Expo | `@sumly/sdk`: `Sumly.init` at the top of `App.tsx` or `app/_layout.tsx`, screens, and taps with `--autocapture` |
+
+Anything else gets the line and the guide for its platform. A file that already has Sumly is left alone, apart from its key and `data-autocapture`, so running it twice changes nothing. Nothing outside the files in the diff is touched, and nothing is written before you say yes.
+
+```
+--key sl_…          your project's public key; asked for when left out
+--dir <folder>      the project (default: this folder)
+--autocapture       count every click, or every tap in an app, without marking anything
+--no-autocapture    leave clicks to the ones you mark
+--file <path>       only this file (repeat for more)
+-y, --yes           no questions: write the change and install what it needs
+--dry-run           show the change and stop
+--no-install        do not install packages (apps)
+--no-wait           do not wait for the first visit
+--wait <minutes>    how long to wait for it (default 10)
+```
+
+The key it uses is the public one that is in your site's HTML anyway: it can only send visits. The wizard reads your project's name and its line from `https://sumly.dev/api/v1/install` and sends nothing else.
+
+No dependencies, Node 18 or later. MIT.

package/bin.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from './src/cli.mjs';
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@sumly/wizard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Add Sumly to your project in one command: finds the framework, shows the one change, writes it when you say yes, and waits for the first visit.",
+  "license": "MIT",
+  "homepage": "https://sumly.dev/install",
+  "bugs": "https://sumly.dev/support",
+  "author": "Primož Cigoj s.p. (https://sumly.dev)",
+  "keywords": ["sumly", "analytics", "wizard", "setup", "nextjs", "nuxt", "astro", "sveltekit", "laravel", "react-native", "expo"],
+  "type": "module",
+  "bin": { "sumly-wizard": "bin.mjs" },
+  "files": ["bin.mjs", "src", "README.md", "LICENSE"],
+  "engines": { "node": ">=18.17" },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm test"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,343 @@
+// npx @sumly/wizard: finds the framework, shows the one change Sumly needs, writes it when the person says
+// yes, and waits for the first visit. No AI, no account on the command line: the project's public key only.
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { dirname, join, resolve } from 'node:path';
+import { detect } from './detect.mjs';
+import { unified } from './diff.mjs';
+import { plan } from './edits.mjs';
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const KEY = /^sl_[A-Za-z0-9]{6,64}$/;
+
+const HELP = `Sumly wizard ${VERSION}: adds Sumly to your project in one go.
+
+  npx @sumly/wizard --key sl_…
+
+  --key sl_…          your project's public key (Sumly › Visitors); asked for when left out
+  --dir <folder>      the project (default: this folder)
+  --autocapture       count every click, or every tap in an app, without marking anything
+  --no-autocapture    leave clicks to the ones you mark
+  --file <path>       only this file (repeat for more), when the project has several pages
+  -y, --yes           no questions: write the change and install what it needs
+  --dry-run           show the change and stop
+  --no-install        do not install packages (apps)
+  --no-wait           do not wait for the first visit
+  --wait <minutes>    how long to wait for it (default 10)
+  --host <url>        another Sumly address (default https://sumly.dev)
+`;
+
+/** @returns {Record<string, any>} */
+export function parse(argv) {
+  const o = { files: [], wait: 10 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const [flag, inline] = a.startsWith('--') && a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, undefined];
+    const value = () => inline ?? argv[++i];
+    switch (flag) {
+      case '--key': o.key = value(); break;
+      case '--dir': o.dir = value(); break;
+      case '--host': o.host = value(); break;
+      case '--file': o.files.push(value()); break;
+      case '--wait': o.wait = Number(value()); break;
+      case '--autocapture': o.autocapture = true; break;
+      case '--no-autocapture': o.autocapture = false; break;
+      case '-y':
+      case '--yes': o.yes = true; break;
+      case '--dry-run': o.dryRun = true; break;
+      case '--no-install': o.install = false; break;
+      case '--no-wait': o.wait = 0; break;
+      case '-h':
+      case '--help': o.help = true; break;
+      case '-v':
+      case '--version': o.version = true; break;
+      default:
+        if (KEY.test(a)) o.key = a;
+        else o.unknown = a;
+    }
+  }
+  return o;
+}
+
+/** Questions on any input: a pasted answer, a pipe, or nothing (then the default). */
+function prompter(input, output) {
+  const rl = createInterface({ input, terminal: false });
+  const lines = [];
+  const waiting = [];
+  let closed = false;
+  // A piped answer is not echoed by a terminal, so the transcript shows it here.
+  const echo = (line) => {
+    if (!input.isTTY) output.write(`${line}\n`);
+    return line;
+  };
+  rl.on('line', (line) => (waiting.length ? waiting.shift()(echo(line)) : lines.push(line)));
+  rl.on('close', () => {
+    closed = true;
+    while (waiting.length) waiting.shift()(null);
+  });
+  const ask = (question) => {
+    output.write(question);
+    if (lines.length) return Promise.resolve(echo(lines.shift()));
+    if (closed) {
+      output.write('\n');
+      return Promise.resolve(null);
+    }
+    return new Promise((r) => waiting.push(r));
+  };
+  return {
+    ask,
+    async yes(question, fallback) {
+      const answer = (await ask(`${question} ${fallback ? '(Y/n)' : '(y/N)'} `))?.trim().toLowerCase();
+      return !answer ? fallback : answer.startsWith('y');
+    },
+    close: () => rl.close(),
+  };
+}
+
+/** The project Sumly knows by this key: its name, its line and the last visit it had. */
+export async function project(host, key, fetcher = fetch) {
+  try {
+    const response = await fetcher(`${host}/api/v1/install`, {
+      headers: { Authorization: `Bearer ${key}`, Accept: 'application/json', 'User-Agent': `sumly-wizard/${VERSION}` },
+      signal: AbortSignal.timeout(15000),
+    });
+    const body = await response.json().catch(() => ({}));
+    return { status: response.status, body };
+  } catch {
+    return { status: 0, body: {} };
+  }
+}
+
+function openBrowser(url) {
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+  try {
+    spawn(cmd, args, { detached: true, stdio: 'ignore' }).on('error', () => {}).unref();
+  } catch {
+    // The address is printed too.
+  }
+}
+
+/** The command that adds packages with the project's own package manager. */
+export function installCommand(project, packages) {
+  const expo = Object.prototype.hasOwnProperty.call(project.deps, 'expo');
+  if (expo) return ['npx', ['expo', 'install', ...packages]];
+  return {
+    pnpm: ['pnpm', ['add', ...packages]],
+    yarn: ['yarn', ['add', ...packages]],
+    bun: ['bun', ['add', ...packages]],
+    npm: ['npm', ['install', ...packages]],
+  }[project.pm];
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * @param {string[]} argv
+ * @param {{ cwd?: string, stdin?: NodeJS.ReadableStream, stdout?: NodeJS.WritableStream, fetch?: typeof fetch, env?: Record<string, string|undefined>, run?: (cmd: string, args: string[], cwd: string) => number, poll?: number, open?: (url: string) => void }} io
+ * @returns {Promise<number>} the exit code
+ */
+export async function run(argv, io = {}) {
+  const out = io.stdout ?? process.stdout;
+  const env = io.env ?? process.env;
+  const o = parse(argv);
+  const color = Boolean(out.isTTY) && !env.NO_COLOR;
+  const paint = (code) => (text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+  const bold = paint('1');
+  const dim = paint('2');
+  const green = paint('32');
+  const yellow = paint('33');
+  const say = (line = '') => out.write(line + '\n');
+
+  if (o.help) {
+    out.write(HELP);
+    return 0;
+  }
+  if (o.version) {
+    say(VERSION);
+    return 0;
+  }
+  if (o.unknown) {
+    say(`Unknown option: ${o.unknown}\n`);
+    out.write(HELP);
+    return 2;
+  }
+
+  const host = (o.host ?? env.SUMLY_HOST ?? 'https://sumly.dev').replace(/\/+$/, '');
+  const dir = resolve(io.cwd ?? process.cwd(), o.dir ?? '.');
+  const prompt = prompter(io.stdin ?? process.stdin, out);
+  const interactive = !o.yes;
+
+  try {
+    say(`${bold('Sumly')} ${dim(`wizard ${VERSION}`)}`);
+    say();
+
+    const found = detect(dir);
+    say(`${green('◆')} Found ${bold(found.name)}${found.files.length ? dim(` · ${found.files.slice(0, 3).join(', ')}${found.files.length > 3 ? ` and ${found.files.length - 3} more` : ''}`) : found.create ? dim(` · ${found.create} (new)`) : ''}`);
+    const guide = `${host}/install${found.guide ? `/${found.guide}` : ''}`;
+
+    let key = o.key ?? env.SUMLY_KEY;
+    while (!key) {
+      if (!interactive) {
+        say('No key. Pass --key sl_… (Sumly › Visitors shows it).');
+        return 2;
+      }
+      const answer = await prompt.ask(`${green('◆')} Your project's key (sl_…). Press Enter to open Sumly and copy it: `);
+      if (answer === null) {
+        say('No key. Pass --key sl_… (Sumly › Visitors shows it).');
+        return 2;
+      }
+      if (answer.trim() === '') {
+        const url = `${host}/visitors?install=1#install`;
+        (io.open ?? openBrowser)(url);
+        say(dim(`  Opened ${url}`));
+        continue;
+      }
+      key = answer.trim();
+    }
+    if (!KEY.test(key)) {
+      say(`That is not a project key: it starts with sl_. Sumly › Visitors shows it.`);
+      return 2;
+    }
+
+    const known = await project(host, key, io.fetch);
+    if (known.status === 401) {
+      say(`Sumly does not know the key ${key}. Copy it again from Sumly › Visitors.`);
+      return 1;
+    }
+    if (known.status !== 200 && known.status !== 0) {
+      say(known.body.error ?? `Sumly answered ${known.status}.`);
+      return 1;
+    }
+    const info = known.status === 200 ? known.body : null;
+    if (info) say(`${green('◆')} Project ${bold(info.project)}${info.domain ? dim(` · ${info.domain}`) : ''}`);
+    else say(`${yellow('▲')} Could not reach ${host}: the line uses the usual address, and the wizard will not wait for the first visit.`);
+
+    if (found.kind === 'none') {
+      say();
+      say(found.id === 'unknown' ? 'The wizard does not know how this project is built yet.' : `The wizard did not find the file Sumly goes into in this ${found.name} project.`);
+      if (found.id === 'expo' || found.id === 'react-native') say(`Add the SDK where the app starts:\n\n  import { Sumly } from '@sumly/sdk/react-native';\n  Sumly.init({ siteKey: '${key}' });\n`);
+      else say(`Add this line to the <head> every page shares:\n\n  <script defer src="${info?.script ?? `${host}/s.js`}" data-site="${key}"></script>\n`);
+      say(`Step by step: ${guide}`);
+      return 0;
+    }
+
+    const app = found.kind === 'sdk';
+    let autocapture = o.autocapture;
+    if (autocapture === undefined) {
+      autocapture = interactive
+        ? await prompt.yes(`${green('◆')} Count every ${app ? 'tap' : 'click'} by itself, without marking buttons?`, Boolean(info?.autocapture))
+        : Boolean(info?.autocapture);
+    }
+
+    const has = (name) => Object.prototype.hasOwnProperty.call(found.deps, name);
+    let storage = false;
+    if (app) {
+      storage = has('@react-native-async-storage/async-storage') || !interactive || (await prompt.yes(`${green('◆')} Keep unsent screens across restarts with AsyncStorage (adds the package)?`, true));
+    }
+
+    let files = o.files.map((f) => f.replace(/\\/g, '/').replace(/^\.\//, ''));
+    if (!files.length && found.files.length > 1 && interactive) {
+      say(`  ${found.files.length} files have their own <head>, and each page needs the line:`);
+      for (const f of found.files) say(dim(`    ${f}`));
+      if (!(await prompt.yes(`${green('◆')} Add it to all of them?`, true))) {
+        for (const f of found.files) if (await prompt.yes(`  ${f}?`, true)) files.push(f);
+        if (!files.length) {
+          say('Nothing picked, nothing changed.');
+          return 0;
+        }
+      }
+    }
+
+    const options = { key, src: info?.script ?? `${host}/s.js`, domains: info?.domains ?? null, autocapture, storage, files };
+    const result = plan(dir, found, options);
+
+    say();
+    for (const f of result.already) say(`${green('✓')} ${f} already has Sumly`);
+    for (const p of result.problems) say(`${yellow('▲')} ${p.file}: ${p.reason}. Step by step: ${guide}`);
+    for (const c of result.changes) {
+      say(unified(c.file, c.before, c.after, { color }));
+      say();
+    }
+
+    if (result.changes.length && o.dryRun) {
+      say(dim('Dry run: nothing written.'));
+      return 0;
+    }
+    if (result.changes.length) {
+      const write = !interactive || (await prompt.yes(`${green('◆')} Write ${result.changes.length === 1 ? 'this change' : `these ${result.changes.length} changes`}?`, true));
+      if (!write) {
+        say('Nothing written.');
+        return 0;
+      }
+      for (const c of result.changes) {
+        mkdirSync(dirname(join(dir, c.file)), { recursive: true });
+        writeFileSync(join(dir, c.file), c.after);
+        say(`${green('✓')} Wrote ${c.file}`);
+      }
+    } else if (!result.problems.length) {
+      say(`${green('✓')} Nothing to change.`);
+    }
+    if (result.problems.length && !result.changes.length && !result.already.length) return 1;
+
+    if (app && o.install !== false && !o.dryRun) {
+      const missing = ['@sumly/sdk', ...(storage ? ['@react-native-async-storage/async-storage'] : [])].filter((p) => !has(p));
+      if (missing.length) {
+        const [cmd, args] = installCommand(found, missing);
+        const line = `${cmd} ${args.join(' ')}`;
+        if (!interactive || (await prompt.yes(`${green('◆')} Run ${bold(line)}?`, true))) {
+          const code = (io.run ?? ((c, a, cwd) => spawnSync(c, a, { cwd, stdio: 'inherit', shell: process.platform === 'win32' }).status ?? 1))(cmd, args, dir);
+          if (code !== 0) say(`${yellow('▲')} That did not finish. Run it yourself: ${line}`);
+        } else {
+          say(`  Run it yourself: ${line}`);
+        }
+        if (missing.includes('@react-native-async-storage/async-storage') && !has('expo')) say(dim('  Then, for iOS: cd ios && pod install'));
+      }
+    }
+
+    for (const n of result.notes) say(`${yellow('▲')} ${n}`);
+    if (autocapture && info && info.autocapture === false) {
+      say(`${yellow('▲')} Turn on ${bold('Every click, without marking')} for ${info.project} in Sumly, or the ${app ? 'taps' : 'clicks'} are not kept: ${info.settings_url ?? `${host}/accounts`}`);
+    }
+    if (!app && interactive) {
+      if (await prompt.yes(`${green('◆')} Do you take payments with Stripe?`, false)) {
+        say('  Payment Links, pricing tables and buy buttons on the page carry the visitor into checkout by themselves.');
+        say(`  A Checkout Session your server makes needs metadata: { sumly_visitor_id: <the sumly_vid cookie> }. How: ${guide}#checkout`);
+        say(`  Then connect Stripe in Sumly with a read-only key: ${host}/accounts`);
+      }
+    }
+
+    prompt.close();
+    if (!info || o.wait <= 0 || o.dryRun) {
+      say();
+      say(`Done. Deploy, open the ${app ? 'app' : 'site'}, and the visit shows in Sumly: ${host}/visitors`);
+      return 0;
+    }
+
+    say();
+    say(app ? 'Now run the app (a dev build is fine) and open a screen.' : 'Now deploy, or start your dev server (localhost counts too), and open the site.');
+    const started = Date.now();
+    const seen = (body) => body.last_seen_at && Date.parse(body.last_seen_at) >= started - 2000;
+    if (info.last_seen_at) say(dim(`  ${info.project} last had a visit ${new Date(info.last_seen_at).toLocaleString()}; waiting for a new one.`));
+    const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    const waiting = `Waiting for the first ${app ? 'screen' : 'visit'}… (it can take a minute; Ctrl+C to stop)`;
+    if (!out.isTTY) say(waiting);
+    const every = io.poll ?? 3000;
+    for (let tick = 0; Date.now() - started < o.wait * 60_000; tick++) {
+      if (out.isTTY) out.write(`\r${frames[tick % frames.length]} ${waiting}`);
+      const now = await project(host, key, io.fetch);
+      if (now.status === 200 && seen(now.body)) {
+        if (out.isTTY) out.write('\r\x1b[K');
+        say(`${green('✓')} Got it. ${now.body.project} is receiving ${app ? 'screens' : 'visits'}: ${now.body.visitors_url ?? `${host}/visitors`}`);
+        return 0;
+      }
+      await sleep(every);
+    }
+    if (out.isTTY) out.write('\r\x1b[K');
+    say(`${yellow('▲')} No visit yet. Is the change deployed? An ad blocker in your browser stops it too${info.domain ? `, and visits from outside ${info.domain} (other than localhost) are not counted` : ''}.`);
+    say(`  Sumly › Visitors shows it as soon as it comes: ${info.visitors_url ?? `${host}/visitors`}`);
+    return 0;
+  } finally {
+    prompt.close();
+  }
+}

package/src/detect.mjs

@@ -0,0 +1,183 @@
+// Which framework a project is built with, from its package.json, composer.json and files,
+// and which files of it Sumly's line (or the app SDK) goes into.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+/** Folders that are built, installed or someone else's: never searched, never edited. */
+const SKIP = new Set(['node_modules', '.git', 'vendor', 'dist', 'build', 'out', '.next', '.nuxt', '.output', '.svelte-kit', '.astro', '.vercel', '.netlify', 'coverage', 'storage', 'bootstrap', 'ios', 'android', '.expo', 'tmp', '.cache']);
+
+/** Blade and Astro folders that hold e-mails, PDFs and the like, not pages. */
+const NOT_PAGES = /(^|\/)(mail|mails|emails?|vendor|pdfs?|notifications)(\/|$)/i;
+
+export const FRAMEWORKS = {
+  'next-app': { name: 'Next.js (App Router)', guide: 'nextjs' },
+  'next-pages': { name: 'Next.js (Pages Router)', guide: 'nextjs' },
+  'react-router': { name: 'React Router (framework mode)', guide: 'react-router' },
+  remix: { name: 'Remix', guide: 'react-router' },
+  nuxt: { name: 'Nuxt', guide: 'vue' },
+  sveltekit: { name: 'SvelteKit', guide: null },
+  astro: { name: 'Astro', guide: 'astro' },
+  laravel: { name: 'Laravel (Blade)', guide: 'laravel' },
+  expo: { name: 'Expo (Expo Router)', guide: 'react-native' },
+  'react-native': { name: 'React Native', guide: 'react-native' },
+  vite: { name: 'Vite', guide: 'react-router' },
+  cra: { name: 'Create React App', guide: 'react-router' },
+  angular: { name: 'Angular', guide: null },
+  html: { name: 'Plain HTML', guide: null },
+  unknown: { name: 'Something Sumly does not know yet', guide: null },
+};
+
+const read = (dir, file) => {
+  try {
+    return readFileSync(join(dir, file), 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+const json = (dir, file) => {
+  const text = read(dir, file);
+  if (text === null) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+
+/** The first of these paths that exists, relative to the project. */
+export function first(dir, paths) {
+  return paths.find((p) => existsSync(join(dir, p))) ?? null;
+}
+
+const variants = (base, exts) => exts.map((e) => base + e);
+const JS = ['.tsx', '.jsx', '.ts', '.js', '.mjs'];
+
+/** Files under dir/start ending in one of exts, skipping built and installed folders; at most limit of them. */
+export function walk(dir, start, exts, limit = 400) {
+  const found = [];
+  const visit = (folder) => {
+    if (found.length >= limit) return;
+    let entries;
+    try {
+      entries = readdirSync(join(dir, folder), { withFileTypes: true });
+    } catch {
+      return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (found.length >= limit) return;
+      const path = folder ? `${folder}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        if (!SKIP.has(entry.name) && !entry.name.startsWith('.')) visit(path);
+      } else if (exts.some((e) => entry.name.endsWith(e))) {
+        found.push(path);
+      }
+    }
+  };
+  visit(start);
+  return found;
+}
+
+/** Page shells: files with their own </head>, each a document that needs the line. */
+function shells(dir, start, exts, rank) {
+  return walk(dir, start, exts)
+    .filter((p) => !NOT_PAGES.test(p) && /<\/head\s*>/i.test(read(dir, p) ?? ''))
+    .sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+}
+
+const bladeRank = (p) => {
+  const order = [/^resources\/views\/app\.blade\.php$/, /^resources\/views\/layouts\/app\.blade\.php$/, /^resources\/views\/components\/layouts\/app\.blade\.php$/, /\/layouts\//, /^resources\/views\/welcome\.blade\.php$/];
+  const i = order.findIndex((r) => r.test(p));
+  return i === -1 ? order.length : i;
+};
+
+const astroRank = (p) => (/\/layouts\//.test(p) ? 0 : /\/pages\//.test(p) ? 1 : 2);
+
+/**
+ * What the project is and where Sumly goes.
+ *
+ * @returns {{ id: string, name: string, guide: string|null, kind: 'script'|'sdk'|'none', files: string[], create?: string, deps: Record<string,string>, pm: string, typescript: boolean }}
+ */
+export function detect(dir) {
+  const pkg = json(dir, 'package.json');
+  const composer = json(dir, 'composer.json');
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  const has = (name) => Object.prototype.hasOwnProperty.call(deps, name);
+  const typescript = has('typescript') || existsSync(join(dir, 'tsconfig.json'));
+  const pm = existsSync(join(dir, 'pnpm-lock.yaml')) ? 'pnpm' : existsSync(join(dir, 'yarn.lock')) ? 'yarn' : existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock')) ? 'bun' : 'npm';
+  const result = (id, kind, files, extra = {}) => ({ id, ...FRAMEWORKS[id], kind, files: files.filter(Boolean), deps, pm, typescript, ...extra });
+
+  if (has('react-native') || has('expo')) {
+    if (has('expo-router')) {
+      const layout = first(dir, [...variants('app/_layout', JS), ...variants('src/app/_layout', JS)]);
+      if (layout) return result('expo', 'sdk', [layout]);
+    }
+    const app = first(dir, [...variants('App', JS), ...variants('src/App', JS), ...variants('app/App', JS)]);
+    return result(has('expo') && has('expo-router') ? 'expo' : 'react-native', app ? 'sdk' : 'none', [app]);
+  }
+
+  if (has('next')) {
+    const layout = first(dir, [...variants('app/layout', JS), ...variants('src/app/layout', JS)]);
+    if (layout) return result('next-app', 'script', [layout]);
+    const app = first(dir, [...variants('pages/_app', JS), ...variants('src/pages/_app', JS)]);
+    if (app) return result('next-pages', 'script', [app]);
+    const pages = existsSync(join(dir, 'src/pages')) ? 'src/pages' : 'pages';
+    return result('next-pages', 'script', [], { create: `${pages}/_app.${typescript ? 'tsx' : 'jsx'}` });
+  }
+
+  if (has('nuxt') || has('nuxt3')) {
+    const config = first(dir, ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs']);
+    return result('nuxt', config ? 'script' : 'none', [config]);
+  }
+
+  if (has('@sveltejs/kit')) {
+    return result('sveltekit', existsSync(join(dir, 'src/app.html')) ? 'script' : 'none', [existsSync(join(dir, 'src/app.html')) ? 'src/app.html' : null]);
+  }
+
+  if (has('astro')) {
+    const files = shells(dir, 'src', ['.astro'], astroRank);
+    return result('astro', files.length ? 'script' : 'none', files);
+  }
+
+  if (has('@react-router/dev') || has('@remix-run/react')) {
+    const root = first(dir, variants('app/root', JS));
+    return result(has('@react-router/dev') ? 'react-router' : 'remix', root ? 'script' : 'none', [root]);
+  }
+
+  const laravel = composer?.require && Object.prototype.hasOwnProperty.call(composer.require, 'laravel/framework');
+  if (laravel) {
+    const files = shells(dir, 'resources/views', ['.blade.php'], bladeRank);
+    return result('laravel', files.length ? 'script' : 'none', files);
+  }
+
+  if (has('@angular/core')) {
+    return result('angular', existsSync(join(dir, 'src/index.html')) ? 'script' : 'none', [existsSync(join(dir, 'src/index.html')) ? 'src/index.html' : null]);
+  }
+
+  if (has('react-scripts')) {
+    return result('cra', existsSync(join(dir, 'public/index.html')) ? 'script' : 'none', [existsSync(join(dir, 'public/index.html')) ? 'public/index.html' : null]);
+  }
+
+  if (has('vite') && existsSync(join(dir, 'index.html'))) {
+    const flavour = ['react', 'vue', 'svelte', 'solid-js', 'preact', 'lit'].find(has);
+    const label = { react: 'React', vue: 'Vue', svelte: 'Svelte', 'solid-js': 'Solid', preact: 'Preact', lit: 'Lit' }[flavour];
+    return { ...result('vite', 'script', ['index.html']), name: label ? `${label} with Vite` : 'Vite' };
+  }
+
+  const pages = shells(dir, '', ['.html', '.htm'], (p) => (p === 'index.html' ? 0 : p.split('/').length));
+  if (pages.length) return result('html', 'script', pages);
+
+  return result('unknown', 'none', []);
+}
+
+/** A path as the person reads it, with forward slashes. */
+export const show = (dir, path) => relative(dir, join(dir, path)).split(sep).join('/');
+
+export const exists = (dir, path) => {
+  try {
+    return statSync(join(dir, path)).isFile();
+  } catch {
+    return false;
+  }
+};

package/src/diff.mjs

@@ -0,0 +1,70 @@
+// A small unified diff of one file, so the person sees exactly what changes before anything is written.
+
+/** Line operations from a longest common subsequence: [' ' | '-' | '+', line]. */
+export function lines(before, after) {
+  const a = before === null ? [] : before.split('\n');
+  const b = after.split('\n');
+  // Same start and end are kept out of the table, so a large file with a small edit stays cheap.
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start]) start++;
+  let endA = a.length;
+  let endB = b.length;
+  while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+    endA--;
+    endB--;
+  }
+  const midA = a.slice(start, endA);
+  const midB = b.slice(start, endB);
+  const ops = a.slice(0, start).map((l) => [' ', l]);
+  if (midA.length * midB.length > 4_000_000) {
+    ops.push(...midA.map((l) => ['-', l]), ...midB.map((l) => ['+', l]));
+  } else {
+    const n = midA.length;
+    const m = midB.length;
+    const table = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--) {
+      for (let j = m - 1; j >= 0; j--) {
+        table[i][j] = midA[i] === midB[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+      }
+    }
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+      if (midA[i] === midB[j]) {
+        ops.push([' ', midA[i]]);
+        i++;
+        j++;
+      } else if (table[i + 1][j] >= table[i][j + 1]) {
+        ops.push(['-', midA[i++]]);
+      } else {
+        ops.push(['+', midB[j++]]);
+      }
+    }
+    while (i < n) ops.push(['-', midA[i++]]);
+    while (j < m) ops.push(['+', midB[j++]]);
+  }
+  ops.push(...a.slice(endA).map((l) => [' ', l]));
+  return ops;
+}
+
+/** The diff as text: changed lines with up to `context` lines around them, and "…" between parts. */
+export function unified(file, before, after, { context = 2, color = false } = {}) {
+  const ops = lines(before, after);
+  const paint = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+  const keep = new Set();
+  ops.forEach(([op], i) => {
+    if (op !== ' ') for (let k = i - context; k <= i + context; k++) keep.add(k);
+  });
+  const out = [paint('1', before === null ? `+++ ${file} (new file)` : `--- ${file}`)];
+  let gap = false;
+  ops.forEach(([op, line], i) => {
+    if (!keep.has(i)) {
+      gap = true;
+      return;
+    }
+    if (gap && out.length > 1) out.push(paint('2', '  …'));
+    gap = false;
+    out.push(op === '+' ? paint('32', `+ ${line}`) : op === '-' ? paint('31', `- ${line}`) : paint('2', `  ${line}`));
+  });
+  return out.join('\n');
+}

package/src/edits.mjs

@@ -0,0 +1,418 @@
+// The one change per framework: Sumly's line in the layout every page shares, or the SDK's init in an app.
+// Every edit is idempotent: a file that already has Sumly gets at most its key or data-autocapture brought
+// up to date, and a second run changes nothing.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export class EditError extends Error {}
+
+const SDK = '@sumly/sdk/react-native';
+const STORAGE = '@react-native-async-storage/async-storage';
+
+/** How a file is written: quotes, semicolons, one level of indent, line endings. */
+export function style(content) {
+  const imports = content.split('\n').filter((l) => /^import\b/.test(l));
+  const singles = imports.filter((l) => /from\s+'/.test(l) || /^import\s+'/.test(l)).length;
+  const doubles = imports.filter((l) => /from\s+"/.test(l) || /^import\s+"/.test(l)).length;
+  const withSemi = imports.filter((l) => /;\s*$/.test(l)).length;
+  const indents = content.split('\n').map((l) => /^[\t ]*/.exec(l)[0]).filter((i) => i.length > 0);
+  const tab = indents.length > 0 && indents.filter((i) => i.startsWith('\t')).length > indents.length / 2;
+  const spaces = indents.filter((i) => !i.startsWith('\t')).map((i) => i.length);
+  const smallest = spaces.length ? Math.min(...spaces) : 2;
+  return {
+    q: doubles > singles ? '"' : "'",
+    semi: imports.length === 0 ? /;[ \t]*$/m.test(content) : withSemi >= imports.length / 2,
+    unit: tab ? '\t' : ' '.repeat(smallest >= 4 ? 4 : 2),
+  };
+}
+
+const indentOf = (line) => /^[\t ]*/.exec(line)[0];
+
+/** The attributes of the line, in the order the Visitors page writes them. */
+function attrs(o) {
+  return [`src="${o.src}"`, `data-site="${o.key}"`, o.domains ? `data-domains="${o.domains}"` : null, o.autocapture ? 'data-autocapture' : null].filter(Boolean).join(' ');
+}
+
+export const htmlLine = (o) => `<script defer ${attrs(o)}></script>`;
+export const astroLine = (o) => `<script is:inline defer ${attrs(o)}></script>`;
+export const jsxLine = (o) => `<script defer ${attrs(o)} />`;
+export const nextLine = (o, name = 'Script') => `<${name} ${attrs(o)} />`;
+
+/**
+ * A file that already has Sumly: bring its key and data-autocapture up to date, touching nothing else.
+ * Returns null when the file has no Sumly line.
+ */
+export function refresh(content, o) {
+  const html = /data-site\s*=\s*\{?\s*(["'])(sl_[A-Za-z0-9_-]*)\1/;
+  const object = /(['"])data-site\1\s*:\s*(['"])(sl_[A-Za-z0-9_-]*)\2/;
+  const sdk = /siteKey\s*:\s*(['"])(sl_[A-Za-z0-9_-]*)\1/;
+  let c = content;
+  let m;
+  if ((m = html.exec(c))) {
+    if (m[2] !== o.key) c = c.slice(0, m.index) + m[0].replace(m[2], o.key) + c.slice(m.index + m[0].length);
+    const end = c.indexOf('>', m.index);
+    const tag = c.slice(c.lastIndexOf('<', m.index), end);
+    if (o.autocapture && !/data-autocapture/.test(tag)) {
+      const at = m.index + m[0].replace(m[2], o.key).length;
+      c = c.slice(0, at) + ' data-autocapture' + c.slice(at);
+    }
+    return c;
+  }
+  if ((m = object.exec(c))) {
+    if (m[3] !== o.key) c = c.slice(0, m.index) + m[0].replace(m[3], o.key) + c.slice(m.index + m[0].length);
+    const close = c.indexOf('}', m.index);
+    if (o.autocapture && !/data-autocapture/.test(c.slice(m.index, close))) {
+      const at = m.index + m[0].replace(m[3], o.key).length;
+      c = c.slice(0, at) + `, ${m[1]}data-autocapture${m[1]}: true` + c.slice(at);
+    }
+    return c;
+  }
+  if ((m = sdk.exec(c)) && /Sumly\.init\s*\(/.test(c)) {
+    if (m[2] !== o.key) c = c.slice(0, m.index) + m[0].replace(m[2], o.key) + c.slice(m.index + m[0].length);
+    if (o.autocapture && !/autocapture\s*:/.test(c)) {
+      c = c.replace(/Sumly\.init\(\s*\{([\s\S]*?)\s*\}\s*\)/, (all, inner) => `Sumly.init({${inner.replace(/,\s*$/, '')}, autocapture: true })`);
+    }
+    return c;
+  }
+  return null;
+}
+
+/**
+ * Put a line just inside a closing tag (</head>, </body>): on its own line, indented like its siblings.
+ * When the closing tag shares its line with other code, "inline" puts it right before the tag and
+ * "after" puts it on a new line after that whole line, at the same indent.
+ */
+export function beforeClosing(content, tag, line, { unit = '  ', crowded = 'inline' } = {}) {
+  const m = new RegExp(`</${tag}\\s*>`, 'i').exec(content);
+  if (!m) return null;
+  const start = content.lastIndexOf('\n', m.index - 1) + 1;
+  const lead = content.slice(start, m.index);
+  if (lead.trim() !== '') {
+    if (crowded === 'after') {
+      const end = content.indexOf('\n', m.index);
+      const at = end === -1 ? content.length : end;
+      return content.slice(0, at) + '\n' + indentOf(content.slice(start, at)) + line + content.slice(at);
+    }
+    return content.slice(0, m.index) + line + content.slice(m.index);
+  }
+  const before = content.slice(0, start).split('\n');
+  before.pop();
+  const previous = [...before].reverse().find((l) => l.trim() !== '') ?? '';
+  const opens = new RegExp(`<${tag}(\\s[^>]*)?>\\s*$`, 'i').test(previous);
+  const indent = opens ? lead + unit : indentOf(previous);
+  return content.slice(0, start) + indent + line + '\n' + content.slice(start);
+}
+
+/** Put a line on a new line after the line that matches, at its indent. */
+export function afterLine(content, pattern, line) {
+  const m = pattern.exec(content);
+  if (!m) return null;
+  const start = content.lastIndexOf('\n', m.index - 1) + 1;
+  const end = content.indexOf('\n', m.index + m[0].length);
+  const at = end === -1 ? content.length : end;
+  return content.slice(0, at) + '\n' + indentOf(content.slice(start, at)) + line + content.slice(at);
+}
+
+/** Line index just after the file's imports (and its 'use client' style directives), and the imports' text. */
+export function importsEnd(content) {
+  const lines = content.split('\n');
+  let last = -1;
+  let open = false;
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i].trim();
+    if (open) {
+      if (/from\s+['"][^'"]+['"]\s*;?\s*$/.test(l) || /^['"][^'"]+['"]\s*;?\s*$/.test(l)) {
+        open = false;
+        last = i;
+      }
+      continue;
+    }
+    if (/^import\b/.test(l)) {
+      if (/from\s+['"][^'"]+['"]\s*;?\s*$/.test(l) || /^import\s+['"][^'"]+['"]\s*;?\s*$/.test(l) || /^import\s+\w+\s*=/.test(l)) last = i;
+      else open = true;
+      continue;
+    }
+    if (l === '' || l.startsWith('//') || l.startsWith('/*') || l.startsWith('*') || /^['"]use [a-z ]+['"];?$/.test(l)) {
+      if (/^['"]use [a-z ]+['"];?$/.test(l) && last === -1) last = i;
+      continue;
+    }
+    break;
+  }
+  return { line: last + 1, text: lines.slice(0, last + 1).join('\n') };
+}
+
+/** Add lines after the last import, or at the top. */
+export function addAfterImports(content, add) {
+  const lines = content.split('\n');
+  const { line } = importsEnd(content);
+  const blank = line === 0 && add[add.length - 1] !== '' && (lines[0] ?? '').trim() !== '' ? [''] : [];
+  lines.splice(line, 0, ...add, ...blank);
+  return lines.join('\n');
+}
+
+const imported = (content, name) => new RegExp(`\\b${name}\\b`).test(importsEnd(content).text);
+
+// ——— the frameworks ———
+
+function head(content, o, line) {
+  const s = style(content);
+  const out = beforeClosing(content, 'head', line, { unit: s.unit });
+  if (out === null) throw new EditError('it has no </head>');
+  return out;
+}
+
+function nextApp(content, o) {
+  const s = style(content);
+  let c = content;
+  let name = /import\s+(\w+)\s+from\s+['"]next\/script['"]/.exec(c)?.[1];
+  if (!name) {
+    name = imported(c, 'Script') ? 'SumlyScript' : 'Script';
+    c = addAfterImports(c, [`import ${name} from ${s.q}next/script${s.q}${s.semi ? ';' : ''}`]);
+  }
+  const out = beforeClosing(c, 'body', nextLine(o, name), { unit: s.unit, crowded: 'after' });
+  if (out === null) throw new EditError('the layout has no </body>');
+  return out;
+}
+
+function nextPages(content, o) {
+  const s = style(content);
+  let c = content;
+  let name = /import\s+(\w+)\s+from\s+['"]next\/script['"]/.exec(c)?.[1];
+  if (!name) {
+    name = imported(c, 'Script') ? 'SumlyScript' : 'Script';
+    c = addAfterImports(c, [`import ${name} from ${s.q}next/script${s.q}${s.semi ? ';' : ''}`]);
+  }
+  const tag = nextLine(o, name);
+  const m = /<Component\s+\{\s*\.\.\.pageProps\s*\}\s*\/>/.exec(c);
+  if (!m) throw new EditError('_app has no <Component {...pageProps} />');
+  const start = c.lastIndexOf('\n', m.index - 1) + 1;
+  const lead = c.slice(start, m.index);
+  const ind = indentOf(lead);
+  const u = s.unit;
+  const direct = /(return|=>)\s*\(?\s*$/.test(c.slice(0, m.index));
+  if (!direct) return afterLine(c, /<Component\s+\{\s*\.\.\.pageProps\s*\}\s*\/>/, tag);
+  if (lead.trim() === '' || /\(\s*$/.test(lead)) {
+    const inner = lead.trim() === '' ? ind : ind + u;
+    const rep = `<>\n${inner}${u}${m[0]}\n${inner}${u}${tag}\n${inner}</>`;
+    return c.slice(0, m.index) + (lead.trim() === '' ? '' : '\n' + inner) + rep + c.slice(m.index + m[0].length);
+  }
+  const rep = `(\n${ind}${u}<>\n${ind}${u}${u}${m[0]}\n${ind}${u}${u}${tag}\n${ind}${u}</>\n${ind})`;
+  return c.slice(0, m.index) + rep + c.slice(m.index + m[0].length);
+}
+
+export function nextPagesNew(o, typescript) {
+  return typescript
+    ? `import type { AppProps } from 'next/app';\nimport Script from 'next/script';\n\nexport default function App({ Component, pageProps }: AppProps) {\n  return (\n    <>\n      <Component {...pageProps} />\n      ${nextLine(o)}\n    </>\n  );\n}\n`
+    : `import Script from 'next/script';\n\nexport default function App({ Component, pageProps }) {\n  return (\n    <>\n      <Component {...pageProps} />\n      ${nextLine(o)}\n    </>\n  );\n}\n`;
+}
+
+function reactRouter(content, o) {
+  const after = afterLine(content, /<Links\s*\/>/, jsxLine(o));
+  if (after !== null) return after;
+  const s = style(content);
+  const out = beforeClosing(content, 'head', jsxLine(o), { unit: s.unit });
+  if (out === null) throw new EditError('root has no <Links /> or </head>');
+  return out;
+}
+
+/** Index of the brace that closes the one at open, skipping strings and comments. */
+export function closing(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '"' || ch === "'" || ch === '`') {
+      for (i++; i < text.length && text[i] !== ch; i++) if (text[i] === '\\') i++;
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '/') {
+      i = text.indexOf('\n', i);
+      if (i === -1) return -1;
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '*') {
+      i = text.indexOf('*/', i);
+      if (i === -1) return -1;
+      continue;
+    }
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    if (ch === '}' || ch === ']' || ch === ')') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+function nuxt(content, o) {
+  const s = style(content);
+  const q = s.q;
+  const u = s.unit;
+  const entry = `{ src: ${q}${o.src}${q}, defer: true, ${q}data-site${q}: ${q}${o.key}${q}${o.domains ? `, ${q}data-domains${q}: ${q}${o.domains}${q}` : ''}${o.autocapture ? `, ${q}data-autocapture${q}: true` : ''} }`;
+  const lineIndent = (at) => indentOf(content.slice(content.lastIndexOf('\n', at - 1) + 1, at));
+  const insertAfterBrace = (at, build) => {
+    const ind = lineIndent(at) + u;
+    return content.slice(0, at + 1) + '\n' + build(ind) + content.slice(at + 1);
+  };
+
+  const config = /defineNuxtConfig\(\s*\{/.exec(content) ?? /export\s+default\s*\{/.exec(content);
+  if (!config) throw new EditError('nuxt.config has no defineNuxtConfig({ … })');
+  const open = config.index + config[0].length - 1;
+  const end = closing(content, open);
+  const top = content.slice(open, end);
+
+  const app = /\bapp\s*:\s*\{/.exec(top);
+  if (!app) {
+    return insertAfterBrace(open, (ind) => `${ind}app: {\n${ind}${u}head: {\n${ind}${u}${u}script: [\n${ind}${u}${u}${u}${entry},\n${ind}${u}${u}],\n${ind}${u}},\n${ind}},`);
+  }
+  const appOpen = open + app.index + app[0].length - 1;
+  const appBody = content.slice(appOpen, closing(content, appOpen));
+  const hd = /\bhead\s*:\s*\{/.exec(appBody);
+  if (!hd) {
+    return insertAfterBrace(appOpen, (ind) => `${ind}head: {\n${ind}${u}script: [\n${ind}${u}${u}${entry},\n${ind}${u}],\n${ind}},`);
+  }
+  const headOpen = appOpen + hd.index + hd[0].length - 1;
+  const headBody = content.slice(headOpen, closing(content, headOpen));
+  const sc = /\bscript\s*:\s*\[/.exec(headBody);
+  if (!sc) {
+    return insertAfterBrace(headOpen, (ind) => `${ind}script: [\n${ind}${u}${entry},\n${ind}],`);
+  }
+  const listOpen = headOpen + sc.index + sc[0].length - 1;
+  return insertAfterBrace(listOpen, (ind) => `${ind}${entry},`);
+}
+
+/**
+ * The app: import the SDK, init it once at the top, and, for taps or Expo Router's screens, a small
+ * component around the app that is now the default export.
+ */
+function reactNative(content, o, project) {
+  const s = style(content);
+  const q = s.q;
+  const semi = s.semi ? ';' : '';
+  const u = s.unit;
+  const expo = project.id === 'expo';
+  let c = content;
+  const notes = [];
+
+  // The wrapper: around the default export, which must take no props (an App or a root layout does not).
+  const wrap = o.autocapture || expo;
+  let inner = null;
+  if (wrap && !/\bSumlyRoot\b/.test(c)) {
+    let m;
+    if ((m = /^export\s+default\s+function\s*(\w*)\s*\(\s*\)/m.exec(c))) {
+      inner = m[1] || 'AppRoot';
+      c = c.slice(0, m.index) + `function ${inner}()` + c.slice(m.index + m[0].length);
+    } else if ((m = /^export\s+default\s+class\s+(\w+)/m.exec(c))) {
+      inner = m[1];
+      c = c.slice(0, m.index) + `class ${inner}` + c.slice(m.index + m[0].length);
+    } else if ((m = /^export\s+default\s+(?!function\b|class\b|async\b)([A-Za-z_$][\w$]*)[ \t]*;?[ \t]*(?:\n|$)/m.exec(c))) {
+      inner = m[1];
+      c = c.slice(0, m.index) + c.slice(m.index + m[0].length);
+    } else {
+      notes.push(o.autocapture
+        ? 'Wrap your app once in <Sumly.Touches>…</Sumly.Touches> so taps count (its default export takes props, so the wizard left it as it is).'
+        : 'Count screens: in the root layout, const pathname = usePathname(); useEffect(() => { Sumly.screen(pathname); }, [pathname]);');
+    }
+  }
+
+  const add = [];
+  if (!new RegExp(`from\\s+['"]${SDK}['"]`).test(c)) add.push(`import { Sumly } from ${q}${SDK}${q}${semi}`);
+  let storage = new RegExp(`import\\s+(\\w+)\\s+from\\s+['"]${STORAGE}['"]`).exec(c)?.[1] ?? null;
+  if (o.storage && !storage) {
+    storage = 'AsyncStorage';
+    add.push(`import AsyncStorage from ${q}${STORAGE}${q}${semi}`);
+  }
+  if (inner && expo) {
+    if (!imported(c, 'usePathname')) add.push(`import { usePathname } from ${q}expo-router${q}${semi}`);
+    if (!imported(c, 'useEffect')) add.push(`import { useEffect } from ${q}react${q}${semi}`);
+  }
+  const options = [`siteKey: ${q}${o.key}${q}`, storage ? `storage: ${storage}` : null, o.autocapture ? 'autocapture: true' : null].filter(Boolean).join(', ');
+  c = addAfterImports(c, [...add, '', `Sumly.init({ ${options} })${semi}`]);
+
+  if (inner) {
+    const body = [];
+    if (expo) {
+      body.push(`${u}const pathname = usePathname()${semi}`);
+      body.push(`${u}useEffect(() => {`, `${u}${u}Sumly.screen(pathname)${semi}`, `${u}}, [pathname])${semi}`);
+    }
+    if (o.autocapture) {
+      body.push(`${u}return (`, `${u}${u}<Sumly.Touches>`, `${u}${u}${u}<${inner} />`, `${u}${u}</Sumly.Touches>`, `${u})${semi}`);
+    } else {
+      body.push(`${u}return <${inner} />${semi}`);
+    }
+    c = c.replace(/\s*$/, '') + `\n\nexport default function SumlyRoot() {\n${body.join('\n')}\n}\n`;
+  }
+
+  if (!expo && !/onStateChange/.test(c) && /<NavigationContainer\b/.test(c)) {
+    c = c.replace(/<NavigationContainer\b/, '<NavigationContainer onStateChange={Sumly.onNavigationChange}');
+  } else if (!expo) {
+    notes.push("Count screens: <NavigationContainer onStateChange={Sumly.onNavigationChange}>, or Sumly.screen('Name') where a screen opens.");
+  }
+  return { content: c, notes };
+}
+
+/**
+ * The changes for a project, without writing anything.
+ *
+ * @param {string} dir
+ * @param {ReturnType<import('./detect.mjs').detect>} project
+ * @param {{ key: string, src: string, domains?: string|null, autocapture?: boolean, storage?: boolean, files?: string[] }} o
+ * @returns {{ changes: {file: string, before: string|null, after: string}[], already: string[], problems: {file: string, reason: string}[], notes: string[] }}
+ */
+export function plan(dir, project, o) {
+  const changes = [];
+  const already = [];
+  const problems = [];
+  const notes = [];
+
+  if (project.create) {
+    changes.push({ file: project.create, before: null, after: nextPagesNew(o, project.typescript) });
+    return { changes, already, problems, notes };
+  }
+
+  const files = o.files?.length ? o.files : project.files;
+  for (const file of files) {
+    let raw;
+    try {
+      raw = readFileSync(join(dir, file), 'utf8');
+    } catch {
+      problems.push({ file, reason: 'there is no such file' });
+      continue;
+    }
+    const crlf = raw.includes('\r\n');
+    const before = crlf ? raw.replace(/\r\n/g, '\n') : raw;
+    let after;
+    try {
+      after = refresh(before, o);
+      if (after === null) {
+        switch (project.id) {
+          case 'next-app': after = nextApp(before, o); break;
+          case 'next-pages': after = nextPages(before, o); break;
+          case 'react-router':
+          case 'remix': after = reactRouter(before, o); break;
+          case 'nuxt': after = nuxt(before, o); break;
+          case 'astro': after = head(before, o, astroLine(o)); break;
+          case 'expo':
+          case 'react-native': {
+            const done = reactNative(before, o, project);
+            after = done.content;
+            notes.push(...done.notes);
+            break;
+          }
+          default: after = head(before, o, htmlLine(o));
+        }
+      } else if (/Sumly\.init\s*\(/.test(after) && o.autocapture && !/Sumly\.Touches/.test(after)) {
+        notes.push('Wrap your app once in <Sumly.Touches>…</Sumly.Touches> so taps count.');
+      }
+    } catch (error) {
+      if (!(error instanceof EditError)) throw error;
+      problems.push({ file, reason: error.message });
+      continue;
+    }
+    if (after === before) {
+      already.push(file);
+      continue;
+    }
+    changes.push({ file, before: raw, after: crlf ? after.replace(/\n/g, '\r\n') : after });
+  }
+  return { changes, already, problems, notes };
+}