@motion-proto/live-tokens 0.14.1 → 0.16.1

package/README.md

@@ -41,7 +41,7 @@ export default defineConfig({
 
 The `themeFileApi` plugin:
 - Seeds `src/live-tokens/data/themes/` with a default theme on first dev-server start.
-- Discovers components at `src/system/components/*.svelte` and seeds `src/live-tokens/data/component-configs/{comp}/default.json` from each component's `:global(:root)` block.
+- Discovers components at `src/components/*.svelte` (and `src/system/components/*.svelte` for back-compat) and seeds `src/live-tokens/data/component-configs/{comp}/default.json` from each component's `:global(:root)` block.
 - Hosts the `/api/live-tokens/*` routes the editor uses to save and load themes + per-component configs.
 - Auto-injects `__PROJECT_ROOT__` for the overlay's "Page Source" link and `__LIVE_TOKENS_API_BASE__` so the client uses whatever `apiBase` you configured.
 
@@ -73,66 +73,79 @@ Resolution order, per folder: explicit `themeFileApi(opts)` argument > matching
 ### Bootstrap in `main.ts`
 
 ```ts
-import './styles/tokens.css';
-import {
-  configureEditor,
-  initializeTheme,
-  initCssVarSync,
-  initRouter,
-  initColumnsOverlay,
-  initEditorStore,
-} from '@motion-proto/live-tokens';
+// main.ts
+import '@motion-proto/live-tokens/app/tokens.css';
+import './live-tokens/data/tokens.generated.css';
+import '@motion-proto/live-tokens/app/fonts.css';
+import { bootLiveTokens } from '@motion-proto/live-tokens';
 import App from './App.svelte';
-import { mount } from 'svelte';
 
-configureEditor({ storagePrefix: 'my-app-' });
-
-async function boot() {
-  initCssVarSync();
-  initRouter();
-  initColumnsOverlay();
-  initEditorStore();
-  if (import.meta.env.DEV) {
-    await initializeTheme();
-  }
-  mount(App, { target: document.getElementById('app')! });
-}
+bootLiveTokens(App, '#app');
+```
+
+`bootLiveTokens` orchestrates the editor's idempotent init hooks, fetches the
+active theme in dev, optionally registers consumer-authored components, and
+mounts the app. FontAwesome is side-effect-imported by the bootstrap (the dev
+overlay always needs icons). The three token-CSS imports stay with the
+consumer because order matters and `tokens.generated.css` is project-local.
+
+Pass `components` to register consumer-authored editable components:
 
-boot();
+```ts
+import MyWidgetEditor, { allTokens as myWidgetTokens } from './components/MyWidgetEditor.svelte';
+
+bootLiveTokens(App, '#app', {
+  components: [{
+    id: 'mywidget',
+    label: 'My Widget',
+    icon: 'fas fa-magic',
+    sourceFile: 'src/components/MyWidget.svelte',
+    editorComponent: MyWidgetEditor,
+    schema: myWidgetTokens,
+  }],
+});
 ```
 
-### Mount overlay + editor pages
+### Mount routes with `<LiveTokensRouter>`
 
 ```svelte
 <!-- App.svelte -->
 <script lang="ts">
-  import { LiveEditorOverlay, ColumnsOverlay } from '@motion-proto/live-tokens';
-  import Editor from '@motion-proto/live-tokens/editor';
-  import ComponentEditorPage from '@motion-proto/live-tokens/component-editor-page';
-  import { route } from './router';
+  import { LiveTokensRouter } from '@motion-proto/live-tokens';
 </script>
 
-<LiveEditorOverlay
-  navLinks={[
-    { path: '/', label: 'Home', icon: 'fa-home' },
-    { path: '/components', label: 'Components', icon: 'fa-puzzle-piece' },
-  ]}
-  pageSources={{
-    '/': 'src/app/Home.svelte',
-  }}
-/>
-<ColumnsOverlay />
-
-{#if $route === '/editor'}
-  <Editor />
-{:else if $route === '/components'}
-  <ComponentEditorPage />
-{:else}
-  <!-- your routes -->
-{/if}
+<LiveTokensRouter pages={{
+  '/': { lazy: () => import('./Home.svelte'), label: 'Home', icon: 'fa-home', source: 'src/Home.svelte' },
+}} />
 ```
 
-`<LiveEditorOverlay />` self-gates: it only renders in dev, never inside an iframe, and never on the editor route. No need to wrap in `{#if import.meta.env.DEV}` guards.
+`<LiveTokensRouter>` owns the dev overlay (`<LiveEditorOverlay>` +
+`<ColumnsOverlay>`), the editor routes (`/editor`, `/components`), the
+in-app link-click interception, and the nav-rail/page-source plumbing the
+overlay needs. Each entry in `pages` is one of your routes; entries with a
+`label` appear in the overlay's nav rail. Pass pages as `lazy: () => import('./Page.svelte')`
+so each page's stylesheet side-effects only evaluate when that route is
+visited; pass `component: PageComponent` instead for an eagerly-imported
+page. The editor routes are dispatched internally, so you don't have to
+dynamic-import the library's editor pages yourself.
+
+You can also relocate or disable a default editor route via the
+`editorRoutes` prop: `<LiveTokensRouter pages={…} editorRoutes={{ editor: '/admin/editor', components: false }} />`.
+Pass a string to move a route; pass `false` to remove the route entirely
+(no dispatch and, for `components`, no auto-injected nav-rail entry).
+
+The whole overlay surface is dev-only and tree-shakes out of production
+builds — no `{#if import.meta.env.DEV}` guards needed.
+
+### Lower-level API (when you need it)
+
+`bootLiveTokens` and `<LiveTokensRouter>` are convenience wrappers. The
+individual init functions (`initCssVarSync`, `initRouter`,
+`initColumnsOverlay`, `initEditorStore`, `initializeTheme`),
+`<LiveEditorOverlay>`, `<ColumnsOverlay>`, and the editor page exports
+(`@motion-proto/live-tokens/editor`,
+`@motion-proto/live-tokens/component-editor-page`) all stay exported. Use
+them directly if you need a custom shell or non-standard route dispatch.
 
 ### Use components
 
@@ -199,7 +212,7 @@ export default defineConfig({
 });
 ```
 
-No `css: 'injected'` workaround, no `optimizeDeps` excludes — `vite build` works as-is. (You'll want the full `themeFileApi` plugin from the Quick install section above when you're ready to persist edits to disk.)
+No `css: 'injected'` workaround, no `optimizeDeps` excludes — `vite build` works as-is. (You'll want the full `themeFileApi` plugin and `bootLiveTokens` / `<LiveTokensRouter>` from the Quick install section above when you're ready to persist edits to disk and ship a real app.)
 
 ## Greenfield? Use the starter
 
@@ -216,25 +229,28 @@ Open http://localhost:5173 and replace `src/app/Home.svelte` with your content.
 
 ## Consumer-authored components
 
-The shipped components are first-party by default, but you can author your own and get the same real-time editing experience via `registerComponent()`. Co-locate runtime and editor files in `src/system/components/` and register the pair before mounting:
+The shipped components are first-party by default, but you can author your own and get the same real-time editing experience. Co-locate runtime and editor files in `src/components/` (or `src/system/components/`, both are scanned by default) and pass them to `bootLiveTokens`:
 
 ```ts
 // src/main.ts
-import { registerComponent } from '@motion-proto/live-tokens';
-import MyWidgetEditor, { allTokens as myWidgetTokens } from './system/components/MyWidgetEditor.svelte';
-
-registerComponent({
-  id: 'mywidget',
-  label: 'My Widget',
-  icon: 'fas fa-magic',
-  sourceFile: 'src/system/components/MyWidget.svelte',
-  editorComponent: MyWidgetEditor,
-  schema: myWidgetTokens,
+import { bootLiveTokens } from '@motion-proto/live-tokens';
+import App from './App.svelte';
+import MyWidgetEditor, { allTokens as myWidgetTokens } from './components/MyWidgetEditor.svelte';
+
+bootLiveTokens(App, '#app', {
+  components: [{
+    id: 'mywidget',
+    label: 'My Widget',
+    icon: 'fas fa-magic',
+    sourceFile: 'src/components/MyWidget.svelte',
+    editorComponent: MyWidgetEditor,
+    schema: myWidgetTokens,
+  }],
 });
-
-// then mount(App, ...)
 ```
 
+(`bootLiveTokens` calls `registerComponent` internally for each entry, gated on `import.meta.env.DEV` so the registration tree-shakes out of production builds. Call `registerComponent` directly if you need finer control over timing.)
+
 The component appears in the `/components` page under a **CUSTOM** group in the nav rail. Token rows, linked-block sharing, per-component config persistence, and reset-to-default work identically to the built-in set. All imports must come from `@motion-proto/live-tokens` or `@motion-proto/live-tokens/component-editor`; never deep-import from `src/`.
 
 ## Claude Code skills

package/dist-plugin/index.cjs

@@ -635,7 +635,7 @@ function themeFileApi(opts) {
   const GENERATED_CSS_PATH = opts.tokensGeneratedCssPath ? import_path3.default.resolve(opts.tokensGeneratedCssPath) : import_path3.default.join(dataDirs.dataDir, "tokens.generated.css");
   const FONTS_CSS_PATH = opts.fontsCssPath ? import_path3.default.resolve(opts.fontsCssPath) : import_path3.default.join(import_path3.default.dirname(CSS_PATH), "fonts.css");
   const API_BASE = opts.apiBase ?? "/api/live-tokens";
-  const consumerComponentsDir = opts.componentsSrcDir ? import_path3.default.resolve(opts.componentsSrcDir) : import_path3.default.resolve("src/system/components");
+  const consumerComponentDirs = opts.componentsSrcDir ? [import_path3.default.resolve(opts.componentsSrcDir)] : [import_path3.default.resolve("src/components"), import_path3.default.resolve("src/system/components")];
   const packageComponentsDir = import_path3.default.resolve(
     import_path3.default.dirname((0, import_node_url.fileURLToPath)(import_meta.url)),
     "..",
@@ -643,8 +643,8 @@ function themeFileApi(opts) {
     "system",
     "components"
   );
-  const COMPONENTS_SCAN_DIRS = [consumerComponentsDir];
-  if (packageComponentsDir !== consumerComponentsDir && import_fs3.default.existsSync(packageComponentsDir)) {
+  const COMPONENTS_SCAN_DIRS = [...consumerComponentDirs];
+  if (!COMPONENTS_SCAN_DIRS.includes(packageComponentsDir) && import_fs3.default.existsSync(packageComponentsDir)) {
     COMPONENTS_SCAN_DIRS.push(packageComponentsDir);
   }
   const LEGACY_PRESETS_DIR = import_path3.default.resolve("presets");
@@ -846,14 +846,24 @@ function themeFileApi(opts) {
   function componentNameFromFile(filePath) {
     return import_path3.default.basename(filePath, ".svelte").toLowerCase();
   }
+  function isThemeAwareComponent(filePath) {
+    try {
+      const source = import_fs3.default.readFileSync(filePath, "utf-8");
+      return /:global\(:root\)\s*\{/.test(source);
+    } catch {
+      return false;
+    }
+  }
   function listComponentSourcePaths() {
     const byName = /* @__PURE__ */ new Map();
     for (const dir of COMPONENTS_SCAN_DIRS) {
       if (!import_fs3.default.existsSync(dir)) continue;
       for (const f of import_fs3.default.readdirSync(dir)) {
         if (!f.endsWith(".svelte")) continue;
+        const full = import_path3.default.join(dir, f);
+        if (!isThemeAwareComponent(full)) continue;
         const name = componentNameFromFile(f);
-        if (!byName.has(name)) byName.set(name, import_path3.default.join(dir, f));
+        if (!byName.has(name)) byName.set(name, full);
       }
     }
     return Array.from(byName.values());
@@ -1695,6 +1705,7 @@ function themeFileApi(opts) {
       const normalized = import_path3.default.resolve(ctx.file);
       if (!COMPONENTS_SCAN_DIRS.some((d) => normalized.startsWith(d))) return;
       if (!normalized.endsWith(".svelte")) return;
+      if (!isThemeAwareComponent(normalized)) return;
       const comp = componentNameFromFile(normalized);
       generateDefaultConfig(comp, normalized);
     }

package/dist-plugin/index.js

@@ -598,7 +598,7 @@ function themeFileApi(opts) {
   const GENERATED_CSS_PATH = opts.tokensGeneratedCssPath ? path3.resolve(opts.tokensGeneratedCssPath) : path3.join(dataDirs.dataDir, "tokens.generated.css");
   const FONTS_CSS_PATH = opts.fontsCssPath ? path3.resolve(opts.fontsCssPath) : path3.join(path3.dirname(CSS_PATH), "fonts.css");
   const API_BASE = opts.apiBase ?? "/api/live-tokens";
-  const consumerComponentsDir = opts.componentsSrcDir ? path3.resolve(opts.componentsSrcDir) : path3.resolve("src/system/components");
+  const consumerComponentDirs = opts.componentsSrcDir ? [path3.resolve(opts.componentsSrcDir)] : [path3.resolve("src/components"), path3.resolve("src/system/components")];
   const packageComponentsDir = path3.resolve(
     path3.dirname(fileURLToPath(import.meta.url)),
     "..",
@@ -606,8 +606,8 @@ function themeFileApi(opts) {
     "system",
     "components"
   );
-  const COMPONENTS_SCAN_DIRS = [consumerComponentsDir];
-  if (packageComponentsDir !== consumerComponentsDir && fs3.existsSync(packageComponentsDir)) {
+  const COMPONENTS_SCAN_DIRS = [...consumerComponentDirs];
+  if (!COMPONENTS_SCAN_DIRS.includes(packageComponentsDir) && fs3.existsSync(packageComponentsDir)) {
     COMPONENTS_SCAN_DIRS.push(packageComponentsDir);
   }
   const LEGACY_PRESETS_DIR = path3.resolve("presets");
@@ -809,14 +809,24 @@ function themeFileApi(opts) {
   function componentNameFromFile(filePath) {
     return path3.basename(filePath, ".svelte").toLowerCase();
   }
+  function isThemeAwareComponent(filePath) {
+    try {
+      const source = fs3.readFileSync(filePath, "utf-8");
+      return /:global\(:root\)\s*\{/.test(source);
+    } catch {
+      return false;
+    }
+  }
   function listComponentSourcePaths() {
     const byName = /* @__PURE__ */ new Map();
     for (const dir of COMPONENTS_SCAN_DIRS) {
       if (!fs3.existsSync(dir)) continue;
       for (const f of fs3.readdirSync(dir)) {
         if (!f.endsWith(".svelte")) continue;
+        const full = path3.join(dir, f);
+        if (!isThemeAwareComponent(full)) continue;
         const name = componentNameFromFile(f);
-        if (!byName.has(name)) byName.set(name, path3.join(dir, f));
+        if (!byName.has(name)) byName.set(name, full);
       }
     }
     return Array.from(byName.values());
@@ -1658,6 +1668,7 @@ function themeFileApi(opts) {
       const normalized = path3.resolve(ctx.file);
       if (!COMPONENTS_SCAN_DIRS.some((d) => normalized.startsWith(d))) return;
       if (!normalized.endsWith(".svelte")) return;
+      if (!isThemeAwareComponent(normalized)) return;
       const comp = componentNameFromFile(normalized);
       generateDefaultConfig(comp, normalized);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motion-proto/live-tokens",
-  "version": "0.14.1",
+  "version": "0.16.1",
   "type": "module",
   "description": "Design token editor with live CSS variable editing. Svelte 5 + Vite 6/7.",
   "keywords": [

package/src/editor/bootstrap.ts

@@ -0,0 +1,55 @@
+/**
+ * One-call boot for a live-tokens consumer app.
+ *
+ * Bundles the five idempotent `init*` hooks that previously had to be
+ * orchestrated by every consumer (see README "Bootstrap in main.ts"), runs
+ * `initializeTheme` in dev, optionally registers custom components, and
+ * mounts the consumer's App at the target.
+ *
+ * CSS imports stay with the consumer — token CSS is order-sensitive
+ * (defaults → editor overrides → fonts) and the consumer's
+ * `tokens.generated.css` is per-project. FA icons are side-effect-imported
+ * here because the dev overlay always needs them and a consumer must not
+ * have to remember to import an icon font.
+ */
+import '@fortawesome/fontawesome-free/css/all.min.css';
+
+import { mount, type Component } from 'svelte';
+import * as cssVarSync from './core/cssVarSync';
+import * as router from './core/routing/router';
+import * as columnsOverlay from './overlay/columnsOverlay';
+import * as editorStore from './core/store/editorStore';
+import { initializeTheme } from './core/themes/themeInit';
+import { registerComponent, type RegisterComponentEntry } from './component-editor/registry';
+
+export interface BootLiveTokensOptions {
+  /** Consumer-authored components to register with the editor before mount. Dev-only. */
+  components?: RegisterComponentEntry[];
+}
+
+export async function bootLiveTokens(
+  App: Component<any, any, any>,
+  target: string | Element,
+  opts: BootLiveTokensOptions = {},
+): Promise<ReturnType<typeof mount>> {
+  cssVarSync.init();
+  router.init();
+  columnsOverlay.init();
+  editorStore.init();
+
+  if (import.meta.env.DEV) {
+    if (opts.components) {
+      for (const entry of opts.components) {
+        registerComponent(entry);
+      }
+    }
+    await initializeTheme();
+  }
+
+  const targetEl =
+    typeof target === 'string' ? document.querySelector(target) : target;
+  if (!targetEl) {
+    throw new Error(`bootLiveTokens: target ${JSON.stringify(target)} not found`);
+  }
+  return mount(App, { target: targetEl });
+}

package/src/editor/component-editor/SideNavigationEditor.svelte

@@ -39,16 +39,22 @@
   ];
 
   // --- Title --------------------------------------------------------------
+  // Title is a flex card containing the label box + toggle box. Per-state
+  // tokens drive the card chrome (surface, border, padding); stateless gap
+  // and radius live in `titleLayoutTokens` since they don't vary across
+  // default/hover/active.
   function titleStateTokens(s: StatefulState): Token[] {
     return [
       { label: 'surface color', groupKey: 'title-surface', variable: `--sidenavigation-title-${s}-surface` },
-      { label: 'divider color', groupKey: 'title-border', variable: `--sidenavigation-title-${s}-border` },
-      { label: 'divider width', canBeLinked: true, groupKey: 'title-border-width', variable: `--sidenavigation-title-${s}-border-width` },
+      { label: 'border color', groupKey: 'title-border', variable: `--sidenavigation-title-${s}-border` },
+      { label: 'border width', canBeLinked: true, groupKey: 'title-border-width', variable: `--sidenavigation-title-${s}-border-width` },
       { label: 'padding', canBeLinked: true, groupKey: 'title-padding', variable: `--sidenavigation-title-${s}-padding` },
-      { label: 'indicator color', groupKey: 'title-accent', variable: `--sidenavigation-title-${s}-accent` },
-      { label: 'indicator width', canBeLinked: true, groupKey: 'title-accent-width', variable: `--sidenavigation-title-${s}-accent-width` },
     ];
   }
+  const titleLayoutTokens: Token[] = [
+    { label: 'gap', canBeLinked: true, groupKey: 'title-gap', variable: '--sidenavigation-title-gap' },
+    { label: 'corner radius', canBeLinked: true, groupKey: 'title-radius', variable: '--sidenavigation-title-radius' },
+  ];
   function titleStateTypeGroups(s: StatefulState): TypeGroupConfig[] {
     return [{
       legend: 'title label',
@@ -59,6 +65,14 @@
       lineHeightVariable: `--sidenavigation-title-${s}-label-line-height`,
     }];
   }
+  // Title label — structural inner box (stateless, like Panel). Sits inside
+  // the title bar so the header reads as: outer bar → [label box] [toggle box].
+  const titleLabelTokens: Token[] = [
+    { label: 'surface color', groupKey: 'title-label-surface', variable: '--sidenavigation-title-label-surface' },
+    { label: 'corner radius', canBeLinked: true, groupKey: 'title-label-radius', variable: '--sidenavigation-title-label-radius' },
+    { label: 'padding', canBeLinked: true, groupKey: 'title-label-padding', variable: '--sidenavigation-title-label-padding' },
+  ];
+
   const titleTypographyTokens: Token[] = STATEFUL_STATES.flatMap((s) => [
     { label: 'font family', canBeLinked: true, groupKey: 'title-label-font-family', variable: `--sidenavigation-title-${s}-label-font-family` },
     { label: 'font size', canBeLinked: true, groupKey: 'title-label-font-size', variable: `--sidenavigation-title-${s}-label-font-size` },
@@ -168,6 +182,8 @@
   const states: Record<string, Token[]> = {
     'Panel': panelTokens,
     ...Object.fromEntries(STATEFUL_STATES.map((s) => [`Title / ${STATE_LABELS[s]}`, titleStateTokens(s)])),
+    'Title Layout': titleLayoutTokens,
+    'Title Label': titleLabelTokens,
     ...Object.fromEntries(TOGGLE_STATES.map((s) => [`Toggle / ${STATE_LABELS[s]}`, toggleStateTokens(s)])),
     ...Object.fromEntries(STATEFUL_STATES.map((s) => [`Section / ${STATE_LABELS[s]}`, sectionStateTokens(s)])),
     ...Object.fromEntries(STATEFUL_STATES.map((s) => [`Item / ${STATE_LABELS[s]}`, itemStateTokens(s)])),
@@ -196,7 +212,6 @@
     ...STATEFUL_STATES.flatMap((s): Array<[string, string]> => [
       [`--sidenavigation-title-${s}-border-width`, `title ${s}`],
       [`--sidenavigation-title-${s}-padding`, `title ${s}`],
-      [`--sidenavigation-title-${s}-accent-width`, `title ${s}`],
       [`--sidenavigation-title-${s}-label-font-family`, `title ${s}`],
       [`--sidenavigation-title-${s}-label-font-size`, `title ${s}`],
       [`--sidenavigation-title-${s}-label-font-weight`, `title ${s}`],

package/src/editor/index.ts

@@ -1,6 +1,10 @@
 export { default as LiveEditorOverlay } from './overlay/LiveEditorOverlay.svelte';
 export type { NavLink } from './core/routing/navLinkTypes';
 export { default as ColumnsOverlay } from './overlay/ColumnsOverlay.svelte';
+export { default as LiveTokensRouter } from './overlay/LiveTokensRouter.svelte';
+export type { RouteEntry, EditorRouteOverrides } from './overlay/LiveTokensRouter.svelte';
+export { bootLiveTokens } from './bootstrap';
+export type { BootLiveTokensOptions } from './bootstrap';
 
 export { columnsVisible, toggleColumns, init as initColumnsOverlay } from './overlay/columnsOverlay';
 export { configureEditor, storageKey } from './core/store/editorConfig';

package/src/editor/overlay/LiveTokensRouter.svelte

@@ -0,0 +1,165 @@
+<script module lang="ts">
+  import type { Component } from 'svelte';
+
+  /**
+   * One entry per consumer route. `label` + `icon` make it appear in the
+   * overlay's nav rail; `source` powers the "Page Source" button. Omit
+   * `label` to keep the route reachable by URL but absent from the rail
+   * (matches the existing playground/unlisted route pattern).
+   *
+   * Provide either `component` (eager) or `lazy` (code-split). Use `lazy`
+   * for any page that side-effect-imports a stylesheet at the top of its
+   * module, so those imports only evaluate when the route is visited and
+   * don't leak into unrelated routes (most importantly the editor pages).
+   */
+  export interface RouteEntry {
+    component?: Component<any, any, any>;
+    lazy?: () => Promise<{ default: Component<any, any, any> }>;
+    label?: string;
+    icon?: string;
+    source?: string;
+    /** Hide the overlay's "Page Source" button on this route. */
+    hidePageSource?: boolean;
+  }
+
+  /**
+   * Override the default editor routes (`/editor`, `/components`). Pass a
+   * string to relocate the route; pass `false` to disable it entirely (no
+   * dispatch and, for `components`, no auto-injected nav-rail entry).
+   */
+  export interface EditorRouteOverrides {
+    editor?: string | false;
+    components?: string | false;
+  }
+</script>
+
+<script lang="ts">
+  import LiveEditorOverlay from './LiveEditorOverlay.svelte';
+  import ColumnsOverlay from './ColumnsOverlay.svelte';
+  import { route, navigate } from '../core/routing/router';
+
+  interface Props {
+    pages: Record<string, RouteEntry>;
+    editorRoutes?: EditorRouteOverrides;
+  }
+
+  let { pages, editorRoutes = {} }: Props = $props();
+
+  let editorEnabled = $derived(editorRoutes.editor !== false);
+  let componentsEnabled = $derived(editorRoutes.components !== false);
+  let editorPath = $derived(typeof editorRoutes.editor === 'string' ? editorRoutes.editor : '/editor');
+  let componentsPath = $derived(typeof editorRoutes.components === 'string' ? editorRoutes.components : '/components');
+
+  const isDev = import.meta.env.DEV;
+  let isEditor = $derived(isDev && editorEnabled && $route === editorPath);
+  let isComponentEditor = $derived(isDev && componentsEnabled && $route === componentsPath);
+
+  // Pages with a label show up in the nav rail, in declaration order. In dev,
+  // the components-editor route is auto-appended so it's reachable from every
+  // page (the convention every existing live-tokens consumer has settled on).
+  let navLinks = $derived([
+    ...Object.entries(pages)
+      .filter(([, e]) => !!e.label)
+      .map(([path, e]) => ({ path, label: e.label!, icon: e.icon ?? '' })),
+    ...(isDev && componentsEnabled
+      ? [{ path: componentsPath, label: 'Components', icon: 'fa-puzzle-piece' }]
+      : []),
+  ]);
+
+  let pageSources = $derived(
+    Object.fromEntries(
+      Object.entries(pages)
+        .filter(([, e]) => !!e.source)
+        .map(([path, e]) => [path, e.source!]),
+    ),
+  );
+
+  // Components-editor route always hides the page-source button (matches the
+  // convention from the original consumer pattern).
+  let hidePageSourceOn = $derived([
+    ...Object.entries(pages)
+      .filter(([, e]) => e.hidePageSource)
+      .map(([path]) => path),
+    ...(componentsEnabled ? [componentsPath] : []),
+  ]);
+
+  // Dispatch the current route. Editor pages are dynamically imported so they
+  // don't ship in non-editor route bundles. Consumer pages dispatch via
+  // `entry.lazy()` when provided (so each page's CSS side-effect imports stay
+  // out of other routes), or via the eagerly-imported `entry.component`.
+  let pagePromise = $derived.by(() => {
+    if (isEditor) return import('../pages/Editor.svelte');
+    if (isComponentEditor) return import('../pages/ComponentEditorPage.svelte');
+    const entry = pages[$route] ?? pages['/'];
+    if (!entry) return Promise.resolve({ default: null as unknown as Component<any, any, any> });
+    if (entry.lazy) return entry.lazy();
+    if (entry.component) return Promise.resolve({ default: entry.component });
+    return Promise.resolve({ default: null as unknown as Component<any, any, any> });
+  });
+
+  // In-app link interception: turn left-clicks on internal `/...` anchors into
+  // navigate() calls so router state updates without a full reload. Modifier
+  // keys (cmd/ctrl/shift/alt) pass through to the browser's default handling.
+  function handleClick(e: MouseEvent) {
+    const anchor = (e.target as HTMLElement).closest('a[href]');
+    if (!anchor) return;
+    const href = anchor.getAttribute('href');
+    if (!href || !href.startsWith('/')) return;
+    if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    navigate(href);
+  }
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions, a11y_no_static_element_interactions -->
+<div
+  class="lt-app"
+  class:is-editor={isEditor}
+  class:is-component-editor={isComponentEditor}
+  onclick={handleClick}
+>
+  <LiveEditorOverlay {navLinks} {pageSources} {hidePageSourceOn} {editorPath} />
+  <ColumnsOverlay />
+
+  {#await pagePromise then m}
+    {@const PageComponent = m.default}
+    {#if PageComponent}
+      <PageComponent />
+    {/if}
+  {/await}
+</div>
+
+<style>
+  :global(html) {
+    scrollbar-gutter: stable;
+  }
+
+  :global(body) {
+    background: var(--page-bg);
+    background-attachment: var(--page-bg-attachment, fixed);
+  }
+
+  .lt-app {
+    width: 100%;
+    min-height: 100vh;
+    color: var(--text-primary);
+    padding-bottom: 12rem;
+    /* Set by LiveEditorOverlay when docked-open. Extends layout past the
+       fixed panel so the viewport can scroll to reveal hidden content. */
+    padding-right: var(--lt-overlay-scroll-pad, 0px);
+  }
+
+  .lt-app.is-editor {
+    padding-bottom: 0;
+    background: black;
+  }
+
+  .lt-app.is-component-editor {
+    min-height: 0;
+    height: 100vh;
+    padding-bottom: 0;
+    padding-right: 0;
+    background: black;
+    overflow: hidden;
+  }
+</style>

package/src/system/components/SideNavigation.svelte

@@ -139,28 +139,28 @@
   class:force-footer-hover={forceHoverPart === 'footer'}
   class:force-footer-active={forceActivePart === 'footer'}
 >
-  <!-- Toggle is a single persistent element. Its `left` position is
-       calc'd from the panel-width tokens so it transitions smoothly
-       between right-of-title (open) and centre-of-rail (closed) using
-       the same duration/easing tokens as the rail width. -->
-  <button
-    type="button"
-    class="sn-toggle"
-    onclick={fireToggle}
-    aria-label={open ? 'Collapse sidebar' : 'Expand sidebar'}
-    aria-expanded={open}
-  >
-    <i class="fa-solid fa-angles-right" aria-hidden="true"></i>
-  </button>
-
-  {#if open}
-    <!-- Open layout. Title bar reserves space for the persistent toggle on
-         the right; the menu is locked at the open-width so it can't reflow
-         while the rail expands around it. -->
-    <header class="sn-title" class:active={titleActive}>
+  <!-- Header is always rendered so the toggle (a child here) survives the
+       collapsed state. The label is the only conditional child — when the
+       rail is closed, the header reduces to just the toggle, centred via the
+       toggle's own `left` calc. Header stays locked to open-width regardless;
+       the aside's overflow clips it during the close animation. -->
+  <header class="sn-title" class:active={titleActive}>
+    {#if open}
       <a href={titleHref} class="sn-title-label">{titleLabel}</a>
-    </header>
+    {/if}
+
+    <button
+      type="button"
+      class="sn-toggle"
+      onclick={fireToggle}
+      aria-label={open ? 'Collapse sidebar' : 'Expand sidebar'}
+      aria-expanded={open}
+    >
+      <i class="fa-solid fa-angles-right" aria-hidden="true"></i>
+    </button>
+  </header>
 
+  {#if open}
     <div class="sn-menu">
       {#each sections as section (section.path)}
         <div class="sn-section">
@@ -228,6 +228,22 @@
     --sidenavigation-close-duration: var(--duration-150);
     --sidenavigation-close-easing: var(--ease-out-quart);
 
+    /* Title — layout (stateless). The header is a flex container that hosts
+       the label box and the toggle box side-by-side; gap and radius drive
+       the card-like outer shell. */
+    --sidenavigation-title-gap: var(--space-8);
+    --sidenavigation-title-radius: var(--radius-md);
+
+    /* Title label — structural inner box (stateless). Renders as a row inside
+       the title bar so the header reads as: outer card → [label box] [toggle
+       box]. align-items: stretch on the header equalises its height with the
+       toggle's. */
+    --sidenavigation-title-label-surface: var(--color-transparent);
+    --sidenavigation-title-label-border: var(--border-canvas-faint);
+    --sidenavigation-title-label-border-width: var(--border-width-1);
+    --sidenavigation-title-label-radius: var(--radius-md);
+    --sidenavigation-title-label-padding: var(--space-6);
+
     /* Title — default */
     --sidenavigation-title-default-surface: var(--color-transparent);
     --sidenavigation-title-default-border: var(--border-canvas-faint);
@@ -242,7 +258,7 @@
     --sidenavigation-title-default-label-line-height: var(--line-height-sm);
 
     /* Title — hover */
-    --sidenavigation-title-hover-surface: var(--surface-canvas);
+    --sidenavigation-title-hover-surface: var(--color-transparent);
     --sidenavigation-title-hover-border: var(--border-canvas-faint);
     --sidenavigation-title-hover-border-width: var(--border-width-1);
     --sidenavigation-title-hover-padding: var(--space-12);
@@ -428,34 +444,27 @@
     --_border: var(--sidenavigation-title-default-border);
     --_border-width: var(--sidenavigation-title-default-border-width);
     --_padding: var(--sidenavigation-title-default-padding);
-    --_indicator: var(--sidenavigation-title-default-accent);
-    --_indicator-width: var(--sidenavigation-title-default-accent-width);
     --_label: var(--sidenavigation-title-default-label);
     --_label-family: var(--sidenavigation-title-default-label-font-family);
     --_label-size: var(--sidenavigation-title-default-label-font-size);
     --_label-weight: var(--sidenavigation-title-default-label-font-weight);
     --_label-line-height: var(--sidenavigation-title-default-label-line-height);
 
-    /* Positioning context for the absolutely-anchored toggle button. */
-    position: relative;
+    /* The header is a pure flex row: card-like outer with the label box and
+       toggle box as siblings. No absolute positioning — the label fills with
+       flex:1, the toggle is a fixed-size sibling. justify-content: center
+       takes over when the label is removed in the collapsed state and the
+       toggle becomes the only child. */
     flex: 0 0 auto;
-    /* Lock to the open-width so the title doesn't reflow during the rail
-       expansion (3rem → 16rem on open). border-box keeps the outer width
-       equal to the token value (otherwise padding + border would push the
-       toggle past the rail's right edge). */
     box-sizing: border-box;
-    width: var(--sidenavigation-panel-open-width);
     display: flex;
-    align-items: center;
-    gap: var(--space-12);
+    align-items: stretch;
+    justify-content: center;
+    gap: var(--sidenavigation-title-gap);
     background: var(--_surface);
-    border-bottom: var(--_border-width) solid var(--_border);
-    border-left: var(--_indicator-width) solid var(--_indicator);
+    border-radius: var(--sidenavigation-title-radius);
     @include themed-padding(--_padding);
-    /* Right padding clears the absolutely-positioned toggle inside this
-       header (toggle width ~36px + 8px breathing room). */
-    padding-right: calc(var(--space-12) + 44px);
-    transition: background var(--duration-150), border-color var(--duration-150);
+    transition: background var(--duration-150);
   }
 
   .sn-title:hover:not(.active),
@@ -464,8 +473,6 @@
     --_border: var(--sidenavigation-title-hover-border);
     --_border-width: var(--sidenavigation-title-hover-border-width);
     --_padding: var(--sidenavigation-title-hover-padding);
-    --_indicator: var(--sidenavigation-title-hover-accent);
-    --_indicator-width: var(--sidenavigation-title-hover-accent-width);
     --_label: var(--sidenavigation-title-hover-label);
     --_label-family: var(--sidenavigation-title-hover-label-font-family);
     --_label-size: var(--sidenavigation-title-hover-label-font-size);
@@ -478,8 +485,6 @@
     --_border: var(--sidenavigation-title-active-border);
     --_border-width: var(--sidenavigation-title-active-border-width);
     --_padding: var(--sidenavigation-title-active-padding);
-    --_indicator: var(--sidenavigation-title-active-accent);
-    --_indicator-width: var(--sidenavigation-title-active-accent-width);
     --_label: var(--sidenavigation-title-active-label);
     --_label-family: var(--sidenavigation-title-active-label-font-family);
     --_label-size: var(--sidenavigation-title-active-label-font-size);
@@ -487,7 +492,18 @@
     --_label-line-height: var(--sidenavigation-title-active-label-line-height);
   }
 
+  /* In the collapsed state the header narrows with the rail. Drop horizontal
+     padding so the toggle (single remaining flex child) still fits in the
+     closed-width aside — open-state padding alone would push it out. */
+  .sidenavigation.collapsed .sn-title {
+    padding-left: 0;
+    padding-right: 0;
+  }
+
   .sn-title-label {
+    background: var(--sidenavigation-title-label-surface);
+    border-radius: var(--sidenavigation-title-label-radius);
+    @include themed-padding(--sidenavigation-title-label-padding);
     color: var(--_label);
     font-family: var(--_label-family);
     font-size: var(--_label-size);
@@ -495,6 +511,8 @@
     line-height: var(--_label-line-height);
     text-decoration: none;
     flex: 1 1 auto;
+    display: flex;
+    align-items: center;
     min-width: 0;
     white-space: nowrap;
     overflow: hidden;
@@ -510,62 +528,38 @@
     --_icon: var(--sidenavigation-toggle-default-icon);
     --_icon-size: var(--sidenavigation-toggle-default-icon-size);
 
-    /* Persistent element anchored to the panel (not the title). Open-state
-       `left` puts it near the right edge of the open-width title; collapsed
-       `left` centres it in the closed-width rail. Both calc'd from the
-       same width tokens so they stay in sync if the consumer overrides. */
-    position: absolute;
-    /* Toggle's outer width is derived from its constituent tokens — icon
-       + padding (both sides) + border (both sides). Stays accurate when a
-       consumer customizes any of those without re-hardcoding here. */
-    --_toggle-width: calc(
-      var(--sidenavigation-toggle-default-icon-size)
-      + 2 * var(--sidenavigation-toggle-default-padding)
-      + 2 * var(--sidenavigation-toggle-default-border-width)
-    );
-    top: var(--space-12);
-    left: calc(var(--sidenavigation-panel-open-width) - var(--_toggle-width) - var(--space-8));
-    z-index: 1;
-    transition:
-      left var(--sidenavigation-open-duration) var(--sidenavigation-open-easing),
-      background var(--duration-150),
-      border-color var(--duration-150),
-      color var(--duration-150);
-
+    /* Regular flex child of .sn-title — no absolute positioning. The header
+       row's justify-content+flex:1-on-label combo puts the toggle at the
+       right edge when the label is present and centres it when the label
+       is removed in the collapsed state. */
     display: inline-flex;
     align-items: center;
     justify-content: center;
-    flex-shrink: 0;
+    flex: 0 0 auto;
+    box-sizing: border-box;
     background: var(--_surface);
     border: var(--_border-width) solid var(--_border);
     border-radius: var(--_radius);
     color: var(--_icon);
     @include themed-padding(--_padding);
     cursor: pointer;
+    transition:
+      background var(--duration-150),
+      border-color var(--duration-150),
+      color var(--duration-150);
   }
 
   .sn-toggle i {
     font-size: var(--_icon-size);
     line-height: 1;
     /* Icon points right by default (expand). Open state flips it to point
-       left (collapse). Rotation tweens with the position so the affordance
-       morphs smoothly between the two states. */
+       left (collapse). Rotation tweens with the rail's width transition so
+       the affordance morphs smoothly between the two states. */
     transition: transform var(--sidenavigation-open-duration) var(--sidenavigation-open-easing);
   }
   .sidenavigation:not(.collapsed) .sn-toggle i {
     transform: rotate(180deg);
   }
-
-  /* Collapsed: centre the toggle in the rail, and swap to close-* timing
-     tokens so the leftward slide matches the rail's shrink. */
-  .sidenavigation.collapsed .sn-toggle {
-    left: calc((var(--sidenavigation-panel-closed-width) - var(--_toggle-width)) / 2);
-    transition:
-      left var(--sidenavigation-close-duration) var(--sidenavigation-close-easing),
-      background var(--duration-150),
-      border-color var(--duration-150),
-      color var(--duration-150);
-  }
   .sidenavigation.collapsed .sn-toggle i {
     transition: transform var(--sidenavigation-close-duration) var(--sidenavigation-close-easing);
   }