@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/svelte/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: svelte
+description: "Use when building, reviewing or fixing Svelte 5 (runes) and SvelteKit code — components with the rune primitives, rune modules versus stores, file routing, universal versus server load functions, form actions with progressive enhancement, remote functions, SSR/CSR/prerender choices, and adapters. Covers migrating Svelte 4 reactive statements to runes and hydration mismatches. NOT Next.js or React Server Components (that is `nextjs`)."
+tags: [svelte, sveltekit, runes, frontend, ssr, web]
+recommends: [typescript, vercel, design]
+origin: ai-hub
+---
+
+# Svelte 5 runes + SvelteKit
+
+> Explicit, signal-based reactivity (runes) plus the SvelteKit data-loading contract: knowing *where code runs* and *how `load` data reaches a page*.
+
+Two things break Svelte code more than anything else: treating `$effect` as the default for computed values, and confusing server-only `load` with universal `load`. This skill keeps you on the right side of both.
+
+## When to use
+
+- Authoring or editing `.svelte` / `.svelte.js` / `.svelte.ts` files.
+- Choosing `$state` vs `$derived` vs `$effect`; migrating Svelte 4 `let` / `$:` / `export let` to runes.
+- Writing or reviewing `+page.svelte`, `+page.ts`, `+page.server.ts`, `+layout*`, `+server.ts`, `+error.svelte`, `hooks.server.ts`.
+- `load` design (universal vs server), `PageData` typing, `depends`/`invalidate`, streaming promises, form actions with `use:enhance`.
+- Remote functions (`query`/`form`/`command`/`prerender` in `*.remote.ts`).
+- Adapter choice and SSR/CSR/prerender flags; hydration-mismatch debugging.
+
+## When NOT to use
+
+- Next.js / React Server Components → `../nextjs/SKILL.md`. Different reactivity model and data-loading contract. Never cross runes with React Server Components.
+- Pure TypeScript typing (generics, mapped/conditional types) with no Svelte dimension → `../typescript/SKILL.md`.
+- Deploy-target specifics (env, edge, project config) → `../vercel/SKILL.md`, `../netlify/SKILL.md`, `../cloudflare/SKILL.md`. This skill *picks the adapter*; those skills own the platform.
+- React, Vue/Nuxt, Astro, SolidJS, Angular are not in this catalog yet — keep any framework comparison brief and inline; do not link them.
+
+Current as of June 2026: **Svelte 5.56.x**, **SvelteKit 2.61.x**. Svelte 5 (runes) shipped Oct 2024.
+
+## First: detect Svelte 4 vs 5 — before you write a single rune
+
+The #1 way to hand someone broken advice is to mix Svelte 4 reactivity (`$:`, `export let`) with runes in the same file. They are silently incompatible: a `$:` block in a runes component does nothing reactive. Detect the mode first.
+
+1. Read `package.json` → `dependencies`/`devDependencies` `svelte`. `^5` (or `5.x`) = runes era. `^4` = legacy.
+2. Read `svelte.config.js`. `compilerOptions.runes: true` forces runes everywhere; absent = per-file auto-detect (a file is in runes mode iff it uses any rune).
+3. Grep the target file: `$state(` / `$props(` / `$derived(` → runes mode. `export let` / `$:` / `<slot` → legacy.
+
+Rule: **never give `$:`/`export let` advice and `$state`/`$props` advice for the same component.** If the codebase is Svelte 4 and the task is new work, migrate the file to runes first (see `references/runes.md` migration map) rather than appending runes onto legacy syntax.
+
+## Runes decision table
+
+Pick the rune by what the value *is*, not by habit. Reading a rune registers a dependency; writing one schedules an update.
+
+| You need | Rune | Why |
+| --- | --- | --- |
+| A reactive value you mutate | `$state(v)` | The cell tracked for reads/writes; deep objects/arrays are proxied. |
+| A value computed from others | `$derived(expr)` / `$derived.by(fn)` | Recomputed lazily from deps read *synchronously*; no manual wiring. |
+| A side effect (DOM, subscription, log) | `$effect(fn)` | Runs *after* DOM update; return a cleanup fn. Escape hatch, not default. |
+| A component input | `let { x } = $props()` | Destructure props; supports defaults and rest. |
+| A two-way-bindable prop | `let { x = $bindable() } = $props()` | Opts the prop into parent `bind:x`. |
+
+**`$effect` is the escape hatch.** If an effect's only job is to set state from other state, it's a `$derived` in disguise — and worse, writing `$state` inside an effect that also reads it can loop.
+
+```svelte
+<!-- Bad: effect used to compute → extra render, can loop -->
+<script>
+  let count = $state(0);
+  let doubled = $state(0);
+  $effect(() => { doubled = count * 2; });
+</script>
+
+<!-- Good: derived value, no effect -->
+<script>
+  let count = $state(0);
+  let doubled = $derived(count * 2);
+</script>
+```
+
+Deep mutation *is* reactive on `$state` (it returns a proxy), so mutate in place — you don't need to reassign.
+
+```svelte
+<script>
+  let todos = $state([{ done: false }]);
+  // Good: proxied, the push is tracked
+  function add() { todos.push({ done: false }); }
+  // Also fine: todos[0].done = true;
+</script>
+```
+
+Props with defaults and renaming:
+
+```svelte
+<script>
+  // Good: default + rename a reserved-ish name + rest props
+  let { title = 'Untitled', class: klass = '', ...rest } = $props();
+</script>
+```
+
+## Shared / global state across modules
+
+Reactive shared state must live in a **`.svelte.js`** or **`.svelte.ts`** module (the `.svelte` part tells the compiler to process runes). A plain `.js` file cannot use runes.
+
+The trap: you cannot `export let count = $state(0)` and reassign it elsewhere — importers get the *value* at import time, not the live cell, so it appears to "stop being reactive." Export a container whose identity is stable.
+
+```js
+// counter.svelte.js
+// Bad: importers bind the value, not the reactive cell
+export let count = $state(0); // reassigning count elsewhere won't propagate
+
+// Good: object identity is stable; .value stays reactive
+export const counter = $state({ value: 0 });
+
+// Good: getter/setter object
+let _n = $state(0);
+export const n = {
+  get value() { return _n; },
+  set value(v) { _n = v; },
+};
+
+// Good: a class instance (fields are reactive)
+export class Counter {
+  value = $state(0);
+  increment() { this.value += 1; }
+}
+```
+
+Classic `writable`/`readable`/`derived` stores from `svelte/store` are still valid and still work — prefer them when you need the `$store` auto-subscription sugar in templates or are integrating Svelte 4 code. For new runes-first code, the module patterns above are simpler. Depth in `references/runes.md`.
+
+## SvelteKit file map — what runs where
+
+| File | Runs | Purpose |
+| --- | --- | --- |
+| `+page.svelte` | client + SSR | The page component; reads `data: PageData`. |
+| `+page.ts` / `+layout.ts` | server (SSR) **and** browser (client nav) | Universal `load`. No secrets — code ships to the client. |
+| `+page.server.ts` / `+layout.server.ts` | server only | Server `load` + `actions`. DB, secrets, filesystem live here. |
+| `+server.ts` | server only | API route: `GET`/`POST`/… returning `Response`. |
+| `+error.svelte` | client + SSR | Rendered when a `load`/render throws. |
+| `hooks.server.ts` | server only | `handle`, `handleFetch`, `handleError` middleware. |
+
+## Data loading
+
+Universal vs server is the core decision. **Secrets, DB clients, and `$env/static/private` belong in `+page.server.ts`** — `+page.ts` code is shipped to the browser. Type the return with the generated `./$types`.
+
+```ts
+// +page.server.ts — server only; safe to touch DB/secrets
+import type { PageServerLoad } from './$types';
+import { db } from '$lib/server/db';
+
+export const load: PageServerLoad = async ({ params, depends }) => {
+  depends('app:post'); // custom dep, target of invalidate('app:post')
+  const post = await db.post.find(params.id);
+  // Top-level promise streams: the page renders, comments arrive later.
+  return { post, comments: db.comment.forPost(params.id) };
+};
+```
+
+```svelte
+<!-- +page.svelte -->
+<script lang="ts">
+  import type { PageData } from './$types';
+  let { data }: { data: PageData } = $props();
+</script>
+
+<h1>{data.post.title}</h1>
+
+{#await data.comments}
+  <p>Loading comments…</p>
+{:then comments}
+  <ul>{#each comments as c}<li>{c.body}</li>{/each}</ul>
+{/await}
+```
+
+Streaming a top-level promise works only from a **server** `load`. Universal `load` cannot stream the same way — await there or move the slow fetch to the server. Re-run a `load` with `invalidate('app:post')` (matches `depends`) or `invalidateAll()`. Patterns for `parent()`, named actions, and validation live in `references/sveltekit-data.md`.
+
+## Mutations: form actions first, remote functions second
+
+**Default to form actions.** They live in `+page.server.ts`, are posted to by a real `<form method="POST">`, and **work without JS**. `use:enhance` upgrades them to no-reload submission progressively.
+
+```ts
+// +page.server.ts
+import { fail, redirect } from '@sveltejs/kit';
+import type { Actions } from './$types';
+
+export const actions: Actions = {
+  login: async ({ request, cookies }) => {
+    const data = await request.formData();
+    const email = String(data.get('email') ?? '');
+    if (!email) return fail(400, { email, missing: true });
+    cookies.set('session', '…', { path: '/' });
+    throw redirect(303, '/dashboard');
+  },
+};
+```
+
+```svelte
+<!-- +page.svelte -->
+<script lang="ts">
+  import { enhance } from '$app/forms';
+  import type { ActionData } from './$types';
+  let { form }: { form: ActionData } = $props();
+</script>
+
+<form method="POST" action="?/login" use:enhance>
+  <input name="email" type="email" />
+  {#if form?.missing}<p>Email required</p>{/if}
+  <button>Log in</button>
+</form>
+```
+
+**Remote functions are EXPERIMENTAL** (available since SvelteKit 2.27, iterated through 2.61; API subject to change). They live in `*.remote.ts` and require opting in with **both** flags in `svelte.config.js` — `kit.experimental.remoteFunctions: true` **and** `compilerOptions.experimental.async: true` (the latter enables top-level `await`/awaited deriveds the feature relies on; without it remote functions do not actually enable). Four kinds: `query` (cached server read), `form` (progressive, parses its own FormData, no schema), `command` (mutation outside a form — requires JS), `prerender` (build-time). Use them for JS-driven flows where a plain form action is awkward; otherwise stick to form actions. Full usage in `references/sveltekit-data.md`.
+
+## SSR / CSR / prerender + adapters
+
+Control rendering per route with module-level exports in `+page.ts`/`+page.server.ts`:
+
+```ts
+export const prerender = true; // render at build time → static HTML
+export const ssr = false;      // skip server render; client-only
+export const csr = false;      // no client JS; pure SSR/static
+```
+
+Pick the adapter for the deploy target, then hand platform details to the platform skill:
+
+- `adapter-auto` — zero-config on Vercel / Netlify / Cloudflare. Good default.
+- `adapter-node` — long-running Node server (your own host, Docker).
+- `adapter-static` — full prerender; the whole site is static (needs `prerender = true` reachable everywhere).
+
+Env vars, edge runtime, KV/D1 bindings, build settings: that's `../vercel/SKILL.md`, `../netlify/SKILL.md`, `../cloudflare/SKILL.md`, not this skill.
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Do this instead |
+| --- | --- | --- |
+| `$effect` to compute a value from `$state` | Extra render pass; can loop if it reads what it writes | `$derived(expr)` / `$derived.by(fn)` |
+| `export let count = $state(0)` for shared state | Importers bind the value, not the live cell → "not reactive" | Export an object / getter / class instance |
+| Runes in a plain `.js` file | Compiler doesn't process runes there | Name it `.svelte.js` / `.svelte.ts` |
+| Mixing `$:` / `export let` with runes in one file | `$:` is dead in runes mode → silent non-reactivity | Migrate the whole file to runes (see references) |
+| DB call / secret in `+page.ts` | Universal `load` ships to the browser; secret leaks | Move to `+page.server.ts` (server-only) |
+| Streaming a top-level promise from universal `load` | Only server `load` streams | Await in load, or move the fetch server-side |
+| Mutating a non-`$state` object expecting reactivity | Only `$state` proxies are tracked | Wrap the value in `$state(...)` |
+| Reaching for remote functions by default | Experimental, JS-required, API may change | Form actions first; remote functions only when needed |
+
+## Verify
+
+Run `scripts/verify.sh` from the SvelteKit project root: `svelte-check` → `tsc --noEmit` → Vitest → `vite build`. Each tool is detected and skipped (not failed) if absent; it exits non-zero only on a real failure. The build step writes the output dir — not read-only.

package/skills/shared/svelte/evals/README.md

@@ -0,0 +1,3 @@
+# svelte evals
+
+These cases are prompts for sanity-checking the skill router and the skill's output quality; no automated runner ships here. Feed each `should_trigger` prompt to your router and confirm it selects `svelte`; feed each `should_not_trigger` prompt and confirm it routes to the named sibling (`nextjs`, `typescript`, `vercel`, `cloudflare`) instead. For the `capability` case, have the skill produce the SvelteKit `/dashboard` route and grade the result against the `must_include` rubric — the correct file split (server-only `load`/`actions`, no secret in universal load), runes usage (`$props`/`$derived`, not `$effect` for computed values), `use:enhance`, and typing from `./$types`. The `why`/`route_to` fields document intent; they are read by humans, not executed.

package/skills/shared/svelte/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: svelte
+
+should_trigger:
+  - prompt: "When should I use $derived instead of $effect in my Svelte component?"
+    why: "Core runes decision — computed value vs side effect — the skill's center of gravity."
+  - prompt: "Migrate this Svelte 4 component using export let and $: to Svelte 5 runes."
+    why: "Svelte 4 to 5 migration needs the export let to $props and $: to $derived/$effect map."
+  - prompt: "My +page.server.ts load returns data but the page tries to read a secret on the client — how do I split this correctly?"
+    why: "Universal vs server load contract; a secret leaking into universal load is the canonical SvelteKit data mistake."
+  - prompt: "Add a login form action in SvelteKit with use:enhance that still works without JavaScript."
+    why: "Form actions with progressive enhancement, the default mutation pattern in SvelteKit."
+  - prompt: "I export a $state count from a .js file and it stops being reactive when other components import it."
+    why: "Non-obvious — must be a .svelte.js module exporting a stable container, not a reassigned let."
+  - prompt: "Per què el meu $state no es reactiu quan muto un array dins un component Svelte?"
+    why: "Catalan, non-English; reactivity gotcha around $state proxies and deep mutation."
+  - prompt: "I'm getting a hydration mismatch warning in my SvelteKit app after SSR — where do I start?"
+    why: "Non-obvious symptom phrasing; hydration mismatch is an SSR/CSR plus load-data debugging task this skill owns."
+
+should_not_trigger:
+  - prompt: "Set up React Server Components with server actions in my Next.js app."
+    route_to: "nextjs"
+    why: "Different framework, reactivity model, and data-loading contract; runes and React Server Components must not be crossed."
+  - prompt: "Write a generic TypeScript mapped type and conditional type for a deep-partial utility, no framework involved."
+    route_to: "typescript"
+    why: "Pure TypeScript typing with no Svelte or Kit dimension."
+  - prompt: "Configure Vercel project environment variables and the edge runtime for my deployment."
+    route_to: "vercel"
+    why: "Platform/deploy config. This skill picks the adapter; the platform skill owns env and edge."
+  - prompt: "Bind a Cloudflare KV and D1 namespace in wrangler.toml for my Worker."
+    route_to: "cloudflare"
+    why: "Platform binding config, not SvelteKit code."
+
+capability:
+  - scenario: "Build a SvelteKit /dashboard route: a server load that fetches the current user, a form action to update the display name, and a runes-based child component that shows a derived greeting from the name."
+    must_include:
+      - "+page.server.ts exporting both a typed load (PageServerLoad) and actions (Actions)."
+      - "PageData / ActionData typing imported from './$types'."
+      - "Current user read server-side (locals or DB) — no secret or DB client in a universal +page.ts."
+      - "<form method=\"POST\"> with use:enhance from '$app/forms'."
+      - "Form action returns fail(...) on invalid input and uses redirect(...) for navigation, both from '@sveltejs/kit'."
+      - "Child component uses let { ... } = $props() and a $derived greeting, not $effect."

package/skills/shared/svelte/references/runes.md

@@ -0,0 +1,97 @@
+# Runes — full semantics, advanced variants, and Svelte 4→5 migration
+
+Current as of June 2026: Svelte 5.56.x. Reading a rune registers a dependency; writing one schedules an update.
+
+## State variants
+
+- `$state(v)` — reactive cell. Objects/arrays become deep proxies, so in-place mutation (`arr.push`, `obj.k = v`) is tracked. No need to reassign.
+- `$state.raw(v)` — non-proxied. The reference is reactive only on *reassignment* (`x = newValue`); mutations are not tracked. Use for large immutable structures or values you always replace wholesale (cheaper, no proxy overhead).
+- `$state.snapshot(x)` — a static, non-proxied deep clone of a `$state` proxy. Use when passing state to code that doesn't expect a proxy (`structuredClone`, external libs, `console.log` a clean object).
+
+```svelte
+<script>
+  let big = $state.raw({ rows: [] });        // reassign to update
+  big = { rows: [...big.rows, newRow] };      // tracked
+
+  let user = $state({ name: 'Ana' });
+  const plain = $state.snapshot(user);        // detached copy
+</script>
+```
+
+## Derived variants
+
+- `$derived(expr)` — for a single expression.
+- `$derived.by(() => { … })` — for multi-statement computations; return the value. Same laziness and dependency tracking; deps are whatever you read *synchronously* inside.
+
+```svelte
+<script>
+  let nums = $state([1, 2, 3]);
+  let total = $derived.by(() => {
+    let s = 0;
+    for (const n of nums) s += n;
+    return s;
+  });
+</script>
+```
+
+A `$derived` is read-only by default but *can* be temporarily overridden by assignment (optimistic UI); it reverts when a dependency changes.
+
+## Effect variants
+
+- `$effect(fn)` — runs after the DOM updates. Return a function for cleanup (runs before re-run and on destroy). Only re-runs for deps read *synchronously* during the run; values read inside `await`/`setTimeout` are not tracked.
+- `$effect.pre(fn)` — runs *before* the DOM updates (e.g. measure scroll before layout changes).
+- `$effect.root(fn)` — creates an effect scope outside the component lifecycle; returns a dispose function. For manually-managed effects (e.g. in a store module).
+- `$effect.tracking()` — boolean: are we inside a tracking context right now? Useful in shared utilities.
+- `untrack(fn)` — read state without registering it as a dependency. Breaks unwanted loops.
+
+```svelte
+<script>
+  import { untrack } from 'svelte';
+  let a = $state(0), log = $state([]);
+  $effect(() => {
+    const cur = a;                       // tracked dep
+    untrack(() => log.push(cur));        // reading/writing log is NOT a dep → no loop
+  });
+</script>
+```
+
+Rule of thumb: if an effect's body is "set state B from state A", delete it and use `$derived`. Reserve `$effect` for genuine side effects — DOM APIs, subscriptions, analytics, third-party widgets.
+
+## Props, binding, debugging
+
+- `$props()` — destructure inputs: `let { a, b = 1, ...rest } = $props()`. Rename reserved words: `let { class: klass } = $props()`.
+- `$props.id()` — a unique, SSR-stable id for the component instance (good for `for`/`aria-describedby` pairing).
+- `$bindable(default)` — marks a prop as two-way: `let { value = $bindable('') } = $props()`, parent does `<Child bind:value />`.
+- `$inspect(...values)` — dev-only; logs when tracked values change. `$inspect(x).with(fn)` for a custom handler. Stripped in production.
+- `$host()` — inside a custom element, the host DOM node (for dispatching native events).
+
+## Snippets and events (replacing slots / dispatchers)
+
+- Slots → **snippets**: `{#snippet name(args)} … {/snippet}` defined, rendered with `{@render name(args)}`. Children passed to a component arrive as the `children` snippet prop: `let { children } = $props()` then `{@render children()}`.
+- `createEventDispatcher` is deprecated → pass **callback props**: `let { onsave } = $props()` and call `onsave(payload)`.
+- DOM events lose the colon: `on:click` → `onclick`, `on:input` → `oninput`.
+
+## Svelte 4 → 5 migration map
+
+| Svelte 4 | Svelte 5 (runes) |
+| --- | --- |
+| `let count = 0;` (reactive top-level) | `let count = $state(0);` |
+| `$: doubled = count * 2;` | `let doubled = $derived(count * 2);` |
+| `$: { sideEffect(count); }` | `$effect(() => { sideEffect(count); });` |
+| `export let title;` | `let { title } = $props();` |
+| `export let title = 'x';` | `let { title = 'x' } = $props();` |
+| `<slot />` | `{@render children()}` (+ `let { children } = $props()`) |
+| named `<slot name="head" />` | named snippet prop + `{@render head()}` |
+| `on:click={fn}` | `onclick={fn}` |
+| `createEventDispatcher()` + `dispatch('save', x)` | callback prop `onsave` + `onsave(x)` |
+| `bind:value` on a prop (auto) | declare `$bindable()` on that prop in the child |
+| store `$count` in template | still valid; or migrate to a `.svelte.js` rune module |
+
+The `npx sv migrate svelte-5` codemod automates most of this; review the diff — it cannot always tell a computed `$:` from a side-effect `$:`.
+
+## Fine-grained reactivity gotchas
+
+- A `$state` array assigned from a `$derived` does not auto-track its source — derive the array directly.
+- Destructuring a `$state` object (`let { x } = state`) snapshots `x`; it stops tracking. Read `state.x` where you need reactivity, or use `$derived(() => state.x)`.
+- `Map`/`Set`/`Date` need `svelte/reactivity` (`SvelteMap`, `SvelteSet`, `SvelteDate`) to be reactive; plain ones are not proxied.
+- Passing a `$state` proxy to a non-Svelte library can confuse it — pass `$state.snapshot(x)`.

package/skills/shared/svelte/references/sveltekit-data.md

@@ -0,0 +1,156 @@
+# SvelteKit data loading, mutations, remote functions, and hooks
+
+Current as of June 2026: SvelteKit 2.61.x.
+
+## Universal vs server `load`
+
+| | Universal (`+page.ts`, `+layout.ts`) | Server (`+page.server.ts`, `+layout.server.ts`) |
+| --- | --- | --- |
+| Runs on | server during SSR **and** browser on client nav | server only |
+| Can touch | public APIs, `$env/static/public`, `fetch` | DB clients, secrets, `$env/static/private`, filesystem, cookies |
+| Return value | any JS value (functions, classes ok) | must be serializable (devalue: Dates, Maps, etc. — no functions/classes) |
+| Can stream | no | yes (top-level promises) |
+
+If both exist for the same route, the server `load` runs first and its data is passed to the universal `load` via the `data` argument.
+
+```ts
+// +layout.server.ts
+import type { LayoutServerLoad } from './$types';
+export const load: LayoutServerLoad = async ({ locals }) => ({ user: locals.user });
+```
+
+## `parent()` and dependency tracking
+
+```ts
+import type { PageLoad } from './$types';
+export const load: PageLoad = async ({ parent, fetch }) => {
+  const { user } = await parent();          // merge in ancestor load data
+  const res = await fetch(`/api/feed/${user.id}`);
+  return { feed: await res.json() };
+};
+```
+
+- `depends('app:feed')` registers a custom invalidation key; `depends` also auto-tracks any `fetch(url)` and accessed `params`/`url`.
+- Re-run: `invalidate('app:feed')` (custom key), `invalidate('/api/feed')` (URL), `invalidate(url => url.pathname.startsWith('/api'))` (predicate), or `invalidateAll()`.
+
+## Streaming
+
+Return a non-awaited promise at the top level of a **server** `load`; the page shell renders immediately and the data resolves later.
+
+```ts
+// +page.server.ts
+export const load = async () => ({
+  meta: await getMeta(),          // awaited — blocks the response
+  slowList: getSlowList(),        // promise — streamed
+});
+```
+
+```svelte
+{#await data.slowList}
+  <Spinner />
+{:then list}
+  …
+{:catch err}
+  <p>{err.message}</p>
+{/await}
+```
+
+## Form actions
+
+Live in `+page.server.ts`. The default action is `<form method="POST">`; named actions use `action="?/login"` and `export const actions = { login, logout }`.
+
+```ts
+import { fail, redirect } from '@sveltejs/kit';
+import type { Actions } from './$types';
+
+export const actions: Actions = {
+  default: async ({ request }) => {
+    const data = await request.formData();
+    const title = String(data.get('title') ?? '').trim();
+    if (!title) return fail(422, { title, error: 'Title required' }); // returned as `form`
+    await save({ title });
+    throw redirect(303, '/done');
+  },
+};
+```
+
+`fail(status, data)` returns serializable data to the page's `form` prop (keep the user's input so the form repopulates). `redirect` and `error` are thrown, not returned.
+
+### `use:enhance`
+
+Bare `use:enhance` gives no-reload submit + automatic `form`/`data` update + focus management. Customize without losing the defaults:
+
+```svelte
+<script lang="ts">
+  import { enhance } from '$app/forms';
+  let submitting = $state(false);
+</script>
+
+<form method="POST" use:enhance={() => {
+  submitting = true;
+  return async ({ update }) => {
+    await update();        // apply the default result handling
+    submitting = false;
+  };
+}}>
+  <button disabled={submitting}>Save</button>
+</form>
+```
+
+## Remote functions (EXPERIMENTAL)
+
+Available since SvelteKit 2.27, iterated through 2.61. API is subject to change. Opt in with **both** flags — `kit.experimental.remoteFunctions` enables the feature, and `compilerOptions.experimental.async` enables the top-level `await` it relies on. Omit either and remote functions stay off:
+
+```js
+// svelte.config.js
+export default {
+  kit: { experimental: { remoteFunctions: true } },
+  compilerOptions: { experimental: { async: true } },
+};
+```
+
+Functions live in `*.remote.ts`. Four kinds:
+
+```ts
+// data.remote.ts
+import { query, form, command, prerender } from '$app/server';
+
+export const getPosts = query(async () => db.post.all());          // cached server read
+export const getPost  = query('unchecked', async (id: string) => db.post.find(id)); // with arg
+
+export const createPost = form(async (data: FormData) => {          // progressive, parses FormData
+  const title = String(data.get('title') ?? '');
+  return db.post.create({ title });
+});
+
+export const like = command(async (id: string) => db.post.like(id)); // mutation, requires JS
+
+export const docs = prerender(async () => loadStaticDocs());        // build-time
+```
+
+In a component, `query`/`prerender` return an awaitable with reactive state (`getPosts().current`, `.loading`, `.error`); `form` exposes props to spread onto a `<form>`; `command` is called imperatively (no form, JS required). Prefer plain form actions unless you specifically need imperative mutations or co-located queries.
+
+## Hooks
+
+```ts
+// hooks.server.ts
+import type { Handle, HandleFetch } from '@sveltejs/kit';
+
+export const handle: Handle = async ({ event, resolve }) => {
+  event.locals.user = await getUser(event.cookies.get('session'));
+  return resolve(event);
+};
+
+export const handleFetch: HandleFetch = async ({ request, fetch }) => {
+  // rewrite/relabel outbound fetch (e.g. internal URL, auth header)
+  return fetch(request);
+};
+```
+
+`handle` wraps every request (auth, headers, `locals`). `handleFetch` intercepts `fetch` calls made inside `load`. `handleError` shapes uncaught errors before they reach `+error.svelte`.
+
+## Errors and redirects
+
+- `error(404, 'Not found')` (thrown) → renders the nearest `+error.svelte` with `page.error`.
+- `redirect(303, '/login')` (thrown) → HTTP redirect; use 303 after a POST.
+- A `load` that throws an unexpected error triggers `handleError` then `+error.svelte`.

package/skills/shared/svelte/scripts/verify.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# verify.sh — Svelte 5 / SvelteKit project gate.
+#
+# Usage:
+#   bash scripts/verify.sh            # run from the SvelteKit project root
+#
+# What it does (in order): svelte-check -> tsc --noEmit -> Vitest -> vite build.
+# Each tool is detected; if it is not installed/resolvable it is SKIPPED with a
+# yellow warning (NOT a failure). Exits non-zero only on a real tool failure, so
+# an empty or tooling-free directory exits 0.
+#
+# Side effects: svelte-check, tsc and the test run are read-only. The final
+# `vite build` WRITES the build output dir (`.svelte-kit/output`, `build/`) and
+# may write `.svelte-kit/` type stubs — it is NOT a pure read-only step. It does
+# no installs and no network mutations. Safe to re-run.
+#
+# Portability: targets stock macOS bash 3.2. No `mapfile`, no empty-array
+# expansion under `set -u`, graceful skip when a tool is missing. `set -e` is
+# intentionally NOT used (each check owns its exit code); `set -u` is on.
+
+set -u
+
+# --- colors (only when stdout is a TTY) -----------------------------------
+if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
+  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
+else
+  RED=""; GREEN=""; YELLOW=""; RESET=""
+fi
+
+failures=0
+# Space-separated list (portable to bash 3.2; avoids empty-array expansion under set -u).
+skips=""
+
+have() { command -v "$1" >/dev/null 2>&1; }
+warn() { printf '%s\n' "${YELLOW}SKIP: $1${RESET}"; skips="${skips}${skips:+ }$2"; return 0; }
+fail() { printf '%s\n' "${RED}FAIL: $1${RESET}"; failures=$((failures + 1)); }
+ok()   { printf '%s\n' "${GREEN}OK: $1${RESET}"; }
+
+# --- resolve a package runner from the lockfile ----------------------------
+RUN=""
+if [ -f pnpm-lock.yaml ] && have pnpm; then
+  RUN="pnpm exec"
+elif [ -f yarn.lock ] && have yarn; then
+  RUN="yarn"
+elif [ -f package-lock.json ] && have npm; then
+  RUN="npm exec --"
+elif have npx; then
+  RUN="npx --no-install"
+fi
+
+run_bin() {
+  # run_bin <bin-name> <args...> : true if the bin is resolvable and runs
+  bin="$1"; shift
+  if have "$bin"; then "$bin" "$@"; return $?; fi
+  if [ -x "node_modules/.bin/$bin" ]; then "node_modules/.bin/$bin" "$@"; return $?; fi
+  if [ -n "$RUN" ]; then $RUN "$bin" "$@"; return $?; fi
+  return 127
+}
+
+bin_available() {
+  bin="$1"
+  have "$bin" && return 0
+  [ -x "node_modules/.bin/$bin" ] && return 0
+  return 1
+}
+
+# --- 0. bail early on a non-SvelteKit / empty directory --------------------
+# No package.json at all → nothing to verify; succeed (don't false-fail an
+# empty or clean target).
+if [ ! -f package.json ]; then
+  printf '%s\n' "${YELLOW}no package.json here — nothing to verify${RESET}"
+  printf '%s\n' "${GREEN}verify.sh: all runnable checks passed${RESET}"
+  exit 0
+fi
+
+# --- 1. svelte-check (type + template diagnostics) -------------------------
+if bin_available svelte-check; then
+  printf '%s\n' "Running svelte-check..."
+  if run_bin svelte-check --threshold error; then ok "svelte-check"; else fail "svelte-check"; fi
+else
+  warn "svelte-check not resolvable — skipping template/type diagnostics" "svelte-check"
+fi
+
+# --- 2. TypeScript ---------------------------------------------------------
+if bin_available tsc && [ -f tsconfig.json ]; then
+  printf '%s\n' "Running tsc --noEmit..."
+  if run_bin tsc --noEmit; then ok "tsc --noEmit"; else fail "tsc --noEmit"; fi
+else
+  warn "tsc or tsconfig.json missing — skipping type check" "tsc"
+fi
+
+# --- 3. Vitest -------------------------------------------------------------
+# Treat the repo as having unit tests when a vitest config exists OR `*.test.*`
+# files exist. (SvelteKit scaffolds use Vitest for unit tests.)
+has_tests=false
+if ls vitest.config.* vitest.workspace.* >/dev/null 2>&1; then
+  has_tests=true
+elif find . \( -name node_modules -o -name .svelte-kit -o -name build -o -name dist \) -prune -o \
+       -name '*.test.*' -print 2>/dev/null | grep -q .; then
+  has_tests=true
+fi
+if bin_available vitest && [ "$has_tests" = true ]; then
+  printf '%s\n' "Running vitest run..."
+  if run_bin vitest run; then ok "vitest"; else fail "vitest"; fi
+else
+  warn "vitest or unit tests (vitest.config.* / *.test.*) not present — skipping unit tests" "vitest"
+fi
+
+# --- 4. vite build (slow; WRITES build output; run last) -------------------
+# SvelteKit builds through Vite. Skip (not fail) if vite is unresolvable.
+if bin_available vite; then
+  printf '%s\n' "Running vite build... (writes .svelte-kit/output and the adapter output dir)"
+  if run_bin vite build; then ok "vite build"; else fail "vite build"; fi
+else
+  warn "vite not resolvable — skipping build" "vite build"
+fi
+
+# --- summary ---------------------------------------------------------------
+printf '\n'
+if [ -n "$skips" ]; then
+  printf '%s\n' "${YELLOW}skipped: ${skips}${RESET}"
+fi
+if [ "$failures" -gt 0 ]; then
+  printf '%s\n' "${RED}verify.sh: $failures check(s) failed${RESET}"
+  exit 1
+fi
+printf '%s\n' "${GREEN}verify.sh: all runnable checks passed${RESET}"
+exit 0