solid2-agent-kit 0.4.2

package/files/shared/rules-body.md

@@ -0,0 +1,222 @@
+# Solid 2.0 — not React, not Solid 1.x
+
+This project uses Solid 2.0 (`solid-js` 2.x). The JSX looks like React but the
+execution model is different: **a component function runs exactly once, at mount**. Updates
+flow from signals/stores directly to the JSX expressions that read them. Components never
+re-render. Solid 2.0 is also **incompatible with Solid 1.x** — treat all Solid 1.x knowledge
+(pre-2.0 tutorials, blog posts, Stack Overflow answers) as wrong for this codebase.
+
+Before writing non-trivial Solid code, read the `solid-2` skill
+(`.cursor/skills/solid-2/SKILL.md` for Cursor, `.claude/skills/solid-2/SKILL.md` for
+Claude Code) for full patterns, decision tables, and official documentation URLs.
+
+## Hard rules (React reflexes to unlearn)
+
+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).
+   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.
+   Mechanically enforced by `solid2-kit check` — run it after editing TSX.
+2. **Never read reactive values at component-body top level.** The body runs once, untracked;
+   `const v = count()` there is a frozen snapshot (Solid warns in dev). Carry the accessor
+   (the function itself) into JSX and call it there.
+3. Signals are read by **calling** them: `{count()}` in JSX, not `{count}`.
+4. **Derived state is a function, not state + effect.** `const full = () => a() + b()`.
+   Never write "a signal plus an effect that syncs it". Use `createMemo` only for expensive
+   computations, multiple consumers, or an equality boundary. When several writes can land
+   before a flush, use the setter updater (`setCount((c) => c + 1)`); `setCount(count() + 1)`
+   reads the last *committed* value and drops the other staged writes. To store a *function*
+   in a signal, wrap it: `setHandler(() => myHandler)` — `setHandler(myHandler)` treats it
+   as an updater.
+5. `class`, not `className`; `for`, not `htmlFor`. `class` accepts strings, conditional
+    objects, and nested arrays: `class={["btn", { active: selected() }]}`. Put *conditional*
+    names in an object — `class={`btn ${on() ? "on" : ""}`}` works but rebuilds the whole
+    string, so Solid cannot add/remove one token. `style` objects use CSS property names
+    (`"background-color"`, not `backgroundColor`) and numbers do NOT auto-append `px`
+    (`width: `${n}px``).
+6. **`onInput` for per-keystroke handling.** Solid's `onChange` is the native change event
+    (fires on blur/commit), not React's per-keystroke `onChange`. Handlers receive native DOM
+    events and run untracked — reading a signal inside a handler always gives the current
+    value (stale closures cannot happen; `useCallback` equivalents are unnecessary).
+    Checkboxes/radios use `checked={...}`, not `value`. Read fields with
+    `event.currentTarget` (the element that owns the handler), not `event.target`
+    (a nested child). Never pass a setter as the handler (`onClick={setCount}`) —
+    that writes the event object; wrap it: `onClick={() => setCount((c) => c + 1)}`.
+7. **Lists use `<For>`**, never `{list().map(...)}` in reactive JSX and never `key` props.
+    `{todos().map((t) => <Row todo={t} />)}` *renders*, then recreates every row on each
+    update. Row identity: default = item reference; `keyed={(item) => item.id}` = key function
+    (child receives item as an accessor); `keyed={false}` = positional. **Rows from
+    server/refetched data (fresh object references on every update — fetch results,
+    subscription payloads) must use a key function on a stable id**, or every update
+    recreates every row. Reference keying is for local arrays whose item identities are
+    stable (e.g. store rows). Match the child signature to the mode: default item is the
+    **raw** value (`todo.title`); `keyed={(t) => t.id}` / `keyed={false}` pass an
+    **accessor** (`todo().title`). Mixing those still “runs” (you render a function, or
+    throw). Empty lists: `fallback` on `<For>`, not a `.length` branch around it.
+    Sliding windows: `<Repeat from={from()} count={n}>`, not `list.slice(from, from+n)`
+    fed to `<For>` (that rebuilds the window array every time).
+8. **Effects have two phases**: `createEffect(compute, apply)`. All reactive reads go in
+    `compute`; its return value feeds `apply`, which does imperative work and may return a
+    cleanup. Single-argument `createEffect(fn)` is an error in Solid 2. Do not substitute
+    `createTrackedEffect` for that — it is an advanced one-callback form that cannot nest
+    primitives. Most React `useEffect` code should not become an effect at all — see the skill.
+9. **Stores update by mutating a draft**: `setStore(draft => { draft.user.name = "Ada" })`.
+   Never rebuild with spreads — that destroys property-level subscriptions. Returning a new
+   array from the setter (`setTodos((t) => t.filter(...))`) *renders* but is unkeyed — same
+   identity loss as wholesale assignment; mutate the draft or `reconcile`. Stores are
+   **property reads** (`todos.length`, `todo.title`), not accessors — never `todos()`.
+10. **Async data is an async computation**: `createMemo(async () => ...)` read under
+    `<Loading>` / `<Errored>` boundaries. Read every reactive input **before the first
+    `await`** — post-`await` reads do not subscribe, and in production the computation can
+    sit pending with no retry. No `useEffect` + `setState` fetching, no `createResource`.
+    `<Loading>` wraps the data slot, not page chrome. After first paint it keeps content
+    during refetch (`isPending` for the indicator). Use `on={id()}` (the *value*, not the
+    accessor) only when that identity change should show the fallback again. Pass an async
+    memo to a child as the **accessor** (`user={user}`), and read `props.user()` under that
+    child's `<Loading>` — `user={user()}` throws not-ready at the parent, so the child's
+    boundary never sees it. "Prop with local edits" = writable derivation:
+    `createSignal(() => props.value)` or `createStore(() => props.value, fallback)`.
+11. Context: the context object is the provider — `<MyContext value={{ theme, setTheme }}>`
+    (no `.Provider`). Pass accessors/setters/stores through context, never snapshot values.
+    `createContext<T>()` without a default throws when read outside a provider (good) — use
+    that for any reactive payload. `createContext("light")` is only for a primitive static
+    fallback; a dummy default on a store/signal context *runs* and then silently no-ops
+    without a provider.
+12. Refs: `let el!: HTMLDivElement` + `ref={el}` or `ref={(node) => (el = node)}`, or forward
+    `props.ref`. Compose with arrays: `ref={[props.ref, (node) => (el = node)]}`. No
+    `useRef`/`.current`. Ref callbacks run untracked and **without an owner**; their
+    return values are ignored. Do not create effects or register cleanup inside a ref
+    callback. For reusable directives, create owned primitives (`onSettled`) in a
+    factory and return only the element callback.
+13. **Writes are staged** and commit on the next microtask. Event handlers need nothing
+    special; tests and imperative integration code must call `flush()` before observing
+    updated state or DOM. Never call `flush()` inside an `action`.
+14. Do not port these React tools — they have no Solid equivalent because the problems they
+    solve don't exist: `useCallback`, `React.memo`, `forwardRef`, `useSyncExternalStore`,
+    dependency arrays, `startTransition`/`useTransition` (updates are held and coordinated
+    automatically; use `isPending` for indicators).
+15. **Components return once.** Never early-return or conditionally return based on reactive
+    values — the branch is chosen once at setup and frozen forever. Put conditionals inside
+    JSX (`<Show>`, ternary, `<Switch>`/`<Match>`). Early returns on genuinely non-reactive
+    values (build-time config, missing env) are fine.
+16. Prefer `textContent` for text-only content. Use `innerHTML` only for trusted or
+    sanitized markup — never interpolate user input into it, never React's
+    `dangerouslySetInnerHTML`, and never combine `innerHTML` with JSX children (they fight
+    over the same contents).
+17. **Never narrow a reactive read with a non-null assertion** (`error()!.message`,
+    `user()!`). Use `<Show when={value()}>` with a function child — it passes a
+    **narrowed accessor**, so no `!` is needed:
+    `<Show when={error()}>{(err) => <p>{err().message}</p>}</Show>`. For non-reactive
+    zero-arg calls, use an explicit guard variable instead of `!`.
+    Mechanically enforced by `solid2-kit check`.
+18. **Never hand-roll async UI state.** No `[loading, setLoading]` signals, no
+    `data() === undefined` readiness branches, no `{ data, error }` signal pairs from
+    integration layers. Model async as a computation (return a promise or async iterable
+    from a memo/store) and let the framework own the states: first load = `<Loading>`
+    fallback; refetch indicator = `isPending()`; errors = thrown into the graph and caught
+    by `<Errored>`; speculative value = `latest()`. Mechanically enforced by
+    `solid2-kit check` (loading-signal naming, zero-arg-call undefined checks).
+19. **Refetch is `refresh(source)`** — rarely needed, but when it is, never fake it with a
+    counter/version signal read inside the computation. Input-driven refetch is automatic
+    (tracked inputs re-run the computation) and subscriptions push. Legit uses: after a
+    mutation inside an `action`, and explicit reload buttons. Pair with `affects(source)`
+    when the reload should present as pending.
+20. **External collections flow into stores through reconciliation.** First choice:
+    function-form `createStore(() => source, fallback)` / `createProjection` (reconcile
+    automatically, keyed by `"id"`). Manual merge: `setStore(reconcile(fresh, "id"))` or
+    apply `reconcile(fresh, "id")(draft.slot)` inside a draft setter. Plain wholesale
+    assignment (`draft.todos = fresh`) renders correctly but notifies every subscriber
+    under the path and destroys row identity — same class of problem as unkeyed `<For>`.
+21. **Solid inputs do not rewind the DOM.** `value={v()}` writes only when `v` changes; a
+    React-style controlled input that ignores invalid keystrokes silently breaks. To reject
+    input, write back explicitly:
+    `onInput={(e) => { if (valid(e.currentTarget.value)) setV(e.currentTarget.value); else e.currentTarget.value = v(); }}`.
+22. Miscellaneous defaults: SSR-stable element ids come from `createUniqueId()` (never
+    `Math.random()` or hardcoded duplicates); pass store data to `structuredClone` /
+    `postMessage` / logs via `snapshot(store)` (proxies fail or leak reactivity); render
+    modals/tooltips/overlays through `<Portal>` from `@solidjs/web`; mutations whose writes
+    cross an async gap default to `action` + `createOptimistic`/`createOptimisticStore` —
+    except reactive clients (e.g. Convex) whose subscriptions already push authoritative
+    state after mutations. Compiler: `"jsxImportSource": "@solidjs/web"` (not `"solid-js"`);
+    Vite plugin is `@solidjs/vite-plugin` (not `vite-plugin-solid`). Server vs browser:
+    `isServer` / `isDev` from `@solidjs/web`, or `clientOnly(() => import("./Widget"))` for
+    browser-only components — never `typeof window` as the SSR boundary. `JSON.stringify(store)`
+    / `structuredClone(store)` without `snapshot(store)` can throw or leak proxies. Async SSR
+    without `<Loading>` *works* but blocks the HTML shell until every read settles — wrap
+    reads, or stream with `renderToStream`.
+23. **Composition.** Pass `props.children` through when you only render them. Inspect or
+    iterate children with `children(() => props.children)` (then `.toArray()`), never a
+    setup-time snapshot. Code-split with `lazy(() => import("./X"))` under `<Loading>` —
+    not `React.lazy` / `<Suspense>`. Named exports: `lazy(() => import("./pages"), { export: "About" })`
+    — `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 })`
+    at module scope — not JSX `<Route>` / `<A>` / `<HashRouter>`. Document head is
+    `<Title>` / `<Meta>` from `@solidjs/meta` with **no** `MetaProvider`.
+
+## Lint heritage: eslint-plugin-solid (Solid 1.x) intents carried into this file
+
+`eslint-plugin-solid` targets Solid 1.x. **Do not install it** — its analyzer predates the
+Solid 2 model and misreads two-phase `createEffect`, writable derivations
+(`createSignal(fn)`), and draft setters as errors. Its still-valid intents are enforced here
+instead, and `solid2-kit check` checks the mechanically detectable ones on the source
+directory (default `src/`).
+
+| 1.x lint rule | Status in Solid 2 | Where |
+|---|---|---|
+| `solid/no-destructure` | still critical | rule 1 + `solid2-kit check` |
+| `solid/reactivity` | still critical | rules 2–3 (+ Solid 2 dev-mode warnings) |
+| `solid/components-return-once` | still valid | rule 15 |
+| `solid/no-react-specific-props` | still valid | rule 5 + `solid2-kit check` |
+| `solid/no-react-deps` | still valid — never pass React-style dependency arrays | rule 8 + `solid2-kit check` react-hook check |
+| `solid/prefer-for` | still valid — `{list().map}` still renders | rule 7 + `solid2-kit check` |
+| `solid/prefer-show` | now a recommended default when narrowing | rule 17 + `solid2-kit check` |
+| `solid/no-innerhtml` | still valid | rule 16 |
+| `solid/style-prop` | still valid | rule 5 + `solid2-kit check` |
+| `solid/imports` | changed paths | banned-API table + `solid2-kit check` |
+| `solid/event-handlers` | still valid | rule 6 |
+| `solid/jsx-no-undef`, `jsx-no-duplicate-props` | covered by TypeScript | project typecheck |
+| `solid/prefer-classlist` | obsolete — `classList` removed | `solid2-kit check` bans `classList` |
+| `solid/no-unknown-namespaces` | obsolete — `on:`/`use:`/`attr:` removed in 2.0 | banned-API table + `solid2-kit check` |
+| `solid/no-proxy-apis` | obsolete — Solid 2 requires Proxy | not carried |
+
+## Banned Solid 1.x APIs (Solid 2 replacements)
+
+| Never write (Solid 1.x) | Write instead (Solid 2) |
+|---|---|
+| `import ... from "solid-js/store"` or `"solid-js/web"` | stores/`merge`/`omit` from `"solid-js"`; `render`/`hydrate`/`Portal`/`Dynamic` from `"@solidjs/web"` |
+| `createResource` | async `createMemo` + `<Loading>`/`<Errored>`; `refresh()`, `latest()`, `isPending()` |
+| `createEffect(fn)` (one arg), `on(...)` | `createEffect(compute, apply)`; deps belong in `compute` |
+| `onMount` | `onSettled` (return cleanup from its callback) |
+| `batch(...)` | delete it — writes auto-batch; `flush()` only to observe synchronously |
+| `<Suspense>`, `<ErrorBoundary>`, `<SuspenseList>` | `<Loading>`, `<Errored>` (fallback gets an error *accessor*), `<Reveal>` |
+| `<Index>` | `<For keyed={false}>` |
+| `<Ctx.Provider value={...}>` | `<Ctx value={...}>` |
+| `setState("a", "b", value)` path setters, `produce(...)` | draft setter: `setState(draft => { ... })` |
+| `mergeProps` / `splitProps` / `unwrap` | `merge` / `omit` / `snapshot` |
+| `classList={...}` | `class` object/array form |
+| `createMutable`, `modifyMutable` | `createStore` + draft setters |
+| `createComputed`, `createSelector`, `createDeferred` | `createMemo`, `createProjection`, external scheduling |
+| `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` |
+| `renderToStringAsync(...)` | `await renderToStream(() => <App />)` (one consumer: `pipe` / `pipeTo` / `readable`) |
+| `clearDelegatedEvents` | delete — delegated listeners are scoped to each render root |
+| `vite-plugin-solid` / `jsxImportSource: "solid-js"` | `@solidjs/vite-plugin` / `"jsxImportSource": "@solidjs/web"` |
+| JSX `<Route>` / `<A>` / `<HashRouter>` / `<Navigate>` | `createRouter({ routes })`, plain `<a href={Router.paths...}>`, `hashHistory()` |
+| `<MetaProvider>` | no provider — render `<Title>` / `<Meta>` / `<Link>` from `@solidjs/meta` anywhere |
+| `use:directive`, `on:`/`oncapture:`, `attr:`/`bool:`, `/*@once*/` | `ref` callbacks, camelCase event props, standard attributes, keep values reactive |
+| `resource.loading` / `resource.error` | `<Loading>` boundary / `<Errored>` boundary |
+
+When unsure about any API, verify against the official Solid 2.0 docs — fetchable URLs are
+listed in `references/official-docs.md` next to the `solid-2` skill. Do not guess from
+Solid 1.x or React memory.
+
+`createTrackedEffect` 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.