@coralai/sps-cli 0.42.0 → 0.43.0

package/skills/frontend/references/performance.md

@@ -0,0 +1,219 @@
+# Performance
+
+Rendering cost, bundle size, code-splitting, images, fonts.
+
+## Measure first
+
+No optimization without a number. Three cheap measures:
+
+- **Lighthouse / PageSpeed Insights** — first-load & Core Web Vitals.
+- **Browser DevTools Performance tab** — where time goes during interaction.
+- **Framework-specific profiler** — React DevTools Profiler, Vue DevTools, Svelte's built-in.
+
+Target Core Web Vitals (real-user, 75th percentile):
+- **LCP** (Largest Contentful Paint) < 2.5 s
+- **INP** (Interaction to Next Paint) < 200 ms
+- **CLS** (Cumulative Layout Shift) < 0.1
+
+If one is green, stop. Optimizing green metrics is churn.
+
+## Initial load
+
+### Bundle size
+
+Use the bundler's analyzer (`rollup-plugin-visualizer`, `webpack-bundle-analyzer`, Next's built-in). Look for:
+
+- **Duplicate libraries** — two copies of React / lodash usually mean a version mismatch.
+- **Locales / polyfills** — `moment` ships every locale by default; `date-fns-tz` / `luxon` are leaner.
+- **Barrel re-exports** defeating tree-shaking — named imports work only if the dependency's `package.json` says `"sideEffects": false`.
+
+### Code splitting
+
+Load only what the current route needs.
+
+```
+const Settings = lazy(() => import('./features/settings/Settings'));
+
+<Suspense fallback={<Skeleton />}>
+  <Settings />
+</Suspense>
+```
+
+Route-level splitting is free with modern routers. Component-level splitting is worth it for:
+- Heavy third-party libs (rich text editor, chart lib, map lib) loaded only when the feature opens.
+- Large modals / drawers.
+
+### Preloading
+
+Tell the browser what's coming:
+
+```
+<link rel="preload" as="font" href="/fonts/inter.woff2" crossorigin>
+<link rel="preconnect" href="https://api.example.com">
+<link rel="dns-prefetch" href="https://cdn.example.com">
+```
+
+Or via framework API (`next/link` prefetch, `<Link>` prefetch). Pair with hover / viewport prefetching (see `routing.md`).
+
+## Render cost
+
+### Keep updates local
+
+One component updating should not re-render the whole tree. Signals (Solid, Vue refs, Svelte reactivity) are fine-grained by default. React re-renders by reference — containment is on you:
+
+- Split components so state lives near where it changes.
+- Memoize the boundary with `React.memo`.
+- Stable callback / object references (`useCallback`, `useMemo`).
+
+Don't spray memoization everywhere. Measure; memoize where it matters.
+
+### Expensive children
+
+```
+function List({ items }) {
+  return items.map(i => <Row key={i.id} item={i} />);
+}
+```
+
+If `Row` is expensive and `List` gets a new `items` array reference (but same data), every row re-renders. Either:
+- Use the cache lib to return stable references from queries.
+- Memoize `Row` with equality on `item.id` + `item.version`.
+
+### Lists — virtualize if big
+
+Rendering 10 000 DOM nodes is slow at any framework. Use `react-window`, `@tanstack/virtual`, or `IntersectionObserver`-based lazy rendering.
+
+Rule of thumb: virtualize any list that might show more than a couple hundred items.
+
+### Avoid layout thrashing
+
+Writing to the DOM (style, class) then reading (offsetHeight, getBoundingClientRect) in the same frame forces re-layout. Batch reads, then writes.
+
+```
+# ❌
+for (const el of items) {
+  el.style.height = 'auto';
+  const h = el.offsetHeight;         // forces layout
+  el.dataset.h = h;
+}
+
+# ✅
+const heights = items.map(el => el.offsetHeight);   // read
+items.forEach((el, i) => el.dataset.h = heights[i]); // write
+```
+
+Use `IntersectionObserver`, `ResizeObserver` instead of `getBoundingClientRect` in scroll / resize handlers.
+
+## Images
+
+Biggest easy win. Order of effect:
+
+1. **Right size.** Don't serve a 2000 × 2000 JPEG into a 400 × 400 avatar slot.
+2. **Right format.** AVIF > WebP > JPEG for photos; PNG / SVG for flat.
+3. **Responsive `srcset` / `<picture>`** so mobile doesn't fetch desktop-size images.
+4. **Lazy-load below-the-fold** with `loading="lazy"` or `IntersectionObserver`.
+5. **Modern image component** (`next/image`, `nuxt/image`) auto-serves the right size/format with `priority` hints for the LCP image.
+
+```
+<img src="hero-400.avif"
+     srcset="hero-400.avif 1x, hero-800.avif 2x"
+     sizes="(max-width: 600px) 400px, 800px"
+     loading="lazy"
+     width="400" height="300"
+     alt="...">
+```
+
+Always set `width` and `height` (or aspect-ratio). Reserves layout space; kills CLS.
+
+## Fonts
+
+Web fonts are costly — big, render-blocking without hints.
+
+```
+<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+```css
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/inter.woff2') format('woff2');
+  font-display: swap;       /* show fallback text while loading; swap in when ready */
+}
+```
+
+- **Subset** to characters you use (`glyphhanger`, `pyftsubset`).
+- **`font-display: swap`** avoids invisible text during load (FOIT).
+- **System font stacks** are free and fast if your brand allows.
+
+## JavaScript execution
+
+Third-party scripts (analytics, chat widgets, A/B tools) are the leading cause of poor INP.
+
+- Load non-critical scripts with `async` / `defer`.
+- Consider `requestIdleCallback` for non-urgent work.
+- Audit what's on the critical path; "one more tag" slows every user.
+
+## Caching
+
+Set `Cache-Control` headers generously on static assets. Combine with content-hashed filenames (`main.f3a7c.js`) so long TTLs don't prevent deploys.
+
+```
+Cache-Control: public, max-age=31536000, immutable       # hashed assets
+Cache-Control: no-cache                                   # HTML
+```
+
+Service workers (PWA) add offline caching; use a tested recipe (Workbox) rather than hand-rolling.
+
+## Reducing main-thread work
+
+Identify long tasks in DevTools (purple blocks). Common offenders:
+
+- JSON parsing large payloads — use streaming (NDJSON), smaller pages.
+- Expensive computations during render — move to a Web Worker.
+- Hydration in SSR apps — use selective / streaming hydration (React Server Components, Qwik's resumability, Astro Islands).
+
+## Web Workers — for CPU-bound work
+
+For image processing, parsing, crypto, heavy transforms.
+
+```
+const worker = new Worker(new URL('./heavy.worker.js', import.meta.url), { type: 'module' });
+worker.postMessage({ data });
+worker.onmessage = (e) => setResult(e.data);
+```
+
+Libraries: `comlink` makes postMessage feel like async function calls. `workerize-loader` auto-splits.
+
+## Avoid Layout Shift (CLS)
+
+- Reserve space for images (`width` / `height` or `aspect-ratio`).
+- Avoid late-loaded content above existing content (banners, cookies) — overlay or reserve.
+- Use CSS `font-size-adjust` and fallback metrics to minimize FOUT jumps.
+
+## Performance budgets
+
+Set numbers in CI:
+
+```
+# lighthouse-ci or equivalent
+"assertions": {
+  "categories:performance": ["error", {"minScore": 0.9}],
+  "largest-contentful-paint": ["warn", {"maxNumericValue": 2500}]
+}
+```
+
+Budget violations block merge. Without numbers, perf erodes silently.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Importing a huge lib for one function | Tree-shake (`lodash-es`), or copy the function |
+| Sending 5 MB JS to render 50 KB of content | Code-split; audit bundles |
+| No lazy-loading for below-the-fold images | `loading="lazy"` / image component |
+| Missing width/height on `<img>` | Causes CLS |
+| `@import` in CSS | Blocks; bundle with build tool |
+| 20 third-party scripts on the critical path | Load deferred; remove what doesn't earn its weight |
+| Shipping unminified dev builds | Build step + server compression |
+| SSR hydrating the entire page on mount | Selective / islands / RSC |
+| Animation with `top`/`left` / `width`/`height` (triggers layout) | Use `transform` / `opacity` |

package/skills/frontend/references/routing.md

@@ -0,0 +1,209 @@
+# Routing
+
+Client-side routing, deep linking, guards, transitions.
+
+## Route = URL + data + component
+
+Every route declaration answers three questions:
+1. What URL pattern matches?
+2. What data does it need?
+3. What renders?
+
+```
+{
+  path: '/orders/:id',
+  loader: ({ params }) => fetchOrder(params.id),
+  element: <OrderDetail />,
+}
+```
+
+Modern routers (React Router 6+, TanStack Router, Nuxt, SvelteKit, Remix) embed data loading. Prefer route-level loaders over fetching in components — it parallelizes data with rendering and enables streaming / Suspense.
+
+## Nested routes
+
+A nested route inherits layout from its parent.
+
+```
+/app
+  /app/profile          <Settings tabs /> + ProfilePanel
+  /app/billing          <Settings tabs /> + BillingPanel
+```
+
+Parent route stays mounted; only the outlet changes. Cheap tab switches, persistent side nav, zero re-fetch for shared data.
+
+## Dynamic segments
+
+```
+/users/:userId/orders/:orderId
+```
+
+Treat params as strings; parse and validate at the boundary. Never trust the URL — a bad one shouldn't crash your app.
+
+## Query params
+
+For sort, filter, pagination, selected tab. Don't shoehorn into path params.
+
+```
+/users?role=admin&sort=-createdAt&page=2
+```
+
+Client routers give you typed access (`useSearchParams` / similar). Always treat query params as optional; have sensible defaults.
+
+## Route guards
+
+Auth, role, feature flag checks happen at the route boundary, not in the component.
+
+```
+{
+  path: '/admin',
+  loader: async () => {
+    const user = await requireAuth();
+    if (!user.roles.includes('admin')) throw redirect('/');
+    return null;
+  },
+  element: <AdminShell />,
+}
+```
+
+Return a redirect or throw; don't render and then unmount. Unauthorized users should never see the page flash.
+
+## Navigation
+
+Imperative vs. declarative:
+
+```
+// Declarative — preferred for actions triggered by markup
+<Link to={`/orders/${id}`}>View</Link>
+
+// Imperative — for after-effect navigation (post-submit, post-auth)
+await submit();
+navigate('/orders');
+```
+
+`<Link>` / `<NuxtLink>` / `<a>` with client-side handling gets you:
+- Prefetching on hover / visible.
+- Correct ctrl/cmd/middle-click behaviour.
+- Accessibility (focus ring, screen-reader announcement).
+
+Avoid `onClick={() => navigate(...)}` on a `<div>` — it breaks all of that.
+
+## Prefetching
+
+The right-click / hover preload is the cheapest perf optimization available.
+
+- **Hover**: preload route data on mouse over (~100ms before click).
+- **Viewport**: preload links that appear on screen.
+- **Intent**: preload the next step in a known flow (after login → dashboard).
+
+Most modern routers support all three declaratively. Enable them.
+
+## Transitions
+
+Two patterns:
+
+### Block-until-ready
+
+Show the old page until the new route's data is loaded. Good for same-shell navigations.
+
+```
+{navigation.state === 'loading' && <TopProgressBar />}
+<Outlet />
+```
+
+### Render-and-stream
+
+Render the new layout immediately with `<Suspense>` boundaries for not-yet-loaded data. Better for deep nested data.
+
+Pick per-route. Don't universalize one policy.
+
+## 404s and fallbacks
+
+Route declarations should include:
+- An explicit 404 route at the end.
+- An error boundary per route level.
+
+```
+{ path: '*', element: <NotFound /> }
+```
+
+Otherwise a mistyped URL renders a blank screen.
+
+## Redirects
+
+Put redirects at the router level, not in an effect.
+
+```
+# ❌ effect-based
+useEffect(() => { if (!user) navigate('/login'); }, [user]);
+// flash of protected content before effect runs
+
+# ✅ route-level
+loader: async () => {
+  const user = await getUser();
+  if (!user) throw redirect('/login');
+  return user;
+}
+```
+
+## Route parameters vs. path
+
+- Path: `/orders/:id` — `id` is essential to identify the resource.
+- Query: `/orders?filter=...&sort=...` — UI controls, non-essential to URL identity.
+
+Rule: if two people share the URL, path params are "what am I looking at", query params are "how do I want to see it".
+
+## Scroll restoration
+
+On back/forward, restore the previous scroll. On forward navigation, scroll to top (or anchor).
+
+Most routers offer `<ScrollRestoration />` / built-in behaviour. Use it. Manual scroll logic becomes buggy fast.
+
+## Loading / pending UI per route
+
+Each route knows what "loading" looks like — a skeleton, a progress bar, or nothing (for fast enough loads).
+
+```
+{
+  path: '/dashboard',
+  loader: fetchDashboard,
+  element: <Dashboard />,
+  pendingElement: <DashboardSkeleton />,   // or via Suspense boundary
+}
+```
+
+Don't use a global spinner that blocks the whole app on every navigation. It makes the UI feel slow.
+
+## Deep linking
+
+Every URL should be shareable / bookmarkable / refreshable:
+
+- Modals that represent significant state → put in URL (`/inbox/message/42`).
+- Selected tab → query param.
+- Filter pills → query param.
+- Ephemeral UI (tooltip open, hover state) → not in URL.
+
+If users screenshot and paste your URL, the page should load exactly what they saw.
+
+## SSR / SSG / hybrid
+
+For SEO-sensitive or fast-first-paint pages, server-render the initial route:
+
+- **SSR** (Next.js, Nuxt, SvelteKit, Remix) — render per-request on the server.
+- **SSG** (static generation) — render at build time.
+- **ISR** (on-demand revalidation) — SSG + background refresh.
+- **CSR** (traditional SPA) — render entirely in the browser.
+
+Choice is architectural; covered more in the framework docs. From a routing perspective: route-level data loaders work identically across all four, which is the whole point of these routers.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `useEffect(() => fetch(...), [params])` in a component | Route loader |
+| Mutating URL via `window.history.pushState` | Use the router API |
+| Non-semantic "links" (`onClick` on `<div>`) | Use `<Link>` / `<a>` |
+| Redirect via `useEffect` + `navigate` for unauthenticated pages | Route guard / loader redirect |
+| Passing current route info via Context | Read from router — `useLocation` / `useRoute` |
+| Nesting routes too deeply for the layout to match | Flatten; layouts and routes are separate axes |
+| Skipping `<NotFound />` | Always have a 404 route |
+| Treating the query string as throwaway | It's user state; design it |

package/skills/frontend/references/state.md

@@ -0,0 +1,190 @@
+# State
+
+Local, shared, server, derived. The taxonomy matters more than the library.
+
+## Taxonomy
+
+| Kind | Lives | Examples | Tool |
+|---|---|---|---|
+| **Local** | In one component | Input text, dropdown-open boolean | `useState` / `ref` / component state |
+| **Shared** | Across siblings or deep tree | Theme, current user, feature flag | Context / provider / store |
+| **Server** | Comes from an API | User list, order details, prices | Server-cache lib (TanStack Query, SWR, Apollo) |
+| **URL** | In the address bar | Current page, filters, selected item | Router query / path params |
+| **Derived** | Computed from other state | `totalCents = sum(items.map(i => i.cents))` | Memo / computed |
+
+Knowing which bucket each piece belongs in saves 80% of state-management pain.
+
+## Server state is special
+
+Server state is not your state — it's a cache of someone else's state. Treat it that way.
+
+```
+// ❌ putting server data into a global store
+dispatch({ type: 'users/loaded', users });
+
+// ✅ using a server-cache library
+const { data: users, isLoading } = useQuery(['users'], fetchUsers);
+```
+
+Server-cache libraries give you:
+- Per-key caching + reuse across components.
+- Stale-while-revalidate, auto-refetch on window focus / network.
+- Optimistic updates with rollback.
+- Request deduplication.
+
+Don't reinvent these. They're not a minor convenience — they handle edge cases that take weeks to replicate.
+
+## Derive, don't store
+
+```
+// ❌ stored
+const [items, setItems] = useState([]);
+const [total, setTotal] = useState(0);
+// now every setItems must also update total — easy to forget
+
+// ✅ derived
+const [items, setItems] = useState([]);
+const total = useMemo(() => items.reduce((s, i) => s + i.cents, 0), [items]);
+```
+
+Two pieces of state that must stay in sync = one piece of state.
+
+## Single source of truth
+
+When two components both "know" the same data, either:
+- Lift the state to their common parent, OR
+- Put it in a shared store.
+
+Never duplicate.
+
+## Local first, global last
+
+Reach for global state only when you genuinely have cross-cutting concerns (auth user, theme, i18n). Otherwise, state that starts local can be lifted when needed. The opposite move (pull-back from global to local) is painful.
+
+## Forms
+
+Forms are half server state, half local. Libraries:
+
+| Lib | Feel |
+|---|---|
+| React Hook Form | Uncontrolled-first, minimal re-renders |
+| Formik | Controlled, rich ecosystem |
+| TanStack Form | Typed, framework-agnostic, modern |
+| Native `<form>` + validation | Underrated for simple cases |
+
+For schema validation, reach for `zod` / `valibot` / `yup` and share the schema with the backend if possible.
+
+Rules:
+- Validate on submit (mandatory) + on blur (optional) + on change (for high-visibility fields like email uniqueness).
+- Disable submit while submitting; prevent double-submit.
+- Clear form fields only when the user expects it (e.g., after successful create; not after error).
+
+## Optimistic UI
+
+Show the expected result immediately. Reconcile on server response.
+
+```
+async function like(postId) {
+  // Optimistic
+  setPosts(posts => posts.map(p => p.id === postId ? { ...p, liked: true, likes: p.likes + 1 } : p));
+
+  try {
+    const updated = await api.like(postId);
+    setPosts(posts => posts.map(p => p.id === postId ? updated : p));
+  } catch (e) {
+    // Rollback
+    setPosts(posts => posts.map(p => p.id === postId ? { ...p, liked: false, likes: p.likes - 1 } : p));
+    toast.error('Failed to like');
+  }
+}
+```
+
+Server-cache libraries make this pattern a one-liner. Use it for any user-initiated action where latency > ~50ms.
+
+## Undo / stack
+
+For multi-step flows or sensitive actions, keep a history:
+
+```
+const [history, setHistory] = useState([initial]);
+const [index, setIndex] = useState(0);
+const current = history[index];
+
+function apply(action) {
+  const next = reducer(current, action);
+  setHistory(h => [...h.slice(0, index + 1), next]);
+  setIndex(i => i + 1);
+}
+function undo() { setIndex(i => Math.max(0, i - 1)); }
+function redo() { setIndex(i => Math.min(history.length - 1, i + 1)); }
+```
+
+## Stores — when you need one
+
+Pick based on complexity:
+
+| Library | Feel |
+|---|---|
+| Zustand | Minimal, hook-based, great for small-to-medium |
+| Jotai | Atoms; fine-grained reactivity |
+| Redux Toolkit | Large apps with strict flow; heavy ceremony |
+| MobX | Observable objects; reactive by mutation |
+| Svelte stores | Built-in; simple |
+| Pinia | Vue default; ergonomic |
+
+Rule of thumb: start without a store. Add one when you pass the same piece of state through 4+ component levels of drilling.
+
+Keep store slices small and feature-aligned (`authStore`, `cartStore`). One giant store is the 2015 Redux antipattern.
+
+## Context — use for slow-changing values
+
+Context rerenders every consumer whenever the value changes. Fine for theme, i18n, auth user. Bad for frequently-changing values (cursor position, scroll position).
+
+Mitigations:
+- Split contexts: one per slow-changing value.
+- Use `useSyncExternalStore` / subscribe pattern for frequently-changing data.
+
+## URL state
+
+Filters, selected tab, pagination — put in the URL.
+
+```
+?status=active&sort=-createdAt&page=3
+```
+
+Benefits:
+- Bookmarkable, shareable, back/forward works.
+- Reload restores state.
+- Observable in analytics.
+
+Frameworks provide query-param hooks (`useSearchParams`, `useRoute`). Treat the URL as part of your state system, not an afterthought.
+
+## Persistence
+
+Some state needs to survive reload: draft form content, selected theme, auth tokens.
+
+| Where | For |
+|---|---|
+| `localStorage` | Preferences, form drafts (size limit ~5MB) |
+| `sessionStorage` | Per-tab, cleared on close |
+| `indexedDB` | Larger data, structured (offline caches) |
+| Cookie | Auth session (HttpOnly, Secure; see `backend/security.md`) |
+
+Rules:
+- Never store tokens in `localStorage` (XSS-readable).
+- Serialize deliberately — full store dumps change often and break older clients.
+- Version the stored shape; migrate on read when structure evolves.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| Global store holding fetched server data | Server-cache library |
+| Deriving state in `useEffect` | Derive with `useMemo` / computed |
+| Controlled forms with tons of re-renders | Uncontrolled + `react-hook-form` / equivalent |
+| Multiple sources of truth for the same value | Pick one; others derive |
+| Prop-drilling 5 levels deep | Context, composition, or store |
+| Redux for 3-component apps | `useState` is enough |
+| State updates inside render | Move to events / effects |
+| Forgetting to reset state on "new" contexts (e.g., user logout) | Clear or keyed remount |
+| Using `useEffect` to sync URL → state → URL | Derive from URL directly |