create-obsidian-arrow 0.4.0 → 0.5.0

package/index.mjs

@@ -181,6 +181,14 @@ function update(targetArg) {
 	}
 	const pkgChanges = mergePackageJson(path.join(root, "package.json"));
 
+	// Create stories/ if missing — user-owned (never overwritten), but must
+	// exist before the first story file can be added.
+	const storiesDir = path.join(root, "stories");
+	const storiesCreated = !fs.existsSync(storiesDir);
+	if (storiesCreated && !dryRun) {
+		fs.mkdirSync(storiesDir);
+	}
+
 	const verb = dryRun ? "Would refresh" : "Refreshed";
 	console.log(
 		`${verb} ${written.length} managed file(s) in ${path.relative(process.cwd(), root) || "."}:`
@@ -188,6 +196,11 @@ function update(targetArg) {
 	for (const file of written) {
 		console.log(`  ${file}`);
 	}
+	if (storiesCreated) {
+		console.log(
+			`  stories/  ${dryRun ? "(would create empty)" : "(created empty — add your *.stories.ts files here)"}`
+		);
+	}
 	if (pkgChanges.length > 0) {
 		console.log(`package.json: ${dryRun ? "would update" : "updated"} ${pkgChanges.join(", ")}`);
 	}

package/package.json

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

package/template/AGENTS.md

@@ -84,19 +84,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 +134,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

@@ -142,25 +142,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/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)}`);
+}

package/template/scripts/create-view.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Usage:
+ *   pnpm create:view ChatView   → src/views/ChatView/ + stories/views/ChatView.stories.ts
+ */
+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 viewName = process.argv[2];
+
+if (!viewName) {
+	console.error("Usage: pnpm create:view <ViewName>");
+	process.exit(1);
+}
+
+const viewDir = path.join(root, "src", "views", viewName);
+const storyDir = path.join(root, "stories", "views");
+
+if (fs.existsSync(viewDir)) {
+	console.error(`Already exists: src/views/${viewName}/`);
+	process.exit(1);
+}
+
+fs.mkdirSync(viewDir, { recursive: true });
+fs.mkdirSync(storyDir, { recursive: true });
+
+const tsContent = `import "./${viewName}.css";
+import { component, html } from "@arrow-js/core";
+import type { ArrowTemplate } from "@arrow-js/core";
+
+export const ${viewName} = component((): ArrowTemplate => {
+	return html\`
+		<div class="oas-settings">
+			<div class="setting-item setting-item-heading">
+				<div class="setting-item-info">
+					<div class="setting-item-name">${viewName}</div>
+				</div>
+			</div>
+		</div>
+	\`;
+});
+`;
+
+const cssContent = `/* ${viewName} layout and chrome */\n`;
+
+const stateContent = `import { reactive } from "@arrow-js/core";
+
+export const state = reactive({
+	// TODO: add view state
+});
+`;
+
+const storyContent = `import { defineStories } from "../../tools/viewer/stories";
+import { ${viewName} } from "../../src/views/${viewName}/${viewName}";
+
+export default defineStories({
+	kind: "view",
+	description: "TODO: describe ${viewName}.",
+	status: "draft",
+	variants: {
+		default: () => ${viewName}(),
+	},
+});
+`;
+
+fs.writeFileSync(path.join(viewDir, `${viewName}.ts`), tsContent);
+fs.writeFileSync(path.join(viewDir, `${viewName}.css`), cssContent);
+fs.writeFileSync(path.join(viewDir, "state.ts"), stateContent);
+fs.writeFileSync(path.join(storyDir, `${viewName}.stories.ts`), storyContent);
+
+console.log(`Created src/views/${viewName}/`);
+console.log(`  ${viewName}.ts, ${viewName}.css, state.ts`);
+console.log(`Created stories/views/${viewName}.stories.ts`);

package/template/scripts/port-css.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/**
+ * PostCSS prefix pipeline — port time only, never modifies source files.
+ *
+ * Usage: pnpm port:css
+ *
+ * Reads porting.config.json, walks CSS files matching `include` globs,
+ * prefixes all class selectors with `cssPrefix`, writes prefixed output
+ * to `outDir/`. Also generates outDir/index.css that @imports all outputs.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import postcss from "postcss";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const configPath = path.join(root, "porting.config.json");
+
+if (!fs.existsSync(configPath)) {
+	console.error("porting.config.json not found. Create it at the project root.");
+	process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+const {
+	cssPrefix = "my-plugin-",
+	outDir = "port-output/css",
+	include = [],
+	viewSubScope = false,
+} = config;
+
+// Kebab-case a PascalCase view name for the ancestor selector.
+function toKebab(name) {
+	return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+// Collect CSS files matching include patterns (simple glob expansion)
+function matchesGlob(file, pattern) {
+	// Convert glob to regex: ** → .*, * → [^/]*
+	const re = new RegExp(
+		`^${pattern.replace(/\*\*/g, "@@").replace(/\*/g, "[^/]*").replace(/@@/g, ".*")}$`
+	);
+	return re.test(file);
+}
+
+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(".css")) results.push(full);
+	}
+	return results;
+}
+
+const allCss = walk(path.join(root, "src"));
+const cssFiles = allCss.filter((f) => {
+	const rel = path.relative(root, f).replace(/\\/g, "/");
+	return include.some((pattern) => matchesGlob(rel, pattern));
+});
+
+if (cssFiles.length === 0) {
+	console.log("No CSS files matched include patterns.");
+	process.exit(0);
+}
+
+// PostCSS plugin: prefix all class selectors; optionally prepend an ancestor.
+// When ancestorClass is provided (viewSubScope for view-folder CSS), every rule
+// selector gains the ancestor: ".composer" → ".vault-mind-chat-view .vault-mind-composer"
+const prefixPlugin = (prefix, ancestorClass) => ({
+	postcssPlugin: "postcss-prefix-classes",
+	Rule(rule) {
+		rule.selector = rule.selector.replace(/\.([a-zA-Z][\w-]*)/g, `.${prefix}$1`);
+		if (ancestorClass) {
+			rule.selector = rule.selector
+				.split(",")
+				.map((s) => `${ancestorClass} ${s.trim()}`)
+				.join(", ");
+		}
+	},
+});
+prefixPlugin.postcss = true;
+
+const outDirAbs = path.join(root, outDir);
+fs.mkdirSync(outDirAbs, { recursive: true });
+
+const outputFiles = [];
+
+for (const cssFile of cssFiles) {
+	const rel = path.relative(path.join(root, "src"), cssFile).replace(/\\/g, "/");
+	const outFile = path.join(outDirAbs, rel);
+	fs.mkdirSync(path.dirname(outFile), { recursive: true });
+
+	// Determine view ancestor class when viewSubScope is enabled.
+	// src/views/ChatView/X.css → ancestor ".vault-mind-chat-view"
+	let ancestorClass = null;
+	if (viewSubScope) {
+		const viewMatch = rel.match(/^views\/([^/]+)\//);
+		if (viewMatch) {
+			ancestorClass = `.${cssPrefix}${toKebab(viewMatch[1])}`;
+		}
+	}
+
+	const source = fs.readFileSync(cssFile, "utf8");
+	const result = await postcss([prefixPlugin(cssPrefix, ancestorClass)]).process(source, {
+		from: cssFile,
+		to: outFile,
+	});
+
+	fs.writeFileSync(outFile, result.css);
+	outputFiles.push(path.relative(outDirAbs, outFile).replace(/\\/g, "/"));
+	console.log(`Prefixed: ${rel} → ${path.relative(root, outFile)}`);
+}
+
+// Generate index.css
+const indexContent = `${outputFiles.map((f) => `@import "./${f}";`).join("\n")}\n`;
+fs.writeFileSync(path.join(outDirAbs, "index.css"), indexContent);
+console.log(`\nGenerated: ${outDir}/index.css (${outputFiles.length} files)`);

package/template/src/components/EmptyState/EmptyState.css

@@ -0,0 +1,30 @@
+.empty-state {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: var(--size-4-2);
+	padding: var(--size-4-4);
+	text-align: center;
+	color: var(--text-muted);
+}
+
+.empty-state-icon {
+	font-size: var(--font-ui-larger, 2rem);
+	line-height: 1;
+	color: var(--text-faint);
+}
+
+.empty-state-title {
+	font-size: var(--font-ui-medium);
+	font-weight: var(--font-semibold);
+	color: var(--text-normal);
+}
+
+.empty-state-description {
+	font-size: var(--font-ui-small);
+	max-width: 280px;
+}
+
+.empty-state-action {
+	margin-top: var(--size-4-2);
+}

package/template/src/components/EmptyState/EmptyState.ts

@@ -0,0 +1,35 @@
+import "./EmptyState.css";
+import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+import { icon } from "../icons";
+
+export interface EmptyStateOptions {
+	icon?: string;
+	title: string;
+	description?: string;
+	action?: { label: string; onClick: () => void };
+}
+
+export function EmptyState(options: EmptyStateOptions): ArrowExpression {
+	return html`
+		<div class="empty-state">
+			${options.icon ? html`<div class="empty-state-icon">${icon(options.icon)}</div>` : ""}
+			<div class="empty-state-title">${options.title}</div>
+			${
+				options.description
+					? html`<div class="empty-state-description">${options.description}</div>`
+					: ""
+			}
+			${
+				options.action
+					? html`<button
+							class="mod-cta empty-state-action"
+							@click="${options.action.onClick}"
+						>
+							${options.action.label}
+						</button>`
+					: ""
+			}
+		</div>
+	`;
+}

package/template/src/components/LoadingState.ts

@@ -0,0 +1,12 @@
+import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
+import { icon } from "./icons";
+
+export function LoadingState(message?: string): ArrowExpression {
+	return html`
+		<div class="oas-flex oas-flex-col oas-items-center oas-gap-2 oas-p-4 oas-text-muted">
+			<span>${icon("loader")}</span>
+			${message ? html`<span class="oas-text-sm">${message}</span>` : ""}
+		</div>
+	`;
+}

package/template/src/components/icons.ts

@@ -0,0 +1,17 @@
+export const ICON_MAP: Record<string, string> = {
+	check: "✓",
+	x: "✕",
+	"chevron-right": "›",
+	"chevron-down": "⌄",
+	loader: "◌",
+	search: "⌕",
+	file: "◻",
+	folder: "◱",
+	info: "ℹ",
+	warning: "⚠",
+	error: "✕",
+};
+
+export function icon(name: string): string {
+	return ICON_MAP[name] ?? "•";
+}

package/template/stories/components/EmptyState.stories.ts

@@ -0,0 +1,25 @@
+import { EmptyState } from "../../src/components/EmptyState/EmptyState";
+import { defineStories } from "../../tools/viewer/stories";
+
+export default defineStories({
+	description: "Reusable empty state for any view — icon, title, description, optional action.",
+	status: "live",
+	variants: {
+		default: () => EmptyState({ title: "Nothing here yet" }),
+		"with description": () => {
+			return EmptyState({
+				icon: "file",
+				title: "No files found",
+				description: "Try a different search or create a new file.",
+			});
+		},
+		"with action": () => {
+			return EmptyState({
+				icon: "search",
+				title: "No results",
+				description: "Your search returned no matches.",
+				action: { label: "Clear search", onClick: () => {} },
+			});
+		},
+	},
+});

package/template/stories/components/LoadingState.stories.ts

@@ -0,0 +1,11 @@
+import { LoadingState } from "../../src/components/LoadingState";
+import { defineStories } from "../../tools/viewer/stories";
+
+export default defineStories({
+	description: "Loading indicator for async view content.",
+	status: "live",
+	variants: {
+		default: () => LoadingState(),
+		"with message": () => LoadingState("Loading sessions…"),
+	},
+});

package/template/test/viewer-derive.test.mjs

@@ -63,3 +63,9 @@ test("buildStoryTree guards cycles: mutual refs fall back to flat roots", () =>
 	assert.equal(roots[0].children[0].slug, "b");
 	assert.equal(roots[0].children[0].children.length, 0);
 });
+
+test("storyMetaFromGlobKey: stories/views/ path auto-kind is view", () => {
+	const meta = storyMetaFromGlobKey("../../stories/views/ChatView.stories.ts");
+	// auto-kind logic lives in discovery.ts, not derive.ts — just confirm storiesPath prefix
+	assert.ok(meta.storiesPath.startsWith("stories/views/"));
+});

package/template/test/viewer-stories.test.mjs

@@ -42,3 +42,29 @@ test("normalizeVariants wraps bare functions and passes objects through", () =>
 	assert.equal(out.full.render, fn);
 	assert.equal(out.full.notes, "n");
 });
+
+test("validateStoryDef accepts kind: view and kind: component", () => {
+	const base = { variants: { default: () => {} } };
+	assert.deepEqual(validateStoryDef({ ...base, kind: "view" }), { ok: true });
+	assert.deepEqual(validateStoryDef({ ...base, kind: "component" }), { ok: true });
+});
+
+test("validateStoryDef rejects invalid kind", () => {
+	const r = validateStoryDef({ variants: { default: () => {} }, kind: "panel" });
+	assert.equal(r.ok, false);
+	assert.match(r.reason, /kind/);
+});
+
+test("validateStoryDef accepts decorator function", () => {
+	const r = validateStoryDef({
+		variants: { default: () => {} },
+		decorator: (c) => c,
+	});
+	assert.deepEqual(r, { ok: true });
+});
+
+test("validateStoryDef rejects non-function decorator", () => {
+	const r = validateStoryDef({ variants: { default: () => {} }, decorator: "bad" });
+	assert.equal(r.ok, false);
+	assert.match(r.reason, /decorator/);
+});

package/template/tools/router/client.ts

@@ -1,4 +1,5 @@
 import { html } from "@arrow-js/core";
+import type { ArrowExpression } from "@arrow-js/core";
 import { Frame } from "../sandbox/frame";
 import { Shell } from "../sandbox/shell";
 import type { Page } from "./routeToPage";
@@ -29,6 +30,10 @@ function getNavigation(): NavigationLike | undefined {
 	return (window as unknown as { navigation?: NavigationLike }).navigation;
 }
 
+function ComponentCanvas(content: ArrowExpression): ArrowExpression {
+	return html`<div class="oas-component-canvas">${content}</div>`;
+}
+
 export function startRouter(root: HTMLElement): void {
 	const render = (url: string): void => {
 		let resolved = routeToPage(url);
@@ -42,9 +47,15 @@ export function startRouter(root: HTMLElement): void {
 		const page: Page = resolved;
 		document.title = page.title;
 		root.replaceChildren();
-		const content = page.sidebar
-			? html`${page.sidebar}${Frame(page.title, page.view)}`
-			: Frame(page.title, page.view);
+
+		let content: ArrowExpression;
+		if (page.sidebar && page.canvas) {
+			content = html`${page.sidebar}${Frame(page.title, page.view)}${ComponentCanvas(page.canvas)}`;
+		} else if (page.sidebar) {
+			content = html`${page.sidebar}${Frame(page.title, page.view)}`;
+		} else {
+			content = Frame(page.title, page.view);
+		}
 		Shell(content)(root);
 	};
 

package/template/tools/router/routeToPage.ts

@@ -3,7 +3,7 @@ import type { ArrowExpression } from "@arrow-js/core";
 import { Home } from "../sandbox/home";
 import { ClassesPage } from "../viewer/ClassesPage";
 import { ComponentsIndex } from "../viewer/ComponentsIndex";
-import { StoryPage } from "../viewer/StoryPage";
+import { StoryPageCanvas, StoryPageDetails, StoryPageView } from "../viewer/StoryPage";
 import { TokensPage } from "../viewer/TokensPage";
 import { findStory } from "../viewer/discovery";
 import { ViewerSidebar } from "../viewer/sidebar";
@@ -19,6 +19,7 @@ export interface Page {
 	title: string;
 	view: ArrowExpression;
 	sidebar?: ArrowExpression;
+	canvas?: ArrowExpression;
 }
 
 export interface Redirect {
@@ -74,11 +75,22 @@ export function routeToPage(url: string): Page | Redirect {
 		}
 		const requested = searchParams.get("variant");
 		const variantName = requested ?? Object.keys(story.variants)[0];
+		// kind: "view" → full page in the frame
+		if (story.kind === "view") {
+			return {
+				status: story.variants[variantName] ? 200 : 404,
+				title: `${story.title} · ${APP_NAME}`,
+				view: StoryPageView(story, variantName),
+				sidebar: ViewerSidebar(`/components/${story.slug}`),
+			};
+		}
+		// kind: "component" → details in frame, canvas separate
 		return {
 			status: story.variants[variantName] ? 200 : 404,
 			title: `${story.title} · ${APP_NAME}`,
-			view: StoryPage(story, variantName),
+			view: StoryPageDetails(story, variantName),
 			sidebar: ViewerSidebar(`/components/${story.slug}`),
+			canvas: StoryPageCanvas(story, variantName),
 		};
 	}
 

package/template/tools/sandbox/sandbox.css

@@ -130,6 +130,19 @@ body {
 	opacity: 0.5;
 }
 
+/* Component canvas — fills remaining stage width for kind: "component" stories */
+.oas-component-canvas {
+	flex: 1;
+	min-width: 0;
+	min-height: 0;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	padding: var(--size-4-4);
+	overflow: auto;
+	background: var(--background-secondary);
+}
+
 /* Collapsible card — Getting Started accordion and other expandable sections. */
 .oas-card {
 	border-bottom: 1px solid var(--background-modifier-border);

package/template/tools/viewer/StoryPage.ts

@@ -3,7 +3,6 @@ import type { ArrowExpression } from "@arrow-js/core";
 import type { DiscoveredStory } from "./discovery";
 import { findStory } from "./discovery";
 
-/** Copy to clipboard, best-effort (clipboard API needs a secure context). */
 export function copyText(text: string): void {
 	void navigator.clipboard?.writeText(text);
 }
@@ -18,18 +17,23 @@ function pathRow(label: string, path: string): ArrowExpression {
 	`;
 }
 
-export function StoryPage(story: DiscoveredStory, variantName: string): ArrowExpression {
-	const variant = story.variants[variantName];
+/** Metadata panel: title, status, variant tabs, notes, paths, children.
+ *  No rendered component — used for kind: "component" left panel. */
+export function StoryPageDetails(story: DiscoveredStory, variantName: string): ArrowExpression {
 	const variantNames = Object.keys(story.variants);
-	const badge =
-		story.status === "live"
-			? html`<span class="oas-badge is-live">live</span>`
-			: html`<span class="oas-badge is-draft">draft</span>`;
+	const variant = story.variants[variantName];
 	return html`
 		<div class="oas-story">
 			<div class="setting-item setting-item-heading">
 				<div class="setting-item-info">
-					<div class="setting-item-name">${story.title} ${badge}</div>
+					<div class="setting-item-name">
+						${story.title}
+						${
+							story.status === "live"
+								? html`<span class="oas-badge is-live">live</span>`
+								: html`<span class="oas-badge is-draft">draft</span>`
+						}
+					</div>
 					${
 						story.description
 							? html`<div class="setting-item-description">${story.description}</div>`
@@ -54,20 +58,35 @@ export function StoryPage(story: DiscoveredStory, variantName: string): ArrowExp
 					? html`<div class="oas-story-children">
 						${story.children.map((slug) => {
 							const child = findStory(slug);
+							const childHref = `/components/${slug}`;
 							return child
-								? html`<a class="oas-child" href="${`/components/${slug}`}">${child.title} →</a>`
+								? html`<a class="oas-child" href="${childHref}">${child.title} →</a>`
 								: html`<span class="oas-child-missing">${slug} (missing story)</span>`;
 						})}
 					</div>`
 					: ""
 			}
-			<div class="oas-story-canvas">
-				${
-					variant
-						? variant.render()
-						: html`<div class="oas-story-missing">No variant "${variantName}" — pick one above.</div>`
-				}
-			</div>
+		</div>
+	`;
+}
+
+/** Rendered component only — decorator applied if present.
+ *  Used for kind: "component" canvas area. */
+export function StoryPageCanvas(story: DiscoveredStory, variantName: string): ArrowExpression {
+	const variant = story.variants[variantName];
+	const rendered = variant
+		? variant.render()
+		: html`<div class="oas-story-missing">No variant "${variantName}" — pick one above.</div>`;
+	return story.decorator ? story.decorator(rendered) : rendered;
+}
+
+/** Full story page: details + canvas together.
+ *  Used for kind: "view" — StoryPageDetails provides the .oas-story wrapper. */
+export function StoryPageView(story: DiscoveredStory, variantName: string): ArrowExpression {
+	return html`
+		${StoryPageDetails(story, variantName)}
+		<div class="oas-story-canvas">
+			${StoryPageCanvas(story, variantName)}
 		</div>
 	`;
 }

package/template/tools/viewer/discovery.ts

@@ -1,3 +1,4 @@
+import type { ArrowExpression } from "@arrow-js/core";
 import { buildStoryTree, storyMetaFromGlobKey, titleFromSlug } from "./derive";
 import type { StoryDef, StoryVariant } from "./stories";
 import { normalizeVariants, validateStoryDef } from "./stories";
@@ -19,6 +20,8 @@ export interface DiscoveredStory {
 	variants: Record<string, StoryVariant>;
 	children: string[];
 	status: "live" | "draft";
+	kind: "view" | "component";
+	decorator?: (content: ArrowExpression) => ArrowExpression;
 }
 
 export interface InvalidStory {
@@ -43,6 +46,7 @@ for (const [globKey, mod] of Object.entries(modules)) {
 		continue;
 	}
 	const def = mod.default as StoryDef;
+	const autoKind = meta.storiesPath.startsWith("stories/views/") ? "view" : "component";
 	stories.push({
 		slug: meta.slug,
 		title: def.title ?? titleFromSlug(meta.slug),
@@ -52,6 +56,8 @@ for (const [globKey, mod] of Object.entries(modules)) {
 		variants: normalizeVariants(def.variants),
 		children: def.children ?? [],
 		status: def.status ?? "draft",
+		kind: def.kind ?? autoKind,
+		decorator: def.decorator,
 	});
 }
 

package/template/tools/viewer/stories.ts

@@ -21,6 +21,12 @@ export interface StoryDef {
 	/** Repo-relative override for where the component lives (e.g. a subcomponent
 	 * defined inside its parent's file). Defaults to the stories path minus `.stories`. */
 	componentPath?: string;
+	/** "view" = full pane frame. "component" = centered canvas with separate details panel.
+	 *  Auto-detected from stories/ path if omitted. */
+	kind?: "view" | "component";
+	/** Wraps the rendered variant — use for ancestor class context.
+	 *  Example: (content) => html`<div class="my-shell">${content}</div>` */
+	decorator?: (content: ArrowExpression) => ArrowExpression;
 	/** Named variants; keys are human strings ("default", "dev mode off"). */
 	variants: Record<string, VariantInput>;
 	/** Slugs of subcomponent stories for drill-in nesting. */
@@ -69,6 +75,16 @@ export function validateStoryDef(def: unknown): ValidationResult {
 			return { ok: false, reason: '"status" must be "live" or "draft"' };
 		}
 	}
+	if ("kind" in def) {
+		if (def.kind !== "view" && def.kind !== "component") {
+			return { ok: false, reason: '"kind" must be "view" or "component"' };
+		}
+	}
+	if ("decorator" in def) {
+		if (typeof def.decorator !== "function") {
+			return { ok: false, reason: '"decorator" must be a function' };
+		}
+	}
 	return { ok: true };
 }