create-obsidian-arrow 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-obsidian-arrow",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Scaffold an Obsidian-styled Arrow.js UI sandbox (pnpm create obsidian-arrow <dir>).",
   "type": "module",
   "bin": {

package/template/AGENTS.md

@@ -11,6 +11,7 @@ This file is the hub — everything else is linked from here:
 - [`docs/workflow.md`](docs/workflow.md) — fresh-machine → running workflow.
 - [`skills/`](skills/) — installable domain skills (`pnpm skills:install`):
   - `obsidian-arrow-sandbox` — running the sandbox, CSS scoping, porting basics.
+  - `obsidian-arrow-composition` — **run before designing any view area**: surveys codebase, shows file trees for confirmation, asks questions, checks DRY/primitive use, produces a locked hierarchy doc.
   - `obsidian-arrow-stories` — **component + story authoring workflow**: `defineStories` API, variants, children, status flag, DRY patterns, utilities.
   - `obsidian-arrow-css` — **CSS decision hierarchy**: Obsidian classes → oas-* utilities → custom CSS; token reference; specificity scoping; overrides via variables; auditing for excess CSS.
   - `arrow-js-obsidian-templates` — Arrow v1.0.6 template syntax + footguns.
@@ -84,19 +85,39 @@ in `boundary()`.
 
 ## Conventions
 
-- **Check `/reference/classes` first** — Obsidian has semantic classes for most
-  common patterns. Use them before writing any custom CSS.
-- **Use `oas-*` utilities second** (`src/utilities.css`) — flex, gap, padding,
-  margin, typography, border, overflow helpers built on Obsidian's token scale.
-  Prefer `class="oas-flex oas-gap-2"` over `style="display:flex;gap:8px"`.
-- **Custom CSS last** — only when Obsidian has no class and utilities don't cover
-  it. Scope under container + element type, use `var(--…)` tokens for values.
-- Add a story by creating `stories/MyThing.stories.ts` — stories live in the
-  top-level `stories/` directory (not in `src/`). Import via
-  `"../tools/viewer/stories"` and `"../src/components/MyThing"`. See the
-  `obsidian-arrow-stories` skill for the full `defineStories` API (variants,
-  children, status, notes). Browse live tokens at `/reference`, curated classes
-  at `/reference/classes`.
+- **Check `/reference/classes` first** — Obsidian has semantic classes for most patterns.
+- **Use `oas-*` utilities second** (`src/utilities.css`) — flex, gap, padding, etc.
+- **Custom CSS last** — co-locate as `ComponentName.css`, import it from `ComponentName.ts`.
+
+### Directory structure
+
+- `src/views/<ViewName>/` — full-pane components mounted from `ItemView.onOpen()`. Named `*View.ts` or `*Panel.ts`. May have CSS, state.ts, and view-specific sub-components.
+- `src/components/<ComponentName>/` — reusable primitives. Folder when multiple files needed; flat `.ts` when single file.
+- **View-specific components** (only used by one view) live inside that view's folder.
+- **Promotion rule:** if a file inside `src/views/<View>/` is imported by 2+ views, move it to `src/components/`.
+- **Import boundary:** nothing inside `src/views/<View>/` is imported from outside that folder. Enforced by lint scripts:
+  - `pnpm check:imports` — catches cross-view boundary violations
+  - `pnpm check:css` — catches .css files with no importer (dead CSS)
+  - `pnpm check:scope` — catches CSS ancestor selectors never applied in templates
+- **Shared icons:** import from `src/components/icons.ts` — do not declare local ICON_MAP copies.
+
+### Stories
+
+- `stories/views/` — stories for views (`kind: "view"`)
+- `stories/components/` — stories for primitives (`kind: "component"`)
+- Mirror the `src/` structure. `kind` auto-detected from path; set explicitly to override.
+- `kind` — specifies story type (`"view"` or `"component"`).
+- `decorator?: (content: ArrowExpression) => ArrowExpression` — wraps the rendered variant in ancestor context when a component requires a parent class to render correctly.
+- Scaffold: `pnpm create:view <Name>` / `pnpm create:component <Name>`
+
+### Composition analysis (extracting shared primitives)
+
+When multiple views share a pattern, extract a primitive — but do it in this order:
+
+1. **Survey all implementations first** — read every view before designing the primitive.
+2. **Map shared shapes at the template level** — find the repeated HTML structure, not just the props.
+3. **Let the primitive emerge from actual shared code** — don't design a generic API upfront.
+4. **Extract and migrate simultaneously** — the primitive + its consumers must be shorter than the originals. If they aren't, the abstraction hasn't paid for itself.
 
 ## CSS scoping
 
@@ -114,12 +135,26 @@ in `boundary()`.
 pnpm typecheck    # tsc --noEmit
 pnpm test         # node:test
 pnpm lint         # biome
-pnpm check        # all of the above (format + typecheck + test)
+pnpm check        # all of the above + CSS orphan + import boundary + scope checks
 ```
 
-Then confirm the actual render in the browser at the `pnpm dev` URL — check the
-console is clean and the component looks like a real Obsidian pane. Do not claim
-a component works on typecheck alone; Arrow's footguns only surface at render.
+Then confirm the actual render:
+
+1. **Cold-load required.** Close and reopen the browser tab — do not just navigate
+   within the SPA. Vite's dev server keeps CSS module state across in-tab navigation,
+   which masks orphaned CSS and missing ancestor classes until a genuine cold load.
+
+2. **Check a computed style.** For each CSS change, assert at least one computed property
+   (`display`, `flexDirection`, `padding`) in the browser console — element count and
+   console-clean alone do not prove styles are applied:
+   ```js
+   getComputedStyle(document.querySelector('.my-class')).display // → "flex"
+   ```
+
+3. **Console clean.** No `[viewer]` warnings, no Arrow errors, no unhandled rejections.
+
+Do not claim a component works on typecheck alone. Arrow's footguns and CSS adoption bugs
+only surface at render time.
 
 ## Porting a component into the plugin
 

package/template/README.md

@@ -92,6 +92,7 @@ skills under [`skills/`](skills/) — it's a skill marketplace. Scaffolds **don'
 vendor copies**; they pull from this published repo, so installs are always
 current.
 
+- `obsidian-arrow-composition` — **run before designing any view area**: surveys codebase, shows proposed file trees, asks targeted questions, checks DRY and primitive use, produces a locked hierarchy doc for the migration agent to execute.
 - `obsidian-arrow-sandbox` — running and using this sandbox, CSS scoping, porting basics.
 - `obsidian-arrow-stories` — **component + story authoring workflow**: the complete `defineStories` API (variants, children, status flag, notes), DRY patterns, utility classes, story viewing, and how to structure sub-components.
 - `obsidian-arrow-css` — **CSS decision hierarchy**: Obsidian classes first, `oas-*` utilities second, custom CSS last; the live token reference (`/reference`), class catalog (`/reference/classes`), specificity scoping, overrides via CSS variables, and auditing components to minimize hand-written CSS.
@@ -142,25 +143,22 @@ swatches, size bars, a filter input, theme-aware resolved values, and a copy
 button. `/reference/classes` is a curated catalog of Obsidian pattern classes
 with live previews.
 
-### Add a story
+### Add a view
 
-Create `stories/MyThing.stories.ts` — stories live in the top-level `stories/`
-directory, keeping `src/` purely for component code:
+```sh
+pnpm create:view ChatView
+```
 
-```ts
-import { defineStories } from "../tools/viewer/stories";
-import { MyThing } from "../src/components/MyThing";
+Creates `src/views/ChatView/` (ts + css + state.ts) and `stories/views/ChatView.stories.ts`.
 
-export default defineStories({
-	description: "What it demonstrates.",
-	status: "draft",
-	variants: { default: () => MyThing() },
-});
+### Add a component
+
+```sh
+pnpm create:component Composer         # primitive → src/components/Composer/
+pnpm create:component ChatView/Widget  # view-specific → src/views/ChatView/Widget.ts
 ```
 
-It appears in the sidebar and at `/components` automatically; the component path
-shown in the viewer is derived from the filename. Stories are sandbox-only —
-they never port to the plugin.
+View stories use `kind: "view"` — full pane frame. Component stories use `kind: "component"` — centered canvas. Both auto-detected from the `stories/views/` vs `stories/components/` path.
 
 ## Porting a component into the plugin
 

package/template/_gitignore

@@ -13,3 +13,6 @@ public/app.css
 
 # subagent-driven-development scratch (briefs, reports, ledger)
 .superpowers/
+
+# PostCSS porting output (port-time only; never commit)
+port-output/

package/template/docs/prompts/agent-setup.md

@@ -44,6 +44,8 @@ READ FIRST
 - AGENTS.md (root) — operating guide + docs map (links everything below).
 - docs/workflow.md — fresh-machine → running workflow.
 - skills/*/SKILL.md — seven installable skills:
+    obsidian-arrow-composition  design component hierarchy: surveys codebase, shows file trees,
+                              asks questions, checks DRY/primitives, produces locked plan
     obsidian-arrow-sandbox    running the sandbox, CSS scoping, porting basics
     obsidian-arrow-stories    component + story authoring: defineStories API,
                               variants, children, status, DRY patterns, utilities

package/template/docs/workflow.md

@@ -58,19 +58,25 @@ in `src/` — never `src/components/` or `stories/`):
 ```sh
 # 1. Check /reference/classes in the running sandbox — does Obsidian have a class
 #    for your pattern? Use it before writing custom CSS.
-# 2. Add src/components/MyThing.ts (Arrow component)
-# 3. Add stories/MyThing.stories.ts (story file — lives in stories/, not src/)
-pnpm dev          # iterate with HMR
+# 2. Scaffold (or add manually):
+pnpm create:view ChatView              # full-pane view → src/views/ChatView/ + stories/views/
+pnpm create:component Composer         # reusable primitive → src/components/Composer/ + stories/components/
+pnpm create:component ChatView/Widget  # view-specific sub-component (not promoted yet)
+# 3. Iterate with HMR
+pnpm dev
 #    /components          → index of all discovered stories
-#    /components/my-thing → story for MyThing
+#    /components/my-thing → story for MyThing (kind: "component" → centered canvas)
+#    /components/chat-view → story for ChatView (kind: "view" → full pane)
 #    /reference           → live Obsidian token reference
 #    /reference/classes   → curated class catalog with live previews
 pnpm run ci       # biome + typecheck + tests + build before trusting it
 ```
 
-Always confirm the actual render in the browser — Arrow's footguns surface only
-at render, so a passing `tsc` is not proof a component works. See the footguns in
-[`AGENTS.md`](../AGENTS.md) and the `arrow-js-obsidian-templates` skill.
+Always confirm the actual render in the browser — Arrow's footguns and CSS scoping bugs
+surface only at render time. **Close and reopen the tab** before each verification step
+(do not rely on Vite's hot-module cache, which keeps CSS registered across SPA
+navigation). Assert at least one computed CSS property per component, not just "console
+clean." See [`AGENTS.md`](../AGENTS.md) for the full verification checklist.
 
 For the complete story authoring workflow (`defineStories` API, variants, children,
 status flag, DRY patterns) see the `obsidian-arrow-stories` skill.

package/template/package.json

@@ -11,12 +11,18 @@
 		"preview": "vite preview",
 		"typecheck": "tsc -p tsconfig.json --noEmit",
 		"pull-css": "node scripts/pull-app-css.mjs",
+		"port:css": "node scripts/port-css.mjs",
 		"create:sync": "node create-obsidian-arrow/scripts/sync-template.mjs",
+		"create:component": "node scripts/create-component.mjs",
+		"create:view": "node scripts/create-view.mjs",
 		"lint": "biome check .",
 		"format": "biome check --write .",
 		"test": "node --experimental-strip-types --test test/*.test.mjs",
-		"check": "biome check --write . && pnpm typecheck && pnpm test",
-		"ci": "biome ci . && pnpm typecheck && pnpm test && pnpm build",
+		"check:css": "node scripts/check-orphaned-css.mjs",
+		"check:scope": "node scripts/check-scope-classes.mjs",
+		"check:imports": "node scripts/check-view-imports.mjs",
+		"check": "biome check . && pnpm typecheck && pnpm test && pnpm check:css && pnpm check:scope && pnpm check:imports",
+		"ci": "biome ci . && pnpm typecheck && pnpm test && pnpm check:css && pnpm check:scope && pnpm check:imports && pnpm build",
 		"skills:install": "node scripts/install-skills.mjs --force",
 		"skills:update": "node scripts/install-skills.mjs --update",
 		"postinstall": "node scripts/install-skills.mjs",
@@ -38,6 +44,7 @@
 		"@types/node": "^22.16.5",
 		"husky": "^9.1.6",
 		"lint-staged": "^15.2.10",
+		"postcss": "^8.5.16",
 		"typescript": "^5.9.3",
 		"vite": "^8.0.0"
 	},

package/template/pnpm-lock.yaml

@@ -39,6 +39,9 @@ importers:
       lint-staged:
         specifier: ^15.2.10
         version: 15.5.2
+      postcss:
+        specifier: ^8.5.16
+        version: 8.5.16
       typescript:
         specifier: ^5.9.3
         version: 5.9.3

package/template/porting.config.example.json

@@ -0,0 +1,6 @@
+{
+	"cssPrefix": "my-plugin-",
+	"viewSubScope": false,
+	"include": ["src/components/**/*.css", "src/views/**/*.css"],
+	"outDir": "port-output/css"
+}

package/template/scripts/check-orphaned-css.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Finds .css files under src/ and tools/ that have no TypeScript importer.
+ * A .css file with no importer is dead CSS — safe to delete.
+ * Exit 1 on violations.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const srcDir = path.join(root, "src");
+const toolsDir = path.join(root, "tools");
+
+function walk(dir, results = []) {
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) walk(full, results);
+		else results.push(full);
+	}
+	return results;
+}
+
+const allFiles = [];
+if (fs.existsSync(srcDir)) {
+	allFiles.push(...walk(srcDir));
+}
+if (fs.existsSync(toolsDir)) {
+	allFiles.push(...walk(toolsDir));
+}
+
+const cssFiles = allFiles.filter((f) => f.endsWith(".css"));
+const tsFiles = allFiles.filter((f) => f.endsWith(".ts") || f.endsWith(".tsx"));
+
+// Build a set of all imported CSS paths (resolved)
+const importedCss = new Set();
+const importRe = /import\s+["']([^"']+\.css)["']/g;
+
+for (const tsFile of tsFiles) {
+	const content = fs.readFileSync(tsFile, "utf8");
+	importRe.lastIndex = 0;
+	let m = importRe.exec(content);
+	while (m !== null) {
+		const resolved = path.resolve(path.dirname(tsFile), m[1]);
+		importedCss.add(resolved);
+		m = importRe.exec(content);
+	}
+}
+
+const orphaned = cssFiles.filter((f) => !importedCss.has(f));
+
+if (orphaned.length === 0) {
+	console.log("check:css — no orphaned CSS files found ✓");
+	process.exit(0);
+}
+
+console.error(`check:css — ${orphaned.length} orphaned CSS file(s) found:`);
+for (const f of orphaned) {
+	console.error(`  ${path.relative(root, f)}`);
+}
+console.error("Each .css file must be imported by a .ts file in the same directory.");
+process.exit(1);

package/template/scripts/check-scope-classes.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Checks that every class used as an ancestor selector in CSS
+ * (e.g. ".my-shell .descendant" — the ".my-shell" part) also appears
+ * in at least one Arrow template in src/ or tools/.
+ *
+ * Catches "designed layer never wired up" bugs: CSS exists, is imported,
+ * but the ancestor class is never applied to a component root.
+ *
+ * Exit 1 on violations (ancestor classes with zero template occurrences).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const srcDir = path.join(root, "src");
+const toolsDir = path.join(root, "tools");
+
+function walk(dir, ext, results = []) {
+	if (!fs.existsSync(dir)) return results;
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) walk(full, ext, results);
+		else if (entry.name.endsWith(ext)) results.push(full);
+	}
+	return results;
+}
+
+// Collect all ancestor selector classes from CSS files in src/ and tools/
+// Pattern: .ancestor-class followed by whitespace and another selector
+const ancestorRe = /\.([\w-]+)\s+[.#\[a-zA-Z]/g;
+const cssFiles = [...walk(srcDir, ".css"), ...walk(toolsDir, ".css")];
+const ancestorClasses = new Map(); // class → [cssFile, ...]
+
+for (const cssFile of cssFiles) {
+	const content = fs.readFileSync(cssFile, "utf8");
+	ancestorRe.lastIndex = 0;
+	let m = ancestorRe.exec(content);
+	while (m !== null) {
+		const cls = m[1];
+		if (!ancestorClasses.has(cls)) ancestorClasses.set(cls, []);
+		ancestorClasses.get(cls).push(path.relative(root, cssFile));
+		m = ancestorRe.exec(content);
+	}
+}
+
+if (ancestorClasses.size === 0) {
+	console.log("check:scope — no ancestor selectors found ✓");
+	process.exit(0);
+}
+
+// Check each ancestor class appears in at least one .ts template in src/ or tools/
+const tsFiles = [...walk(srcDir, ".ts"), ...walk(toolsDir, ".ts")];
+const tsContent = tsFiles.map((f) => fs.readFileSync(f, "utf8")).join("\n");
+
+let violations = 0;
+for (const [cls, cssFilePaths] of ancestorClasses) {
+	// Check if the class string appears anywhere in templates
+	// (as a class="..." value or in a reactive class expression)
+	if (!tsContent.includes(cls)) {
+		console.error(
+			`VIOLATION: .${cls} used as ancestor selector in CSS but never applied in any template:`
+		);
+		for (const f of cssFilePaths) console.error(`  defined in: ${f}`);
+		violations++;
+	}
+}
+
+if (violations > 0) {
+	console.error(
+		`check:scope — ${violations} ancestor class(es) never applied in templates.\nAdd the class to a component root or remove the CSS rules.`
+	);
+	process.exit(1);
+}
+
+console.log(`check:scope — all ${ancestorClasses.size} ancestor classes verified in templates ✓`);

package/template/scripts/check-view-imports.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Two checks:
+ * 1. Cross-view boundary: files inside src/views/<View>/ must not be imported
+ *    from outside src/views/<View>/. Exit 1 on violation.
+ * 2. Primitive promotion: files inside any src/views/<View>/ imported by 2+
+ *    different view directories — suggest promotion to src/components/.
+ *    Warning only, exit 0.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const srcDir = path.join(root, "src");
+const viewsDir = path.join(srcDir, "views");
+const toolsDir = path.join(root, "tools");
+
+function walk(dir, results = []) {
+	if (!fs.existsSync(dir)) return results;
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) walk(full, results);
+		else if (entry.name.endsWith(".ts") || entry.name.endsWith(".mjs")) results.push(full);
+	}
+	return results;
+}
+
+// Collect all .ts and .mjs files from src/ and tools/
+const allTs = [...walk(srcDir), ...walk(toolsDir)];
+
+// Map: absolute path → set of importing files
+const importedBy = new Map();
+
+const importRe = /(?:import|from)\s+["']([^"']+)["']/g;
+
+for (const file of allTs) {
+	const content = fs.readFileSync(file, "utf8");
+	importRe.lastIndex = 0;
+	let m = importRe.exec(content);
+	while (m !== null) {
+		const imp = m[1];
+		if (imp.startsWith(".")) {
+			const dir = path.dirname(file);
+			const resolved = path.resolve(dir, imp);
+
+			// Try with .ts extension if not already present
+			let targetPath = resolved;
+			if (!resolved.endsWith(".ts") && !resolved.endsWith(".mjs") && !fs.existsSync(resolved)) {
+				if (fs.existsSync(`${resolved}.ts`)) {
+					targetPath = `${resolved}.ts`;
+				} else if (fs.existsSync(`${resolved}.mjs`)) {
+					targetPath = `${resolved}.mjs`;
+				}
+			}
+
+			if (!importedBy.has(targetPath)) importedBy.set(targetPath, new Set());
+			importedBy.get(targetPath).add(file);
+		}
+		m = importRe.exec(content);
+	}
+}
+
+// Get all view directories
+const viewDirs = fs.existsSync(viewsDir)
+	? fs
+			.readdirSync(viewsDir, { withFileTypes: true })
+			.filter((e) => e.isDirectory())
+			.map((e) => path.join(viewsDir, e.name))
+	: [];
+
+if (viewDirs.length === 0) {
+	console.log("check:imports — no cross-view boundary violations ✓");
+	process.exit(0);
+}
+
+let violations = 0;
+const promotionCandidates = [];
+
+for (const viewDir of viewDirs) {
+	const viewFiles = walk(viewDir);
+	for (const viewFile of viewFiles) {
+		const importers = importedBy.get(viewFile) ?? new Set();
+
+		// Check 1: any importer outside this view dir?
+		for (const importer of importers) {
+			if (!importer.startsWith(viewDir)) {
+				console.error(
+					`VIOLATION: ${path.relative(root, viewFile)} imported from outside its view folder:\n` +
+						`  by ${path.relative(root, importer)}`
+				);
+				violations++;
+			}
+		}
+
+		// Check 2: imported by 2+ different view dirs?
+		const importingViewDirs = new Set(
+			[...importers]
+				.map((imp) => {
+					const rel = path.relative(viewsDir, imp);
+					if (rel.startsWith("..")) return null;
+					if (!rel.includes("/")) return null;
+					return path.join(viewsDir, rel.split("/")[0]);
+				})
+				.filter(Boolean)
+		);
+		if (importingViewDirs.size >= 2) {
+			promotionCandidates.push({
+				file: path.relative(root, viewFile),
+				importedBy: importingViewDirs.size,
+			});
+		}
+	}
+}
+
+if (promotionCandidates.length > 0) {
+	console.warn(
+		"\nPromotion candidates (used in 2+ view directories — consider moving to src/components/):"
+	);
+	for (const c of promotionCandidates) {
+		console.warn(`  ${c.file}  (${c.importedBy} view directories)`);
+	}
+}
+
+if (violations > 0) {
+	console.error(
+		`\ncheck:imports — ${violations} cross-view boundary violation(s). Move the file to src/components/ or keep it internal.`
+	);
+	process.exit(1);
+}
+
+console.log("check:imports — no cross-view boundary violations ✓");
+process.exit(0);

package/template/scripts/component-hash.mjs

@@ -38,7 +38,18 @@ function fail(message) {
 
 function hashFile(file) {
 	try {
-		return hashSource(fs.readFileSync(file, "utf8"));
+		let source = fs.readFileSync(file, "utf8");
+
+		// For .ts files, include co-located CSS if it exists
+		if (file.endsWith(".ts")) {
+			const cssPath = file.replace(/\.ts$/, ".css");
+			if (fs.existsSync(cssPath)) {
+				const cssSource = fs.readFileSync(cssPath, "utf8");
+				source = `${source}\n/* CSS */\n${cssSource}`;
+			}
+		}
+
+		return hashSource(source);
 	} catch (error) {
 		fail(`cannot read ${file} (${error.code ?? error.message})`);
 		return ""; // unreachable; fail() exits

package/template/scripts/create-component.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Usage:
+ *   pnpm create:component Composer                  → src/components/Composer/ (with CSS)
+ *   pnpm create:component icons                     → src/components/icons.ts (flat, no args)
+ *   pnpm create:component ChatView/ChatComposer      → src/views/ChatView/ChatComposer.ts (flat)
+ *   pnpm create:component ChatView/Widget --css      → src/views/ChatView/Widget/ (with CSS)
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+const flags = process.argv.slice(2).filter((a) => a.startsWith("--"));
+const withCss = flags.includes("--css");
+
+if (!args[0]) {
+	console.error("Usage: pnpm create:component <[ViewName/]ComponentName> [--css]");
+	process.exit(1);
+}
+
+const parts = args[0].split("/");
+const componentName = parts.pop();
+const parentView = parts[0]; // e.g. "ChatView" or undefined
+
+let srcDir;
+let storyPath;
+let isFolder;
+
+if (parentView) {
+	// View-specific: flat by default, folder with --css
+	const viewDir = path.join(root, "src", "views", parentView);
+	isFolder = withCss;
+	srcDir = isFolder ? path.join(viewDir, componentName) : viewDir;
+	storyPath = path.join(root, "stories", "views", parentView, `${componentName}.stories.ts`);
+} else {
+	// Primitive: folder with CSS by default
+	isFolder = true;
+	srcDir = path.join(root, "src", "components", componentName);
+	storyPath = path.join(root, "stories", "components", `${componentName}.stories.ts`);
+}
+
+const tsFile = path.join(srcDir, `${componentName}.ts`);
+const cssFile = isFolder ? path.join(srcDir, `${componentName}.css`) : null;
+
+// Component .ts stub
+const cssImport = cssFile ? `import "./${componentName}.css";\n` : "";
+const tsContent = `${cssImport}import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+
+export function ${componentName}(): ArrowExpression {
+	return html\`<div class="${componentName
+		.replace(/([A-Z])/g, (m, l, i) => (i ? "-" : "") + l.toLowerCase())
+		.replace(/^-/, "")}">TODO</div>\`;
+}
+`;
+
+// Story stub
+const importPath = "../../tools/viewer/stories";
+const componentImport = parentView
+	? `../../src/views/${parentView}/${componentName}`
+	: `../../src/components/${isFolder ? `${componentName}/` : ""}${componentName}`;
+const kindLine = parentView ? `\tkind: "component",\n` : "";
+
+const storyContent = `import { defineStories } from "${importPath}";
+import { ${componentName} } from "${componentImport}";
+
+export default defineStories({
+${kindLine}\tdescription: "TODO: describe ${componentName}.",
+\tstatus: "draft",
+\tvariants: {
+\t\tdefault: () => ${componentName}(),
+\t},
+});
+`;
+
+// Write files
+if (isFolder) fs.mkdirSync(srcDir, { recursive: true });
+else fs.mkdirSync(path.dirname(tsFile), { recursive: true });
+
+if (fs.existsSync(tsFile)) {
+	console.error(`Already exists: ${tsFile}`);
+	process.exit(1);
+}
+
+fs.writeFileSync(tsFile, tsContent);
+console.log(`Created: ${path.relative(root, tsFile)}`);
+
+if (cssFile) {
+	fs.writeFileSync(cssFile, `/* ${componentName} styles */\n`);
+	console.log(`Created: ${path.relative(root, cssFile)}`);
+}
+
+fs.mkdirSync(path.dirname(storyPath), { recursive: true });
+if (!fs.existsSync(storyPath)) {
+	fs.writeFileSync(storyPath, storyContent);
+	console.log(`Created: ${path.relative(root, storyPath)}`);
+} else {
+	console.log(`Story already exists, skipped: ${path.relative(root, storyPath)}`);
+}