@bastani/atomic 0.5.11 → 0.5.12-1

package/.agents/skills/typescript-react-reviewer/references/checklist.md

@@ -0,0 +1,267 @@
+# Code Review Checklist
+
+## Critical Issues (Block Merge)
+
+### React Hooks
+
+- [ ] No `useEffect` that only computes derived state
+- [ ] No missing cleanup functions (subscriptions, timers, fetch)
+- [ ] No conditional hook calls (`if (x) { useState() }`)
+- [ ] Dependency arrays are complete and correct
+- [ ] No `eslint-disable react-hooks/exhaustive-deps` without strong justification
+
+### State Management
+
+- [ ] No direct state mutations (`.push()`, `.splice()`, `arr[i] = x`)
+- [ ] No copying server data to local state (TanStack Query data → useState)
+- [ ] State is colocated near where it's used
+
+### React 19 Specific
+
+- [ ] `useFormStatus` called in child component, not same component as `<form>`
+- [ ] Promises passed to `use()` are not created inline in render
+- [ ] Server Actions have `'use server'` directive
+- [ ] `'use client'` boundary is as low as possible in component tree
+
+### Keys
+
+- [ ] No `index` as key in lists that can reorder, filter, or add/remove items
+- [ ] Keys are stable and unique within siblings
+
+### TypeScript
+
+- [ ] No `any` type without explicit justification comment
+- [ ] Array access handles possible `undefined` (or `noUncheckedIndexedAccess` enabled)
+- [ ] Props interfaces use discriminated unions for mutually exclusive props
+
+---
+
+## High Priority Issues
+
+### Component Structure
+
+- [ ] No component defined inside another component (causes remount)
+- [ ] Components under 300 lines (split if larger)
+- [ ] Single responsibility - one reason to change
+
+### Props and State
+
+- [ ] Controlled inputs initialized with empty string, not `undefined`
+- [ ] Props typed explicitly (not using `React.FC` with generics)
+- [ ] No prop drilling beyond 2-3 levels
+
+### Performance
+
+- [ ] `useMemo`/`useCallback` justified by measurement or `React.memo` child
+- [ ] No inline object/function in JSX passed to memoized children
+- [ ] Large lists use virtualization (react-window, react-virtual)
+
+### Error Handling
+
+- [ ] Error boundaries at appropriate granularity
+- [ ] Async operations have error handling
+- [ ] Form validation shows clear error messages
+
+---
+
+## Architecture Checks
+
+### Custom Hooks
+
+- [ ] Hook names start with `use` followed by capital letter
+- [ ] Hooks are reusable or significantly improve readability
+- [ ] Non-hook logic extracted to utility functions instead
+
+### State Management Strategy
+
+- [ ] Server state uses TanStack Query (or similar)
+- [ ] Client state uses appropriate solution:
+  - Local: `useState`/`useReducer`
+  - Global simple: Zustand
+  - Global derived: Jotai
+- [ ] Form state uses React 19 `useActionState` where appropriate
+
+### File Organization
+
+- [ ] Feature-based folder structure for larger apps
+- [ ] No barrel files (`index.ts`) in application code
+- [ ] Shared components in `components/`
+- [ ] Feature-specific code in `features/<name>/`
+
+---
+
+## TypeScript Quality
+
+### Type Safety
+
+- [ ] Strict mode enabled (`"strict": true`)
+- [ ] `noUncheckedIndexedAccess: true` for array safety
+- [ ] Generic components preserve type inference
+- [ ] Event handlers properly typed (`React.MouseEvent<HTMLButtonElement>`)
+
+### Type Patterns
+
+- [ ] Discriminated unions for variant props
+- [ ] `as const` for literal types where appropriate
+- [ ] Explicit return types on exported functions
+- [ ] No type assertions (`as`) without comment explaining why
+
+### Context Typing
+
+- [ ] Context created with `null` default has custom hook with null check
+- [ ] Provider value is memoized if object
+
+```typescript
+// ✅ Correct context pattern
+const MyContext = createContext<ContextType | null>(null);
+
+function useMyContext() {
+  const ctx = useContext(MyContext);
+  if (!ctx) throw new Error('useMyContext must be within MyProvider');
+  return ctx;
+}
+
+function MyProvider({ children }: { children: ReactNode }) {
+  const value = useMemo(() => ({ /* ... */ }), [deps]);
+  return <MyContext value={value}>{children}</MyContext>;
+}
+```
+
+---
+
+## Performance Checks
+
+### Re-render Prevention
+
+- [ ] `React.memo` used for expensive pure components
+- [ ] Callbacks passed to memoized children are stable (`useCallback`)
+- [ ] Object props to memoized children are stable (`useMemo`)
+- [ ] Zustand selectors select minimal state
+
+### Bundle Size
+
+- [ ] Route-level code splitting with `React.lazy`
+- [ ] Heavy libraries imported dynamically where possible
+- [ ] No unused dependencies
+- [ ] Tree-shaking friendly imports (no `import * as`)
+
+### Lists and Tables
+
+- [ ] Virtualization for 100+ items
+- [ ] Stable keys for all list items
+- [ ] Filtered/sorted lists memoized if expensive
+
+---
+
+## Accessibility (a11y)
+
+### Semantic HTML
+
+- [ ] Interactive elements are `<button>`, `<a>`, `<input>`, etc. (not `<div onClick>`)
+- [ ] Headings follow hierarchy (`h1` → `h2` → `h3`)
+- [ ] Lists use `<ul>`/`<ol>`/`<li>`
+
+### Forms
+
+- [ ] All inputs have associated `<label>` (via `htmlFor` or wrapping)
+- [ ] Required fields indicated visually and via `aria-required`
+- [ ] Error messages associated via `aria-describedby`
+
+### Keyboard Navigation
+
+- [ ] All interactive elements focusable
+- [ ] Visible focus indicators (don't remove `outline`)
+- [ ] `tabIndex` used appropriately (0 or -1, rarely positive)
+
+### Screen Readers
+
+- [ ] Images have meaningful `alt` text (or `alt=""` if decorative)
+- [ ] Icons have `aria-label` or `aria-hidden="true"`
+- [ ] Dynamic content updates announced (`aria-live`)
+
+### Links
+
+- [ ] External links have `rel="noopener noreferrer"` with `target="_blank"`
+- [ ] Link text is descriptive (not "click here")
+
+---
+
+## Testing Standards
+
+### Query Priority
+
+Use queries in this order (Testing Library best practice):
+
+1. `getByRole` - accessible to everyone
+2. `getByLabelText` - form fields
+3. `getByPlaceholderText` - if no label
+4. `getByText` - non-interactive elements
+5. `getByTestId` - last resort
+
+### Test Quality
+
+- [ ] Tests verify behavior, not implementation
+- [ ] `userEvent` used instead of `fireEvent`
+- [ ] Async operations use `waitFor` or `findBy`
+- [ ] Error states covered
+- [ ] Edge cases covered (empty state, loading, error)
+
+### Test Structure
+
+- [ ] Arrange-Act-Assert pattern
+- [ ] One assertion focus per test (can have multiple asserts)
+- [ ] Test descriptions explain expected behavior
+- [ ] No test interdependencies
+
+---
+
+## Quick Reference: Common Issues by Symptom
+
+| Symptom | Likely Cause | Check |
+|---------|--------------|-------|
+| Infinite re-renders | Object in dependency array | New object created each render? |
+| Stale state in callback | Missing dependency | Closure over old value? |
+| State doesn't update | Direct mutation | Using `.push()` or direct assignment? |
+| Controlled input warning | `undefined` initial value | Initialize with empty string |
+| Hook error | Conditional hook call | Hook inside `if`/loop? |
+| Memory leak warning | Missing cleanup | Subscription/timer without cleanup? |
+| Type error on array access | Missing undefined check | Enable `noUncheckedIndexedAccess` |
+| Child re-renders unnecessarily | Unstable props | Inline object/function to memo child? |
+| Form status always false | Wrong component | `useFormStatus` in form component? |
+
+---
+
+## Review Comment Templates
+
+### Critical Issue
+
+```
+🚫 **Critical:** [Issue description]
+
+This will cause [bug/leak/crash] because [reason].
+
+**Current:**
+```code```
+
+**Should be:**
+```code```
+```
+
+### Suggestion
+
+```
+💡 **Suggestion:** [Improvement description]
+
+This would improve [maintainability/performance/readability] by [reason].
+
+**Consider:**
+```code```
+```
+
+### Question
+
+```
+❓ **Question:** [Clarification needed]
+
+Is this intentional? [Context for why you're asking]
+```

package/.agents/skills/typescript-react-reviewer/references/react19-patterns.md

@@ -0,0 +1,305 @@
+# React 19 Patterns Reference
+
+## useActionState (Forms)
+
+Replaces manual `isLoading`, `error`, `data` state management for form actions.
+
+```typescript
+import { useActionState } from 'react';
+
+interface FormState {
+  error: string | null;
+  success: boolean;
+}
+
+async function createPost(prevState: FormState, formData: FormData): Promise<FormState> {
+  const title = formData.get('title') as string;
+  if (!title) return { error: 'Title required', success: false };
+  
+  await fetch('/api/posts', { method: 'POST', body: JSON.stringify({ title }) });
+  return { error: null, success: true };
+}
+
+function NewPostForm() {
+  const [state, formAction, isPending] = useActionState(createPost, {
+    error: null,
+    success: false,
+  });
+
+  return (
+    <form action={formAction}>
+      <input name="title" />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Submitting...' : 'Submit'}
+      </button>
+      {state.error && <p className="error">{state.error}</p>}
+    </form>
+  );
+}
+```
+
+**Review Points:**
+- Action function must return consistent object shape
+- Actions should be pure (return new state, not mutate)
+- Check that error handling covers all failure cases
+
+## useFormStatus (Submit Button State)
+
+**Critical Rule:** Must be called in a child component of `<form>`, NOT in the same component.
+
+```typescript
+import { useFormStatus } from 'react-dom';
+
+// ✅ CORRECT: Child component
+function SubmitButton({ children }: { children: React.ReactNode }) {
+  const { pending, data, method, action } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? 'Submitting...' : children}
+    </button>
+  );
+}
+
+function MyForm() {
+  return (
+    <form action={submitAction}>
+      <input name="email" />
+      <SubmitButton>Send</SubmitButton>
+    </form>
+  );
+}
+
+// ❌ WRONG: Same component as form - pending is always false!
+function BadForm() {
+  const { pending } = useFormStatus(); // BUG: Always false
+  return (
+    <form action={submitAction}>
+      <button disabled={pending}>Submit</button>
+    </form>
+  );
+}
+```
+
+## useOptimistic (Instant UI Updates)
+
+Provides instant feedback before server confirms. Automatically reverts on error.
+
+```typescript
+import { useOptimistic, startTransition } from 'react';
+
+interface Message {
+  id: string;
+  text: string;
+  sending?: boolean;
+}
+
+function MessageThread({ messages }: { messages: Message[] }) {
+  const [optimisticMessages, addOptimisticMessage] = useOptimistic(
+    messages,
+    (currentMessages, newText: string) => [
+      { id: crypto.randomUUID(), text: newText, sending: true },
+      ...currentMessages,
+    ]
+  );
+
+  async function sendMessage(formData: FormData) {
+    const text = formData.get('message') as string;
+    addOptimisticMessage(text);
+    
+    startTransition(async () => {
+      await deliverMessage(text);
+    });
+  }
+
+  return (
+    <div>
+      {optimisticMessages.map(msg => (
+        <div key={msg.id} style={{ opacity: msg.sending ? 0.5 : 1 }}>
+          {msg.text}
+        </div>
+      ))}
+      <form action={sendMessage}>
+        <input name="message" />
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+**Review Points:**
+- Optimistic state should be visually distinct (opacity, spinner)
+- Consider what happens on error (automatic revert)
+- Wrap async operations in `startTransition`
+
+## use() API (Promise and Context Reading)
+
+Unlike hooks, `use()` can be called conditionally. Major departure from traditional React rules.
+
+### Reading Promises
+
+```typescript
+import { use, Suspense } from 'react';
+
+// ✅ CORRECT: Promise passed from parent
+function Comments({ commentsPromise }: { commentsPromise: Promise<Comment[]> }) {
+  const comments = use(commentsPromise); // Suspends until resolved
+  return <ul>{comments.map(c => <li key={c.id}>{c.text}</li>)}</ul>;
+}
+
+function Page() {
+  const commentsPromise = fetchComments(); // Created once
+  return (
+    <Suspense fallback={<Spinner />}>
+      <Comments commentsPromise={commentsPromise} />
+    </Suspense>
+  );
+}
+
+// ❌ WRONG: Promise created in render - INFINITE LOOP
+function BadComponent() {
+  const data = use(fetch('/api').then(r => r.json())); // New promise every render!
+}
+```
+
+### Conditional Context Reading
+
+```typescript
+import { use, createContext } from 'react';
+
+const ThemeContext = createContext<string>('light');
+
+// ✅ use() can be called conditionally (useContext cannot!)
+function HorizontalRule({ show }: { show: boolean }) {
+  if (show) {
+    const theme = use(ThemeContext);
+    return <hr className={`hr-${theme}`} />;
+  }
+  return null;
+}
+```
+
+**Review Points:**
+- Always wrap `use(promise)` in `<Suspense>`
+- Promise must come from props, state, or outside component
+- Never create promise inline in render
+
+## Server vs Client Components
+
+| Server Components | Client Components |
+|-------------------|-------------------|
+| No directive needed | Must start with `'use client'` |
+| Can access DB, filesystem | Can use useState, useEffect |
+| Zero client JS | Ships JS to browser |
+| Cannot use hooks | Full interactivity |
+
+### Boundary Placement
+
+Push `'use client'` as low as possible in the tree.
+
+```typescript
+// ✅ GOOD: Only interactive part is Client Component
+// ProductPage.tsx (Server Component - no directive)
+async function ProductPage({ id }: { id: string }) {
+  const product = await db.query(`SELECT * FROM products WHERE id = $1`, [id]);
+  
+  return (
+    <article>
+      <h1>{product.name}</h1>           {/* Server: no JS */}
+      <p>{product.description}</p>       {/* Server: no JS */}
+      <AddToCartButton productId={id} /> {/* Client: needs onClick */}
+    </article>
+  );
+}
+
+// AddToCartButton.tsx
+'use client';
+function AddToCartButton({ productId }: { productId: string }) {
+  const [adding, setAdding] = useState(false);
+  // Client-side interactivity
+}
+
+// ❌ BAD: Entire page is client-side unnecessarily
+'use client';
+function ProductPage({ id }) {
+  // Everything ships to client even though most is static
+}
+```
+
+### Serialization Constraint
+
+Props passed from Server to Client Components must be serializable.
+
+**Cannot pass:**
+- Functions (except Server Actions)
+- Classes
+- Symbols
+- DOM nodes
+
+```typescript
+// ❌ WRONG: Function prop from Server to Client
+async function ServerParent() {
+  const handleClick = () => console.log('clicked'); // Not serializable!
+  return <ClientChild onClick={handleClick} />;
+}
+
+// ✅ CORRECT: Use Server Action
+async function ServerParent() {
+  async function handleSubmit(formData: FormData) {
+    'use server';
+    // Server-side logic
+  }
+  return <ClientChild onSubmit={handleSubmit} />;
+}
+```
+
+## ref as Prop (React 19)
+
+No more `forwardRef` needed - ref can be passed as a regular prop.
+
+```typescript
+// React 18: Required forwardRef
+const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => (
+  <input ref={ref} {...props} />
+));
+
+// React 19: ref is just a prop
+function Input({ ref, ...props }: InputProps & { ref?: React.Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />;
+}
+```
+
+## Context as Provider
+
+`<Context>` can be used directly as provider (no `.Provider` needed).
+
+```typescript
+// React 18
+<ThemeContext.Provider value={theme}>
+  {children}
+</ThemeContext.Provider>
+
+// React 19
+<ThemeContext value={theme}>
+  {children}
+</ThemeContext>
+```
+
+## Document Metadata in Components
+
+Title and meta tags can be rendered anywhere in the tree.
+
+```typescript
+function BlogPost({ post }: { post: Post }) {
+  return (
+    <article>
+      <title>{post.title}</title>
+      <meta name="description" content={post.excerpt} />
+      <h1>{post.title}</h1>
+      <p>{post.content}</p>
+    </article>
+  );
+}
+```
+
+React 19 automatically hoists these to `<head>`.

package/.agents/skills/typeset/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: typeset
+description: Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography.
+version: 2.1.1
+user-invocable: true
+argument-hint: "[target]"
+---
+
+Assess and improve typography that feels generic, inconsistent, or poorly structured — turning default-looking text into intentional, well-crafted type.
+
+## MANDATORY PREPARATION
+
+Invoke /impeccable — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first.
+
+---
+
+## Assess Current Typography
+
+Analyze what's weak or generic about the current type:
+
+1. **Font choices**:
+   - Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
+   - Does the font match the brand personality? (A playful brand shouldn't use a corporate typeface)
+   - Are there too many font families? (More than 2-3 is almost always a mess)
+
+2. **Hierarchy**:
+   - Can you tell headings from body from captions at a glance?
+   - Are font sizes too close together? (14px, 15px, 16px = muddy hierarchy)
+   - Are weight contrasts strong enough? (Medium vs Regular is barely visible)
+
+3. **Sizing & scale**:
+   - Is there a consistent type scale, or are sizes arbitrary?
+   - Does body text meet minimum readability? (16px+)
+   - Is the sizing strategy appropriate for the context? (Fixed `rem` scales for app UIs; fluid `clamp()` for marketing/content page headings)
+
+4. **Readability**:
+   - Are line lengths comfortable? (45-75 characters ideal)
+   - Is line-height appropriate for the font and context?
+   - Is there enough contrast between text and background?
+
+5. **Consistency**:
+   - Are the same elements styled the same way throughout?
+   - Are font weights used consistently? (Not bold in one section, semibold in another for the same role)
+   - Is letter-spacing intentional or default everywhere?
+
+**CRITICAL**: The goal isn't to make text "fancier" — it's to make it clearer, more readable, and more intentional. Good typography is invisible; bad typography is distracting.
+
+## Plan Typography Improvements
+
+Consult the [typography reference](reference/typography.md) from the impeccable skill for detailed guidance on scales, pairing, and loading strategies.
+
+Create a systematic plan:
+
+- **Font selection**: Do fonts need replacing? What fits the brand/context?
+- **Type scale**: Establish a modular scale (e.g., 1.25 ratio) with clear hierarchy
+- **Weight strategy**: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings — or whatever fits)
+- **Spacing**: Line-heights, letter-spacing, and margins between typographic elements
+
+## Improve Typography Systematically
+
+### Font Selection
+
+If fonts need replacing:
+- Choose fonts that reflect the brand personality
+- Pair with genuine contrast (serif + sans, geometric + humanist) — or use a single family in multiple weights
+- Ensure web font loading doesn't cause layout shift (`font-display: swap`, metric-matched fallbacks)
+
+### Establish Hierarchy
+
+Build a clear type scale:
+- **5 sizes cover most needs**: caption, secondary, body, subheading, heading
+- **Use a consistent ratio** between levels (1.25, 1.333, or 1.5)
+- **Combine dimensions**: Size + weight + color + space for strong hierarchy — don't rely on size alone
+- **App UIs**: Use a fixed `rem`-based type scale, optionally adjusted at 1-2 breakpoints. Fluid sizing undermines the spatial predictability that dense, container-based layouts need
+- **Marketing / content pages**: Use fluid sizing via `clamp(min, preferred, max)` for headings and display text. Keep body text fixed
+
+### Fix Readability
+
+- Set `max-width` on text containers using `ch` units (`max-width: 65ch`)
+- Adjust line-height per context: tighter for headings (1.1-1.2), looser for body (1.5-1.7)
+- Increase line-height slightly for light-on-dark text
+- Ensure body text is at least 16px / 1rem
+
+### Refine Details
+
+- Use `tabular-nums` for data tables and numbers that should align
+- Apply proper `letter-spacing`: slightly open for small caps and uppercase, default or tight for large display text
+- Use semantic token names (`--text-body`, `--text-heading`), not value names (`--font-16`)
+- Set `font-kerning: normal` and consider OpenType features where appropriate
+
+### Weight Consistency
+
+- Define clear roles for each weight and stick to them
+- Don't use more than 3-4 weights (Regular, Medium, Semibold, Bold is plenty)
+- Load only the weights you actually use (each weight adds to page load)
+
+**NEVER**:
+- Use more than 2-3 font families
+- Pick sizes arbitrarily — commit to a scale
+- Set body text below 16px
+- Use decorative/display fonts for body text
+- Disable browser zoom (`user-scalable=no`)
+- Use `px` for font sizes — use `rem` to respect user settings
+- Default to Inter/Roboto/Open Sans when personality matters
+- Pair fonts that are similar but not identical (two geometric sans-serifs)
+
+## Verify Typography Improvements
+
+- **Hierarchy**: Can you identify heading vs body vs caption instantly?
+- **Readability**: Is body text comfortable to read in long passages?
+- **Consistency**: Are same-role elements styled identically throughout?
+- **Personality**: Does the typography reflect the brand?
+- **Performance**: Are web fonts loading efficiently without layout shift?
+- **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
+
+Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.