create-obsidian-arrow 0.3.0 → 0.4.1

package/README.md

@@ -45,9 +45,11 @@ prints this hint when it detects nesting.
 ## Update an existing project
 
 The scaffolder is create-only, but `update` refreshes an existing project's
-**managed** tooling (`scripts/`, `skills/`, `docs/`, `.github/`, `.husky/`,
-`biome.json`, agent guides) and merges new `package.json` scripts/deps — it never
-touches your `src/`, `public/`, `index.html`, or build configs:
+**managed** files (`scripts/`, `docs/`, `.github/`, `.husky/`, `biome.json`,
+agent guides, `tools/viewer/`, `tools/router/`, `tools/sandbox/`, `src/main.ts`,
+`src/utilities.css`, `test/`) and merges new `package.json` scripts/deps —
+it never touches `src/components/`, `stories/`, `public/`, `index.html`, or
+build configs:
 
 ```sh
 npx create-obsidian-arrow update            # in the project (or: update <dir>)
@@ -69,7 +71,7 @@ node create-obsidian-arrow/index.mjs update ../my-app   # update
 
 A full sandbox: client-only Vite + TS, `@arrow-js/core` + `@arrow-js/framework`
 (no SSR), `routeToPage` + Navigation-API router, a Storybook-style component
-viewer at `/components` (co-locate `*.stories.ts` to add stories), a live token
+viewer at `/components` (add `*.stories.ts` files in `stories/`), a live token
 and class reference at `/reference`, Biome + husky pre-commit + `node:test` +
 GitHub Actions CI, a `skills:install` that pulls the agent skills from the
 published repo, and the `pull-css` script that extracts Obsidian's `app.css`.

package/index.mjs

@@ -13,9 +13,11 @@
  * Scaffold copies the vendored template/, restores .gitignore (vendored as
  * _gitignore), names the project, and runs `git init`.
  *
- * Update refreshes only the *managed* tooling files from the template and merges
- * package.json scripts + missing deps — it never touches your src/, public/,
- * index.html, or the core build configs. Use --dry-run to preview.
+ * Update refreshes *managed* files from the template and merges package.json
+ * scripts + missing deps. Managed = scripts/, docs/, .github/, .husky/,
+ * biome.json, AGENTS.md, CLAUDE.md, tools/, src/main.ts, src/utilities.css,
+ * test/. Never touches src/components/, stories/, public/, index.html,
+ * vite.config.ts, tsconfig.json, or .gitignore. Use --dry-run first.
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
@@ -25,12 +27,29 @@ import { fileURLToPath } from "node:url";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const templateDir = path.join(here, "template");
 
-// Files/dirs the template owns and `update` may overwrite/merge. Everything else
-// (src/, public/, index.html, vite.config.ts, tsconfig.json, lockfile, .gitignore,
-// port-parity.json, …) is treated as user-owned and left alone. Skills aren't
-// here — they're pulled from the published repo via `pnpm skills:update`, not
-// vendored into the scaffold.
-const MANAGED = ["scripts", "docs", ".github", ".husky", "biome.json", "AGENTS.md", "CLAUDE.md"];
+// Files/dirs the template owns and `update` may overwrite/merge.
+//
+// src/components/ and stories/ are user-owned and never touched.
+// tools/ contains all viewer/router/sandbox infrastructure and IS managed.
+// Everything else (public/, index.html, vite.config.ts, tsconfig.json,
+// lockfile, .gitignore, port-parity.json, …) is also user-owned. Skills aren't here — they're pulled from the published
+// repo via `pnpm skills:update`, not vendored into the scaffold.
+const MANAGED = [
+	// Tooling
+	"scripts",
+	"docs",
+	".github",
+	".husky",
+	"biome.json",
+	"AGENTS.md",
+	"CLAUDE.md",
+	// Viewer infrastructure — all managed; src/components/ and stories/ are user-owned
+	"tools",
+	"src/main.ts",
+	"src/utilities.css",
+	// Viewer tests
+	"test",
+];
 
 const argv = process.argv.slice(2);
 const dryRun = argv.includes("--dry-run");
@@ -162,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) || "."}:`
@@ -169,13 +196,18 @@ 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(", ")}`);
 	}
 	console.log(
 		dryRun
 			? "\n(dry run — nothing written.)"
-			: "\nLeft alone: src/, public/, index.html, vite.config.ts, tsconfig.json, .gitignore.\nRun `pnpm install` then `pnpm check`. Update skills separately with `pnpm skills:update`.\n"
+			: "\nLeft alone: src/components/, stories/, public/, index.html, vite.config.ts, tsconfig.json, .gitignore.\n(tools/, src/main.ts, src/utilities.css, and test/ were refreshed above.)\nRun `pnpm install` then `pnpm check`. Update skills separately with `pnpm skills:update`.\n"
 	);
 }
 

package/package.json

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

package/template/AGENTS.md

@@ -91,10 +91,12 @@ in `boundary()`.
   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 a co-located `*.stories.ts` next to the component —
-  it appears at `/components/<slug>` automatically. 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`.
+- 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`.
 
 ## CSS scoping
 
@@ -104,7 +106,7 @@ in `boundary()`.
 - Scope any custom rule under a container class + element type (e.g.
   `.oas-frame button.oas-theme-toggle`) so it beats Obsidian's global
   `button:not(.clickable-icon)` rule and never leaks. Sandbox-only chrome lives
-  in `src/sandbox/sandbox.css`; component styling stays on Obsidian classes.
+  in `tools/sandbox/sandbox.css`; component styling stays on Obsidian classes.
 
 ## Verify before claiming done
 
@@ -126,7 +128,7 @@ is mechanical: copy the component file into the plugin's view directory and
 mount it from `ItemView.onOpen()` via `template(this.contentEl)`. If it uses
 `boundary()`/async components, add `@arrow-js/framework` to the plugin and the
 `import '@arrow-js/framework'` side-effect import. Strip any sandbox chrome
-(`src/sandbox/*`) — that stays here.
+(`tools/sandbox/*`) — that stays here.
 
 **Bring `src/utilities.css` along.** Components may use `oas-`-prefixed utility
 classes (flex, gap, padding, typography, border — all built on Obsidian's token

package/template/README.md

@@ -24,9 +24,10 @@ Then `cd my-app && pnpm install && pnpm pull-css && pnpm dev`. A freshly
 scaffolded project passes `pnpm run ci` out of the box. The initializer's
 template is generated from this repo (`pnpm create:sync`), so it never drifts.
 
-**Update an existing project's tooling** (refreshes the managed files — scripts,
-skills, docs, agent guides, CI, `biome.json` — and merges new `package.json`
-scripts/deps; never touches `src/`, `public/`, `index.html`, or build configs):
+**Update an existing project's tooling** (refreshes managed files — scripts,
+docs, CI, `biome.json`, agent guides, and the viewer/router/sandbox
+infrastructure in `src/` — merges new `package.json` scripts/deps; never
+touches `src/components/`, `stories/`, `public/`, `index.html`, or build configs):
 
 ```sh
 npx create-obsidian-arrow update            # in the project (or: update <dir>)
@@ -86,7 +87,7 @@ typecheck. CI (`.github/workflows/ci.yml`) runs the `ci` script on push/PR.
 
 ## Agent skills
 
-This repo is the source of truth for five [`skills`](https://github.com/vercel-labs/skills)-compatible
+This repo is the source of truth for seven [`skills`](https://github.com/vercel-labs/skills)-compatible
 skills under [`skills/`](skills/) — it's a skill marketplace. Scaffolds **don't
 vendor copies**; they pull from this published repo, so installs are always
 current.
@@ -143,21 +144,23 @@ with live previews.
 
 ### Add a story
 
-Create `src/components/MyThing.stories.ts` next to the component:
+Create `stories/MyThing.stories.ts` — stories live in the top-level `stories/`
+directory, keeping `src/` purely for component code:
 
 ```ts
-import { defineStories } from "../viewer/stories";
-import { MyThing } from "./MyThing";
+import { defineStories } from "../tools/viewer/stories";
+import { MyThing } from "../src/components/MyThing";
 
 export default defineStories({
 	description: "What it demonstrates.",
+	status: "draft",
 	variants: { default: () => MyThing() },
 });
 ```
 
-It appears in the sidebar and on Home automatically; the src path shown in the
-viewer is derived from the file location. Stories are sandbox-only — they never
-port to the plugin.
+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.
 
 ## Porting a component into the plugin
 

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

@@ -74,10 +74,11 @@ CONVENTIONS
   .vertical-tab-*, .modal, .mod-cta) and var(--…) tokens first; add custom CSS
   only when Obsidian has no class, scoped under a container class + element type
   (e.g. `.my-panel button.my-action`) so it beats Obsidian's global button rule.
-- Sandbox-only chrome lives in src/sandbox/* — it does NOT port to a plugin.
-- Add a demo by creating a co-located `*.stories.ts` next to the component (see
-  README "Add a story"); it appears at `/components/<slug>` automatically.
-  Browse Obsidian tokens/classes at `/reference`.
+- Sandbox-only chrome lives in tools/sandbox/* — it does NOT port to a plugin.
+- Add a story by creating `stories/MyThing.stories.ts` (top-level `stories/`
+  dir, NOT in `src/`). Import: `"../tools/viewer/stories"` and
+  `"../src/components/MyThing"`. It appears at `/components/<slug>` automatically.
+  Browse tokens at `/reference`, curated classes at `/reference/classes`.
 
 VERIFY BEFORE CLAIMING DONE
 - `pnpm typecheck && pnpm test && pnpm lint` (or `pnpm run ci` for the full chain).
@@ -92,11 +93,12 @@ components, add @arrow-js/framework to the plugin and the side-effect
 `import '@arrow-js/framework'`. Also copy src/utilities.css into the plugin once
 (all ported components share it) — components may use oas-* utility classes
 (flex, gap, padding, text, border helpers built on Obsidian's token scale).
-Leave src/sandbox/* behind. Guard against drift with the porting-parity check
+Leave tools/sandbox/* behind. Guard against drift with the porting-parity check
 (see the arrow-js-obsidian-porting skill).
 
 MAINTENANCE (existing project)
-Refresh tooling later with `npx create-obsidian-arrow update` (preserves src/),
+Refresh tooling with `npx create-obsidian-arrow update` (preserves src/components/
+and stories/ — updates viewer, router, sandbox, utilities, and tooling files),
 update skills with `pnpm skills:update`. See the obsidian-arrow-maintenance skill.
 
 Start by scaffolding, running setup steps, then read AGENTS.md and confirm

package/template/docs/prompts/update-existing.md

@@ -11,10 +11,12 @@ Update this existing Obsidian Arrow project to the latest tooling and agent
 skills. Do NOT change any of my source code.
 
 HARD CONSTRAINTS
-- Never modify src/, public/, index.html, vite.config.ts, tsconfig.json, or my
-  component/app code. Only managed tooling, skills, and docs may change.
+- Never modify src/components/, stories/, public/, index.html, vite.config.ts,
+  tsconfig.json, or my component/app code. Only managed tooling, skills, docs,
+  and the viewer/router/sandbox infrastructure in src/ may change.
 - Preview before applying anything destructive; don't commit unless I ask.
-- At the end, prove src/ was untouched (`git diff --stat` shows no src/ changes).
+- At the end, prove src/components/ and stories/ were untouched
+  (`git diff --stat` shows no changes to those paths).
 
 CONTEXT
 Scaffolded from create-obsidian-arrow. Tooling + agent skills come from the
@@ -29,12 +31,14 @@ STEPS (in order)
      project dir. If the OUTER root differs, that's where skills must be installed
      so the session's skill:// registry (repo-root + global only) can find them.
 
-2. Refresh tooling — preserves src/
+2. Refresh tooling — preserves src/components/ only
    - Preview:  npx create-obsidian-arrow update --dry-run
    - Apply:    npx create-obsidian-arrow update
    - Then:     pnpm install
-   Refreshes scripts/, docs/, .github/, .husky/, biome.json, AGENTS.md, CLAUDE.md
-   and merges package.json scripts/deps. It never touches src/, public/, or configs.
+   Refreshes scripts/, docs/, .github/, .husky/, biome.json, AGENTS.md, CLAUDE.md,
+   tools/, src/main.ts, src/utilities.css, test/,
+   and merges package.json scripts/deps. It never touches src/components/, public/,
+   index.html, vite.config.ts, tsconfig.json, or .gitignore.
 
 3. Reset agent skills to the current set
    - Audit:   npx skills list
@@ -73,6 +77,6 @@ REPORT
 - Skills are pulled from the published repo, so step 3 is location-independent for
   the *source* — only the *install location* matters (run it at the repo root the
   agent uses; reload after).
-- `npx create-obsidian-arrow update` is **create-only-safe**: it refreshes managed
-  files and merges `package.json`, but never overwrites `src/`, `public/`,
+- `npx create-obsidian-arrow update` refreshes managed files and merges
+  `package.json`, but never overwrites `src/components/`, `stories/`, `public/`,
   `index.html`, or build configs. See the `obsidian-arrow-maintenance` skill.

package/template/docs/workflow.md

@@ -49,8 +49,9 @@ Then point the agent at [`AGENTS.md`](../AGENTS.md), or brief a fresh agent with
 `skills` CLI is cwd-relative). To install them at the outer repo instead:
 `pnpm skills:install --yes --project-dir=<outer-repo>` (or `--global`).
 
-**Refresh an existing project's tooling** (scripts, skills, docs, CI — never your
-`src/`): `npx create-obsidian-arrow update` (add `--dry-run` to preview).
+**Refresh an existing project's tooling** (scripts, docs, CI, viewer/router/sandbox
+in `src/` — never `src/components/` or `stories/`):
+`npx create-obsidian-arrow update` (add `--dry-run` to preview).
 
 ## Build → verify → port loop
 
@@ -58,7 +59,7 @@ Then point the agent at [`AGENTS.md`](../AGENTS.md), or brief a fresh agent with
 # 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 src/components/MyThing.stories.ts (co-located story file)
+# 3. Add stories/MyThing.stories.ts (story file — lives in stories/, not src/)
 pnpm dev          # iterate with HMR
 #    /components          → index of all discovered stories
 #    /components/my-thing → story for MyThing
@@ -77,7 +78,7 @@ status flag, DRY patterns) see the `obsidian-arrow-stories` skill.
 **Port a component into a plugin:** copy the component file and `src/utilities.css`
 (once, shared by all ports) into the plugin. Mount from `ItemView.onOpen()` via
 `template(this.contentEl)`. If it uses `boundary()`/async, add
-`@arrow-js/framework` and `import '@arrow-js/framework'`. Leave `src/sandbox/*`
+`@arrow-js/framework` and `import '@arrow-js/framework'`. Leave `tools/sandbox/*`
 behind.
 
 ## Scaffold vs. clone

package/template/package.json

@@ -27,7 +27,11 @@
 	},
 	"dependencies": {
 		"@arrow-js/core": "^1.0.6",
-		"@arrow-js/framework": "^1.0.6"
+		"@arrow-js/framework": "^1.0.6",
+		"@codemirror/lang-markdown": "^6.5.0",
+		"@codemirror/merge": "^6.12.2",
+		"@codemirror/state": "^6.7.0",
+		"@codemirror/view": "^6.43.4"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^1.9.4",

package/template/pnpm-lock.yaml

@@ -14,6 +14,18 @@ importers:
       '@arrow-js/framework':
         specifier: ^1.0.6
         version: 1.0.6
+      '@codemirror/lang-markdown':
+        specifier: ^6.5.0
+        version: 6.5.0
+      '@codemirror/merge':
+        specifier: ^6.12.2
+        version: 6.12.2
+      '@codemirror/state':
+        specifier: ^6.7.0
+        version: 6.7.0
+      '@codemirror/view':
+        specifier: ^6.43.4
+        version: 6.43.4
     devDependencies:
       '@biomejs/biome':
         specifier: ^1.9.4
@@ -99,6 +111,36 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@codemirror/autocomplete@6.20.3':
+    resolution: {integrity: sha512-tlosUqb+3BbxCxZdu4tKeRghPFC+QM7q4X5YhKV2eCmPG+1r2F3f4AaSz5sCrFqUtX4Jh20VFTKecl16MgiV9g==}
+
+  '@codemirror/lang-css@6.3.1':
+    resolution: {integrity: sha512-kr5fwBGiGtmz6l0LSJIbno9QrifNMUusivHbnA1H6Dmqy4HZFte3UAICix1VuKo0lMPKQr2rqB+0BkKi/S3Ejg==}
+
+  '@codemirror/lang-html@6.4.11':
+    resolution: {integrity: sha512-9NsXp7Nwp891pQchI7gPdTwBuSuT3K65NGTHWHNJ55HjYcHLllr0rbIZNdOzas9ztc1EUVBlHou85FFZS4BNnw==}
+
+  '@codemirror/lang-javascript@6.2.5':
+    resolution: {integrity: sha512-zD4e5mS+50htS7F+TYjBPsiIFGanfVqg4HyUz6WNFikgOPf2BgKlx+TQedI1w6n/IqRBVBbBWmGFdLB/7uxO4A==}
+
+  '@codemirror/lang-markdown@6.5.0':
+    resolution: {integrity: sha512-0K40bZ35jpHya6FriukbgaleaqzBLZfOh7HuzqbMxBXkbYMJDxfF39c23xOgxFezR+3G+tR2/Mup+Xk865OMvw==}
+
+  '@codemirror/language@6.12.4':
+    resolution: {integrity: sha512-1q4PaT+o6PbgpkJt4Q8Fv5XJxTy4FUZ4MWETtyiDw3J0Pyr9E2vqcKL+k9wcvjNTIsauxvE7OfmWj3FRPHQ76A==}
+
+  '@codemirror/lint@6.9.7':
+    resolution: {integrity: sha512-28/+iWLYxKxsvGYhSYL7zaCZqLz5+FFFDq9tVsvGv9kv8RY4fFAchJ5WX9M3YrrRlTIsECjsXPqeNgnSmNP2dg==}
+
+  '@codemirror/merge@6.12.2':
+    resolution: {integrity: sha512-V8JvyAPjHbPupqP7BeMcsdsYCbyPij74jxIbaIJDORI+VZzW44zFmon8bF+oxGWvOKhcRmkiUMXd8MxHr3YA2w==}
+
+  '@codemirror/state@6.7.0':
+    resolution: {integrity: sha512-Zbl9NyscLMZkfXPQnNAIIAFftidrA1UbcJEIMp24C0Bukc2I5T8wJS0wsXYsnDOqCFJUeJ1BITGNs5CqPDSmSg==}
+
+  '@codemirror/view@6.43.4':
+    resolution: {integrity: sha512-YImu23iyKfncJzT7sRy+rEqEhSc8RhOHqDxwy4WzXRKJwYm6iwf/9OJk5ctCAdZ6yi2ZqaGEvmf55fSVqMDrgg==}
+
   '@csstools/color-helpers@5.1.0':
     resolution: {integrity: sha512-S11EXWJyy0Mz5SYvRmY8nJYTFFd1LCNV+7cXyAgQtOOuzb4EsgfqDufL+9esx72/eLhsRdGZwaldu/h+E4t4BA==}
     engines: {node: '>=18'}
@@ -136,6 +178,30 @@ packages:
   '@emnapi/wasi-threads@1.2.2':
     resolution: {integrity: sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==}
 
+  '@lezer/common@1.5.2':
+    resolution: {integrity: sha512-sxQE460fPZyU3sdc8lafxiPwJHBzZRy/udNFynGQky1SePYBdhkBl1kOagA9uT3pxR8K09bOrmTUqA9wb/PjSQ==}
+
+  '@lezer/css@1.3.4':
+    resolution: {integrity: sha512-N+tn9tej2hPvyKgHEApMOQfHczDJCwxrRFS3SPn9QjYN+uwHvEDnCgKRrb3mxDYxRS8sKMM8fhC3+lc04Abz5Q==}
+
+  '@lezer/highlight@1.2.3':
+    resolution: {integrity: sha512-qXdH7UqTvGfdVBINrgKhDsVTJTxactNNxLk7+UMwZhU13lMHaOBlJe9Vqp907ya56Y3+ed2tlqzys7jDkTmW0g==}
+
+  '@lezer/html@1.3.13':
+    resolution: {integrity: sha512-oI7n6NJml729m7pjm9lvLvmXbdoMoi2f+1pwSDJkl9d68zGr7a9Btz8NdHTGQZtW2DA25ybeuv/SyDb9D5tseg==}
+
+  '@lezer/javascript@1.5.4':
+    resolution: {integrity: sha512-vvYx3MhWqeZtGPwDStM2dwgljd5smolYD2lR2UyFcHfxbBQebqx8yjmFmxtJ/E6nN6u1D9srOiVWm3Rb4tmcUA==}
+
+  '@lezer/lr@1.4.10':
+    resolution: {integrity: sha512-rnCpTIBafOx4mRp43xOxDJbFipJm/c0cia/V5TiGlhmMa+wsSdoGmUN3w5Bqrks/09Q/D4tNAmWaT8p6NRi77A==}
+
+  '@lezer/markdown@1.6.4':
+    resolution: {integrity: sha512-N0SxazMj4k65DBfaf1azqtMZd6u7MqluP84/NZnB/io8Td9aleFmAhz9hcbvSfsxT5tdYlJ5qgv5aMJGY4zEtA==}
+
+  '@marijn/find-cluster-break@1.0.3':
+    resolution: {integrity: sha512-FY+MKLBoTsLNJF/eLWaOsXGdz6uh3Iu1axjPf6TUq92IYumcTcXWHoS747JARLkcdlJ/Waiaxc5wQfFO8jC6NA==}
+
   '@napi-rs/wasm-runtime@1.1.6':
     resolution: {integrity: sha512-ZLv/JdUfkvOy9eCnnBaGfiO+XimbjebAeO+MRQqD/B+FR1tnRN0tpKSJHRbE8sFfS6aqsXZ67TQjfwfsxULVbg==}
     peerDependencies:
@@ -288,6 +354,9 @@ packages:
     resolution: {integrity: sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==}
     engines: {node: '>=18'}
 
+  crelt@1.0.7:
+    resolution: {integrity: sha512-aK6BbWfhf4U/wCcLHKPJl/xa6VkVstRaPywWtMKGwuOLc/wZTyQYuoxgvZnNsBvv7Kg3YTBQYYBCggcviQczuA==}
+
   cross-spawn@7.0.6:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
@@ -648,6 +717,9 @@ packages:
     resolution: {integrity: sha512-dOESqjYr96iWYylGObzd39EuNTa5VJxyvVAEm5Jnh7KGo75V43Hk1odPQkNDyXNmUR6k+gEiDVXnjB8HJ3crXw==}
     engines: {node: '>=12'}
 
+  style-mod@4.1.3:
+    resolution: {integrity: sha512-i/n8VsZydrugj3Iuzll8+x/00GH2vnYsk1eomD8QiRrSAeW6ItbCQDtfXCeJHd0iwiNagqjQkvpvREEPtW3IoQ==}
+
   symbol-tree@3.2.4:
     resolution: {integrity: sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==}
 
@@ -731,6 +803,9 @@ packages:
       yaml:
         optional: true
 
+  w3c-keyname@2.2.8:
+    resolution: {integrity: sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==}
+
   w3c-xmlserializer@5.0.0:
     resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
     engines: {node: '>=18'}
@@ -843,6 +918,87 @@ snapshots:
   '@biomejs/cli-win32-x64@1.9.4':
     optional: true
 
+  '@codemirror/autocomplete@6.20.3':
+    dependencies:
+      '@codemirror/language': 6.12.4
+      '@codemirror/state': 6.7.0
+      '@codemirror/view': 6.43.4
+      '@lezer/common': 1.5.2
+
+  '@codemirror/lang-css@6.3.1':
+    dependencies:
+      '@codemirror/autocomplete': 6.20.3
+      '@codemirror/language': 6.12.4
+      '@codemirror/state': 6.7.0
+      '@lezer/common': 1.5.2
+      '@lezer/css': 1.3.4
+
+  '@codemirror/lang-html@6.4.11':
+    dependencies:
+      '@codemirror/autocomplete': 6.20.3
+      '@codemirror/lang-css': 6.3.1
+      '@codemirror/lang-javascript': 6.2.5
+      '@codemirror/language': 6.12.4
+      '@codemirror/state': 6.7.0
+      '@codemirror/view': 6.43.4
+      '@lezer/common': 1.5.2
+      '@lezer/css': 1.3.4
+      '@lezer/html': 1.3.13
+
+  '@codemirror/lang-javascript@6.2.5':
+    dependencies:
+      '@codemirror/autocomplete': 6.20.3
+      '@codemirror/language': 6.12.4
+      '@codemirror/lint': 6.9.7
+      '@codemirror/state': 6.7.0
+      '@codemirror/view': 6.43.4
+      '@lezer/common': 1.5.2
+      '@lezer/javascript': 1.5.4
+
+  '@codemirror/lang-markdown@6.5.0':
+    dependencies:
+      '@codemirror/autocomplete': 6.20.3
+      '@codemirror/lang-html': 6.4.11
+      '@codemirror/language': 6.12.4
+      '@codemirror/state': 6.7.0
+      '@codemirror/view': 6.43.4
+      '@lezer/common': 1.5.2
+      '@lezer/markdown': 1.6.4
+
+  '@codemirror/language@6.12.4':
+    dependencies:
+      '@codemirror/state': 6.7.0
+      '@codemirror/view': 6.43.4
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+      '@lezer/lr': 1.4.10
+      style-mod: 4.1.3
+
+  '@codemirror/lint@6.9.7':
+    dependencies:
+      '@codemirror/state': 6.7.0
+      '@codemirror/view': 6.43.4
+      crelt: 1.0.7
+
+  '@codemirror/merge@6.12.2':
+    dependencies:
+      '@codemirror/language': 6.12.4
+      '@codemirror/state': 6.7.0
+      '@codemirror/view': 6.43.4
+      '@lezer/highlight': 1.2.3
+      style-mod: 4.1.3
+
+  '@codemirror/state@6.7.0':
+    dependencies:
+      '@marijn/find-cluster-break': 1.0.3
+
+  '@codemirror/view@6.43.4':
+    dependencies:
+      '@codemirror/state': 6.7.0
+      crelt: 1.0.7
+      style-mod: 4.1.3
+      w3c-keyname: 2.2.8
+
   '@csstools/color-helpers@5.1.0': {}
 
   '@csstools/css-calc@2.1.4(@csstools/css-parser-algorithms@3.0.5(@csstools/css-tokenizer@3.0.4))(@csstools/css-tokenizer@3.0.4)':
@@ -879,6 +1035,41 @@ snapshots:
       tslib: 2.8.1
     optional: true
 
+  '@lezer/common@1.5.2': {}
+
+  '@lezer/css@1.3.4':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+      '@lezer/lr': 1.4.10
+
+  '@lezer/highlight@1.2.3':
+    dependencies:
+      '@lezer/common': 1.5.2
+
+  '@lezer/html@1.3.13':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+      '@lezer/lr': 1.4.10
+
+  '@lezer/javascript@1.5.4':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+      '@lezer/lr': 1.4.10
+
+  '@lezer/lr@1.4.10':
+    dependencies:
+      '@lezer/common': 1.5.2
+
+  '@lezer/markdown@1.6.4':
+    dependencies:
+      '@lezer/common': 1.5.2
+      '@lezer/highlight': 1.2.3
+
+  '@marijn/find-cluster-break@1.0.3': {}
+
   '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)':
     dependencies:
       '@emnapi/core': 1.11.1
@@ -986,6 +1177,8 @@ snapshots:
 
   commander@13.1.0: {}
 
+  crelt@1.0.7: {}
+
   cross-spawn@7.0.6:
     dependencies:
       path-key: 3.1.1
@@ -1326,6 +1519,8 @@ snapshots:
 
   strip-final-newline@3.0.0: {}
 
+  style-mod@4.1.3: {}
+
   symbol-tree@3.2.4: {}
 
   tinyglobby@0.2.17:
@@ -1372,6 +1567,8 @@ snapshots:
       fsevents: 2.3.3
       yaml: 2.9.0
 
+  w3c-keyname@2.2.8: {}
+
   w3c-xmlserializer@5.0.0:
     dependencies:
       xml-name-validator: 5.0.0

package/template/src/components/DiffViewer.ts

@@ -0,0 +1,42 @@
+import type { ArrowExpression } from "@arrow-js/core";
+import { markdown } from "@codemirror/lang-markdown";
+import { MergeView } from "@codemirror/merge";
+import { EditorState } from "@codemirror/state";
+
+export interface DiffViewerOptions {
+	original: string;
+	modified: string;
+	/** Which side shows original (a) and which shows modified (b). Default: a-b */
+	orientation?: "a-b" | "b-a";
+}
+
+/**
+ * CodeMirror 6 MergeView — side-by-side diff using the same CM6 engine as
+ * Obsidian's editor. Obsidian's app.css styles .cm-* classes automatically,
+ * so this looks native without additional theming.
+ *
+ * Arrow's ArrowExpression type doesn't include Node but accepts it at runtime.
+ * The cast is intentional — CM6 manages its own DOM and Arrow inserts it as-is.
+ */
+export function DiffViewer(options: DiffViewerOptions): ArrowExpression {
+	const el = document.createElement("div");
+	el.className = "oas-diff-viewer";
+
+	new MergeView({
+		a: {
+			doc: options.original,
+			extensions: [markdown(), EditorState.readOnly.of(true)],
+		},
+		b: {
+			doc: options.modified,
+			extensions: [markdown(), EditorState.readOnly.of(true)],
+		},
+		parent: el,
+		orientation: options.orientation ?? "a-b",
+		highlightChanges: true,
+		collapseUnchanged: { margin: 3, minSize: 4 },
+	});
+
+	// biome-ignore lint/suspicious/noExplicitAny: Arrow accepts Node at runtime; type doesn't include it
+	return el as unknown as ArrowExpression;
+}

package/template/src/main.ts

@@ -2,10 +2,10 @@
 // This is the one extra line a plugin would add to adopt @arrow-js/framework.
 import "@arrow-js/framework";
 
-import { startRouter } from "./router/client";
-import { applyTheme } from "./sandbox/theme";
+import { startRouter } from "../tools/router/client";
+import { applyTheme } from "../tools/sandbox/theme";
 import "./utilities.css";
-import "./sandbox/sandbox.css";
+import "../tools/sandbox/sandbox.css";
 
 applyTheme();
 

package/template/stories/DiffViewer.stories.ts

@@ -0,0 +1,75 @@
+import { DiffViewer } from "../src/components/DiffViewer";
+import { defineStories } from "../tools/viewer/stories";
+
+const ORIGINAL = `---
+title: Meeting Notes
+status: draft
+---
+
+# Team Standup
+
+Quick notes from today's standup.
+
+## Done
+
+- Reviewed the PR for the search panel
+- Fixed the token filter in the reference viewer
+
+## In Progress
+
+- Arrow component for the diff viewer
+- Documentation updates
+
+## Notes
+
+See the project board for full task breakdown.
+`;
+
+const MODIFIED = `---
+title: Meeting Notes
+status: complete
+tags: [standup, team]
+---
+
+# Team Standup — 2026-07-02
+
+Notes from today's standup.
+
+## Done
+
+- Reviewed and merged the PR for the search panel
+- Fixed the token filter in the reference viewer
+- Added DiffViewer component to the sandbox
+
+## In Progress
+
+- Documentation updates
+- Editor pane integration
+
+## Notes
+
+See the project board for full task breakdown.
+Next standup: Thursday.
+`;
+
+const SHORT_ORIGINAL = `function greet(name: string): string {
+	return "Hello, " + name;
+}
+`;
+
+const SHORT_MODIFIED = `function greet(name: string, greeting = "Hello"): string {
+	return \`\${greeting}, \${name}!\`;
+}
+`;
+
+export default defineStories({
+	description:
+		"CodeMirror 6 MergeView — side-by-side diff using the same engine as Obsidian's editor. Changed lines highlight inline; unchanged sections collapse.",
+	status: "draft",
+	variants: {
+		"markdown document": () => DiffViewer({ original: ORIGINAL, modified: MODIFIED }),
+		"code snippet": () => DiffViewer({ original: SHORT_ORIGINAL, modified: SHORT_MODIFIED }),
+		"reversed (b-a)": () =>
+			DiffViewer({ original: ORIGINAL, modified: MODIFIED, orientation: "b-a" }),
+	},
+});

package/template/{src/components → stories}/SettingsPanel.stories.ts

@@ -1,11 +1,11 @@
-import { defineStories } from "../viewer/stories";
-import { SettingsPanel } from "./SettingsPanel";
+import { SettingsPanel } from "../src/components/SettingsPanel";
+import { defineStories } from "../tools/viewer/stories";
 
 export default defineStories({
 	description: "Vertical tabs, toggles, a keyed list, and an async boundary() section.",
+	status: "live",
 	variants: {
 		default: () => SettingsPanel(),
 	},
 	children: ["toggle"],
-	status: "live",
 });

package/template/{src/components → stories}/Toggle.stories.ts

@@ -1,10 +1,11 @@
 import { reactive } from "@arrow-js/core";
-import { defineStories } from "../viewer/stories";
-import { Toggle } from "./SettingsPanel";
+import { Toggle } from "../src/components/SettingsPanel";
+import { defineStories } from "../tools/viewer/stories";
 
 export default defineStories({
 	description: "Obsidian checkbox-container toggle used by SettingsPanel.",
 	componentPath: "src/components/SettingsPanel.ts",
+	status: "live",
 	variants: {
 		interactive: () => {
 			const state = reactive({ on: true });
@@ -24,5 +25,4 @@ export default defineStories({
 			notes: "Static off state (click does nothing).",
 		},
 	},
-	status: "live",
 });

package/template/test/token-utils.test.mjs

@@ -5,7 +5,7 @@ import {
 	filterTokens,
 	groupTokens,
 	parseCustomProps,
-} from "../src/viewer/token-utils.ts";
+} from "../tools/viewer/token-utils.ts";
 
 test("parseCustomProps extracts custom property declarations from rule text", () => {
 	const css = "body.theme-dark { --text-accent: #a288ff; --size-4-2: 8px; color: red; }";

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

@@ -5,7 +5,7 @@ import {
 	kebabCase,
 	storyMetaFromGlobKey,
 	titleFromSlug,
-} from "../src/viewer/derive.ts";
+} from "../tools/viewer/derive.ts";
 
 test("kebabCase converts PascalCase and spaces/underscores", () => {
 	assert.equal(kebabCase("SettingsPanel"), "settings-panel");
@@ -19,16 +19,16 @@ test("titleFromSlug start-cases", () => {
 });
 
 test("storyMetaFromGlobKey derives slug + repo-relative paths", () => {
-	const meta = storyMetaFromGlobKey("../components/SettingsPanel.stories.ts");
+	const meta = storyMetaFromGlobKey("../../stories/SettingsPanel.stories.ts");
 	assert.equal(meta.slug, "settings-panel");
-	assert.equal(meta.storiesPath, "src/components/SettingsPanel.stories.ts");
+	assert.equal(meta.storiesPath, "stories/SettingsPanel.stories.ts");
 	assert.equal(meta.componentPath, "src/components/SettingsPanel.ts");
 });
 
 test("storyMetaFromGlobKey handles nested directories", () => {
-	const meta = storyMetaFromGlobKey("../components/chat/MessageFeed.stories.ts");
+	const meta = storyMetaFromGlobKey("../../stories/chat/MessageFeed.stories.ts");
 	assert.equal(meta.slug, "message-feed");
-	assert.equal(meta.storiesPath, "src/components/chat/MessageFeed.stories.ts");
+	assert.equal(meta.storiesPath, "stories/chat/MessageFeed.stories.ts");
 	assert.equal(meta.componentPath, "src/components/chat/MessageFeed.ts");
 });
 

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

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { defineStories, normalizeVariants, validateStoryDef } from "../src/viewer/stories.ts";
+import { defineStories, normalizeVariants, validateStoryDef } from "../tools/viewer/stories.ts";
 
 test("defineStories is an identity that preserves the def", () => {
 	const def = { variants: { default: () => "x" } };

package/template/{src → tools}/sandbox/sandbox.css

@@ -430,3 +430,45 @@ body {
 	width: auto;
 	max-width: 100%;
 }
+
+/* DiffViewer — CodeMirror 6 MergeView container */
+.oas-diff-viewer {
+	height: 480px;
+	overflow: hidden;
+	border: 1px solid var(--background-modifier-border);
+	border-radius: var(--radius-m);
+	font-family: var(--font-monospace);
+	font-size: var(--font-ui-small);
+}
+
+.oas-diff-viewer .cm-mergeView {
+	height: 100%;
+}
+
+.oas-diff-viewer .cm-editor {
+	height: 100%;
+	background: var(--background-primary);
+	color: var(--text-normal);
+}
+
+.oas-diff-viewer .cm-scroller {
+	overflow: auto;
+	font-family: var(--font-monospace);
+}
+
+.oas-diff-viewer .cm-mergeViewEditor {
+	border-right: 1px solid var(--background-modifier-border);
+}
+
+.oas-diff-viewer .cm-mergeViewEditor:last-child {
+	border-right: none;
+}
+
+.oas-diff-viewer .cm-deletedChunk {
+	background: color-mix(in srgb, var(--color-red) 15%, transparent);
+}
+
+.oas-diff-viewer .cm-insertedChunk,
+.oas-diff-viewer .cm-changedLine {
+	background: color-mix(in srgb, var(--color-green) 12%, transparent);
+}

package/template/{src → tools}/viewer/derive.ts

@@ -2,8 +2,8 @@
  * Pure derivation helpers for the component viewer. DOM-free so node:test can
  * cover them directly (via --experimental-strip-types).
  *
- * Glob keys come from import.meta.glob in src/viewer/discovery.ts, so they are
- * relative to src/viewer/ (e.g. "../components/SettingsPanel.stories.ts").
+ * Glob keys come from import.meta.glob in src/viewer/discovery.ts, relative to
+ * src/viewer/ — e.g. "../../stories/SettingsPanel.stories.ts".
  */
 
 export interface StoryPathMeta {
@@ -27,10 +27,20 @@ export function titleFromSlug(slug: string): string {
 		.join(" ");
 }
 
-/** "../components/Foo.stories.ts" → repo-relative paths + slug. */
+/**
+ * "../../stories/Foo.stories.ts" → project-relative paths + slug.
+ *
+ * Glob keys are relative to src/viewer/, so "../../" reaches the project root.
+ * Default componentPath mirrors the stories/ subtree into src/components/:
+ *   stories/Foo.stories.ts       → src/components/Foo.ts
+ *   stories/chat/Foo.stories.ts  → src/components/chat/Foo.ts
+ * Override with componentPath in the story def when the component lives elsewhere.
+ */
 export function storyMetaFromGlobKey(globKey: string): StoryPathMeta {
-	const storiesPath = `src/${globKey.replace(/^(\.\.\/|\.\/)+/, "")}`;
-	const componentPath = storiesPath.replace(/\.stories\.ts$/, ".ts");
+	const storiesPath = globKey.replace(/^(\.\.\/)+/, "");
+	const componentPath = storiesPath
+		.replace(/^stories\//, "src/components/")
+		.replace(/\.stories\.ts$/, ".ts");
 	const base = storiesPath.split("/").pop() ?? "";
 	const slug = kebabCase(base.replace(/\.stories\.ts$/, ""));
 	return { slug, storiesPath, componentPath };

package/template/{src → tools}/viewer/discovery.ts

@@ -3,10 +3,11 @@ import type { StoryDef, StoryVariant } from "./stories";
 import { normalizeVariants, validateStoryDef } from "./stories";
 
 /**
- * Discovers co-located *.stories.ts files at build time. The glob key IS the
- * file path, so src locations shown in the viewer are derived, never
- * hand-maintained. One malformed story file is skipped (with a console.warn
- * and an entry in invalidStories) — it never blanks the viewer.
+ * Discovers stories/*.stories.ts files at build time. Stories live in the
+ * top-level stories/ directory (not in src/), keeping src/ pure component code.
+ * The glob key IS the file path, so src locations shown in the viewer are
+ * derived, never hand-maintained. One malformed story file is skipped (with a
+ * console.warn and an entry in invalidStories) — it never blanks the viewer.
  */
 
 export interface DiscoveredStory {
@@ -25,7 +26,7 @@ export interface InvalidStory {
 	reason: string;
 }
 
-const modules = import.meta.glob("../components/**/*.stories.ts", { eager: true }) as Record<
+const modules = import.meta.glob("../../stories/**/*.stories.ts", { eager: true }) as Record<
 	string,
 	{ default?: unknown }
 >;