claude-toolkit 0.1.27 → 0.10.0

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"]
 		}
 	}
 }

package/stacks/vite/skills/ct-vite-vitest-patterns/SKILL.md

@@ -470,6 +470,67 @@ The compat layer auto-converts old keys. New code should use the new keys.
 
 ---
 
+## Performance
+
+> _Verified against Vite 8 / Rolldown / Vitest 4 (2026-06)._
+
+### Dev Cold-Start & HMR: optimizeDeps
+
+Vite pre-bundles bare-import deps on first run, cached in `node_modules/.vite`. A missing entry triggers a mid-session "new dependency optimized, reloading" full reload -- the #1 HMR killer.
+
+```typescript
+optimizeDeps: {
+  include: ['lodash-es', 'pkg/cjs-only'], // force-bundle CJS / plugin-injected / lazy deps not auto-discovered
+  exclude: ['small-pure-esm-lib'],         // only small pure-ESM pkgs, or deps that break when bundled
+}
+```
+
+Do **not** `exclude` a large multi-file ESM dep (e.g. `lodash-es` ships 600+ modules) -- unbundled it floods the browser with parallel requests and slows page loads; keep it pre-bundled. Never `exclude` a CJS dep. If an excluded ESM dep has a nested CJS dep, add that nested dep to `include`.
+
+`vite --force` (or `rm -rf node_modules/.vite`) busts a stale cache. Pair with `server.warmup.clientFiles` (already covered).
+
+### Bundle Size: measure, then split
+
+```typescript
+import { visualizer } from 'rollup-plugin-visualizer' // ^7 for Vite 8 / Rolldown
+process.env.ANALYZE && visualizer({ gzipSize: true, brotliSize: true }) // ANALYZE=1 vite build
+```
+
+Read the gzip/brotli column to find oversized chunks. Route-level dynamic `import()` is the primary code-split. Use manual chunks only to isolate stable vendor deps. In Vite 8 / Rolldown the `manualChunks` object form is removed and the function form is deprecated -- use `rolldownOptions.output.codeSplitting` (the old `advancedChunks` key is a deprecated alias):
+
+```typescript
+build: { rolldownOptions: { output: {
+  codeSplitting: { groups: [{ name: 'vendor', test: /node_modules/ }] },
+} } }
+```
+
+### build.target & CSS
+
+Don't lower `target: 'baseline-widely-available'` without cause. A low target (`es2015`) makes Oxc down-level async/await, optional chaining, and spread into verbose helpers -- bigger bundles, slower transforms. Match real browser support.
+
+```typescript
+css: { transformer: 'lightningcss' }, // experimental: faster + smaller than the postcss default
+```
+
+`build.cssMinify` already defaults to `'lightningcss'` in Vite 8 -- no action needed for minification; the opt-in above is only for the CSS *transformer*.
+
+### Vitest Run Speed: pool & isolate
+
+`isolate: true` (default) builds a fresh environment per test file -- safe but slow. Disabling it is often the single biggest speedup for pure-logic suites.
+
+| Goal | Setting |
+|---|---|
+| Safe default (global mutation, `process.env`, fake timers) | `pool: 'forks'`, `isolate: true` |
+| Fastest, pure side-effect-free Node logic | `pool: 'threads'`, `isolate: false` |
+| Fast jsdom (leaks globals -- verify) | `pool: 'vmThreads'` (isolation can't be disabled) |
+| Debug a flaky/order-dependent test | `--no-file-parallelism` or `poolOptions.threads.singleThread` |
+
+```typescript
+test: { pool: 'threads', isolate: false } // big speedup for logic suites; leaks global state between files
+```
+
+> `pool: 'forks'` and `isolate: true` are the Vitest defaults. Gains from `threads` show mostly in larger suites; `forks` stays safer for native-module / segfault-prone tests.
+
 ## Anti-Patterns
 
 ### Vite
@@ -479,6 +540,10 @@ The compat layer auto-converts old keys. New code should use the new keys.
 3. **Duplicating resolve config for tests** -- Vitest inherits Vite's aliases and plugins. Don't redeclare.
 4. **Using `rollupOptions` in Vite 8** -- Works via compat but generates warnings. Use `rolldownOptions`.
 5. **Not externalizing peer deps in library mode** -- Bundling framework deps causes duplicate instances.
+6. **Lowering `build.target` by habit** -- Down-levels modern syntax into helper bloat and slows transforms. Set it to your actual browser support.
+7. **Tuning chunks without measuring** -- Run `ANALYZE=1 vite build` with `visualizer` first. Over-grouping into manual chunks defeats per-route lazy loading and cache granularity.
+8. **`optimizeDeps.exclude` on large ESM deps** -- Unbundling a multi-file ESM package floods the browser with requests. Exclude only small pure-ESM or bundle-breaking deps.
+9. **Ignoring the "new dependency optimized, reloading" warning** -- A dep escaped pre-bundle discovery. Add it to `optimizeDeps.include` to stop full reloads.
 
 ### Vitest
 
@@ -490,3 +555,9 @@ The compat layer auto-converts old keys. New code should use the new keys.
 6. **Snapshot-only testing** -- Snapshots catch regressions but don't verify correctness. Add explicit assertions.
 7. **Global jsdom environment** -- Use `test.projects` to run DOM tests in jsdom and logic tests in node.
 8. **Using `vi.spyOn` in browser mode** -- Use `vi.mock('./module', { spy: true })` instead.
+9. **Leaving `isolate: true` on pure-logic suites** -- A large run-speed cost. Set `isolate: false` + `pool: 'threads'` for side-effect-free tests; keep `forks` + `isolate: true` where global/env mutation needs isolation.
+
+## See Also
+
+- `ct-testing-patterns` — the canonical cross-runner test-speed rule (parallelism, file-level `--shard` + blob/merge-reports, isolate trade-off).
+- `ct-solidjs-patterns` — `lazy()` route/screen code-splitting relies on Vite's dynamic-import chunking.