claude-toolkit 0.1.25 → 0.9.0

package/stacks/cloudflare/skills/ct-cloudflare-d1-kv/SKILL.md

@@ -96,6 +96,83 @@ Key points:
 - Always use Hyperdrive for external database connections from Workers.
 - Connection pool size is configurable per Hyperdrive config.
 
+## Performance
+
+> _Verified against Cloudflare Workers / D1 / KV (2026-06)._
+
+Latency on Workers is dominated by **network round trips**, not CPU. Every `await` on D1/KV/`fetch` is a hop -- collapse and parallelize them.
+
+### Don't serialize independent round trips
+
+```rust
+// BAD: ~2x latency -- two independent reads run back to back
+let user = get_user(&db, id).await?;
+let prefs = get_prefs(&kv, id).await?;
+
+// GOOD: one round-trip wall-time -- run concurrently
+let (user, prefs) = futures::try_join!(get_user(&db, id), get_prefs(&kv, id))?;
+```
+```typescript
+// TS equivalent
+const [user, prefs] = await Promise.all([getUser(db, id), getPrefs(kv, id)]);
+```
+
+I/O overlaps in the single-threaded isolate, so wall-time approaches the slowest call. (A Worker can have only ~6 connections waiting on response headers at once -- so fan-out is no substitute for collapsing N reads into one query.)
+
+Kill N+1: never loop per-row queries. Use one `IN (...)`/JOIN, or `db.batch()` of selects.
+
+```rust
+// BAD: 1 + N round trips
+for id in ids { rows.push(db.prepare("SELECT * FROM u WHERE id=?1").bind(&[id.into()])?.first(None).await?); }
+// GOOD: 1 round trip
+let placeholders = ids.iter().map(|_| "?").collect::<Vec<_>>().join(",");
+let users = db.prepare(&format!("SELECT * FROM u WHERE id IN ({placeholders})"))
+    .bind(&binds)?.all().await?.results::<User>()?;   // .all() -> D1Result; .results() -> typed rows
+```
+
+### Verify the index is actually used
+
+An index exists != the planner uses it. Functions on columns, leading-`%` LIKE, and TEXT/INT mismatches force a SCAN.
+
+```sql
+EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?1;
+-- want: SEARCH users USING INDEX idx_users_email   (NOT: SCAN users)
+```
+
+### Cache API for full responses (not just KV)
+
+`caches.default` is data-center-local (contents don't replicate across colos): sub-ms in-colo, cheaper than a KV read, no eventual-consistency lag. Use it for whole GET responses (only GET is cacheable); use KV read-through for sub-response values. Fill the cache off the response path with `waitUntil`.
+
+```typescript
+const cache = caches.default;
+let res = await cache.match(request);
+if (!res) {
+  res = await render(request);                 // Cache-Control sets TTL
+  ctx.waitUntil(cache.put(request, res.clone())); // non-blocking write
+}
+return res;
+```
+
+`cache.put` rejects non-GET, `206`, `Vary: *`, and `Set-Cookie` responses (strip the cookie or set `Cache-Control: private=Set-Cookie` first).
+
+Same rule for cache/KV writes and invalidation: `ctx.waitUntil(kv.put(...))` so writes never add to TTFB.
+
+### Stream instead of buffering
+
+Buffering the full body adds total generation time to TTFB. Return a `ReadableStream` (or pipe an upstream body) so bytes flush as produced.
+
+### Smart Placement for origin/Hyperdrive-heavy Workers
+
+Smart Placement moves the isolate closer to your **back-end** (origin APIs, or an external Postgres/MySQL behind Hyperdrive) when latency is dominated by multiple **sequential** calls to it:
+
+```toml
+# wrangler.toml
+[placement]
+mode = "smart"
+```
+
+It does **not** help D1 or KV: D1 routing is governed by the primary-instance location + read replication (use the Sessions API to read from a nearby replica), and KV is already served from the data center the Worker runs in. Leave Smart Placement off for single-hop, D1/KV-only, or static-heavy Workers.
+
 ## Anti-Patterns
 
 1. **Unbounded queries** -- Always LIMIT. D1 has 5MB response cap.
@@ -104,3 +181,12 @@ Key points:
 4. **Skipping batch** -- Each D1 call is a network round trip.
 5. **KV without TTL** -- Stale data persists indefinitely.
 6. **Untested migrations** -- Always `--local` before `--remote`.
+7. **Sequential awaits on independent reads** -- each is a round trip; use `try_join!`/`Promise.all`.
+8. **Per-row query loops (N+1)** -- batch into one `IN (...)`/JOIN or `db.batch()`.
+9. **Awaiting cache/KV writes before responding** -- use `ctx.waitUntil()` so puts don't add to TTFB.
+10. **Assuming the index is used** -- check `EXPLAIN QUERY PLAN` for `USING INDEX`, not `SCAN`.
+11. **Smart Placement for D1/KV latency** -- it targets origins/Hyperdrive, not D1/KV; use D1 read replication (Sessions API) instead.
+
+## See Also
+
+- `ct-rust-wasm-patterns` — the same D1 round-trip / `IN`-with-bound-params batching, from the Rust handler side.

package/stacks/i18n-typesafe/skills/ct-i18n-typesafe/SKILL.md

@@ -54,6 +54,49 @@ Types are inferred from base locale: `{name:string}`, `{count:number}`. TypeScri
 
 Organize by feature (common, auth, events), one level deep. Avoid deep nesting -- it makes keys verbose.
 
+## Performance
+
+> _Verified against typesafe-i18n + SolidJS (2026-06)._
+
+Ship one locale, not all. typesafe-i18n generates both loaders -- pick the async one.
+
+```ts
+// CORRECT: per-locale dynamic import -> separate chunk, only active locale fetched
+import { loadLocaleAsync } from './i18n/i18n-util.async';
+await loadLocaleAsync(detectLocale());   // e.g. 'en' loads the i18n/en chunk only
+
+// WRONG: i18n-util.sync static-imports every dictionary at module top -> all in this bundle
+import { loadLocale } from './i18n/i18n-util.sync';
+loadLocale('en');                        // loadAllLocales() is worse
+```
+
+Build formatters once per locale; never construct Intl objects in a component or list row. (Measured: constructing `Intl.NumberFormat` ~20x slower than reusing one instance.)
+
+```ts
+// src/i18n/formatters.ts -- constructed once via loadFormatters(locale)
+export const initFormatters: FormattersInitializer<Locales, Formatters> = (locale) => ({
+  // Intl.* is expensive to construct; reuse the instance across all calls
+  currency: (v: number) => new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(v),
+});
+// usage in en/index.ts: price: 'Total: {amount:number|currency}'  -- typed param, not new Intl.* at the call site
+```
+
+Don't block first paint on the locale fetch. In Solid, `<Suspense>` only suspends on a tracked resource read -- a bare `await loadLocaleAsync()` will NOT trip the boundary. Drive it off a resource (or use the Solid adapter's `<TypesafeI18n>`, which withholds children until the locale loads):
+
+```tsx
+import { createResource, Suspense } from 'solid-js';
+// loaded() is read inside the boundary, so Suspense shows the shell until the chunk arrives
+const [loaded] = createResource(detectLocale, loadLocaleAsync);
+<Suspense fallback={<AppShell />}>{loaded.state === 'ready' && props.children}</Suspense>
+// index.html: a modulepreload link for /assets/i18n-en-*.js overlaps with the main bundle fetch
+```
+
+RTL: drive the html dir attribute from the locale; use CSS logical properties so layout flips with zero extra CSS or JS.
+
+```css
+.card { margin-inline-start: 1rem; padding-inline: 1rem; inset-inline-start: 0; } /* not margin-left */
+```
+
 ## Anti-Patterns
 
 1. **Hardcoded strings** -- Every user-visible string goes through `LL()`.
@@ -62,3 +105,12 @@ Organize by feature (common, auth, events), one level deep. Avoid deep nesting -
 4. **Dynamic key access** -- `LL()[dynamicKey]()` bypasses type safety. Use conditional rendering.
 5. **Forgetting loadLocale** -- Must call before rendering or get runtime errors.
 6. **Over-splitting namespaces** -- Group by feature, not by component.
+7. **Sync `loadLocale` / `loadAllLocales` in app code** -- `i18n-util.sync` static-imports every dictionary into the bundle that pulls it in. Use `loadLocaleAsync` so each locale is its own chunk.
+8. **Constructing `Intl.NumberFormat`/`DateTimeFormat` per render** -- ~20x costlier than reuse; build once in `formatters.ts` and reference via `{v:number|formatter}`.
+9. **Awaiting `loadLocaleAsync` without a Suspense-tracked resource** -- Blanks the screen until the JSON loads, and a bare `await` never trips Solid's `<Suspense>`. Gate via `createResource` (or `<TypesafeI18n>`), show a shell fallback, and modulepreload the active locale.
+10. **Physical CSS for layout (`margin-left`, `left`)** -- Breaks RTL and needs per-dir overrides. Use logical properties (`margin-inline-start`, `inset-inline-start`).
+
+## See Also
+
+- `ct-solidjs-patterns` — the `createResource`-tracked `<Suspense>` boundary (a bare `await` never suspends in Solid) and `lazy()` cold-start splitting.
+- `ct-vanilla-extract-patterns` — RTL = `dir` from locale (here) + logical properties authored in `.css.ts` (there).

package/stacks/i18n-typesafe/stack.json

@@ -19,7 +19,8 @@
 					"(?:translat).*(?:key|string)"
 				],
 				"contentPatterns": ["useI18nContext", "LL\\.", "baseLocale", "Locales"]
-			}
+			},
+			"relatedSkills": ["ct-solidjs-patterns", "ct-vanilla-extract-patterns"]
 		}
 	}
 }

package/stacks/playwright/skills/ct-playwright-patterns/SKILL.md

@@ -107,7 +107,7 @@ await page.route("**/analytics/**", (route) => route.abort());
 
 Mock ~80% of API calls for speed; keep ~20% hitting real endpoints. Always call `route.continue()`, `route.fulfill()`, or `route.abort()`. Use `page.unrouteAll()` in cleanup.
 
-## WebSocket Mocking (v1.53+)
+## WebSocket Mocking (v1.48+)
 
 ```typescript
 await page.routeWebSocket("wss://example.com/ws", (ws) => {
@@ -127,7 +127,7 @@ test("WCAG 2.1 AA", async ({ page }) => {
 });
 ```
 
-Aria snapshots (v1.52+): `await expect(nav).toMatchAriaSnapshot(...)`.
+Aria snapshots (v1.49+): `await expect(nav).toMatchAriaSnapshot(...)`.
 
 ## Parallelization
 
@@ -137,6 +137,65 @@ Aria snapshots (v1.52+): `await expect(nav).toMatchAriaSnapshot(...)`.
 
 Each worker gets its own `BrowserContext` (isolated cookies/storage). Use `mode: "serial"` sparingly.
 
+## Test Speed
+
+> _Verified against Playwright 1.5x (2026-06)._
+
+E2E wall-clock is dominated by browser launches and UI setup. Three levers: maximize parallelism, seed state over HTTP, fan out across CI.
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  fullyParallel: true,                          // parallelize within files, not just across them
+  workers: process.env.CI ? "50%" : undefined,  // track the runner's real vCPUs; undefined = 50% cores locally
+  webServer: {
+    command: "npm run preview",                 // prebuilt/preview server, not a dev build
+    url: "http://localhost:4173",
+    reuseExistingServer: !process.env.CI,       // reuse on local reruns; CI always boots fresh
+    timeout: 120_000,
+  },
+});
+```
+
+> Don't hardcode `workers` to a number larger than the runner. GitHub standard runners are 2 vCPU (private) / 4 (public); oversubscribing thrashes. `"50%"` (or a count you've matched to the runner) is portable.
+
+**Seed state over HTTP, not the UI.** Driving the browser to create fixtures/auth is the costliest per-test work. Do it once in the `setup` project via the `request` fixture (no browser, no UI clicks), then reuse `storageState` — same project-dependency pattern this stack already uses for UI login:
+
+```typescript
+// e2e/auth.setup.ts  (consumed via dependencies: ["setup"] + storageState in config)
+import { test as setup } from "@playwright/test";
+
+setup("authenticate via API", async ({ request }) => {
+  await request.post("/api/login", {
+    data: { email: process.env.E2E_EMAIL, password: process.env.E2E_PASSWORD },
+  });
+  await request.storageState({ path: "e2e/.auth/user.json" });
+});
+```
+
+The `request` fixture is a full HTTP client (it wraps `apiRequest.newContext()` under the hood) and carries cookies set by the response — no manual context to dispose. Keep credentials in env/secrets, never literals, and keep `e2e/.auth/` gitignored (it holds live session tokens).
+
+**Shard across CI runners** (blob reporter + `merge-reports`, v1.37+):
+
+```yaml
+strategy:
+  matrix: { shard: [1, 2, 3, 4] }
+steps:
+  - run: npx playwright test --shard=${{ matrix.shard }}/4
+# reporter: process.env.CI ? "blob" : "html"  in config
+# upload blob-report/, then a dependent job:
+  - run: npx playwright merge-reports --reporter=html ./all-blob-reports
+```
+
+Shards stay balanced only when `fullyParallel: true` lets Playwright split at the test level; otherwise file-level granularity leaves wall-clock gated by the slowest shard.
+
+| Lever | Effect |
+|---|---|
+| `fullyParallel: true` + `workers` | Near-linear speedup up to vCPU count |
+| `request` fixture seeding | Cuts per-test setup from seconds to ms |
+| `--shard=i/n` across runners | ~total/n with `fullyParallel`; uneven (gated by slowest shard) without it |
+| `trace: "on-first-retry"` | No trace cost on the passing path |
+
 ## CI/CD
 
 - Use official Playwright Docker image (`mcr.microsoft.com/playwright:v1.58.0-noble`)
@@ -166,3 +225,12 @@ Each worker gets its own `BrowserContext` (isolated cookies/storage). Use `mode:
 6. **Using Playwright for unit tests** -- Use Vitest for pure logic.
 7. **Committing raw codegen output** -- Always refactor into Page Objects.
 8. **Not cleaning up route handlers** -- Use `page.unrouteAll()`.
+9. **Logging in / seeding data through the UI per test** -- Use the `request` fixture (or `context.request`) to seed state over HTTP, save it to `storageState`, reuse via project `dependencies`.
+10. **Hardcoding `workers` above the runner's vCPUs on CI** -- Defaults to 50% of *logical* cores; throttled/oversubscribed runners thrash. Use `"50%"` or pin to the runner's real vCPU count.
+11. **`--shard` without the blob reporter + `merge-reports`** -- Produces fragmented/duplicate reports instead of one merged HTML.
+12. **Booting a dev server (HMR/rebuild) as the `webServer` target** -- Point CI at a prebuilt preview build.
+
+## See Also
+
+- `ct-testing-patterns` — the canonical cross-runner test-speed rule (parallelism sized to the runner, file-level `--shard` + blob/merge-reports).
+- `ct-vite-vitest-patterns` — shares the CI sharding/worker budget; don't oversubscribe a runner running both.

package/stacks/protobuf/skills/ct-protobuf-contracts/SKILL.md

@@ -68,6 +68,34 @@ prost_build::Config::new()
 - Adding fields and enum values is safe.
 - Run `buf breaking --against .git#branch=main` before merging.
 
+## Performance
+
+> _Verified against proto3 / prost / protoc-gen-ts (2026-06)._
+
+Wire format = field tag + value. Tag size depends only on the field NUMBER (`tag = (number << 3) | wire_type`, varint-encoded), so number placement is a perf decision, not just style.
+
+| Field number | Tag bytes |
+|---|---|
+| 1-15 | 1 |
+| 16-2047 | 2 |
+| 2048+ | 3 |
+
+```protobuf
+// Hot message decoded in tight loops -- keep it small, flat, low numbers.
+message Tick {
+  int64 ts       = 1;   // 1-byte tag
+  double price   = 2;
+  repeated int32 levels = 3;  // packed automatically in proto3 (one tag for the whole run)
+  string debug_note = 16;     // rarely set -> 2-byte tag, fine up here
+}
+```
+
+- **Packed repeated scalars are free wins.** `repeated int32/int64/float/double/bool/enum` are packed by default in proto3 (single tag + length, not a tag per element). `repeated string/bytes/message` are NOT packed -- prefer packed scalar arrays over `repeated SomeWrapper` in hot paths.
+- **`bytes`, not `string`, for opaque data.** `string` is UTF-8-validated on every decode (prost runs `str::from_utf8` eagerly; protoc-gen-ts runs `TextDecoder` with `fatal`). Use `bytes` for hashes, tokens, IDs, and binary blobs to skip the scan; keep `string` for human-readable text.
+- **Keep hot messages flat.** Each nested sub-message is a separate length-delimited decode + allocation in prost. Inline frequent fields; reserve nesting for cold/rare data.
+- **Decode once.** prost decodes the whole message eagerly and allocates as it goes -- there are no lazy fields (proto3 `[lazy=true]` is not implemented by prost or protoc-gen-ts). Decode a payload one time and pass the struct around; never re-parse the same bytes. (The one zero-copy lever: generate `bytes` fields as `bytes::Bytes` via `prost_build`'s `.bytes(...)` to borrow from the input buffer instead of copying.)
+- **Route without full decode.** Cheapest dispatch/filter is a transport header carried outside the message body. If you must read one field from the payload, neither prost nor protoc-gen-ts exposes a partial-decode API -- you decode the whole message -- so put any field you might hand-scan for at number 1-15 to keep that scan short.
+
 ## Anti-Patterns
 
 1. **Reusing field numbers** -- Causes data corruption. Always reserve removed numbers.
@@ -76,3 +104,11 @@ prost_build::Config::new()
 4. **Proto2 syntax** -- Always proto3 for new projects.
 5. **Skipping buf lint** -- Inconsistent naming compounds. Lint early.
 6. **Large messages** -- Not for multi-MB payloads. Use streaming/chunking.
+7. **`string` for binary/opaque data** -- Forces UTF-8 validation on every decode. Use `bytes`.
+8. **`repeated` wrapper messages for scalar arrays** -- Loses proto3 packing. Use `repeated int32/double/...` directly in hot paths.
+9. **Re-decoding the same payload** -- No lazy fields; every Decode allocates (the only zero-copy path is `bytes` fields generated as `bytes::Bytes`). Decode once, reuse the struct.
+10. **High field numbers on hot fields** -- Numbers >=16 cost 2+ tag bytes per occurrence. Keep frequent fields at 1-15.
+
+## See Also
+
+- `ct-rust-wasm-patterns` — the decode-once consumer side; generate `bytes` fields as `bytes::Bytes` to borrow from the input buffer.

package/stacks/rust-wasm/skills/ct-rust-wasm-patterns/SKILL.md

@@ -66,6 +66,60 @@ pub struct User {
 
 Parse body: `let body: CreateUserRequest = req.json().await?;`
 
+## Performance
+
+> _Verified against worker-rs / wasm32-unknown-unknown (2026-06)._
+
+Two costs dominate on Workers: **.wasm size** (eats the startup CPU budget, the 10MB bundle limit, and worst-case cold starts) and the **JS<->WASM boundary** (large Request/Response bodies and serde payloads get *copied* across — not the cost of small calls, the cost of big bytes).
+
+### Binary size — the release profile does the heavy lifting
+
+Most size comes from the Rust build, not `wasm-opt`. In `Cargo.toml`:
+
+```toml
+[profile.release]
+opt-level = "z"      # "z" = smallest; try "s" — sometimes smaller AND faster, always measure
+lto = true           # cross-crate inlining + dead-code elimination
+codegen-units = 1    # better optimization, slower build
+strip = true         # drop symbols
+```
+
+Don't bother with `panic = "abort"` for size: `wasm32-unknown-unknown` already defaults to abort, so there are no unwind tables to drop. Modern `worker-build` recovers from panics automatically — a panicking request returns 500 and the instance reinitializes, no config needed. Keep `console_error_panic_hook` regardless — it surfaces the panic message in your logs.
+
+`worker-build` runs `wasm-opt` automatically before upload (a balanced `-O`, not `-Oz`) — no manual step. For size-aggressive optimization, opt into `-Oz` via the `wasm-opt` key in your Cargo package metadata.
+
+Targets: <1MB compressed is fine; smaller = leaner startup. Use `cargo bloat --release` to find the heavy deps before trimming.
+
+### Boundary — pass bulk data, don't re-copy it; and cut DB round-trips
+
+The boundary cost that bites is copying *large* payloads across JS<->WASM. Deserialize the body once (`req.json().await?`), not field-by-field, and don't shuttle the same buffer back and forth.
+
+Separately, cut **D1 round-trips** — these are network hops, not boundary copies, and they dominate latency. One call beats N:
+
+```rust
+// SLOW: one D1 round-trip per id
+for id in &ids {
+    db.prepare("SELECT * FROM users WHERE id=?1").bind(&[id.into()])?.first::<User>(None).await?;
+}
+
+// FAST: expand placeholders, bind every value, one round-trip
+let ph = (1..=ids.len()).map(|i| format!("?{i}")).collect::<Vec<_>>().join(",");
+let binds = ids.iter().map(|id| id.into()).collect::<Vec<_>>();
+let users = db.prepare(format!("SELECT * FROM users WHERE id IN ({ph})"))
+    .bind(&binds)?.all().await?.results::<User>()?;
+```
+
+For many independent statements in one hop, use `db.batch(vec![...])` (statements run sequentially in a single call).
+
+Hoist binding lookups out of loops — good hygiene, cheap to do:
+
+```rust
+let cfg = ctx.env.var("CONFIG")?.to_string();   // once, not per iteration
+for row in &rows { /* use cfg */ }
+```
+
+WASM wins on CPU-bound bulk work (parsing, crypto, number crunching) kept *inside* Rust. For trivial routing/string work the marshalling overhead can exceed the win — keep those paths thin.
+
 ## Anti-Patterns
 
 1. **Panics in production** -- Always `Result`, never `unwrap()`/`expect()`.
@@ -74,3 +128,11 @@ Parse body: `let body: CreateUserRequest = req.json().await?;`
 4. **Buffering large files** -- 128MB memory limit. Stream, don't buffer.
 5. **Raw SQL concatenation** -- Always `bind()` prepared statements.
 6. **Missing CORS** -- Handle OPTIONS preflight for API workers.
+7. **Cargo-culting `panic="abort"`** -- It's already the default on `wasm32-unknown-unknown` (no size win). Set the real size knobs (`opt-level="z"`, `lto=true`, `codegen-units=1`, `strip=true`); `worker-build` already auto-recovers from panics.
+8. **Chatty D1 calls** -- Per-row queries each cost a network round-trip. Collapse into one statement (expanded `IN` with bound params) or `db.batch(...)`.
+9. **WASM for trivial work** -- Boundary marshalling of small payloads can exceed the compute. Use WASM for bulk CPU work, not tiny string ops; keep large buffers from re-crossing.
+
+## See Also
+
+- `ct-cloudflare-d1-kv` — same D1 round-trip batching (`IN` + bound params, `db.batch()`), documented from the binding side.
+- `ct-protobuf-contracts` — decode once / `bytes` over `string`; generate `bytes` fields as `bytes::Bytes` for zero-copy.

package/stacks/solidjs/skills/ct-solidjs-patterns/SKILL.md

@@ -56,6 +56,65 @@ setState("user", "settings", "theme", "light");
 setState("items", items => [...items, newItem]);
 ```
 
+## Performance
+
+> _Verified against SolidJS 1.x (2026-06); 2.0 changes batching semantics._
+
+Solid is fast by default: no VDOM, no re-render cycle. Wins come from list keying, splitting bundles, and keeping the reactive graph narrow.
+
+### `<For>` vs `<Index>`
+
+| Use | When | Keyed by |
+|-----|------|----------|
+| `<For>` | array of objects; add/remove/reorder matters | item reference |
+| `<Index>` | primitives, or fixed slots where only the value changes (inputs, cells) | position |
+
+```tsx
+<For each={users()}>{(u) => <Row user={u} />}</For>        // identity matters
+<Index each={scores()}>{(s, i) => <Cell value={s()} />}</Index> // s is a SIGNAL: s(), i is a number
+```
+
+Wrong choice tears down and rebuilds rows on every change. Note the swap: `<For>` gives `(item, index())`, `<Index>` gives `(item(), index)`.
+
+### Code-split for cold-start
+
+Split at route/screen boundaries so the first screen isn't blocked by the whole app (critical under Capacitor).
+
+```tsx
+const Settings = lazy(() => import("./screens/Settings"));
+<Suspense fallback={<Spinner />}><Settings /></Suspense>  // createResource suspends here too
+```
+
+### Hot paths: `batch` + `untrack`
+
+Only writes inside a reactive computation (effect/memo) auto-batch. Writes from event handlers, timers, async callbacks, and resolved promises do NOT — wrap multiple writes in `batch()` (Solid 1.x; 2.0 will auto-batch everything).
+
+```tsx
+const onSave = () => batch(() => { setX(1); setY(2); });  // event handler: NOT auto-batched -> batch()
+setTimeout(() => batch(() => { setX(1); setY(2); }), 0);  // async/timer: one update, not two
+createEffect(() => { log(a()); untrack(() => b()); });    // subscribe to a, read b without subscribing
+```
+
+### Keep state granular
+
+```tsx
+// Whole-object signal: every reader re-runs on ANY field change (new ref = notify)
+const [user, setUser] = createSignal({ name, age });
+// Store: path update notifies only that path's dependents
+const [user, setUser] = createStore({ name, age });
+setUser("age", 31); // name readers untouched
+```
+
+Keep signals local; lift only what's truly shared.
+
+### Theme via attribute, not signal
+
+Driving theme through a signal+context re-evaluates every consumer on toggle. Use a data-attribute + CSS vars — zero reactive work:
+
+```tsx
+document.documentElement.dataset.theme = "dark"; // CSS: [data-theme="dark"] { --bg: #111 }
+```
+
 ## Anti-Patterns
 
 1. **Destructuring props** -- Breaks reactivity. Always `props.x`.
@@ -64,3 +123,14 @@ setState("items", items => [...items, newItem]);
 4. **Manual keys in For** -- `<For>` is keyed by reference automatically.
 5. **Signals outside reactive context** -- `count()` at top level captures once. Wrap in JSX or effects.
 6. **Forgetting to call signals** -- `count` is a getter, `count()` is the value.
+7. **`<Index>` for object lists / `<For>` for primitives** -- Mismatched keying rebuilds rows. Objects→`<For>`, primitives/slots→`<Index>`.
+8. **Theme/global toggles as signal+context** -- Re-evaluates all consumers. Use a `data-` attribute + CSS vars.
+9. **One signal holding a whole object** -- Any field change re-runs every reader. Use `createStore` for path-granular updates.
+10. **Eager-importing every screen** -- Blocks cold-start. `lazy()` + `<Suspense>` at route/screen boundaries.
+11. **Assuming event handlers auto-batch** -- They don't (Solid 1.x). Multiple writes in a handler/timer/async callback run dependents per-write; wrap them in `batch()`.
+
+## See Also
+
+- `ct-vanilla-extract-patterns` — theme via `data-theme`/class swap (not signals); logical properties for RTL.
+- `ct-i18n-typesafe` — defer locale loading behind a `createResource`-tracked `<Suspense>` (a bare `await` never trips Solid's boundary).
+- `ct-capacitor-ui` — `lazy()` + `<Suspense>` screen splitting is the main lever for mobile cold-start.

package/stacks/solidjs/stack.json

@@ -51,7 +51,8 @@
 				"ct-testing-patterns",
 				"ct-vite-vitest-patterns",
 				"ct-storybook-patterns",
-				"ct-playwright-patterns"
+				"ct-playwright-patterns",
+				"ct-i18n-typesafe"
 			]
 		}
 	}

package/stacks/storybook/skills/ct-storybook-patterns/SKILL.md

@@ -156,6 +156,58 @@ test("renders primary", () => {
 });
 ```
 
+## Performance
+
+> _Verified against Storybook 8/9/10 + Vitest browser mode (2026-06)._
+
+Browser-mode story tests are the slowest part of CI. Optimize for parallelism, lazy work, and caching.
+
+### Shard the Vitest run across CI jobs
+
+```bash
+# CI matrix: 4 jobs, each runs 1/4 of the story FILES (sharding is file-level)
+vitest run --project=storybook --shard=1/4 --reporter=blob   # job 1
+vitest run --project=storybook --shard=2/4 --reporter=blob   # job 2 ... etc.
+# final job merges results + coverage from all shards:
+vitest --merge-reports --reporter=junit --coverage
+```
+
+- `--project=storybook` skips the jsdom `unit` project when you only need stories.
+- Browser tests already run files in parallel (`fileParallelism` defaults on). Don't disable it.
+- `--reporter=blob` per shard + `--merge-reports` is required, or coverage is per-shard and incomplete.
+
+### Don't confuse `instances` with parallelism
+
+`browser.instances` runs the **same** test files across different browsers/setups -- each extra instance re-runs the whole suite. It is not a way to add CPU parallelism.
+
+```typescript
+browser: { enabled: true, headless: true, provider: playwright(),
+  instances: [{ browser: "chromium" }] },  // keep ONE for speed
+// Add instances only to cover more browsers (each re-runs everything).
+// Scale CPU via fileParallelism (within a job) + --shard (across CI jobs).
+```
+
+### Dev startup is already lazy
+
+On-demand story loading is automatic in modern Storybook (Vite builder, code-split: a story's code loads only when rendered). There is no flag to enable -- it's simply the default in Storybook 8/9/10 (the old `storyStoreV7` flag is gone).
+
+- Webpack's `lazyCompilation`/`fsCache` do **not** apply to the Vite builder; ignore that advice for this stack.
+- Don't defeat code-splitting with eager glob imports of all stories in custom config.
+
+### Keep stories cheap
+
+- Scope expensive setup **per-story**, not in `preview.ts` globals -- global decorators/loaders run for *every* story x every interaction test.
+- `mswLoader` and theme providers as globals are fine if light; move heavy data setup to `parameters` on the stories that need it.
+- Gate axe-core with `parameters.a11y.test` (`"error" | "todo" | "off"`), settable project -> component -> story (most specific wins). `test: "error"` globally runs the full ruleset on every story; downgrade or `"off"` where not needed, or run a11y in its own shard. (`tags` only include/exclude stories from a run -- they don't toggle a11y.)
+
+### Cache the Vite dep-prebundle between CI runs
+
+```yaml
+# Cache node_modules/.vite (Vite's default cacheDir), keyed on the lockfile.
+# This is the esbuild dependency pre-bundling cache used by dev / the browser-test run.
+# Note: it does NOT speed up `storybook build` (vite build ignores it).
+```
+
 ## Anti-Patterns
 
 1. **Destructuring SolidJS props in stories** -- Pass props via `args`; use `createJSXDecorator` for decorators.
@@ -164,3 +216,13 @@ test("renders primary", () => {
 4. **Skipping error/edge-case stories** -- Always include loading, error, empty, boundary states.
 5. **Using `@storybook/test-runner`** -- Use `@storybook/addon-vitest` instead.
 6. **Registering `sb.mock` in story files** -- Register in `.storybook/preview.ts` only.
+7. **Running the full story suite in one CI job** -- Use `vitest --shard=N/M` across matrix jobs (with `--reporter=blob` + `--merge-reports`).
+8. **Duplicating same-browser `instances` to "go faster"** -- Each instance re-runs the whole suite. Scale via `fileParallelism` + `--shard`; add instances only for more browsers.
+9. **Heavy decorators/loaders in `preview.ts`** -- Global setup runs per-story; scope expensive providers/data per-story.
+10. **`a11y: { test: "error" }` globally with no scoping** -- Axe runs the full ruleset per story; downgrade per story via `parameters.a11y.test` or use a dedicated a11y shard.
+11. **Discarding the Vite cache between CI runs** -- Persist `node_modules/.vite` keyed on the lockfile (dev / browser-test speedup; not `storybook build`).
+
+## See Also
+
+- `ct-testing-patterns` — the canonical cross-runner test-speed rule (file-level `--shard` + blob/merge-reports, parallelism).
+- `ct-vite-vitest-patterns` — owns the deep Vitest sharding/`--project`/cache config the browser-mode run inherits.

package/stacks/vanilla-extract/skills/ct-vanilla-extract-patterns/SKILL.md

@@ -67,6 +67,58 @@ const props = defineProperties({
 export const sprinkles = createSprinkles(props);
 ```
 
+## Performance
+
+> _Verified against vanilla-extract (2026-06)._
+
+Zero-runtime is the point: all classes/vars are extracted at build, the browser does the styling. Keep it that way — the wins below are about *bytes shipped* and *theme-swap cost*, not JS.
+
+### Theme swap = one attribute write, zero re-render
+
+`createTheme` returns a **class that only sets CSS custom properties**. Swapping themes is one DOM write; the cascade repaints — no component re-render, no JS restyle.
+
+```ts
+// createTheme(tokens) -> [class, contract]; createTheme(contract, tokens) -> class
+export const [themeClass, vars] = createTheme({ color: { bg: '#fff', text: '#111' } });
+export const dark = createTheme(vars, { color: { bg: '#111', text: '#eee' } }); // same contract, new values
+
+// runtime: flip the class on a root element — that's the entire cost
+root.className = isDark ? dark : themeClass;            // no setState, no re-render
+```
+
+Prefer the attribute path if you'd rather not own the class: register the theme on a selector at build time, then the runtime cost is a single `data-*` write.
+
+```ts
+// build time (.css.ts): bind a theme to a selector
+createGlobalTheme('[data-theme="dark"]', vars, { color: { bg: '#111', text: '#eee' } });
+// runtime: one attribute write, cascade does the rest
+document.documentElement.dataset.theme = 'dark';
+```
+
+`assignVars` is the *build-time* way to assign a whole contract in one shot inside a `style()`/`globalStyle()` `vars` block — handy for declaring a theme on a selector — not a runtime knob. Never put theme values in component state; let the CSS-variable cascade do it.
+
+### Sprinkles dedup — CSS grows with declarations, not components
+
+Each property-value(-condition) emits **one class, once**. 500 components calling `sprinkles({ padding: 'md' })` share a single class. Stylesheet size is bounded by `properties x values x conditions`, not usage. (Note: `style({ padding: vars.space.md })` does *not* dedupe across call sites — route high-frequency props through sprinkles to get the shared class.)
+
+```ts
+// good: high-frequency layout/spacing -> sprinkles (deduped)
+<div class={sprinkles({ display: 'flex', paddingInline: 'lg' })} />
+// reserve style() for genuine one-offs
+```
+
+Keep condition sets lean: every condition multiplies class count per property. A property with 6 values across 3 breakpoints = 18 classes.
+
+### Logical properties (also your RTL story)
+
+Author `paddingInline` / `marginInline` / `insetInlineStart` instead of `left`/`right`. One stylesheet flips for RTL via `dir="rtl"` — no duplicate LTR/RTL CSS, no runtime mirroring lib.
+
+| physical            | logical              |
+| ------------------- | -------------------- |
+| `paddingLeft/Right` | `paddingInline`      |
+| `marginTop/Bottom`  | `marginBlock`        |
+| `left` / `right`    | `insetInlineStart/End` |
+
 ## Anti-Patterns
 
 1. **Inline styles** -- Use `style()` or `sprinkles()`.
@@ -74,3 +126,13 @@ export const sprinkles = createSprinkles(props);
 3. **Overusing globalStyle** -- Prefer scoped `style()`. Reserve global for resets only.
 4. **Non-`.css.ts` files** -- Build plugin only processes `*.css.ts`.
 5. **Raw CSS variable strings** -- Use the `vars` object for type-safe references.
+6. **Theme in component state** — Re-renders the tree on toggle. Swap a class/`data-theme` on the root; the CSS-var cascade handles the rest with zero re-render.
+7. **Bespoke `style()` for common spacing/layout** — Defeats sprinkles dedup (`style()` doesn't merge identical declarations across call sites). Route high-frequency props through `sprinkles()`; one shared class instead of N.
+8. **Physical left/right** — Forces a second RTL stylesheet. Use logical `*Inline`/`*Block` props; one sheet flips with `dir="rtl"`.
+9. **Wide conditions x properties matrix** — Class count = properties x values x conditions. Trim breakpoints and property lists before they explode the CSS.
+
+## See Also
+
+- `ct-solidjs-patterns` — keep theme out of the reactive graph; swap a `data-theme` attribute, not a signal.
+- `ct-i18n-typesafe` — RTL = `dir` from locale (i18n) + logical properties (here).
+- `ct-capacitor-ui` — mobile webview: animate `transform`/`opacity` only; avoid `box-shadow`/`filter` on scrolled nodes.

package/stacks/vanilla-extract/stack.json

@@ -34,7 +34,7 @@
 					"createTheme\\("
 				]
 			},
-			"relatedSkills": ["ct-solidjs-patterns"]
+			"relatedSkills": ["ct-solidjs-patterns", "ct-i18n-typesafe"]
 		}
 	}
 }