create-obsidian-arrow 0.5.0 → 0.5.2

package/template/stories/views/DiffViewer/DiffViewer.stories.ts

@@ -0,0 +1,94 @@
+import { DiffViewerView } from "../../../src/views/DiffViewer/DiffViewerView";
+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-04
+
+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 view to the sandbox
+
+## In Progress
+
+- Documentation updates
+- Editor pane integration
+
+## Notes
+
+See the project board for full task breakdown.
+Next standup: Thursday.
+`;
+
+const CODE_ORIGINAL = `function greet(name: string): string {
+\treturn "Hello, " + name;
+}
+
+const result = greet("world");
+console.log(result);
+`;
+
+const CODE_MODIFIED = `function greet(name: string, greeting = "Hello"): string {
+\treturn \`\${greeting}, \${name}!\`;
+}
+
+const result = greet("world", "Hi");
+console.log(result);
+`;
+
+export default defineStories({
+	title: "Editor / DiffViewer",
+	description:
+		"Full-pane diff editor using CodeMirror 6 MergeView. Header shows file labels and accept/reject actions. Body fills the remaining height — CM6 manages internal scrolling.",
+	status: "live",
+	kind: "view",
+	componentPath: "src/views/DiffViewer/DiffViewerView.ts",
+	variants: {
+		markdown: () =>
+			DiffViewerView({
+				original: ORIGINAL,
+				modified: MODIFIED,
+				originalLabel: "notes-draft.md",
+				modifiedLabel: "notes-revised.md",
+			}),
+		code: () =>
+			DiffViewerView({
+				original: CODE_ORIGINAL,
+				modified: CODE_MODIFIED,
+				originalLabel: "utils.ts (original)",
+				modifiedLabel: "utils.ts (modified)",
+			}),
+	},
+});

package/template/stories/views/EditorView.stories.ts

@@ -0,0 +1,55 @@
+import { html } from "@arrow-js/core";
+import { defineStories } from "../../tools/viewer/stories";
+
+export default defineStories({
+	title: "Views / Editor View",
+	description:
+		"Note/document view at readable line width. Full-bleed header + footer with the body content capped at --file-line-width via oas-readable-width. Copy this for any editor- or reader-style view; scaffold with `pnpm create:view <Name> --editor`.",
+	status: "live",
+	kind: "view",
+	surface: "editor",
+	componentPath: "src/utilities.css",
+	variants: {
+		default: () => html`
+			<div class="oas-shell-view" style="height: 420px; border: 1px dashed var(--background-modifier-border);">
+				<div class="oas-shell-view-header" style="padding: var(--size-4-2) var(--size-4-3); background: var(--background-secondary); border-bottom: 1px solid var(--background-modifier-border);">
+					Editor header (title, actions) — spans the full pane
+				</div>
+				<div class="oas-shell-view-body">
+					<div class="oas-readable-width">
+						<h1>Document title</h1>
+						<p>
+							The body content is capped at Obsidian's readable line width
+							(<code>--file-line-width</code>, 700px) and centered — the same
+							measure the markdown editor uses. Header and footer stay full-bleed.
+						</p>
+						${Array.from({ length: 4 }, (_, i) =>
+							html`<p>
+								Paragraph ${i + 1}. Long-form prose stays comfortable to read
+								because the line length never exceeds the readable measure, no
+								matter how wide the pane is dragged. Resize the panel to see the
+								column stay put while the chrome fills the width.
+							</p>`.key(i)
+						)}
+					</div>
+				</div>
+				<div class="oas-shell-view-footer" style="padding: var(--size-4-2) var(--size-4-3);">
+					Editor footer (word count, status) — spans the full pane
+				</div>
+			</div>
+		`,
+		body_only: () => html`
+			<div class="oas-shell-view" style="height: 420px; border: 1px dashed var(--background-modifier-border);">
+				<div class="oas-shell-view-body">
+					<div class="oas-readable-width">
+						<h1>Reader view</h1>
+						<p>
+							Body only — no header or footer. Content is centered at readable
+							line width, ideal for a distraction-free reader or preview pane.
+						</p>
+					</div>
+				</div>
+			</div>
+		`,
+	},
+});

package/template/stories/views/ExampleView/ExampleView.stories.ts

@@ -0,0 +1,15 @@
+import { ExampleView } from "../../../src/views/ExampleView/ExampleView";
+import { defineStories } from "../../../tools/viewer/stories";
+
+export default defineStories({
+	title: "Example / ExampleView",
+	description:
+		"Reference shell for a new view. Duplicate this folder, rename ExampleView → YourView, and replace the stub content. The oas-shell-* classes handle all layout.",
+	status: "live",
+	kind: "view",
+	componentPath: "src/views/ExampleView/ExampleView.ts",
+	variants: {
+		with_items: () => ExampleView(),
+		empty: () => ExampleView([]),
+	},
+});

package/template/stories/views/PanelView.stories.ts

@@ -0,0 +1,61 @@
+import { html } from "@arrow-js/core";
+import { defineStories } from "../../tools/viewer/stories";
+
+export default defineStories({
+	title: "Views / Panel View",
+	description:
+		"Standard view structure: header, scrollable body, pinned footer. Copy this pattern for any new view — duplicate the view folder and change names and imports.",
+	status: "live",
+	kind: "view",
+	componentPath: "src/utilities.css",
+	variants: {
+		default: () => html`
+			<div class="oas-shell-view" style="height: 320px; border: 1px dashed var(--background-modifier-border);">
+				<div class="oas-shell-view-header" style="padding: var(--size-4-2) var(--size-4-3); background: var(--background-secondary); border-bottom: 1px solid var(--background-modifier-border);">
+					View header (breadcrumbs, actions)
+				</div>
+				<div class="oas-shell-view-body" style="padding: var(--size-4-3);">
+					<p>Scrollable content area. Add more items here to see scrolling.</p>
+					${Array.from({ length: 8 }, (_, i) =>
+						html`<div class="setting-item"><div class="setting-item-info"><div class="setting-item-name">Item ${i + 1}</div></div></div>`.key(
+							i
+						)
+					)}
+				</div>
+				<div class="oas-shell-view-footer" style="padding: var(--size-4-2) var(--size-4-3);">
+					View footer (status bar, actions)
+				</div>
+			</div>
+		`,
+		body_only: () => html`
+			<div class="oas-shell-view" style="height: 320px; border: 1px dashed var(--background-modifier-border);">
+				<div class="oas-shell-view-body" style="padding: var(--size-4-3);">
+					<p>View with body only — no header or footer.</p>
+				</div>
+			</div>
+		`,
+		expanding_footer: {
+			render: () => html`
+				<div class="oas-shell-view" style="height: 320px; border: 1px dashed var(--background-modifier-border);">
+					<div class="oas-shell-view-header oas-flex oas-items-center" style="padding: 0 var(--size-4-3); background: var(--background-secondary); border-bottom: 1px solid var(--background-modifier-border);">
+						Header — pinned top at min-height (${"40px"})
+					</div>
+					<div class="oas-shell-view-body" style="padding: var(--size-4-3);">
+						<p>Body fills the space between and scrolls. The footer below holds a
+						contained component and expands past its min-height to fit it, staying
+						pinned to the bottom.</p>
+					</div>
+					<div class="oas-shell-view-footer oas-flex oas-flex-col" style="gap: var(--size-4-2); padding: var(--size-4-3); background: var(--background-secondary);">
+						<textarea class="oas-w-full" rows="3" placeholder="A composer that grows the footer…"></textarea>
+						<div class="oas-flex oas-items-center oas-justify-between">
+							<span class="setting-item-description">Footer expands for its contents</span>
+							<button class="mod-cta">Send</button>
+						</div>
+					</div>
+				</div>
+			`,
+			notes:
+				"Footer holds a multi-row component and expands past its 40px min-height while staying pinned to the bottom; the body shrinks and scrolls to give it room.",
+		},
+	},
+});

package/template/stories/views/SettingsPanel/SettingsPanel.stories.ts

@@ -0,0 +1,14 @@
+import { SettingsPanel } from "../../../src/components/SettingsPanel";
+import { defineStories } from "../../../tools/viewer/stories";
+
+export default defineStories({
+	title: "Settings / SettingsPanel",
+	description:
+		"Full settings view with vertical tabs, feature toggles, a keyed list, and an async boundary() section. The canonical reference for Obsidian settings-style views.",
+	status: "live",
+	kind: "view",
+	componentPath: "src/components/SettingsPanel.ts",
+	variants: {
+		default: () => SettingsPanel(),
+	},
+});

package/template/test/css-structure.test.mjs

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { test } from "node:test";
+import { fileURLToPath } from "node:url";
+
+/**
+ * CSS structure integrity guards.
+ *
+ * The sandbox has three CSS layers:
+ *   oasbox-*  sandbox chrome only (tools/sandbox/sandbox.css) — never port to plugin
+ *   oas-*     portable utilities (src/utilities.css) — ships with component ports
+ *   oas-diff-viewer  co-located with DiffViewer component (src/components/DiffViewer/DiffViewer.css)
+ *
+ * These tests ensure classes live in the right layer after the overhaul.
+ */
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+const utilitiesCSS = fs.readFileSync(path.join(root, "src/utilities.css"), "utf8");
+const sandboxCSS = fs.readFileSync(path.join(root, "tools/sandbox/sandbox.css"), "utf8");
+const diffViewerCSS = fs.readFileSync(
+	path.join(root, "src/components/DiffViewer/DiffViewer.css"),
+	"utf8"
+);
+
+// Strip block comments from CSS before checking selectors.
+function stripComments(css) {
+	return css.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+// ── utilities.css must contain portable classes ──────────────────────────────
+
+test("utilities.css contains portable badge classes", () => {
+	assert.ok(utilitiesCSS.includes(".oas-badge {"), "missing .oas-badge");
+	assert.ok(utilitiesCSS.includes(".oas-badge.is-live"), "missing .oas-badge.is-live");
+	assert.ok(utilitiesCSS.includes(".oas-badge.is-draft"), "missing .oas-badge.is-draft");
+});
+
+test("utilities.css contains portable card classes", () => {
+	assert.ok(utilitiesCSS.includes(".oas-card {"), "missing .oas-card");
+	assert.ok(utilitiesCSS.includes(".oas-card-header"), "missing .oas-card-header");
+	assert.ok(utilitiesCSS.includes(".oas-card-body"), "missing .oas-card-body");
+});
+
+test("utilities.css contains view/component shell classes", () => {
+	assert.ok(utilitiesCSS.includes(".oas-shell-view {"), "missing .oas-shell-view");
+	assert.ok(utilitiesCSS.includes(".oas-shell-view-body {"), "missing .oas-shell-view-body");
+	assert.ok(utilitiesCSS.includes(".oas-shell-view-header {"), "missing .oas-shell-view-header");
+	assert.ok(utilitiesCSS.includes(".oas-shell-panel {"), "missing .oas-shell-panel");
+});
+
+test("utilities.css contains EmptyState classes", () => {
+	// EmptyState CSS is co-located (src/components/EmptyState/EmptyState.css),
+	// but uses oas- prefix so it ports with the component. Verify it exists.
+	const emptyStateCSS = fs.readFileSync(
+		path.join(root, "src/components/EmptyState/EmptyState.css"),
+		"utf8"
+	);
+	assert.ok(emptyStateCSS.includes(".oas-empty-state {"), "missing .oas-empty-state");
+	assert.ok(emptyStateCSS.includes(".oas-empty-title {"), "missing .oas-empty-title");
+});
+
+// ── DiffViewer.css must be co-located ────────────────────────────────────────
+
+test("DiffViewer.css is co-located and contains .oas-diff-viewer", () => {
+	assert.ok(
+		diffViewerCSS.includes(".oas-diff-viewer {"),
+		"missing .oas-diff-viewer in DiffViewer.css"
+	);
+});
+
+// ── sandbox.css must not contain portable classes (they were moved) ───────────
+
+test("sandbox.css does not define .oas-badge (moved to utilities.css)", () => {
+	const stripped = stripComments(sandboxCSS);
+	assert.ok(
+		!stripped.includes(".oas-badge"),
+		".oas-badge must not appear in sandbox.css — it lives in utilities.css"
+	);
+});
+
+test("sandbox.css does not define .oas-card (moved to utilities.css)", () => {
+	const stripped = stripComments(sandboxCSS);
+	assert.ok(
+		!stripped.includes(".oas-card"),
+		".oas-card must not appear in sandbox.css — it lives in utilities.css"
+	);
+});
+
+test("sandbox.css does not define .oas-diff-viewer (moved to DiffViewer.css)", () => {
+	const stripped = stripComments(sandboxCSS);
+	assert.ok(
+		!stripped.includes(".oas-diff-viewer"),
+		".oas-diff-viewer must not appear in sandbox.css — it lives in DiffViewer.css"
+	);
+});
+
+// ── sandbox.css must use oasbox- prefix for all chrome class selectors ────────
+
+test("sandbox.css has no .oas- class selectors (all renamed to oasbox- or moved out)", () => {
+	const stripped = stripComments(sandboxCSS);
+	// Match lines that start a new rule with .oas- (not .oasbox-)
+	const violations = stripped
+		.split("\n")
+		.filter((line) => /^\s*\.oas-/.test(line) && !/^\s*\.oasbox-/.test(line));
+	assert.deepEqual(
+		violations,
+		[],
+		`sandbox.css chrome classes must use oasbox- prefix. oas-* is for portable utilities.\n${violations.join("\n")}`
+	);
+});

package/template/test/template-footguns.test.mjs

@@ -12,9 +12,13 @@ import { fileURLToPath } from "node:url";
  * HTML comment should appear in any of them. (Use JS // comments instead.)
  */
 
-const srcDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "src");
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const srcDir = path.join(root, "src");
+// tools/ also contains Arrow html`` templates (viewer, router, sandbox chrome)
+const toolsDir = path.join(root, "tools");
 
 function tsFiles(dir) {
+	if (!fs.existsSync(dir)) return [];
 	const out = [];
 	for (const name of fs.readdirSync(dir)) {
 		const full = path.join(dir, name);
@@ -25,14 +29,16 @@ function tsFiles(dir) {
 	return out;
 }
 
+const allTemplateDirs = [srcDir, toolsDir];
+
 test("no literal HTML comments in Arrow template modules", () => {
-	const offenders = tsFiles(srcDir).filter((file) =>
-		fs.readFileSync(file, "utf8").includes("<!--")
-	);
+	const offenders = allTemplateDirs
+		.flatMap(tsFiles)
+		.filter((file) => fs.readFileSync(file, "utf8").includes("<!--"));
 	assert.deepEqual(
-		offenders.map((f) => path.relative(srcDir, f)),
+		offenders.map((f) => path.relative(root, f)),
 		[],
-		"HTML comments break Arrow templates — move them to JS // comments"
+		"HTML comments break Arrow templates — use JS // comments instead (<!-- --> inflates expression slot count)"
 	);
 });
 
@@ -56,3 +62,76 @@ test("inline @event handlers type the param as Event, not a narrowed subtype", (
 		"Arrow @event handlers must use (e: Event), not a narrowed subtype (e.g. MouseEvent); narrow inside the handler instead"
 	);
 });
+
+/**
+ * Footgun #4 (type-level): `as unknown as ArrowTemplate` or
+ * `as unknown as ArrowExpression` double-cast. This silences TypeScript but
+ * Arrow.js 1.x does NOT support raw Node insertion in template expressions —
+ * it falls through to createTextNode(String(value)), rendering "[object HTMLDivElement]".
+ * Use queueMicrotask to mount imperative widgets (see DiffViewer.ts for the pattern).
+ */
+test("no `as unknown as Arrow*` double-cast outside DiffViewer", () => {
+	const offenders = tsFiles(srcDir).filter((file) =>
+		/as unknown as Arrow(?:Template|Expression)/.test(fs.readFileSync(file, "utf8"))
+	);
+	assert.deepEqual(
+		offenders.map((f) => path.relative(srcDir, f)),
+		[],
+		"`as unknown as ArrowTemplate/ArrowExpression` renders as [object Object] — use queueMicrotask to mount imperative widgets instead (see DiffViewer.ts)"
+	);
+});
+
+/**
+ * Footgun #5 (data): story variant render functions must not call Date.now().
+ * Story variants must be deterministic — static mock data only. Agents often
+ * inject Date.now() thinking it's fine for timestamps; it isn't: the viewer
+ * shows a different value on every render and differs from what was tested.
+ */
+const storiesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "stories");
+
+function storiesFiles(dir) {
+	if (!fs.existsSync(dir)) return [];
+	const out = [];
+	for (const name of fs.readdirSync(dir)) {
+		const full = path.join(dir, name);
+		const stat = fs.statSync(full);
+		if (stat.isDirectory()) out.push(...storiesFiles(full));
+		else if (name.endsWith(".stories.ts")) out.push(full);
+	}
+	return out;
+}
+
+test("story variants must not call Date.now()", () => {
+	const offenders = storiesFiles(storiesDir).filter((file) =>
+		fs.readFileSync(file, "utf8").includes("Date.now()")
+	);
+	assert.deepEqual(
+		offenders.map((f) => path.relative(storiesDir, f)),
+		[],
+		"Story variants must not call Date.now() — use static mock data from mock-data.ts instead"
+	);
+});
+
+/**
+ * Footgun #6 (story metadata): status must be "live" or "draft" if set.
+ * An unknown status silently causes the badge to be omitted, making the
+ * story appear as a draft without explanation.
+ */
+const VALID_STATUS = new Set(["live", "draft"]);
+
+test("story status field must be 'live', 'draft', or absent", () => {
+	const offenders = [];
+	for (const file of storiesFiles(storiesDir)) {
+		const src = fs.readFileSync(file, "utf8");
+		// Match status: "something" — catch values other than live/draft
+		const match = src.match(/\bstatus:\s*["']([^"']+)["']/);
+		if (match && !VALID_STATUS.has(match[1])) {
+			offenders.push(`${path.relative(storiesDir, file)}: status "${match[1]}"`);
+		}
+	}
+	assert.deepEqual(
+		offenders,
+		[],
+		`Story status must be "live" or "draft" (or omitted). Invalid:\n${offenders.join("\n")}`
+	);
+});

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

@@ -55,6 +55,18 @@ test("validateStoryDef rejects invalid kind", () => {
 	assert.match(r.reason, /kind/);
 });
 
+test("validateStoryDef accepts surface: panel and surface: editor", () => {
+	const base = { variants: { default: () => {} } };
+	assert.deepEqual(validateStoryDef({ ...base, surface: "panel" }), { ok: true });
+	assert.deepEqual(validateStoryDef({ ...base, surface: "editor" }), { ok: true });
+});
+
+test("validateStoryDef rejects invalid surface", () => {
+	const r = validateStoryDef({ variants: { default: () => {} }, surface: "wide" });
+	assert.equal(r.ok, false);
+	assert.match(r.reason, /surface/);
+});
+
 test("validateStoryDef accepts decorator function", () => {
 	const r = validateStoryDef({
 		variants: { default: () => {} },

package/template/tools/router/client.ts

@@ -1,6 +1,7 @@
 import { html } from "@arrow-js/core";
 import type { ArrowExpression } from "@arrow-js/core";
 import { Frame } from "../sandbox/frame";
+import { applyDefaultWidth, layoutState, pageState, startResize } from "../sandbox/layout";
 import { Shell } from "../sandbox/shell";
 import type { Page } from "./routeToPage";
 import { routeToPage } from "./routeToPage";
@@ -30,8 +31,24 @@ function getNavigation(): NavigationLike | undefined {
 	return (window as unknown as { navigation?: NavigationLike }).navigation;
 }
 
+/** Component canvas: width controlled by panel slider, content centered. */
 function ComponentCanvas(content: ArrowExpression): ArrowExpression {
-	return html`<div class="oas-component-canvas">${content}</div>`;
+	return html`
+		<div class="oasbox-component-canvas" style="${() => `width:${layoutState.width}px`}">
+			${content}
+			<div class="oasbox-resize-handle" aria-hidden="true" @mousedown="${startResize}"></div>
+		</div>
+	`;
+}
+
+/** View canvas: width controlled by panel slider, content fills full height. */
+function ViewCanvas(content: ArrowExpression): ArrowExpression {
+	return html`
+		<div class="oasbox-view-canvas" style="${() => `width:${layoutState.width}px`}">
+			${content}
+			<div class="oasbox-resize-handle" aria-hidden="true" @mousedown="${startResize}"></div>
+		</div>
+	`;
 }
 
 export function startRouter(root: HTMLElement): void {
@@ -46,15 +63,20 @@ export function startRouter(root: HTMLElement): void {
 		}
 		const page: Page = resolved;
 		document.title = page.title;
+		pageState.breadcrumb = page.breadcrumb;
+		if (page.defaultWidth !== undefined) {
+			applyDefaultWidth(page.defaultWidth);
+		}
 		root.replaceChildren();
 
 		let content: ArrowExpression;
 		if (page.sidebar && page.canvas) {
-			content = html`${page.sidebar}${Frame(page.title, page.view)}${ComponentCanvas(page.canvas)}`;
+			const canvasEl = page.viewCanvas ? ViewCanvas(page.canvas) : ComponentCanvas(page.canvas);
+			content = html`${page.sidebar}${Frame(page.view)}${canvasEl}`;
 		} else if (page.sidebar) {
-			content = html`${page.sidebar}${Frame(page.title, page.view)}`;
+			content = html`${page.sidebar}${Frame(page.view)}`;
 		} else {
-			content = Frame(page.title, page.view);
+			content = Frame(page.view);
 		}
 		Shell(content)(root);
 	};

package/template/tools/router/routeToPage.ts

@@ -1,10 +1,12 @@
 import { html } from "@arrow-js/core";
 import type { ArrowExpression } from "@arrow-js/core";
 import { Home } from "../sandbox/home";
+import { EDITOR_DEFAULT_WIDTH, PANEL_DEFAULT_WIDTH } from "../sandbox/layout";
 import { ClassesPage } from "../viewer/ClassesPage";
 import { ComponentsIndex } from "../viewer/ComponentsIndex";
-import { StoryPageCanvas, StoryPageDetails, StoryPageView } from "../viewer/StoryPage";
+import { StoryPageCanvas, StoryPageDetails } from "../viewer/StoryPage";
 import { TokensPage } from "../viewer/TokensPage";
+import { ViewsIndex } from "../viewer/ViewsIndex";
 import { findStory } from "../viewer/discovery";
 import { ViewerSidebar } from "../viewer/sidebar";
 
@@ -17,9 +19,16 @@ import { ViewerSidebar } from "../viewer/sidebar";
 export interface Page {
 	status: number;
 	title: string;
+	/** Short breadcrumb shown in the toolbar (no app-name suffix). */
+	breadcrumb: string;
 	view: ArrowExpression;
 	sidebar?: ArrowExpression;
 	canvas?: ArrowExpression;
+	/** When true the canvas renders full-height (view story), not centered (component story). */
+	viewCanvas?: boolean;
+	/** Preferred initial pane width for this route (sandbox chrome). Applied by
+	 * the client router until the tester drags the resize handle. */
+	defaultWidth?: number;
 }
 
 export interface Redirect {
@@ -32,8 +41,9 @@ function notFound(pathname: string): Page {
 	return {
 		status: 404,
 		title: `Not found · ${APP_NAME}`,
+		breadcrumb: "Not found",
 		view: html`
-			<div class="oas-settings">
+			<div class="oasbox-settings">
 				<div class="setting-item setting-item-heading">
 					<div class="setting-item-info">
 						<div class="setting-item-name">Not found</div>
@@ -51,7 +61,7 @@ export function routeToPage(url: string): Page | Redirect {
 	const { pathname, searchParams } = new URL(url, window.location.origin);
 
 	if (pathname === "/" || pathname === "") {
-		return { status: 200, title: APP_NAME, view: Home() };
+		return { status: 200, title: APP_NAME, breadcrumb: APP_NAME, view: Home() };
 	}
 
 	if (pathname === "/example") {
@@ -62,11 +72,22 @@ export function routeToPage(url: string): Page | Redirect {
 		return {
 			status: 200,
 			title: `Components · ${APP_NAME}`,
+			breadcrumb: "Components",
 			view: ComponentsIndex(),
 			sidebar: ViewerSidebar(pathname),
 		};
 	}
 
+	if (pathname === "/views" || pathname === "/views/") {
+		return {
+			status: 200,
+			title: `Views · ${APP_NAME}`,
+			breadcrumb: "Views",
+			view: ViewsIndex(),
+			sidebar: ViewerSidebar(pathname),
+		};
+	}
+
 	const storyMatch = pathname.match(/^\/components\/([^/]+)$/);
 	if (storyMatch) {
 		const story = findStory(storyMatch[1]);
@@ -75,22 +96,15 @@ 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}`,
+			breadcrumb: story.title,
 			view: StoryPageDetails(story, variantName),
 			sidebar: ViewerSidebar(`/components/${story.slug}`),
 			canvas: StoryPageCanvas(story, variantName),
+			viewCanvas: story.kind === "view",
+			defaultWidth: story.surface === "editor" ? EDITOR_DEFAULT_WIDTH : PANEL_DEFAULT_WIDTH,
 		};
 	}
 
@@ -98,6 +112,7 @@ export function routeToPage(url: string): Page | Redirect {
 		return {
 			status: 200,
 			title: `Tokens · ${APP_NAME}`,
+			breadcrumb: "Tokens",
 			view: TokensPage(),
 			sidebar: ViewerSidebar(pathname),
 		};
@@ -107,6 +122,7 @@ export function routeToPage(url: string): Page | Redirect {
 		return {
 			status: 200,
 			title: `Classes · ${APP_NAME}`,
+			breadcrumb: "Classes",
 			view: ClassesPage(),
 			sidebar: ViewerSidebar(pathname),
 		};