solid2-agent-kit 0.19.0 → 0.20.0

package/bin/baseline.mjs

@@ -10,12 +10,21 @@
 // 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.13' },
-  '@solidjs/web': { line: 2, baseline: '2.0.0-rc.13' },
-  '@solidjs/signals': { line: 2, baseline: '2.0.0-rc.13' },
-  '@solidjs/diagnostics': { line: 2, baseline: '2.0.0-rc.13' },
-  '@solidjs/router': { line: 2, baseline: '2.0.0-next.34' },
+  '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

@@ -695,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',
@@ -750,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,
@@ -1315,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;
@@ -1342,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

@@ -68,9 +68,10 @@ 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(...)`)

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: "client"` on the memo/signal/derived store, not a `clientOnly` component split. Router link state is automatic (`aria-current`/`data-active`/`data-pending` + CSS; `useLinkState`/`useIsRouting` in JSX); search params via `useSearchParams`; router forms validate on the server (`throw respond({issues},{400})`) with inline errors from `useSubmissions`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write) <!-- upstream:async-store-setter-throws -->, and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or per root `render(fn, root, undefined, { onError })` — options are the 4th argument), not a side effect inside `<Errored fallback>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. <!-- upstream:dynamic-deprecated --> Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.
+- 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).
@@ -200,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
@@ -244,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
@@ -387,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) —
@@ -501,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,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 --> |
+| 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)`) |
@@ -268,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
@@ -331,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
@@ -507,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)).
@@ -965,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`
 
@@ -1234,6 +1255,11 @@ effects** — a pure markup or styling change does not need it.
    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]`,
@@ -1398,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
@@ -1461,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)`),
@@ -1860,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 |
@@ -1911,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) |
@@ -2092,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.
@@ -2176,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/package.json

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