solid2-agent-kit 0.11.1 → 0.12.0

package/README.md

@@ -16,7 +16,7 @@ Supported agents: **Cursor** and **Claude Code**.
 | Always-applied hard rules | `.cursor/rules/solid-2.mdc` (glob-attached to `*.tsx`/`*.jsx`) | managed block in `CLAUDE.md` | 23 hard rules + banned Solid 1.x API table + eslint-plugin-solid lint-heritage table. Injected without the agent having to decide to read anything |
 | Agent skill | `.cursor/skills/solid-2/` | `.claude/skills/solid-2/` | Execution-model primer, decision tables, canonical patterns, a “still runs / write the other form” table, review checklist, official-doc URL index |
 | Shared agent context | managed block in `AGENTS.md` | same (Claude Code users can reference it from `CLAUDE.md`) | Core principles and pointers, always in context |
-| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[files...]`): fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), `<Dynamic>` (use `dynamic()`), `import type { JSX } from "solid-js"` (no `JSX` namespace there — `Element` from `solid-js`, DOM `JSX` types from `@solidjs/web`), two-phase effects whose apply only writes a local signal (use a writable derivation), and core `action(async ...)` with a plain async function instead of a generator (only `yield` re-enters the transaction) |
+| Mechanical gate | `solid2-kit check` | same | Comment-stripped regex guard over `src/**/*.{ts,tsx,jsx}` (or explicit `[files...]`): fails on props destructuring (including multi-line signatures), `{ ...props }` rest copies, `{list().map(...)}` in JSX, React imports/hooks/JSX props/`React.lazy`/`useOptimistic`/`onDoubleClick`, Solid 1.x imports/APIs/components/JSX namespaces, `vite-plugin-solid`, old-router `<Route>`/`<A>`/`<HashRouter>`/`<FileRoutes>`, `MetaProvider`, `Context.Provider`, camelCase style keys, `key` props, `value()!` hand-narrowing, hand-rolled loading signals, `=== undefined` readiness branches, SolidStart leftovers (`@solidjs/start`, `h3`, `createAsync`, `useSubmission`, `"use client"`), Next.js imports/`useRouter`/`typeof window`, `history.pushState`, `render(<App />)` (pass a function), `isPending(user())` / `latest(user())` (pass the accessor), `<Dynamic>` (use `dynamic()`), `import type { JSX } from "solid-js"` (no `JSX` namespace there — `Element` from `solid-js`, DOM `JSX` types from `@solidjs/web`), two-phase effects whose apply only writes a local signal (use a writable derivation), core `action(async ...)` with a plain async function instead of a generator (only `yield` re-enters the transaction), and `setStore(async ...)` on a `createStore` / `createOptimisticStore` setter (the draft is a synchronous transaction; dev throws `[ASYNC_STORE_SETTER]`) |
 | Edit-time hook | `postToolUse` entry in `.cursor/hooks.json` | `PostToolUse` entry in `.claude/settings.json` (matcher includes `Bash`) | Runs the mechanical gate automatically on **every agent file edit — including edits made through shell commands** (sed, heredocs, codemods; source paths mentioned in the command are checked after it ran) — and feeds findings straight back into the conversation (Cursor: `additional_context`; Claude Code: stderr + exit 2), so enforcement does not depend on the agent remembering to run `check`. Wired only when the kit is a local devDependency; opt out with `--no-hooks` |
 | Turn-end gate | — | `Stop` entry in `.claude/settings.json` | Whole-project `check` + `doctor` when the agent tries to end its turn: with findings in place the stop is blocked (exit 2) and the findings are fed back, so a turn cannot finish with React/Solid 1.x patterns left behind. Loop-safe via `stop_hook_active` (one forced continuation, never an infinite loop) |
 | Pre-execution guard | `preToolUse` + `beforeShellExecution` entries in `.cursor/hooks.json` | `PreToolUse` entry in `.claude/settings.json` | Denies actions **before they run**: edits/deletes of kit-owned guardrail files (an agent blocked by a gate will try to remove the gate), edits that would strip the kit's hook entries or managed blocks, uninspectable shell rewrites of those files, and `npm/pnpm/yarn/bun install` of banned dependencies (`react`, `vite-plugin-solid`, `eslint-plugin-solid`, SolidStart, ...) — caught proactively instead of post-hoc by `doctor` |

package/bin/solid2-kit.mjs

@@ -338,6 +338,24 @@ function soleLocalSetterApply(apply, localSetters) {
 
 const LOCAL_SETTER_DECL = /\[\s*[\w$]+\s*,\s*(set[A-Z][\w$]*)\s*\]\s*=\s*createSignal\b/g;
 
+// A store setter callback is a synchronous transaction — the draft closes when
+// the callback returns, so `setStore(async (draft) => …)` loses every write
+// after its first await (Solid 2.0.0-rc.9 throws ASYNC_STORE_SETTER in dev).
+// Signals may hold promises, so only setters declared via createStore /
+// createOptimisticStore destructuring in the same file are checked.
+const LOCAL_STORE_SETTER_DECL =
+  /\[\s*[\w$]+\s*,\s*(set[A-Z][\w$]*)\s*\]\s*=\s*create(?:Optimistic)?Store\b/g;
+
+function storeSetterAsyncFindings(content) {
+  const setters = new Set([...content.matchAll(LOCAL_STORE_SETTER_DECL)].map((m) => m[1]));
+  if (setters.size === 0) return [];
+  const findings = [];
+  for (const call of content.matchAll(/(?<![.\w$])(set[A-Z][\w$]*)\s*\(\s*async\b/g)) {
+    if (setters.has(call[1])) findings.push({ index: call.index });
+  }
+  return findings;
+}
+
 function effectSyncFindings(content) {
   const localSetters = new Set([...content.matchAll(LOCAL_SETTER_DECL)].map((m) => m[1]));
   if (localSetters.size === 0) return [];
@@ -603,7 +621,16 @@ const CHECKS = [
     id: 'dynamic-jsx',
     pattern: /<Dynamic[\s/>]/g,
     message:
-      '`<Dynamic>` is a JSX convenience wrapper. Application code should use dynamic(() => ...) from "@solidjs/web" so the component identity stays stable.',
+      '`<Dynamic>` is deprecated (Solid 2.0.0-rc.9). Hoist a component with dynamic(() => ...) from "@solidjs/web" so the factory is built once and the component identity stays stable.',
+  },
+  {
+    // `setStore(async (draft) => …)` on a setter declared via createStore /
+    // createOptimisticStore in this file — the draft closes before the await
+    // resumes. `setSignal(async …)` is not flagged (a signal may hold a promise).
+    id: 'store-setter-async',
+    find: storeSetterAsyncFindings,
+    message:
+      'Store setter callbacks are synchronous transactions — writes after the first `await` are lost (dev throws [ASYNC_STORE_SETTER]). Await outside, then call the setter with a synchronous draft mutation (inside an action, `yield` first).',
   },
   {
     // `action(async (item) => ...)` with core `action` never re-enters the

package/files/commands/solid2-review.md

@@ -28,6 +28,11 @@ Steps:
      `isPending` treated as a global spinner instead of a per-expression question;
    - treating `<Errored>` as a terminal ErrorBoundary, or routing per-row mutation
      failures through it (those belong in the action / a projection-folded map);
+     error reporting done as a side effect inside `fallback` instead of
+     `configureClientErrors` / `configureServerErrors` / `render(..., { onError })`;
+   - store setter callbacks that `await` (the draft closes when the callback returns —
+     `[ASYNC_STORE_SETTER]`), store setters called at component-body top level, and
+     `latest()` used as a null-safe read of an unsettled source;
    - nested fetches assumed to waterfall, or `<Loading>` lifted along with a lifted fetch;
    - rewriting App with loading/error branches, or snapshot/restore, when wrapping
      a client store in server functions; disabling optimistic rows until ack;

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`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — children/return types are `Element` from `solid-js`; DOM `JSX` types come from `@solidjs/web`. 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`. Fire-and-forget confirmations wait with `yield until(predicate, {timeout})`. 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, and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`.
+- 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`. One router instance; in-app navigation is `useNavigate` / `<a href>`, not `window.location`. Types: `solid-js` exports no `JSX` namespace — children/return types are `Element` from `solid-js`; DOM `JSX` types come from `@solidjs/web`. 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`. Fire-and-forget confirmations wait with `yield until(predicate, {timeout})`. 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), and a held write needs `isPending`/`latest`/optimistic/`affects` feedback or dev + attribution reports `[SILENT_HOLD]`. Error monitoring is `configureClientErrors` / `configureServerErrors` (or `render(..., { onError })`), not a side effect inside `<Errored fallback>`. `<Dynamic>` is deprecated — use `dynamic()`.

package/files/shared/rules-body.md

@@ -15,7 +15,10 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
 1. **Never destructure props.** `function C({ name })` and `const { name } = props` read the
    prop getter once at setup and kill reactivity. Keep `props.x` and read it inside JSX, a
    memo, or an effect compute function. Defaults go at the read site: `props.x ?? fallback`.
-   Rest props: `omit(props, "label", "value")`, never `const rest = { ...props }` (a snapshot).
+   Rest props: `omit(props, "label", "value")` (or a predicate: `omit(props, (k) => k.startsWith("data-"))`),
+   never `const rest = { ...props }` (a snapshot). `merge` / `omit` return read-only live
+   views — assigning onto them is a silent no-op; `{ ...merged }` gives an own object that
+   never updates again.
    JSX `{...rest}` is fine once `rest` is a reactive proxy. Rule of thumb: the string `props.`
    must never appear at component-body top level *as a read* (`const x = props.x`); nested
    functions (`() => props.x`, `omit(props, ...)`, `children(() => props.children)`) are fine.
@@ -83,6 +86,12 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
    `reconcile` or the derived form (dev + attribution flags the store-level waste as
    `[IMMUTABLE_UPDATE_IN_STORE]`). Stores are
    **property reads** (`todos.length`, `todo.title`), not accessors — never `todos()`.
+   The setter callback is a **synchronous** transaction: `setStore(async (draft) => …)`
+   throws `[ASYNC_STORE_SETTER]` in dev (writes after the first `await` were silently
+   lost before). `await` first, then call the setter (inside an `action`, `yield` first).
+   Mechanically enforced by `solid2-kit check`. A store setter called at
+   component-body top level is a write in an owned scope (`[REACTIVE_WRITE_IN_OWNED_SCOPE]`,
+   same as a signal setter) — seed the initial shape through the `createStore` argument.
 10. **Async data is an async computation**: `createMemo(async () => ...)` (or
     `createMemo(() => fetchUser(id()))`) read under `<Loading>` / `<Errored>`.
     **Fetch high, block low** — creating/reading are like sync; consuming (await)
@@ -103,7 +112,9 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     accessor) only when that identity change should show the fallback again. 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.
+    `<Loading>`. `{latest(() => x())}` is a preview, not the visible answer, and not a
+    null-safe probe: `latest(user)` before the first value throws `NotReadyError` in every
+    scope (event handlers included) — it never returns `undefined` for an unsettled source.
     Default navigation holds: keep `selectedId()` so highlight and content stay
     consistent; `latest(selectedId)` only when the highlight should move first.
     Pair `class={{ pending: isPending(selectedId) }}` with a short CSS
@@ -176,6 +187,10 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     live reconnect, input change). `reset` retries the collected *sources*, not a UI
     remount. Per-row mutation failures belong in an errors map the projection folds
     in (survives the optimistic overlay), not in `<Errored>` around the whole list.
+    Error monitoring is a hook, not a side effect in the fallback: the boundary-caught
+    failures no global handler sees reach `configureClientErrors({ onError })` from
+    `solid-js` (or `render(..., { onError })` per root) and `configureServerErrors({ onError })`
+    from `@solidjs/web` — do not call `captureException` inside `<Errored fallback>`.
     Making a client store "real" is additive: same setters, wrap mutations in
     `action`, swap `createOptimisticStore` and a file of server functions — do
     not rewrite `App.tsx` with loading/error branches.
@@ -212,7 +227,10 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     cross an async gap default to `action` + `createOptimistic`/`createOptimisticStore` —
     the sync mutation *is* the prediction (an overlay, discarded on settle); write the
     body as a generator (`function*` / `async function*`) suspending on `yield`, never a
-    plain `async` function (`solid2-kit check` flags that); put
+    plain `async` function (`solid2-kit check` flags that). After a bare `await`, put a
+    bare `yield` before the next write **and** before anything that creates a reader
+    (`yield until(...)`, `latest()`, a memo/effect) — `until(...)`'s argument is evaluated
+    in the post-`await` continuation, outside the transaction; put
     `pending` on the record rather than a second copy of state. Do not snapshot
     and restore, disable optimistic rows until ack, mutex rapid clicks, or freeze
     unrelated writes because one action is in flight; failed-action replay is
@@ -263,7 +281,8 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     — `lazy(() => import("./pages").then((m) => ({ default: m.About })))` hydrates wrong
     because the named export is not a call-site literal. Select a component from reactive
     state with `dynamic(() => ...)` from `@solidjs/web`
-    (stable identity). If the project has `@solidjs/router`, routes are `createRouter({ routes })`
+    (stable identity); `<Dynamic component={...}>` is deprecated (`@deprecated` in the
+    types since 2.0.0-rc.9, still shipped in 2.0). If the project has `@solidjs/router`, routes are `createRouter({ routes })`
     at module scope — not JSX `<Route>` / `<A>` / `<HashRouter>`. That package's `action` /
     `query` are URL-addressable POST forms and a read cache — not core `action` /
     `refresh` from `solid-js`. Router mutations: `<form action={save} method="post">`
@@ -291,7 +310,11 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     (`<meta name="description">`) that Solid Meta should manage.
     Return `respond(value, { status, headers })` from a `"use server"` function, not
     `Response.json` — a raw `Response` is HTTP-handler control flow; scripted
-    callers should receive the value. Reads are function calls too (`await getUser(id)`
+    callers should receive the value. Production sanitizes every thrown value that
+    crosses the wire — server-function throws **and** SSR render errors (an `<Errored>`
+    fallback printing `err().message` shows `"Internal Server Error"` in a production
+    server render) — so intentional client-facing failures are `markSafeError(...)` or
+    `throw respond(body, { status })`. Reads are function calls too (`await getUser(id)`
     on a `GET()`-declared read; the method mirrors the operation). Return or throw a
     redirect (`if (!session?.userId) throw redirect("/sign-in")`); `redirect()` /
     `respond()` take `revalidate` like `reload()`. Cache GET reads with
@@ -367,7 +390,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(source)` from `@solidjs/web` |
+| `createDynamic(...)`, `<Dynamic component={...}>` (deprecated in 2.0) | `dynamic(source)` from `@solidjs/web` |
 | `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"` |
@@ -383,7 +406,8 @@ When unsure about any API, verify against the official Solid 2.0 docs — fetcha
 listed in `references/official-docs.md` next to the `solid-2` skill. Do not guess from
 Solid 1.x or React memory.
 
-`createTrackedEffect`, `createRenderEffect`, and `storePath` exist in Solid 2 but
-are not defaults: use two-phase `createEffect` unless a single tracked callback is
-required, and draft setters instead of `storePath` except while converting 1.x
-path setters.
+`createTrackedEffect` and `createRenderEffect` exist in Solid 2 but are not defaults:
+use two-phase `createEffect` unless a single tracked callback is required. `storePath`
+(the 1.x path-setter migration helper) is no longer exported from `solid-js` as of
+2.0.0-rc.9 — convert path setters to draft setters instead of importing it from
+`@solidjs/signals`.

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

@@ -68,7 +68,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; prefer over `<Dynamic>`) |
+| Pick a component/tag from reactive state | `dynamic(() => ...)` from `@solidjs/web` (stable identity; `<Dynamic>` is deprecated) |
 | 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)`) |
@@ -120,7 +120,11 @@ To merge defaults or split props reactively use `merge` / `omit` from `solid-js`
 Omitted keys still fall through, so `merge({ type: "button" }, props)` is the
 usual defaults pattern. That is not Solid 1 `mergeProps`, which ignored
 `undefined`. Forwarding leftover props: `const rest = omit(props, "label")` then
-`<input {...rest} />`. `const rest = { ...props }` compiles and then never updates.
+`<input {...rest} />`; a predicate hides keys by rule without enumerating first
+(`omit(props, (key) => key.startsWith("data-"))`). `const rest = { ...props }` compiles
+and then never updates. Both helpers return **read-only live views** (since
+2.0.0-rc.9 for every input, plain objects included): assigning onto the result is a
+silent no-op, and `{ ...merged }` is an own object that carries no sources.
 
 ### Store updates (draft mutation)
 
@@ -134,6 +138,26 @@ setProfile((draft) => {
 });
 ```
 
+The setter callback is a **synchronous transaction** — the draft closes when it
+returns. `setProfile(async (draft) => { draft.name = await load(); })` used to commit
+only the writes before the first `await` and silently drop the rest; since
+2.0.0-rc.9 it throws `[ASYNC_STORE_SETTER]` in dev (`solid2-kit check` flags it too).
+Await outside, then write synchronously (inside an `action`, `yield` first):
+
+```tsx
+// WRONG — the draft is already closed when the await resumes
+setProfile(async (draft) => { draft.name = await fetchName(); });
+
+// CORRECT
+const name = await fetchName();
+setProfile((draft) => { draft.name = name; });
+```
+
+A signal may hold a promise, so `setSignal` has no such rule. A store setter called
+at component-body top level is a write in an owned scope — dev throws
+`[REACTIVE_WRITE_IN_OWNED_SCOPE]` (rc.9 closed the exemption store writes had) — so
+seed the shape through the `createStore` argument or a derivation.
+
 **External collections enter stores through reconciliation, never wholesale assignment.**
 `draft.todos = serverTodos` renders correctly but replaces every object identity — all
 subscribers under the path re-run and row identity is lost. In order of preference:
@@ -204,8 +228,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
 variable in JSX (`const View = tab() ? A : B` freezes the choice at setup).
-`<Dynamic>` is the JSX spelling of the same primitive; application code should
-use `dynamic()` so the component identity stays stable.
+`<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
+is **deprecated** since 2.0.0-rc.9 — `@deprecated` in the types, no runtime warning,
+still shipped in 2.0. Hoist a `dynamic()` per component instance (or per module for a
+constant tag) instead.
 
 ### Two-phase effect (imperative boundary only)
 
@@ -357,7 +384,11 @@ return <StoryDetail story={story} />;
   React ErrorBoundary. `reset` retries the collected *data sources*, not a UI remount.
 - Refetch: `refresh(results)`. In-flight indicator: `isPending(results)` (or
   `isPending(() => results())`). Freshest in-flight value for a preview:
-  `latest(results)`. Do not start `fetch` at component-body top level.
+  `latest(results)`. `latest` is not a null-safe probe: before the source's first value
+  it throws `NotReadyError` in every scope (since 2.0.0-rc.9 also in event handlers and
+  imperative code, which used to receive `undefined`). A write is visible to `latest()` /
+  `isPending()` only from the flush that carries it — `flush()` first when a test reads
+  its own write through them. Do not start `fetch` at component-body top level.
 - Coordinate sibling `<Loading>` reveal with `<Reveal>` (`order="sequential"` default,
   or `"together"` / `"natural"`). `collapsed` (sequential only) suppresses tail
   skeletons past the frontier so the page does not stack fallbacks as popcorn.
@@ -384,6 +415,32 @@ repeating `String(error())` at each boundary:
 <Errored fallback={(error, reset) => <ErrorFallback error={error} reset={reset} />}>
 ```
 
+**Report boundary-caught errors through the error hooks, not from the fallback.** An
+error an `<Errored>` collected never reaches `window.onerror`; a `captureException`
+call inside `fallback` is a side effect in render that fires on every re-render of the
+fallback. Since 2.0.0-rc.9 the runtime has a seam for exactly this failure, called
+once per error object with where it was thrown (`ownerPath`) and where it was met
+(`boundaryPath`):
+
+```ts
+import { configureClientErrors } from 'solid-js';
+import { configureServerErrors } from '@solidjs/web';
+
+configureClientErrors({
+  onError: (error, { ownerPath, boundaryPath }) => report(error, { ownerPath, boundaryPath }),
+});
+// server side (SSR renders and server functions); its return value, if any, is the
+// sanitized value the client receives instead of the original error
+configureServerErrors({ onError: (error, { kind, handling }) => report(error, { kind, handling }) });
+```
+
+`render` / `hydrate` accept a per-root `onError` that wins over the ambient hook.
+Uncaught errors (`REACTIVITY_HALTED`) go to the platform's `reportError`, which every
+monitor already listens on — do not report them twice. `renderToStream` /
+`renderToString`'s `onError` option *is* the per-render server hook: it now hears every
+handled failure, so filter on `context.handling === "failed"` when only request-failing
+errors matter (the rc.8 one-argument form keeps working).
+
 ### Streams and subscriptions (websockets, reactive clients)
 
 Push-based sources integrate by returning an **async iterable** from a computation — reads
@@ -532,7 +589,11 @@ Write the body as a generator — `function*` or `async function*`, never a plai
 `async (...) =>` — because only `yield` re-enters the transaction: the runtime has no
 hook into a plain `await` continuation, so even inside `async function*` an `await`
 leaves the transaction until the next `yield` (`solid2-kit check` flags the
-non-generator form).
+non-generator form). The bare `yield` must also come before anything that **creates a
+reader** — `until()`, `latest()`, a memo or effect, a mount — not only before writes:
+the expression of the next `yield` is evaluated in the post-`await` continuation, so
+`await save(); yield until(...)` builds the predicate's reader outside the transaction.
+Write `await save(); yield; yield until(...)`.
 
 When confirmation arrives outside the response — a fire-and-forget transport echoed
 back on a live source — hold the action open with `yield until(predicate, { timeout })`:
@@ -792,10 +853,18 @@ an agent sneaks in fails the suite instead of scrolling by.
 Diagnostics come in two layers, both dev-build only (production strips them and `DEV`
 is `undefined` there). Always-on findings include misplaced reads
 (`[STRICT_READ_UNTRACKED]`, `[PENDING_ASYNC_UNTRACKED_READ]`), misplaced writes
-(`[REACTIVE_WRITE_IN_OWNED_SCOPE]`, `[FLUSH_IN_ACTION]`, `[SERVER_WRITE]`), and
+(`[REACTIVE_WRITE_IN_OWNED_SCOPE]` — since rc.9 also for store setters called in a
+component or root body, `[ASYNC_STORE_SETTER]` for a store setter callback that returns
+a promise, `[FLUSH_IN_ACTION]`, `[SERVER_WRITE]`), and
 `[ASYNC_OUTSIDE_LOADING_BOUNDARY]` when a tracked read has no boundary above 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), `[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]`.
 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.
@@ -805,16 +874,20 @@ every scope that re-ran, what changed to cause it, and how long it took. Since
 `solid-js` 2.0.0-rc.8 the engine lives behind its own subpath — `DEV.attribution`
 no longer exists (it is a type error; `DEV` holds only devtools hooks, graph
 traversal, and console reporting), and the low-level hook slot on `OBSERVE` is for
-engines and devtools, not app code:
+engines and devtools, not app code. 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); `attribution` keeps `enable`, `disable`, `subscribe`, `markFlight`, and the
+record ring buffers (`history`, `holds`, `waterfalls`, `navigations`, `interactions`):
 
 ```ts
-import { attribution } from 'solid-js/attribution';
+import { attribution, formatRerun, why } from 'solid-js/attribution';
 import { isDev } from '@solidjs/web';
 
 if (isDev) attribution.enable({ log: false });
 // reproduce the interaction, then ask why a scope ran:
-for (const event of attribution.why(total)) {
-  console.log(attribution.format(event));
+for (const event of why(total)) {
+  console.log(formatRerun(event));
 }
 ```
 
@@ -823,8 +896,10 @@ for (const event of attribution.why(total)) {
 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`. In production the import
-resolves to an inert same-surface twin (~640 bytes) whose `enable()` is a no-op, so
-with the `isDev` guard the cost is zero and the import can stay in the code.
+resolves to an inert same-surface twin whose `enable()` is a no-op, so
+with the `isDev` guard the cost is zero and the import can stay in the code. 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.
 
 While attribution is enabled, Solid also warns on its own about over-subscription,
 chained async waterfalls (`[ASYNC_WATERFALL]`), memos whose fresh-but-equal output
@@ -835,10 +910,11 @@ row-rebuilding lists (`[UNSTABLE_LIST_IDENTITY]` — key by id or reconcile into
 store), and silent holds (`[SILENT_HOLD]` — a write held on async work with no
 `isPending()` / `latest()` reader, optimistic value, `affects()` mark, or effect that
 ran while held; info from 100ms, warning from 200ms, tunable via
-`enable({ holds: { infoMs, warnMs } })`). `attribution.costs()`, `holds()`, and
-`feedback()` rank the session worst-first; `waterfalls()`, `navigations()`, and
-`interactions()` hold the fact tables behind the verdicts.
-`attribution.subscriptions(scope)` lists a scope's current dependencies to compare
+`enable({ holds: { infoMs, warnMs } })`). `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.
+`subscriptions(scope)` (named import) lists a scope's current dependencies to compare
 against what it uses.
 
 For regression tests, `@solidjs/diagnostics` turns the same channels into assertions:
@@ -1118,11 +1194,17 @@ reaches the client — the directive is the privacy boundary. Mutations that sho
 revalidate: `redirect` / `reload` from `@solidjs/web` (see the server-function
 guides). Return or throw a redirect — guards read `if (!session?.userId) throw
 redirect("/sign-in")`. `redirect()` and `respond()` accept the same `revalidate`
-option as `reload()` when the mutation also changes location or returns a value. After a router/server mutation do **not** follow with a client `fetch`
+option as `reload()` when the mutation also changes location or returns a value;
+`revalidate: REVALIDATE_ALL` (`"*"`, from `@solidjs/web`) declares every cache entry
+stale, distinct from omitting it (the host's default) and from `[]` (nothing). After a router/server mutation do **not** follow with a client `fetch`
 to "refresh the page" — `reload` / `revalidate` (and the router's single-flight
 response) close that loop. For 404 during SSR: `httpStatus(404)` from `@solidjs/web`.
 `throw new Error("…")` is stripped to `"Internal Server Error"` in production —
-use `markSafeError` or `respond(..., { status })` for intentional client-facing
+on the server-function wire **and**, since 2.0.0-rc.9, on every SSR road a failure
+takes (an `<Errored>` fallback rendered on the server, a rejected async source
+serialized into the stream, a `<Loading>` fragment's rejection), so `err().message`
+in a fallback reads the generic message in a production server render. Use
+`markSafeError` or `respond(..., { status })` for intentional client-facing
 failures. Do not `return Response.json(...)` from `"use server"` — that is
 HTTP-handler control flow; `respond(value, { status })` is what a scripted
 caller unwraps. JSON-encodable arguments only unless `enableRichArguments()`
@@ -1317,7 +1399,14 @@ how to reuse. Prefer the form on the right.
 | `submission.clear()` from an effect | on dismiss/resubmit only — from an effect, errors flash and vanish |
 | `revalidate(liveSource)` | `live()` updates through the open stream; do not revalidate it |
 | `refresh(user)` without `affects` when the reload should look pending | pair `affects(user)` with `refresh(user)` — a bare `refresh` re-asks quietly |
-| `<Dynamic component={tab() ? A : B} />` | `const View = dynamic(() => (tab() ? A : B))` — `<Dynamic>` is a JSX convenience; app code should use `dynamic()` for stable identity |
+| `<Dynamic component={tab() ? A : B} />` | `const View = dynamic(() => (tab() ? A : B))` — `<Dynamic>` is deprecated (rc.9); `dynamic()` hoists the factory and keeps identity stable |
+| `setStore(async (draft) => { draft.x = await load(); })` | `const x = await load(); setStore((draft) => { draft.x = x; })` — the setter is a synchronous transaction; dev throws `[ASYNC_STORE_SETTER]` |
+| `setStore((d) => { d.items = seed; })` in a component body | seed through `createStore(seed)` / `createStore(() => props.items, fallback)` — a body-level store write is `[REACTIVE_WRITE_IN_OWNED_SCOPE]` |
+| `const saved = await api.save(); yield until(() => ...)` | `await api.save(); yield; yield until(() => ...)` — a bare `yield` re-enters the transaction before any reader is created, not only before writes |
+| `fallback={(err) => { captureException(err()); return <Fallback />; }}` | `configureClientErrors({ onError })` from `solid-js` (or `render(..., { onError })`), `configureServerErrors({ onError })` from `@solidjs/web` — once per error, with `ownerPath` / `boundaryPath` |
+| `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())` |
+| `attribution.why(total)` / `attribution.format(e)` / `attribution.costs()` | named imports from `solid-js/attribution`: `why(total)`, `formatRerun(e)`, `costs()`, `feedback()`, `subscriptions(scope)` (rc.9) |
+| `import { storePath } from "solid-js"` | gone from `solid-js` (rc.9); write draft setters `setState((d) => { d.user.name = "Grace"; })` |
 | `<meta name="description" content="...">` hardcoded in the document shell | `<Meta>` from `@solidjs/meta`. A static `<title>` is the fallback; other hardcoded tags coexist with the registry |
 | `useHead({ tag: "meta", ... })` for ordinary page tags | `<Title>` / `<Meta>` / `<Script>` (JSON-LD). `useHead` is the lower-level registry |
 | two `<Meta property="og:image">` meant as one replacement set | wrap them in `<Head>` — a later group replaces the earlier set as one unit |
@@ -1490,7 +1579,9 @@ always-applied rules installed alongside this skill.
       or `isPending(selectedId)` when the write is the question. `<Errored>` heals
       when the source succeeds; `reset` retries sources, not a UI remount. Per-row
       mutation failures stay in the action/projection, not in `<Errored>` around
-      the list. Core `refresh(source)`, router `revalidate(key)`, and `return reload(...)` are
+      the list. Error monitoring goes through `configureClientErrors` /
+      `configureServerErrors` (or `render(..., { onError })`), never a side effect in
+      the fallback. Core `refresh(source)`, router `revalidate(key)`, and `return reload(...)` are
       different APIs — do not mix them. Client → server is additive (same
       setters + `action` + server functions): do not rewrite App with
       loading/error branches, disable optimistic rows until ack, or refetch in
@@ -1513,11 +1604,14 @@ always-applied rules installed alongside this skill.
       (values), not `typeof window`.
       Component teardown is `onSettled` (return cleanup), not `onCleanup`.
 - [ ] Dev console shows no diagnostics: reads in tracking scopes (no
-      `[STRICT_READ_UNTRACKED]`), held writes paired with `isPending` / `latest` /
-      optimistic values / `affects()` (no `[SILENT_HOLD]`). Attribution-only costs
+      `[STRICT_READ_UNTRACKED]`), store setters synchronous and never called at
+      body level (no `[ASYNC_STORE_SETTER]` / `[REACTIVE_WRITE_IN_OWNED_SCOPE]`), held
+      writes paired with `isPending` / `latest` / optimistic values / `affects()`
+      (no `[SILENT_HOLD]`). Attribution-only costs
       (`[IMMUTABLE_UPDATE_IN_STORE]`, `[UNSTABLE_LIST_IDENTITY]`, `[EFFECT_*]`)
-      checked via `attribution` from `solid-js/attribution` when touching stores,
-      lists, or effects. Name interrogated scopes (`{ name: "total" }`).
+      checked via `attribution` + the named folds (`why`, `costs`, `feedback`) from
+      `solid-js/attribution` when touching stores, lists, or effects. Name
+      interrogated scopes (`{ name: "total" }`).
 - [ ] 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.11.1",
+  "version": "0.12.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",