solid2-agent-kit 0.8.1 → 0.11.0

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

@@ -70,7 +70,10 @@ Most React `useEffect` code should NOT become `createEffect`:
 | 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>`) |
 | Overlay / modal | `<Portal>` — hoist async reads *above* the portal (reads inside start on the client) |
+| Async value used several layers down | Create the memo high; pass `value={memo()}` through intermediates (they do not wait); put `<Loading>` around the leaf read |
+| Nested child with its own fetch | Leave it nested — it runs in parallel. Sequential only when the second call needs the first response (`fetchAuthor(story().authorId)`) |
 | Browser-only widget (charts, maps, `window`) | `clientOnly(() => import("./Chart"))` from `@solidjs/web` (`{ lazy: true }` defers the import until first render) |
+| Browser-only *value* (`localStorage`, viewport size) | `createMemo(..., { ssrSource: "client" })` — per-value policy at the data source, no component split (`"hybrid"` when server data mixes with client signals) |
 | Server vs browser branch | `isServer` / `isDev` from `@solidjs/web` (build-time constants), not `typeof window` |
 | SSR-stable `id` / `for` / `aria-*` pairing | `createUniqueId()` |
 
@@ -221,7 +224,9 @@ createEffect(
 Reads inside `apply` do not track. Extract every needed reactive value in `compute`
 (e.g. `() => ({ name: user.name, role: user.role })`). Passing a store proxy into `apply`
 and reading `user.name` there *runs once* and never retriggers. Compute-phase errors can be
-intercepted with the bundle form `createEffect(compute, { effect, error })`.
+intercepted with the bundle form `createEffect(compute, { effect, error })`. Skip the
+initial run with `{ defer: true }` — the `on(deps, fn, { defer: true })` replacement;
+the effect first runs on the next change.
 
 A two-phase effect whose apply only calls a local signal setter is "state + effect" in
 disguise — formally legal Solid 2, still rule 4 (`solid2-kit check` flags it). The reset
@@ -245,44 +250,117 @@ const [signInError, setSignInError] = createSignal<string | null>(() => {
 });
 ```
 
-### Async data
+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
+`previousX` comparison reset during render for the same behavior.)
+
+### Async data — fetch high, block low
+
+Creating and reading an async value are the same as sync. **Consuming** (the
+await) is a DX choice; **blocking** (the boundary) is a UX choice. Solid
+unwelds them: where you create the memo is performance, where `<Loading>`
+wraps the *read* is design, and neither is an architecture decision. JSX
+component props are lazy (**passing isn't reading**), so intermediates do
+not wait. Nested components mount immediately — they do not suspend — so
+their fetches run in parallel. Making a value remote should touch the memo
+and the boundary, not every file on the path, and should not change prop
+types to `Promise<User>` or `Accessor<User>`.
 
 ```tsx
-import { Errored, For, Loading, createMemo, createSignal } from 'solid-js';
+import { Errored, Loading, createMemo, createSignal, isPending } from 'solid-js';
 
-const [query, setQuery] = createSignal('');
-const results = createMemo(async () => {
-  const value = query().trim();
-  if (!value) return [];
-  return api.search(value);
-});
+function App() {
+  const [selectedId, setSelectedId] = createSignal(1);
+  const story = createMemo(() => fetchStory(selectedId()));
 
-return (
-  <Errored fallback={(error) => <p>{String(error())}</p>}>
-    <Loading fallback={<p>Searching...</p>}>
-      <ul><For each={results()}>{(r) => <li>{r.title}</li>}</For></ul>
-    </Loading>
-  </Errored>
-);
+  return (
+    <Errored fallback={(error, reset) => <ErrorFallback error={error} reset={reset} />}>
+      <StoryList selectedId={selectedId()} onSelect={setSelectedId} />
+      <main class={{ pending: isPending(selectedId) }}>
+        <Loading fallback={<DetailSkeleton />}>
+          <StoryDetail story={story()} storyId={selectedId()} />
+        </Loading>
+      </main>
+    </Errored>
+  );
+}
+
+function StoryDetail(props: { story: Story; storyId: number }) {
+  const byline = createMemo(() => `${props.story.author} · ${props.story.points} points`);
+  return (
+    <article class={{ stale: isPending(() => props.story) }}>
+      <h1>{props.story.title}</h1>
+      <p>{byline()}</p>
+      <Comments storyId={props.storyId} />
+    </article>
+  );
+}
+```
+
+`story()` is a `Story`, not `Story | undefined` — if the computation is running,
+the value is there. No `?.`, no `!`. `<StoryDetail story={story()} />` is the
+correct colorless form: the prop expression is a getter, so `StoryDetail` (and
+every layout in between) renders immediately. The wait happens when
+`props.story.title` is read, under that `<Loading>`.
+
+```tsx
+// WRONG — extracting at the parent is a real read; child's <Loading> never sees it
+const current = story();
+return <StoryDetail story={current} />;
+
+// WRONG — Promise / Accessor types on the path. Making story remote is not a
+// type change for StoryLayout / StoryDetail.
+function StoryDetail(props: { story: Promise<Story> }) { /* ... */ }
+function StoryDetail(props: { story: Accessor<Story> }) { /* ... */ }
+
+// Fine — pass the memo itself only when the child must refresh() that source.
+// isPending / latest are questions: they work on the value prop too.
+return <StoryDetail story={story} />;
 ```
 
-- The `<Loading>` boundary must be an owner ancestor of the **read** (`results()`), not of
+- The `<Loading>` boundary must be an owner ancestor of the **read**, not of
   where the memo was created, and not of page chrome (header/nav) that should stay mounted.
-  Boundary placement is purely a UX decision — it does not change when fetches start
-  (no waterfalls: nested components set up and fetch in parallel). After first paint the
+  Lifting the fetch does **not** mean lifting the boundary — that is consume glued
+  back onto block. After first paint the
   boundary keeps settled content during refetch; `isPending(results)` (pass the accessor,
-  not `isPending(results())`) is the
-  indicator. Use `on={query()}` (the **value**, not the accessor `on={query}`) only when
-  that identity should put the fallback back on screen.
+  not `isPending(results())`) is the indicator. Use `on={query()}` (the **value**, not the
+  accessor `on={query}`) only when that identity should put the fallback back on screen.
   Do not use `isPending` as the first-load spinner.
+- **Nesting is not a waterfall.** `Comments` above fetches in parallel with `story`
+  because it reads `props.storyId` (already known), not `props.story`. Passing
+  `storyId={props.story.id}` *would* wait on the story fetch — that is a real data
+  dependency, same as `createMemo(() => fetchAuthor(story().authorId))`. Components
+  do not suspend; they run once. Only the expressions that read wait, so a parent
+  JSX read does not delay a child that does not need that value.
+- `isPending` is a **per-expression question**, not state and not a global spinner.
+  Ask it anywhere: on the async source (`isPending(results)`), below it
+  (`isPending(() => props.story)`), on a derived memo (`isPending(byline)`), or
+  *above* the fetch but below the write (`isPending(selectedId)`), even when the
+  fetch lives in a child. You do not need to pass the memo accessor just to ask.
+  Granularity is the expression: `isPending(() => item.quantity)` (paired with
+  `affects(item, "quantity")`) or `isPending(() => todos.length)` dims only what
+  that read depends on. A hold with no feedback at all is `[SILENT_HOLD]` under
+  attribution — always pair a held write with one of these questions, an
+  optimistic value, or `affects()`.
+- Default navigation **holds**. `selectedId()` and the old story stay put until
+  the new answer lands, so the highlight never points at the wrong content.
+  `latest(selectedId)` is the opt-in when the design wants the highlight to move
+  on click. Pair `class={{ pending: isPending(selectedId) }}` with a short CSS
+  `transition-delay` so fast swaps do not flash. Inputs that feed a request follow
+  the same rule: bind `value={latest(query)}` so a controlled search box reflects
+  keystrokes while its write is held (an uncontrolled input needs nothing).
 - Read every reactive input **before the first `await`** in an async computation. A read
   after `await` does not subscribe; production can sit pending with no retry.
 - `<Errored>` function fallbacks receive an error **accessor** and a `reset` callback:
-  `fallback={(error, reset) => ...}`.
+  `fallback={(error, reset) => ...}`. The boundary **heals** when the source succeeds
+  again (refresh, live reconnect, input change) — it is graph status, not a terminal
+  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.
-- Coordinate reveal order of sibling `<Loading>` boundaries with `<Reveal order="sequential" | "together" | "natural">`.
+- 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.
 
 **Never hand-roll these states.** No `[loading, setLoading]` signal, no
 `data() === undefined` branch, no `{ data, error }` signal pair — those are React/Solid 1.x
@@ -290,7 +368,12 @@ reflexes that bypass the async model and `solid2-kit check` flags them. If a val
 make it an async computation and read it under boundaries. Refetching is `refresh(source)`
 (typically as the last step of a mutation `action`, or a reload button) — never a
 counter/version signal read inside the computation to force re-runs; input-driven refetch is
-already automatic.
+already automatic. No request counters or `AbortController`s for dedup/cancellation
+either — superseded answers are dropped automatically and settled content holds;
+debounce at the event handler (`onInput={debounce(...)}`), never as an effect copying
+one signal into another. And throw unusable responses instead of returning
+`{ success: false }` objects checked at every read — failures travel to `<Errored>`
+like values.
 
 **Normalize thrown values once.** Thrown values are `unknown` in JavaScript, so define one
 shared `ErrorFallback` component per app — extract the message via `instanceof Error`, wire
@@ -334,21 +417,101 @@ function createSubscriptionQuery<T>(
 }
 ```
 
+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).
+
 ### Mutations: `action` + optimistic state
 
+The synchronous mutation *is* the prediction. Optimistic UI is not a second copy of
+state — it is an overlay the graph discards when the action settles (pass or fail).
+There is no rollback to write. Put in-flight affordances on the record
+(`pending?: boolean`); they vanish with the overlay.
+
+Minimal shape — the durable value derives from `fn`, optimistic writes overlay it,
+and `refresh` re-runs the derivation so the store reconciles against the server
+(no separate `getMessages()` call):
+
 ```tsx
 import { action, createOptimisticStore, refresh } from 'solid-js';
 
-const [todos, setTodos] = createOptimisticStore(fetchTodos, []);
+function createMessages() { // call from a component — not module scope (SSR shares modules)
+  const [messages, setMessages] = createOptimisticStore(() => getMessages(), []);
 
-const addTodo = action(function* (todo: Todo) {
-  setTodos((draft) => { draft.push(todo); }); // optimistic, auto-reverts on failure
-  yield saveTodo(todo);                        // yield promises to stay in the transaction
-  refresh(todos);
-});
-// invoke from an event handler: onClick={() => void addTodo(newTodo)}
+  const addMessage = action(function* (message: Message) {
+    setMessages((m) => { m.push(message); });
+    yield saveMessage(message);
+    refresh(messages);
+  });
+  return [messages, { addMessage }] as const;
+}
 ```
 
+Mutate the draft (`m.push(message)`), never spread-rebuild (`[...m, message]`) —
+stores track writes finely, so only the changed part updates. When the action
+settles, the overlay is discarded and the refreshed server data is authoritative;
+if it agrees with the prediction, reconciliation finds no differences and nothing
+re-renders. Derived reconciliation keys by `"id"` by default — pass `{ key: ... }`
+only when the identity field differs.
+
+Layered form, when per-row UI must survive overlay discard (a recoverable error
+with Retry on that row only):
+
+```tsx
+import { action, createOptimisticStore, refresh } from 'solid-js';
+
+type Todo = { id: string; title: string; completed: boolean; pending?: boolean; error?: { completed: boolean } };
+
+function createTodos() { // call from a component — not module scope (SSR shares modules)
+  const errors = new Map<string, { completed: boolean }>();
+  const [todos, setTodos] = createOptimisticStore<Todo[]>(async () => {
+    const current = await api.list();
+    return current.map((todo) => {
+      const error = errors.get(todo.id);
+      return error ? { ...todo, error } : todo;
+    });
+  }, []);
+
+  const toggleTodo = action(function* (id: string, completed: boolean) {
+    setTodos((draft) => {
+      const todo = draft.find((row) => row.id === id);
+      if (!todo) return;
+      todo.completed = completed;
+      todo.pending = true;
+    });
+    try {
+      yield api.toggle(id, completed);
+      errors.delete(id);
+    } catch {
+      errors.set(id, { completed });
+    } finally {
+      refresh(todos);
+    }
+  });
+  return [todos, { toggleTodo }] as const;
+}
+```
+
+Three layers, in this order: durable source → ephemeral UI that must survive
+overlay discard (the `errors` map, folded in the projection) → optimistic overlay
+(`pending`, the predicted `completed`). Consumers read one store. Catch
+*expected* mutation failures in the action so a toggle error does not blank the
+list through `<Errored>`; unhandled projection/render errors still reach the
+boundary.
+
+Going from a client store to the server is **additive**: same `setTodos`
+calls, wrap each mutation in `action`, swap in `createOptimisticStore` and a
+file of server functions. Do not rewrite `App.tsx` with loading/error branches,
+and do not snapshot-the-cache / write-a-prediction / restore-on-error. A cache
+library is not the productionizing step — the sync mutation already was the
+prediction. (Router `query` or `@tanstack/solid-query` remain valid when the
+project already uses them; they are not required to "make it real".)
+Optimistic rows stay interactive — a not-yet-acked todo can still
+be toggled. Do not disable the control until confirmation, and do not mutex
+rapid clicks; `action` is the transaction (no half-mutation, no interleaved
+list). An in-flight action does not freeze unrelated writes. Collecting failed
+actions to replay is a design choice, not something the runtime requires.
+
 Ordinary signal/store writes inside an action are held until it settles. Never call
 `flush()` inside an action. Invoke actions from handlers, not from component/computation bodies.
 Do not set a `submitted` signal and watch it from an effect — that work belongs in the
@@ -356,11 +519,37 @@ handler or the `action`.
 
 `createOptimistic` / `createOptimisticStore` are for a tentative value during an
 active mutation, not a local editing session (use a writable derivation or a plain
-store for that).
+store for that). A whole-form `createOptimistic(false)` saving flag is fine; prefer
+`pending` on the record when the affordance is per item. The overlay is
+discarded when the action settles — the confirmed store is the truth. Wrapping
+the same store in server functions does not change that; do not add
+snapshot/restore.
 
 **`yield`, not a bare `await`, is the transaction boundary.** `await api.save()` then
-`setTodos(...)` *runs*, but the write commits immediately and optimistic rollback is lost.
-Either `yield saveTodo(todo)` or, when you need a typed result, `const saved = await api.save(); yield; setTodos(...)`.
+`setTodos(...)` *runs*, but the write commits immediately — it is not held as an
+overlay. Either `yield saveTodo(todo)` or, when you need a typed result, `const saved = await api.save(); yield; setTodos(...)`.
+Write the body as a generator — `function*` or `async function*`, never a plain
+`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).
+
+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 })`:
+
+```tsx
+const send = action(function* (text: string) {
+  const clientId = crypto.randomUUID();
+  setMessages((m) => { m.push({ clientId, text, pending: true }); });
+  yield socket.send({ clientId, text });
+  yield until(() => messages.some((m) => m.clientId === clientId), { timeout: 10_000 });
+});
+```
+
+The predicate reads authoritative state, so the optimistic row cannot satisfy it;
+only the echo can. Timeout rejects with `TimeoutError` (strongly recommended on
+droppable transports; abort via `signal`). Outside actions, `await until(() => user())`
+waits for a value before continuing.
 
 Navigation-shaped updates do **not** need core `action`. A plain setter is enough:
 reads pull the async, and downstream async computeds hold previous values until the
@@ -513,6 +702,46 @@ do not `return () => cleanup`. Put owned setup in a **directive factory** (like
 `ResizeObserver`, third-party widgets, and native listener options (`capture` /
 `passive`) — Solid event props do not take those options.
 
+### Per-value SSR policy: `ssrSource`
+
+`clientOnly` splits a *component*; `ssrSource` keeps one *value* off the server,
+decided at the data source. `createMemo`, function-form `createSignal`, and derived
+stores (`createStore(fn, seed)`, `createProjection`, `createOptimisticStore(fn, seed)`)
+all accept `ssrSource: "server" | "hybrid" | "client"`:
+
+```tsx
+import { Loading, createMemo } from 'solid-js';
+
+function DraftPreview(props: { documentId: string }) {
+  const draft = createMemo(
+    () => localStorage.getItem(`draft:${props.documentId}`),
+    { ssrSource: 'client' },
+  );
+
+  return (
+    <section>
+      <h2>Saved draft</h2>
+      <Loading fallback={<p>Checking for a saved draft...</p>}>
+        <p>{draft() ?? 'No saved draft.'}</p>
+      </Loading>
+    </section>
+  );
+}
+```
+
+| Policy | Meaning | Use when |
+|---|---|---|
+| `"server"` (default) | Client adopts the serialized server value; compute does not re-run | Compute is deterministic from server-available inputs |
+| `"hybrid"` | Client adopts the serialized value, then re-runs the compute to take over | Server data mixes with client signals (window size, user locale) |
+| `"client"` | Server value skipped; compute runs after hydration as if first-mounted | Serialization is meaningless (`localStorage`, viewport) |
+
+With `"client"`, the bare form suspends on the server and the nearest `<Loading>`
+fallback renders into the HTML; a declared first value (`loadingValue` on
+signal-family sources, `seedLoadingValue: true` on store-family sources) renders
+provisional data with no boundary involvement instead. Filling the value in from
+an `onSettled` callback remains a valid alternative; `NoHydration` / `Hydration`
+split hydration *ownership* instead and do not express this policy.
+
 ## Scheduling and tests
 
 Signal/store writes outside a synchronous flush scope are **staged**; the reactive queue
@@ -529,6 +758,8 @@ Wait for an async expression to settle in tests: `await resolve(() => value())`.
 on a pending resource. `onSettled` is also a **single** fire (untracked): it is not
 `onMount` that re-runs, and it is not an effect. Run tests in dev mode first — Solid 2 emits diagnostics for top-level reactive reads,
 writes from owned scopes, and async reads outside `<Loading>`. Fix them; don't suppress.
+A read at component-body top level reports `[STRICT_READ_UNTRACKED]` naming the
+component — move the read into JSX, a memo, or an effect compute.
 
 Component tests use `@solidjs/testing-library`. Pass a **function** to `render` so
 the tree has an owner, and `flush()` after interactions that stage writes:
@@ -556,6 +787,60 @@ To turn those dev diagnostics into a hard gate, patch `console.warn` in the test
 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.
 
+### Dev diagnostics and attribution
+
+Diagnostics come in two tiers, 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
+`[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.
+
+Cost and responsiveness findings need the opt-in attribution engine, which records
+every scope that re-ran, what changed to cause it, and how long it took:
+
+```ts
+import { DEV } from 'solid-js';
+
+DEV?.attribution.enable();
+// reproduce the interaction, then ask why a scope ran:
+for (const event of DEV!.attribution.why(total)) {
+  console.log(DEV!.attribution.format(event));
+}
+```
+
+While attribution is enabled, Solid also warns on its own about over-subscription,
+chained async waterfalls (`[ASYNC_WATERFALL]`), memos whose fresh-but-equal output
+never settles (`[UNSTABLE_MEMO_OUTPUT]`), effects that relay state
+(`[EFFECT_RELAY_TEAR]`) or feed their own inputs (`[EFFECT_WRITES_OWN_SOURCE]`),
+immutable updates inside stores (`[IMMUTABLE_UPDATE_IN_STORE]` — mutate the draft),
+row-rebuilding lists (`[UNSTABLE_LIST_IDENTITY]` — key by id or reconcile into a
+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; reported from 300ms as info, from 500ms as a warning). `DEV.attribution.costs()`,
+`holds()`, and `feedback()` rank the session worst-first. Name the scopes you intend
+to interrogate (`createMemo(..., { name: "total" })`); `DEV.attribution.subscriptions(scope)`
+lists a scope's current dependencies to compare against what it uses.
+
+For regression tests, `@solidjs/diagnostics` turns the same channels into assertions:
+
+```ts
+import { captureArtifact } from '@solidjs/diagnostics';
+
+const { artifact } = await captureArtifact(() => {
+  fireEvent.click(getByRole('button', { name: 'Add' }));
+  flush();
+}, { scenario: 'add-item' });
+
+expect(artifact).toHaveNoDiagnostics();
+expect(artifact).toHaveNoSilentHolds();
+```
+
+`toHaveNoDiagnostics` fails on any coded warning (`info` findings excluded);
+`toStayWithinRerunBudget` / `toHaveNoWaste` catch recompute regressions. See the
+debugging-reactivity guide in [references/official-docs.md](references/official-docs.md).
+
 ## Client mode: no server HTML, no hydration reflexes
 
 The `@solidjs/vite-plugin` default (client mode, the `bare` tier) serves an empty-body
@@ -568,7 +853,7 @@ deferred "safe" initial value is worse than unnecessary: if anything persists th
 (an effect writing `localStorage`), the placeholder **overwrites the user's stored
 preference** before the real value is adopted. Mismatch only becomes a concept in
 start/SSR mode, where `hydrate()` mounts onto server HTML — and the Solid answer there is
-`isServer` / `clientOnly`, still not React-style deferred adoption.
+`isServer` / `clientOnly` / per-value `ssrSource`, still not React-style deferred adoption.
 
 ## App stack (only if the project has these packages)
 
@@ -593,6 +878,9 @@ DOM-specific `JSX` types (`JSX.IntrinsicElements`, `JSX.CSSProperties`) and
 with `start: true` / `ssr: true` / `serverFunctions: true` only when the
 project already uses start mode. Tiers are `bare` → `basic` (router) →
 `fullstack` (SSR + server functions); do not jump a tier without cause.
+Under `start: true` the plugin owns entries, the document shell, and the build —
+write `src/App.tsx`, not SolidStart-style `entry-client.tsx` / `entry-server.tsx`
+or a hand-written `index.html`.
 
 ### Solid Router 2 — `createRouter`, not JSX `<Route>`
 
@@ -614,7 +902,7 @@ export default function App() {
     <Router>
       {(props) => (
         <>
-          <a href={Router.paths()}>Home</a>
+          <a href={Router.paths}>Home</a>
           <main>{props.children}</main>
         </>
       )}
@@ -637,6 +925,27 @@ 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
+`location.pathname === ...` comparisons are the wrong tool.
+
+Build URLs from `paths`: static segments are properties (`Router.paths.about`, never
+`Router.paths.about()`), parameterized segments are calls (`paths.products(id)`),
+followed by an optional search object and hash (`paths.search({ q, page }, "results")`).
+Nodes stringify in `href` / `navigate()` / `redirect()`, so call with no arguments
+only when an API insists on a plain string.
+
+Search params are the home for shareable state (filter, sort, page): `const [search,
+setSearch] = useSearchParams()` — the setter merges and navigates without scrolling;
+`""` / `undefined` / `null` removes a key. For typed values, put a synchronous
+Standard Schema on the route's `search` field and pass the path node:
+`useSearchParams(Router.paths.search)` (async schemas throw; a failing schema leaves
+the raw strings rather than throwing).
+
 **Two different `action`s.** Core `action` from `solid-js` is a generator transaction
 (optimistic writes that span an async gap). Router `action` from `@solidjs/router` is
 a URL-addressable POST mutation (`useSubmissions`, `<form action={save} method="post">`).
@@ -661,6 +970,59 @@ Only POST forms are accepted. Bind extra args with `.with(id)` (they go in the
 action URL). `onSubmit={(e) => { e.preventDefault(); fetch(...) }}` *runs* and
 drops the no-JS form fallback. `useAction` is JS-only for the same reason.
 
+Validated forms come in three passes sharing one HTML shape. Pass 1 (above) posts
+uncontrolled inputs with browser `required` / `pattern` — it works with no JavaScript.
+Pass 2 validates on the server, where the user cannot bypass it:
+
+```ts
+import { redirect, respond } from '@solidjs/web';
+import * as v from 'valibot';
+
+const Address = v.object({
+  postalCode: v.pipe(v.string(), v.regex(/^[0-9]{5}$/, 'Enter a five-digit postal code')),
+});
+export type AddressIssues = Partial<Record<'postalCode', string>>;
+
+export async function saveAddress(form: FormData) {
+  'use server';
+  const parsed = v.safeParse(Address, Object.fromEntries(form));
+  if (!parsed.success) {
+    const issues: AddressIssues = {};
+    for (const issue of parsed.issues) {
+      const field = issue.path?.[0]?.key as keyof AddressIssues | undefined;
+      if (field && !issues[field]) issues[field] = issue.message;
+    }
+    throw respond({ issues }, { status: 400 });
+  }
+  await database.addresses.save(parsed.output);
+  return redirect('/checkout/shipping');
+}
+```
+
+Keep server functions in `src/data/`, not under `src/routes` (with method discovery
+on, a `.ts` file there is an API route). `throw respond(...)` is intentional control
+flow — the status and value survive production sanitization, unlike a plain thrown
+`Error`. Pass 3 renders the messages inline from the recorded submission:
+
+```tsx
+import { action, useSubmissions } from '@solidjs/router';
+
+const submitAddress = action(saveAddress);
+const submissions = useSubmissions(submitAddress);
+const issues = () => (submissions.at(-1)?.error as { issues?: AddressIssues } | undefined)?.issues ?? {};
+
+<Show when={issues().postalCode}>{(message) => <p role="alert">{message()}</p>}</Show>
+```
+
+`issues()` is a plain derived function; `aria-invalid` on the input, `role="alert"`
+on the message. Redirect outcomes do not stay in the list; the no-JS outcome arrives
+via flash cookie as the same submission shape. Pending state is CSS on the automatic
+attribute — `form[aria-busy] button[type="submit"] { opacity: .6 }` — no component
+code. `submission.clear()` on dismiss/resubmit only, never from an effect (errors
+would flash and vanish). Live per-keystroke validation is a controlled input plus a
+memo message (`aria-live="polite"`), keeping `name` so `FormData` still works; leave
+the rest uncontrolled.
+
 **`query` is the read cache** (optional, only with the router). Wrap a read,
 give it a stable name, and consume it through a Solid async primitive:
 
@@ -689,7 +1051,8 @@ router mutation, `revalidate(...)` — not core `refresh()`, and not
 refresh cached data: `return reload({ revalidate: "todos" })`). `live()` sources
 update through the open stream; do not `revalidate` them. Replace SolidStart /
 Router 0.x leftovers: no `createAsync`, `useSubmission` (singular), `cache()`,
-router `json()`, or `<FileRoutes />` (`fileRoutes(pageRoutes)` instead).
+router `json()`, or `<FileRoutes />` (`fileRoutes(pageRoutes)` from `@solidjs/router/fs`
+over `pageRoutes` from `virtual:file-routes` instead).
 
 ### Server functions — `"use server"`
 
@@ -702,11 +1065,23 @@ export async function findUser(id: string) {
 ```
 
 A function-level server function cannot close over component locals — pass
-values as arguments. Treat every argument as untrusted. Read trusted identity
+values as arguments. Treat every argument as untrusted — TypeScript does not
+cross the HTTP boundary, so do not invent tRPC / RPC type-gen;
+validate inside the function (a parse in the function body is that
+validation, not an RPC schema across the wire). These functions *are* the RPC — do not add an
+API-route file (or a Next `route.ts`) just to wrap `db.todos.insert`. API
+routes are for real HTTP endpoints (webhooks, third-party POST), not for the
+app's own RPC. Read trusted identity
 from `getRequestEvent()`, never from a caller-supplied user id. During SSR the same
-reference runs in-process; in the browser it is HTTP. Mutations that should
+reference runs in-process (no HTTP); in the browser it is HTTP. Anything
+referenced only inside the `"use server"` body (db client, secrets) never
+reaches the client — the directive is the privacy boundary. Mutations that should
 revalidate: `redirect` / `reload` from `@solidjs/web` (see the server-function
-guides). For 404 during SSR: `httpStatus(404)` from `@solidjs/web`.
+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`
+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
 failures. Do not `return Response.json(...)` from `"use server"` — that is
@@ -715,9 +1090,71 @@ caller unwraps. JSON-encodable arguments only unless `enableRichArguments()`
 was called once in the client entry (`Date` / `Map` / `Set` throw without it).
 `GET()` is only for idempotent reads (URLs leak into logs/history);
 import it from `@solidjs/web/server-functions`, never `@solidjs/start`.
+Reads are function calls too: `GET(async (id) => { "use server"; ... })` is invoked
+as `await getUser(id)` — Solid owns the endpoint, serialization, and decoding, the
+database access stays on the server, and argument/return types flow to the caller.
+The HTTP method mirrors the operation (reads GET, mutations POST); when encoded
+arguments would exceed the URL limit the client falls back to a read-only POST.
+Cache GET reads with HTTP, not a hand-rolled Solid cache: responses default to
+`Cache-Control: no-store`, so supply the policy via `respond()` — the caller still
+receives the value; headers ride the transport.
+
+```ts
+import { respond } from '@solidjs/web';
+import { GET } from '@solidjs/web/server-functions';
+
+export const fetchStory = GET(async (id: number) => {
+  'use server';
+  const story = await db.stories.find(id);
+  return respond(story, {
+    headers: { 'cache-control': 'public, max-age=60, s-maxage=300' },
+  });
+});
+```
+
 `live()` yields **current state** (each yield replaces the last); do not treat
-it as an append-only event log, and hoist the memo so consumers share one
-connection.
+it as an append-only event log. Until the first yield it is unsettled
+(`<Loading>`), same as a Promise; later yields are updates — the fallback does
+not return.
+Wire status is a side channel on the **iterable the `live()` call returns**,
+not a field in the value and not a property of the memo:
+
+```ts
+const source = stockPrice("ACME");
+source.onstatus = (next) => setStatus(next);
+const price = createMemo(() => source);
+```
+
+Do not yield `{ price, connected: true }`. After the first successful connection,
+transient failures retry with exponential backoff; a 4xx is a definite rejection.
+There is no subscription API and no store wiring to configure. For a reactive
+argument, call `live()` inside the memo so the input is tracked:
+`createMemo(() => stockPrice(props.symbol))`. Every reader of that memo shares
+one connection — hoist it instead of calling `live()` at each site. Do not
+subscribe/unsubscribe in the component around `live()`. The `live()` generator
+may still subscribe to an upstream source.
+
+**The graph continues across the wire.** An in-flight Promise serializes as a
+Promise and resolves in the client graph as it settles — including before the
+bundle has loaded. A `live()` source sends its first value in the HTML then
+picks up the stream. Do not refetch in `onSettled` / `hydrate` to "load for the
+client", and do not delay `renderToStream` to preserve visual order — `<Reveal>`
+controls when content *appears*, while HTML still ships as soon as it is ready.
+With the router's single-flight integration, a mutation response can seed the
+destination route's preloads; that is the refresh, not a follow-up `fetch`.
+When the app has a server bundle (`ssr` or server functions), production is
+`handleRequest(request)` from the built `dist/server/server.js` (or that
+module's Fetchable default `fetch`) — not an import from `solid-js`. Cloudflare /
+Netlify / Nitro Vite plugins adopt that handler — do not write a Solid adapter,
+a custom Worker, or a Netlify Function. For Node, use the official template
+`server.js` (web `Request` in, stream the response); do not invent an
+Express/Solid bridge. Client-only `start: true` is still static `dist/client`
+— there is no handler to wrap. Request middleware is the Vite option
+`start: { middleware: "./src/middleware.ts" }` (web `Request` + `next`), not
+Express `app.use`. Server functions that return components
+(`serverFunctions: { components: true }`) are experimental preview — do not use
+them unless the project already has that flag on.
+
 Unscripted forms: `<form method="post" action={createTodo.url}>` (the reference
 `.url`), not a client `preventDefault` + `fetch`, and not a hand-built
 `/_server/` URL. GET forms (`method="get" action={search.url}`) are only for
@@ -755,15 +1192,16 @@ how to reuse. Prefer the form on the right.
 | `const rest = { ...props }` | `const rest = omit(props, "label")` |
 | `const user = createMemo(async () => { await fetch(...); return id(); })` | read `id()` **before** `await` |
 | `action(async function* () { await save(); setX(v); })` | `yield save()` or `await save(); yield; setX(v)` |
+| `action(async (item) => { ... })` with core `action` from `solid-js` | `action(function* (item) { ...; yield ...; ... })` — only a generator re-enters the transaction (`solid2-kit check` flags this). Router `action` from `@solidjs/router` is the one that takes `async (form) => ...` |
 | `todos()` on a store | `todos.length` / `todo.title` (property reads) |
-| `setTodos((t) => t.filter((x) => x.ok))` | mutate the draft, or `reconcile` |
+| `draft.todos = fresh` (wholesale fresh-tree assignment) | `reconcile(fresh, "id")`, or function-form `createStore` / `createProjection` (auto-keyed by `"id"`). Removal via `setTodos((t) => t.filter(...))` is fine — survivors keep identity |
 | `createEffect(() => user, (u) => log(u.name))` | `createEffect(() => user.name, (name) => log(name))` |
 | `<Loading fallback={<PageSkeleton />}>{/* header + data */}</Loading>` | wrap only the data slot; chrome stays outside |
 | `<Loading on={id} fallback={...}>` (the accessor) | `on={id()}` — a value, so identity changes can show fallback |
 | `setCount(count() + 1)` when writes can batch | `setCount((c) => c + 1)` |
 | `setHandler(fn)` to store a function | `setHandler(() => fn)` (otherwise `fn` is an updater) |
 | `{user() ? <P user={user()!} /> : <SignIn />}` | `<Show when={user()}>{(u) => <P user={u()} />}</Show>` |
-| `<Child user={user()} />` for an async memo | `<Child user={user} />` and read `props.user()` under the child's `<Loading>` |
+| `const u = user(); return <Child user={u} />` / `user: Promise<User>` / `user: Accessor<User>` as the default | `<Child user={user()} />` and `{props.user.name}` under `<Loading>` — types stay `User`. Pass the memo itself only when the child must `refresh()` that source. `isPending(() => props.user)` works on the value |
 | `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)}` |
@@ -774,6 +1212,7 @@ how to reuse. Prefer the form on the right.
 | `<For each={rows.slice(from, from + n)}>` | `<Repeat from={from()} count={n}>` |
 | `{count() && <Badge />}` | `<Show when={count()}>` — `0` must not render as text |
 | `throw new Error("expired")` from a server function (prod) | `throw markSafeError(...)` or `throw respond(body, { status })` |
+| `const r = await api.x(); if (!r.ok) ...` result-object checks at every read | throw unusable responses; contain each region with `<Errored>` |
 | `GET(async (id) => { "use server"; await db.delete(id) })` | mutations stay on POST; `GET()` is for idempotent reads |
 | `live()` yields as an event log to append | each yield **replaces** the current answer; yield current state first |
 | `<article innerHTML={html()}>…children…</article>` | `innerHTML` **or** children, not both |
@@ -787,6 +1226,7 @@ how to reuse. Prefer the form on the right.
 | `renderToString(() => <App />)` for an async or lazy-route tree | `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`). String render emits `<Loading>` fallbacks |
 | `clientOnly(() => import("./Map"))` for a rarely shown widget | same + `{ lazy: true }` so the import waits until first render (default starts at declaration) |
 | `<NoHydration><Chart /></NoHydration>` to skip SSR of a widget | `clientOnly(() => import("./Chart"))` — `NoHydration`/`Hydration` split ownership, they do not choose visible content |
+| `clientOnly` split (or `isServer` branch) for one browser-only *value* | `createMemo(() => localStorage.getItem(k), { ssrSource: "client" })` — `"hybrid"` when server data mixes with client signals |
 | `await flush()` / `flush()` to wait on a pending memo | `await resolve(() => value())` (or Testing Library async queries); `flush()` only drains staged *sync* writes |
 | `action(function* () { setX(v); })` around a navigation-shaped setter | plain setter; async computeds hold previous values. Core `action` only when writes happen *after* async work |
 | `createContext` + a root provider for a true app singleton | module-level signal/store (SSR: shared across requests). Context is subtree scoping |
@@ -802,6 +1242,8 @@ how to reuse. Prefer the form on the right.
 | `const View = tab() ? A : B; return <View />` | `const View = dynamic(() => (tab() ? A : B))` — the ternary at setup freezes the choice |
 | `<For each={resolved()}>` after `children()` | `{resolved.toArray()}` — resolved children are not a reactive data list |
 | `<input onChange={...}>` for keystrokes | `onInput` — native `onChange` is blur/commit |
+| debounce as an effect copying one signal into another | debounce at the handler: `onInput={debounce((e) => setQuery(e.currentTarget.value), 150)}` |
+| `value={query()}` on a search box whose writes feed a request | `value={latest(query)}` so keystrokes show while the write is held (uncontrolled needs nothing) |
 | `createOptimistic` for a local edit draft | writable derivation / plain store. Optimistic is for an in-flight mutation |
 | `createMemo(async fn, { loadingValue })` / `{ seedLoadingValue: true }` as the default first-flight UI | `<Loading>` for first flight; those options are escape hatches (store projections use `seedLoadingValue`) |
 | `setSubmitted(true)` + an effect that watches it | do the work in the handler or an `action` |
@@ -809,14 +1251,31 @@ how to reuse. Prefer the form on the right.
 | `action={"/_server/" + id}` in app JSX | `action={createTodo.url}` or a router `action` |
 | `<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 |
+| `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) |
 | `try { user() } catch (e) { /* NotReadyError */ }` | `<Loading>` — app code should not catch `NotReadyError` |
 | `{latest(() => results())}` as the visible list | settled read + `isPending()` for the indicator; `latest` is for previews |
+| `selectedId={latest(selectedId)}` as the default highlight | `selectedId={selectedId()}` so highlight and content stay consistent; `latest` only when the highlight should move first |
+| `isPending` on a root/global pending signal, or wrapping the whole shell | ask the question at the design site (dimmed list, disabled button, pane). It works on the source, a derived prop, or the write |
+| `<Loading>` glued to the `createMemo` (consume + block in one place) | fetch high, block low — the boundary wraps the read, not the creation |
+| `class={{ pending: isPending(id) }}` flashing on every navigation | same class + a short CSS `transition-delay` so only slow swaps show |
+| `<Comments />` nested under `{story().title}` assumed to waterfall | both mount immediately and fetch in parallel if the child reads an already-known id; a real waterfall is `createMemo(() => fetchAuthor(story().authorId))` or `storyId={props.story.id}` |
+| `<Errored>` as a terminal ErrorBoundary; `reset={() => location.reload()}` | the boundary heals when the source succeeds again; `reset` retries collected *sources*, not a UI remount |
+| `<Errored>` around a list catching a toggle/save failure | catch expected mutation failures in the `action`; keep row errors in a map the projection folds in (survives overlay discard) |
+| `yield { ...tick, connected: true }` from `live()` | yield the value; wire status is `source.onstatus` (`"connected"` / `"reconnecting"` / `"closed"`) |
+| sibling `<Loading>` fallbacks stacking as popcorn | `<Reveal collapsed>` (sequential default) suppresses tail skeletons past the frontier |
+| in-memory cache around a GET server function | `return respond(value, { headers: { "cache-control": "..." } })` — metadata rides HTTP, the value rides the graph |
+| `story()?.title` / treating `story()` as `Story \| undefined` | `{story().title}` under `<Loading>` — if the computation is running, the value is there |
 | `typeof window !== "undefined"` | `isServer` / `isDev` from `@solidjs/web` |
 | `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 |
+| 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 |
+| `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 |
@@ -837,6 +1296,16 @@ how to reuse. Prefer the form on the right.
 | `createRenderEffect` / `createTrackedEffect` as the default effect | two-phase `createEffect(compute, apply)` |
 | `createEffect(() => source(), () => setError(null))` to reset a signal | `createSignal(() => { source(); return null; })` — the writable derivation resets on change; a sole-setter apply is rule 4 |
 | a "server-safe" initial value adopted after mount (React hydration-mismatch fix) | client mode mounts with `render()` into an empty body — no hydration, no mismatch; read `localStorage` / `matchMedia` directly at signal creation |
+| rewrite `App.tsx` with loading/error branches, or snapshot/restore, when the list moves to the server | same `setTodos`; wrap mutations in `action`; swap `createOptimisticStore` + a server-functions file. The overlay is discarded; the confirmed store is the truth |
+| disable an optimistic row until ack, or mutex rapid clicks / freeze unrelated writes | keep the control enabled; `action` is the transaction. An in-flight action does not freeze other writes. Failed-action replay is optional |
+| tRPC / RPC type-gen around `"use server"` | TypeScript does not cross HTTP — validate inside the function. Locals only the body reads (db, secrets) stay off the client |
+| `src/routes/api/todos.ts` (or a Next `route.ts`) wrapping `db.todos.insert` | `"use server"` *is* the RPC. API routes are for real HTTP endpoints (webhooks), not the app's own mutations |
+| router/server mutation, then `fetch` / `onSettled` / `hydrate` to refresh the page | `reload` / `revalidate` / single-flight (the mutation response can seed destination preloads). In-flight Promises serialize as Promises; `live()` continues from HTML |
+| delay `renderToStream` so HTML arrives in visual order | stream as soon as ready; `<Reveal collapsed>` controls when content *appears* |
+| subscribe/unsubscribe in the component around `live()` | `createMemo(() => stockPrice(props.symbol))` — hoist that memo to share one connection. `onstatus` is on the iterable the `live()` call returns, not on the memo. Until the first yield, `<Loading>`; later yields are updates |
+| a Solid adapter / custom Worker / Express bridge, or `entry-client.tsx` under `start: true` | With a server bundle: `handleRequest` from `dist/server/server.js` / Fetchable `fetch`; platform plugins adopt it. Node: template `server.js`. Client-only start: static `dist/client`. Middleware is `start: { middleware: "..." }`, not Express `app.use` |
+| `createMemo(async () => (await props.story).author)` | `createMemo(() => props.story.author)` — a derivation over an async value becomes async; no await, no Promise type |
+| return a component from `"use server"` / flip `serverFunctions.components` | experimental preview — do not enable unless the project already has that flag |
 
 ```tsx
 // WRONG — post-await read never subscribes; production can hang pending
@@ -869,23 +1338,24 @@ function Field(props: { label: string; class?: string }) {
 ```
 
 ```tsx
-// WRONG — user() throws not-ready at Page; child's <Loading> never sees it
+// WRONG — extracting at the parent is a real read; child's <Loading> never sees it
 function Page() {
   const user = createMemo(async () => (await fetch('/api/me')).json());
-  return <Profile user={user()} />;
+  const current = user();
+  return <Profile user={current} />;
 }
 
-// CORRECT — pass the accessor; read it under the boundary that owns the fallback
-function Profile(props: { user: Accessor<User> }) {
+// CORRECT — JSX props are lazy (passing isn't reading); types stay User
+function Profile(props: { user: User }) {
   return (
     <Loading fallback={<p>Loading…</p>}>
-      <h1>{props.user().name}</h1>
+      <h1>{props.user.name}</h1>
     </Loading>
   );
 }
 function Page() {
   const user = createMemo(async () => (await fetch('/api/me')).json());
-  return <Profile user={user} />;
+  return <Profile user={user()} />;
 }
 ```
 
@@ -960,21 +1430,39 @@ always-applied rules installed alongside this skill.
       is a writable derivation (`createSignal(() => { source(); return initial; })`), not
       an effect calling the setter.
 - [ ] Event handlers wrap setters (`onClick={() => setX(...)}`), use `currentTarget`,
-      and `onInput` for keystrokes. `innerHTML` is sanitized and not mixed with children.
-- [ ] Async memos are passed as accessors (`user={user}`), not `user={user()}`, so
-      `<Loading>` around the *read* can catch not-ready.
+      and `onInput` for keystrokes. Debounce at the handler, never as an effect copying
+      signals. `innerHTML` is sanitized and not mixed with children.
+- [ ] Async memos are passed as values (`user={user()}`); JSX props are lazy.
+      Types stay `User` — not `Promise<User>` / `Accessor<User>`. `<Loading>` wraps
+      the *read*, not the memo, not chrome. Extracting `const u = user()` at the
+      parent is the read that throws. Nested child fetches run in parallel
+      (components do not suspend); a real waterfall is `fetchB(a().id)`.
+      `isPending` is per-expression (`isPending(() => props.story)` works);
+      `latest(selectedId)` is opt-in, not the default highlight. Inputs feeding a request
+      bind `latest(query)`; failures throw to `<Errored>`, never `{ success: false }`
+      result objects checked at every read.
 - [ ] Lists via `<For>` (server/refetched rows keyed by stable id), conditionals via
       ternary/`<Show>`; no `{list().map(...)}` in JSX; no `key` props; no `value()!`.
 - [ ] Effects are two-phase and only at imperative boundaries; apply does not read stores.
 - [ ] Async reads sit under `<Loading>` (the data slot, not chrome); errors under `<Errored>`.
       Reactive inputs of an async memo are read before the first `await`. No hand-rolled
       `loading`/`error` signals or `=== undefined` readiness branches. First load is
-      `<Loading>`; refetch indicator is `isPending(user)` (the accessor, not `user()`).
-      Core `refresh(source)`, router `revalidate(key)`, and `return reload(...)` are
-      different APIs — do not mix them.
+      `<Loading>`; refetch indicator is `isPending(user)` (the accessor, not `user()`)
+      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
+      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
+      `hydrate` / `onSettled`. HTTP does not enforce TypeScript — validate
+      inside `"use server"`; do not invent tRPC. `live()` owns the client connection.
+      A server bundle uses `handleRequest` from `dist/server/server.js`; client-only start
+      is static `dist/client`. Do not delay `renderToStream` for visual order
+      (`<Reveal>` does).
 - [ ] External collections reconcile into stores (function-form `createStore` /
-      `reconcile`), never wholesale draft assignment or `setTodos((t) => t.filter(...))`
-      as the identity-preserving update.
+      `reconcile`), never wholesale draft assignment of a fresh tree
+      (`setTodos((t) => t.filter(...))` for removal is fine — survivors keep identity).
 - [ ] Rest props via `omit`, not `{ ...props }`. Conditional `class` via objects, not string concat.
 - [ ] Input filters write back to the DOM on reject (inputs do not rewind).
 - [ ] No Solid 1.x imports or APIs (`solid-js/store`, `createResource`, `onMount`, `Suspense`, ...).
@@ -982,12 +1470,25 @@ always-applied rules installed alongside this skill.
       `solid-js`; DOM `JSX` types come from `@solidjs/web`.
 - [ ] Inspect children with `children()`; code-split with `lazy` + `<Loading>`; reactive
       component choice with `dynamic()`. No `React.lazy`, no effects inside ref callbacks.
-- [ ] Browser-only code uses `isServer` / `clientOnly`, not `typeof window`.
+- [ ] Browser-only code uses `isServer` / `clientOnly` (components) / `ssrSource`
+      (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
+      (`[IMMUTABLE_UPDATE_IN_STORE]`, `[UNSTABLE_LIST_IDENTITY]`, `[EFFECT_*]`)
+      checked via `DEV.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
-      core `action`/`refresh`. Forms: `<form action={save} method="post">`.
+      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
+      (`throw respond({ issues }, { status: 400 })`) with inline errors from
+      `useSubmissions`.
 - [ ] `render(() => <App />, root)` — a function, not `render(<App />)`. `hydrate` when
       HTML already exists. Stream async/lazy trees (`await renderToStream(...)`) with
       exactly one consumer (`pipe` / `pipeTo` / `readable`). Snapshot stores with