claude-toolkit 0.1.27 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.9.0 (2026-06-08)
+
+Re-baselined from 0.1.x to reflect accumulated scope: 10 stack connectors, the full `init`/`update`/`sync` CLI, stack auto-detection with drift and monorepo/workspace support, and a complete skill/command/agent/hook system. Versioning is now conventional-commit-driven from this release onward.
+
+- feat: render/runtime-speed guidance across every stack skill, each paired with a security guardrail
+- feat: new `ct-capacitor-ui` skill for webview performance and native feel
+- feat: canonical test-speed rule in core testing skill + cross-stack `relatedSkills` wiring
+- build: conventional-commit-aware versioning (feat→minor, fix/perf→patch, breaking→major)
+- ci: automated npm publish on GitHub release
+
+## 0.1.33 (2026-06-07)
+
+- chore: apply biome formatting to skill-eval hook
+
+## 0.1.32 (2026-06-07)
+
+- feat: add ct-capacitor-ui skill for webview performance and native feel
+
+## 0.1.31 (2026-06-07)
+
+- feat: add i18n performance guidance and wire relatedSkills to solidjs/vanilla-extract
+
+## 0.1.30 (2026-06-07)
+
+- feat: add test-speed guidance to vite, playwright, storybook, and core testing skill
+
+## 0.1.29 (2026-06-07)
+
+- feat: add performance guidance to cloudflare, rust-wasm, and protobuf skills
+
+## 0.1.28 (2026-06-07)
+
+- feat: add render-speed guidance to solidjs and vanilla-extract skills
+
 ## 0.1.27 (2026-06-01)
 
 - feat: detect stacks across workspace packages and monorepo subdirectories

package/README.md

@@ -109,7 +109,7 @@ This keeps your config aligned as your project evolves — `init` for first-time
 | `i18n-typesafe`   | typesafe-i18n internationalization                                 |
 | `playwright`      | Playwright E2E testing, Page Objects, fixtures, CI/CD              |
 | `storybook`       | Storybook interaction testing, CSF 3, visual regression            |
-| `capacitor`       | Capacitor 8 native runtime, Capgo OTA live updates, channels       |
+| `capacitor`       | Capacitor 8 runtime, Capgo OTA, channels; webview UI & native feel |
 
 ## Core Features (always included)
 

package/core/hooks/skill-eval.js

@@ -129,14 +129,7 @@ function matchDirectoryMapping(filePath, mappings) {
 /**
  * Evaluate a single skill against the prompt and context
  */
-function evaluateSkill(
-	skillName,
-	skill,
-	prompt,
-	promptLower,
-	filePaths,
-	rules,
-) {
+function evaluateSkill(skillName, skill, prompt, promptLower, filePaths, rules) {
 	const { triggers = {}, excludePatterns = [], priority = 5 } = skill;
 	const scoring = rules.scoring;
 
@@ -207,10 +200,7 @@ function evaluateSkill(
 	// 6. Check directory mappings
 	if (rules.directoryMappings && filePaths.length > 0) {
 		for (const filePath of filePaths) {
-			const mappedSkill = matchDirectoryMapping(
-				filePath,
-				rules.directoryMappings,
-			);
+			const mappedSkill = matchDirectoryMapping(filePath, rules.directoryMappings);
 			if (mappedSkill === skillName) {
 				score += scoring.directoryMatch;
 				reasons.push(`directory mapping`);
@@ -279,14 +269,7 @@ function evaluate(prompt) {
 
 	const matches = [];
 	for (const [name, skill] of Object.entries(skills)) {
-		const match = evaluateSkill(
-			name,
-			skill,
-			prompt,
-			promptLower,
-			filePaths,
-			rules,
-		);
+		const match = evaluateSkill(name, skill, prompt, promptLower, filePaths, rules);
 		if (match && match.score >= config.minConfidenceScore) {
 			matches.push(match);
 		}

package/core/skills/ct-testing-patterns/SKILL.md

@@ -107,6 +107,18 @@ Bun supports `describe`, `it`/`test`, `expect`, lifecycle hooks, and snapshot te
 
 See 3-Layer Testing Strategy above. Many unit tests (fast, focused) > some interaction tests (component sandbox) > few E2E tests (full flow). Aim for 70/20/10 distribution.
 
+## Test Speed
+
+Three levers recur across every runner (Vitest, Playwright, Storybook browser mode). Stated once here; each stack skill carries the framework-specific syntax.
+
+- **Parallelism sized to the runner.** Enable file-level parallelism (Vitest `fileParallelism`, Playwright `fullyParallel`), but cap workers to the runner's *real* vCPUs (`"50%"` or a measured count). GitHub standard runners are 2 vCPU (private) / 4 (public); oversubscribing thrashes.
+- **Shard across CI jobs, then merge the blob reports.** Sharding splits at the *file* level (`--shard=i/n`), so wall-clock is gated by the slowest shard -- balance file sizes. Always emit a blob report per shard (`--reporter=blob`) and merge it (`merge-reports` / `--merge-reports`) in a dependent job, or results and coverage are fragmented and incomplete.
+- **Skip isolation where state is clean.** Per-file environment isolation is the safe default but the biggest run-speed cost. Disable it (Vitest `isolate: false`, `pool: 'threads'`) only for side-effect-free logic suites; keep it where tests mutate globals/env/timers.
+
+Profile before tuning, and never `sleep` to mask timing -- use the framework's auto-waiting (see Shared Principles).
+
+Per-runner config: `ct-vite-vitest-patterns`, `ct-playwright-patterns`, `ct-storybook-patterns`.
+
 ## Anti-Patterns
 
 1. **Testing implementation** -- Asserting internal state or call counts breaks on refactors.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.1.27",
+	"version": "0.9.0",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {

package/stacks/capacitor/skills/ct-capacitor-ota/SKILL.md

@@ -39,6 +39,21 @@ CapacitorUpdater.notifyAppReady();
 
 This is the safety net that makes OTA reversible. A bundle that white-screens never sticks.
 
+### Boot ordering: splash vs notifyAppReady
+
+A freshly-applied OTA bundle re-runs your bootstrap. Hide the splash *after* the first real view paints, or users see a white webview between hide and first render. Requires `launchAutoHide: false` (otherwise the OS hides the splash on its own schedule and you can't sequence it).
+
+```typescript
+// capacitor.config.ts → plugins.SplashScreen.launchAutoHide: false
+import { SplashScreen } from "@capacitor/splash-screen";
+
+CapacitorUpdater.notifyAppReady();   // fire-and-forget — never gate first paint on it
+await firstMeaningfulView();         // await your app's first real paint
+await SplashScreen.hide();           // only now reveal the webview
+```
+
+`notifyAppReady()` returns a Promise but the 10s `appReadyTimeout` is generous — call it early and move on; do not `await` it before painting. (Webview rendering performance and native feel live in `ct-capacitor-ui`.)
+
 ## Configuration
 
 ```typescript
@@ -176,3 +191,4 @@ OTA of JS/HTML/CSS is allowed: **Apple** developer agreement §3.3.2 (since iOS
 - `ct-vite-vitest-patterns` — the build that produces `webDir`
 - `ct-playwright-patterns` — E2E-verify a bundle before you upload it
 - `ct-typescript-conventions` — typing `capacitor.config.ts` and the updater API
+- `ct-capacitor-ui` — webview UI performance & native feel (safe areas, touch targets, compositor-only animation)

package/stacks/capacitor/skills/ct-capacitor-ui/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ct-capacitor-ui
+description: Capacitor webview UI performance and native feel — safe areas, touch targets, tap feedback, compositor-only animation, and on-device profiling
+---
+
+# Capacitor Webview UI & Native Feel
+
+> _Verified against Capacitor 8 (iOS 15 floor; `content-visibility` on iOS 18+) (2026-06)._
+
+The webview *is* the runtime. A Capacitor app lives or dies on whether it feels native — safe-area-aware, instant to tap, smooth to scroll — on a low-end phone, not on your desktop. This skill is the UI/runtime side; OTA delivery lives in `ct-capacitor-ota`.
+
+## Performance & Native Feel
+
+The webview *is* the runtime — budget like a low-end Android phone, not desktop Chrome. Profile on a real cheap device or throttled emulation (4x CPU, "Slow 4G"); effects that are free on a desktop GPU jank in WebView.
+
+```html
+<!-- index.html — required for env() safe-area tokens to resolve to non-zero -->
+<meta name="viewport"
+      content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
+`width=device-width` (above) already removes the legacy ~300ms tap delay on modern iOS/Android WebViews. The block below is about *tap feel*, not latency:
+
+```css
+/* No grey tap-flash; suppress double-tap-to-zoom pause on controls */
+* { -webkit-tap-highlight-color: transparent; }
+button, a, [role="button"], input, label { touch-action: manipulation; }
+
+/* If you kill the default highlight, give back your OWN press feedback —
+   otherwise buttons feel dead. */
+button:active, [role="button"]:active { opacity: 0.7; }
+:focus-visible { outline: 2px solid; outline-offset: 2px; }
+```
+
+```css
+/* Respect notch / home indicator — paint edge-to-edge, pad with env() */
+.app-header { padding-top: env(safe-area-inset-top); }
+.app-footer { padding-bottom: env(safe-area-inset-bottom); }
+
+/* Native scroll feel */
+:where(html, body) { overscroll-behavior: none; }   /* no rubber-band on the shell */
+.scroll-region { overflow-y: auto; overscroll-behavior: contain; }
+```
+
+| Concern       | Do                                                              | Why                                              |
+| ------------- | -------------------------------------------------------------- | ------------------------------------------------ |
+| Touch targets | min 44x44px (iOS) / 48dp (Android)                             | HIG / Material minimum; fewer mis-taps           |
+| Animation     | animate `transform` / `opacity` only                          | compositor-only; skips layout & paint            |
+| Long lists    | `content-visibility: auto` + `contain-intrinsic-size`         | skips offscreen layout on Android & iOS 18+ WebView; older iOS ignores it (harmless). Need it everywhere → use a JS virtualizer |
+| Scroll jank   | avoid `box-shadow` / `filter` / `backdrop-filter` on scrolled nodes | repaint per frame on low-end GPUs           |
+
+Keep the webview locked down regardless of perf work: tight `server.allowNavigation`, no loading remote origins into the shell, and web debugging off in production builds.
+
+## Anti-Patterns
+
+1. **Profiling only in desktop Chrome** — desktop GPU hides jank that cripples low-end Android WebView. Test on a real cheap device or throttled emulation.
+2. **Omitting `viewport-fit=cover`** — `env(safe-area-inset-*)` resolves to 0; content slides under the notch / home indicator and looks like a wrapped website.
+3. **Killing `-webkit-tap-highlight-color` without a replacement press state** — buttons feel dead (no touch acknowledgement). Remove the grey flash *and* add your own `:active` / `:focus-visible` feedback. (Note: the legacy 300ms delay is already gone on modern WebViews via `width=device-width`; `touch-action: manipulation` only suppresses the double-tap-zoom pause.)
+4. **Animating `top` / `left` / `width` or shadows on scroll** — forces layout/paint each frame; use `transform` / `opacity`.
+
+## See Also
+
+- `ct-capacitor-ota` — OTA delivery, channels, `notifyAppReady`, and the splash/boot-ordering note.
+- `ct-solidjs-patterns` — `lazy()` + `<Suspense>` screen splitting protects webview cold-start.
+- `ct-vanilla-extract-patterns` — author the safe-area / logical-property styles; animate `transform`/`opacity` only.
+- `ct-i18n-typesafe` — defer locale loading so first paint isn't blocked.

package/stacks/capacitor/stack.json

@@ -57,7 +57,53 @@
 			"relatedSkills": [
 				"ct-vite-vitest-patterns",
 				"ct-playwright-patterns",
-				"ct-typescript-conventions"
+				"ct-typescript-conventions",
+				"ct-capacitor-ui"
+			]
+		},
+		"ct-capacitor-ui": {
+			"description": "Capacitor webview UI performance and native feel: safe areas, touch targets, tap feedback, compositor-only animation, on-device profiling",
+			"priority": 7,
+			"triggers": {
+				"keywords": [
+					"safe area",
+					"safe-area",
+					"viewport",
+					"touch target",
+					"tap highlight",
+					"native feel",
+					"splash",
+					"overscroll",
+					"notch",
+					"home indicator",
+					"webview"
+				],
+				"keywordPatterns": [
+					"\\bsafe-area\\b",
+					"\\bviewport-fit\\b",
+					"\\btouch-action\\b",
+					"\\boverscroll\\b"
+				],
+				"pathPatterns": ["**/index.html"],
+				"intentPatterns": [
+					"(?:safe area|notch|home indicator)",
+					"(?:native feel|touch target|tap feedback)",
+					"(?:scroll|animation).*(?:jank|smooth|perf)"
+				],
+				"contentPatterns": [
+					"safe-area-inset",
+					"viewport-fit",
+					"touch-action",
+					"-webkit-tap-highlight-color",
+					"overscroll-behavior",
+					"content-visibility"
+				]
+			},
+			"relatedSkills": [
+				"ct-capacitor-ota",
+				"ct-solidjs-patterns",
+				"ct-vanilla-extract-patterns",
+				"ct-i18n-typesafe"
 			]
 		}
 	}

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

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.