claude-toolkit 0.1.25 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 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
+
+## 0.1.26 (2026-06-01)
+
+- docs: document update command in README CLI commands table
+
 ## 0.1.25 (2026-06-01)
 
 - feat: add update command to sync detected stacks into existing config

package/README.md

@@ -45,11 +45,12 @@ export default defineConfig({
 
 ## CLI Commands
 
-| Command                    | Description                                              |
-| -------------------------- | -------------------------------------------------------- |
-| `bunx claude-toolkit init` | Scaffold config file and generate `.claude/`             |
-| `bunx claude-toolkit sync` | Regenerate `.claude/` from config (after toolkit update) |
-| `bunx claude-toolkit help` | Show available commands                                  |
+| Command                      | Description                                          |
+| ---------------------------- | ---------------------------------------------------- |
+| `bunx claude-toolkit init`   | Scaffold config and generate `.claude/` (first run)  |
+| `bunx claude-toolkit update` | Add newly detected stacks to config, then regenerate |
+| `bunx claude-toolkit sync`   | Regenerate `.claude/` from the current config        |
+| `bunx claude-toolkit help`   | Show available commands                              |
 
 ## Stack Auto-Detection
 
@@ -108,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.25",
+	"version": "0.9.0",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {

package/src/detect.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { StackName } from "./types.js";
 
@@ -11,15 +11,51 @@ export interface DetectedStack {
 interface PackageJson {
 	dependencies?: Record<string, string>;
 	devDependencies?: Record<string, string>;
+	workspaces?: string[] | { packages?: string[] };
+}
+
+/** A directory to inspect for stack markers, with its project-relative label */
+interface ScanRoot {
+	/** Absolute path */
+	dir: string;
+	/** Project-relative path ("." for the project root) */
+	rel: string;
+}
+
+/** Pre-resolved view of the project: every package and directory worth scanning */
+interface DetectContext {
+	projectDir: string;
+	/** Package.json files found at the root and across workspaces/subdirs */
+	packages: { rel: string; pkg: PackageJson }[];
+	/** Directories to check for marker files (root + subdirs + workspace packages) */
+	scanRoots: ScanRoot[];
 }
 
 interface StackDetector {
 	name: StackName;
-	detect: (projectDir: string, pkg: PackageJson | null) => DetectedStack | null;
+	detect: (ctx: DetectContext) => DetectedStack | null;
 }
 
-function loadPackageJson(projectDir: string): PackageJson | null {
-	const pkgPath = join(projectDir, "package.json");
+/** Directories never worth scanning into */
+const IGNORE_DIRS = new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"out",
+	"target",
+	"coverage",
+	".git",
+	".wrangler",
+	".next",
+	".cache",
+	".vercel",
+	".turbo",
+	"playwright-report",
+	"test-results",
+]);
+
+function readPackageJson(dir: string): PackageJson | null {
+	const pkgPath = join(dir, "package.json");
 	if (!existsSync(pkgPath)) return null;
 	try {
 		return JSON.parse(readFileSync(pkgPath, "utf-8")) as PackageJson;
@@ -28,19 +64,112 @@ function loadPackageJson(projectDir: string): PackageJson | null {
 	}
 }
 
-function hasDep(pkg: PackageJson | null, name: string): boolean {
-	if (!pkg) return false;
+/** Immediate, non-ignored subdirectory names of a directory */
+function listSubdirs(dir: string): string[] {
+	try {
+		return readdirSync(dir, { withFileTypes: true })
+			.filter((e) => e.isDirectory() && !IGNORE_DIRS.has(e.name) && !e.name.startsWith("."))
+			.map((e) => e.name);
+	} catch {
+		return [];
+	}
+}
+
+/** Resolve workspace package directories (project-relative) from the root package.json */
+function resolveWorkspaceDirs(projectDir: string, rootPkg: PackageJson | null): string[] {
+	const ws = rootPkg?.workspaces;
+	const patterns = Array.isArray(ws) ? ws : (ws?.packages ?? []);
+	const dirs: string[] = [];
+	for (const pattern of patterns) {
+		if (pattern.includes("*")) {
+			// Resolve a glob like "packages/*" or "apps/*" to concrete package dirs
+			const glob = new Bun.Glob(`${pattern}/package.json`);
+			for (const match of glob.scanSync({ cwd: projectDir, onlyFiles: true })) {
+				dirs.push(match.replace(/[/\\]package\.json$/, "").replace(/\\/g, "/"));
+			}
+		} else {
+			dirs.push(pattern.replace(/\\/g, "/"));
+		}
+	}
+	return dirs;
+}
+
+/** Build the set of directories and package.json files worth inspecting */
+function buildContext(projectDir: string): DetectContext {
+	const rootPkg = readPackageJson(projectDir);
+
+	// Root + immediate subdirs + workspace packages (deduped)
+	const rels = new Set<string>(["."]);
+	for (const name of listSubdirs(projectDir)) rels.add(name);
+	for (const dir of resolveWorkspaceDirs(projectDir, rootPkg)) rels.add(dir);
+
+	const scanRoots: ScanRoot[] = [...rels].map((rel) => ({
+		rel,
+		dir: rel === "." ? projectDir : join(projectDir, rel),
+	}));
+
+	const packages: { rel: string; pkg: PackageJson }[] = [];
+	for (const { rel, dir } of scanRoots) {
+		const pkg = rel === "." ? rootPkg : readPackageJson(dir);
+		if (pkg) packages.push({ rel, pkg });
+	}
+
+	return { projectDir, packages, scanRoots };
+}
+
+function pkgHasDep(pkg: PackageJson, name: string): boolean {
 	return name in (pkg.dependencies ?? {}) || name in (pkg.devDependencies ?? {});
 }
 
-function fileExists(projectDir: string, ...segments: string[]): boolean {
-	return existsSync(join(projectDir, ...segments));
+function pkgLabel(rel: string): string {
+	return rel === "." ? "root package.json" : `${rel}/package.json`;
 }
 
-function rootConfigExists(projectDir: string, prefix: string): string | null {
-	const glob = new Bun.Glob(`${prefix}.*`);
-	for (const match of glob.scanSync({ cwd: projectDir, onlyFiles: true })) {
-		return match;
+function relPath(rel: string, name: string): string {
+	return rel === "." ? name : `${rel}/${name}`;
+}
+
+/** First package (project-relative dir) declaring `name`, or null */
+function findDep(ctx: DetectContext, name: string): string | null {
+	for (const { rel, pkg } of ctx.packages) {
+		if (pkgHasDep(pkg, name)) return rel;
+	}
+	return null;
+}
+
+/** First scan root containing a file/dir named `name` (top-level only), as a project-relative path */
+function findFile(ctx: DetectContext, name: string): string | null {
+	for (const { rel, dir } of ctx.scanRoots) {
+		if (existsSync(join(dir, name))) return relPath(rel, name);
+	}
+	return null;
+}
+
+/** First scan root containing a `${prefix}.*` config file (top-level only) */
+function findConfig(ctx: DetectContext, prefix: string): string | null {
+	for (const { rel, dir } of ctx.scanRoots) {
+		const glob = new Bun.Glob(`${prefix}.*`);
+		for (const match of glob.scanSync({ cwd: dir, onlyFiles: true })) {
+			return relPath(rel, match);
+		}
+	}
+	return null;
+}
+
+/** Look for `*.proto` files directly in scan roots or under a conventional `proto/` dir */
+function findProtoFiles(ctx: DetectContext): string | null {
+	for (const { rel, dir } of ctx.scanRoots) {
+		const direct = new Bun.Glob("*.proto");
+		for (const match of direct.scanSync({ cwd: dir, onlyFiles: true })) {
+			return relPath(rel, match);
+		}
+		const protoDir = join(dir, "proto");
+		if (existsSync(protoDir)) {
+			const nested = new Bun.Glob("**/*.proto");
+			for (const match of nested.scanSync({ cwd: protoDir, onlyFiles: true })) {
+				return relPath(rel, `proto/${match}`);
+			}
+		}
 	}
 	return null;
 }
@@ -48,104 +177,108 @@ function rootConfigExists(projectDir: string, prefix: string): string | null {
 const DETECTORS: StackDetector[] = [
 	{
 		name: "solidjs",
-		detect: (_dir, pkg) =>
-			hasDep(pkg, "solid-js")
-				? { name: "solidjs", reason: "found solid-js in dependencies" }
-				: null,
+		detect: (ctx) => {
+			const at = findDep(ctx, "solid-js");
+			return at ? { name: "solidjs", reason: `found solid-js in ${pkgLabel(at)}` } : null;
+		},
 	},
 	{
 		name: "vite",
-		detect: (dir, pkg) => {
-			if (hasDep(pkg, "vite")) return { name: "vite", reason: "found vite in dependencies" };
-			const viteConfig = rootConfigExists(dir, "vite.config");
-			if (viteConfig) return { name: "vite", reason: `found ${viteConfig}` };
-			const vitestConfig = rootConfigExists(dir, "vitest.config");
-			if (vitestConfig) return { name: "vite", reason: `found ${vitestConfig}` };
-			return null;
+		detect: (ctx) => {
+			const dep = findDep(ctx, "vite");
+			if (dep) return { name: "vite", reason: `found vite in ${pkgLabel(dep)}` };
+			const config = findConfig(ctx, "vite.config") ?? findConfig(ctx, "vitest.config");
+			return config ? { name: "vite", reason: `found ${config}` } : null;
 		},
 	},
 	{
 		name: "vanilla-extract",
-		detect: (_dir, pkg) =>
-			hasDep(pkg, "@vanilla-extract/css")
-				? { name: "vanilla-extract", reason: "found @vanilla-extract/css in dependencies" }
-				: null,
+		detect: (ctx) => {
+			const at = findDep(ctx, "@vanilla-extract/css");
+			return at
+				? { name: "vanilla-extract", reason: `found @vanilla-extract/css in ${pkgLabel(at)}` }
+				: null;
+		},
 	},
 	{
 		name: "rust-wasm",
-		detect: (dir) =>
-			fileExists(dir, "Cargo.toml") ? { name: "rust-wasm", reason: "found Cargo.toml" } : null,
+		detect: (ctx) => {
+			const f = findFile(ctx, "Cargo.toml");
+			return f ? { name: "rust-wasm", reason: `found ${f}` } : null;
+		},
 	},
 	{
 		name: "protobuf",
-		detect: (dir) => {
-			if (fileExists(dir, "buf.yaml")) return { name: "protobuf", reason: "found buf.yaml" };
-			if (fileExists(dir, "buf.gen.yaml"))
-				return { name: "protobuf", reason: "found buf.gen.yaml" };
-			const glob = new Bun.Glob("**/*.proto");
-			for (const _match of glob.scanSync({ cwd: dir, onlyFiles: true })) {
-				return { name: "protobuf", reason: "found .proto files" };
-			}
-			return null;
+		detect: (ctx) => {
+			const buf =
+				findFile(ctx, "buf.yaml") ??
+				findFile(ctx, "buf.gen.yaml") ??
+				findFile(ctx, "buf.work.yaml");
+			if (buf) return { name: "protobuf", reason: `found ${buf}` };
+			const proto = findProtoFiles(ctx);
+			return proto ? { name: "protobuf", reason: `found ${proto}` } : null;
 		},
 	},
 	{
 		name: "cloudflare",
-		detect: (dir) => {
-			if (fileExists(dir, "wrangler.toml"))
-				return { name: "cloudflare", reason: "found wrangler.toml" };
-			if (fileExists(dir, "wrangler.jsonc"))
-				return { name: "cloudflare", reason: "found wrangler.jsonc" };
-			return null;
+		detect: (ctx) => {
+			const f =
+				findFile(ctx, "wrangler.toml") ??
+				findFile(ctx, "wrangler.jsonc") ??
+				findFile(ctx, "wrangler.json");
+			return f ? { name: "cloudflare", reason: `found ${f}` } : null;
 		},
 	},
 	{
 		name: "i18n-typesafe",
-		detect: (_dir, pkg) =>
-			hasDep(pkg, "typesafe-i18n")
-				? { name: "i18n-typesafe", reason: "found typesafe-i18n in dependencies" }
-				: null,
+		detect: (ctx) => {
+			const at = findDep(ctx, "typesafe-i18n");
+			if (at) return { name: "i18n-typesafe", reason: `found typesafe-i18n in ${pkgLabel(at)}` };
+			const f = findFile(ctx, ".typesafe-i18n.json");
+			return f ? { name: "i18n-typesafe", reason: `found ${f}` } : null;
+		},
 	},
 	{
 		name: "playwright",
-		detect: (dir, pkg) => {
-			if (hasDep(pkg, "@playwright/test"))
-				return { name: "playwright", reason: "found @playwright/test in dependencies" };
-			const config = rootConfigExists(dir, "playwright.config");
-			if (config) return { name: "playwright", reason: `found ${config}` };
-			return null;
+		detect: (ctx) => {
+			const dep = findDep(ctx, "@playwright/test");
+			if (dep) return { name: "playwright", reason: `found @playwright/test in ${pkgLabel(dep)}` };
+			const config = findConfig(ctx, "playwright.config");
+			return config ? { name: "playwright", reason: `found ${config}` } : null;
 		},
 	},
 	{
 		name: "storybook",
-		detect: (dir, pkg) => {
-			if (hasDep(pkg, "storybook"))
-				return { name: "storybook", reason: "found storybook in dependencies" };
-			if (fileExists(dir, ".storybook"))
-				return { name: "storybook", reason: "found .storybook/ directory" };
-			return null;
+		detect: (ctx) => {
+			const dep = findDep(ctx, "storybook");
+			if (dep) return { name: "storybook", reason: `found storybook in ${pkgLabel(dep)}` };
+			const dir = findFile(ctx, ".storybook");
+			return dir ? { name: "storybook", reason: `found ${dir}/ directory` } : null;
 		},
 	},
 	{
 		name: "capacitor",
-		detect: (dir, pkg) => {
-			if (hasDep(pkg, "@capgo/capacitor-updater"))
-				return { name: "capacitor", reason: "found @capgo/capacitor-updater in dependencies" };
-			if (hasDep(pkg, "@capacitor/core"))
-				return { name: "capacitor", reason: "found @capacitor/core in dependencies" };
-			const config = rootConfigExists(dir, "capacitor.config");
-			if (config) return { name: "capacitor", reason: `found ${config}` };
-			return null;
+		detect: (ctx) => {
+			const capgo = findDep(ctx, "@capgo/capacitor-updater");
+			if (capgo)
+				return {
+					name: "capacitor",
+					reason: `found @capgo/capacitor-updater in ${pkgLabel(capgo)}`,
+				};
+			const core = findDep(ctx, "@capacitor/core");
+			if (core) return { name: "capacitor", reason: `found @capacitor/core in ${pkgLabel(core)}` };
+			const config = findConfig(ctx, "capacitor.config");
+			return config ? { name: "capacitor", reason: `found ${config}` } : null;
 		},
 	},
 ];
 
-/** Scan a project directory and detect which stacks are present */
+/** Scan a project directory (root + subdirs + workspace packages) and detect which stacks are present */
 export function detectStacks(projectDir: string): DetectedStack[] {
-	const pkg = loadPackageJson(projectDir);
+	const ctx = buildContext(projectDir);
 	const detected: DetectedStack[] = [];
 	for (const detector of DETECTORS) {
-		const result = detector.detect(projectDir, pkg);
+		const result = detector.detect(ctx);
 		if (result) detected.push(result);
 	}
 	return detected;

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