@motion-proto/live-tokens 0.34.0 → 0.36.0

package/.claude/skills/live-tokens-build-page/SKILL.md

@@ -8,7 +8,7 @@ description: Apply the @motion-proto/live-tokens project conventions when buildi
 Two rules above all else:
 
 1. **Use a shipped component if one fits.** Import from `@motion-proto/live-tokens/components/<Name>.svelte`. See [[live-tokens-pick-component]] for the catalogue and the confusing-pair decisions. Author custom markup only when nothing fits, and then consider [[live-tokens-create-component]] so the new piece is editable too.
-2. **Use theme tokens for every value.** Every color, spacing, radius, font-size, and font-family in page CSS is a `var(--token-*)`. No hex literals. No pixel literals. A change in `/editor` should repaint your page.
+2. **Use theme tokens for every value.** Every color, spacing, radius, font-size, and font-family in page CSS is a `var(--token-*)`. No hex literals. No pixel literals. A change in `/live-tokens/editor` should repaint your page.
 
 ## Layout
 
@@ -28,10 +28,10 @@ To place children at specific page-column positions, span the parent grid (`grid
 
 - Hex or pixel literals in page CSS.
 - Hardcoded column counts (`repeat(10, 1fr)`). Use `repeat(var(--columns-count), 1fr)`.
-- Utility classes overriding shipped components. Extend via the `/components` editor instead.
+- Utility classes overriding shipped components. Extend via the `/live-tokens/components` editor instead.
 - Deep imports from `node_modules/@motion-proto/live-tokens/src/...`. Use public entry points only.
 - Mounting `Editor` or `ComponentEditorPage` outside their dedicated routes.
 
 ## Verify
 
-In dev: change a colour in `/editor` and confirm your page repaints (proves token usage). The overlay's "Page Source" button on the new route opens the page in VS Code (proves the route's `source`). `ColumnsOverlay` (Cmd+G) shows content sitting inside `--columns-max-width`.
+In dev: change a colour in `/live-tokens/editor` and confirm your page repaints (proves token usage). The overlay's "Page Source" button on the new route opens the page in VS Code (proves the route's `source`). `ColumnsOverlay` (Cmd+G) shows content sitting inside `--columns-max-width`.

package/.claude/skills/live-tokens-create-component/SKILL.md

@@ -5,7 +5,7 @@ description: Author a brand-new editable component for a @motion-proto/live-toke
 
 # Authoring a component for a live-tokens project
 
-This skill teaches you how to add a new editable component to a project that consumes `@motion-proto/live-tokens`. The end state: a runtime Svelte file, an editor Svelte file, one `registerComponent()` call, and a `/components` page entry under the **CUSTOM** group with full token editing, linked-block sharing, and persistence.
+This skill teaches you how to add a new editable component to a project that consumes `@motion-proto/live-tokens`. The end state: a runtime Svelte file, an editor Svelte file, one `registerComponent()` call, and a `/live-tokens/components` page entry under the **CUSTOM** group with full token editing, linked-block sharing, and persistence.
 
 ## Worked examples ship inside the package
 
@@ -44,7 +44,7 @@ For pattern reference, read any shipped component's source directly from the con
    ```
    The schema side-effect happens inside `registerComponent` (which `bootLiveTokens` calls for you), so you don't call `registerComponentSchema` separately. **Do not place a standalone `registerComponent(...)` *before* `bootLiveTokens`** — that registers before the editor's init hooks run, which is the wrong window and can leave editor changes disconnected from the live page. Only call `registerComponent` directly if your app mounts manually (no `bootLiveTokens`), in which case call it before `mount(App, ...)`.
 4. **Tell the picker** — open `.claude/skills/live-tokens-pick-component/SKILL.md` and add your new component to the **Catalogue** line under the family it belongs to (Action / Input / Selection / Containers / Messaging / Display). If it's confusable with an existing component (a second selection control, a competing container), add a row to that family's decision table explaining the use-case it owns. Without this step, the component exists but [[live-tokens-pick-component]] can't recommend it when a user asks "which component should I use?" — the same rule applies whether the component is first-party (update the picker shipped in this package) or consumer-authored (update the local copy at `.claude/skills/live-tokens-pick-component/SKILL.md` that `setup-claude` placed in your project).
-5. **Verify** — open `/components` and run the verification checklist at the bottom of this file.
+5. **Verify** — open `/live-tokens/components` and run the verification checklist at the bottom of this file.
 
 ## Token discipline
 
@@ -559,7 +559,7 @@ A new first-party component is auto-covered the moment it lands in `builtInRegis
 
 **If your component declares `intrinsics`, the intrinsics contract test covers it too.** `src/editor/component-editor/intrinsicsContract.test.ts` iterates every entry with an `intrinsics` array and asserts, per (intrinsic, variant), that the runtime `:global(:root)` declares a default, the default is one of the spec's `values`, and the editor's `default` equals the runtime default. This is what would have caught a getter defaulting to `center` while `:global(:root)` says `start`. Same auto-coverage rule: declare `intrinsics` on the registry entry and the test picks it up.
 
-Finally navigate to `/components` and confirm the runtime behaviours no static check can see:
+Finally navigate to `/live-tokens/components` and confirm the runtime behaviours no static check can see:
 
 - [ ] The new component appears in the nav rail under the **CUSTOM** group (system entries above, custom below the labeled divider).
 - [ ] Token rows render. Color pickers, radius selectors, font selectors all work.

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.36.0 — ImageLightbox `capNatural`: stop upscaling small sources
+
+### Added
+
+- **`ImageLightbox` gains a `capNatural` prop.** By default the modal opens
+  fitted to the viewport, which upscales a small source (e.g. a low-res GIF or
+  screenshot) until it looks soft. Set `capNatural` and the open fit is clamped
+  to the source's natural resolution (100%, 1 source px = 1 screen px), so small
+  images stay crisp while larger ones fit the viewport exactly as before. It only
+  bounds the initial open; pair it with `maxZoom={1}` to also stop the `extended`
+  zoom controls from magnifying past 100%. Needs the natural pixel size (from
+  `width`/`height` or the loaded image) — until that's known the image fits the
+  viewport, then snaps to the cap once measured.
+
+## 0.35.0 — Dev routes moved to a reserved `/live-tokens/*` namespace
+
+### Changed (breaking)
+
+- **The package's dev-only routes moved under a reserved `/live-tokens/*`
+  namespace:** `/editor` → `/live-tokens/editor`, `/components` →
+  `/live-tokens/components`, `/docs` → `/live-tokens/docs`. These routes are
+  `import.meta.env.DEV`-only and never appear in production, so the longer paths
+  cost nothing where users actually see URLs. Reserving a namespace means a
+  consumer's own `/docs` or `/components` page no longer collides with a package
+  route, and any owned route added in a future release stays inside the namespace
+  (no surprise collisions on a version bump). Relocate or disable any of them via
+  the `editorRoutes` prop exactly as before.
+
+### Fixed
+
+- **A consumer page at `/docs` or `/components` no longer crashes the app.** The
+  package auto-injected nav entries at those paths; a consumer page at the same
+  path produced a duplicate key in the overlay's keyed nav list and threw an
+  uncaught error, and silently shadowed the consumer's page at dispatch. With the
+  reserved namespace the collision cannot occur, so `editorRoutes.docs = false`
+  is no longer needed to dodge it.
+- **`editorRoutes.components` relocation now also moves the overlay's
+  components-view pairing**, which previously compared a hardcoded `/components`.
+
+### Migrating
+
+- **`npx live-tokens migrate` now flags hardcoded route references.** If your
+  source navigates to the old paths (e.g. `navigate('/editor')` from the old
+  scaffold, or `<a href="/components">`), `migrate` reports each one with its
+  file, line, and suggested `/live-tokens/*` replacement. Add `--write` to
+  rewrite the unambiguous ones automatically. `/docs` is never auto-rewritten
+  (you likely own that route), and any path you declare in `pages` or relocate
+  via `editorRoutes` is left for manual review. The editor stays reachable via
+  the dev overlay regardless, so this only affects hardcoded shortcut links.
+
 ## 0.34.0 — Token-as-API contract guardrail; opt-in autoMigrate
 
 ### Added

package/README.md

@@ -8,8 +8,8 @@ A foundational design system for quickly styling and building Svelte + Vite micr
 
 - **Real-time token editing.** Pick a color, drag a hue slider, retype a font size — the page repaints on every input event via CSS-variable writes. No reload, no save-and-refresh, no build step. Works across colors, typography, spacing, radii, shadows, motion, palettes, and gradients.
 - **Real-time component editing.** Each of ~24 shipped Svelte components (Button, Input, Card, Dialog, Badge, Callout, Table, Tooltip, Toggle, TabBar, SegmentedControl, RadioButton, MenuSelect, ProgressBar, CornerBadge, SectionDivider, CollapsibleSection, Notification, Image, ImageLightbox, CodeSnippet, SideNavigation, and more) declares its own design-token aliases in a `:global(:root)` block. Rewire any alias from a per-component picker and see that component update everywhere it's used — live, on your real pages, not in a Storybook sandbox.
-- **Theme editor** (`/editor` route, dev-only) — the home of real-time token editing. Save themes to disk as JSON, promote one to "production" to bake it into a static `tokens.css` for the build.
-- **Per-component editor** (`/components` route, dev-only) — the home of real-time component-alias editing. Pick token aliases per component without writing CSS.
+- **Theme editor** (`/live-tokens/editor` route, dev-only) — the home of real-time token editing. Save themes to disk as JSON, promote one to "production" to bake it into a static `tokens.css` for the build.
+- **Per-component editor** (`/live-tokens/components` route, dev-only) — the home of real-time component-alias editing. Pick token aliases per component without writing CSS.
 - **Live editor overlay** — pins to the top-right of every dev page. Opens the editor in a side panel or floating window so you edit *on the page you're styling*, not in a separate tab. Includes a "Page Source" button that opens the current page's `.svelte` file in VS Code.
 - **Manifests** — a manifest captures a whole site configuration as one portable artifact: the theme in one slot, every component in its own slot, each holding either the shipped default or a custom file. Export it as a bundle and import it into another project to restore the full styling in one step.
 - **Vite plugin** — hosts the `/api/live-tokens/{themes,component-configs,manifests}/*` routes that persist your edits to disk as you make them. The single namespace keeps live-tokens' routes from colliding with anything your app serves under `/api`.
@@ -122,7 +122,7 @@ bootLiveTokens(App, '#app', {
 ```
 
 `<LiveTokensRouter>` owns the dev overlay (`<LiveEditorOverlay>` +
-`<ColumnsOverlay>`), the editor routes (`/editor`, `/components`, `/docs`), the
+`<ColumnsOverlay>`), the editor routes (`/live-tokens/editor`, `/live-tokens/components`, `/live-tokens/docs`), 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')`
@@ -307,7 +307,7 @@ bootLiveTokens(App, '#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/`.
+The component appears in the `/live-tokens/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
 
@@ -345,7 +345,7 @@ It enforces the file layout, `:global(:root)` block, token-suffix vocabulary, th
 
 ## How the editor ships changes to prod
 
-1. Edit in `/editor` or `/components`. Saves write to `<dataDir>/themes/{name}.json` and `<dataDir>/component-configs/{comp}/{name}.json`.
+1. Edit in `/live-tokens/editor` or `/live-tokens/components`. Saves write to `<dataDir>/themes/{name}.json` and `<dataDir>/component-configs/{comp}/{name}.json`.
 2. Promote a theme to "production." Its variables are written into `tokens.generated.css` next to your authored `tokens.css`.
 3. `npm run build` bundles both as plain CSS. No editor code, no JSON lookups, no dev surfaces ship to prod.
 

package/bin/cli.mjs

@@ -11,6 +11,7 @@ import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 import { checkComponent, formatReport } from './check-component.mjs';
 import { runMigrate, formatMigrateResult } from './migrate.mjs';
+import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
 
 const USAGE = `Usage: npx @motion-proto/live-tokens <command> [options]
@@ -21,10 +22,15 @@ Commands:
   setup-claude [--force]      Install bundled Claude Code skills into ./.claude/skills/
   check-component <id>        Validate <id>'s runtime, editor, and registration
                               against the live-tokens-create-component contract
-  migrate [--check] [--tokens <path>]
-                              Reconcile your tokens.css with the installed
-                              package's Layer-1 token vocabulary. --check reports
-                              without writing (exit 1 if changes are needed).
+  migrate [--check] [--write] [--tokens <path>]
+                              Reconcile your project with the installed package:
+                              applies additive tokens.css migrations (unless
+                              --check), and reports source references to the
+                              editor/components/docs routes that moved to
+                              /live-tokens/* in 0.35.0. --write also rewrites the
+                              unambiguous route references (never /docs). --check
+                              reports without writing (exit 1 if token migrations
+                              are pending; route findings are advisory).
 `;
 
 function fail(message, code = 1) {
@@ -67,13 +73,21 @@ if (command === 'check-component') {
 
 if (command === 'migrate') {
   const check = rest.includes('--check');
+  const write = rest.includes('--write');
   const tokensIdx = rest.indexOf('--tokens');
   const tokensArg = tokensIdx !== -1 ? rest[tokensIdx + 1] : undefined;
   if (tokensIdx !== -1 && !tokensArg) fail(`--tokens requires a path`);
   try {
     const result = await runMigrate({ tokensArg, check });
     console.log(formatMigrateResult(result, { check }));
-    // Exit 1 when --check finds pending changes (CI-friendly) or on no-path.
+
+    // Route-reference pass: advisory by default, rewrites the unambiguous hits
+    // only with --write (and never under --check).
+    const routes = runMigrateRoutes({ root: process.cwd(), apply: write && !check });
+    const routeOut = formatRouteResult(routes, { check });
+    if (routeOut) console.log('\n' + routeOut);
+
+    // Route findings are advisory; only token migrations gate the exit code.
     if (result.status === 'no-path') process.exit(1);
     if (check && result.status === 'would-change') process.exit(1);
     process.exit(0);

package/bin/migrate-routes.mjs

@@ -0,0 +1,179 @@
+// `live-tokens migrate` route-reference pass (0.35.0 namespace move).
+//
+// The package's dev-only routes moved to a reserved `/live-tokens/*` namespace,
+// so consumer source that hardcoded `/editor`, `/components`, or `/docs` (e.g.
+// `navigate('/editor')` from the old scaffold) now 404s. This scans the
+// consumer's source and reports those references; with `apply`, it rewrites the
+// unambiguous ones.
+//
+// Safety: `/docs` is never auto-rewritten (consumers commonly own a docs page),
+// and any path the project declares as its own (a `pages` key) or manages via
+// `editorRoutes` is left as an advisory. A reference is rewritten only when the
+// package definitely owns that path.
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+
+const MOVED = [
+  { old: '/editor', next: '/live-tokens/editor' },
+  { old: '/components', next: '/live-tokens/components' },
+  { old: '/docs', next: '/live-tokens/docs' },
+];
+
+// Never auto-rewritten: a consumer's own docs page is the common case, and we
+// can't tell their `/docs` from the package's without guessing.
+const NEVER_AUTOWRITE = new Set(['/docs']);
+
+const SCAN_EXTS = new Set(['.svelte', '.ts', '.js', '.mjs', '.tsx', '.jsx']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'dist-plugin', '.git', '.svelte-kit', 'build']);
+
+function walk(dir, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walk(join(dir, e.name), out);
+    } else if (SCAN_EXTS.has(extname(e.name))) {
+      out.push(join(dir, e.name));
+    }
+  }
+  return out;
+}
+
+// `navigate('/p')` / `navigate("/p")` / `navigate(`/p`)` and the href forms
+// `href="/p"` / `href='/p'` / `href={'/p'}`. The closing backreference quote
+// pins the path to the exact string, so `/live-tokens/editor` never matches
+// `/editor` (the char before `/editor` there is `s`, not a quote).
+function refRegex(oldPath) {
+  return new RegExp(`(navigate\\(\\s*|href\\s*=\\s*\\{?\\s*)(['"\`])${oldPath}\\2`, 'g');
+}
+
+function kindOf(prefix) {
+  return prefix.trimStart().startsWith('href') ? 'href' : 'navigate';
+}
+
+/**
+ * A path is the consumer's, not the package's, if they declare a page at it
+ * (`'/x':` in a pages map) or name it in an `editorRoutes` override. Conservative
+ * by design: when unsure we mark it owned, which only ever downgrades a rewrite
+ * to an advisory.
+ */
+function detectConsumerOwned(files) {
+  const owned = new Set();
+  for (const file of files) {
+    const c = readFileSync(file, 'utf8');
+    const hasEditorRoutes = /editorRoutes/.test(c);
+    for (const { old } of MOVED) {
+      const key = old.slice(1);
+      if (new RegExp(`['"]\\/${key}['"]\\s*:`).test(c)) owned.add(old);
+      if (hasEditorRoutes && new RegExp(`\\b${key}\\s*:`).test(c)) owned.add(old);
+    }
+  }
+  return owned;
+}
+
+function scanContent(content) {
+  const lines = content.split('\n');
+  const found = [];
+  for (const { old, next } of MOVED) {
+    const re = refRegex(old);
+    lines.forEach((text, i) => {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(text))) {
+        found.push({ line: i + 1, kind: kindOf(m[1]), old, next });
+      }
+    });
+  }
+  return found;
+}
+
+function applyRewrites(content, paths) {
+  let out = content;
+  for (const { old, next } of paths) {
+    out = out.replace(refRegex(old), (_full, prefix, quote) => `${prefix}${quote}${next}${quote}`);
+  }
+  return out;
+}
+
+/**
+ * Scan (and with `apply`, rewrite) source under `root`. Returns
+ * `{ scannedFiles, rewritten, pendingWrite, advisory, owned }` — `rewritten` is
+ * populated only when `apply` is true; otherwise auto-writable hits land in
+ * `pendingWrite`. `advisory` always holds the hits we won't touch automatically.
+ */
+export function runMigrateRoutes({ root = process.cwd(), apply = false } = {}) {
+  const srcDir = join(root, 'src');
+  const base = existsSync(srcDir) ? srcDir : root;
+  const files = walk(base);
+  const owned = detectConsumerOwned(files);
+
+  const rewritten = [];
+  const pendingWrite = [];
+  const advisory = [];
+
+  for (const file of files) {
+    const content = readFileSync(file, 'utf8');
+    const rel = relative(root, file);
+    const hits = scanContent(content).map((h) => ({
+      ...h,
+      file: rel,
+      autoWrite: !NEVER_AUTOWRITE.has(h.old) && !owned.has(h.old),
+      reason: NEVER_AUTOWRITE.has(h.old) ? 'docs-never' : owned.has(h.old) ? 'consumer-owned' : null,
+    }));
+    if (hits.length === 0) continue;
+
+    const auto = hits.filter((h) => h.autoWrite);
+    advisory.push(...hits.filter((h) => !h.autoWrite));
+
+    if (apply && auto.length) {
+      const paths = MOVED.filter((m) => auto.some((h) => h.old === m.old));
+      const next = applyRewrites(content, paths);
+      if (next !== content) {
+        writeFileSync(file, next);
+        rewritten.push(...auto);
+      }
+    } else {
+      pendingWrite.push(...auto);
+    }
+  }
+
+  return { scannedFiles: files.length, rewritten, pendingWrite, advisory, owned: [...owned] };
+}
+
+export function formatRouteResult(result, { check = false } = {}) {
+  const { rewritten, pendingWrite, advisory } = result;
+  if (!rewritten.length && !pendingWrite.length && !advisory.length) return '';
+
+  const ref = (h) => `      ${h.file}:${h.line}  ${h.kind} '${h.old}' → '${h.next}'`;
+  const lines = ['Route references — /editor, /components, /docs moved to /live-tokens/* in 0.35.0:'];
+
+  if (rewritten.length) {
+    lines.push(`  ✓ Rewrote ${rewritten.length} reference(s):`);
+    rewritten.forEach((h) => lines.push(ref(h)));
+  }
+  if (pendingWrite.length) {
+    lines.push(
+      check
+        ? `  Would rewrite ${pendingWrite.length} reference(s) with --write:`
+        : `  ${pendingWrite.length} reference(s) can be rewritten — re-run with --write to apply:`,
+    );
+    pendingWrite.forEach((h) => lines.push(ref(h)));
+  }
+  if (advisory.length) {
+    lines.push(`  ⚠ ${advisory.length} reference(s) need manual review:`);
+    advisory.forEach((h) => {
+      const why =
+        h.reason === 'docs-never'
+          ? `/docs is never auto-rewritten — update to '${h.next}' only if it points at the package guide`
+          : `you declare or relocate '${h.old}' yourself — leave it if it's your route`;
+      lines.push(`      ${h.file}:${h.line}  ${h.kind} '${h.old}'  (${why})`);
+    });
+  }
+  if (rewritten.length) lines.push('\n  Review the diff in git before committing.');
+  return lines.join('\n');
+}

package/package.json

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

package/src/editor/core/cssVarSync.ts

@@ -4,10 +4,10 @@
  * Writes to document.documentElement and — when running inside a same-origin
  * iframe (the live-preview overlay) — also writes to
  * window.parent.document.documentElement. This lets the overlay editor at
- * /editor drive the host site's :root in real time without any message-passing
- * infrastructure.
+ * /live-tokens/editor drive the host site's :root in real time without any
+ * message-passing infrastructure.
  *
- * When the editor runs standalone at /editor (not inside the overlay iframe),
+ * When the editor runs standalone at /live-tokens/editor (not inside the overlay iframe),
  * parentRoot is null and every call is a plain single-root write.
  *
  * Roots are resolved lazily — `init()` (or any setter call) populates them on

package/src/editor/core/routing/ownedRoutes.ts

@@ -0,0 +1,11 @@
+// The package's dev-only editor surfaces live under a reserved `/live-tokens/*`
+// namespace so they can never collide with a consumer's own routes — the
+// consumer owns the rest of the URL space. Keeping the defaults in one place
+// is the guard against the nav rail and the dispatcher drifting onto different
+// paths (the collision/shadow class these constants exist to prevent).
+//
+// A consumer relocates or disables each surface via the `editorRoutes` prop on
+// <LiveTokensRouter>; these are only the defaults.
+export const DEFAULT_EDITOR_PATH = '/live-tokens/editor';
+export const DEFAULT_COMPONENTS_PATH = '/live-tokens/components';
+export const DEFAULT_DOCS_PATH = '/live-tokens/docs';

package/src/editor/core/routing/router.ts

@@ -1,12 +1,13 @@
 import { writable } from 'svelte/store';
 import { storageKey } from '../store/editorConfig';
+import { DEFAULT_EDITOR_PATH } from './ownedRoutes';
 
 function prevKey(): string {
   return storageKey('prev-route');
 }
 
 function rememberPrev(current: string) {
-  if (current === '/editor') return;
+  if (current === DEFAULT_EDITOR_PATH) return;
   try { sessionStorage.setItem(prevKey(), current); } catch { /* ignore */ }
 }
 

package/src/editor/docs/Docs.svelte

@@ -39,6 +39,7 @@
 <script lang="ts">
   import { onMount, tick } from 'svelte';
   import { marked, type Tokens } from 'marked';
+  import { DEFAULT_COMPONENTS_PATH } from '../core/routing/ownedRoutes';
 
   import Button from '../../system/components/Button.svelte';
   import CodeSnippet from '../../system/components/CodeSnippet.svelte';
@@ -68,7 +69,7 @@
   let error = $state<string | null>(null);
   let chapterMeta = $state<Chapter | null>(null);
 
-  /* Parse `/docs#editing-tokens~palettes` → chapter `editing-tokens`, anchor `palettes`.
+  /* Parse `/live-tokens/docs#editing-tokens~palettes` → chapter `editing-tokens`, anchor `palettes`.
      Using `~` as the delimiter keeps each part valid for an HTML id. */
   let parsedHash = $derived.by(() => {
     const raw = hash.replace(/^#/, '');
@@ -269,7 +270,7 @@
               Demo Site
             </Button>
           </a>
-          <a href="/components" class="rail-action">
+          <a href={DEFAULT_COMPONENTS_PATH} class="rail-action">
             <Button variant="outline" size="small" icon="fas fa-puzzle-piece" fullWidth>
               Components
             </Button>

package/src/editor/docs/content/creating-components.md

@@ -26,13 +26,13 @@ Describe what you want in plain English. Phrases like these trigger the skill:
 
 Claude asks any clarifying questions it needs (which variants, which states,
 which parts), then writes the component, registers it with the editor, and runs
-its verification checklist. When it finishes, open `/components` to see your new
+its verification checklist. When it finishes, open `/live-tokens/components` to see your new
 component in the editor and confirm everything works.
 
 ## What you get
 
 - A runtime component whose editable properties default to your theme tokens.
-- An editor entry that appears under **Custom** in the `/components` view.
+- An editor entry that appears under **Custom** in the `/live-tokens/components` view.
 - The naming and wiring handled for you, so the component fits the system.
 
 Advanced authors who want to write a component by hand can read the naming and

package/src/editor/docs/content/getting-started.md

@@ -28,14 +28,14 @@ version upgrades never touch your styles. The package code stays in
 | Path | What it is |
 |------|------------|
 | `src/pages/Home.svelte` | The starter page. Replace it with your own content. |
-| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds the dev-only `/editor`, `/components`, and `/docs` routes. |
+| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds dev-only routes under a reserved `/live-tokens/*` namespace: `/live-tokens/editor`, `/live-tokens/components`, and `/live-tokens/docs`. |
 | `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |
 | `src/styles/site.css` | Themed page typography, yours to edit. |
 
 ## Your first edit
 
 1. Run `npm run dev` and open the home page.
-2. Click **Open Token Editor**, or visit `/editor`. The editor opens beside
+2. Click **Open Token Editor**, or visit `/live-tokens/editor`. The editor opens beside
    the page.
 3. Open **Palettes**, pick **Brand**, and change the base hex. The page
    repaints as you type.

package/src/editor/docs/content.generated.ts

@@ -3,8 +3,8 @@
 
 export const docContent: Record<string, string> = {
   "01-overview": "# Overview\n\nLive Tokens is a design system for building Svelte microsites quickly. You\nstyle your site by editing tokens and components in a live editor. When it looks right, you save the manifest and ship it.\n\n## How it works\n\n- The editor runs in your dev server, on top of your real pages. You style in\n  context, not in a separate sandbox.\n- Every change updates a CSS variable, so the page repaints instantly. No\n  reload, no build step.\n- Saving writes a small JSON file into your project. Shipping bakes your chosen\n  theme into a plain CSS file that the build bundles.\n- The editor is dev-only. Production ships plain CSS variables and the\n  components you used, nothing else.\n\n## What you can edit\n\n- **Tokens**: the design-system primitives, colour palettes, type, spacing,\n  radius, shadow, and gradients, that apply across your whole site.\n- **Components**: the package ships about 25 editable components (Button, Card,\n  Dialog, Table, and more).You style components by changing the tokens assigned to each property.\n\n## Where to go next\n\n- **[Getting started](getting-started.md)**: scaffold a project and make your\n  first edit.\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own components\n  editable.\n",
-  "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/components` view.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
+  "creating-components": "# Creating components\n\nThe package ships about 25 editable components. When you need one it doesn't\nhave, you can make your own Svelte component editable, so anyone using the\neditor can re-point its colours, type, and spacing without touching code.\n\nThe simplest way is to ask Claude. The package bundles a Claude Code skill that\nknows the conventions, writes the files, and checks the result for you.\n\n## Install the skills\n\n```bash\nnpx @motion-proto/live-tokens setup-claude\n```\n\nThis copies the bundled skills into your project's `.claude/skills/`. Once\nthey're there, Claude Code picks them up automatically.\n\n## Ask for a component\n\nDescribe what you want in plain English. Phrases like these trigger the skill:\n\n- \"Add a Toggle component to live-tokens\"\n- \"Make this Svelte component editable in the live-tokens editor\"\n- \"Create a Stat component with a value and a label\"\n\nClaude asks any clarifying questions it needs (which variants, which states,\nwhich parts), then writes the component, registers it with the editor, and runs\nits verification checklist. When it finishes, open `/live-tokens/components` to see your new\ncomponent in the editor and confirm everything works.\n\n## What you get\n\n- A runtime component whose editable properties default to your theme tokens.\n- An editor entry that appears under **Custom** in the `/live-tokens/components` view.\n- The naming and wiring handled for you, so the component fits the system.\n\nAdvanced authors who want to write a component by hand can read the naming and\nstate-model conventions shipped in the package\n(`src/system/styles/CONVENTIONS.md` and the skill's own `SKILL.md`).\n",
   "editing-tokens": "# Editing tokens\n\nA tour of the editor. The page behind it repaints on every change; saving\nwrites a theme file you can reload later.\n\nThe editor has two views:\n\n- **Tokens**: the design-system primitives (colour, type, spacing, and so on).\n  They apply everywhere your site uses them.\n- **Components**: per-component editors. Re-Assign what tokens a component uses\n  without changing the underlying system.\n\nThis page covers **Tokens**. For components, see\n[Creating components](creating-components.md).\n\n## Palettes\n\nMost colour work happens here. Each palette (Brand, Accent, Neutral, Canvas,\nSuccess, Warning, Info, Danger, and a few more) has:\n\n- **Base colour.** Pick a hex; the palette derives an 11-step ramp (100 to 950)\n  from it.\n- **Curves.** Two curves shape how lightness and saturation fall off across the\n  ramp. Drag the handles to bias it darker, lighter, or more saturated.\n- **Overrides.** Lock a single step to a hand-picked hex when the curve doesn't\n  land where you want.\n\nEditing a palette base ripples through every colour that depends on it, in real\ntime. Colours use OKLCH, so the ramp stays perceptually even across hues\nwithout muddy mid-tones.\n\n## Type\n\n- **Fonts.** Add sources from Google Fonts, Adobe (Typekit), a CSS URL, or an\n  inline `@font-face`. The font loads in the page as soon as you add it.\n- **Stacks.** Named font cascades you reference by token, such as a display\n  stack and a body stack.\n- **Sizes and weights.** A t-shirt scale (xs, sm, md, lg, xl, 2xl…) for size and\n  a numeric scale (100 to 900) for weight.\n\n## Spacing, radius, shadow\n\nNumeric scales with a slider per step.\n\n- **Spacing**: the padding, gap, and margin scale.\n- **Radius**: none through full.\n- **Shadow**: colour, offset, blur, spread, and opacity per step, with stacked\n  shadows supported.\n\nChange a step and every element using it repaints.\n\n## Overlays and gradients\n\n- **Overlays** are translucent tints layered over surfaces, like the subtle\n  tint a card gets on hover. Set a colour and opacity per state.\n- **Gradients** are reusable gradient tokens with a stop list and direction, for\n  hero panels and accent backgrounds.\n\n## Columns\n\nThe page-grid overlay. Set column count, gutter, and outer margin, and toggle\nthe visual guide with `Cmd/Ctrl+G`. Pages built on the column system reflow\nlive.\n\n## Saving\n\nThe editor saves to your browser continuously, so work survives a reload\nmid-edit. **Save** is a separate step: it writes a named theme file under\n`src/live-tokens/data/themes/`.\n\nThe header gives you undo/redo (`Cmd/Ctrl+Z`, `Cmd/Ctrl+Shift+Z`) and a file\nmenu for New, Save, Save as, Switch, and Delete. You can keep many themes side\nby side; one is active at a time. See [Themes](themes-workflow.md) for the full\nlifecycle.\n",
-  "getting-started": "# Getting started\n\nScaffold a live token site in a moments. You need Node 20 or later, a\npackage manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.\n\n## Scaffold a new app\n\n```bash\nnpm create @motion-proto/live-tokens@latest my-app\ncd my-app\nnpm install\nnpm run dev\n```\n\nOpen the URL Vite prints (usually `http://localhost:5173`). You get a\none-page Svelte + Vite app that depends on the published package, with the\neditor wired up and the full component set ready to import.\n\n`npx @motion-proto/live-tokens create my-app` runs the same scaffold without\nthe initialiser package.\n\n### What the scaffold gives you\n\nEvery editable file lives under `src/` and is committed, so `npm install` and\nversion upgrades never touch your styles. The package code stays in\n`node_modules`.\n\n| Path | What it is |\n|------|------------|\n| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |\n| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds the dev-only `/editor`, `/components`, and `/docs` routes. |\n| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |\n| `src/styles/site.css` | Themed page typography, yours to edit. |\n\n## Your first edit\n\n1. Run `npm run dev` and open the home page.\n2. Click **Open Token Editor**, or visit `/editor`. The editor opens beside\n   the page.\n3. Open **Palettes**, pick **Brand**, and change the base hex. The page\n   repaints as you type.\n4. Open the file menu and choose **Save as**. A theme appears as JSON under\n   `src/live-tokens/data/themes/`.\n5. Reload. Your saved theme is the active theme, so the page returns as you\n   left it.\n\n## What you just changed\n\nEvery edit sets a CSS custom property on `:root`. Your components read those\nproperties through `var(--...)`. There is no token build step and no\npreprocessor rewriting your code: the page renders against plain CSS variables\nthe editor swaps live.\n\nTo ship, promote a theme to production in the editor. That bakes the theme's\nvariables into `src/live-tokens/data/tokens.generated.css`, which your build\nbundles alongside `tokens.css`. The editor itself never reaches production.\n\nAlready have a Svelte 5 + Vite app? The\n[README](https://github.com/motionproto/live-tokens#readme) covers installing\ninto an existing project.\n\n## Where to go next\n\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own component\n  editable.\n",
+  "getting-started": "# Getting started\n\nScaffold a live token site in a moments. You need Node 20 or later, a\npackage manager (npm, pnpm, or yarn), and a browser. Open claude code in your repo and start building.\n\n## Scaffold a new app\n\n```bash\nnpm create @motion-proto/live-tokens@latest my-app\ncd my-app\nnpm install\nnpm run dev\n```\n\nOpen the URL Vite prints (usually `http://localhost:5173`). You get a\none-page Svelte + Vite app that depends on the published package, with the\neditor wired up and the full component set ready to import.\n\n`npx @motion-proto/live-tokens create my-app` runs the same scaffold without\nthe initialiser package.\n\n### What the scaffold gives you\n\nEvery editable file lives under `src/` and is committed, so `npm install` and\nversion upgrades never touch your styles. The package code stays in\n`node_modules`.\n\n| Path | What it is |\n|------|------------|\n| `src/pages/Home.svelte` | The starter page. Replace it with your own content. |\n| `src/App.svelte` | Your routes. `<LiveTokensRouter>` adds dev-only routes under a reserved `/live-tokens/*` namespace: `/live-tokens/editor`, `/live-tokens/components`, and `/live-tokens/docs`. |\n| `src/system/styles/tokens.css` | Your base token vocabulary, hand-authored. |\n| `src/styles/site.css` | Themed page typography, yours to edit. |\n\n## Your first edit\n\n1. Run `npm run dev` and open the home page.\n2. Click **Open Token Editor**, or visit `/live-tokens/editor`. The editor opens beside\n   the page.\n3. Open **Palettes**, pick **Brand**, and change the base hex. The page\n   repaints as you type.\n4. Open the file menu and choose **Save as**. A theme appears as JSON under\n   `src/live-tokens/data/themes/`.\n5. Reload. Your saved theme is the active theme, so the page returns as you\n   left it.\n\n## What you just changed\n\nEvery edit sets a CSS custom property on `:root`. Your components read those\nproperties through `var(--...)`. There is no token build step and no\npreprocessor rewriting your code: the page renders against plain CSS variables\nthe editor swaps live.\n\nTo ship, promote a theme to production in the editor. That bakes the theme's\nvariables into `src/live-tokens/data/tokens.generated.css`, which your build\nbundles alongside `tokens.css`. The editor itself never reaches production.\n\nAlready have a Svelte 5 + Vite app? The\n[README](https://github.com/motionproto/live-tokens#readme) covers installing\ninto an existing project.\n\n## Where to go next\n\n- **[Editing tokens](editing-tokens.md)**: a tour of the editor.\n- **[Themes](themes-workflow.md)**: save, switch, and ship.\n- **[Creating components](creating-components.md)**: make your own component\n  editable.\n",
   "themes-workflow": "# Themes\n\nSave your work, switch between themes, and ship one to production.\n\n## How themes work\n\n- **Your live edits** are what the page shows right now. They save to your\n  browser automatically and survive a reload, but they are not yet a file.\n- **A saved theme** is a named JSON file in `src/live-tokens/data/themes/`. You\n  create one with **Save as**.\n- **The active theme** is the saved theme the page loads at startup. Exactly one\n  at a time.\n- **The production theme** is the one that ships. Promoting sets it.\n\n## Saving\n\nIn the editor header:\n\n- **Save** updates the current theme.\n- **Save as** names a new theme. Use it for your first save and for forking.\n\nNames are tidied to lowercase with underscores, so \"My Brand!\" becomes\n`my_brand`. There is a built-in `default` theme you can always return to; the\neditor never overwrites it.\n\n## Switching\n\nThe file menu lists every saved theme. Pick one to make it active; the page\nreloads with it applied. Your current edits are saved to the previous theme\nfirst, so you don't lose work.\n\n## Shipping\n\n**Promote to production** is the \"ship it\" step. It bakes the theme's variables\ninto `src/live-tokens/data/tokens.generated.css`, which your build bundles\nalongside `tokens.css`. Fonts regenerate to match.\n\nProduction builds (`npm run build`) ship only that plain CSS and your\ncomponents. No editor, no JSON loading, no runtime indirection. If you save\nwhile the production theme is active, the generated CSS updates immediately,\nwith no separate promote step.\n\n## Manifests\n\nA **manifest** bundles one theme plus a config for each component into a single\nnamed set. Useful when you run several brands and want each to apply its theme\nand component tweaks in one move. There is a protected default and an active\nmanifest; applying one swaps everything at once.\n\n## Keeping your work safe\n\nEverything under `src/live-tokens/data/` is plain JSON, so commit it. Themes\nshow up as readable diffs you can review per branch. There are no automatic\nbackups: git is your safety net. To experiment freely, **Save as** a new name\nfirst, then edit.\n\n## Where to go next\n\n- **[Creating components](creating-components.md)**: make your own components\n  editable in the same editor.\n",
 };

package/src/editor/overlay/LiveEditorOverlay.svelte

@@ -15,6 +15,7 @@
   import { fade } from 'svelte/transition';
   import { cubicInOut } from 'svelte/easing';
   import { route, navigate } from '../core/routing/router';
+  import { DEFAULT_EDITOR_PATH, DEFAULT_COMPONENTS_PATH } from '../core/routing/ownedRoutes';
   import { editorView } from '../core/store/editorViewStore';
   import { columnsVisible, toggleColumns } from './columnsOverlay';
   import { storageKey } from '../core/store/editorConfig';
@@ -27,6 +28,7 @@
   interface Props {
     open?: boolean | undefined;
     editorPath?: string;
+    componentsPath?: string;
     navLinks?: NavLink[];
     pageSources?: Record<string, string>;
     hidePageSourceOn?: string[];
@@ -35,7 +37,8 @@
 
   let {
     open = $bindable(undefined),
-    editorPath = '/editor',
+    editorPath = DEFAULT_EDITOR_PATH,
+    componentsPath = DEFAULT_COMPONENTS_PATH,
     navLinks = [],
     pageSources = {},
     hidePageSourceOn = [],
@@ -62,9 +65,9 @@
     overlayOpen.set(!!open);
   });
 
-  // The /components route renders the same component-editor surface as the
-  // overlay's components view. Pair them: on entering /components, flip the
-  // overlay to tokens so the two surfaces don't stack. Fires only on route
+  // The components route renders the same component-editor surface as the
+  // overlay's components view. Pair them: on entering it, flip the overlay to
+  // tokens so the two surfaces don't stack. Fires only on route
   // change, not on every editorView change — otherwise cross-window storage
   // sync re-triggers the rule, which writes editorView, which fires another
   // storage event, which fires the rule again. The result is heavy re-render
@@ -75,7 +78,7 @@
     const r = $route;
     if (r === prevRoute) return;
     prevRoute = r;
-    if (r === '/components') {
+    if (r === componentsPath) {
       editorView.update((v) => (v === 'components' ? 'tokens' : v));
     }
   });

package/src/editor/overlay/LiveTokensRouter.svelte

@@ -28,9 +28,11 @@
   }
 
   /**
-   * Override the default editor routes (`/editor`, `/components`, `/docs`).
-   * Pass a string to relocate the route; pass `false` to disable it entirely
-   * (no dispatch and, for `components`/`docs`, no auto-injected nav-rail entry).
+   * Override the package's dev-only routes, which default to the reserved
+   * `/live-tokens/*` namespace (`/live-tokens/editor`, `/live-tokens/components`,
+   * `/live-tokens/docs`) so they never collide with consumer pages. Pass a
+   * string to relocate a route; pass `false` to disable it entirely (no
+   * dispatch and, for `components`/`docs`, no auto-injected nav-rail entry).
    */
   export interface EditorRouteOverrides {
     editor?: string | false;
@@ -40,8 +42,8 @@
 
   /**
    * Resolve a path to the single entry that renders it. Precedence, after the
-   * package-owned routes (`/editor`, `/components`, `/docs`) have already been
-   * matched by the component:
+   * package-owned `/live-tokens/*` routes (editor, components, docs) have
+   * already been matched by the component:
    *
    *   1. `pages[route]` — exact static match.
    *   2. `resolve(route)` — consumer code, where params / prefixes / gating
@@ -66,6 +68,7 @@
   import LiveEditorOverlay from './LiveEditorOverlay.svelte';
   import ColumnsOverlay from './ColumnsOverlay.svelte';
   import { route, navigate } from '../core/routing/router';
+  import { DEFAULT_EDITOR_PATH, DEFAULT_COMPONENTS_PATH, DEFAULT_DOCS_PATH } from '../core/routing/ownedRoutes';
 
   interface Props {
     pages: Record<string, RouteEntry>;
@@ -84,9 +87,9 @@
   let editorEnabled = $derived(editorRoutes.editor !== false);
   let componentsEnabled = $derived(editorRoutes.components !== false);
   let docsEnabled = $derived(editorRoutes.docs !== false);
-  let editorPath = $derived(typeof editorRoutes.editor === 'string' ? editorRoutes.editor : '/editor');
-  let componentsPath = $derived(typeof editorRoutes.components === 'string' ? editorRoutes.components : '/components');
-  let docsPath = $derived(typeof editorRoutes.docs === 'string' ? editorRoutes.docs : '/docs');
+  let editorPath = $derived(typeof editorRoutes.editor === 'string' ? editorRoutes.editor : DEFAULT_EDITOR_PATH);
+  let componentsPath = $derived(typeof editorRoutes.components === 'string' ? editorRoutes.components : DEFAULT_COMPONENTS_PATH);
+  let docsPath = $derived(typeof editorRoutes.docs === 'string' ? editorRoutes.docs : DEFAULT_DOCS_PATH);
 
   const isDev = import.meta.env.DEV;
   let isEditor = $derived(isDev && editorEnabled && $route === editorPath);
@@ -176,7 +179,7 @@
   class:is-component-editor={isComponentEditor}
   onclick={handleClick}
 >
-  <LiveEditorOverlay {navLinks} {pageSources} {hidePageSourceOn} {editorPath} />
+  <LiveEditorOverlay {navLinks} {pageSources} {hidePageSourceOn} {editorPath} {componentsPath} />
   <ColumnsOverlay />
 
   {#await pagePromise then m}

package/src/editor/pages/Editor.svelte

@@ -5,6 +5,7 @@
   import { installEditorKeybindings } from '../core/store/editorKeybindings';
   import { initializeEditorStore } from '../core/store/editorStore';
   import { storageKey } from '../core/store/editorConfig';
+  import { DEFAULT_EDITOR_PATH } from '../core/routing/ownedRoutes';
   // Editor chrome + form controls + icon font must be JS imports (not @import
   // inside the style block) so Vite resolves them via the module graph
   // regardless of how the consumer compiles Svelte CSS (external ?lang.css vs
@@ -23,7 +24,7 @@
   function pickBackHref(): string {
     try {
       const prev = sessionStorage.getItem(storageKey('prev-route'));
-      if (prev && prev !== '/editor') return prev;
+      if (prev && prev !== DEFAULT_EDITOR_PATH) return prev;
     } catch {
       // ignore
     }

package/src/editor/ui/EditorViewSwitcher.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { editorView } from '../core/store/editorViewStore';
   import { parentRoute } from '../core/routing/parentRouteStore';
+  import { DEFAULT_COMPONENTS_PATH } from '../core/routing/ownedRoutes';
 
   interface Props {
     condensed?: boolean;
@@ -8,11 +9,13 @@
 
   let { condensed = false }: Props = $props();
 
-  // On /components the host page is already the components editor — the
-  // overlay's components view would just stack on top of it, so disable the
+  // On the components route the host page is already the components editor —
+  // the overlay's components view would just stack on top, so disable the
   // switch. The switcher renders inside the editor iframe, so we read the
-  // *parent* route, not this iframe's own route.
-  let componentsDisabled = $derived($parentRoute === '/components');
+  // *parent* route, not this iframe's own. Compares the default path:
+  // editorRoutes.components relocation isn't plumbed across the iframe, so a
+  // relocated route won't disable the switch.
+  let componentsDisabled = $derived($parentRoute === DEFAULT_COMPONENTS_PATH);
 
   function set(v: 'tokens' | 'components') {
     editorView.set(v);

package/src/system/components/ImageLightbox.svelte

@@ -28,12 +28,22 @@
     extended?: boolean;
     /** Maximum zoom, as a multiple of the image's natural resolution: `1` = 100%
         of the source's real pixels (1 source px = 1 screen px), `2` = 200%. The
-        modal always opens fitted to the viewport; this only caps how far the
-        `extended` zoom controls can magnify. Unset = the default 5x-the-fit cap.
-        An image whose fitted size already exceeds the cap simply can't be zoomed
-        in. Needs the natural pixel size (from `width`/`height`, or the loaded
-        image); until that's known the default cap applies. */
+        modal opens fitted to the viewport (or to natural size when `capNatural`
+        is set); this only caps how far the `extended` zoom controls can magnify.
+        Unset = the default 5x-the-fit cap. An image whose fitted size already
+        exceeds the cap simply can't be zoomed in. Needs the natural pixel size
+        (from `width`/`height`, or the loaded image); until that's known the
+        default cap applies. */
     maxZoom?: number | undefined;
+    /** Cap the opened image at its natural resolution (100%): the modal still
+        opens centered, but never scales the source above 1:1, so a small source
+        (e.g. a low-res GIF) stays crisp instead of being upscaled to fill the
+        viewport. Larger images are unaffected — they fit the viewport as usual.
+        Only bounds the initial open fit; pair with `maxZoom={1}` to also stop the
+        `extended` controls zooming past 100%. Needs the natural pixel size (from
+        `width`/`height`, or the loaded image); until that's known the image fits
+        the viewport, then snaps to the cap once measured. */
+    capNatural?: boolean;
   }
 
   let {
@@ -46,6 +56,7 @@
     fit = 'contain',
     extended = false,
     maxZoom = undefined,
+    capNatural = false,
   }: Props = $props();
 
   const items = $derived(
@@ -151,7 +162,11 @@
     if (!aspect) {
       return { top: vh * 0.04, left: vw * 0.03, width: capW, height: capH };
     }
-    const tileW = Math.min(capW, capH * aspect);
+    let tileW = Math.min(capW, capH * aspect);
+    if (capNatural) {
+      const nw = naturalWidthOf(current);
+      if (nw) tileW = Math.min(tileW, nw);
+    }
     const tileH = tileW / aspect;
     return {
       top: (vh - tileH) / 2,

package/template/README.md

@@ -14,9 +14,10 @@ Open http://localhost:5173.
 This project follows the package's [recommended layout](https://github.com/motionproto/live-tokens#recommended-project-layout): all editable state lives under `src/` and is committed, so `npm install` and upgrades never touch your styles.
 
 - `src/pages/Home.svelte` — the starter page. Replace it with your own content.
-- `src/App.svelte` — your routes. `<LiveTokensRouter>` adds the dev-only
-  `/editor` (theme tokens), `/components` (per-component aliases), and `/docs`
-  (the user guide) routes.
+- `src/App.svelte` — your routes. `<LiveTokensRouter>` adds dev-only routes under
+  a reserved `/live-tokens/*` namespace (so they never collide with your pages):
+  `/live-tokens/editor` (theme tokens), `/live-tokens/components` (per-component
+  aliases), and `/live-tokens/docs` (the user guide).
 - `src/system/styles/tokens.css` — your theme token vocabulary. The dev server
   writes edits here when you use the in-browser editor.
 - `src/styles/site.css` — themed page typography. Yours to edit.
@@ -24,7 +25,7 @@ This project follows the package's [recommended layout](https://github.com/motio
 ## Editing live
 
 Run `npm run dev`, then click **Open Token Editor** on the home page (or visit
-`/editor`). Changes persist to `src/system/styles/tokens.css` and the JSON under
+`/live-tokens/editor`). Changes persist to `src/system/styles/tokens.css` and the JSON under
 `src/live-tokens/data/`. The editor is dev-only — `npm run build` ships plain
 CSS variables and the components you used, nothing else.
 

package/template/src/App.svelte

@@ -1,9 +1,10 @@
 <script lang="ts">
   import { LiveTokensRouter } from '@motion-proto/live-tokens';
 
-  // <LiveTokensRouter> owns the dev-only /editor and /components routes.
-  // Declare your own pages here. Lazy imports keep each page's CSS
-  // side-effects out of the editor routes; omit `label` to keep a route
+  // <LiveTokensRouter> owns the dev-only /live-tokens/editor and
+  // /live-tokens/components routes (a reserved namespace, so they never collide
+  // with your pages). Declare your own pages here. Lazy imports keep each page's
+  // CSS side-effects out of the editor routes; omit `label` to keep a route
   // reachable by URL but hidden from the overlay nav rail.
   const pages = {
     '/': {

package/template/src/pages/Home.svelte

@@ -22,8 +22,8 @@
       </p>
       {#if isDev}
         <div class="actions">
-          <Button on:click={() => navigate('/editor')}>Open Token Editor</Button>
-          <Button variant="secondary" on:click={() => navigate('/components')}>Components</Button>
+          <Button on:click={() => navigate('/live-tokens/editor')}>Open Token Editor</Button>
+          <Button variant="secondary" on:click={() => navigate('/live-tokens/components')}>Components</Button>
         </div>
       {/if}
     </Card>