solid2-agent-kit 0.17.0 → 0.19.0

package/README.md

@@ -20,7 +20,7 @@ Supported agents: **Cursor** and **Claude Code**.
 | Edit-time hook | `postToolUse` entry in `.cursor/hooks.json` | `PostToolUse` entry in `.claude/settings.json` (matcher includes `Bash`) | Runs the mechanical gate automatically on **every agent file edit — including edits made through shell commands** (sed, heredocs, codemods; source paths mentioned in the command are checked after it ran) — and feeds findings straight back into the conversation (Cursor: `additional_context`; Claude Code: stderr + exit 2), so enforcement does not depend on the agent remembering to run `check`. Wired only when the kit is a local devDependency; opt out with `--no-hooks` |
 | Turn-end gate | — | `Stop` entry in `.claude/settings.json` | Whole-project `check` + `doctor` when the agent tries to end its turn: with findings in place the stop is blocked (exit 2) and the findings are fed back, so a turn cannot finish with React/Solid 1.x patterns left behind. Loop-safe via `stop_hook_active` (one forced continuation, never an infinite loop) |
 | Pre-execution guard | `preToolUse` + `beforeShellExecution` entries in `.cursor/hooks.json` | `PreToolUse` entry in `.claude/settings.json` | Denies actions **before they run**: edits/deletes of kit-owned guardrail files (an agent blocked by a gate will try to remove the gate), edits that would strip the kit's hook entries or managed blocks, uninspectable shell rewrites of those files, and `npm/pnpm/yarn/bun install` of banned dependencies (`react`, `vite-plugin-solid`, `eslint-plugin-solid`, SolidStart, ...) — caught proactively instead of post-hoc by `doctor` |
-| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a Solid 1.x line of `solid-js` / `@solidjs/router` / `@solidjs/meta` / `@solidjs/testing-library` / `@tanstack/solid-router` / `@tanstack/solid-query` (declared, or installed from the `latest` tag — Solid 2 releases are on `next`; TanStack Router's and Query's on `rc`), `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
+| Project-wiring gate | `solid2-kit doctor` | same | Config drift the source gate cannot see: React / `vite-plugin-solid` / `eslint-plugin-solid` / SolidStart deps in `package.json`, a Solid 1.x line of `solid-js` / `@solidjs/router` / `@solidjs/meta` / `@solidjs/testing-library` / `@tanstack/solid-router` / `@tanstack/solid-query` (declared, or installed from the `latest` tag — Solid 2 releases are on `next`; TanStack Router's and Query's on `rc`), a Solid 2 prerelease older than the kit's baseline in `bin/baseline.mjs` (`@solidjs/web` / `@solidjs/signals` / `@solidjs/diagnostics` `latest` is an older rc than `next`), `jsx` ≠ `preserve` or `jsxImportSource` ≠ `@solidjs/web` in tsconfig, Solid 1.x wiring in root config files, and stale installed guidance (kit updated but `sync` not re-run) |
 | Review command | `.cursor/commands/solid2-review.md` | `.claude/commands/solid2-review.md` | `/solid2-review` — on-demand deep review: runs both gates, then walks the diff against the skill checklist targeting the semantic failure classes regexes cannot see (post-`await` reads, effect misuse, unkeyed server rows, boundary placement, context snapshots) |
 
 Managed blocks are delimited with `<!-- solid2-agent-kit:*:start/end -->` markers; everything
@@ -169,6 +169,7 @@ markdown with an `.md` suffix).
 
 ```
 bin/solid2-kit.mjs                 CLI: init / sync / check / doctor / hook
+bin/baseline.mjs                   Solid 2 versions the kit is verified against (doctor + check:upstream)
 files/shared/rules-body.md         hard rules (rendered into .mdc and CLAUDE.md)
 files/shared/agents-section.md     AGENTS.md managed-block content
 files/skills/solid-2/              SKILL.md + references/official-docs.md

package/bin/baseline.mjs

@@ -0,0 +1,41 @@
+// The Solid 2 releases the kit's guidance is verified against, shared by
+// `solid2-kit doctor` (a project on an older release is flagged) and
+// check:upstream (scripts/upstream-probes/registry.mjs: a newer release is
+// flagged). `line` is the major the kit targets: check:upstream installs the
+// newest dist-tagged version on it. `baseline` is the version every upstream
+// probe was verified against — bump it (and fix any marked claim that changed)
+// after re-verifying.
+//
+// npm dist-tags lag each other on these prereleases (@solidjs/web, @solidjs/signals
+// and @solidjs/diagnostics `latest` is an older 2.0 rc than `next`;
+// @solidjs/vite-plugin's `next` is behind `latest`), so a bare install can
+// resolve a release older than the baseline.
+export const BASELINE = {
+  'solid-js': { line: 2, baseline: '2.0.0-rc.13' },
+  '@solidjs/web': { line: 2, baseline: '2.0.0-rc.13' },
+  '@solidjs/signals': { line: 2, baseline: '2.0.0-rc.13' },
+  '@solidjs/diagnostics': { line: 2, baseline: '2.0.0-rc.13' },
+  '@solidjs/router': { line: 2, baseline: '2.0.0-next.34' },
+  '@solidjs/vite-plugin': { line: 3, baseline: '3.0.0-next.47' },
+  '@solidjs/testing-library': { line: 1, baseline: '1.0.0-beta.3' },
+};
+
+export function parseVersion(version) {
+  const [core, pre] = version.split('+')[0].split(/-(.*)/s);
+  return { core: core.split('.').map(Number), pre: pre ? pre.split('.') : [] };
+}
+
+// Semver precedence, prerelease-aware (2.0.0-rc.10 > 2.0.0-rc.9 < 2.0.0).
+export function compareVersions(a, b) {
+  const x = parseVersion(a);
+  const y = parseVersion(b);
+  for (let i = 0; i < 3; i++) if (x.core[i] !== y.core[i]) return x.core[i] - y.core[i];
+  if (!x.pre.length || !y.pre.length) return y.pre.length - x.pre.length;
+  for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+    const [p, q] = [x.pre[i], y.pre[i]];
+    if (p === undefined || q === undefined) return p === undefined ? -1 : 1;
+    const numeric = /^\d+$/.test(p) && /^\d+$/.test(q);
+    if (p !== q) return numeric ? Number(p) - Number(q) : /^\d+$/.test(p) ? -1 : /^\d+$/.test(q) ? 1 : p < q ? -1 : 1;
+  }
+  return 0;
+}

package/bin/solid2-kit.mjs

@@ -24,6 +24,7 @@ import {
 } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { BASELINE, compareVersions } from './baseline.mjs';
 
 const KIT_ROOT = fileURLToPath(new URL('..', import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(KIT_ROOT, 'package.json'), 'utf8')).version;
@@ -273,7 +274,7 @@ function init() {
   if (hooksNote) console.log(`  note: ${hooksNote}`);
   if (!hasDiagnosticsDependency(target)) {
     console.log(
-      '  note: the solid-2 skill\'s development loop drives the dev server\'s /__solid/diagnostics endpoint; add "@solidjs/diagnostics" to devDependencies so @solidjs/vite-plugin serves it (auto-on when declared). Without it the fallback is an isDev-guarded attribution.enable({ log: false }).',
+      `  note: the solid-2 skill's development loop drives the dev server's /__solid/diagnostics endpoint; add "@solidjs/diagnostics" to devDependencies (install @solidjs/diagnostics@^${BASELINE['@solidjs/diagnostics'].baseline} — npm \`latest\` can be an older rc) so @solidjs/vite-plugin serves it (auto-on when declared). Without it the fallback is an isDev-guarded attribution.enable({ log: false }).`,
     );
   }
 }
@@ -479,6 +480,29 @@ function reactKeyPropFindings(content) {
 // reads it from package.json / node_modules.
 const TANSTACK_ROUTER_MODULE = /^@tanstack\/(?:solid-router|router-core)$/;
 
+// `<Loading on={id}>` hands the boundary an accessor: `on` is a tracked
+// expression whose value is irrelevant, so a bare accessor is never read and
+// the boundary never re-arms. `on={id()}`, `on={props.id}` and
+// `on={[a(), b()]}` do not match. The opening tag is scanned to its own `>`
+// (braces balanced) so a `fallback={<p>…</p>}` before `on` does not end it.
+function loadingOnAccessorFindings(content) {
+  const matches = [];
+  for (const tag of content.matchAll(/<Loading\b/g)) {
+    let index = tag.index + tag[0].length;
+    let depth = 0;
+    while (index < content.length) {
+      const ch = content[index];
+      if (ch === '{') depth += 1;
+      else if (ch === '}') depth -= 1;
+      else if (ch === '>' && depth === 0) break;
+      index += 1;
+    }
+    const bare = content.slice(tag.index, index).match(/\son=\{\s*[A-Za-z_$][\w$]*\s*\}/);
+    if (bare) matches.push({ index: tag.index + bare.index });
+  }
+  return matches;
+}
+
 // Local names bound by `import [Default,] { a, b as c } from "<module>"`.
 function importedNames(content, moduleName) {
   const names = new Set();
@@ -748,6 +772,13 @@ const CHECKS = [
     message:
       'Pass the accessor to isPending/latest, not the call: isPending(user), not isPending(user()). Calling it first evaluates the read before the helper runs.',
   },
+  {
+    // `<Loading on={id}>` — the accessor is never read, so `on` never re-arms.
+    id: 'loading-on-accessor',
+    find: loadingOnAccessorFindings,
+    message:
+      '`on` is a tracked dependency list, not a key: a bare accessor is never read, so the boundary never re-arms. Read it — on={id()} — or list several inputs: on={[a(), b()]}.',
+  },
   {
     id: 'dynamic-jsx',
     pattern: /<Dynamic[\s/>]/g,
@@ -1259,6 +1290,31 @@ const SOLID2_LINE_PACKAGES = [
   },
 ];
 
+// Packages doctor checks the version of: the Solid 1.x lines above, then any
+// release older than the kit's baseline (bin/baseline.mjs) — a bare
+// `npm i @solidjs/web` installs `latest`, 2.0.0-rc.0, which the current
+// @solidjs/vite-plugin's `@solidjs/web ^2.0.0-rc.13` peer rejects.
+const VERSION_CHECKED = [...new Set([...SOLID2_LINE_PACKAGES.map((p) => p.name), ...Object.keys(BASELINE)])];
+
+// The lower bound of a single-comparator range ("^2.0.0-rc.0", "~2.0.0-rc.8",
+// ">=2.0.0-rc.0", "2.0.0-rc.0") or an installed version. Dist-tags, "*",
+// unions and protocol specs have no bound to read; their install is checked.
+const LOWER_BOUND = /^\s*(?:[\^~]|>=|=)?\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)\s*$/;
+
+// `declared` ranges are judged by their floor: npm installs the `latest` tag
+// whenever it satisfies the range, so "^2.0.0-rc.0" resolves to rc.0 today.
+function versionProblem(name, version, declared) {
+  const line = SOLID2_LINE_PACKAGES.find((p) => p.name === name);
+  if (line?.solid1.test(version)) return `the Solid 1.x line; this kit teaches Solid 2.x. ${line.fix}`;
+  const baseline = BASELINE[name]?.baseline;
+  const lowest = version.match(LOWER_BOUND)?.[1];
+  if (baseline && lowest && compareVersions(lowest, baseline) < 0) {
+    const older = declared ? 'allows releases older than' : 'older than';
+    return `${older} ${baseline}, the release this kit's guidance is verified against (npm dist-tags lag on the Solid 2 prereleases, so a bare install can resolve an older one). Install ${name}@^${baseline}.`;
+  }
+  return null;
+}
+
 function installedVersion(target, name) {
   try {
     return JSON.parse(readFileSync(join(target, 'node_modules', name, 'package.json'), 'utf8')).version;
@@ -1283,21 +1339,19 @@ function doctorFindings(target) {
   for (const [name, message] of Object.entries(BANNED_DEPS)) {
     if (name in deps) report(`dep-${name.replace(/[@/]/g, '')}`, `package.json depends on "${name}". ${message}`);
   }
-  for (const { name, id, solid1, fix } of SOLID2_LINE_PACKAGES) {
+  for (const name of VERSION_CHECKED) {
+    const id = SOLID2_LINE_PACKAGES.find((p) => p.name === name)?.id ?? `${name.replace('@solidjs/', '')}-version`;
     const range = deps[name];
-    if (typeof range === 'string' && solid1.test(range)) {
-      report(id, `package.json pins ${name} "${range}" — the Solid 1.x line; this kit teaches Solid 2.x. ${fix}`);
+    if (typeof range !== 'string') continue;
+    const declared = versionProblem(name, range, true);
+    if (declared) {
+      report(id, `package.json pins ${name} "${range}" — ${declared}`);
       continue;
     }
-    // A range such as "latest" or "*" only shows its line once resolved.
-    if (range === undefined) continue;
+    // A range such as "latest" or "*" only shows its version once resolved.
     const installed = installedVersion(target, name);
-    if (installed && solid1.test(installed)) {
-      report(
-        id,
-        `node_modules has ${name} ${installed} (package.json: "${range}") — the Solid 1.x line; this kit teaches Solid 2.x. ${fix}`,
-      );
-    }
+    const resolved = installed && versionProblem(name, installed, false);
+    if (resolved) report(id, `node_modules has ${name} ${installed} (package.json: "${range}") — ${resolved}`);
   }
 
   for (const entry of readdirSync(target, { withFileTypes: true })) {

package/files/commands/solid2-review.md

@@ -14,7 +14,8 @@ Steps:
 4. Review every changed `.tsx`/`.jsx`/`.ts` file against the checklist, prioritizing what
    regexes cannot see:
    - reactive reads at component-body top level, or extracted into plain `const`s;
-   - async computations reading reactive inputs **after** the first `await`;
+   - async computations reading reactive inputs **after** the first `await` (dev reports
+     `[UNTRACKED_READ_AFTER_AWAIT]` on V8);
    - effects that copy state instead of deriving it, or reading stores in the apply phase;
    - `<For>` over server/refetched rows without a stable-id key function;
    - core `action` bodies that are not generators (plain `async` functions) or that write
@@ -23,7 +24,8 @@ Steps:
    - `<Loading>`/`<Errored>` wrapping page chrome instead of the data slot, or
      `const u = user()` extracted then passed (a real parent-side read). Passing
      `user={user()}` is the colorless form — do not "fix" it into accessors or
-     `Promise<User>` props;
+     `Promise<User>` props; `<Loading on={id}>` handed the accessor instead of a read
+     (`on={id()}`), or the boundary's data also read outside it (`[LOADING_ON_OUTSIDE_HOLD]`);
    - `latest(selectedId)` as the default highlight (hold is the default);
      `isPending` treated as a global spinner instead of a per-expression question;
    - treating `<Errored>` as a terminal ErrorBoundary, or expecting it to catch
@@ -74,7 +76,8 @@ Steps:
      thrown failures, or router forms without server-side validation (`throw respond(...)`)
      and `useSubmissions` inline errors;
    - browser-only *values* handled with a `clientOnly` component split or an `isServer`
-     branch instead of `ssrSource: "client"` / `"hybrid"` on the memo/signal/derived store;
+     branch instead of `ssrSource: "client"` on the memo/signal/derived store (`"hybrid"`
+     only continues an async-iterable source after hydration <!-- upstream:ssr-source-hybrid-stream -->);
    - held writes with no feedback (`isPending` / `latest` / optimistic value / `affects()`)
      — the `[SILENT_HOLD]` shape — and dev-console diagnostics (`[STRICT_READ_UNTRACKED]`,
      attribution-only store/list/effect costs) left unaddressed;

package/files/shared/agents-section.md

@@ -5,4 +5,4 @@
 - After editing TSX, run the `solid2-kit check` mechanical gate — it fails on React/Solid 1.x tokens and props destructuring. Use the project's `lint:solid` script if one exists; otherwise `npx solid2-agent-kit check` (with the kit as a devDependency) or `npx github:lightsound/solid2-agent-kit check`. An edit-time hook may also run this gate automatically after each file edit — treat its findings as errors to fix immediately, not warnings. Do not install `eslint-plugin-solid` (built for Solid 1.x; misreads Solid 2 idioms).
 - After editing `package.json`, `tsconfig*.json`, or root config files (Vite, ESLint), run `solid2-kit doctor` — it fails on React/Solid 1.x wiring: `react`/`vite-plugin-solid`/`eslint-plugin-solid`/SolidStart dependencies, 1.x `solid-js` ranges, and `jsx`/`jsxImportSource` values other than `preserve`/`@solidjs/web`.
 - The kit's guidance and gate files (`.cursor/rules/solid-2.mdc`, the `solid-2` skill directories, hook entries, managed blocks in this file and `CLAUDE.md`) are guardrails, not obstacles. Never edit, weaken, bypass, or delete them to make a failure go away — fix the flagged code. If a guardrail seems wrong, stop and tell the user.
-- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass async values as values (`user={user()}`) — JSX props are lazy; types stay `User`, not `Promise<User>`. `<Loading>` wraps the read, not the memo. Nested fetches run in parallel (components do not suspend). `isPending` is a per-expression question (`isPending(() => props.story)` / `isPending(selectedId)`), not a global spinner; `latest(selectedId)` is opt-in so highlight and content stay consistent by default. `<Errored>` heals when the source succeeds. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup` — return the cleanup; `onCleanup`, memo/effect creation, and `flush()` throw inside the `onSettled` callback in dev. Effect `apply` functions use block bodies (`(t) => { document.title = t; }`): any return value other than a cleanup function halts reactivity. Stores are written only through the setter's draft — writes to the store itself are silently ignored, and `Map`/`Set`/`Date` inside a store are not tracked. Shared state, app-wide included, is created in a provider at the root of `App` (`createContext<T>()` + `useX()`), never a module-level signal/store (one instance serves every SSR request). Errors thrown out of an `action` never reach `<Errored>` — catch them in the action or `.catch` the call. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — markup types are `JSX.Element` from `@solidjs/web` or `Element` from `solid-js` (alias it `SolidElement` next to DOM code) <!-- upstream:jsx-namespace-absent -->. Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state). Client → server is additive (same setters + `action` + server functions): do not rewrite App with loading/error branches, disable optimistic rows until ack, invent tRPC, or refetch in `hydrate`/`onSettled`. The graph continues across the wire (`live()` owns the client connection; `<Reveal>` not a delayed stream). A server bundle uses `handleRequest` / Fetchable `fetch`; client-only start is static `dist/client`. One browser-only value takes `ssrSource` on the memo/signal/derived store (`client`/`hybrid`), not a `clientOnly` component split. Router link state is automatic (`aria-current`/`data-active`/`data-pending` + CSS; `useLinkState`/`useIsRouting` in JSX); search params via `useSearchParams`; router forms validate on the server (`throw respond({issues},{400})`) with inline errors from `useSubmissions`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write) <!-- upstream:async-store-setter-throws -->, and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or per root `render(fn, root, undefined, { onError })` — options are the 4th argument), not a side effect inside `<Errored fallback>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. <!-- upstream:dynamic-deprecated --> Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.
+- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass async values as values (`user={user()}`) — JSX props are lazy; types stay `User`, not `Promise<User>`. `<Loading>` wraps the read, not the memo. Nested fetches run in parallel (components do not suspend). `isPending` is a per-expression question (`isPending(() => props.story)` / `isPending(selectedId)`), not a global spinner; `latest(selectedId)` is opt-in so highlight and content stay consistent by default. `<Errored>` heals when the source succeeds. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup` — return the cleanup; `onCleanup`, memo/effect creation, and `flush()` throw inside the `onSettled` callback in dev. Effect `apply` functions use block bodies (`(t) => { document.title = t; }`): any return value other than a cleanup function halts reactivity. Stores are written only through the setter's draft — writes to the store itself are silently ignored, and `Map`/`Set`/`Date` inside a store are not tracked. Shared state, app-wide included, is created in a provider at the root of `App` (`createContext<T>()` + `useX()`), never a module-level signal/store (one instance serves every SSR request). Errors thrown out of an `action` never reach `<Errored>` — catch them in the action or `.catch` the call. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — markup types are `JSX.Element` from `@solidjs/web` or `Element` from `solid-js` (alias it `SolidElement` next to DOM code) <!-- upstream:jsx-namespace-absent -->. Reset-a-signal-on-change is a writable derivation (`createSignal(() => { source(); return initial; })`), never an effect calling the setter. Client mode mounts with `render()` into an empty body — no hydration mismatch exists, so never defer initial values to post-mount React-style (that can overwrite persisted state). Client → server is additive (same setters + `action` + server functions): do not rewrite App with loading/error branches, disable optimistic rows until ack, invent tRPC, or refetch in `hydrate`/`onSettled`. The graph continues across the wire (`live()` owns the client connection; `<Reveal>` not a delayed stream). A server bundle uses `handleRequest` / Fetchable `fetch`; client-only start is static `dist/client`. One browser-only value takes `ssrSource: "client"` on the memo/signal/derived store, not a `clientOnly` component split. Router link state is automatic (`aria-current`/`data-active`/`data-pending` + CSS; `useLinkState`/`useIsRouting` in JSX); search params via `useSearchParams`; router forms validate on the server (`throw respond({issues},{400})`) with inline errors from `useSubmissions`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write) <!-- upstream:async-store-setter-throws -->, and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or per root `render(fn, root, undefined, { onError })` — options are the 4th argument), not a side effect inside `<Errored fallback>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. <!-- upstream:dynamic-deprecated --> Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.

package/files/shared/rules-body.md

@@ -125,14 +125,18 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     must `refresh()` that source — type that prop `SourceAccessor<User>` (`Accessor<User>`
     is TS2345 at `refresh`) — `isPending(() => props.user)` works on the
     value. Read every reactive input **before the first
-    `await`** — post-`await` reads do not subscribe, and in production the computation can
+    `await`** — post-`await` reads do not subscribe (dev reports `[UNTRACKED_READ_AFTER_AWAIT]`
+    on V8 engines), and in production the computation can
     sit pending with no retry. No `useEffect` + `setState` fetching, no `createResource`.
     `<Loading>` wraps the data slot, not page chrome. After first paint it keeps content
-    during refetch (`isPending` for the indicator). Use `on={id()}` (the *value*, not the
-    accessor) only when that identity change should show the fallback again. `on` compares
-    with `!==` (several keys: one string such as `` `${a()}/${b()}` ``, never a fresh array)
-    and takes effect only when no reader outside the boundary waits on the same write
-    (that is how one slow panel stops holding the page). Do not start `fetch` (or any request) at component-body top
+    during refetch (`isPending` for the indicator). Add `on={id()}` (a tracked *read*, not
+    the accessor `on={id}`) only when that change of subject should show the fallback again.
+    `on` is a dependency list, not a compared key: its value is irrelevant, a change to
+    anything it reads re-arms the boundary (several inputs: `on={[a(), b()]}`), and the
+    fallback lands with the frame of the change that caused it. <!-- upstream:loading-on-dependency-list -->
+    It can never show while the same data is also read outside the boundary (dev reports
+    `[LOADING_ON_OUTSIDE_HOLD]`) — move that read under the boundary so one hold owns the
+    data; that is how one slow panel stops holding the page. Do not start `fetch` (or any request) at component-body top
     level — that runs once at mount and is not a reactive source. Do not `try/catch` `NotReadyError` around a read, and do not
     use `loadingValue` / `seedLoadingValue` as the default first-flight UI — those skip
     `<Loading>`. `{latest(() => x())}` is a preview, not the visible answer, and not a
@@ -323,9 +327,10 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     render. `NoHydration` / `Hydration` split hydration *ownership*; they do not choose
     visible content — `clientOnly` is for components that must never run on the server.
     A single browser-only *value* takes `ssrSource` on the memo/signal/derived store
-    (`"client"` skips the server value and computes after hydration, e.g. `localStorage`;
-    `"hybrid"` re-runs after adopting the serialized value, e.g. window size mixed with
-    server data) — do not split a component via `clientOnly` for one value. An
+    (`"client"` skips the server value and computes after hydration, e.g. `localStorage`,
+    or server data mixed with the window size; `"hybrid"` adopts the serialized value and
+    then continues an async-iterable source on the client — for a sync or promise compute
+    it is identical to `"server"`, no re-run <!-- upstream:ssr-source-hybrid-stream -->) — do not split a component via `clientOnly` for one value. An
     `onSettled` fill-in remains a valid alternative.
     Pass a **function** to `render` / `hydrate` / `renderToString` / `renderToStream`
     (`render(() => <App />, root)`), never `render(<App />, root)`. `hydrate` when the
@@ -348,7 +353,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     link previews) takes `{ deferStream: true }` on its memo; keep the boundary. `pipe` / `pipeTo` / `readable` each consume
     a stream render — use exactly one. `createRoot` is for tests, libraries, and
     non-render entry points; inside a component let `render` / the component owner
-    own the scope. Async reads inside `<Portal>` start on the client — hoist the
+    own the scope (a root created under an owner is disposed with it — detach on purpose
+    with `runWithOwner(null, () => createRoot(...))`). Async reads inside `<Portal>` start on the client — hoist the
     read above the portal. Navigation-shaped updates (a setter, then async computeds holding previous values)
     do not need core `action` — reach for it only when writes happen *after* async work.
     Invoke actions from handlers, not from memos or effects.
@@ -437,9 +443,11 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     experimental `serverFunctions.components` flag. Server-function arguments are JSON:
     send `Date` / `Map` / `Set` as ISO strings / arrays (they throw otherwise; one `File` /
     `Blob` / `FormData` argument travels natively). `enableRichArguments()` from
-    `@solidjs/web/server-functions/rich-args` (at `src/App.tsx` module scope) lifts that,
-    but in rc.9 importing it fails `vite build` (`"./client" is not exported`) <!-- upstream:rich-args-vite-build https://github.com/solidjs/solid/issues/3627 -->. Declare live reads as `live(GET(fn))` —
-    `live()` outermost. A plain `async function*` server function is an event stream on
+    `@solidjs/web/server-functions/rich-args` (at `src/App.tsx` module scope) lifts that
+    (its import builds cleanly since 2.0.0-rc.10 — a `resolve.dedupe: ["@solidjs/web"]`
+    workaround left from rc.9 is no longer needed) <!-- upstream:rich-args-vite-build https://github.com/solidjs/solid/issues/3627 -->. Declare live reads as `live(GET(fn))` —
+    `live()` outermost; an undeclared async iterable still producing while a document
+    renders is `[SSR_UNDECLARED_LIVE_SOURCE]` in dev. A plain `async function*` server function is an event stream on
     one connection (no reconnect when it drops); `live()` is one value that changes over
     time and reconnects. `live()` connection state is
     `source.onstatus` (`"connected"` / `"reconnecting"` / `"closed"`), never a

package/files/skills/solid-2/SKILL.md

@@ -74,7 +74,7 @@ Most React `useEffect` code should NOT become `createEffect`:
 | Async value used several layers down | Create the memo high; pass `value={memo()}` through intermediates (they do not wait); put `<Loading>` around the leaf read |
 | Nested child with its own fetch | Leave it nested — it runs in parallel. Sequential only when the second call needs the first response (`fetchAuthor(story().authorId)`) |
 | Browser-only widget (charts, maps, `window`) | `clientOnly(() => import("./Chart"))` from `@solidjs/web` (`{ lazy: true }` defers the import until first render; `{ export: "Chart" }` for a named export). Placeholder: `<Chart fallback={<Skeleton />} />` — SSR renders the fallback; a `<Loading>` around it leaves the server HTML empty |
-| Browser-only *value* (`localStorage`, viewport size) | `createMemo(..., { ssrSource: "client" })` — per-value policy at the data source, no component split (`"hybrid"` when server data mixes with client signals) |
+| Browser-only *value* (`localStorage`, viewport size) | `createMemo(..., { ssrSource: "client" })` — per-value policy at the data source, no component split (`"hybrid"` only to keep consuming an async-iterable source after hydration <!-- upstream:ssr-source-hybrid-stream -->) |
 | Server vs browser code path | `isServer` / `isDev` from `@solidjs/web` (build-time constants), not `typeof window` — never to choose markup (`{isServer ? <A /> : <B />}` is a hydration mismatch; use `clientOnly` / `ssrSource`) |
 | SSR-stable `id` / `for` / `aria-*` pairing | `createUniqueId()` |
 
@@ -256,7 +256,11 @@ const Result = dynamic(() => (detailed() ? Detailed : Compact));
 ```
 
 `dynamic()` returns a **stable** component whose source can be a component, an
-intrinsic tag name, a promise, or empty. Prefer it over swapping a component
+intrinsic tag name, a promise, or empty. An async source (a promise, or a `live()`
+server-component iterable) may resolve to a server component or a tag name; a promise
+of a *client* component function is a dev error on the server
+(`[DYNAMIC_ASYNC_COMPONENT]`) — resolve the async upstream, or `lazy()` for code.
+Prefer it over swapping a component
 variable in JSX (`const View = tab() ? A : B` freezes the choice at setup).
 `<Dynamic component={...}>` is the same primitive with a worse shape (the tag travels
 in the props bag, so every instance merges and omits it and rebuilds a factory) and
@@ -399,8 +403,12 @@ return <StoryDetail story={story} />;
   Lifting the fetch does **not** mean lifting the boundary — that is consume glued
   back onto block. After first paint the
   boundary keeps settled content during refetch; `isPending(results)` (pass the accessor,
-  not `isPending(results())`) is the indicator. Use `on={query()}` (the **value**, not the
-  accessor `on={query}`) only when that identity should put the fallback back on screen.
+  not `isPending(results())`) is the indicator. Add `on={query()}` (a tracked **read** —
+  the accessor `on={query}` reads nothing) only when that change of subject should put the
+  fallback back on screen. `on` is a dependency list, not a compared key: its value is
+  irrelevant, several inputs go in as `on={[query(), page()]}`, and a change to anything it
+  reads re-arms the boundary. <!-- upstream:loading-on-dependency-list --> `[LOADING_ON_OUTSIDE_HOLD]` in dev means the same data is
+  also read outside the boundary, so the fallback can never show — move that read under it.
   Do not use `isPending` as the first-load spinner.
 - **Nesting is not a waterfall.** `Comments` above fetches in parallel with `story`
   because it reads `props.storyId` (already known), not `props.story`. Passing
@@ -426,7 +434,8 @@ return <StoryDetail story={story} />;
   the same rule: bind `value={latest(query)}` so a controlled search box reflects
   keystrokes while its write is held (an uncontrolled input needs nothing).
 - Read every reactive input **before the first `await`** in an async computation. A read
-  after `await` does not subscribe; production can sit pending with no retry.
+  after `await` does not subscribe (dev reports `[UNTRACKED_READ_AFTER_AWAIT]` on V8 —
+  Chromium, Node, Deno, Bun); production can sit pending with no retry.
 - `<Errored>` function fallbacks receive an error **accessor** and a `reset` callback:
   `fallback={(error, reset) => ...}`. The boundary **heals** when the source succeeds
   again (refresh, live reconnect, input change) — it is graph status, not a terminal
@@ -988,8 +997,8 @@ function DraftPreview(props: { documentId: string }) {
 | Policy | Meaning | Use when |
 |---|---|---|
 | `"server"` (default) | Client adopts the serialized server value; compute does not re-run | Compute is deterministic from server-available inputs |
-| `"hybrid"` | Client adopts the serialized value, then re-runs the compute to take over | Server data mixes with client signals (window size, user locale) |
-| `"client"` | Server value skipped; compute runs after hydration as if first-mounted | Serialization is meaningless (`localStorage`, viewport) |
+| `"hybrid"` | Client adopts the serialized value, then — for an async-iterable source — continues the stream on the client; for a sync or promise compute it is identical to `"server"` (no re-run) <!-- upstream:ssr-source-hybrid-stream --> | A stream (`live()`, a subscription) the client should keep consuming after hydration |
+| `"client"` | Server value skipped; compute runs after hydration as if first-mounted | Serialization is meaningless (`localStorage`, viewport), or server data mixes with a browser-only input |
 
 With `"client"`, the bare form suspends on the server and the nearest `<Loading>`
 fallback renders into the HTML; a declared first value (`loadingValue` on
@@ -1068,19 +1077,24 @@ see [Production observability](#production-observability-the-observe-build) —
 dev setting. Diagnostics come in two layers: **findings** (facts about a render, present
 in observe and dev) and **checks** (dev-only guidance printed by the console reporter).
 Always-on dev checks include misplaced reads
-(`[STRICT_READ_UNTRACKED]`, `[PENDING_ASYNC_UNTRACKED_READ]`), misplaced writes
+(`[STRICT_READ_UNTRACKED]`, `[PENDING_ASYNC_UNTRACKED_READ]`, `[UNTRACKED_READ_AFTER_AWAIT]`
+for a first read made after an `await` in an async compute — V8 engines only), misplaced writes
 (`[REACTIVE_WRITE_IN_OWNED_SCOPE]` — since rc.9 also for store setters called in a
 component or root body <!-- upstream:store-write-owned-scope -->, `[ASYNC_STORE_SETTER]` for a store setter callback that returns
 a promise <!-- upstream:async-store-setter-throws -->, `[FLUSH_IN_ACTION]`, `[SERVER_WRITE]`), and
-`[ASYNC_OUTSIDE_LOADING_BOUNDARY]` when a tracked read has no boundary above it.
+`[ASYNC_OUTSIDE_LOADING_BOUNDARY]` when a tracked read has no boundary above it, and
+`[LOADING_ON_OUTSIDE_HOLD]` when a `<Loading on>` boundary's data is also read outside it.
 Each entry carries a stable `[CODE]`, what the runtime observed, and an owner chain
 (`in <App> › <Cart> › <LineItem>`); never silence a code before understanding it.
 Since rc.9 the server render reports on the same channel with the same owner chains:
 `[SSR_RENDER_ERROR_CONTAINED]` (a boundary routed a render error; `ownerPath` is where
-it was thrown, `boundaryPath` where it was met) <!-- upstream:ssr-render-error-contained -->, `[SSR_ERROR_SANITIZED]` (the original
-behind a production-sanitized error), `[SSR_CLIENT_CONTENT_MASKED]` (client-only content
-that surfaced only after a real server wait — the wait was wasted), server-side
-`[ASYNC_WATERFALL]`, and `[REVEAL_IN_RENDER_TO_STRING]`.
+it was thrown, `boundaryPath` where it was met) <!-- upstream:ssr-render-error-contained -->, `[SERVER_ERROR_SANITIZED]` (the original
+behind a production-sanitized error, from a server function or an SSR render),
+`[SSR_CLIENT_CONTENT_MASKED]` (client-only content that surfaced only after a real
+server wait — the wait was wasted), `[SSR_BOUNDARY_WATERFALL]` (sequential waits inside
+one server `<Loading>` boundary), `[SSR_UNDECLARED_LIVE_SOURCE]` (an async iterable
+still pumping into a document render — declare it `live()`), and
+`[REVEAL_IN_RENDER_TO_STRING]`.
 For the repair behind any code, read the `reactivity-diagnostics` skill Solid ships
 in the repo (`node_modules/solid-js/skills/reactivity-diagnostics/SKILL.md`) — every
 code maps to what the runtime observed and what to change.
@@ -1091,13 +1105,18 @@ every scope that re-ran, what changed to cause it, and how long it took. Since
 no longer exists <!-- upstream:dev-attribution-removed --> (it is a type error; `DEV` holds only devtools hooks, graph
 traversal, and console reporting). `OBSERVE` is the public observability surface on
 the observe and dev builds — `OBSERVE.records`, `OBSERVE.diagnostics`,
-`OBSERVE.exclude`, `OBSERVE.server.trace` are for app and tool code; only the
-`OBSERVE.attribution` hook slot (`install` / `withInteraction` / `withOrigin`) belongs
-to engines, routers, and devtools. Since 2.0.0-rc.9 the folds, queries, and
-formatters are **named exports** of that subpath, not methods of `attribution`
-(`attribution.why` / `.costs` / `.feedback` / `.subscriptions` / `.format` are type
-errors) <!-- upstream:attribution-named-exports -->; `attribution` keeps `enable`, `disable`, `subscribe`, `markFlight`, and the
-record ring buffers (`history`, `holds`, `waterfalls`, `navigations`, `interactions`):
+`OBSERVE.exclude` / `OBSERVE.include`, `OBSERVE.ownerPath`, `OBSERVE.server.trace` are
+for app and tool code; only the `OBSERVE.attribution` slot (`withInteraction` /
+`withOrigin`) belongs to engines, routers, and devtools. Since 2.0.0-rc.9 the folds,
+queries, and formatters are **named exports** of that subpath, not methods of
+`attribution` (`attribution.why` / `.costs` / `.feedback` / `.subscriptions` / `.format`
+are type errors) <!-- upstream:attribution-named-exports -->; `attribution` keeps `enable` (a hold on the one shared engine — it
+returns the release), `disable` (full teardown), `markFlight`, and one ring-buffer reader,
+`attribution.history(type)` (`"rerun"` / `"hold"` / `"waterfall"` / `"navigation"` /
+`"interaction"`). Live records — the engine's included — arrive on
+`OBSERVE.records.subscribe(type, (event, live) => …)`; `attribution.subscribe` and the
+`holds()` / `waterfalls()` / `navigations()` / `interactions()` methods are gone since
+2.0.0-rc.10. <!-- upstream:attribution-history-records -->
 
 ```ts
 import { attribution, formatRerun, why } from 'solid-js/attribution';
@@ -1116,13 +1135,15 @@ to query the tables yourself. Name the scopes you intend to interrogate
 (`createMemo(..., { name: "total" })`) — chains refer to nodes by name, and
 anonymous nodes print as `computed` / `effect` / `signal`; component labels
 (`<Checkout>`) are always present under `vite dev` and survive minification only with
-the compiler's `componentNames` option (`solid({ observe: true })` turns it on). On the
+the compiler's `sourceNames` option (components, binding effects, primitives — the Vite
+plugin turns it on under `vite dev` and `observe: true`; `componentNames` was its rc.9 name
+and is rejected now) <!-- upstream:source-names-option -->. On the
 **prod build** the import resolves to an inert same-surface twin whose `enable()` is a
 no-op, so the import can stay in the code. On the **observe build** it is the real
 engine and an unguarded `enable()` records in production — keep the `isDev` guard
 unless recording in production is the intent. The split is pay-for-use: importing
 `costs` or `feedback` is what turns their tables on, so a records-only consumer
-(`attribution.subscribe(...)`) ships neither.
+(`OBSERVE.records.subscribe("rerun", …)`) ships neither.
 
 While attribution is enabled, Solid also warns on its own about over-subscription,
 chained async waterfalls (`[ASYNC_WATERFALL]`), memos whose fresh-but-equal output
@@ -1136,10 +1157,18 @@ ran while held; info from 100ms, warning from 200ms, tunable via
 `enable({ holds: { infoMs, warnMs } })`). A hold that *was* acknowledged but still ran
 long is `[LONG_HOLD]` (info from 500ms, warning from 1000ms;
 `enable({ longHolds: { infoMs, warnMs } })`) — the suggestion is a `<Loading on={...}>`
-boundary, never removing the hold. `costs()`, `feedback()` (named imports), and
-`attribution.holds()` rank the session worst-first; `attribution.waterfalls()`,
-`attribution.navigations()`, and `attribution.interactions()` hold the fact tables
-behind the verdicts.
+boundary, never removing the hold. Beside them: `[UNTRACKED_ASYNC_HANDLER]` (an `async`
+handler that awaits with no write before the `await` and no `action` — no hold exists, so
+the click looks dead; make it an `action`, or write a `createOptimistic(false)` flag
+first), `[ABANDONED_FLIGHTS]` (a source re-asked on every keystroke, answers thrown away
+— debounce at the handler), `[STACKED_HOLDS]` (repeated clicks piling into one hold),
+`[FALLBACK_FLASH]` (a fallback shown under 150ms), `[WASTED_RECOMPUTE]` (a scope whose
+runs mostly compared equal — narrow its reads upstream), `[GRAPH_GROWTH]` (the graph grows
+on every visit to a route — an undisposed root or subscription), and `[OPTIMISTIC_REVERTED]`
+(info: a guess the screen showed was replaced). `costs()` and `feedback()` (named imports)
+rank the session worst-first; `attribution.history("hold")` / `("waterfall")` /
+`("navigation")` / `("interaction")` hold the fact tables behind the verdicts (each hold
+carries its `silent` / `long` verdict). <!-- upstream:attribution-history-records -->
 `subscriptions(scope)` (named import) lists a scope's current dependencies to compare
 against what it uses.
 
@@ -1179,7 +1208,8 @@ effects** — a pure markup or styling change does not need it.
 2. **Name the scopes you changed** (`createMemo(fn, { name: "total" })`,
    `createStore(v, { name: "cart" })`) so chains and tables refer to them by name.
 3. **Record the interaction and ask.** First choice — no app code — is the diagnostics
-   endpoint: with `@solidjs/diagnostics` in `devDependencies`, the Vite plugin's
+   endpoint: with `@solidjs/diagnostics` in `devDependencies` at the same version as
+   `solid-js` (npm `latest` can lag; `solid2-kit doctor` flags an older one), the Vite plugin's
    `diagnostics` option (auto-on when the package is declared; dev server only, never
    under vitest, `vite build`, or preview) injects the capture bridge and serves
    `/__solid/diagnostics`. `begin` enables attribution with `log: false` for the
@@ -1201,11 +1231,14 @@ effects** — a pure markup or styling change does not need it.
    `attribution.enable({ log: false })` in the client entry, then `why(scope)` /
    `costs()` / `feedback()` from the console or a scratch effect — never `log: true`
    left on (one collapsed `[why-run]` group per re-run) and never unguarded (on the
-   observe build it records in production).
+   observe build it records in production). Under `vite dev` the plugin also paints the
+   same records as tracks in the Chrome Performance panel (`performanceTracks`, on by
+   default; `false` opts out) — record there when a timeline reads better than tables.
 4. **Read the verdicts, then the tables.** Fix every coded warning the session raised
    (`[SILENT_HOLD]`, `[IMMUTABLE_UPDATE_IN_STORE]`, `[UNSTABLE_LIST_IDENTITY]`,
    `[EFFECT_RELAY_TEAR]`, `[EFFECT_WRITES_OWN_SOURCE]`, `[ASYNC_WATERFALL]`,
-   `[HOT_SCOPE_RERUNS]`). Then `costs().scopes` (self time, `wastedMs` for runs whose
+   `[HOT_SCOPE_RERUNS]`, `[WASTED_RECOMPUTE]`, `[ABANDONED_FLIGHTS]`,
+   `[UNTRACKED_ASYNC_HANDLER]`). Then `costs().scopes` (self time, `wastedMs` for runs whose
    result did not change), `costs().writes` (root writes by downstream work),
    `feedback().sources` / `.interactions` / `.flights` / `.fallbacks` (silent holds,
    held time per interaction, abandoned requests, fallback flashes). A scope that
@@ -1232,14 +1265,16 @@ export default { plugins: [solid({ ssr: true, observe: true })] };
 ```
 
 `observe: true` adds the `observe` condition to every environment (client and server,
-`vite build` and preview) and turns on the compiler's `componentNames` option so
-`ownerPath` / `boundaryPath` name components instead of `computed`. Without the plugin,
-set `resolve.conditions` (or `node --conditions=observe` for an unbundled server) and
-`componentNames` yourself. Cost in Solid's size suite: ~16.8 KB against ~15.3 KB brotli
+`vite build` and preview) and turns on the compiler's `sourceNames` option (components,
+binding effects, and primitives) so `ownerPath` / `boundaryPath` name components instead
+of `computed` <!-- upstream:source-names-option -->. Without the plugin, set `resolve.conditions` (or `node --conditions=observe`
+for an unbundled server) and `sourceNames` yourself. Cost in Solid's size suite: ~16.8 KB against ~15.3 KB brotli
 for a small client app; importing the attribution engine on top raises the cap to
 ~27 KB (a separate entry — an observe build that never imports it never ships it). The
 two error hooks are **not** part of this: they fire on every build, prod included, only
-the paths are `undefined` there.
+the paths are `undefined` there. `enablePerformanceTracks()` from
+`@solidjs/web/performance-tracks` paints the records on the Chrome Performance panel in
+production too (observe build; a no-op on the prod build).
 
 - **Instrumentation order.** A monitoring SDK's `init()` (and `configureServerErrors`)
   must run before the modules it patches load. `import "./instrument"` at the top of an
@@ -1256,22 +1291,31 @@ the paths are `undefined` there.
   `OBSERVE?.server.trace.provide((request) => ({ traceId, spanId, entries }))`, once per
   request. Do not write middleware to inject trace headers.
 - **Records.** `OBSERVE?.records.subscribe(type, (event, live) => …)` delivers one plain
-  record per `"boundary"` (a `<Loading>` that waited on the server), `"invocation"`
-  (server-function execution), `"call"` (server-function call from the page — shares
-  `id` with its invocation), and `"frame"` (produced / applied). Records are
+  record per `"render"` (a server render: `mode`, `shellMs`, `durationMs`, `boundaries`,
+  `outcome`, the matched `route`), `"boundary"` (a `<Loading>` that waited on the server),
+  `"invocation"` (server-function execution), `"request"` / `"call"` (a server-function
+  call from the page, at send and at settle — `call` shares `id` with its invocation),
+  `"frame"` (produced / applied), and `"recovery"` (a boundary the client re-rendered
+  after a server failure); the attribution engine's own records (`"rerun"`, `"hold"`,
+  `"interaction"`, `"navigation"`, …) ride the same channel while it is enabled. Records are
   serializable data; live handles (request, args, the error as thrown) ride in the
   second argument. Listeners run synchronously inside the runtime, **must not write
   signals**, and should subscribe from a module that loads before the app.
-- **Interactions.** `attribution.enable()` then
-  `attribution.subscribe("interaction", (event) => …)` says what each click waited on
+- **Interactions.** `attribution.enable()` (keep the release it returns) then
+  `OBSERVE?.records.subscribe("interaction", (event) => …)` <!-- upstream:attribution-history-records --> says what each click waited on
   (`event.settledMs`, `event.holds[].blockers`, `event.holds[].holdMs`); a hold nothing acknowledged
   is the dead click. The fold tables stay separate imports.
 - **What leaves the process.** Beyond names, four record fields carry page data —
   `target` (element as `tag#id "text"`, 30 chars), `prev` / `value` previews (40 chars),
-  navigation `to` / `from` / `params`, and `data.error` on server render findings — an
-  exporter decides what to do with each. A tool that renders inside the app it watches
+  navigation `to` / `from` / `params`, and `data.error` on server render findings. The
+  engine's `values` option governs the first three at the source — `"full"` (the dev
+  default), `"labels"` (no previews; element text only on buttons and links), `"none"`
+  (the observe-build default) — so an exporter on the observe build passes its level
+  explicitly (`attribution.enable({ values: "labels" })`) and decides what to do with the
+  rest. A tool that renders inside the app it watches
   (devtools panel) marks its root with `OBSERVE?.exclude(getOwner()!)` inside its
-  `createRoot` so its own effects and stores never become findings; do not route its
+  `createRoot` so its own effects and stores never become findings (`OBSERVE?.include(owner)`
+  re-admits the app's root under an excluded shell); do not route its
   writes through `runWithOwner` (that is a write in an owned scope).
 
 ## Client mode: no server HTML, no hydration reflexes
@@ -1641,10 +1685,10 @@ status, so `return respond({ error }, { status: 400 })` reads as success to the
 is success metadata a scripted caller unwraps. Arguments are JSON: send `Date` / `Map` /
 `Set` as ISO strings / arrays (they throw otherwise; one `File` / `Blob` / `FormData`
 argument travels natively). `enableRichArguments()` from
-`@solidjs/web/server-functions/rich-args` (at `src/App.tsx` module scope) lifts that, but
-in rc.9 importing it fails `vite build` (`"./client" is not exported` — the dev server
-works, so the break shows only at build); `resolve: { dedupe: ["@solidjs/web"] }` in the
-Vite config works around it. <!-- upstream:rich-args-vite-build https://github.com/solidjs/solid/issues/3627 -->
+`@solidjs/web/server-functions/rich-args` (at `src/App.tsx` module scope) lifts that. Its
+import failed `vite build` in rc.9 (`"./client" is not exported`); that is fixed since
+2.0.0-rc.10, so a `resolve: { dedupe: ["@solidjs/web"] }` workaround left in a Vite config
+is no longer needed (the plugin dedupes the runtime packages itself under `vite dev`). <!-- upstream:rich-args-vite-build https://github.com/solidjs/solid/issues/3627 -->
 `GET()` is only for idempotent reads (URLs leak into logs/history);
 import it from `@solidjs/web/server-functions`, never `@solidjs/start`.
 Reads are function calls too: `GET(async (id) => { "use server"; ... })` is invoked
@@ -1672,7 +1716,10 @@ export const fetchStory = GET(async (id: number) => {
 A value that changes over time is `live(GET(fn))` — **`live()` outermost**: `GET()`
 chooses the read transport and `live()` wraps the call behavior around it. `live()`
 does not imply `GET()`; without it the source streams over POST, which is fine when a
-cacheable URL is of no use.
+cacheable URL is of no use. A server component rendered into a document that reads an
+*undeclared* async iterable still producing after 5s is `[SSR_UNDECLARED_LIVE_SOURCE]` in
+dev — declare it `live()` (the document takes the first value and closes it; the client
+connects after hydration) or bound the source.
 
 ```ts
 // src/data/auction.ts
@@ -1805,7 +1852,7 @@ how to reuse. Prefer the form on the right.
 | `createEffect(() => user, (u) => { log(u.name); })` | `createEffect(() => user.name, (name) => { log(name); })` |
 | `createEffect(() => title(), (t) => (document.title = t))` / `(v) => setX(v)` | `(t) => { document.title = t; }` — apply returns a cleanup or nothing; any other return value halts reactivity. An apply that only calls a local setter is rule 4 even with braces (`solid2-kit check` flags it): use a (writable) derivation |
 | `<Loading fallback={<PageSkeleton />}>{/* header + data */}</Loading>` | wrap only the data slot; chrome stays outside |
-| `<Loading on={id} fallback={...}>` (the accessor) | `on={id()}` — a value, so identity changes can show fallback |
+| `<Loading on={id} fallback={...}>` (the accessor), or `` on={`${a()}/${b()}`} `` to key several inputs | `on={id()}` / `on={[a(), b()]}` — `on` is a tracked dependency list, not a compared key: a bare accessor is never read (`solid2-kit check` flags it), and an array is the several-inputs form <!-- upstream:loading-on-dependency-list --> |
 | `setCount(count() + 1)` when writes can batch | `setCount((c) => c + 1)` |
 | `setHandler(fn)` to store a function | `setHandler(() => fn)` (otherwise `fn` is an updater) |
 | `{user() ? <P user={user()!} /> : <SignIn />}` | `<Show when={user()}>{(u) => <P user={u()} />}</Show>` |
@@ -1837,7 +1884,7 @@ how to reuse. Prefer the form on the right.
 | `renderToString(() => <App />)` for an async or lazy-route tree | `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`). String render emits `<Loading>` fallbacks |
 | `clientOnly(() => import("./Map"))` for a rarely shown widget | same + `{ lazy: true }` so the import waits until first render (default starts at declaration) |
 | `<NoHydration><Chart /></NoHydration>` to skip SSR of a widget | `clientOnly(() => import("./Chart"))` — `NoHydration`/`Hydration` split ownership, they do not choose visible content |
-| `clientOnly` split (or `isServer` branch) for one browser-only *value* | `createMemo(() => localStorage.getItem(k), { ssrSource: "client" })` — `"hybrid"` when server data mixes with client signals |
+| `clientOnly` split (or `isServer` branch) for one browser-only *value* | `createMemo(() => localStorage.getItem(k), { ssrSource: "client" })` — `"hybrid"` only to keep consuming an async-iterable source after hydration <!-- upstream:ssr-source-hybrid-stream --> |
 | `await flush()` / `flush()` to wait on a pending memo | `await resolve(() => value())` (or Testing Library async queries); `flush()` only drains staged *sync* writes |
 | `action(function* () { setX(v); })` around a navigation-shaped setter | plain setter; async computeds hold previous values. Core `action` only when writes happen *after* async work |
 | `export const [cart, setCart] = createStore(...)` for app-wide state | `createCart()` called by a `CartProvider` at the root of `App`, read with `useCart()` over `createContext<T>()` — module state has no owner and, under SSR, one instance serves every request (`[SERVER_WRITE]`). Module scope is for constants and `createContext` |
@@ -1900,7 +1947,7 @@ how to reuse. Prefer the form on the right.
 | `latest(user) ?? placeholder` in a handler as a null-safe read | `latest()` throws `NotReadyError` before the first value in every scope; read settled values under `<Loading>`, or `await until(() => user())` <!-- upstream:latest-throws-unsettled --> |
 | `attribution.why(total)` / `attribution.format(e)` / `attribution.costs()` | named imports from `solid-js/attribution`: `why(total)`, `formatRerun(e)`, `costs()`, `feedback()`, `subscriptions(scope)` (rc.9) <!-- upstream:attribution-named-exports --> |
 | `attribution.enable()` unguarded in app code, or `enable()` with the default `log: true` left on | `if (isDev) attribution.enable({ log: false })` — on the observe build an unguarded `enable()` records in production; prefer the `/__solid/diagnostics` session (`begin` enables, `end` disables) so app code carries nothing |
-| `solid({ observe: true })` added "to see diagnostics in dev" | `vite dev` is always the dev build; `observe: true` is the production-observability opt-in (observe condition + `componentNames` for `vite build`/preview) |
+| `solid({ observe: true })` added "to see diagnostics in dev" | `vite dev` is always the dev build; `observe: true` is the production-observability opt-in (observe condition + `sourceNames` for `vite build`/preview <!-- upstream:source-names-option -->) |
 | `configureServerErrors({ onError: (e) => { report(e); return e; } })` | return nothing or a reference (`new Error(\`ref ${id}\`)`) — the return value replaces the sanitized wire value; the error itself leaks message/stack/secrets |
 | `import "./instrument"` at the top of the server entry for a monitoring SDK | `start: { instrument: "./src/instrument.ts" }` — ESM hoists static imports in dependency order, so the entry's own deps load first |
 | Express/middleware injecting `traceparent` / trace headers into responses | the runtime carries a sampled or provided trace on `Server-Timing` + `<meta>`; forward downstream with `getTraceContext()?.entries`; SDKs use `OBSERVE?.server.trace.provide` |
@@ -2111,7 +2158,7 @@ always-applied rules installed alongside this skill.
       memo/effect. Effect `apply` functions have block bodies and return only a
       cleanup or nothing.
 - [ ] Dev console shows no diagnostics: reads in tracking scopes (no
-      `[STRICT_READ_UNTRACKED]`), store setters synchronous and never called at
+      `[STRICT_READ_UNTRACKED]`, no `[UNTRACKED_READ_AFTER_AWAIT]`), store setters synchronous and never called at
       body level (no `[ASYNC_STORE_SETTER]` <!-- upstream:async-store-setter-throws --> /
       `[REACTIVE_WRITE_IN_OWNED_SCOPE]` <!-- upstream:store-write-owned-scope -->), held
       writes paired with `isPending` / `latest` / optimistic values / `affects()`

package/files/skills/solid-2/references/official-docs.md

@@ -26,6 +26,7 @@ The skill does not cover these; fetch the pages when the task needs them.
 - Row selection without `createSelector` (id-keyed projection): https://v2-rebuild--solid-docs-v2.netlify.app/guides/lists.md, https://v2-rebuild--solid-docs-v2.netlify.app/guides/performance.md
 - Infinite scroll, polling, sharing one request: https://v2-rebuild--solid-docs-v2.netlify.app/guides/data-fetching-patterns.md
 - Writing a custom primitive (called under an owner, `MaybeAccessor`, `getOwner` / `runWithOwner` / `isDisposed` after async): https://v2-rebuild--solid-docs-v2.netlify.app/guides/custom-primitives.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/owner-introspection/get-owner.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/owner-introspection/run-with-owner.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/owner-introspection/is-disposed.md
+- Library code that must know whether it is hydrating, or write a keyed server-to-client value (`isHydrating`, `isHydratable`, `getHydrationWriter` / `takeHydrationValue`): https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/manual-hydration/is-hydrating.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/manual-hydration/is-hydratable.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/rendering-ssr/get-hydration-writer.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/rendering-ssr/take-hydration-value.md
 - Wrapping a non-Solid library, push feeds with a reactive argument, web components (`prop:`, event names): https://v2-rebuild--solid-docs-v2.netlify.app/guides/integrate-non-solid-code.md
 - Typed env (`env.ts` schema, `VITE_` client keys), `import "server-only"`, what compiles `"use server"`: https://v2-rebuild--solid-docs-v2.netlify.app/building-apps/environment.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/vite-plugin-solid/modules.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/vite-plugin-solid/server-functions.md
 - Sessions and cookies (`parseCookieHeader` / `serializeCookie`, `RequestEventLocals` typing, when a cookie write commits): https://v2-rebuild--solid-docs-v2.netlify.app/building-apps/sessions-and-auth.md, https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/cookies.md
@@ -158,6 +159,7 @@ the error hooks fire on every build.
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-js/advanced/diagnostics-dev-hooks/configure-client-errors.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/configure-server-errors.md
 - https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/request-response/get-trace-context.md
+- https://v2-rebuild--solid-docs-v2.netlify.app/reference/solid-web/performance-tracks/enable-performance-tracks.md
 
 ## Reference: components and JSX (solid-js)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Teach AI coding agents (Cursor, Claude Code) to write correct Solid 2.0 instead of React or Solid 1.x — always-applied rules, an agent skill, and a mechanical pattern gate.",
   "type": "module",
   "license": "MIT",