create-obsidian-arrow 0.5.1 → 0.5.2

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),
 		};

package/template/tools/sandbox/frame.ts

@@ -1,35 +1,15 @@
 import { html } from "@arrow-js/core";
 import type { ArrowExpression, ArrowTemplate } from "@arrow-js/core";
-import { layoutState, startResize } from "./layout";
-import { themeState, toggleTheme } from "./theme";
 
 /**
- * Wraps a route view in an Obsidian workspace-leaf shell so the sandbox looks
- * like a real side-panel view. Uses Obsidian's own layout classes
- * (.workspace-leaf, .view-header, .view-content) so the chrome is styled by
- * app.css. Width is driven by reactive layout state (toolbar slider / presets /
- * the edge drag handle); height fills the stage.
+ * Story details frame — fixed-width left panel showing story metadata
+ * (REFERENCES, VARIANTS, etc.). This is sandbox chrome, not an Obsidian leaf.
  *
- * Sandbox chrome only — the route view mounted inside is what ports to a plugin.
+ * No view-header here: the breadcrumb lives in the top toolbar, and the right
+ * canvas shows whatever view-header the story component defines.
  */
-export const Frame = (title: string, content: ArrowExpression): ArrowTemplate => html`
-	<div class="workspace-leaf oas-frame" style="${() => `width:${layoutState.width}px`}">
-		<div class="workspace-leaf-content" data-type="arrow-sandbox">
-			<div class="view-header">
-				<div class="oas-view-header-left">
-					<a class="clickable-icon oas-home" href="/" aria-label="Examples">⌂</a>
-					<div class="view-header-title">${title}</div>
-				</div>
-				<div class="view-actions">
-					<button
-						class="clickable-icon oas-theme-toggle"
-						aria-label="Toggle theme"
-						@click="${toggleTheme}"
-					>${() => (themeState.theme === "theme-dark" ? "☾" : "☀")}</button>
-				</div>
-			</div>
-			<div class="view-content oas-view-content">${content}</div>
-		</div>
-		<div class="oas-resize-handle" aria-hidden="true" @mousedown="${startResize}"></div>
+export const Frame = (content: ArrowExpression): ArrowTemplate => html`
+	<div class="oasbox-frame">
+		<div class="oasbox-view-content">${content}</div>
 	</div>
 `;

package/template/tools/sandbox/home.ts

@@ -30,6 +30,7 @@ const GETTING_STARTED = [
 
 const VIEWS = [
 	{ label: "Components", path: "/components", note: "Component story viewer" },
+	{ label: "Views", path: "/views", note: "Full-pane view stories" },
 	{ label: "Tokens", path: "/reference", note: "CSS custom property reference" },
 	{ label: "Classes", path: "/reference/classes", note: "Obsidian class catalog" },
 ];
@@ -38,7 +39,7 @@ export const Home = component((): ArrowTemplate => {
 	setTimeout(recheck, 250);
 
 	return 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">Obsidian Arrow Sandbox</div>
@@ -63,7 +64,7 @@ export const Home = component((): ArrowTemplate => {
 						style="${() =>
 							`color: ${stylingLoaded() ? "var(--text-success)" : "var(--text-error)"}; font-weight: var(--font-semibold);`}"
 					>${() => (stylingLoaded() ? "READY" : "MISSING")}</span>
-					<button class="oas-recheck" @click="${recheck}">Re-check</button>
+					<button class="oasbox-recheck" @click="${recheck}">Re-check</button>
 				</div>
 			</div>
 
@@ -88,7 +89,7 @@ export const Home = component((): ArrowTemplate => {
 				<span class="oas-card-chevron">›</span>
 			</div>
 			<div class="oas-card-body">
-				<div class="oas-settings">
+				<div class="oasbox-settings">
 					${GETTING_STARTED.map((step) =>
 						html`
 							<div class="setting-item">
@@ -108,13 +109,7 @@ export const Home = component((): ArrowTemplate => {
 			</div>
 		</div>
 
-		<div class="oas-settings">
-			<div class="setting-item setting-item-heading">
-				<div class="setting-item-info">
-					<div class="setting-item-name">Views</div>
-					<div class="setting-item-description">Main pages in this sandbox.</div>
-				</div>
-			</div>
+		<div class="oasbox-settings">
 			${VIEWS.map((view) =>
 				html`
 					<div class="setting-item">
@@ -125,7 +120,7 @@ export const Home = component((): ArrowTemplate => {
 							<div class="setting-item-description">${view.note}</div>
 						</div>
 						<div class="setting-item-control">
-							<a class="mod-cta oas-open-link" href="${view.path}">Open</a>
+							<a class="mod-cta oasbox-open-link" href="${view.path}">Open</a>
 						</div>
 					</div>
 				`.key(view.label)

package/template/tools/sandbox/layout.ts

@@ -6,9 +6,30 @@ import { reactive } from "@arrow-js/core";
  * chrome — not ported into the plugin.
  */
 export const MIN_WIDTH = 240;
-export const WIDTH_PRESETS = [280, 360, 480, 640];
+export const WIDTH_PRESETS = [280, 360, 480, 640, 800];
 
-export const layoutState = reactive<{ width: number }>({ width: 420 });
+/** Sensible starting pane width per view chrome. Editor (readable-line-width)
+ * views need a pane wider than --file-line-width (700px) for the centering to
+ * be visible; panels open at the standard side-panel width. */
+export const PANEL_DEFAULT_WIDTH = 420;
+export const EDITOR_DEFAULT_WIDTH = 820;
+
+/** `userAdjusted` flips true the first time the tester drags the handle; after
+ * that we stop applying per-page defaults so their chosen width sticks. */
+export const layoutState = reactive<{ width: number; userAdjusted: boolean }>({
+	width: PANEL_DEFAULT_WIDTH,
+	userAdjusted: false,
+});
+
+/** Apply a route's preferred default width, unless the tester has taken over. */
+export function applyDefaultWidth(px: number): void {
+	if (!layoutState.userAdjusted) {
+		setWidth(px);
+	}
+}
+
+/** Current page breadcrumb shown in the toolbar. Updated by the client router. */
+export const pageState = reactive<{ breadcrumb: string }>({ breadcrumb: "" });
 
 function maxWidth(): number {
 	return Math.max(MIN_WIDTH, window.innerWidth);
@@ -22,6 +43,7 @@ export function setWidth(px: number): void {
  * binds directly to Arrow's `@mousedown` handler signature. */
 export function startResize(event: Event): void {
 	event.preventDefault();
+	layoutState.userAdjusted = true;
 	const startX = (event as MouseEvent).clientX;
 	const startWidth = layoutState.width;