solid2-agent-kit 0.20.0 → 0.22.0

package/bin/baseline.mjs

@@ -18,14 +18,14 @@
 // 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.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' },
+  'solid-js': { line: 2, baseline: '2.0.0-rc.15' },
+  '@solidjs/web': { line: 2, baseline: '2.0.0-rc.15' },
+  '@solidjs/signals': { line: 2, baseline: '2.0.0-rc.15' },
+  '@solidjs/diagnostics': { line: 2, baseline: '2.0.0-rc.15' },
+  '@solidjs/compiler': { line: 2, baseline: '2.0.0-rc.15' },
+  '@solidjs/babel-plugin': { line: 2, baseline: '2.0.0-rc.15' },
+  '@solidjs/router': { line: 2, baseline: '2.0.0-next.39' },
+  '@solidjs/vite-plugin': { line: 3, baseline: '3.0.0-next.50' },
   '@solidjs/testing-library': { line: 1, baseline: '1.0.0-beta.3' },
 };
 

package/bin/solid2-kit.mjs

@@ -767,6 +767,15 @@ const CHECKS = [
     message:
       'Lowercase `on*` is a plain attribute in Solid 2 (dev warns [LOWERCASE_EVENT_ATTRIBUTE]), not an event binding. Use the camelCase prop (onClick).',
   },
+  {
+    // `preloadLinks` takes link preload strategies since @solidjs/router
+    // 2.0.0-next.38 and preloads nothing by default: `true` (the old on switch)
+    // preloads nothing and only warns in dev, and `false` is a no-op.
+    id: 'preload-links-boolean',
+    pattern: /\bpreloadLinks\s*:\s*(?:true|false)\b/g,
+    message:
+      '`preloadLinks` takes link preload strategies, not a boolean, and preloads nothing by default. Hover/focus warming is preloadLinks: intentPreload() (from "@solidjs/router"); to disable it, omit the option.',
+  },
   {
     id: 'history-nav',
     pattern: /\b(?:history\.pushState|history\.replaceState|window\.location\.href\s*=)/g,

package/files/commands/solid2-review.md

@@ -71,7 +71,9 @@ Steps:
      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`; <!-- upstream:pending-links-opt-in -->
+     `useSearchParams`; <!-- upstream:pending-links-opt-in --> route `preload`
+     functions written to run on hover in a router without `preloadLinks: intentPreload()`
+     (link preloading is opt-in; a boolean `preloadLinks` preloads nothing) <!-- upstream:preload-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(...)`)

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. 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.
+- 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 -->; link preloading is opt-in too (`preloadLinks: intentPreload()` for hover/focus; none by default) <!-- upstream:preload-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

@@ -397,7 +397,10 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `createMemo(() => getProduct(props.params.id))`. `props.data` is whatever `preload`
     returned when the route first matched: it does not follow param changes (and an async
     `preload` makes it a Promise), so return a value only for data that stays fixed while
-    the route is matched. One router instance —
+    the route is matched. Link warming is opt-in: route code and `preload` run ahead of
+    the click only with a strategy — `createRouter({ routes, preloadLinks: intentPreload() })`
+    for hover/focus (none by default; a boolean `preloadLinks` only warns in dev).
+    <!-- upstream:preload-links-opt-in --> 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 needs no component code:
@@ -519,7 +522,7 @@ 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` — `dynamicComponent(source)` when the source only answers with a component <!-- upstream:dynamic-component-export --> |
+| `createDynamic(...)`, `<Dynamic component={...}>` (deprecated in 2.0) <!-- upstream:dynamic-deprecated --> | `dynamic(source)` from `@solidjs/web` — `dynamicComponent(source)` from `solid-js` 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"` |
@@ -534,12 +537,14 @@ directory (default `src/`).
 
 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. Two official pages still describe the previous release —
+Solid 1.x or React memory. Some 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
+(it needs `links: pendingLinks`) <!-- upstream:docs-pending-links-stale -->, 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 -->
+`prev`) <!-- upstream:docs-derived-write-stale -->, and the performance guide and
+attribution reference give `[WIDE_SCOPE_DEPS]` a threshold of 30 (the default
+`wideDeps` is 200). <!-- upstream:docs-wide-deps-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

@@ -69,7 +69,7 @@ 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 --> — `dynamicComponent(() => ...)` when the source only answers with a component, never a tag <!-- upstream:dynamic-component-export --> |
+| Pick a component/tag from reactive state | `dynamic(() => ...)` from `@solidjs/web` (stable identity; `<Dynamic>` is deprecated) <!-- upstream:dynamic-deprecated --> — `dynamicComponent(() => ...)` from `solid-js` 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)`) |
@@ -238,7 +238,10 @@ const About = lazy(() => import('./pages'), { export: 'About' });
 Never `React.lazy` / `<Suspense>`. The lazy component suspends through
 `<Loading>` on first render; `.preload()` starts the import early. Named
 exports must use `{ export: "About" }` — a `.then((m) => ({ default: m.About }))`
-wrapper hydrates incorrectly (the name is not a call-site literal).
+wrapper hydrates incorrectly (the name is not a call-site literal). A module that is
+not a component (a route table, a parser) takes `lazyModule(() => import("./x"))` from
+`solid-js`: call it (or `.preload()`) for the cached promise, `.peek()` for the module
+once it has landed; the server preloads it before hydration by module id.
 
 ### Dynamic component: `dynamic()` (canonical)
 
@@ -269,7 +272,8 @@ still shipped in 2.0. <!-- upstream:dynamic-deprecated --> Hoist a `dynamic()` p
 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
+`dynamicComponent()` from `solid-js` instead (`@solidjs/web` re-exports it): 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(() =>
@@ -548,29 +552,66 @@ and thrown errors reach `<Errored>`. Integration layers should return a plain ac
 ```tsx
 import { createMemo, onCleanup } from 'solid-js';
 
-function createSubscriptionQuery<T>(
-  subscribe: (next: (value: T) => void, fail: (error: unknown) => void) => () => void,
+function createSubscriptionQuery<A, T>(
+  args: () => A,
+  subscribe: (args: A, next: (value: T) => void, fail: (error: unknown) => void) => () => void,
+  name: string,
 ) {
-  const queue: T[] = [];
-  let failure: unknown;
-  let wake = () => {};
-  // Custom primitive: unsubscribe is tied to the caller's owner via onCleanup.
-  // Component bodies use onSettled and return cleanup instead.
-  onCleanup(subscribe(
-    (value) => { queue.push(value); wake(); },
-    (error) => { failure = error; wake(); },
-  ));
-
-  return createMemo(() => (async function* () {
-    while (true) {
-      if (failure !== undefined) throw failure;
-      if (queue.length > 0) { yield queue.shift() as T; continue; }
-      await new Promise<void>((resolve) => { wake = resolve; });
-    }
-  })());
+  return createMemo(() => {
+    const resolved = args(); // tracked, and read before any await: a change re-subscribes
+    let current: T | undefined;
+    let version = 0;
+    let failure: unknown;
+    let disposed = false;
+    let wake = () => {};
+    const unsubscribe = subscribe(
+      resolved,
+      (value) => { current = value; version += 1; failure = undefined; wake(); },
+      (error) => { failure = error; wake(); },
+    );
+    // Inside a computation, onCleanup runs before the next run and on disposal.
+    onCleanup(() => { disposed = true; unsubscribe(); wake(); });
+
+    return (async function* () {
+      let seen = 0;
+      while (!disposed) {
+        if (failure !== undefined) throw failure;
+        if (version > seen) { seen = version; yield current as T; continue; }
+        await new Promise<void>((resolve) => { wake = resolve; });
+      }
+    })();
+  }, { name }); // e.g. `query:${functionName}` — attribution tables name rows by it
 }
 ```
 
+Open the subscription **inside the compute**, not around the memo. Then a change of
+`args` closes the old subscription and opens the new one, `refresh(query)` and
+`<Errored>`'s `reset` re-run the compute into a fresh subscription with the failure
+cleared (a subscription opened outside the memo keeps its failure, so a retry never
+recovers), and unmounting the owner closes it. Results that are snapshots (query
+results) conflate to the latest value, as above; an event stream where every message
+matters keeps a queue instead. A memo's compute runs **when it is created**, not on
+first read (only `{ lazy: true }` defers it, and that also tears the memo down whenever
+nothing observes it), so a subscription memo created in a provider connects even if
+nothing reads it — resolve the client inside the compute and return a never-settling
+iterable when there is none, rather than constructing it at module scope.
+
+Identity-like subscriptions (the session, the current user) are app-wide state
+(rule 11): create them **once**, in a provider at the root. One per page is torn down
+on unmount and re-opened on mount, so every navigation starts with a fallback for one
+round trip, and a page query that waits on it behind its own boundary is a sequential
+pair — `[ASYNC_WATERFALL]` under attribution.
+
+Clients that share one subscription per query-and-args and hand its current value to
+every new subscriber (Convex, most reactive database clients) prefetch by subscribing
+**early**: in the route's `preload` on link intent (`preloadLinks: intentPreload()` on
+the router — without a strategy nothing preloads on hover <!-- upstream:preload-links-opt-in -->), held open for a short grace period
+(seconds) and released at once on error, so a hover while signed out leaves no failure
+for the page to inherit. Skip `intent === "initial"` there — on the first match the page
+subscribes on mount anyway, and an identity-gated read would run before the session is
+restored. Nothing is cached outside the client; the page's own subscription is the only
+one left when the hold expires.
+
 Server-function `live()` sources are the same shape (async iterable → memo). Connection
 state is `source.onstatus` (`"connected"` / `"reconnecting"` / `"closed"`), not a field
 in the yielded value — see [Server functions](#server-functions--use-server).
@@ -799,6 +840,30 @@ Never `{todos().map((t) => <Row todo={t} />)}` and never `<For each={todos().map
 The `.map` form *renders*; it just rebuilds every row. `children().toArray().map` is
 fine — those nodes are already resolved.
 
+Join and narrow **upstream of the list**, not per row. A row that narrows its own
+lookup — `<For each={layout().cards}>{(card) => <Show when={byKey().get(card().key)}>…}` —
+makes every row a reactive source of the list's insert effect (one per row; a plain
+element or component row costs none), so every row change re-runs one effect that
+tracks the whole list. Nothing flags it below 2000 rows: `[WIDE_SCOPE_DEPS]` skips that
+insert pass by design (and defaults to 200 sources), and only the always-on
+`[HUGE_FAN_IN]` reports it, from 2000 — so this is a review rule, not something a
+diagnostics gate catches. <!-- upstream:per-row-show-insert-sources --> Build the joined
+rows in one memo and iterate those; `flatMap` drops the misses without a `!`:
+
+```tsx
+const cards = createMemo(() => {
+  const byKey = new Map(props.matches.map((m) => [m.key, m]));
+  return layout().cards.flatMap((card) => {
+    const match = byKey.get(card.key);
+    return match === undefined ? [] : [{ card, match }];
+  });
+}, { name: "cards" });
+
+<For each={cards()} keyed={(row) => row.card.key}>
+  {(row) => <MatchCard match={row().match} x={row().card.x} />}
+</For>
+```
+
 `<Repeat from={start()} count={20}>{(index) => ...}</Repeat>` renders by absolute index with
 no array diffing — use for fixed slot counts and virtual scrolling windows.
 
@@ -1075,12 +1140,22 @@ write and `flush()`: `const { setA, b, dispose } = createRoot((dispose) => { …
 the test — `createRouter({ routes, history: memoryHistory("/orders/42") })` — because
 Testing Library's `render(…, { location })` is typed but not implemented (1.0.0-beta.3). <!-- upstream:testing-library-location -->
 
+An end-to-end test that must wait for hydration of an SSR page waits on a marker set from
+`onHydrationEnd` (`solid-js`, `@experimental`): register it *after* `hydrate()`, e.g.
+`onHydrationEnd(() => { document.documentElement.dataset.hydrated = ""; })`. It fires when
+the hydration phase ends — including when a module preload failed and the markup was left
+non-interactive — so it is a test-tooling marker, never a branch for what the app renders
+(`isHydrating()` / `onSettled` own that). Outside hydration it runs in the next microtask.
+<!-- upstream:hydration-end-experimental -->
+
 `jsxImportSource` for tests and app code is `"@solidjs/web"`, not `"solid-js"`.
 Vite plugin is `@solidjs/vite-plugin`, not `vite-plugin-solid`.
 
-To turn those dev diagnostics into a hard gate, patch `console.warn` in the test setup
-file to rethrow unexpected warnings — then any top-level reactive read or unowned write
-an agent sneaks in fails the suite instead of scrolling by.
+To turn those dev diagnostics into a hard gate on every test, capture them per test
+with `@solidjs/diagnostics` — see
+[Gating every test on diagnostics](#gating-every-test-on-diagnostics). Patching
+`console.warn` sees only what the console reporter prints, and none of the
+attribution-tier findings or the hold tables.
 
 ### Dev diagnostics and attribution
 
@@ -1208,7 +1283,9 @@ expect(artifact).toHaveNoDiagnostics();
 expect(artifact).toHaveNoSilentHolds();
 ```
 
-`toHaveNoDiagnostics` fails on any coded warning (`info` findings excluded);
+`toHaveNoDiagnostics` fails on every captured finding, `info` ones included
+(`[FALLBACK_FLASH]`, `[OPTIMISTIC_REVERTED]`, …) — its `allow` list names codes to
+tolerate;
 `toStayWithinRerunBudget` / `toHaveNoWaste` catch recompute regressions. The
 `agent-loops` skill the package ships
 (`node_modules/@solidjs/diagnostics/skills/agent-loops/SKILL.md`) documents the agent
@@ -1216,6 +1293,101 @@ verification loops: capture until the channel is quiet, scenario budgets as the
 definition of done, and hold/latency gates. See the debugging-reactivity guide in
 [references/official-docs.md](references/official-docs.md).
 
+### Gating every test on diagnostics
+
+Solid grades its findings `info` / `warn` / `error` and offers no switch to escalate
+them, so "diagnostics are errors" is enforced in tests. The shape that holds up is a
+setup file that wraps **every** test body in one capture, so a test written by someone
+who never heard of the engine is gated anyway:
+
+```ts
+// src/test-setup.ts — listed in the vitest project's `setupFiles`
+import { afterEach, beforeEach } from 'vitest';
+import { flush } from 'solid-js';
+import { captureArtifact, expectNoDiagnostics, expectNoSilentHolds } from '@solidjs/diagnostics';
+
+let end: (() => void) | undefined;
+let capture: ReturnType<typeof captureArtifact<void>> | undefined;
+export const roots: (() => void)[] = []; // a `mount()` helper pushes each render's dispose
+
+beforeEach((context) => {
+  if (capture) throw new Error('tests under the gate must run sequentially');
+  capture = captureArtifact<void>(() => new Promise<void>((resolve) => { end = resolve; }), {
+    scenario: context.task.name,
+    attribution: { hotTime: false, fallbackFlashes: false }, // wall-clock: see below
+  });
+});
+
+afterEach(async () => {
+  for (const dispose of roots.splice(0).reverse()) dispose();
+  flush();
+  end?.();
+  const pending = capture;
+  capture = undefined;
+  if (pending === undefined) throw new Error('this test ran outside the gate');
+  const { artifact } = await pending; // close the capture before asserting anything
+  expectNoDiagnostics(artifact);
+  expectNoSilentHolds(artifact);
+});
+```
+
+What the shape has to get right:
+
+- **A DOM environment** (`happy-dom` / `jsdom`) for every reactive test, `.test.ts`
+  included. Under vitest's `node` environment the export conditions select Solid's
+  **server build**: writes are inert (`[SERVER_WRITE]`), effects never run, and the
+  attribution tables stay empty — a green test that proves nothing. Components that only
+  exist in the server build (a `<html>` document shell) get their own `node` project
+  rendered with `renderToString`, outside the gate.
+- **No HMR transform in the test project**: `solid({ refresh: { disabled: true } })`.
+  The refresh transform wraps every component declaration in a memo, so the graph
+  under test is not the graph production ships, and tests have no HMR to serve. (The
+  wrappers are marked as plumbing, so the engine does not count them as sources.)
+  <!-- upstream:per-row-show-insert-sources -->
+- **Two assertions, not one.** `[SILENT_HOLD]` is emitted only once a hold outlasts
+  `holds.infoMs` (100ms), so a shorter unacknowledged hold is recorded and coded
+  nowhere; `expectNoSilentHolds` asks the hold table, where no threshold applies.
+- **Wall-clock checks off where the clock means nothing.** `hotTime`'s 8ms budget is
+  half a real browser frame; an emulated DOM spends more than that rendering a page, and
+  a loaded runner several times more, so the failure names an innocent component.
+  `[FALLBACK_FLASH]` measures backend latency, and a fake that settles at once flashes
+  every fallback. Keep the count-based and structural checks (holds, waterfalls, list
+  identity, wide scopes); measure time in a real browser.
+- **Sequential tests only.** The diagnostics channel and the engine are process-global,
+  so under `test.concurrent` one test's finding lands in another's artifact — refuse the
+  overlap rather than blame the wrong test.
+- **Dispose what the test mounted** before the capture closes. A root left alive re-runs
+  on later writes, and its finding fails whichever test is open then.
+- **Settle deferred work** (`await resolve(...)`, `flush()`) before the body returns: an
+  un-awaited timer or promise lands in the next test's capture, or in none. Module scope
+  runs before the first capture opens — keep fixtures there, never a render.
+- **The app's own `attribution.enable()` stands down under a harness**
+  (`if (import.meta.env.VITEST) return;`, and in the browser gate's mode). A hold taken
+  while the engine is enabled opens a fresh window over `history()` / `costs()` /
+  `feedback()`, which erases what the capture recorded so far, and options combine by
+  the most demanding value per key, so the app's default hold re-arms every threshold
+  the gate turned off. <!-- upstream:attribution-hold-window -->
+- **A test whose subject is a finding requires it** (`expectDiagnostic(artifact, code)`
+  and then `allow` it), so the test fails when it stops provoking the code instead of
+  decaying into a mute. Never `allow` a finding about real code.
+- **Fixtures above the threshold** for scale-dependent codes. `[WIDE_SCOPE_DEPS]` fires
+  at 200 dependencies by default, `[HUGE_FAN_OUT]` / `[HUGE_FAN_IN]` and
+  `[HOT_SCOPE_RERUNS]` at their own counts, so a fixture of three rows cannot falsify a
+  per-row cost. When a gate is meant to catch one, give it a fixture past the code's
+  threshold (or a lower threshold in the capture's `attribution` options) and check it
+  fails with the defect re-injected. A per-row cost in a list's own insert pass is
+  outside `[WIDE_SCOPE_DEPS]` entirely (see [Lists](#lists-for-child-signatures-per-keying-mode)).
+
+An emulated DOM cannot see everything, so keep one **real-browser gate** for the main
+path: `captureBrowserArtifact(page, interact, { scenario })` from
+`@solidjs/diagnostics/playwright` drives the same capture through the bridge the Vite
+plugin injects into `vite dev`, and returns the same artifact, so one verdict function
+judges both. Serve that dev server in a dedicated mode with `refresh: { disabled: true }`
+and `performanceTracks: false`: the tracks paint every record from inside the scopes the
+engine times, enough to push a page's first render past the 8ms `[HOT_SCOPE_TIME]`
+budget. The wall-clock thresholds mean something there — except `fallbackFlashes`
+against a backend on loopback.
+
 ### Development loop: self-diagnose before finishing
 
 Enable observability in development **by default** and lean on it. The dev build
@@ -1436,7 +1608,7 @@ Session location is `useLocation` / `useParams`,
 not `Router.paths`.
 
 **Route `preload` starts reads; the page reads them in a memo.** `preload` runs when
-the route matches (and on link hover), so it should kick off the query and return
+the route matches (and ahead of a click under a `preloadLinks` strategy <!-- upstream:preload-links-opt-in -->), so it should kick off the query and return
 nothing; the component reads the same query through a memo that tracks the params:
 
 ```tsx
@@ -1484,15 +1656,27 @@ data that stays fixed while the route is matched. The factory `preload` on
 undefined` per key) — wrap a route in `defineRoute` when `preload` or the component
 needs `params.id: string`.
 
-Link warming: `preload="false"` skips that link's *data* preload; `preloadLinks: false`
-disables automatic link preloading. Intent values are `"initial"` / `"navigate"` /
-`"native"` / `"preload"`. One router per app.
+Link warming is **opt-in**: `createRouter({ routes, preloadLinks: intentPreload() })`
+warms a link's route code and runs its `preload` on hover (after a short delay), focus
+and touch. Without `preloadLinks` nothing preloads ahead of the click. The other
+strategies, all from `@solidjs/router` and combinable as an array: `tapPreload()`
+(pointerdown), `viewportPreload()` and `eagerPreload()` (code only by default, for links
+marked `preload="viewport"` / `preload="eager"`, or every link with `{ all: true }`).
+`preload="false"` on an anchor opts that link out; `usePreloadRoute()` warms a route by
+hand. A boolean `preloadLinks` (the old on/off switch) only warns in dev and preloads
+nothing. <!-- upstream:preload-links-opt-in --> Intent values are `"initial"` /
+`"navigate"` / `"native"` / `"preload"`. One router per app.
 
 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
+target) on the anchors it handles; style them in CSS. The plugin is also a *reader* of
+the in-flight navigation: without it, or a `useLinkState().pending` / `isPending` read of
+the location somewhere on screen, nothing reads it, so every navigation that waits on a
+lazy page or its first data is an unacknowledged hold (`[SILENT_HOLD]` past 100ms,
+shorter ones only in `toHaveNoSilentHolds`). Create the router with
+`links: pendingLinks` by default, even when no stylesheet uses `data-pending` yet. <!-- upstream:pending-links-opt-in --> 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.
@@ -1947,6 +2131,7 @@ how to reuse. Prefer the form on the right.
 | `<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 `aria-current` / `data-active` (+ `data-pending` via `links: pendingLinks`); `useLinkState` in JSX, `useIsRouting()` for progress bars <!-- upstream:pending-links-opt-in --> |
+| `createRouter({ routes, preloadLinks: true })` (or `false`) | `preloadLinks: intentPreload()` for hover/focus warming; omit the option for none — it takes strategies and a boolean preloads nothing <!-- upstream:preload-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) |
@@ -1967,6 +2152,8 @@ how to reuse. Prefer the form on the right.
 | `Object.assign({}, props)` / expecting `merge` to skip `undefined` like 1.x `mergeProps` | `omit` / `merge` — explicit `undefined` **overrides** (Object.assign) |
 | `isPending(user())` / `latest(user())` | `isPending(user)` / `latest(user)` — pass the accessor (or `() => user()`). Calling it first evaluates the read before the helper runs |
 | `isPending(...)` as the first-load spinner | `<Loading>` owns first flight; `isPending` is the *refetch* indicator after a settled answer exists |
+| `<For each={rows()}>{(row) => <Show when={byKey().get(row().key)}>…</Show>}</For>` (narrowing per row) | join in one memo upstream and iterate the joined rows (`flatMap` drops misses) — a per-row `<Show>` makes every row a source of the list's insert effect, which no diagnostic flags below `[HUGE_FAN_IN]`'s 2000 <!-- upstream:per-row-show-insert-sources --> |
+| a subscription opened beside `createMemo(() => iterate())` instead of inside its compute | open it inside the compute with `onCleanup` there — args changes re-subscribe, `refresh` / `reset` retry with a fresh subscription, unmount closes it |
 | a held write with no feedback anywhere | pair it with `isPending()` / `latest()` / an optimistic value / `affects()` — otherwise dev + attribution reports `[SILENT_HOLD]` |
 | `refresh(getUser.key)` / `revalidate(user)` / `return refresh()` from `"use server"` | three APIs: core `refresh(source)` reruns a reactive source; router `revalidate(getUser.key)` invalidates the query cache; `return reload({ revalidate: "todos" })` asks the integration to refresh cached data |
 | `return redirect(...)` as the only redirect shape | guards `throw redirect("/sign-in")`; `redirect()` / `respond()` take `revalidate` too when the mutation also moves or returns a value |
@@ -2136,6 +2323,10 @@ Known stale pages — this skill is verified against the installed release and w
 - `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 -->
+- `guides/performance` ("tracks 30 or more sources") and the attribution reference
+  (`wideDeps`, "default 30") give the old `[WIDE_SCOPE_DEPS]` threshold; the default is
+  200, and a list's insert pass is exempt from the check (see
+  [Lists](#lists-for-child-signatures-per-keying-mode)). <!-- upstream:docs-wide-deps-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
@@ -2215,6 +2406,10 @@ always-applied rules installed alongside this skill.
       `feedback`) whenever the change touched stores, lists, async, actions, or
       effects. Name interrogated scopes (`{ name: "total" }`). `observe: true` is a
       production opt-in, not a dev step.
+- [ ] Tests that render run under a DOM environment with the HMR transform off and a
+      per-test capture asserting `expectNoDiagnostics` + `expectNoSilentHolds`; app code
+      does not call `attribution.enable()` under the harness. List rows do not narrow
+      themselves with a per-row `<Show>` (no diagnostic catches it).
 - [ ] If the project has a router: `createRouter({ routes })`, not JSX `<Route>` / `<A>`.
       One instance, no nested `<Router>`. Navigate with `useNavigate` / `<a href>`, not
       `window.location`. Router `action`/`query` come from `@solidjs/router` (POST forms + cache), not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid2-agent-kit",
-  "version": "0.20.0",
+  "version": "0.22.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",