@oneie/claude 0.6.0 → 0.7.0

package/skills/react19/SKILL.md

@@ -1,177 +1,198 @@
 ---
 name: react19
-description: React 19 patterns including Actions, use() hook, transitions, ref as prop, and optimistic updates for the Envelope System
+description: React 19 patterns as they are actually used in `one.ie/web` — Actions/useActionState, use(), useTransition, useOptimistic, ref-as-prop, document metadata — plus the repo's real async surfaces (props from the Astro page, SSE via useSurfaceRefresh, fetch-in-effect). Use when writing or reviewing a .tsx island in one.ie/web, choosing between a transition and an Action for a form, or deciding how a client component gets its data.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Glob, Grep
 ---
 
 # React 19 Development
 
-Modern React 19 patterns for building interactive components in the Envelope System.
+React 19 patterns for the interactive islands in `one.ie/web/src/components/`.
+
+Installed: **React 19.2.6** (declared `^19.1.0`), rendered by **Astro 6.3.7** on
+Cloudflare Workers. `template/site` is a separate tree on Astro 7 — use the
+`template:react19` skill there.
+
+For prop typing, file structure, `cn()` styling, `useState`/`useReducer` choice,
+and named-vs-default exports, read `.claude/rules/react.md`. It auto-loads on
+every `*.tsx` and is already in context when you edit — this skill does not
+repeat it.
 
 ## Works With
 
 | Skill        | Load when                                                                        |
 |--------------|----------------------------------------------------------------------------------|
-| `/signal`    | Any `onClick` — every click emits `ui:<surface>:<action>` via `emitClick()`. See `.claude/rules/ui.md`. |
-| `/astro`     | The component lives in an Astro page — hydration directives (`client:load`, `client:only`) decide worker bundle size. |
-| `/shadcn`    | Using Cards, Tabs, Badges, Dialog — shadcn components are React components with ref-as-prop. |
-| `/ai-ui`     | Agent reasoning UIs, tool-call visualization, generative components composed from shadcn. |
-| `/reactflow` | Graph visualizations — ColonyGraph, PheromoneGraph read substrate highways.       |
+| `/shadcn`    | Using Card, Tabs, Badge, Dialog — primitives under the 6-token system. |
+| `/astro`     | The component lives in an Astro page — hydration directives (`client:load`, `client:idle`, `client:only`) decide worker bundle size. |
+| `/puck`      | Block `render` fns are React components; the editor is a `client:only` island. |
+| `/reactflow` | Graph islands — WorkflowFlow, OrgChartView, LifecycleFlow, PathGraph. |
+| `/ai-ui`     | Agent reasoning UIs, tool-call visualization, generative components. |
+
+Every semantic `onClick` emits `emitClick('ui:<surface>:<action>')` from
+`@/lib/ui-signal`. That contract lives in `.claude/rules/ui.md`, which auto-loads
+on `one.ie/web/src/components/**/*.tsx`. There is no `/signal` skill.
 
-Auto-loads on `*.tsx`: `rules/react.md` + `rules/ui.md` (per `.claude/settings.json`).
+Rules auto-load via each rule file's own `paths:` frontmatter (not
+`settings.json`, which wires hooks only): `rules/react.md` on `**/*.tsx`,
+`rules/ui.md` on `one.ie/web/src/components/**/*.tsx`, `rules/design.md` on
+`one.ie/web/**/*.{tsx,astro,css}`.
 
 ## When to Use This Skill
 
-- Build React components in `src/components/`
+- Build a React island in `one.ie/web/src/components/`
 - Implement form handling with Actions
-- Use the new `use()` hook for promises/context
+- Use `use()` for promises/context
 - Apply transitions for non-blocking updates
-- Implement optimistic UI patterns
+- Decide how a client component gets its data (SSE, fetch-in-effect, or props)
 
 ## Key React 19 Features
 
+Adoption in `one.ie/web` is deliberate, not uniform. Before reaching for a
+feature, know where it already lives:
+
+| Feature | Files using it in `one.ie/web/src` |
+|---|---|
+| `useTransition` | 7 — the auth forms, `SubscribeForm`, `CampaignCardRenderer` |
+| `useActionState` | 1 — `components/peer/VideoRoomManager.tsx` |
+| `useDeferredValue` | 2 |
+| `useSyncExternalStore` | 2 |
+| `useReducer` | 1 |
+| `useOptimistic` | **0** — no in-repo precedent |
+| `forwardRef` | **0** — fully migrated to ref-as-prop |
+
 ### 1. Actions (Form Handling)
 
-Actions replace manual form handling. They work with `<form action={...}>`:
+`useActionState` returns `[state, dispatch, isPending]`. The real usage in
+`VideoRoomManager.tsx` posts through `ask()` from `@/lib/in/ask`:
 
 ```tsx
-// src/components/envelopes/EnvelopeSubmitter.tsx
 import { useActionState } from 'react';
+import { ask } from '@/lib/in/ask';
 
-interface EnvelopeFormState {
-  success: boolean;
+interface CreateRoomState {
+  ok: boolean;
   error?: string;
-  envelopeId?: string;
+  slug?: string;
 }
 
-async function submitEnvelope(
-  prevState: EnvelopeFormState,
+async function createRoom(
+  _prev: CreateRoomState | null,
   formData: FormData
-): Promise<EnvelopeFormState> {
-  const action = formData.get('action') as string;
-  const target = formData.get('target') as string;
-
+): Promise<CreateRoomState> {
+  const name = formData.get('name') as string;
+  const slug = formData.get('slug') as string;
   try {
-    // Process envelope
-    const envelope = createEnvelope({ action, target });
-    return { success: true, envelopeId: envelope.id };
+    await ask('room:create', { name, slug });
+    return { ok: true, slug };
   } catch (e) {
-    return { success: false, error: (e as Error).message };
+    return { ok: false, error: (e as Error).message };
   }
 }
 
-export function EnvelopeSubmitter() {
-  const [state, formAction, isPending] = useActionState(
-    submitEnvelope,
-    { success: false }
-  );
+export function CreateRoomForm() {
+  const [state, dispatch, isPending] = useActionState(createRoom, null);
 
   return (
-    <form action={formAction}>
-      <input name="action" placeholder="Action name" disabled={isPending} />
-      <input name="target" placeholder="Target agent" disabled={isPending} />
+    <form action={dispatch} className="space-y-3">
+      <input name="name" placeholder="Room name" disabled={isPending} />
+      <input name="slug" placeholder="room-slug" disabled={isPending} />
       <button type="submit" disabled={isPending}>
-        {isPending ? 'Sending...' : 'Send Envelope'}
+        {isPending ? 'Creating…' : 'Create room'}
       </button>
-      {state.error && <p className="text-red-500">{state.error}</p>}
-      {state.success && <p className="text-green-500">Sent: {state.envelopeId}</p>}
+      {state?.error && <p className="text-destructive text-sm">{state.error}</p>}
+      {state?.ok && <p className="text-success text-sm">Created {state.slug}</p>}
     </form>
   );
 }
 ```
 
+The initial state is `null` in the real call, so every read is `state?.field`.
+If you initialise with an object instead, type it and drop the optional chain —
+but be consistent within one component.
+
 ### 2. use() Hook
 
-Read promises and context directly with `use()`:
+`use()` reads a promise or a context. **No component in `one.ie/web` uses it
+today** — islands hydrate with props from the Astro page, or fetch in an effect.
+Introduce it only when you also introduce the `<Suspense>` boundary and a stable
+promise; a promise recreated each render suspends forever.
 
 ```tsx
-// Reading a promise
 import { use, Suspense } from 'react';
 
-interface RuntimeState {
-  agents: Agent[];
-  promises: AgentPromise[];
-}
+interface Stats { actors: number; signals: number }
 
-function RuntimeDisplay({ runtimePromise }: { runtimePromise: Promise<RuntimeState> }) {
-  const runtime = use(runtimePromise); // Suspends until resolved
+function StatsDisplay({ statsPromise }: { statsPromise: Promise<Stats> }) {
+  const stats = use(statsPromise); // suspends until resolved
 
   return (
     <div>
-      <h2>Agents: {runtime.agents.length}</h2>
-      <h2>Promises: {runtime.promises.length}</h2>
+      <h2>Actors: {stats.actors}</h2>
+      <h2>Signals: {stats.signals}</h2>
     </div>
   );
 }
 
-// Wrap with Suspense
-export function RuntimeContainer() {
-  const runtimePromise = fetchRuntimeState();
-
+// The promise must be created OUTSIDE the suspending component —
+// created in render, it is a new promise every attempt.
+export function StatsContainer({ statsPromise }: { statsPromise: Promise<Stats> }) {
   return (
-    <Suspense fallback={<div>Loading runtime...</div>}>
-      <RuntimeDisplay runtimePromise={runtimePromise} />
+    <Suspense fallback={<div>Loading…</div>}>
+      <StatsDisplay statsPromise={statsPromise} />
     </Suspense>
   );
 }
 ```
 
-```tsx
-// Reading context conditionally
-import { use, createContext } from 'react';
-
-const RuntimeContext = createContext<Runtime | null>(null);
+Reading context with `use()` is the safe half — it may be called conditionally,
+unlike `useContext`:
 
-function AgentCard({ agentId }: { agentId: string }) {
-  const runtime = use(RuntimeContext);
-  if (!runtime) return null;
+```tsx
+import { use } from 'react';
+import { EditorSlugContext } from '@/components/puck/editor-slug-context';
 
-  const agent = runtime.getAgent(agentId);
-  return <div>{agent.name}</div>;
+function BlockInspector({ enabled }: { enabled: boolean }) {
+  if (!enabled) return null;
+  const slug = use(EditorSlugContext); // legal after an early return
+  return <span>{slug}</span>;
 }
 ```
 
 ### 3. Transitions
 
-Non-blocking state updates with `useTransition`:
+The repo's most-used React 19 primitive. `SubscribeForm` and the auth pages wrap
+their submit in `startTransition` so the button stays responsive:
 
 ```tsx
 import { useState, useTransition } from 'react';
+import { emitClick } from '@/lib/ui-signal';
 
-interface Agent {
-  id: string;
-  name: string;
-  envelopes: Envelope[];
-}
+interface Actor { id: string; name: string }
 
-export function AgentTabs({ agents }: { agents: Agent[] }) {
-  const [selectedAgent, setSelectedAgent] = useState(agents[0]?.id);
+export function ActorTabs({ actors }: { actors: Actor[] }) {
+  const [selected, setSelected] = useState(actors[0]?.id);
   const [isPending, startTransition] = useTransition();
 
-  const handleTabChange = (agentId: string) => {
-    startTransition(() => {
-      setSelectedAgent(agentId);
-    });
-  };
-
-  const agent = agents.find(a => a.id === selectedAgent);
+  const actor = actors.find(a => a.id === selected);
 
   return (
     <div>
-      <div className="tabs">
-        {agents.map(a => (
+      <div className="flex gap-2">
+        {actors.map(a => (
           <button
             key={a.id}
-            onClick={() => handleTabChange(a.id)}
-            className={a.id === selectedAgent ? 'active' : ''}
+            onClick={() => {
+              emitClick('ui:actors:select', { id: a.id });
+              startTransition(() => setSelected(a.id));
+            }}
+            className={a.id === selected ? 'bg-primary text-on-primary' : ''}
           >
             {a.name}
           </button>
         ))}
       </div>
       <div className={isPending ? 'opacity-50' : ''}>
-        {agent && <AgentContent agent={agent} />}
+        {actor && <ActorContent actor={actor} />}
       </div>
     </div>
   );
@@ -180,45 +201,40 @@ export function AgentTabs({ agents }: { agents: Agent[] }) {
 
 ### 4. Optimistic Updates
 
-Show expected state before server confirms:
+`useOptimistic` has **no precedent in this repo** — treat an introduction as a
+new pattern and keep it inside one component. It only reverts correctly when the
+update runs inside an Action or a transition; calling it from a bare event
+handler throws.
 
 ```tsx
 import { useOptimistic } from 'react';
+import { ask } from '@/lib/in/ask';
 
-interface Envelope {
-  id: string;
-  status: 'pending' | 'resolved' | 'rejected';
-}
+interface Task { id: string; title: string; status: string }
 
-export function EnvelopeList({ envelopes: initialEnvelopes }: { envelopes: Envelope[] }) {
-  const [optimisticEnvelopes, addOptimisticEnvelope] = useOptimistic(
-    initialEnvelopes,
-    (state, newEnvelope: Envelope) => [...state, newEnvelope]
+export function TaskList({ tasks }: { tasks: Task[] }) {
+  const [optimisticTasks, addOptimisticTask] = useOptimistic(
+    tasks,
+    (state: Task[], next: Task) => [...state, next]
   );
 
-  async function sendEnvelope(formData: FormData) {
-    const tempEnvelope: Envelope = {
-      id: `temp-${Date.now()}`,
-      status: 'pending',
-    };
-
-    // Show optimistically
-    addOptimisticEnvelope(tempEnvelope);
-
-    // Actually send
-    await submitEnvelope(formData);
+  // Must be a form action (or wrapped in startTransition) — not a plain onClick.
+  async function createTask(formData: FormData) {
+    const title = formData.get('title') as string;
+    addOptimisticTask({ id: `temp-${Date.now()}`, title, status: 'pending' });
+    await ask('tasks:create', { title });
   }
 
   return (
     <div>
-      <form action={sendEnvelope}>
-        <input name="action" />
-        <button type="submit">Send</button>
+      <form action={createTask}>
+        <input name="title" />
+        <button type="submit">Add</button>
       </form>
       <ul>
-        {optimisticEnvelopes.map(env => (
-          <li key={env.id} className={env.id.startsWith('temp-') ? 'opacity-50' : ''}>
-            {env.id}: {env.status}
+        {optimisticTasks.map(t => (
+          <li key={t.id} className={t.id.startsWith('temp-') ? 'opacity-50' : ''}>
+            {t.title}: {t.status}
           </li>
         ))}
       </ul>
@@ -227,17 +243,15 @@ export function EnvelopeList({ envelopes: initialEnvelopes }: { envelopes: Envel
 }
 ```
 
+The optimistic entry disappears on its own when the Action settles and the real
+`tasks` prop updates — do not remove it by hand.
+
 ### 5. ref as Prop
 
-No more `forwardRef` needed in React 19:
+`forwardRef` is fully retired here — zero occurrences in
+`one.ie/web/src/components/`. Declare `ref` as an ordinary prop:
 
 ```tsx
-// Before (React 18)
-const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => (
-  <input ref={ref} {...props} />
-));
-
-// After (React 19)
 interface InputProps {
   ref?: React.Ref<HTMLInputElement>;
   placeholder?: string;
@@ -247,24 +261,27 @@ function Input({ ref, ...props }: InputProps) {
   return <input ref={ref} {...props} />;
 }
 
-// Usage
 function Form() {
   const inputRef = useRef<HTMLInputElement>(null);
-  return <Input ref={inputRef} placeholder="Enter action" />;
+  return <Input ref={inputRef} placeholder="Receiver" />;
 }
 ```
 
 ### 6. Document Metadata
 
-Render `<title>` and `<meta>` anywhere:
+React 19 hoists `<title>` and `<meta>` from anywhere in the tree. In this repo
+that is almost always the wrong layer — the Astro page owns the head, and an
+island rendered `client:only` will not produce metadata for the SSR response or
+for a crawler. Use it only for a genuinely client-routed sub-view.
 
 ```tsx
-function AgentPage({ agent }: { agent: Agent }) {
+interface Room { id: string; name: string }
+
+function RoomView({ room }: { room: Room }) {
   return (
     <div>
-      <title>{agent.name} | Envelope System</title>
-      <meta name="description" content={`Agent ${agent.name} details`} />
-      <h1>{agent.name}</h1>
+      <title>{room.name}</title>
+      <h1>{room.name}</h1>
     </div>
   );
 }
@@ -272,129 +289,74 @@ function AgentPage({ agent }: { agent: Agent }) {
 
 ## Project-Specific Patterns
 
-### Runtime Context Provider
+### How an island gets its data
 
-```tsx
-// src/components/providers/RuntimeProvider.tsx
-import { createContext, useState, useCallback, ReactNode } from 'react';
-import { Runtime } from '@/engine/Runtime';
-
-interface RuntimeContextValue {
-  runtime: Runtime;
-  refresh: () => void;
-  uiSchema: object;
-}
-
-export const RuntimeContext = createContext<RuntimeContextValue | null>(null);
+Three real paths, in order of preference:
 
-export function RuntimeProvider({ children }: { children: ReactNode }) {
-  const [runtime] = useState(() => new Runtime());
-  const [uiSchema, setUiSchema] = useState(() => runtime.toUISchema());
+**1. Props from the Astro page (default).** The page runs SSR, queries, and
+passes plain data across the island boundary. No client fetch, no loading state.
 
-  const refresh = useCallback(() => {
-    setUiSchema(runtime.toUISchema());
-  }, [runtime]);
-
-  return (
-    <RuntimeContext.Provider value={{ runtime, refresh, uiSchema }}>
-      {children}
-    </RuntimeContext.Provider>
-  );
-}
+```astro
+---
+export const prerender = false;
+import { OrgChartView } from '@/components/org/OrgChartView';
+---
+<OrgChartView chart="marketing" client:only="react" />
 ```
 
-### Envelope Form with Actions
+**2. Live refresh over SSE — `useSurfaceRefresh`.** A resolver mutation from
+anywhere (UI, chat, MCP, CLI) broadcasts one frame; every mounted surface on that
+dimension re-pulls. This is the repo's answer to "keep the view fresh", and it
+replaces polling:
 
 ```tsx
-// src/components/envelopes/CreateEnvelopeForm.tsx
-import { useActionState } from 'react';
-import { use } from 'react';
-import { RuntimeContext } from '@/components/providers/RuntimeProvider';
-import { createEnvelope } from '@/engine/Envelope';
+import { useState, useCallback } from 'react';
+import { useSurfaceRefresh } from '@/lib/use-surface-refresh';
 
-export function CreateEnvelopeForm() {
-  const { runtime, refresh } = use(RuntimeContext)!;
+interface Workflow { id: string; name: string }
 
-  async function handleSubmit(prevState: any, formData: FormData) {
-    const envelope = createEnvelope({
-      action: formData.get('action') as string,
-      inputs: JSON.parse(formData.get('inputs') as string || '{}'),
-      sender: 'user',
-      receiver: formData.get('receiver') as string,
-    });
+export function WorkflowList({ slug }: { slug: string }) {
+  const [rows, setRows] = useState<Workflow[]>([]);
 
-    await runtime.send(envelope);
-    refresh();
+  const reload = useCallback(() => {
+    fetch(`/api/workflows?slug=${slug}`)
+      .then(r => r.json() as Promise<{ data?: Workflow[] }>)
+      .then(d => setRows(d.data ?? []))
+      .catch(() => {});
+  }, [slug]);
 
-    return { success: true, envelopeId: envelope.id };
-  }
-
-  const [state, formAction, isPending] = useActionState(handleSubmit, {});
+  useSurfaceRefresh(slug, 'workflows', reload);
 
-  return (
-    <form action={formAction} className="space-y-4">
-      <input name="action" placeholder="Action" className="input" />
-      <input name="receiver" placeholder="Target Agent" className="input" />
-      <textarea name="inputs" placeholder='{"key": "value"}' className="textarea" />
-      <button type="submit" disabled={isPending} className="btn">
-        {isPending ? 'Sending...' : 'Send Envelope'}
-      </button>
-    </form>
-  );
+  return <ul>{rows.map(w => <li key={w.id}>{w.name}</li>)}</ul>;
 }
 ```
 
-### Promise Tracker with Transitions
+`useSurfaceRefresh(slug, dimension, onRefresh)` subscribes to the `inbox:{slug}`
+topic on `/api/analytics/watch` and fires only for `surface:refresh` frames
+matching `dimension`. It handles reconnect backoff and debounce itself.
 
-```tsx
-// src/components/promises/PromiseTracker.tsx
-import { useState, useTransition } from 'react';
-import { AgentPromise } from '@/engine/types';
+**3. Fetch in an effect.** Still the common shape for one-shot loads
+(`VideoRoomManager` does this). Acceptable; just keep the `.catch(() => {})` so a
+failed load never leaves an unhandled rejection in a Worker.
 
-interface Props {
-  promises: AgentPromise[];
-}
+### @oneie/react — for consumers, not for this app
 
-export function PromiseTracker({ promises }: Props) {
-  const [filter, setFilter] = useState<'all' | 'pending' | 'resolved'>('all');
-  const [isPending, startTransition] = useTransition();
+`packages/react/` publishes `@oneie/react`: `SubstrateProvider` + `useSubstrate`,
+**10 data hooks** (`useAgent`, `useAgentList`, `useDiscover`, `useHealth`,
+`useHighways`, `useRecall`, `useRevenue`, `useStats`, `useWallet`, `useFn`), two
+optimistic helpers (`useOptimisticMark`, `useOptimisticPay`), and two stream
+helpers (`streamChat`, `streamTail`).
 
-  const filtered = promises.filter(p =>
-    filter === 'all' || p.status === filter
-  );
-
-  return (
-    <div>
-      <div className="flex gap-2 mb-4">
-        {(['all', 'pending', 'resolved'] as const).map(f => (
-          <button
-            key={f}
-            onClick={() => startTransition(() => setFilter(f))}
-            className={filter === f ? 'btn-active' : 'btn'}
-          >
-            {f}
-          </button>
-        ))}
-      </div>
-      <ul className={isPending ? 'opacity-50' : ''}>
-        {filtered.map(promise => (
-          <li key={promise.id} className="flex items-center gap-2">
-            <span className={`status-dot status-${promise.status}`} />
-            <span>{promise.label}</span>
-          </li>
-        ))}
-      </ul>
-    </div>
-  );
-}
-```
+**`one.ie/web` does not depend on `@oneie/react`.** Its only `@oneie` dependency
+is `@oneie/sdk` (`file:../../packages/sdk`). Do not import these hooks into a web
+component — the package is for external apps embedding the substrate. Inside
+this app, use the three data paths above.
 
 ## TypeScript Patterns
 
 ### Event Handlers
 
 ```tsx
-// Type-safe event handlers
 function handleClick(e: React.MouseEvent<HTMLButtonElement>) {
   e.preventDefault();
 }
@@ -408,84 +370,22 @@ function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
 }
 ```
 
-### Component Props
-
-```tsx
-// Prefer interfaces for props
-interface AgentCardProps {
-  agent: Agent;
-  onSelect?: (id: string) => void;
-  className?: string;
-  children?: React.ReactNode;
-}
-
-// Use PropsWithChildren for components with children
-import { PropsWithChildren } from 'react';
-
-interface PanelProps {
-  title: string;
-}
-
-function Panel({ title, children }: PropsWithChildren<PanelProps>) {
-  return (
-    <div>
-      <h2>{title}</h2>
-      {children}
-    </div>
-  );
-}
-```
-
-## State Management Patterns
-
-### Local state for UI
-
-```tsx
-const [isOpen, setIsOpen] = useState(false);
-const [selectedTab, setSelectedTab] = useState('agent-a');
-```
-
-### useReducer for complex state
-
-```tsx
-type Action =
-  | { type: 'SELECT_AGENT'; agentId: string }
-  | { type: 'ADD_ENVELOPE'; envelope: Envelope }
-  | { type: 'UPDATE_PROMISE'; promiseId: string; status: string };
-
-interface State {
-  selectedAgent: string;
-  envelopes: Envelope[];
-  promises: AgentPromise[];
-}
-
-function reducer(state: State, action: Action): State {
-  switch (action.type) {
-    case 'SELECT_AGENT':
-      return { ...state, selectedAgent: action.agentId };
-    case 'ADD_ENVELOPE':
-      return { ...state, envelopes: [...state.envelopes, action.envelope] };
-    case 'UPDATE_PROMISE':
-      return {
-        ...state,
-        promises: state.promises.map(p =>
-          p.id === action.promiseId ? { ...p, status: action.status } : p
-        ),
-      };
-  }
-}
-```
+With an Action you do not write `handleSubmit` at all — `<form action={dispatch}>`
+receives `FormData` directly and never needs `preventDefault`.
 
 ## Best Practices
 
-1. **Use Actions for forms**: Cleaner than manual `onSubmit`
-2. **Wrap async with Suspense**: When using `use()` with promises
-3. **Use transitions for tabs/filters**: Keeps UI responsive
-4. **Optimistic updates for UX**: Show expected state immediately
-5. **Type everything**: No `any` types
-6. **Prefer `interface` over `type`**: For props and objects
+1. **Props before fetch**: let the Astro page do the query; hydrate with data.
+2. **`useSurfaceRefresh` before polling**: one SSE topic already carries every
+   resolver mutation.
+3. **Actions for forms**: `<form action={dispatch}>` beats a manual `onSubmit`.
+4. **Transitions for tabs and filters**: the repo's most-used React 19 primitive.
+5. **`use()` needs a stable promise**: created in render, it never resolves.
+6. **`useOptimistic` only inside an Action or transition**: it throws otherwise.
+7. **Never import `@oneie/react` into `one.ie/web`**: it is not a dependency.
+8. **Emit the click signal first**: `emitClick(...)` then the local handler.
 
 ---
 
-**Version**: 1.0.0
-**Tech**: React 19.1
+**Tech**: React 19.2.6 · Astro 6.3.7 · Tailwind 4
+**Tree**: `one.ie/web` — for `template/site` (Astro 7) use `template:react19`