voidmachine 0.0.0 → 4.0.0

package/core-assets/packs/pack-react/skills/void-client-vs-server-component/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: void-client-vs-server-component
+description: Decide which components run on server vs client in a React 19 / Next.js app and place the 'use client' boundary correctly. Server Components by default; client is the exception.
+---
+
+# client-vs-server-component
+
+Use when creating any React 19 component in a project that supports Server Components (Next.js App Router, similar). The choice is **not** "type 'use client' if the component is interactive" — that's the lazy heuristic that leads to 80% of the app shipping to the browser.
+
+## The default
+
+**Server Component (no `'use client'`) by default.** Add `'use client'` only when you need browser-only APIs:
+
+- React state hooks: `useState`, `useReducer`, `useContext`, `useRef`
+- Effects: `useEffect`, `useLayoutEffect`
+- Browser APIs: `window`, `document`, `localStorage`, `IntersectionObserver`
+- Event handlers attached at component level (`onClick`, `onChange`, `onSubmit`)
+- Third-party libraries that use any of the above
+
+If your component does **none** of these — even if it ends up inside a Client Component — leave it server. RSC composition lets you pass server-rendered children into client wrappers.
+
+## The boundary placement rule
+
+Push `'use client'` **as far down the tree as possible**. Bad pattern:
+
+```tsx
+// ✗ app/dashboard/page.tsx
+'use client';                                  // entire page becomes client
+import { useState } from 'react';
+import { UserList } from './UserList';        // also becomes client, even if it didn't need to
+
+export default function Page() {
+  const [filter, setFilter] = useState('');
+  return (
+    <>
+      <input value={filter} onChange={(e) => setFilter(e.target.value)} />
+      <UserList filter={filter} />
+    </>
+  );
+}
+```
+
+Good pattern — isolate the interactive part:
+
+```tsx
+// ✓ app/dashboard/page.tsx (Server)
+import { UserList } from './UserList';         // stays server
+import { FilterInput } from './FilterInput';   // client island
+
+export default function Page() {
+  return (
+    <>
+      <FilterInput />
+      <UserList />
+    </>
+  );
+}
+```
+
+`FilterInput` owns the `useState`. It can either:
+- Push the filter to the URL and let `UserList` re-render server-side via search params
+- Or render `<UserList />` as a child it receives from the server and re-filter client-side from a snapshot
+
+The pattern: **client wraps server children**. Server Component as child of Client Component is allowed; the inverse is not.
+
+## State + data: who owns what
+
+| Concern | Lives on | Component type |
+|---|---|---|
+| URL params (`?filter=...`) | Server (read via `searchParams`) | Server Component |
+| Persistent server-side data | Server (DB / cache) | Server Component fetching directly |
+| Transient UI state (open/closed, focus, input value) | Client (`useState`) | Client Component |
+| Cross-component client state | Client (URL > Zustand > Context) | Client provider tree |
+| Optimistic updates | Client (capture-queue, see `void-offline-first-mutation`) | Client component |
+
+When in doubt, ask: "does this state need to survive a hard refresh?" If yes → server (or URL). If no → client.
+
+## Anti-patterns
+
+- ✗ **`'use client'` at the top of `app/layout.tsx`** — destroys server rendering for the whole subtree
+- ✗ **Wrapping all components in client just to use `<Link>`** — Next's `Link` works in Server Components
+- ✗ **`useEffect` to fetch data in a Client Component when a Server Component could fetch it on the server** — slow, waterfall, ugly loading states
+- ✗ **`import { db } from '@repo/db'` in a Client Component** — caught by `no-db-in-components` hook; refactor as a Server Action or Server Component fetch
+- ✗ **Marking a leaf component `'use client'` because its parent is** — children inherit client mode if the parent passes them through children prop into a client wrapper; explicit `'use client'` is only needed where state/effects live
+
+## Forms — special case
+
+Use **Server Actions** (`'use server'`) called from a Server Component form. The form HTML is server-rendered. JS hydration adds progressive enhancement:
+
+```tsx
+// app/contact/page.tsx (Server)
+import { sendContact } from './actions';
+
+export default function Page() {
+  return (
+    <form action={sendContact}>
+      <input name="email" type="email" required />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+Need controlled state for validation feedback? Wrap just the input in a client component. The form action stays server.
+
+## Performance signal: "JS payload"
+
+Open DevTools → Network tab → filter by JS. If your `app/dashboard` route ships > 100KB of JS, you have too much client. Audit which components are `'use client'`. 90% should not be.
+
+## Composition
+
+- `void-cache-component-pattern` — Server Components ARE the cache substrate; mark `'use cache'` for caching.
+- `void-state-architecture` — guides client-state placement once you've decided to use Client Components.
+- `void-form-pattern` — react-hook-form + Zod for client-controlled forms (Server Actions otherwise).
+- the `pack-react` doctrine module on components — components are pure UI either way (no DB, no fetch via service).
+- `void-hexagonal-architecture` — Server Components can call services directly (they're the boundary); Client Components call Server Actions.

package/core-assets/packs/pack-react/skills/void-client-vs-server-component/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-react/skills/void-form-pattern/.source

@@ -0,0 +1,7 @@
+Sources for `void-form-pattern` skill (see `docs/plans/skill-audits/void-form-pattern.md` for the full audit):
+
+- react-hook-form docs — canonical controlled-form pattern and skeleton.
+- @hookform/resolvers Zod adapter — schema-sharing resolver pattern.
+- Distilled by repeated form bugs on real projects — the "when NOT to use" and shared-schema discipline.
+
+Strategy: distill. Default stack (react-hook-form + Zod resolver + shared schema with Server Action) eliminates the recurring "where does validation live" question.

package/core-assets/packs/pack-react/skills/void-form-pattern/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: void-form-pattern
+description: "Build forms with react-hook-form + Zod resolver (void-machine default): validation, error UX, submit flow with Server Actions. Composes with server-action."
+---
+
+# form-pattern
+
+Use when building any form with > 1 field, any field with validation, or any submit that triggers a mutation. The default in void-machine is **react-hook-form** + **Zod resolver** for client-side controlled forms, paired with **Server Actions** on submit.
+
+For a single-field action (search input, toggle, "delete" button), use a Server Action directly — no library needed.
+
+## The default stack
+
+- `react-hook-form` — form state, registration, validation orchestration
+- `@hookform/resolvers/zod` — bridge to Zod
+- `zod` — schema (single source of truth: same schema validates client AND server)
+- Server Action (`void-server-action`) — the submit target
+
+## Canonical skeleton
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { saveContact } from '@/actions/contact';
+
+const FormSchema = z.object({
+  email: z.string().email('Format email invalide'),
+  message: z.string().min(10, 'Min 10 caractères').max(2000),
+});
+type FormValues = z.infer<typeof FormSchema>;
+
+export function ContactForm() {
+  const form = useForm<FormValues>({
+    resolver: zodResolver(FormSchema),
+    defaultValues: { email: '', message: '' },
+  });
+
+  async function onSubmit(values: FormValues) {
+    const result = await saveContact(values);
+    if (!result.ok) {
+      form.setError('root', { message: result.error });
+      return;
+    }
+    form.reset();
+  }
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} noValidate>
+      <label>
+        Email
+        <input {...form.register('email')} type="email" aria-invalid={!!form.formState.errors.email} />
+        {form.formState.errors.email && <span role="alert">{form.formState.errors.email.message}</span>}
+      </label>
+
+      <label>
+        Message
+        <textarea {...form.register('message')} aria-invalid={!!form.formState.errors.message} />
+        {form.formState.errors.message && <span role="alert">{form.formState.errors.message.message}</span>}
+      </label>
+
+      {form.formState.errors.root && <p role="alert">{form.formState.errors.root.message}</p>}
+
+      <button type="submit" disabled={form.formState.isSubmitting}>
+        {form.formState.isSubmitting ? 'Envoi…' : 'Envoyer'}
+      </button>
+    </form>
+  );
+}
+```
+
+Five things to notice:
+
+1. **One Zod schema** — same schema is imported by the Server Action for server-side validation. No drift.
+2. **`noValidate`** — disable browser default validation (which conflicts with custom error UX).
+3. **`role="alert"`** on errors — announces to screen readers immediately.
+4. **`aria-invalid`** — semantic state for AT.
+5. **`form.formState.isSubmitting`** disables the button — no double-submit, no manual `useState` for loading.
+
+## Schema sharing with the Server Action
+
+```ts
+// schemas/contact.ts (single source of truth)
+import { z } from 'zod';
+export const ContactSchema = z.object({
+  email: z.string().email(),
+  message: z.string().min(10).max(2000),
+});
+
+// app/(actions)/contact.ts
+'use server';
+import { ContactSchema } from '@/schemas/contact';
+
+export async function saveContact(input: unknown) {
+  const parsed = ContactSchema.safeParse(input);  // ← same schema
+  if (!parsed.success) return { ok: false, error: 'invalid-input' };
+  /* ... service call ... */
+  return { ok: true };
+}
+
+// components/ContactForm.tsx
+import { ContactSchema } from '@/schemas/contact';
+// resolver: zodResolver(ContactSchema)  ← same schema
+```
+
+Never duplicate the schema in the client and server. Always import from one location.
+
+## Error display patterns
+
+- **Field-level errors**: render right after the input (`{errors.field && <span role="alert">`).
+- **Form-level errors** (server rejection): use `form.setError('root', ...)` and render once at top or near submit button.
+- **No `alert()`**, no `toast.error()` for validation — inline is more usable and accessible.
+- **Focus the first invalid field on submit fail** — react-hook-form does this by default via `shouldFocusError: true`.
+
+## When NOT to use react-hook-form
+
+- **Single-field form** (search, newsletter signup):
+
+  ```tsx
+  <form action={subscribe}>
+    <input name="email" type="email" required />
+    <button>Subscribe</button>
+  </form>
+  ```
+
+  Native HTML + Server Action. No library. The browser's `required` + `type="email"` covers basic validation; the Server Action does the real check.
+
+- **File upload only** — use `<input type="file">` + Server Action; the form library adds no value.
+
+> **Repeatable fields in a native form**: when the Server Action reads `FormData` directly (the paths above — multi-select, a checkbox group, `<input multiple>`), do **not** `Object.fromEntries(formData)`: it keeps only the last value and silently drops the rest. Read repeatable fields with `formData.getAll(name)` and validate them with `z.array(...)` in the shared schema. See `void-server-action`.
+
+- **Wizard / multi-step** — react-hook-form's `Controller` works but consider XState or a similar state machine for complex flows.
+
+## Anti-patterns
+
+- ✗ **`useState` for each field** — that's what react-hook-form replaces; you lose validation, focus management, submit orchestration
+- ✗ **Validation in `onSubmit` only** — users want feedback on blur, not just on submit. Use `mode: 'onBlur'` or `'onTouched'`
+- ✗ **Different schemas client and server** — they drift; bugs slip through. One Zod schema.
+- ✗ **Disabling submit button via `disabled={!form.formState.isValid}`** — confusing UX. Let the user click; show errors after.
+- ✗ **`onSubmit={handler}` directly** — bypasses validation. Always `form.handleSubmit(handler)`.
+- ✗ **Calling `toast.error()` for field validation** — inline errors are the standard a11y pattern.
+
+## Touch + mobile
+
+- Use `inputMode="email"` / `inputMode="numeric"` / `inputMode="decimal"` to surface the right mobile keyboard.
+- `autoComplete="email"` / `"current-password"` / `"one-time-code"` for the right autofill behavior. Skip = bad UX.
+- Touch targets ≥ 44×44 (composes with `void-accessibility-check`).
+
+## Composition
+
+- `void-server-action` — the submit target; shares the Zod schema.
+- `void-security-guidance` — Zod schema is the trust boundary; server-side re-validates identically.
+- `void-state-architecture` — form state IS local state; lives in the form component, never lifted.
+- `void-accessibility-check` — labels, role="alert", focus management on error.
+- `void-tdd` — form components get `@testing-library/user-event` tests asserting validation + submit + error display.

package/core-assets/packs/pack-react/skills/void-form-pattern/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-react/skills/void-state-architecture/.source

@@ -0,0 +1,5 @@
+Sources for `void-state-architecture` skill (see `docs/plans/skill-audits/void-state-architecture.md` for the full audit):
+
+- No external source audited — native skill authored for void-machine.
+
+Strategy: native. Encodes a strict tier order (URL > server > local > lifted > Zustand > React Query) against React-specific state tooling that other UI stacks do not share.

package/core-assets/packs/pack-react/skills/void-state-architecture/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: void-state-architecture
+description: Decide where state lives — local, lifted, URL, server, client global. The decision tree to avoid useState-in-the-wrong-place sprawl. Default to URL or server before reaching for global stores.
+---
+
+# state-architecture
+
+Use when adding any state to a React app. The wrong location is the most common architectural drift: state ends up too high (every input re-renders the page), too low (sibling components can't communicate), or in a global store when URL would have sufficed.
+
+## The decision tree (top → bottom; use the highest that works)
+
+```
+1. Can it live in the URL?            → URL search params or path segment
+2. Can the server own it?              → DB / cache, render via Server Component
+3. Is it ONE component's concern?      → useState in that component
+4. Is it ≤ 3 sibling components?       → lift to closest common parent
+5. Is it cross-tree client-only?       → Zustand (or Jotai for atoms)
+6. Is it server data with caching?     → React Query (TanStack) / SWR
+```
+
+Default to (1) or (2). Reach for (5) last. Context is mentioned below but rarely the right answer.
+
+## (1) URL state — the most under-used
+
+State that should survive a refresh, be shareable, or be back-button-friendly belongs in the URL:
+
+- Filters, sorts, pagination, tabs
+- "Which item is selected" in a list/detail layout
+- Modal open/closed when the modal is shareable (`?invite=true`)
+- Search queries
+
+```tsx
+// Server Component reading searchParams
+export default function Page({ searchParams }: { searchParams: { sort?: string } }) {
+  const sort = searchParams.sort ?? 'newest';
+  return <ItemList sort={sort} />;
+}
+
+// Client Component pushing to URL
+'use client';
+import { useRouter, useSearchParams } from 'next/navigation';
+export function SortSelect() {
+  const router = useRouter();
+  const params = useSearchParams();
+  return <select onChange={(e) => router.push(`?${new URLSearchParams({ ...Object.fromEntries(params), sort: e.target.value })}`)}>...</select>;
+}
+```
+
+The benefit: refresh works, share link works, back button works, server can SSR with the right data. Three lines of effort, huge UX win.
+
+## (2) Server state — the second most under-used
+
+If the data is in the database (or any server cache), the source of truth is the server. Don't mirror it into `useState`:
+
+```tsx
+// ✗ Client component fetching + storing
+'use client';
+export function UserCard({ userId }) {
+  const [user, setUser] = useState<User | null>(null);
+  useEffect(() => { fetch(`/api/users/${userId}`).then(r => r.json()).then(setUser); }, [userId]);
+  if (!user) return <Spinner />;
+  return <Card>{user.name}</Card>;
+}
+
+// ✓ Server Component fetching directly
+export async function UserCard({ userId }: { userId: string }) {
+  const user = await userService.getById(userId);
+  return <Card>{user.name}</Card>;
+}
+```
+
+When server-fetch isn't feasible (interactive lists with optimistic updates), reach for React Query — but read (1) and (2) first.
+
+## (3) Local state — `useState` in one component
+
+For state ONE component cares about (input value, dropdown open, hover, focus):
+
+```tsx
+const [open, setOpen] = useState(false);
+```
+
+Fine. Don't lift it. Don't put it in context. Don't put it in Zustand.
+
+## (4) Lifted state — closest common parent
+
+When 2-3 siblings share state, lift to the closest common parent. NOT to the page root, NOT to a layout, NOT to context. The closest common parent.
+
+```tsx
+function TabContainer() {                       // closest common parent
+  const [active, setActive] = useState('overview');
+  return (
+    <>
+      <TabHeader active={active} onChange={setActive} />
+      <TabContent active={active} />
+    </>
+  );
+}
+```
+
+If lifting forces you to drill props through 4+ levels, you have a structural problem — not a state location problem. Refactor the component tree first.
+
+## (5) Client global state — Zustand / Jotai
+
+Use **only** when:
+
+- State is genuinely cross-tree (consumed by components that don't share a useful common parent — e.g., a toast queue, a command palette open state)
+- And it's client-side only (no server source of truth)
+- And lifting would cross > 5 component levels
+
+```ts
+// stores/toast.ts
+import { create } from 'zustand';
+export const useToast = create<{ items: Toast[]; push(t: Toast): void; dismiss(id: string): void }>(...);
+```
+
+If you can't justify ALL THREE conditions, don't add a store. Zustand is light but each store is a new mental load + a new place to debug.
+
+## When Context is right
+
+- Theme (rarely changes, deeply read)
+- Locale / i18n (same)
+- Auth user (Server Components read it from cookies; Client Components get a snapshot via `<UserProvider>`)
+
+Anything that **changes frequently** (form state, list selection, hover) in Context **kills perf**: every consumer re-renders on every change. That's not a Context problem, that's a wrong-tool problem.
+
+## Server state caching: React Query vs Server Components
+
+If you're on RSC + Server Actions, your "server state" is fetched server-side. React Query becomes useful only for:
+
+- Lists with optimistic updates that don't go through a Server Action (rare)
+- Real-time data with explicit refetch needs (e.g., dashboards polling every 5s)
+- Apps that aren't RSC (Vite SPA, Expo)
+
+In Next.js App Router with Server Actions, you can mostly skip React Query.
+
+## Anti-patterns
+
+- ✗ **Storing form values in a Zustand store** — local state in the form component is correct
+- ✗ **Storing server data in `useState`** — leads to stale data, refetch dance
+- ✗ **Putting `filterValue` in Context** — every consumer re-renders on every keystroke
+- ✗ **Using `useState` for what should be in the URL** — refresh loses state, share-link breaks
+- ✗ **Three different stores for the same feature** (`useUserStore`, `useUserPreferencesStore`, `useUserSessionStore`) — fuse or use selectors
+
+## Workflow
+
+For each state you're about to add:
+
+1. **Can it be URL?** If yes, use URL search params.
+2. **Can it be server?** If yes, fetch in a Server Component.
+3. **Does ONE component need it?** `useState` there.
+4. **Do ≤3 siblings need it?** Lift to common parent.
+5. **Genuinely cross-tree client-only?** Zustand store; one per concern.
+6. **Server data with caching needs?** React Query, but exhaust 1+2 first.
+
+## Composition
+
+- `void-client-vs-server-component` — server state lives in Server Components, client state lives in Client Components.
+- `void-form-pattern` — react-hook-form handles form state; this skill says it's local.
+- `void-offline-first-mutation` — capture-queue uses IndexedDB for offline writes (a 7th tier above Zustand, scoped to writes-pending-sync).
+- `void-cache-component-pattern` — server data caching strategy.

package/core-assets/packs/pack-react/skills/void-state-architecture/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-server/skills/void-background-job-pattern/.source

@@ -0,0 +1,6 @@
+Sources for `void-background-job-pattern` skill (see `docs/plans/skill-audits/void-background-job-pattern.md` for the full audit):
+
+- No external source audited — native distillation of the void-machine job taxonomy (event-driven vs cron vs one-shot) and per-type wrapper patterns.
+- Tooling referenced (not vendored): Inngest, Trigger.dev, Cloudflare Queues, Vercel Cron.
+
+Strategy: distill. Distilled from the harness's own job-type decision table; queue tooling is named but no source skill was copied.