solid2-agent-kit 0.18.0 → 0.20.0

package/bin/baseline.mjs

@@ -10,13 +10,22 @@
 // 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.
+//
+// The JSX compilers (@solidjs/compiler, native and the default;
+// @solidjs/babel-plugin under `compiler: "babel"`) are listed because compiled
+// output carries behavior the guidance states (lowercase `on*` is a plain
+// attribute since rc.14). Projects rarely declare them — @solidjs/vite-plugin
+// pulls them in — so doctor also checks an undeclared install of any package
+// here, which is where a lockfile holds an older compiler.
 export const BASELINE = {
-  'solid-js': { line: 2, baseline: '2.0.0-rc.9' },
-  '@solidjs/web': { line: 2, baseline: '2.0.0-rc.9' },
-  '@solidjs/signals': { line: 2, baseline: '2.0.0-rc.9' },
-  '@solidjs/diagnostics': { line: 2, baseline: '2.0.0-rc.9' },
-  '@solidjs/router': { line: 2, baseline: '2.0.0-next.27' },
-  '@solidjs/vite-plugin': { line: 3, baseline: '3.0.0-next.44' },
+  'solid-js': { line: 2, baseline: '2.0.0-rc.14' },
+  '@solidjs/web': { line: 2, baseline: '2.0.0-rc.14' },
+  '@solidjs/signals': { line: 2, baseline: '2.0.0-rc.14' },
+  '@solidjs/diagnostics': { line: 2, baseline: '2.0.0-rc.14' },
+  '@solidjs/compiler': { line: 2, baseline: '2.0.0-rc.14' },
+  '@solidjs/babel-plugin': { line: 2, baseline: '2.0.0-rc.14' },
+  '@solidjs/router': { line: 2, baseline: '2.0.0-next.37' },
+  '@solidjs/vite-plugin': { line: 3, baseline: '3.0.0-next.47' },
   '@solidjs/testing-library': { line: 1, baseline: '1.0.0-beta.3' },
 };
 

package/bin/solid2-kit.mjs

@@ -480,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();
@@ -672,7 +695,7 @@ const CHECKS = [
     pattern: /<(?:HashRouter|MemoryRouter|Route|Navigate|A|FileRoutes|StartClient|StartServer)\b/g,
     exemptImportsFrom: TANSTACK_ROUTER_MODULE,
     message:
-      'Solid Router 0.x/1.x or SolidStart JSX. Define routes with createRouter({ routes }) / fileRoutes(pageRoutes) and plain <a href={Router.paths...}> (link state: automatic aria-current/data-active/data-pending + CSS, or useLinkState).',
+      'Solid Router 0.x/1.x or SolidStart JSX. Define routes with createRouter({ routes }) / fileRoutes(pageRoutes) and plain <a href={Router.paths...}> (link state: automatic aria-current/data-active + CSS, data-pending via createRouter({ links: pendingLinks }), or useLinkState).',
   },
   {
     id: 'meta-provider',
@@ -727,6 +750,23 @@ const CHECKS = [
     message:
       'React DOM prop. Native dblclick is onDblClick; keypress is onKeyDown; Solid has no suppressHydrationWarning.',
   },
+  {
+    // Only `on` + uppercase binds an event: since rc.14 a lowercase `on*`
+    // attribute is a plain attribute (dev warns [LOWERCASE_EVENT_ATTRIBUTE]),
+    // and a 1.x `on:click` is a plain namespaced attribute — neither runs the
+    // handler. A real event name in lowercase is always a leftover. Anchored
+    // on `={` (a JSX expression attribute): `const onmessage = ...`,
+    // `ws.onerror = fn`, and HTML strings (`onerror="…"`) are not matches,
+    // and neither is a string expression (`onclick={"track()"}`) — a string
+    // inline-handler attribute is the one legitimate lowercase use. The names
+    // are the GlobalEventHandlers / WindowEventHandlers set, so a custom
+    // attribute that merely starts with `on` (`one={…}`) is never flagged.
+    id: 'solid1-lowercase-event',
+    pattern:
+      /(?<=\s)on(?:abort|afterprint|animation(?:cancel|end|iteration|start)|auxclick|beforeinput|beforematch|beforeprint|beforetoggle|beforeunload|blur|cancel|canplay|canplaythrough|change|click|close|command|contextlost|contextmenu|contextrestored|copy|cuechange|cut|dblclick|drag|dragend|dragenter|dragleave|dragover|dragstart|drop|durationchange|emptied|ended|error|focus|focusin|focusout|formdata|fullscreenchange|fullscreenerror|gotpointercapture|hashchange|input|invalid|keydown|keypress|keyup|languagechange|load|loadeddata|loadedmetadata|loadstart|lostpointercapture|message|messageerror|mousedown|mouseenter|mouseleave|mousemove|mouseout|mouseover|mouseup|offline|online|pagehide|pagereveal|pageshow|pageswap|paste|pause|play|playing|pointercancel|pointerdown|pointerenter|pointerleave|pointermove|pointerout|pointerover|pointerrawupdate|pointerup|popstate|progress|ratechange|rejectionhandled|reset|resize|scroll|scrollend|search|securitypolicyviolation|seeked|seeking|select|selectionchange|selectstart|slotchange|stalled|storage|submit|suspend|timeupdate|toggle|touchcancel|touchend|touchmove|touchstart|transitioncancel|transitionend|transitionrun|transitionstart|unhandledrejection|unload|volumechange|waiting|wheel)\s*=\s*\{(?!\s*["'`])/g,
+    message:
+      'Lowercase `on*` is a plain attribute in Solid 2 (dev warns [LOWERCASE_EVENT_ATTRIBUTE]), not an event binding. Use the camelCase prop (onClick).',
+  },
   {
     id: 'history-nav',
     pattern: /\b(?:history\.pushState|history\.replaceState|window\.location\.href\s*=)/g,
@@ -749,6 +789,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,
@@ -1263,7 +1310,7 @@ 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.9` peer rejects.
+// @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",
@@ -1285,6 +1332,19 @@ function versionProblem(name, version, declared) {
   return null;
 }
 
+// An undeclared package on the baseline's major that a dependency pulled in
+// (the JSX compilers under @solidjs/vite-plugin): only the floor applies — a
+// lockfile keeps the version it first resolved. Another major is someone
+// else's copy, not the one the kit's guidance describes.
+function transitiveProblem(name, installed) {
+  const { line, baseline } = BASELINE[name];
+  if (!LOWER_BOUND.test(installed) || compareVersions(installed, `${line}.0.0-0`) < 0 || compareVersions(installed, `${line + 1}.0.0-0`) >= 0) {
+    return null;
+  }
+  if (compareVersions(installed, baseline) >= 0) return null;
+  return `older than ${baseline}, the release this kit's guidance is verified against. It is not in package.json, so a dependency installed it and the lockfile holds the old version: update it (\`npm update ${name}\`, \`pnpm update ${name}\`, or reinstall without the lockfile entry).`;
+}
+
 function installedVersion(target, name) {
   try {
     return JSON.parse(readFileSync(join(target, 'node_modules', name, 'package.json'), 'utf8')).version;
@@ -1312,7 +1372,12 @@ function doctorFindings(target) {
   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') continue;
+    if (typeof range !== 'string') {
+      const installed = BASELINE[name] && installedVersion(target, name);
+      const transitive = installed && transitiveProblem(name, installed);
+      if (transitive) report(id, `node_modules has ${name} ${installed} (not in package.json) — ${transitive}`);
+      continue;
+    }
     const declared = versionProblem(name, range, true);
     if (declared) {
       report(id, `package.json pins ${name} "${range}" — ${declared}`);

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
@@ -66,15 +68,17 @@ Steps:
      (`filter` for removal is fine — survivors keep identity; only fresh-tree wholesale
      replacement needs `reconcile` / the derived form);
    - hand-rolled link-active comparisons (`location.pathname === ...`) instead of the
-     automatic `aria-current` / `data-active` / `data-pending` attributes (+ CSS) or
+     automatic `aria-current` / `data-active` attributes (+ CSS) — `data-pending` is
+     opt-in via `createRouter({ links: pendingLinks })` — or
      `useLinkState` / `useIsRouting`; hand-rolled query parsing instead of
-     `useSearchParams`;
+     `useSearchParams`; <!-- upstream:pending-links-opt-in -->
    - search inputs bound to a held value without `latest`, effect-based debounce, fully
      controlled forms without `name`s, `{ success: false }` result objects instead of
      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. Creating a memo/effect/root inside an effect's `apply` callback throws in dev too (`[PRIMITIVE_IN_EFFECT_CALLBACK]`) — create it in the body or compute phase. <!-- upstream:primitive-in-effect-callback --> 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 `aria-current`/`data-active` + CSS (`data-pending` is opt-in via `createRouter({ links: pendingLinks })`; `useLinkState`/`useIsRouting` in JSX) <!-- upstream:pending-links-opt-in -->; 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

@@ -32,7 +32,11 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    Never write "a signal plus an effect that syncs it". That includes **reset**: to clear
    a signal when another reactive value changes, use a writable derivation —
    `createSignal(() => { source(); return initial; })` (re-runs when `source()` changes;
-   the setter still works) — never a `createEffect` whose apply calls the setter. The
+   the setter still works) — never a `createEffect` whose apply calls the setter. A write
+   lands at once; on the next source change the function re-runs receiving the write as
+   `prev` (a store receives it as the draft), so a function that ignores `prev` resets on
+   every source change — including a write staged in the same update — while one that
+   honors `prev` can keep the local value. <!-- upstream:derived-write-prev --> The
    derivation also moves the `source()` read to the read site, under its boundaries.
    (React needs `useState(props.x)` plus a `previousX` comparison reset for the same
    derive-override-reset behavior.)
@@ -59,6 +63,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `event.currentTarget` (the element that owns the handler), not `event.target`
     (a nested child). Never pass a setter as the handler (`onClick={setCount}`) —
     that writes the event object; wrap it: `onClick={() => setCount((c) => c + 1)}`.
+    Only `on` + uppercase binds an event: lowercase `onclick` is a plain attribute
+    (dev warns `[LOWERCASE_EVENT_ATTRIBUTE]`), not a handler.
+    <!-- upstream:lowercase-event-attribute -->
     Debounce at the handler (`onInput={debounce(...)}`), never as an effect copying
     one signal into another.
 7. **Lists use `<For>`**, never `{list().map(...)}` in reactive JSX and never `key` props (only `@solidjs/meta` tags take `key`, as the tag's identity).
@@ -125,14 +132,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
@@ -196,7 +207,11 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     updated *synchronous* state or DOM. Waiting on an async memo is
     `await resolve(() => value())` (or Testing Library async queries), not `flush()`.
     Never call `flush()` inside an `action`, an `onSettled` callback (throws in dev), or an
-    effect callback (a no-op, `[FLUSH_IN_EFFECT_CALLBACK]`).
+    effect callback (a no-op, `[FLUSH_IN_EFFECT_CALLBACK]`). Never create a memo, effect,
+    or root inside an effect callback either — it throws in dev
+    (`[PRIMITIVE_IN_EFFECT_CALLBACK]`, `runWithOwner(null, …)` included); create it in the
+    body or compute phase, or under `runWithOwner(owner, …)` with an owner captured in
+    the body. <!-- upstream:primitive-in-effect-callback -->
 14. Do not port these React tools — they have no Solid equivalent because the problems they
     solve don't exist: `useCallback`, `React.memo`, `forwardRef`, `useSyncExternalStore`,
     dependency arrays, `startTransition`/`useTransition` (updates are held and coordinated
@@ -240,7 +255,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     from `@solidjs/web` — do not call `captureException` inside `<Errored fallback>`.
     The server hook's return value replaces the sanitized error on the wire: return
     nothing or a reference id, never the error itself (message/stack/secrets would
-    reach the browser).
+    reach the browser). Failures outside render and server functions (middleware,
+    request setup) reach it via `reportRequestFailure(error, event)` as
+    `kind: "request"`. <!-- upstream:report-request-failure -->
     Making a client store "real" is additive: same setters, wrap mutations in
     `action`, swap in the **function form** `createOptimisticStore(() => api.list(), [])`
     (with `refresh` after the `yield`) and a file of server functions — do
@@ -323,9 +340,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 +366,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.
@@ -381,9 +400,14 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     the route is matched. One router instance —
     Solid Router does not support nested `<Router>` / nested `createRouter`.
     In-app navigation is `useNavigate` or `<a href={Router.paths...}>`, not
-    `window.location` / `history.pushState`. Link state is automatic
-    (`aria-current` / `data-active` / `data-pending` + CSS; `useLinkState` /
-    `useIsRouting` in JSX) — never hand-rolled `location.pathname` comparisons. Trusted identity is
+    `window.location` / `history.pushState`. Link state needs no component code:
+    `aria-current` (same path and same query) and `data-active` (path prefix, the
+    root exact-only) are automatic; `data-pending` is opt-in via
+    `createRouter({ links: pendingLinks })`. Style them in CSS — nav highlighting on
+    `data-active` (a nav link to `/products` loses `aria-current` on
+    `/products?page=2`); `useLinkState` /
+    `useIsRouting` in JSX — never hand-rolled `location.pathname` comparisons.
+    <!-- upstream:pending-links-opt-in --> Trusted identity is
     `getRequestEvent()`, never a caller-supplied user id. Unscripted (no-JS) POST
     forms use a router `action` over a `(form: FormData)` server function (the post
     arrives as one `FormData`; other signatures make `action={save}` TS2322) —
@@ -437,9 +461,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
@@ -493,22 +519,27 @@ directory (default `src/`).
 | `startTransition`, `useTransition` | automatic held updates + `isPending` |
 | `onError` / `catchError` | `<Errored>` or effect bundle `{ effect, error }` |
 | `from(...)` / `observable(...)` (the solid-js helpers) | inbound: async iterable from a memo; outbound: split effect |
-| `createDynamic(...)`, `<Dynamic component={...}>` (deprecated in 2.0) <!-- upstream:dynamic-deprecated --> | `dynamic(source)` from `@solidjs/web` |
+| `createDynamic(...)`, `<Dynamic component={...}>` (deprecated in 2.0) <!-- upstream:dynamic-deprecated --> | `dynamic(source)` from `@solidjs/web` — `dynamicComponent(source)` when the source only answers with a component <!-- upstream:dynamic-component-export --> |
 | `renderToStringAsync(...)` | `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`) |
 | `clearDelegatedEvents` | delete — delegated listeners are scoped to each render root |
 | `vite-plugin-solid` / `jsxImportSource: "solid-js"` | `@solidjs/vite-plugin` / `"jsxImportSource": "@solidjs/web"` |
-| JSX `<Route>` / `<A>` / `<HashRouter>` / `<Navigate>` / `<FileRoutes>` | `createRouter({ routes })`, `fileRoutes(pageRoutes)` (`fileRoutes` from `@solidjs/router/fs`, `pageRoutes` from `virtual:file-routes`), plain `<a href={Router.paths...}>`, `hashHistory()`; link state via automatic `aria-current` / `data-active` / `data-pending` + CSS (`useLinkState` in JSX) |
+| JSX `<Route>` / `<A>` / `<HashRouter>` / `<Navigate>` / `<FileRoutes>` | `createRouter({ routes })`, `fileRoutes(pageRoutes)` (`fileRoutes` from `@solidjs/router/fs`, `pageRoutes` from `virtual:file-routes`), plain `<a href={Router.paths...}>`, `hashHistory()`; link state via automatic `aria-current` / `data-active` + CSS and opt-in `data-pending` (`links: pendingLinks`), or `useLinkState` in JSX <!-- upstream:pending-links-opt-in --> |
 | `useCurrentMatches`, `MemoryRouter` / `createMemoryHistory`, `redirect` / `reload` from `@solidjs/router`, `indexArray` | `useRouteMatches`, `createRouter({ routes, history: memoryHistory("/x") })`, `redirect` / `reload` from `@solidjs/web`, `mapArray(list, fn, { keyed: false })` |
 | `createAsync` / `createAsyncStore` / `useSubmission` / router `json()` / `cache()` | `createMemo(() => getUser(id()))`, `useSubmissions`, `respond()` from `@solidjs/web`, `query` |
 | `import ... from "@solidjs/start"` / `vinxi` / `h3` / `"use client"` | `GET` from `@solidjs/web/server-functions`; Solid has no `"use client"` |
 | `render(<App />, root)` | `render(() => <App />, root)` (same for `hydrate` / `renderToString` / `renderToStream`) |
 | `<MetaProvider>` | no provider — render `<Title>` / `<Meta>` / `<Link>` from `@solidjs/meta` anywhere |
-| `use:directive`, `on:`/`oncapture:`, `attr:`/`bool:`, `/*@once*/` | `ref` callbacks, camelCase event props, standard attributes, keep values reactive; `prop:` remains for DOM properties (`prop:indeterminate`, objects/arrays on custom elements — plain props are attributes and stringify) |
+| `use:directive`, `on:`/`oncapture:`, `attr:`/`bool:`, `/*@once*/` (also lowercase `onclick`-style attributes — plain attributes, not events <!-- upstream:lowercase-event-attribute -->) | `ref` callbacks, camelCase `on`-capitalized event props, standard attributes, keep values reactive; `prop:` remains for DOM properties (`prop:indeterminate`, objects/arrays on custom elements — plain props are attributes and stringify) |
 | `resource.loading` / `resource.error` | `<Loading>` boundary / `<Errored>` boundary |
 
 When unsure about any API, verify against the official Solid 2.0 docs — fetchable URLs are
 listed in `references/official-docs.md` next to the `solid-2` skill. Do not guess from
-Solid 1.x or React memory.
+Solid 1.x or React memory. Two official pages still describe the previous release —
+these rules win there: the router navigation page lists `data-pending` as automatic
+(it needs `links: pendingLinks`) <!-- upstream:docs-pending-links-stale -->, and the
+`createSignal` reference says a write to a writable derivation wins over a same-tick
+recompute (a source change in the same update now re-runs it with the write as
+`prev`). <!-- upstream:docs-derived-write-stale -->
 
 `createRenderEffect` exists in Solid 2 but is not a default. `storePath`
 (the 1.x path-setter migration helper) is no longer exported from `solid-js` as of

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

@@ -39,7 +39,7 @@ Practical consequences:
 | Object that is replaced wholesale (fetch response, selected item, `User \| null`) | `createSignal(objectValue)` |
 | Value derived from other reactive values | plain function `() => ...` (never a signal synced by an effect) |
 | Expensive derivation, multiple consumers, or equality boundary needed | `createMemo(() => ...)` |
-| Follows a prop but user can locally override; prop change resets | writable derivation: `createSignal(() => props.value)` / `createStore(() => props.value, fallback)` |
+| Follows a prop but user can locally override; prop change resets | writable derivation: `createSignal(() => props.value)` / `createStore(() => props.value, fallback)` — a write lands at once and the function receives it as `prev` (the draft on a store) on re-run; honoring `prev` keeps the edit across source changes <!-- upstream:derived-write-prev --> |
 | Shared by a subtree, independent per provider instance | signal/store created inside a provider component, passed via context |
 | App-wide state (theme, session, cart, locale) | the same provider, placed at the root of `App` — not a module-level signal/store (under SSR one module instance serves every request) |
 | Constants (a category list, a formatter, the `createContext` call) | module scope |
@@ -69,12 +69,12 @@ Most React `useEffect` code should NOT become `createEffect`:
 | Inspect, count, or iterate children | `children(() => props.children)` then `.toArray()` |
 | Code-split a component | `lazy(() => import("./X"))` read under `<Loading>` |
 | Named export from a lazy module | `lazy(() => import("./pages"), { export: "About" })` |
-| Pick a component/tag from reactive state | `dynamic(() => ...)` from `@solidjs/web` (stable identity; `<Dynamic>` is deprecated) <!-- upstream:dynamic-deprecated --> |
+| Pick a component/tag from reactive state | `dynamic(() => ...)` from `@solidjs/web` (stable identity; `<Dynamic>` is deprecated) <!-- upstream:dynamic-deprecated --> — `dynamicComponent(() => ...)` when the source only answers with a component, never a tag <!-- upstream:dynamic-component-export --> |
 | Overlay / modal | `<Portal>` — hoist async reads *above* the portal (reads inside start on the client) |
 | 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
@@ -264,6 +268,13 @@ is **deprecated** since 2.0.0-rc.9 — `@deprecated` in the types, no runtime wa
 still shipped in 2.0. <!-- upstream:dynamic-deprecated --> Hoist a `dynamic()` per component instance (or per module for a
 constant tag) instead.
 
+When the source only ever answers with a component — never a tag name — use
+`dynamicComponent()` instead: same contract and hydration shape minus the tag arm, so
+a tag name is a compile error and a page whose only dynamic mounts are components
+retains no element runtime (`createElement` / `spread` / the namespace tables). It
+is the documented way to mount a server component: `dynamicComponent(() =>
+getStory(props.id))`. <!-- upstream:dynamic-component-export -->
+
 ### Two-phase effect (imperative boundary only)
 
 ```tsx
@@ -327,7 +338,12 @@ const [signInError, setSignInError] = createSignal<string | null>(() => {
 ```
 
 The writable form spells exactly this: derive from the source, allow a local
-override, reset when the source changes. (React needs `useState(props.x)` plus a
+override, reset when the source changes. The mechanics: a write lands at once,
+and on the next source change the function re-runs receiving the write as `prev`
+(a store receives it as the draft). A function that ignores `prev` resets — this
+pattern — and also discards a write staged in the same update as a source change;
+one that honors `prev` can keep the local value. <!-- upstream:derived-write-prev -->
+(React needs `useState(props.x)` plus a
 `previousX` comparison reset during render for the same behavior.)
 
 ### Async data — fetch high, block low
@@ -399,8 +415,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 +446,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
@@ -498,7 +519,11 @@ rendered), `render` / `client` (a `<Loading>` fragment rejected, client re-rende
 hydration value would not serialize), `server-function` / `thrown` (`direct: true` for
 an in-process call during SSR), `server-function` / `channel` (a rejection or throw
 escaping through the result graph — a promise, an iterable, or a stream — after the
-head committed). A monitoring SDK's `init()` that
+head committed), and `request` / `failed` — a failure outside render and server
+functions (middleware, request setup) reported via
+`reportRequestFailure(error, event)` from `@solidjs/web`. A synchronous throw out of
+`renderToString` / `renderToStream`'s first pass is reported `render` / `failed`
+before rethrow. <!-- upstream:report-request-failure --> A monitoring SDK's `init()` that
 registers this hook must load before the server graph — put it in the plugin's
 `start: { instrument: "./src/instrument.ts" }`, not at the top of an entry (see
 [Production observability](#production-observability-the-observe-build)).
@@ -956,7 +981,12 @@ onSettled(() => {
 
 Effect callbacks follow the same shape: return the cleanup from `apply` (an
 `onCleanup` there never runs), and `flush()` inside one is a no-op
-(`[FLUSH_IN_EFFECT_CALLBACK]`).
+(`[FLUSH_IN_EFFECT_CALLBACK]`). Creating a memo, an effect, or a root inside `apply`
+throws in dev (`[PRIMITIVE_IN_EFFECT_CALLBACK]` — the effect phase has no owner to
+dispose them; `runWithOwner(null, …)` does not lift it): create them in the
+component body or the compute phase, or attach them to an owner captured with
+`getOwner()` in the body via `runWithOwner(owner, …)`.
+<!-- upstream:primitive-in-effect-callback -->
 
 ### Per-value SSR policy: `ssrSource`
 
@@ -988,8 +1018,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 +1098,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 +1126,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 +1156,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 +1178,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.
 
@@ -1202,11 +1252,19 @@ 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.
+   The six attribution cost checks (`hotRuns`, `hotTime`, `wideDeps`, `unstableMemos`,
+   `fanOut`, `wastedRecompute`) are opt-in there: `performanceTracks: { attribution:
+   { checks: true } }` (or `enablePerformanceTracks({ attribution: { checks: true } })`,
+   or your own `attribution.enable()` hold — the diagnostics-session path above already
+   turns them on). <!-- upstream:perf-tracks-cost-checks -->
 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
@@ -1233,14 +1291,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
@@ -1257,22 +1317,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
@@ -1355,7 +1424,8 @@ export default function App() {
 
 The `<Loading>` covers the first load of the lazy pages (and lets SSR stream the shell);
 later navigations hold the current page while the next one loads (links get
-`data-pending`). Create the instance at **module scope**. Nested layouts are `children` arrays
+`data-pending` when the router is created with `links: pendingLinks`
+<!-- upstream:pending-links-opt-in -->). Create the instance at **module scope**. Nested layouts are `children` arrays
 on the route objects, not nested `<Route>` / nested routers. Solid Router does
 **not** support nested `<Router>` instances — compose one route tree (or a lazy
 `children` thunk). Navigate with
@@ -1418,13 +1488,20 @@ Link warming: `preload="false"` skips that link's *data* preload; `preloadLinks:
 disables automatic link preloading. Intent values are `"initial"` / `"navigate"` /
 `"native"` / `"preload"`. One router per app.
 
-Link state needs no component code: the router sets `aria-current="page"` (exact
-match), `data-active` (exact or descendant — the `/` link is active only on exact
-match), and `data-pending` (in-flight navigation target) on the anchors it handles;
-style them in CSS. For non-anchors, or state needed in JSX, `useLinkState(() => href,
-{ end })` returns the same three as accessors (`active` / `current` / `pending`);
-`useIsRouting()` is the page-level pending flag for progress bars. Hand-rolled
+Link state needs no component code: the router sets `aria-current="page"` (same path
+and same query — parameter order and hash aside), `data-active` (exact or descendant
+on the path only — the `/` link is active only on exact match), and, with the opt-in
+`createRouter({ links: pendingLinks })` plugin, `data-pending` (in-flight navigation
+target) on the anchors it handles; style them in CSS. Highlight nav links on
+`data-active`, not `aria-current`: a nav link to `/products` is not current on
+`/products?page=2`. An `aria-current` you write
+yourself is yours — the router only manages the attribute on links where it set it.
+For non-anchors, or state needed in JSX, `useLinkState(() => href,
+{ end })` returns the same three as accessors (`active` / `current` / `pending` —
+`pending` works without the plugin); `useIsRouting()` is the page-level pending
+flag for progress bars. Hand-rolled
 `location.pathname === ...` comparisons are the wrong tool.
+<!-- upstream:pending-links-opt-in -->
 
 Build URLs from `paths`: static segments are properties (`Router.paths.about`, never
 `Router.paths.about()`), parameterized segments are calls (`paths.products(id)`),
@@ -1642,10 +1719,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
@@ -1673,7 +1750,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
@@ -1806,7 +1886,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>` |
@@ -1814,6 +1894,7 @@ how to reuse. Prefer the form on the right.
 | `lazy(() => import("./p").then((m) => ({ default: m.About })))` | `lazy(() => import("./p"), { export: "About" })` |
 | `dangerouslySetInnerHTML={{ __html }}` | `innerHTML={html()}` (sanitized); never with JSX children |
 | `onClick={setCount}` | `onClick={() => setCount((c) => c + 1)}` |
+| `onclick={fn}` / `onmouseover={fn}` (lowercase handlers) | `onClick={fn}` — a lowercase `on*` name is a plain attribute (dev warns `[LOWERCASE_EVENT_ATTRIBUTE]`), not an event <!-- upstream:lowercase-event-attribute --> |
 | `event.target.value` | `event.currentTarget.value` |
 | `createContext(emptyStore)` for reactive state | `createContext<Todos>()` — dummy defaults silently no-op |
 | `<For keyed={(t) => t.id}>{(todo) => todo.title}` | `todo().title` — key-function items are accessors |
@@ -1838,7 +1919,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` |
@@ -1865,7 +1946,7 @@ how to reuse. Prefer the form on the right.
 | `action={"/_server/" + id}` / `action={createTodo.url}` on a POST form | a router action: `const save = action(createTodo, "create-todo")` + `<form action={save} method="post">` over a `(form: FormData)` server function (other signatures are TS2322) — `.url` on a bare `"use server"` function is TS2339; it is typed only on `GET()` / `live()` references (GET search forms) |
 | `<form method="get" action={update.url}>` for a mutation | GET forms only for idempotent search; mutations are POST |
 | `window.location.href = ...` / `history.pushState` | `useNavigate()` or `<a href={Router.paths...}>` |
-| `class={{ active: location.pathname === "/about" }}` hand-rolled link state | CSS on automatic `aria-current` / `data-active` / `data-pending`; `useLinkState` in JSX, `useIsRouting()` for progress bars |
+| `class={{ active: location.pathname === "/about" }}` hand-rolled link state | CSS on `aria-current` / `data-active` (+ `data-pending` via `links: pendingLinks`); `useLinkState` in JSX, `useIsRouting()` for progress bars <!-- upstream:pending-links-opt-in --> |
 | `new URLSearchParams(location.search)` hand-rolled query parsing | `useSearchParams()` (setter merges, no scroll); typed via a route `search` schema + `useSearchParams(Router.paths.search)` |
 | `Router.paths.about()` / string-concatenated URLs | static nodes are properties (`Router.paths.about`); calls bind params, then search object and hash |
 | `httpStatus(404)` in a click handler | call it bare in the component / error-fallback body (a scope declaration, not a mutation) |
@@ -1901,7 +1982,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` |
@@ -2046,6 +2127,16 @@ agent use the mirror, which serves every page as plain markdown:
 
 A curated URL list is in [references/official-docs.md](references/official-docs.md).
 
+Known stale pages — this skill is verified against the installed release and wins:
+
+- `routing/solid-router/navigation` lists `data-pending` among the attributes the router
+  sets on its own; it needs `createRouter({ links: pendingLinks })`, and `aria-current`
+  also compares the query (the link-state paragraph under Solid Router 2 above).
+  <!-- upstream:docs-pending-links-stale -->
+- `reference/solid-js/reactivity/create-signal` says a write to a writable derivation
+  wins over a same-tick recompute; a source change in the same update re-runs the
+  function, which receives the write as `prev`. <!-- upstream:docs-derived-write-stale -->
+
 **Never** consult Solid 1.x sources (docs.solidjs.com, pre-2.0 tutorials, old Stack Overflow).
 Solid 2.0 is a breaking rewrite; 1.x answers are wrong here. The banned-API table is in the
 always-applied rules installed alongside this skill.
@@ -2112,7 +2203,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()`
@@ -2130,8 +2221,8 @@ always-applied rules installed alongside this skill.
       core `action`/`refresh`. Forms: `<form action={save} method="post">`. Core `action`
       bodies are generators (`function*` / `async function*`) suspending on `yield`,
       never plain `async` functions. Link state is automatic attributes + CSS
-      (`aria-current` / `data-active` / `data-pending`; `useLinkState` / `useIsRouting`
-      in JSX). Search params via `useSearchParams`. Forms validate on the server
+      (`aria-current` / `data-active`, `data-pending` via `links: pendingLinks`;
+      `useLinkState` / `useIsRouting` in JSX). <!-- upstream:pending-links-opt-in --> Search params via `useSearchParams`. Forms validate on the server
       (`throw respond({ issues }, { status: 400 })`) with inline errors from
       `useSubmissions`.
 - [ ] `render(() => <App />, root)` — a function, not `render(<App />)`. `hydrate` when

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.18.0",
+  "version": "0.20.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",