solid

Solid 2 in OpenClaw

The Control UI and plugin views (extensions/x, extensions/workboard) render with Solid 2 (solid-js, @solidjs/web, @solidjs/signals, compiled by @solidjs/vite-plugin/@solidjs/compiler). Lit and Web Awesome are removed from these surfaces; new code is Solid only. The Canvas hosts also use Solid.

Read ui/AGENTS.md first; its state-ownership rules apply to Solid unchanged. Use the exact installed Solid pins from the owning package.json: the runtime and compiler are 2.0.0-rc.18, and @solidjs/vite-plugin is 3.0.0-next.51. @solidjs/testing-library remains 1.0.0-beta.3. solid-js and @solidjs/* are exempt from the repository's seven-day release-age gate (Peter, 2026-10-11). Peter also approved exact-version exceptions for seroval@1.7.0 and seroval-plugins@1.7.0 on 2026-10-24: rc.18 requires them for SSR/hydration serialization. Other third-party Solid ecosystem packages remain subject to the gate.

Rules that keep the UI correct

Before your first edit, read the installed ui/node_modules/solid-js/CHEATSHEET.md, especially its "What changed from 1.x" list. It is the rc.18 API contract, written as a guard against React and Solid 1 priors, the two dominant bug sources. For new code or a Solid audit, then read idioms and lessons; to refactor or review existing code, also use the refactor checklist. Check solid-js/types/client/flow.d.ts and the installed @solidjs/signals / @solidjs/web types when choosing an API. rc.18 has no createAsync: asynchronous values are ordinary computations returning promises or async iterables. createDeferred explicitly permits stale answers during refetch; use it only when that lag is the intended presentation contract.

For async reads, mutations, keyed projections, lazy components, or coordinated loading, read the async and action recipes. Cron is the worked reference: plain owners admit requests and writes; Solid presents their readiness and optimistic transitions.

For lists, derivations, copies, or anything on a hot path, read performance.

1. Domain owners stay plain TypeScript. The Gateway store, capabilities, lib/sessions/*, caches, persistence, and mutation authority keep synchronous mutate-then-read semantics. Solid 2 writes become visible only after a microtask flush, so authoritative state never lives in a signal. → state and ownership
2. Components consume projections from ui/src/lib/reactive/ (one per owner and scope, never a second store) and useApplication() for the application context. Add a thin adapter only with its first production caller; subscribe to ordered events directly.
3. Host tags and classes survive. A component renders its existing openclaw-* tag as a plain host element in light DOM; CSS and E2E select it. Never rename a tag or a class. → components
4. One implementation per registered tag. Solid-rendered native hosts share their renderer through defineSolidBridge in ui/src/lib/solid-bridge.ts; use its returned component in JSX. Specialized native hosts such as Tooltip keep their existing wrapper and lifecycle owner. → components
5. One renderer per DOM region, and one lifecycle owner per overlay surface. → overlays
6. Derive, don't synchronize. createMemo before createSignal; no copies of owner state; no defensive guards for states the owner already excludes. Prefer smaller code with fewer owners.
7. Keep rendering controller lifecycles out. Production Control UI rendering controllers and host-update contracts have been removed and are guarded. The controller-to-Solid recipe explains the boundary for new integrations: plain domain owners retain authority; Solid owns presentation and lifecycle.

Component skeleton

An illustrative component (the tag is an example): it renders its host tag, reads an owner through a projection, and derives instead of copying state.

import { createMemo, Show } from "solid-js";
import { useApplication } from "../lib/reactive/context.ts";
import { projectAgents } from "../lib/reactive/domain-capabilities.ts";

export function AgentCount(props: { compact?: boolean }) {
  const app = useApplication();
  // Reads through to the synchronous owner; disposed with this component's owner.
  const agents = projectAgents(app.agents);
  // Never destructure props: reads must stay reactive.
  const count = createMemo(() => agents.read().agentsList?.agents.length ?? 0);
  return (
    <openclaw-agent-count class={["agent-count", { "agent-count--compact": props.compact }]}>
      <Show when={count() > 0} fallback={<span class="muted">—</span>}>
        <span>{count()}</span>
      </Show>
    </openclaw-agent-count>
  );
}

Use jsxImportSource: "@solidjs/web" and its JSX types, not Solid 1's solid-js/web.

Traps that compile but break

• on:x, oncapture:, attr:x, bool:x, classList, and use: are compile errors on native elements in rc.18. Spreads can still hide them from the compiler; keep the lint guard. prop: and XML namespaces remain supported.
• Events are camelCase (onClick). Dashed custom events need the exact dash, such as onSession-change, or a listen(...) ref factory.
• Native event bindings bind once: dispatch through a stable callback that reads the current handler prop. Runtime spreads, including dynamic elements, can update handlers.
• A read right after a write sees the old value until flush(). Don't write-then-read in handlers; derive.
• Reactive reads after the first await in an async memo are untracked, and async memos get no AbortSignal.
• Ref callbacks run unowned: onCleanup inside them does nothing.
• ARIA enumerations are typed strings: aria-pressed={pressed() ? "true" : "false"}, never a boolean.
• Solid 1 APIs (createResource, onMount, mergeProps, Context.Provider) don't carry over: use async computations, onSettled, merge, and the context component itself.
• Writing a signal or store from a memo, an effect compute phase, or a component body throws in dev. untrack doesn't exempt it (the guard checks the owner); derive instead, or write from a handler, onSettled, or effect apply.
• Class strings built with template literals or .filter(Boolean).join(" ") lose composable reactivity: use class={["base", { active: active() }]}.
• createRenderEffect is for render-phase runtime bindings, and flush() in production code usually hides a write-then-read: feature code uses createEffect and derivations.

Enforced wave-zero guard

pnpm check:control-ui-controllers runs in lint and the changed-file checks. For production ui/src and the bundled Workboard, Memory Core, Nostr, WhatsApp, ClawRouter, and X view directories, it rejects createRenderEffect outside lib/reactive/, all direct addEventListener calls in TSX, DOM queries outside the explicit foreign-DOM owner list, and option-free memos whose callback only returns a literal. Property/equality, async, and option-bearing memos retain their contracts. Tests and test helpers are excluded. The native AST scan counts generic and optional calls; flush, getOwner, and runWithOwner resolve actual Solid imports, including aliases and namespaces, without counting owner methods or shadowed locals.

createEffect, untrack, addEventListener, querySelector(All), flush, getOwner, and runWithOwner also have per-file shrink-only baselines in config/control-ui-*-baseline.txt and config/plugin-ui-*-baseline.txt. New calls cannot borrow another file's allowance, including allowances in another plugin or the host. Deleting calls requires pnpm check:control-ui-controllers --prune; moving an allowance requires a verified Git rename. Never raise a baseline to admit new debt. See the refactor checklist for replacements and the permitted survivors.

The guard also bans JSX classList and hand-written createComponent outside the explicit context-adapter allowlist. Component/view onCleanup and manual stored/chained import loaders have shrink-only baselines; computation cleanup and reactive primitives remain allowed. Saving flags require recipe review: trace the co-written createOptimistic(false) rather than infer busy state from isPending or a nearby optimistic declaration.

More, each with its root cause: lessons learned.

Testing

mountSolid, waitForSolid/flush, renderSolidRef, and the Solid application-context provider live in ui/src/test-helpers/. .test.tsx files are discovered. Keep assertions when you replace a harness. Visual changes need inspected, sanitized before/after screenshots. Follow the assigned campaign's compute budget. → testing

References

Topic	Read when
idioms	choosing a primitive, derivations, props, lifecycle, stores, keys, async, context, diagnostics
async and actions	Gateway-owned reads, optimistic mutations, keyed projections, lazy code, sibling loading
refactor checklist	refactoring or reviewing existing Solid: measurable smells, replacements, before/after
components	writing components, native custom-element hosts, JSX bindings, events, refs, styles
state and ownership	touching owners, projections, async reads, lifetimes, parking, chat render lifecycle
overlays	menus, popovers, tooltips, dialogs, focus, positioning, the platform floor
testing	unit, browser, E2E, WebKit, parity, retention suites
performance	startup bundle, lazy loading, render budgets
plugins	building a plugin's Control UI view in Solid
lessons learned	before a new kind of change; most entries cost a failed CI run to learn