solid2-agent-kit 0.13.0 → 0.14.0

package/files/commands/solid2-review.md

@@ -34,6 +34,9 @@ Steps:
      `[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;
+   - mutations on a value read through `live()` that settle on `yield save()` alone or
+     `refresh()` the live-derived store, instead of `yield until(predicate, { timeout })`
+     for the stream's echo (the old value flashes back when the overlay drops);
    - rewriting App with loading/error branches, or snapshot/restore, when wrapping
      a client store in server functions; disabling optimistic rows until ack;
    - tRPC / type-gen around `"use server"`, a client `fetch` after a mutation,

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, `[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>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.
+- Solid 2.0 shipped recently and breaks with 1.x — never trust pre-2.0 Solid docs, tutorials, or training knowledge. Verify APIs against https://v2-rebuild--solid-docs-v2.netlify.app/llms.txt (markdown mirror of https://v2.solidjs.com/, which blocks non-browser fetchers). If the project has `@solidjs/router`, server functions, or `@solidjs/meta`, use those official pages (see the skill's official-docs index) — not React Router, Next.js, SolidStart 1.x, or Solid Router 0.x/1.x JSX `<Route>`/`<A>`. Core `action` from `solid-js` is a generator transaction; router `action`/`query` from `@solidjs/router` are POST forms and a read cache. Core `refresh(source)`, router `revalidate(key)`, and server-function `return reload(...)` are three different APIs. Pass the accessor to `isPending(user)`, not `isPending(user())`. Pass async values as values (`user={user()}`) — JSX props are lazy; types stay `User`, not `Promise<User>`. `<Loading>` wraps the read, not the memo. Nested fetches run in parallel (components do not suspend). `isPending` is a per-expression question (`isPending(() => props.story)` / `isPending(selectedId)`), not a global spinner; `latest(selectedId)` is opt-in so highlight and content stay consistent by default. `<Errored>` heals when the source succeeds. Pass a function to `render`/`hydrate`: `render(() => <App />, root)`. Component teardown is `onSettled`, not `onCleanup`. 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`. Confirmations on another channel — fire-and-forget sends, and mutations whose result is read through `live()` — wait with `yield until(predicate, {timeout})`, not `refresh()`. Declare `live(GET(fn))` (`live()` outermost). Debounce at the handler; inputs feeding a request bind `latest(query)`. Dev diagnostics are errors: `[STRICT_READ_UNTRACKED]` means a read outside a tracking scope, `[ASYNC_STORE_SETTER]` means a store setter callback awaited (the draft is a synchronous transaction — await first, then write), 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>`; the server hook must return a reference or nothing, never the error itself. `<Dynamic>` is deprecated — use `dynamic()`. Observability is on by default in development: whenever a change touches stores, lists, async, actions, or effects, keep the dev console free of `[CODE]` findings and run an attribution session (`/__solid/diagnostics` `begin` → interact → `whyDidRun` / `costs` → `end` with `@solidjs/diagnostics` installed, otherwise `isDev`-guarded `attribution.enable({ log: false })` + `why()` / `costs()`) before finishing. `vite dev` is always the dev build; `solid({ observe: true })` is a production opt-in.

package/files/shared/rules-body.md

@@ -242,9 +242,16 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     `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
-    optional. Fire-and-forget confirmations wait with `yield until(predicate,
-    { timeout })` — the predicate reads authoritative state. Except reactive clients (e.g. Convex) whose subscriptions already push authoritative
-    state after mutations. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
+    optional. Confirmations that arrive on another channel wait with `yield until(predicate,
+    { timeout })` — the predicate reads authoritative state, so the overlay cannot satisfy it.
+    That covers fire-and-forget sends **and** request/response mutations whose result is
+    read through a `live()` source: `live()` takes no part in revalidation or single-flight,
+    so after `yield save()` alone the overlay drops before the stream echoes the write and
+    the old value flashes back. Follow it with `yield until(...)`, not `refresh(liveStore)`
+    (that re-runs the derivation — the stream closes and the source reconnects — so each
+    mutation costs a reconnect, and the flash remains whenever the new connection's first
+    value predates the write). Skip `until` only for reactive clients (e.g. Convex)
+    whose subscriptions already carry the write when the mutation resolves. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
     Vite plugin is `@solidjs/vite-plugin` (not `vite-plugin-solid`) — run `solid2-kit doctor`
     after touching `package.json` / tsconfig / root configs; it fails on React and Solid 1.x
     wiring. Server vs browser:
@@ -346,7 +353,10 @@ Claude Code) for full patterns, decision tables, and official documentation URLs
     components from `"use server"` unless the project already enabled the
     experimental `serverFunctions.components` flag. JSON-encodable server-function arguments
     only, unless `enableRichArguments()` was called once in the client entry
-    (`Date` / `Map` / `Set` throw without it). `live()` connection state is
+    (`Date` / `Map` / `Set` throw without it). Declare live reads as `live(GET(fn))` —
+    `live()` outermost. A plain `async function*` server function is an event stream on
+    one connection (no reconnect when it drops); `live()` is one value that changes over
+    time and reconnects. `live()` connection state is
     `source.onstatus` (`"connected"` / `"reconnecting"` / `"closed"`), never a
     field in the yielded value. Sibling `<Loading>` reveal order is `<Reveal>`
     (`collapsed` suppresses tail skeletons under sequential order).

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

@@ -632,6 +632,38 @@ 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.
 
+The same hold applies when the mutation *does* answer but the value is read through a
+`live()` source. A live source updates only through its open stream — it takes no part
+in revalidation or single-flight mutation data — so the mutation's response and the
+stream's echo race. Settle on `yield saveBid(...)` alone and the overlay is discarded
+first: the old bid flashes back until the stream catches up.
+
+```tsx
+import { action, createOptimisticStore, until } from 'solid-js';
+import { liveAuction, saveBid } from '../data/auction';
+
+function Auction(props: { id: string }) {
+  const [auction, setAuction] = createOptimisticStore(() => liveAuction(props.id), { highBid: 0 });
+
+  const bid = action(function* (amount: number) {
+    setAuction((a) => { a.highBid = amount; });                    // overlay
+    yield saveBid(props.id, amount);                                 // the write goes up
+    yield until(() => auction.highBid >= amount, { timeout: 10_000 }); // hold for the echo
+  });
+
+  return <button onClick={() => bid(auction.highBid + 1)}>Bid {auction.highBid + 1}</button>;
+}
+```
+
+Do not `refresh(auction)` in place of `until`: on a store derived from a live source it
+re-runs the derivation — the current stream is closed and `liveAuction()` opens a new
+connection. That costs a reconnect per mutation and hides the flash only when the new
+connection's first value already includes the write; when the read side lags the write,
+the old value still flashes back before the echo. Reactive clients whose
+subscriptions already carry the write when the mutation resolves (e.g. Convex) need
+neither. The server side of `liveAuction` / `saveBid` is in
+[Server functions](#server-functions--use-server).
+
 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
 new ones are ready (`isPending` / `latest`). Reach for `action` from `solid-js` only
@@ -1367,8 +1399,42 @@ export const fetchStory = GET(async (id: number) => {
 });
 ```
 
+A value that changes over time is `live(GET(fn))` — **`live()` outermost**: `GET()`
+chooses the read transport and `live()` wraps the call behavior around it. `live()`
+does not imply `GET()`; without it the source streams over POST, which is fine when a
+cacheable URL is of no use.
+
+```ts
+// src/data/auction.ts
+import { GET, live } from '@solidjs/web/server-functions';
+
+export const liveAuction = live(
+  GET(async function* (id: string) {
+    'use server';
+    yield await db.auctions.find(id); // current state first, from storage
+    for await (const _change of db.auctions.subscribe(id)) {
+      yield await db.auctions.find(id);
+    }
+  }),
+);
+
+export async function saveBid(id: string, amount: number) {
+  'use server';
+  await db.bids.place(id, amount);
+}
+```
+
+A plain `async function*` server function (no `live()`) is a different tool: an
+**event sequence** on one connection, consumed with `for await` and accumulated. When
+that connection drops, the iteration ends with an error and nothing reopens it; ending
+the iteration in the browser aborts the request and fires the server's
+`request.signal`. Use it for an order's status history; use `live()` when each value
+replaces the previous one.
+
 `live()` yields **current state** (each yield replaces the last); do not treat
-it as an append-only event log. Until the first yield it is unsettled
+it as an append-only event log. A reconnect calls the function again and its first
+yield replaces the stale answer, so read that first value from the state mutations write
+to (database, shared server state) — not from generator locals or per-connection memory. 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**,
@@ -1469,7 +1535,10 @@ how to reuse. Prefer the form on the right.
 | `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 |
+| `live()` yields as an event log to append | each yield **replaces** the current answer; yield current state first, read from the state mutations write to — a reconnect calls the function again, so generator locals or per-connection memory are not the source |
+| `GET(live(async function* () { ... }))` | `live(GET(async function* () { ... }))` — `live()` outermost; `live()` alone streams over POST |
+| a plain `async function*` `"use server"` stream for a value that must survive a dropped connection | `live()` — a plain stream is an event sequence on one connection (`for await`, accumulate); nothing reopens it when it drops |
+| `yield saveBid(...)` then `refresh(auction)` on a store derived from `live()` | `yield saveBid(...); yield until(() => auction.highBid >= amount, { timeout })` — `live()` is outside revalidation/single-flight; `refresh` re-runs the derivation (closes the stream, calls the source again): a reconnect per mutation, and the old value still flashes back whenever the new first value predates the write |
 | `<article innerHTML={html()}>…children…</article>` | `innerHTML` **or** children, not both |
 | `fallback={(error) => <p>{error.message}</p>}` | `error` is an accessor: `error().message` (or `String(error())`) |
 | `import { action } from "solid-js"` on a `<form>` | `import { action } from "@solidjs/router"` + `<form action={save} method="post">` (core `action` is a generator transaction, not a form URL) |
@@ -1726,7 +1795,9 @@ always-applied rules installed alongside this skill.
       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.
+      inside `"use server"`; do not invent tRPC. `live()` owns the client connection,
+      is declared `live(GET(fn))`, and a mutation on a live-read value holds with
+      `yield until(...)` for the echo instead of `refresh()`.
       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).

package/package.json

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