@motion-proto/live-tokens 0.94.3 → 0.95.0

package/src/demo/sections/SectionOffering.svelte

@@ -17,13 +17,15 @@
   .offering {
     grid-column: 1 / -1;
     display: grid;
-    grid-template-columns: repeat(var(--columns-count), 1fr);
-    column-gap: var(--columns-gutter);
+    grid-template-columns: subgrid;
   }
 
   .offering-quote {
-    grid-column: 3 / -3;
+    grid-column: var(--kit-narrow);
+    justify-self: center;
+    max-width: 24em;
     margin: 0;
+    font-size: var(--heading-lg-font-size);
   }
 
   .offering-quote blockquote {
@@ -38,12 +40,13 @@
 
   .offering-quote p {
     font-family: var(--font-serif);
-    font-size: var(--font-size-3xl);
+    font-size: var(--heading-lg-font-size);
     font-weight: var(--font-weight-normal);
     color: var(--text-primary);
     line-height: 1.2;
     margin: 0;
     hyphens: none;
+    text-wrap: pretty;
     text-indent: -0.55em;
   }
 
@@ -65,29 +68,11 @@
     margin-top: 0;
     font-family: var(--font-serif);
     font-weight: var(--font-weight-normal);
-    font-size: var(--font-size-3xl);
+    font-size: var(--heading-lg-font-size);
     font-variation-settings: 'opsz' 144, 'SOFT' 100;
     letter-spacing: 0.01em;
     color: var(--text-primary);
     text-align: right;
     padding-right: 0.4em;
   }
-
-  @media (max-width: 960px) {
-    .offering-quote {
-      grid-column: 2 / -2;
-    }
-    .offering-quote p {
-      font-size: var(--font-size-xl);
-    }
-  }
-
-  @media (max-width: 600px) {
-    .offering-quote {
-      grid-column: 1 / -1;
-    }
-    .offering-quote p {
-      font-size: var(--font-size-4xl);
-    }
-  }
 </style>

package/src/editor/bootstrap.ts

@@ -18,11 +18,8 @@ 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 * as themeDocumentSync from './core/themes/themeDocumentSync';
-import * as liveStateStream from './core/themes/liveStateStream';
-import { initializeTheme } from './core/themes/themeInit';
-import { registerComponent, type RegisterComponentEntry } from './component-editor/registry';
+import { registerComponent } from './component-editor/registration';
+import type { RegisterComponentEntry } from './component-editor/registry';
 import { registerSketchStyle, type RegisterSketchStyleInput } from './core/sketch/sketchRegistry';
 
 export interface BootLiveTokensOptions {
@@ -43,7 +40,6 @@ export async function bootLiveTokens(
   cssVarSync.init();
   router.init();
   columnsOverlay.init();
-  editorStore.init();
 
   // Before the DEV block: `initializeTheme` recovers the open theme's style by
   // name against the pool, so the pool has to be whole by the time it runs.
@@ -52,6 +48,16 @@ export async function bootLiveTokens(
   }
 
   if (import.meta.env.DEV) {
+    // Imported here, never statically, so a build drops the editor. The
+    // registry alone imports every shipped component and editor.
+    const [editorStore, themeDocumentSync, liveStateStream, { initializeTheme }] = await Promise.all([
+      import('./core/store/editorStore'),
+      import('./core/themes/themeDocumentSync'),
+      import('./core/themes/liveStateStream'),
+      import('./core/themes/themeInit'),
+      import('./component-editor/registry'),
+    ]);
+    editorStore.init();
     themeDocumentSync.init();
     liveStateStream.init();
     if (opts.components) {

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

@@ -50,7 +50,7 @@
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
   import { buildSiblings } from './scaffolding/siblings';
-  import demoImageUrl from '../../system/assets/offering.webp';
+  import demoImageUrl from '../../system/assets/newspaper.webp';
   import { editorState, setComponentAlias } from '../core/store/editorStore';
 
   let aliases = $derived(

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

@@ -45,13 +45,12 @@
   import ImageLightbox from '../../system/components/ImageLightbox.svelte';
   import VariantGroup from './scaffolding/VariantGroup.svelte';
   import ComponentEditorBase from './scaffolding/ComponentEditorBase.svelte';
-  import offeringUrl from '../../system/assets/offering.webp';
   import newspaperUrl from '../../system/assets/newspaper.webp';
 
   const demoImages = [
-    // Offering carries explicit dimensions (the no-reflow path); Newspaper omits
-    // them to exercise self-measure from the loaded image.
-    { src: offeringUrl, alt: 'Offering', width: 1455, height: 970 },
+    // The first entry carries explicit dimensions (the no-reflow path); the second
+    // omits them to exercise self-measure from the loaded image.
+    { src: newspaperUrl, alt: 'Newspaper', width: 2048, height: 1152 },
     { src: newspaperUrl, alt: 'Newspaper' },
   ];
 

package/src/editor/component-editor/registration.ts

@@ -0,0 +1,36 @@
+import type { RegisterComponentEntry } from './registry';
+
+/*
+ * `registerComponent` lives apart from `registry.ts` so a production build can
+ * call it without bundling the registry, which imports every shipped component
+ * and editor. Entries wait here until the registry loads, which happens in dev
+ * only.
+ */
+
+type Sink = (entry: RegisterComponentEntry) => void;
+
+const pending: RegisterComponentEntry[] = [];
+let sink: Sink | null = null;
+
+/**
+ * Register a consumer-authored component with the editor. Call from `main.ts`
+ * before app mount.
+ *
+ * Collision rule: if `entry.id` matches a built-in id, a warning is logged and
+ * the custom entry wins (the custom editor and schema replace the built-in for
+ * the rest of the session).
+ *
+ * Side effect: registers the schema with the editor store so reset-to-default
+ * and sibling-group resolution work for the new component.
+ */
+export function registerComponent(entry: RegisterComponentEntry): void {
+  if (sink) sink(entry);
+  else pending.push(entry);
+}
+
+/** Called once by `registry.ts` as it loads. Drains the entries registered
+    before it, in call order, and takes every later one directly. */
+export function attachRegistry(next: Sink): void {
+  sink = next;
+  for (const entry of pending.splice(0)) next(entry);
+}

package/src/editor/component-editor/registry.ts

@@ -1,6 +1,9 @@
 import type { Component } from 'svelte';
 import type { CatalogueEntry, Token, IntrinsicSpec } from './scaffolding/types';
 import { registerComponentSchema } from '../core/store/editorStore';
+import { attachRegistry } from './registration';
+
+export { registerComponent } from './registration';
 
 import BadgeEditor, { allTokens as badgeTokens } from './BadgeEditor.svelte';
 import { catalogue as badgeCatalogue } from '../../system/components/Badge.svelte';
@@ -433,18 +436,7 @@ const customRegistry = new Map<string, RegistryEntry>();
 /** Argument shape for `registerComponent()`. `origin` is set internally to `'custom'`. */
 export type RegisterComponentEntry = Omit<RegistryEntry, 'origin'>;
 
-/**
- * Register a consumer-authored component at runtime. Call from `main.ts`
- * before app mount.
- *
- * Collision rule: if `entry.id` matches a built-in id, a warning is logged and
- * the custom entry wins (the custom editor and schema replace the built-in for
- * the rest of the session).
- *
- * Side effect: registers the schema with the editor store so reset-to-default
- * and sibling-group resolution work for the new component.
- */
-export function registerComponent(entry: RegisterComponentEntry): void {
+function addCustomComponent(entry: RegisterComponentEntry): void {
   if (entry.id in builtInRegistry) {
     console.warn(
       `[registerComponent] custom component "${entry.id}" overrides a built-in. The custom editor will be used.`,
@@ -496,6 +488,7 @@ export function getComponentIds(): ReadonlyArray<string> {
 for (const entry of Object.values(builtInRegistry)) {
   registerComponentSchema(entry.id, entry.schema);
 }
+attachRegistry(addCustomComponent);
 
 /**
  * Validate that the server's filesystem scan matches the merged registry's id list.

package/src/editor/component-editor/scaffolding/ShadowBackdrop.svelte

@@ -83,12 +83,21 @@
     grid-area: controls;
   }
 
+  /* Narrow: the preview leads, since it is what the pinned stage is for, and a
+     component wider than the stage scrolls inside it. */
   @container variant-group (max-width: 32rem) {
+    /* Holds its height so the pinned stage scrolls to the controls rather than
+       squeezing the preview under them. */
     .shadow-backdrop.with-controls {
+      flex-shrink: 0;
       grid-template-columns: minmax(0, 1fr);
       grid-template-areas:
-        "controls"
-        "preview";
+        "preview"
+        "controls";
+    }
+
+    .shadow-backdrop-content {
+      overflow-x: auto;
     }
   }
 </style>

package/src/editor/component-editor/scaffolding/StateBlock.svelte

@@ -268,6 +268,13 @@
     align-items: stretch;
   }
 
+  /* Sections stack one per line here, so each heading rule spans the card. */
+  @container variant-group (max-width: 32rem) {
+    .element-section {
+      flex: 1 1 100%;
+    }
+  }
+
   .element-section .state-type-groups {
     display: flex;
     flex-direction: row;

package/src/editor/component-editor/scaffolding/TokenLayout.svelte

@@ -436,10 +436,9 @@
 
   @container variant-group (max-width: 380px) {
     .token-grid {
-      grid-template-columns: max-content 1fr;
+      grid-template-columns: max-content var(--token-selector-w) minmax(0, 1fr);
       column-gap: var(--ui-space-6);
     }
-    .token-grid :global(.ui-token-selector) { grid-column: 2; }
   }
 
   .zone-divider {

package/src/editor/component-editor/scaffolding/VariantGroup.svelte

@@ -567,7 +567,7 @@
      pinned and always leaves the controls a viewport to live in. */
   .tabs-preview {
     position: sticky;
-    top: 0;
+    top: var(--editor-sticky-top, 0px);
     z-index: 2;
     display: flex;
     flex-direction: column;
@@ -598,6 +598,20 @@
     flex: none;
   }
 
+  /* A capped stage nests a scroller inside the page scroll, which a phone
+     handles badly, and an uncapped pinned band covers the controls. The band
+     scrolls with the page at full height instead. */
+  @media (max-width: 600px) {
+    .tabs-preview {
+      position: relative;
+      max-height: none;
+    }
+
+    .tabs-preview::after {
+      display: none;
+    }
+  }
+
   /* Soft fade at the bottom of the sticky band so property rows scrolling
      up don't sharply cut against the pinned preview. Greyscale (no accent).
      Sits below the preview body, above scrolling content. */
@@ -910,8 +924,9 @@
   /* Direct child of .variant-group; needs its own margin since flex gap doesn't apply across siblings. */
   .properties-header {
     display: flex;
+    flex-wrap: wrap;
     align-items: center;
-    gap: var(--ui-space-16);
+    gap: var(--ui-space-8) var(--ui-space-16);
     margin-top: var(--ui-space-8);
     margin-bottom: var(--ui-space-8);
   }

package/src/editor/core/store/editorPersistence.ts

@@ -21,6 +21,7 @@ import { quietGet, quietSet } from '../storage/storage';
 import { isGradientSlot, makeDefaultGradients } from '../themes/slices/gradients';
 import { seedShadowsFromDom } from '../themes/slices/shadows';
 import { makeDefaultWashScale, type WashFamily } from '../themes/slices/washes';
+import { normalizeColumnsState } from '../themes/slices/columns';
 import { sanitizeHarmonyAxes } from '../palettes/colorHarmony';
 import {
   renameBackgroundPaletteKey,
@@ -189,6 +190,10 @@ export function normalizePaletteBasis(state: EditorState): EditorState {
   return { ...state, palettes: migratePaletteColorsToOklch(raw) };
 }
 
+export function normalizeColumns(state: EditorState): EditorState {
+  return { ...state, columns: normalizeColumnsState(state.columns) };
+}
+
 export function hydrate(): void {
   // Corrupt state, missing key, or unavailable storage all return null;
   // the editor falls through to the empty default in that case.
@@ -200,7 +205,7 @@ export function hydrate(): void {
     store.set(
       normalizeHarmonyAxes(
         normalizeBaseAnchors(
-          normalizePaletteBasis(normalizePaletteLabels(normalizeComponents(normalizeWashes(migrateGradients(merged))))),
+          normalizePaletteBasis(normalizePaletteLabels(normalizeComponents(normalizeColumns(normalizeWashes(migrateGradients(merged)))))),
         ),
       ),
     );

package/src/editor/core/store/editorRenderer.ts

@@ -18,7 +18,6 @@ import { palettesToVars } from '../palettes/paletteDerivation';
 import {
   editorState,
   columnsToVars,
-  columnsEqualsDefault,
   washesToVars,
   shadowsToVars,
   gradientsToVars,
@@ -27,9 +26,7 @@ import {
 
 export function deriveCssVars(state: EditorState): Record<string, string> {
   const out: Record<string, string> = { ...state.cssVars };
-  if (!columnsEqualsDefault(state.columns)) {
-    Object.assign(out, columnsToVars(state.columns));
-  }
+  Object.assign(out, columnsToVars(state.columns));
   Object.assign(out, washesToVars(state.washes));
   if (state.shadows.tokens.length > 0) {
     Object.assign(out, shadowsToVars(state.shadows));

package/src/editor/core/store/editorStore.ts

@@ -56,8 +56,7 @@ import {
   initializeEditorStore,
 } from './editorPersistence';
 import {
-  DEFAULT_COLUMNS,
-  columnsEqualsDefault,
+  defaultColumns,
   columnsToVars,
   loadColumnsFromVars,
 } from '../themes/slices/columns';
@@ -100,7 +99,7 @@ function emptyState(): EditorState {
       overrides: {},
     },
     washes: makeDefaultWashesState(),
-    columns: { ...DEFAULT_COLUMNS },
+    columns: defaultColumns(),
     components: {},
     gradients: { tokens: makeDefaultGradients() },
     harmonyAxes: defaultHarmonyAxes(),
@@ -143,10 +142,9 @@ export {
 
 export {
   columnsToVars,
-  columnsEqualsDefault,
+  columnsFromVars,
   COLUMN_VAR_NAMES,
-  DEFAULT_COLUMNS,
-  parseColumnVars,
+  defaultColumns,
 } from '../themes/slices/columns';
 
 export {
@@ -430,9 +428,7 @@ export function loadFromFile(colorsAndType: ColorsAndType): void {
  */
 function colorsAndTypeContent(state: EditorState): Omit<ColorsAndType, 'name' | 'createdAt' | 'updatedAt'> {
   const cssVariables: Record<string, string> = { ...state.cssVars };
-  if (!columnsEqualsDefault(state.columns)) {
-    Object.assign(cssVariables, columnsToVars(state.columns));
-  }
+  Object.assign(cssVariables, columnsToVars(state.columns));
   Object.assign(cssVariables, washesToVars(state.washes));
   if (state.shadows.tokens.length > 0) {
     Object.assign(cssVariables, shadowsToVars(state.shadows));

package/src/editor/core/store/editorTypes.ts

@@ -1,6 +1,7 @@
 import type { PaletteConfig, FontSource, FontStack } from '../themes/themeTypes';
 import type { GradientStop, GradientValue, LinearDirection } from '../themes/parsers/gradient';
 import type { HarmonyAxis } from '../palettes/colorHarmony';
+import type { ColumnViewport, ColumnViewportValues } from '../themes/slices/columns';
 
 export interface ShadowGlobals {
   angle: number;
@@ -40,8 +41,7 @@ export interface WashScale {
 export interface ColumnsState {
   count: number;
   maxWidth: number;
-  gutter: number;
-  margin: number;
+  viewports: Record<ColumnViewport, ColumnViewportValues>;
 }
 
 /** Gradient render mode.

package/src/editor/core/themes/migrations/2026-10-15-responsive-columns.ts

@@ -0,0 +1,40 @@
+import type { Migration } from './index';
+
+/**
+ * The column grid's stored gutter and margin move to their desktop names
+ * (2026-10-15).
+ *
+ * tokens.css points `--columns-gutter` and `--columns-margin` at a
+ * per-viewport value for the window's width. A theme that stores either
+ * overrides every breakpoint, so each moves to its desktop name with its
+ * value. `--columns-count` stays one value at every width and keeps its name.
+ *
+ * A stored value equal to the one every shipped theme held (`12`, `32px`,
+ * `0px` or `0`) counts as unset and is dropped, so the theme inherits the
+ * tokens.css default. The theme stores no tablet or phone value. The names
+ * and values freeze those of 2026-10-15.
+ */
+const RENAMES: Record<string, string> = {
+  '--columns-gutter': '--columns-desktop-gutter',
+  '--columns-margin': '--columns-desktop-margin',
+};
+
+const SHIPPED: Record<string, readonly string[]> = {
+  '--columns-count': ['12'],
+  '--columns-gutter': ['32px'],
+  '--columns-margin': ['0px', '0'],
+};
+
+export const colorsAndTypeMigration_2026_10_15_responsiveColumns: Migration = {
+  id: '2026-10-15-responsive-columns',
+  fromVersion: 9,
+  toVersion: 10,
+  appliesTo: 'colors-and-type',
+  apply(rawVars) {
+    return Object.fromEntries(
+      Object.entries(rawVars)
+        .filter(([name, value]) => !SHIPPED[name]?.includes(value.trim()))
+        .map(([name, value]) => [RENAMES[name] ?? name, value]),
+    );
+  },
+};

package/src/editor/core/themes/migrations/index.ts

@@ -82,6 +82,7 @@ import { componentMigration_2026_09_13_sectiondividerSurface } from './2026-09-1
 import { componentMigration_2026_09_20_imagelightboxScrim } from './2026-09-20-imagelightbox-scrim';
 import { componentMigration_2026_09_20_scrimColorAndOpacity } from './2026-09-20-scrim-color-and-opacity';
 import { colorsAndTypeMigration_2026_09_21_washColorAndOpacity } from './2026-09-21-wash-color-and-opacity';
+import { colorsAndTypeMigration_2026_10_15_responsiveColumns } from './2026-10-15-responsive-columns';
 import { componentMigration_2026_09_21_scrimSurface } from './2026-09-21-scrim-surface';
 import { componentMigration_2026_09_13_cornerbadgePrefix } from './2026-09-13-cornerbadge-prefix';
 import { componentMigration_2026_09_13_toggleLabel } from './2026-09-13-toggle-label';
@@ -140,6 +141,7 @@ export const MIGRATIONS: Migration[] = [
   componentMigration_2026_09_20_scrimColorAndOpacity,
   colorsAndTypeMigration_2026_09_21_washColorAndOpacity,
   componentMigration_2026_09_21_scrimSurface,
+  colorsAndTypeMigration_2026_10_15_responsiveColumns,
 ];
 
 function countFor(kind: 'colors-and-type' | 'component-config'): number {

package/src/editor/core/themes/slices/columns.ts

@@ -1,59 +1,129 @@
 /**
- * Columns slice — fixed-shape (count/maxWidth/gutter/margin) state, derived to
- * four CSS vars. Values default to a 12-column 1440px grid; while state matches
- * the default we leave tokens.css in charge so the `clamp()` in
- * `--columns-gutter` survives until the editor overrides it.
+ * Columns slice. The column grid holds one count and one max width, and a
+ * gutter and a margin per viewport. `--columns-gutter` and `--columns-margin`
+ * are structural: tokens.css points them at the viewport values for the
+ * window's width, and the editor never writes them.
  */
-import type { ColumnsState } from '../../store/editorTypes';
+import type { ColumnsState, EditorState } from '../../store/editorTypes';
 
-export const DEFAULT_COLUMNS: ColumnsState = { count: 12, maxWidth: 1440, gutter: 16, margin: 0 };
+export const COLUMN_VIEWPORTS = ['desktop', 'tablet', 'phone'] as const;
+export type ColumnViewport = (typeof COLUMN_VIEWPORTS)[number];
 
-export const COLUMN_VAR_NAMES = ['--columns-count', '--columns-max-width', '--columns-gutter', '--columns-margin'] as const;
+export interface ColumnViewportValues {
+  gutter: number;
+  margin: number;
+}
+export type ColumnProperty = keyof ColumnViewportValues;
+export const COLUMN_PROPERTIES: readonly ColumnProperty[] = ['gutter', 'margin'];
 
-export function columnsToVars(c: ColumnsState): Record<string, string> {
-  return {
-    '--columns-count': String(c.count),
-    '--columns-max-width': `${c.maxWidth}px`,
-    '--columns-gutter': `${c.gutter}px`,
-    '--columns-margin': `${c.margin}px`,
-  };
+/** The widest window each narrower viewport covers, as tokens.css's `@media (max-width)` blocks declare it. */
+export const COLUMN_BREAKPOINTS: Record<Exclude<ColumnViewport, 'desktop'>, number> = {
+  tablet: 767,
+  phone: 480,
+};
+
+export const COLUMN_COUNT_NAME = '--columns-count';
+export const COLUMN_MAX_WIDTH_NAME = '--columns-max-width';
+
+export function columnVarName(viewport: ColumnViewport, property: ColumnProperty): string {
+  return `--columns-${viewport}-${property}`;
 }
 
-/**
- * Only emit column CSS vars once the user has actually modified columns.
- * While columns match the default, we leave tokens.css in charge — which
- * preserves the `clamp()` in `--columns-gutter` until the editor overrides it.
- */
-export function columnsEqualsDefault(c: ColumnsState): boolean {
-  return c.count === DEFAULT_COLUMNS.count
-    && c.maxWidth === DEFAULT_COLUMNS.maxWidth
-    && c.gutter === DEFAULT_COLUMNS.gutter
-    && c.margin === DEFAULT_COLUMNS.margin;
-}
-
-export function parseColumnVars(vars: Record<string, string>): Partial<ColumnsState> {
-  const out: Partial<ColumnsState> = {};
-  const count = parseInt(vars['--columns-count'] ?? '', 10);
-  if (Number.isFinite(count) && count > 0) out.count = count;
-  const maxWidth = parseFloat(vars['--columns-max-width'] ?? '');
-  if (Number.isFinite(maxWidth)) out.maxWidth = Math.round(maxWidth);
-  const gutter = parseFloat(vars['--columns-gutter'] ?? '');
-  if (Number.isFinite(gutter)) out.gutter = Math.round(gutter);
-  const margin = parseFloat(vars['--columns-margin'] ?? '');
-  if (Number.isFinite(margin)) out.margin = Math.round(margin);
+export const VIEWPORT_COLUMN_NAMES: readonly string[] = COLUMN_VIEWPORTS.flatMap((viewport) =>
+  COLUMN_PROPERTIES.map((property) => columnVarName(viewport, property)),
+);
+
+export const STRUCTURAL_COLUMN_NAMES = ['--columns-gutter', '--columns-margin'] as const;
+
+export const COLUMN_VAR_NAMES: readonly string[] = [COLUMN_COUNT_NAME, COLUMN_MAX_WIDTH_NAME, ...VIEWPORT_COLUMN_NAMES];
+
+export const COLUMN_DEFAULTS: Readonly<ColumnsState> = {
+  count: 12,
+  maxWidth: 1440,
+  viewports: {
+    desktop: { gutter: 32, margin: 32 },
+    tablet: { gutter: 24, margin: 24 },
+    phone: { gutter: 16, margin: 16 },
+  },
+};
+
+export function defaultColumns(): ColumnsState {
+  return structuredClone(COLUMN_DEFAULTS);
+}
+
+/** Each name appears only when its value differs from the tokens.css default. */
+export function columnsToVars(c: ColumnsState): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (c.count !== COLUMN_DEFAULTS.count) out[COLUMN_COUNT_NAME] = String(c.count);
+  if (c.maxWidth !== COLUMN_DEFAULTS.maxWidth) out[COLUMN_MAX_WIDTH_NAME] = `${c.maxWidth}px`;
+  for (const viewport of COLUMN_VIEWPORTS) {
+    for (const property of COLUMN_PROPERTIES) {
+      const value = c.viewports[viewport][property];
+      if (value !== COLUMN_DEFAULTS.viewports[viewport][property]) {
+        out[columnVarName(viewport, property)] = `${value}px`;
+      }
+    }
+  }
   return out;
 }
 
+function parseLength(raw: string | undefined): number | undefined {
+  const length = parseFloat(raw ?? '');
+  return Number.isFinite(length) ? Math.round(length) : undefined;
+}
+
+/** A name the bag lacks, or holds in a form the editor cannot edit, keeps its default. */
+export function columnsFromVars(vars: Record<string, string>): ColumnsState {
+  const columns = defaultColumns();
+  const count = parseInt(vars[COLUMN_COUNT_NAME] ?? '', 10);
+  if (Number.isFinite(count) && count > 0) columns.count = count;
+  const maxWidth = parseLength(vars[COLUMN_MAX_WIDTH_NAME]);
+  if (maxWidth !== undefined) columns.maxWidth = maxWidth;
+  for (const viewport of COLUMN_VIEWPORTS) {
+    for (const property of COLUMN_PROPERTIES) {
+      const value = parseLength(vars[columnVarName(viewport, property)]);
+      if (value !== undefined) columns.viewports[viewport][property] = value;
+    }
+  }
+  return columns;
+}
+
 /**
  * Loader: route the relevant entries from a freshly-loaded theme's vars bag
  * into `next.columns` and remove them from the bag so derivation stays
  * single-source. Mutates `next` and `rawVars` in place.
  */
-export function loadColumnsFromVars(
-  next: import('../../store/editorTypes').EditorState,
-  rawVars: Record<string, string>,
-): void {
-  const overrides = parseColumnVars(rawVars);
-  next.columns = { ...DEFAULT_COLUMNS, ...overrides };
+export function loadColumnsFromVars(next: EditorState, rawVars: Record<string, string>): void {
+  next.columns = columnsFromVars(rawVars);
   for (const name of COLUMN_VAR_NAMES) delete rawVars[name];
 }
+
+interface FlatColumnsState {
+  count: number;
+  maxWidth: number;
+  gutter: number;
+  margin: number;
+}
+
+// The flat state's old defaults rendered nothing, so a session sitting on them
+// takes today's defaults instead of pinning a 16px desktop gutter.
+const FLAT_DEFAULTS: FlatColumnsState = { count: 12, maxWidth: 1440, gutter: 16, margin: 0 };
+
+/**
+ * A session persisted before the per-viewport state holds one flat set, which
+ * the renderer wrote to the names that are now the count, the max width and
+ * the desktop gutter and margin. Its `0` margin is the one every shipped theme
+ * held, so it takes today's default as a stored theme's does.
+ */
+export function normalizeColumnsState(raw: ColumnsState | FlatColumnsState): ColumnsState {
+  if ('viewports' in raw) return raw;
+  const columns = defaultColumns();
+  const isFlatDefault = (Object.keys(FLAT_DEFAULTS) as (keyof FlatColumnsState)[])
+    .every((key) => raw[key] === FLAT_DEFAULTS[key]);
+  if (isFlatDefault) return columns;
+  columns.count = raw.count;
+  columns.maxWidth = raw.maxWidth;
+  columns.viewports.desktop.gutter = raw.gutter;
+  if (raw.margin !== FLAT_DEFAULTS.margin) columns.viewports.desktop.margin = raw.margin;
+  return columns;
+}