From 0eb21647c368aa556d26ed5dc3fd44c6e672cfd7 Mon Sep 17 00:00:00 2001
From: SylvainDruaux <sydru06@gmail.com>
Date: Mon, 19 Oct 2026 23:05:31 +0200
Subject: [PATCH] feat(preview): add a column guide over the canvas
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A new toolbar button, next to the breakpoints buttons, opens the column
guide's menu. When on, the guide draws full-height columns over the
preview, under the selection outlines. It never takes a click and never
writes to the project. It works in the desktop app and in Studio, which
share the same implementation.

In a Lumos project, the guide reads the layout variables at the current
preview width: the column count from --site-column-count, --site-columns
or --_column-count, and the margin, gutter and max width from
--site-margin, --site-gutter and --max-width-main. Fluid clamp() values
are resolved to pixels by the preview frame.

Without those variables, Stacki's defaults apply: 12 columns, a fluid
margin (16–48px) and gutter (16–32px), and no max width.

In the menu, the column count can be picked from an editable list of
whole numbers from 4 to 24, or read from a project variable. A count
outside that range is ignored, and the menu says why. The margin, gutter
and max width take a length (px or rem) or a project variable. Reset
brings back the project's value or the default.

Colour, opacity, numbers and visibility are saved per project, and ⇧G
shows or hides the guide. The menu reuses the style panel's controls,
which adds a preview edge to eslint.config.mjs.
---
 electron/preload/frameBasics.ts               |   4 +
 electron/preload/frameDesign.ts               |   5 +-
 electron/preload/frameGuide.ts                | 243 ++++++
 electron/preload/frameQueries.ts              |   9 +-
 electron/preload/frameReports.ts              |   3 +-
 eslint.config.mjs                             |  11 +
 src/app/shell/AppPanes.tsx                    |   1 +
 src/features/preview/GuideMenu.tsx            | 789 ++++++++++++++++++
 src/features/preview/GuideOverlay.tsx         |  51 ++
 src/features/preview/PreviewPane.tsx          |  35 +-
 src/features/preview/PreviewToolbar.tsx       |   4 +
 src/features/preview/guide.css                | 110 +++
 src/features/preview/guideModel.ts            | 545 ++++++++++++
 src/features/preview/guideSettings.ts         | 277 ++++++
 src/features/preview/previewMessages.ts       |  86 ++
 src/features/preview/previewRuntime.ts        |  68 +-
 src/features/style/LayerPopover.tsx           |   6 +-
 src/ui/Icons.tsx                              |   9 +
 studio/scripts/shared-source.json             |   6 +
 studio/src/app/Editor.tsx                     |   1 +
 studio/src/features/preview/PreviewCanvas.tsx |  29 +-
 studio/src/features/preview/previewClient.ts  |   3 +
 studio/src/features/preview/previewKeys.ts    |   2 +
 studio/src/features/preview/usePreview.ts     |  36 +-
 test/renderer/preview/guideModel.test.js      | 326 ++++++++
 test/renderer/preview/guideSettings.test.js   | 118 +++
 test/renderer/preview/previewMessages.test.js |  64 ++
 27 files changed, 2812 insertions(+), 29 deletions(-)
 create mode 100644 electron/preload/frameGuide.ts
 create mode 100644 src/features/preview/GuideMenu.tsx
 create mode 100644 src/features/preview/GuideOverlay.tsx
 create mode 100644 src/features/preview/guide.css
 create mode 100644 src/features/preview/guideModel.ts
 create mode 100644 src/features/preview/guideSettings.ts
 create mode 100644 test/renderer/preview/guideModel.test.js
 create mode 100644 test/renderer/preview/guideSettings.test.js

diff --git a/electron/preload/frameBasics.ts b/electron/preload/frameBasics.ts
index f8b56738..b19c0684 100644
--- a/electron/preload/frameBasics.ts
+++ b/electron/preload/frameBasics.ts
@@ -27,6 +27,10 @@ export type GapRow = { top: number; bottom: number; items: DOMRect[] };
 // come from the project's markup, and what lies below the bound is skipped.
 export const PRELOAD_LIMITS = { domDepthMax: 512, cssRuleDepthMax: 64 } as const;
 
+// Marks the elements the canvas adds to the page to measure it: its own
+// writes, which never start a page walk (mutationKind in frameReports.ts).
+export const PROBE_ATTR = 'data-avb-probe';
+
 export const isElement = (node: Node): node is Element => node.nodeType === 1;
 export const isComment = (node: Node): node is Comment => node.nodeType === 8;
 export const isText = (node: Node): node is Text => node.nodeType === 3;
diff --git a/electron/preload/frameDesign.ts b/electron/preload/frameDesign.ts
index 573f5881..3afc732d 100644
--- a/electron/preload/frameDesign.ts
+++ b/electron/preload/frameDesign.ts
@@ -175,7 +175,10 @@ function forwardShortcut(event: KeyboardEvent): void {
   // usually made, so it has to reach the app from in here too.
   const isClassJump = mod && !event.altKey && !event.shiftKey && event.key === 'Enter';
   const isProperties = !mod && !event.altKey && !event.shiftKey && event.key.toLowerCase() === 'k';
-  if (isDelete || isDuplicate || isClassJump || isProperties) {
+  // ⇧G shows or hides the column guide drawn over this frame. It is replayed
+  // as the key "G", which says Shift on its own (src/features/preview/guideSettings.ts).
+  const isGuide = !mod && !event.altKey && event.shiftKey && event.key.toLowerCase() === 'g';
+  if (isDelete || isDuplicate || isClassJump || isProperties || isGuide) {
     event.preventDefault();
     try {
       window.parent.postMessage(
diff --git a/electron/preload/frameGuide.ts b/electron/preload/frameGuide.ts
new file mode 100644
index 00000000..7eef82b3
--- /dev/null
+++ b/electron/preload/frameGuide.ts
@@ -0,0 +1,243 @@
+// What the column guide is drawn from: the page's own layout values, measured
+// where they apply. The guide is drawn by the app over the frame
+// (src/features/preview/GuideOverlay.tsx); the frame only says how wide the
+// page is and what its margin, gutter, maximum width and column count come to
+// at that width.
+//
+// The values are read from the page, never written to it. A project that
+// declares them (Lumos does: `--site-margin`, `--site-gutter`,
+// `--max-width-main`) gets a guide that follows its fluid `clamp()` values at
+// every preview width; a project that declares none gets `undefined` for each.
+// A variable typed into the guide's menu (`--container-padding`) is sent here
+// by name and measured the same way, so a project with its own names follows
+// its own fluid values too; each name is also read as a whole number, for a
+// column count of the project's own (`--grid-columns`). Which value wins is the app's to decide
+// (src/features/preview/guideModel.ts).
+
+import { PROBE_ATTR } from './frameBasics';
+
+// The custom properties a guide is built from, as Lumos names them. The app
+// keeps the same names (GUIDE_PROJECT_VARIABLES): the preload imports nothing
+// of the renderer's.
+const GUIDE_VARIABLES = {
+  margin: '--site-margin',
+  gutter: '--site-gutter',
+  widthMax: '--max-width-main',
+} as const;
+// A site-wide column count on :root, tried in this order. The app's parser
+// accepts exactly these names (guideModel.ts).
+const SITE_COLUMN_COUNT_VARIABLES = ['--site-column-count', '--site-columns'] as const;
+// Lumos keeps its column count on its auto grid rather than on :root, so a
+// page with no site-wide count is asked through an element of that class.
+const GRID_CLASS = 'grid-autofit';
+const GRID_COLUMN_COUNT_VARIABLE = '--_column-count';
+const COLUMN_COUNT_PATTERN = /^\d{1,3}$/;
+// The names the app may ask about: one per menu value (margin, gutter, maximum
+// width and column count), each a custom property name within the app's own
+// bound (guideModel.ts).
+const MENU_VARIABLES_MAX = 4;
+const MENU_VARIABLE_CHARS_MAX = 64;
+const MENU_VARIABLE_PATTERN = /^--[A-Za-z0-9_-]+$/;
+
+/** How the host sends to the editor: the desktop canvas and Studio each post their own way. */
+export type GuidePost = (message: unknown) => void;
+
+/** The page side of the column guide, as a host wires it. */
+export interface GuideFrame {
+  /** Handles a message from the editor, once the host has checked its sender. */
+  readonly receive: (data: unknown) => void;
+}
+
+// What was last posted, so a measurement that changed nothing stays quiet.
+let lastSent = '';
+let measureQueued = false;
+// The variables typed into the guide's menu, as the editor last sent them.
+let menuVariables: readonly string[] = [];
+let post: GuidePost = () => undefined;
+
+/** Starts reporting the guide's measurements, now and whenever they may change. */
+export function startGuide(send: GuidePost): GuideFrame {
+  post = send;
+  queueGuide();
+  window.addEventListener('load', queueGuide);
+  window.addEventListener('resize', queueGuide);
+  // A page patched in place after an edit (electron/previewClient/morphClient.ts).
+  document.addEventListener('avb:morphed', queueGuide);
+  watchStyles();
+  return { receive: receiveGuideMessage };
+}
+
+// The editor sends the menu's variables when a frame loads and whenever they
+// change. Each message asks for a full report, even one that repeats the last:
+// the editor listening now may not have heard the earlier ones.
+function receiveGuideMessage(data: unknown): void {
+  if (messageType(data) === 'avb:guide-variables') {
+    menuVariables = parseMenuVariables(data);
+    lastSent = '';
+    queueGuide();
+  }
+}
+
+// The dev server delivers CSS by swapping a <style> in <head>, so an edited
+// margin arrives there. A changed root font size or layout arrives as a resize.
+function watchStyles(): void {
+  try {
+    new MutationObserver(queueGuide).observe(document.head, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+    });
+    new ResizeObserver(queueGuide).observe(document.documentElement);
+  } catch {
+    /* No observers: load and resize still report. */
+  }
+}
+
+// One measurement per frame, however many changes asked for it.
+function queueGuide(): void {
+  if (measureQueued) {
+    return;
+  }
+  measureQueued = true;
+  requestAnimationFrame(() => {
+    measureQueued = false;
+    sendGuide();
+  });
+}
+
+function sendGuide(): void {
+  const body = document.body;
+  if (!body) {
+    return;
+  }
+  const message = measureGuide(body);
+  const key = JSON.stringify(message);
+  if (key === lastSent) {
+    return;
+  }
+  lastSent = key;
+  try {
+    post(message);
+  } catch {
+    /* The editor went away. */
+  }
+}
+
+// A throwaway element in the body takes each value as its width, and the
+// engine resolves it: `clamp()`, `rem` and `100vw` come back as pixels at the
+// frame's current width. Each probe is removed before the frame paints.
+function measureGuide(body: HTMLElement) {
+  const root = document.documentElement;
+  const rootStyle = getComputedStyle(root);
+  return {
+    type: 'avb:guide',
+    viewportWidth: root.clientWidth,
+    rootFontSize: Number.parseFloat(rootStyle.fontSize),
+    margin: lengthOf(body, rootStyle, GUIDE_VARIABLES.margin),
+    gutter: lengthOf(body, rootStyle, GUIDE_VARIABLES.gutter),
+    widthMax: lengthOf(body, rootStyle, GUIDE_VARIABLES.widthMax),
+    variables: Object.fromEntries(
+      menuVariables.map((name) => [name, lengthOf(body, rootStyle, name)]),
+    ),
+    // The same names read as a column count: a whole number on :root.
+    counts: Object.fromEntries(
+      menuVariables.map((name) => [name, countOf(rootStyle.getPropertyValue(name))]),
+    ),
+    ...columnCountOf(body, rootStyle),
+  };
+}
+
+// A declared length, in pixels, or undefined for one the page does not declare.
+function lengthOf(
+  body: HTMLElement,
+  rootStyle: CSSStyleDeclaration,
+  variable: string,
+): number | undefined {
+  const declared = rootStyle.getPropertyValue(variable).trim();
+  if (declared === '' || declared === 'none') {
+    return undefined;
+  }
+  const probe = appendProbe(body, `width:var(${variable})`);
+  try {
+    const width = probe.getBoundingClientRect().width;
+    return Number.isFinite(width) ? width : undefined;
+  } finally {
+    probe.remove();
+  }
+}
+
+// The site-wide count when the page declares one, else Lumos's grid count.
+function columnCountOf(body: HTMLElement, rootStyle: CSSStyleDeclaration) {
+  for (const variable of SITE_COLUMN_COUNT_VARIABLES) {
+    const site = countOf(rootStyle.getPropertyValue(variable));
+    if (site !== undefined) {
+      return { columnCount: site, columnVariable: variable };
+    }
+  }
+  const probe = appendProbe(body, '');
+  probe.className = GRID_CLASS;
+  try {
+    const grid = countOf(getComputedStyle(probe).getPropertyValue(GRID_COLUMN_COUNT_VARIABLE));
+    if (grid !== undefined) {
+      return { columnCount: grid, columnVariable: GRID_COLUMN_COUNT_VARIABLE };
+    }
+    return { columnCount: undefined, columnVariable: undefined };
+  } finally {
+    probe.remove();
+  }
+}
+
+// An invisible, zero-height element the canvas owns: its own writes never
+// start a page walk (mutationKind in frameReports.ts).
+function appendProbe(body: HTMLElement, style: string): HTMLElement {
+  const probe = document.createElement('div');
+  probe.setAttribute(PROBE_ATTR, '');
+  probe.setAttribute(
+    'style',
+    'position:absolute;left:0;top:0;height:0;margin:0;padding:0;border:0;' +
+      'box-sizing:content-box;visibility:hidden;pointer-events:none;' +
+      style,
+  );
+  body.appendChild(probe);
+  return probe;
+}
+
+function countOf(declared: string): number | undefined {
+  const value = declared.trim();
+  return COLUMN_COUNT_PATTERN.test(value) ? Number.parseInt(value, 10) : undefined;
+}
+
+function messageType(input: unknown): unknown {
+  if (typeof input !== 'object' || input === null) {
+    return undefined;
+  }
+  return 'type' in input ? input.type : undefined;
+}
+
+// The names the app sent, checked here too: each is written into a probe's
+// style attribute as `var(<name>)`, so only plain custom property names are
+// accepted. A message with an invalid name, or too many, measures nothing.
+function parseMenuVariables(input: unknown): readonly string[] {
+  if (typeof input !== 'object' || input === null) {
+    return [];
+  }
+  const names: unknown = 'names' in input ? input.names : undefined;
+  if (!Array.isArray(names)) {
+    return [];
+  }
+  if (names.length > MENU_VARIABLES_MAX) {
+    return [];
+  }
+  const valid = names.filter(isMenuVariable);
+  return valid.length === names.length ? valid : [];
+}
+
+function isMenuVariable(name: unknown): name is string {
+  if (typeof name !== 'string') {
+    return false;
+  }
+  if (name.length > MENU_VARIABLE_CHARS_MAX) {
+    return false;
+  }
+  return MENU_VARIABLE_PATTERN.test(name);
+}
diff --git a/electron/preload/frameQueries.ts b/electron/preload/frameQueries.ts
index d677af24..ac34604b 100644
--- a/electron/preload/frameQueries.ts
+++ b/electron/preload/frameQueries.ts
@@ -2,11 +2,12 @@
 // it tracks, scrolling a node into view and the viewport height to freeze; and
 // starting the frame once the document is ready.
 
-import { isElement, isText } from './frameBasics';
+import { PROBE_ATTR, isElement, isText } from './frameBasics';
 import { queryAuthoredStyles } from './frameStyleSources';
 import { list, pathText, text } from '../../shared/core/boundary';
 import { LIMITS } from '../../shared/core/limits';
 import { freezeViewportHeight, report } from './frameViewport';
+import { startGuide, type GuideFrame } from './frameGuide';
 import {
   PATH_ATTR,
   STAMP_ATTRIBUTE,
@@ -24,7 +25,6 @@ import {
 } from './frameRegions';
 import { ownClasses, resetThinCache } from './frameMeasure';
 import {
-  PROBE_ATTR,
   forgetReportedKeys,
   paintOpened,
   scrollPathIntoView,
@@ -136,6 +136,7 @@ export function listenForQueries(): void {
       reportRender();
       return;
     }
+    guideFrame?.receive(data);
     if (data['type'] === 'avb:track' && Array.isArray(data['paths'])) {
       track(data, data['paths']);
     }
@@ -380,9 +381,13 @@ const track = (data: Record<string, unknown>, paths: unknown[]) => {
   }
 };
 
+// The column guide's page side, once the frame has started.
+let guideFrame: GuideFrame | undefined;
+
 const start = () => {
   report();
   startOutlines();
+  guideFrame = startGuide((message) => window.parent.postMessage(message, '*'));
   // Tell the app which route this frame is on (used by interactive
   // preview mode to follow link navigation).
   try {
diff --git a/electron/preload/frameReports.ts b/electron/preload/frameReports.ts
index d07a4e98..31ea6e11 100644
--- a/electron/preload/frameReports.ts
+++ b/electron/preload/frameReports.ts
@@ -6,7 +6,7 @@ import { authoredStyleMutation } from './frameAuthoredStyles';
 // writes never trigger a pass.
 
 import type { Rect, Spacing } from './frameBasics';
-import { isComment, isElement, isText } from './frameBasics';
+import { PROBE_ATTR, isComment, isElement, isText } from './frameBasics';
 import {
   PATH_ATTR,
   elementsWithPath,
@@ -470,7 +470,6 @@ export const remeasureStyles = () => {
 // colour the style panel asked about. Its own writes are now told apart by
 // what they touched, never by timing.
 type MutationKind = 'none' | 'css' | 'page';
-export const PROBE_ATTR = 'data-avb-probe';
 const ownElement = (node: Node): boolean => {
   if (!isElement(node)) {
     return false;
diff --git a/eslint.config.mjs b/eslint.config.mjs
index fa8d596a..544e5913 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -303,6 +303,17 @@ const SOURCE_LAYERS = {
     ],
     // The history panel draws commits with git's file and branch widgets.
     history: ['features/git/BranchActions', 'features/git/FileBrowser', 'features/git/FileStatus'],
+    // The column guide's menu is built from the style panel's controls.
+    preview: [
+      'features/style/LayerPopover',
+      'features/style/SizeKit',
+      'features/style/VariableConnect',
+      'features/style/components/ColorSwatch',
+      'features/style/components/DragSlider',
+      'features/style/components/FieldLabel',
+      'features/style/components/Select',
+      'features/style/components/useScrub',
+    ],
     // A variable's value is edited with the style panel's value editors.
     variables: [
       'features/style/CustomValueEditor',
diff --git a/src/app/shell/AppPanes.tsx b/src/app/shell/AppPanes.tsx
index a56ef936..c4dd3a0a 100644
--- a/src/app/shell/AppPanes.tsx
+++ b/src/app/shell/AppPanes.tsx
@@ -58,6 +58,7 @@ export function CanvasPane({ app }: { readonly app: ShellView }) {
       focusWhole={app.focusWhole}
       device={app.device}
       onDevice={app.setDevice}
+      projectPath={app.project.path}
       judgeEvent={app.judgeEvent}
       onStaleEvent={app.onStaleEvent}
       onPreviewReload={app.onPreviewReload}
diff --git a/src/features/preview/GuideMenu.tsx b/src/features/preview/GuideMenu.tsx
new file mode 100644
index 00000000..7bb6f716
--- /dev/null
+++ b/src/features/preview/GuideMenu.tsx
@@ -0,0 +1,789 @@
+import { useCallback, useRef, useState, type ReactElement } from 'react';
+import { CloseIcon, GuideIcon, PencilIcon } from '../../ui/Icons';
+import useDismiss from '../../ui/useDismiss';
+import LayerPopover from '../style/LayerPopover';
+import ColorSwatch from '../style/components/ColorSwatch';
+import FieldLabel from '../style/components/FieldLabel';
+import DragSlider from '../style/components/DragSlider';
+import Select from '../style/components/Select';
+import useScrub from '../style/components/useScrub';
+import { stepSizeKey, useFollowingDraft } from '../style/SizeKit';
+import VariableConnect from '../style/VariableConnect';
+import {
+  GUIDE_COLUMN_CHOICES_DEFAULT,
+  GUIDE_COLUMN_COUNT_DEFAULT,
+  GUIDE_DEFAULTS,
+  GUIDE_FLUID_DEFAULTS,
+  GUIDE_LIMITS,
+  GUIDE_PROJECT_VARIABLES,
+  addGuideColumnChoice,
+  clampGuideOpacity,
+  fluidText,
+  guideColumnOptions,
+  guideProjectCount,
+  guideSizeText,
+  isGuideColumnPick,
+  parseGuideColumnCount,
+  parseGuideSize,
+  removeGuideColumnChoice,
+  resetGuideColumnChoices,
+  type GuideColumnOption,
+  type GuideColumnSetting,
+  type GuideMetrics,
+  type GuideSettings,
+  type GuideSize,
+  type GuideValue,
+  type ResolvedGuide,
+} from './guideModel';
+import { parseGuideColor, type GuideUpdate } from './guideSettings';
+import './guide.css';
+
+// The preview toolbar's column-guide button and the menu it opens. Every row
+// is a control from the style panel, so the menu reads and behaves like the
+// panel: the same labels, fields, slider, swatch and switch.
+
+const MENU_WIDTH_PX = 280;
+const MENU_EDGE_PX = 8;
+const { columnPickMax, columnPickMin } = GUIDE_LIMITS;
+const COUNT_RANGE = `A whole number from ${columnPickMin} to ${columnPickMax}.`;
+const COUNT_SPAN = `${columnPickMin}–${columnPickMax}`;
+
+export interface GuideMenuProps {
+  readonly settings: GuideSettings;
+  readonly update: GuideUpdate;
+  /** What the frame measured; undefined until it reports. */
+  readonly metrics: GuideMetrics | undefined;
+  readonly guide: ResolvedGuide | undefined;
+  /** Canvas mode draws no overlays, so the guide has nowhere to show. */
+  readonly available: boolean;
+}
+
+export function GuideMenu(props: GuideMenuProps) {
+  const buttonRef = useRef<HTMLButtonElement>(null);
+  const [anchor, setAnchor] = useState<HTMLElement | undefined>(undefined);
+  const close = useCallback(() => setAnchor(undefined), []);
+  // The popover closes on clicks in the app's own window; a click in the
+  // canvas lands in the frame's document instead, which only this hears. No
+  // element is passed, so a click inside the menu never counts as outside.
+  useDismiss(undefined, { active: anchor !== undefined }, close);
+  const title = props.available ? 'Column guide — ⇧G' : 'Column guide — not shown in Canvas';
+  return (
+    <div className="device-btns guide-btns">
+      <button
+        ref={buttonRef}
+        type="button"
+        className={props.settings.visible && props.available ? 'on' : ''}
+        title={title}
+        aria-label="Column guide"
+        aria-haspopup="dialog"
+        aria-expanded={anchor !== undefined}
+        disabled={!props.available}
+        onClick={() =>
+          setAnchor(anchor === undefined ? (buttonRef.current ?? undefined) : undefined)
+        }
+      >
+        <GuideIcon size={13} />
+      </button>
+      {anchor !== undefined ? (
+        <LayerPopover
+          anchorEl={anchor}
+          ariaLabel="Column guide"
+          span={menuSpan(anchor)}
+          onClose={close}
+        >
+          <GuideMenuRows {...props} />
+        </LayerPopover>
+      ) : undefined}
+    </div>
+  );
+}
+
+function GuideMenuRows({ settings, update, metrics, guide }: GuideMenuProps) {
+  // The menu is portaled outside the style panel, so style-panel-surface gives
+  // its controls the panel's own button and field rules instead of the app-wide
+  // ones (see styles.css).
+  return (
+    <div className="guide-menu style-panel-surface">
+      <SwitchRow
+        label="Guide"
+        value={settings.visible}
+        onChange={(visible) => update((previous) => ({ ...previous, visible }))}
+      />
+      <ColumnsRow settings={settings} update={update} metrics={metrics} />
+      <ColorRow settings={settings} update={update} />
+      <OpacityRow settings={settings} update={update} />
+      <SwitchRow
+        label="Numbers"
+        value={settings.numbers}
+        onChange={(numbers) => update((previous) => ({ ...previous, numbers }))}
+      />
+      <div className="embed-editor_display-menu-divider" />
+      <SizeRow
+        label="Margin"
+        value={guide?.margin}
+        setting={settings.margin}
+        projectVariable={GUIDE_PROJECT_VARIABLES.margin}
+        placeholder={fluidText(GUIDE_FLUID_DEFAULTS.margin)}
+        onChange={(margin) => update((previous) => ({ ...previous, margin }))}
+      />
+      <SizeRow
+        label="Gutter"
+        value={guide?.gutter}
+        setting={settings.gutter}
+        projectVariable={GUIDE_PROJECT_VARIABLES.gutter}
+        placeholder={fluidText(GUIDE_FLUID_DEFAULTS.gutter)}
+        onChange={(gutter) => update((previous) => ({ ...previous, gutter }))}
+      />
+      <SizeRow
+        label="Max width"
+        value={guide?.widthMax}
+        setting={settings.widthMax}
+        projectVariable={GUIDE_PROJECT_VARIABLES.widthMax}
+        placeholder="None"
+        onChange={(widthMax) => update((previous) => ({ ...previous, widthMax }))}
+      />
+      <GuideMenuNotes settings={settings} guide={guide} metrics={metrics} />
+    </div>
+  );
+}
+
+// The counts in order, the one the guide defers to named "(Project)" or
+// "(Default)". The pencil opens the list's editor under the row.
+function ColumnsRow({
+  settings,
+  update,
+  metrics,
+}: Pick<GuideMenuProps, 'settings' | 'update' | 'metrics'>) {
+  const [editing, setEditing] = useState(false);
+  const projectCount = metrics === undefined ? undefined : guideProjectCount(metrics, settings);
+  const options = guideColumnOptions(settings.columnChoices, projectCount);
+  return (
+    <>
+      <div className="embed-editor_size-row">
+        <ResetLabel
+          label="Columns"
+          changed={settings.columns !== GUIDE_DEFAULTS.columns}
+          onReset={() => update((previous) => ({ ...previous, columns: GUIDE_DEFAULTS.columns }))}
+        />
+        <div className="guide-columns-field">
+          <Select
+            value={columnValue(settings.columns, options)}
+            options={options.map(columnItem)}
+            ariaLabel="Column count"
+            onChange={(value) =>
+              update((previous) => ({ ...previous, columns: columnSetting(value) }))
+            }
+          />
+          <button
+            type="button"
+            className={`embed-editor_icon-btn ${editing ? 'is-active' : ''}`}
+            aria-pressed={editing}
+            title="Edit column counts"
+            aria-label="Edit column counts"
+            onClick={() => setEditing(!editing)}
+          >
+            <PencilIcon />
+          </button>
+        </div>
+      </div>
+      {editing ? (
+        <>
+          <ColumnChoices
+            settings={settings}
+            update={update}
+            options={options}
+            projectCount={projectCount}
+          />
+          <ColumnVariableRow settings={settings} update={update} metrics={metrics} />
+          <div className="embed-editor_display-menu-divider" />
+        </>
+      ) : undefined}
+    </>
+  );
+}
+
+// The list as the content panel's tags: a chip per count, an × on each one
+// that can go, and a field that adds a count. The default count and the
+// project's stay, and the field closes once the menu holds its limit.
+function ColumnChoices({
+  settings,
+  update,
+  options,
+  projectCount,
+}: Pick<GuideMenuProps, 'settings' | 'update'> & {
+  readonly options: readonly GuideColumnOption[];
+  readonly projectCount: number | undefined;
+}) {
+  const [draft, setDraft] = useState('');
+  const outOfRange = draft !== '' && parseGuideColumnCount(draft) === undefined;
+  const add = (count: number): void =>
+    update((previous) => ({
+      ...previous,
+      columnChoices: addGuideColumnChoice(previous.columnChoices, count, projectCount),
+    }));
+  const remove = (count: number): void =>
+    update((previous) =>
+      previous.columnChoices.includes(count) ? removeGuideColumnChoice(previous, count) : previous,
+    );
+  const edited = settings.columnChoices.join() !== GUIDE_COLUMN_CHOICES_DEFAULT.join();
+  return (
+    <>
+      <div className="content-tags guide-column-choices">
+        {options.map((option) => (
+          <span key={option.count} className="content-chip">
+            {option.count}
+            {columnRemovable(option) ? (
+              <button
+                type="button"
+                className="ghost"
+                title={`Remove ${option.count}`}
+                aria-label={`Remove ${option.count}`}
+                onClick={() => remove(option.count)}
+              >
+                <CloseIcon size={9} />
+              </button>
+            ) : undefined}
+          </span>
+        ))}
+        <ColumnAdd
+          draft={draft}
+          outOfRange={outOfRange}
+          full={options.length >= GUIDE_LIMITS.columnChoicesMax}
+          onDraft={setDraft}
+          onAdd={add}
+        />
+        {edited ? (
+          <button
+            type="button"
+            className="ghost guide-column-reset"
+            onClick={() => update(resetGuideColumnChoices)}
+          >
+            Reset list
+          </button>
+        ) : undefined}
+      </div>
+      {outOfRange ? (
+        <p className="embed-editor_more-note guide-note-error">{COUNT_RANGE}</p>
+      ) : undefined}
+    </>
+  );
+}
+
+// The variable the "(Project)" entry reads. Untouched, it shows the one the
+// guide found, as a chip, or "None"; a name typed or picked replaces it, and
+// emptied or reset, the guide looks for its own again. The list leaves out
+// colours and fonts, as for any property that takes a number.
+function ColumnVariableRow({
+  settings,
+  update,
+  metrics,
+}: Pick<GuideMenuProps, 'settings' | 'update' | 'metrics'>) {
+  const onChange = (columnVariable: string | undefined): void =>
+    update((previous) => ({ ...previous, columnVariable }));
+  const commit = (text: string): void => {
+    if (text.trim() === '') {
+      onChange(undefined);
+      return;
+    }
+    const size = parseGuideSize(text);
+    if (size?.kind === 'variable') {
+      onChange(size.name);
+    }
+  };
+  const shown = settings.columnVariable ?? metrics?.columns?.variable;
+  return (
+    <div className="embed-editor_size-row">
+      <ResetLabel
+        label="Variable"
+        changed={settings.columnVariable !== undefined}
+        onReset={() => onChange(undefined)}
+      />
+      <div className="embed-editor_field">
+        <GuideField
+          value={shown === undefined ? '' : `var(${shown})`}
+          ariaLabel="Column count variable"
+          placeholder="None"
+          title="A project variable holding a whole number (--name)."
+          variables="Connect the column count to a variable"
+          variableProperty="column-count"
+          onCommit={commit}
+        />
+      </div>
+    </div>
+  );
+}
+
+// The tag field's input. It takes digits only, two at most, so the range is
+// all a count can miss; Enter adds one within it, and leaving the field adds
+// it and clears the text, a count out of range included.
+function ColumnAdd({
+  draft,
+  outOfRange,
+  full,
+  onDraft,
+  onAdd,
+}: {
+  readonly draft: string;
+  readonly outOfRange: boolean;
+  readonly full: boolean;
+  readonly onDraft: (draft: string) => void;
+  readonly onAdd: (count: number) => void;
+}) {
+  const add = (): boolean => {
+    const count = parseGuideColumnCount(draft);
+    if (count === undefined) {
+      return false;
+    }
+    onAdd(count);
+    return true;
+  };
+  return (
+    <input
+      className={outOfRange ? 'guide-column-out' : undefined}
+      value={draft}
+      inputMode="numeric"
+      maxLength={2}
+      disabled={full}
+      placeholder={full ? `${GUIDE_LIMITS.columnChoicesMax} at most` : 'Add…'}
+      aria-label="Add a column count"
+      aria-invalid={outOfRange}
+      title={COUNT_RANGE}
+      onChange={(event) => onDraft(event.target.value.replace(/\D/g, '').slice(0, 2))}
+      onBlur={() => {
+        add();
+        onDraft('');
+      }}
+      onKeyDown={(event) => {
+        if (event.key === 'Enter') {
+          event.preventDefault();
+          if (add()) {
+            onDraft('');
+          }
+        }
+      }}
+    />
+  );
+}
+
+function ColorRow({ settings, update }: Pick<GuideMenuProps, 'settings' | 'update'>) {
+  const commit = (text: string): void => {
+    const color = parseGuideColor(text);
+    if (color !== undefined) {
+      update((previous) => ({ ...previous, color }));
+    }
+  };
+  return (
+    <div className="embed-editor_size-row">
+      <ResetLabel
+        label="Color"
+        changed={settings.color !== GUIDE_DEFAULTS.color}
+        onReset={() => update((previous) => ({ ...previous, color: GUIDE_DEFAULTS.color }))}
+      />
+      <div className="embed-editor_type-field">
+        <ColorSwatch value={settings.color} ariaLabel="Guide color" onChange={commit} />
+        <GuideField value={settings.color} ariaLabel="Guide color" onCommit={commit} />
+      </div>
+    </div>
+  );
+}
+
+function OpacityRow({ settings, update }: Pick<GuideMenuProps, 'settings' | 'update'>) {
+  const commit = (value: number): void =>
+    update((previous) => ({ ...previous, opacity: clampGuideOpacity(value) }));
+  return (
+    <div className="embed-editor_size-row">
+      <ResetLabel
+        label="Opacity"
+        changed={settings.opacity !== GUIDE_DEFAULTS.opacity}
+        onReset={() => update((previous) => ({ ...previous, opacity: GUIDE_DEFAULTS.opacity }))}
+      />
+      <div className="embed-editor_shadow-field">
+        <DragSlider
+          value={settings.opacity}
+          min={GUIDE_LIMITS.opacityMin}
+          max={GUIDE_LIMITS.opacityMax}
+          step={GUIDE_LIMITS.opacityStep}
+          ariaLabel="Guide opacity"
+          onInput={commit}
+          onCommit={commit}
+        />
+        <div className="embed-editor_field embed-editor_grad-num embed-editor_opacity-num">
+          <GuideField
+            value={String(settings.opacity)}
+            ariaLabel="Guide opacity"
+            inputMode="decimal"
+            onCommit={(text) => {
+              const value = Number.parseFloat(text);
+              if (Number.isFinite(value)) {
+                commit(value);
+              }
+            }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// The panel's clearable caption: dim at the default, a blue pill once changed,
+// whose menu (or an Option-click) puts the default back.
+function ResetLabel({
+  label,
+  changed,
+  onReset,
+}: {
+  readonly label: string;
+  readonly changed: boolean;
+  readonly onReset: () => void;
+}) {
+  return (
+    <FieldLabel className="embed-editor_size-label" active={changed} onReset={onReset}>
+      {label}
+    </FieldLabel>
+  );
+}
+
+function SwitchRow({
+  label,
+  value,
+  onChange,
+}: {
+  readonly label: string;
+  readonly value: boolean;
+  readonly onChange: (value: boolean) => void;
+}) {
+  return (
+    <div className="embed-editor_size-row">
+      <span className="u-field-label embed-editor_size-label">{label}</span>
+      <button
+        type="button"
+        className={`cms-toggle ${value ? 'on' : ''}`}
+        aria-pressed={value}
+        aria-label={label}
+        onClick={() => onChange(!value)}
+      >
+        <span className="cms-toggle-knob" />
+        <span className="cms-toggle-label">{value ? 'On' : 'Off'}</span>
+      </button>
+    </div>
+  );
+}
+
+// A margin, gutter or maximum width: a length in px or rem, or a variable of
+// the project's own, picked from the panel's variable list or typed. Untouched,
+// it shows the default it draws with: the project's Lumos variable as a chip,
+// or the fluid range the placeholder names. Emptied or reset, it goes back to
+// that default. Like every field in the panel, it is always editable: the
+// guide only draws, so changing it never touches the project.
+function SizeRow({
+  label,
+  value,
+  setting,
+  projectVariable,
+  placeholder,
+  onChange,
+}: {
+  readonly label: string;
+  readonly value: GuideValue | undefined;
+  readonly setting: GuideSize | undefined;
+  readonly projectVariable: string;
+  readonly placeholder: string;
+  readonly onChange: (size: GuideSize | undefined) => void;
+}) {
+  const commit = (text: string): void => {
+    if (text.trim() === '') {
+      onChange(undefined);
+      return;
+    }
+    const size = parseGuideSize(text);
+    if (size !== undefined) {
+      onChange(size);
+    }
+  };
+  return (
+    <div className="embed-editor_size-row">
+      <ResetLabel
+        label={label}
+        changed={setting !== undefined}
+        onReset={() => onChange(undefined)}
+      />
+      <div className="embed-editor_field">
+        <GuideField
+          value={sizeShown(value, setting, projectVariable)}
+          ariaLabel={label}
+          placeholder={placeholder}
+          title={sizeTitle(value, setting, projectVariable)}
+          variables={`Connect ${label} to a variable`}
+          onCommit={commit}
+        />
+      </div>
+    </div>
+  );
+}
+
+// The notes under the menu: which of the menu's variables the page does not
+// declare, so the field's text is not what the guide draws with. The column
+// variable must also hold a whole number.
+function GuideMenuNotes({
+  settings,
+  guide,
+  metrics,
+}: Pick<GuideMenuProps, 'settings' | 'guide' | 'metrics'>) {
+  const missing = guide === undefined ? [] : missingVariables(settings, guide);
+  const countNotes = metrics === undefined ? [] : columnCountNotes(settings, metrics);
+  return (
+    <>
+      {missing.map((name) => (
+        <p key={name} className="embed-editor_more-note guide-note-error">
+          {name} is not declared on this page, so its default is used.
+        </p>
+      ))}
+      {countNotes.map((note) => (
+        <p key={note} className="embed-editor_more-note guide-note-error">
+          {note}
+        </p>
+      ))}
+    </>
+  );
+}
+
+// Why a column variable is not what the guide counts with: it gives no whole
+// number, or one outside the menu's range. The menu's own variable and the
+// one the guide found are checked alike.
+function columnCountNotes(settings: GuideSettings, metrics: GuideMetrics): readonly string[] {
+  const notes: string[] = [];
+  const name = settings.columnVariable;
+  if (name !== undefined) {
+    const note = columnCountNote(name, metrics.variableCounts[name]);
+    if (note !== undefined) {
+      notes.push(note);
+    }
+  }
+  const detected = metrics.columns;
+  if (detected !== undefined) {
+    const note = columnCountNote(detected.variable, detected.count);
+    if (note !== undefined) {
+      notes.push(note);
+    }
+  }
+  return notes;
+}
+
+function columnCountNote(name: string, declared: number | undefined): string | undefined {
+  if (declared === undefined) {
+    return (
+      `${name} is not declared on this page, or is not a whole number, so its default is ` + 'used.'
+    );
+  }
+  if (isGuideColumnPick(declared)) {
+    return undefined;
+  }
+  return `${name} is outside ${COUNT_SPAN}, so its default is used.`;
+}
+
+// The panel's text field: follows its value while not focused, steps numbers
+// with the arrow keys, scrubs with a drag, and commits on blur or Enter. Given
+// `variables`, it also carries the panel's variable button, as the style
+// panel's own fields do (LiveInput.tsx): the visible sign that a variable is
+// accepted, and the list of the ones the project defines.
+function GuideField({
+  value,
+  ariaLabel,
+  placeholder,
+  title,
+  inputMode,
+  variables,
+  variableProperty = 'width',
+  onCommit,
+}: {
+  readonly value: string;
+  readonly ariaLabel: string;
+  readonly placeholder?: string;
+  readonly title?: string;
+  readonly inputMode?: 'decimal';
+  /** The variable button's label; absent, the field takes no variable. */
+  readonly variables?: string;
+  /** The CSS property the variable list is filtered for. */
+  readonly variableProperty?: string;
+  readonly onCommit: (text: string) => void;
+}) {
+  const { draft, setDraft, focused } = useFollowingDraft(value);
+  const scrub = useScrub({
+    value: draft,
+    disabled: false,
+    onPreview: setDraft,
+    onInput: () => undefined,
+    onCommit: (text: string) => {
+      setDraft(text);
+      onCommit(text);
+    },
+  });
+  const input = (
+    <input
+      {...scrub.input}
+      className="u-input embed-editor_size-input"
+      value={draft}
+      spellCheck={false}
+      aria-label={ariaLabel}
+      {...(placeholder === undefined ? {} : { placeholder })}
+      {...(title === undefined ? {} : { title })}
+      {...(inputMode === undefined ? {} : { inputMode })}
+      onChange={(event) => setDraft(event.target.value)}
+      onFocus={() => {
+        focused.current = true;
+      }}
+      onBlur={() => {
+        focused.current = false;
+        if (draft === value) {
+          return;
+        }
+        onCommit(draft);
+        setDraft(value);
+      }}
+      onKeyDown={(event) => {
+        const stepped = stepSizeKey(event);
+        if (stepped !== undefined) {
+          setDraft(stepped);
+        }
+      }}
+    />
+  );
+  if (variables === undefined) {
+    return input;
+  }
+  return withVariables(input, { label: variables, property: variableProperty }, (binding) => {
+    setDraft(binding);
+    onCommit(binding);
+  });
+}
+
+// A picked variable replaces the value and is committed at once, as in the
+// panel. The property narrows the list to the variables that fit it.
+function withVariables(
+  input: ReactElement,
+  button: { readonly label: string; readonly property: string },
+  onPick: (binding: string) => void,
+) {
+  return (
+    <VariableConnect
+      code
+      className="is-fill"
+      ariaLabel={button.label}
+      prop={button.property}
+      onPick={onPick}
+    >
+      {input}
+    </VariableConnect>
+  );
+}
+
+// The field's text: the menu's own value, else the project's variable it
+// defaults to (shown as a chip), else empty for the placeholder's default.
+function sizeShown(
+  value: GuideValue | undefined,
+  setting: GuideSize | undefined,
+  projectVariable: string,
+): string {
+  if (setting !== undefined) {
+    return guideSizeText(setting);
+  }
+  return value?.source === 'project' ? `var(${projectVariable})` : '';
+}
+
+// The field's tooltip: where the value comes from, what it is at this width,
+// and what the field takes.
+function sizeTitle(
+  value: GuideValue | undefined,
+  setting: GuideSize | undefined,
+  projectVariable: string,
+): string {
+  const accepts = 'A length (32px, 2rem) or a project variable (--name).';
+  if (value === undefined) {
+    return accepts;
+  }
+  const px = `${Math.round(value.px)}px at this width`;
+  switch (value.source) {
+    case 'project':
+      return `From the project's ${projectVariable}: ${px}.\n${accepts}`;
+    case 'variable':
+      return `${setting?.kind === 'variable' ? setting.name : 'Variable'}: ${px}.\n${accepts}`;
+    case 'fixed':
+      return `${px}.\n${accepts}`;
+    case 'default':
+      return `Default: ${px}.\n${accepts}`;
+    default: {
+      const exhaustive: never = value.source;
+      return exhaustive;
+    }
+  }
+}
+
+// The menu's variables the page does not declare: set, but not what was used.
+function missingVariables(settings: GuideSettings, guide: ResolvedGuide): readonly string[] {
+  const pairs = [
+    [settings.margin, guide.margin],
+    [settings.gutter, guide.gutter],
+    [settings.widthMax, guide.widthMax],
+  ] as const;
+  const names = new Set<string>();
+  for (const [setting, value] of pairs) {
+    if (setting?.kind === 'variable') {
+      if (value?.source !== 'variable') {
+        names.add(setting.name);
+      }
+    }
+  }
+  return [...names];
+}
+
+// The entry the setting selects: a pick equal to the count the guide defers
+// to is that entry, as the list holds that count once.
+function columnValue(setting: GuideColumnSetting, options: readonly GuideColumnOption[]): string {
+  if (setting === 'project') {
+    return 'project';
+  }
+  const deferred = options.find((option) => option.source !== 'list');
+  return deferred?.count === setting ? 'project' : String(setting);
+}
+
+function columnItem(option: GuideColumnOption): { readonly value: string; readonly label: string } {
+  switch (option.source) {
+    case 'project':
+      return { value: 'project', label: `${option.count} (Project)` };
+    case 'default':
+      return { value: 'project', label: `${option.count} (Default)` };
+    case 'list':
+      return { value: String(option.count), label: String(option.count) };
+    default: {
+      const exhaustive: never = option.source;
+      return exhaustive;
+    }
+  }
+}
+
+// Every count of the list can go but the default, and the count the guide
+// defers to, which the list shows whether or not it holds it.
+function columnRemovable(option: GuideColumnOption): boolean {
+  if (option.source === 'list') {
+    return option.count !== GUIDE_COLUMN_COUNT_DEFAULT;
+  }
+  return false;
+}
+
+function columnSetting(value: string): GuideColumnSetting {
+  if (value === 'project') {
+    return value;
+  }
+  const count = Number(value);
+  if (!isGuideColumnPick(count)) {
+    throw new Error(`Guide menu: ${value} is not an offered column count`);
+  }
+  return count;
+}
+
+// Below the button, as wide as the menu, kept inside the window.
+function menuSpan(anchor: HTMLElement): { readonly left: number; readonly width: number } {
+  const rect = anchor.getBoundingClientRect();
+  const leftMax = window.innerWidth - MENU_WIDTH_PX - MENU_EDGE_PX;
+  return { left: Math.max(MENU_EDGE_PX, Math.min(rect.left, leftMax)), width: MENU_WIDTH_PX };
+}
diff --git a/src/features/preview/GuideOverlay.tsx b/src/features/preview/GuideOverlay.tsx
new file mode 100644
index 00000000..a78a947b
--- /dev/null
+++ b/src/features/preview/GuideOverlay.tsx
@@ -0,0 +1,51 @@
+import type { CSSProperties } from 'react';
+import { assert } from '../../../shared/core/assert';
+import { GUIDE_NUMBER_OPACITY, guideColumns, type ResolvedGuide } from './guideModel';
+import type { GuideSettings } from './guideModel';
+import './guide.css';
+
+// The column guide over the preview: full-height columns pinned to the visible
+// part of the page, numbered along the bottom. It is drawn in the overlay
+// layer, before the outlines (PreviewPane.tsx), so every selection and spacing
+// band paints over it; like the rest of that layer it never takes a click.
+//
+// Its geometry is in the frame's CSS pixels; the layer is in screen pixels, so
+// every box is scaled here, exactly as the outlines are.
+export function GuideOverlay({
+  guide,
+  settings,
+  scale,
+}: {
+  readonly guide: ResolvedGuide;
+  readonly settings: Pick<GuideSettings, 'color' | 'numbers' | 'opacity'>;
+  readonly scale: number;
+}) {
+  assert(scale > 0, 'Guide overlay: positive scale');
+  const columns = guideColumns(guide);
+  return (
+    <div className="guide-overlay" aria-hidden="true">
+      {columns.map((column, index) => (
+        <div
+          key={index}
+          className="guide-column"
+          style={{ left: column.xPx * scale, width: column.widthPx * scale }}
+        >
+          <span className="guide-column-fill" style={fillStyle(settings)} />
+          {settings.numbers ? (
+            <span className="guide-column-number" style={numberStyle(settings)}>
+              {index + 1}
+            </span>
+          ) : undefined}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function fillStyle(settings: Pick<GuideSettings, 'color' | 'opacity'>): CSSProperties {
+  return { background: settings.color, opacity: settings.opacity };
+}
+
+function numberStyle(settings: Pick<GuideSettings, 'color'>): CSSProperties {
+  return { color: settings.color, opacity: GUIDE_NUMBER_OPACITY };
+}
diff --git a/src/features/preview/PreviewPane.tsx b/src/features/preview/PreviewPane.tsx
index c5dde9d0..768f243d 100644
--- a/src/features/preview/PreviewPane.tsx
+++ b/src/features/preview/PreviewPane.tsx
@@ -12,6 +12,8 @@ import type { PreviewVerdict } from '../../../shared/page/previewToken';
 import type { PreviewReloadReason } from './previewMessages';
 import './previewViewport.css';
 import type { LiveValue } from '../../ui/liveValue';
+import { GuideOverlay } from './GuideOverlay';
+import { useColumnGuide, type ShownGuide } from './guideSettings';
 
 export { deviceForWidth } from './PreviewToolbar';
 
@@ -50,6 +52,8 @@ interface PreviewPaneProps {
   readonly focusWhole?: boolean;
   readonly device: PreviewDevice;
   readonly onDevice: (device: PreviewDevice) => void;
+  /** The open project: the column guide's settings are kept per project. */
+  readonly projectPath?: string | undefined;
 }
 
 export default function PreviewPane(props: PreviewPaneProps) {
@@ -57,6 +61,12 @@ export default function PreviewPane(props: PreviewPaneProps) {
   const runtime = usePreviewRuntime({ ...props, selPath: props.selPath }, url);
   const dimensions = usePreviewDimensions();
   const sizing = usePreviewSizing(props.device, dimensions, props.onDevice);
+  const columnGuide = useColumnGuide({
+    projectKey: props.projectPath,
+    metrics: runtime.guide,
+    available: props.device !== 'canvas',
+    frame: runtime,
+  });
   return (
     <>
       <PreviewToolbar
@@ -74,9 +84,16 @@ export default function PreviewPane(props: PreviewPaneProps) {
                 onFit: () => props.onDevice('desktop'),
               },
             })}
+        guide={columnGuide.menu}
       />
       <div className="preview-frame-wrap" ref={sizing.wrapRef}>
-        <PreviewContent props={props} url={url} runtime={runtime} sizing={sizing} />
+        <PreviewContent
+          props={props}
+          url={url}
+          runtime={runtime}
+          sizing={sizing}
+          shownGuide={columnGuide.shown}
+        />
       </div>
     </>
   );
@@ -90,11 +107,13 @@ function PreviewContent({
   url,
   runtime,
   sizing,
+  shownGuide,
 }: {
   readonly props: PreviewPaneProps;
   readonly url: string | undefined;
   readonly runtime: Runtime;
   readonly sizing: Sizing;
+  readonly shownGuide: ShownGuide | undefined;
 }) {
   if (url && props.device === 'canvas') {
     return (
@@ -106,7 +125,15 @@ function PreviewContent({
     );
   }
   if (url) {
-    return <DesignPreview props={props} url={url} runtime={runtime} sizing={sizing} />;
+    return (
+      <DesignPreview
+        props={props}
+        url={url}
+        runtime={runtime}
+        sizing={sizing}
+        shownGuide={shownGuide}
+      />
+    );
   }
   return <PreviewPlaceholder props={props} />;
 }
@@ -116,11 +143,13 @@ function DesignPreview({
   url,
   runtime,
   sizing,
+  shownGuide,
 }: {
   readonly props: PreviewPaneProps;
   readonly url: string;
   readonly runtime: Runtime;
   readonly sizing: Sizing;
+  readonly shownGuide: ShownGuide | undefined;
 }) {
   const width = sizing.width;
   const scale = sizing.viewport.scale;
@@ -159,6 +188,8 @@ function DesignPreview({
           borderRadius: width ? 10 * scale : 0,
         }}
       >
+        {/* First in the layer, so the outlines and spacing bands paint over it. */}
+        {shownGuide && <GuideOverlay {...shownGuide} scale={scale} />}
         <PreviewOverlays
           rects={runtime.rects}
           spacing={runtime.spacing}
diff --git a/src/features/preview/PreviewToolbar.tsx b/src/features/preview/PreviewToolbar.tsx
index 3b7ea575..667fe3fd 100644
--- a/src/features/preview/PreviewToolbar.tsx
+++ b/src/features/preview/PreviewToolbar.tsx
@@ -2,6 +2,7 @@ import React, { useEffect, useLayoutEffect, useMemo, useRef, useState } from 're
 import type { IconProps } from '../../ui/Icons';
 import { CanvasIcon, ChevronRightIcon, DesktopIcon, PhoneIcon, TabletIcon } from '../../ui/Icons';
 import { PreviewSizeControls } from './PreviewSizeControls';
+import { GuideMenu, type GuideMenuProps } from './GuideMenu';
 import type { PreviewSizeControlsProps } from './PreviewSizeControls';
 
 export type PreviewDevice = 'desktop' | 'tablet' | 'phone' | 'canvas' | 'custom';
@@ -58,12 +59,14 @@ export function PreviewToolbar({
   activeDevice,
   onDevice,
   sizing,
+  guide,
 }: {
   readonly crumbs: readonly PreviewCrumb[];
   readonly onCrumb?: (id: string | undefined) => void;
   readonly activeDevice: PreviewDevice;
   readonly onDevice: (device: PreviewDevice) => void;
   readonly sizing?: PreviewSizeControlsProps;
+  readonly guide: GuideMenuProps;
 }) {
   const shownCrumbs = useFoldedCrumbs(crumbs);
   const buttonRefs = useRef(new Map<FixedDevice, HTMLButtonElement>());
@@ -85,6 +88,7 @@ export function PreviewToolbar({
         {...(onCrumb === undefined ? {} : { onCrumb })}
         onExpand={shownCrumbs.expand}
       />
+      <GuideMenu {...guide} />
       <div className="device-btns">
         {indicator && <span className="device-indicator" style={indicator} />}
         {DEVICES.map(({ key, Icon, title }) => (
diff --git a/src/features/preview/guide.css b/src/features/preview/guide.css
new file mode 100644
index 00000000..dce19776
--- /dev/null
+++ b/src/features/preview/guide.css
@@ -0,0 +1,110 @@
+/* The column guide over the preview (GuideOverlay.tsx). It fills the overlay
+   layer, which is the visible part of the page, so the columns stay put while
+   the page scrolls under them. Colour and opacity come from the guide's
+   settings, inline. */
+.guide-overlay {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+.guide-column {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-end;
+  align-items: center;
+  /* The numbers keep a small gap above the bottom edge. */
+  padding-bottom: 0.6rem;
+}
+.guide-column-fill {
+  position: absolute;
+  inset: 0;
+}
+.guide-column-number {
+  position: relative;
+  font-family: var(--font);
+  font-size: var(--font-size-lg);
+  line-height: 1;
+  font-variant-numeric: tabular-nums;
+}
+
+/* The toolbar button that opens the guide's menu: a group of its own, styled
+   as the device group beside it. A lone button has no sliding indicator, so it
+   carries the indicator's fill itself while the guide is shown. */
+.device-btns.guide-btns button.on {
+  background: rgba(255, 255, 255, 0.12);
+}
+
+/* The menu takes the panel's label column at its own width: the panel's
+   popovers narrow it for short labels, and "Max width" is not one. */
+.guide-menu {
+  --embed-editor_size-label-w: 64px;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-4);
+}
+
+/* The switch keeps its own width inside the row's grid cell, so its knob
+   sits on its track. */
+.guide-menu .cms-toggle {
+  justify-self: start;
+}
+
+/* The column dropdown takes the row's width, less the pencil beside it. */
+.guide-columns-field {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+}
+.guide-columns-field > :first-child {
+  flex: 1;
+  min-width: 0;
+}
+
+/* Over an icon, the browser looks for a tooltip on the icon and never reaches
+   its button's title. The menu's icons let the pointer through, so the
+   pencil and the variable buttons show their tooltip wherever they are
+   hovered. */
+.guide-menu .embed-editor_icon-btn svg,
+.guide-menu .embed-editor_varconnect-dot svg {
+  pointer-events: none;
+}
+
+/* The list's editor reads as the content panel's tags. Its field takes the
+   room the chips leave, and "Reset list" sits at the end in the chips' grey. */
+.guide-column-choices input {
+  min-width: 56px;
+}
+.guide-column-choices .guide-column-reset {
+  margin-left: auto;
+  padding: 2px 4px;
+  font-size: 11px;
+  color: var(--text-faint);
+  background: transparent;
+}
+
+/* A count out of range reads red, and so does every note that says a value
+   is not what the guide uses. */
+.guide-column-choices input.guide-column-out,
+.guide-menu .guide-note-error {
+  color: var(--color-danger);
+}
+
+/* The note starts where the row labels' text does: they carry the label
+   pill's inner padding. No word is left alone on the last line. */
+.guide-menu .embed-editor_more-note {
+  padding-inline: var(--space-2);
+  text-wrap: pretty;
+}
+
+/* The guide's popover takes the side panels' colour, as part of the canvas
+   chrome, and its controls the panel's own surface steps (.u-surface-page):
+   the panel's grey at rest, one step lighter on hover. */
+.embed-editor_layer-popover-box:has(> .guide-menu) {
+  --surface-control: var(--color-bg-surface);
+  --surface-control-hover: var(--color-bg-surface-raised);
+  background: var(--bg-panel);
+}
diff --git a/src/features/preview/guideModel.ts b/src/features/preview/guideModel.ts
new file mode 100644
index 00000000..9d2ba89a
--- /dev/null
+++ b/src/features/preview/guideModel.ts
@@ -0,0 +1,545 @@
+// The column guide: what it is drawn from, and where each column falls.
+//
+// Each of the margin, the gutter and the maximum width is taken, in order,
+// from the menu (a fixed length, or a variable of the project's own read from
+// the page), then from the project's Lumos variable, measured in the frame at
+// the current preview width (electron/preload/frameGuide.ts), then, for the
+// margin and gutter, from Lumos's fluid starting ranges. The project's value
+// is a default: the guide only draws and never writes to the project, and
+// resetting a field brings that value back. The column count works the same
+// way, the menu's pick over the project's.
+
+import { assert } from '../../../shared/core/assert';
+
+export const GUIDE_LIMITS = {
+  /** The menu's column list, the count it defers to included. */
+  columnChoicesMax: 8,
+  columnPickMax: 24,
+  columnPickMin: 4,
+  colorCharsMax: 64,
+  lengthPxMax: 100_000,
+  lengthRemMax: 6_000,
+  opacityMax: 0.2,
+  opacityMin: 0.06,
+  opacityStep: 0.01,
+  rootFontPxMax: 1_000,
+  /** A variable name typed into the menu, with its leading dashes. */
+  variableCharsMax: 64,
+  /** Margin, gutter, maximum width and column count: one variable each at most. */
+  variablesMax: 4,
+} as const satisfies Record<string, number>;
+
+/** The counts the menu offers until its list is edited. */
+export const GUIDE_COLUMN_CHOICES_DEFAULT: readonly number[] = [6, 8, 10, 12, 16];
+/** The project's count (or the default when it has none), or a count picked in the menu. */
+export type GuideColumnSetting = 'project' | number;
+
+/**
+ * The count used when the project declares none and the setting defers to it.
+ * The menu always offers it: its list can lose every other count, never this one.
+ */
+export const GUIDE_COLUMN_COUNT_DEFAULT = 12;
+/** The numbers are the column colour, this much more opaque than the column. */
+export const GUIDE_NUMBER_OPACITY = 0.5;
+
+/** The variables a project count is read from, in the order they are tried. */
+export const GUIDE_COLUMN_VARIABLES = [
+  '--site-column-count',
+  '--site-columns',
+  '--_column-count',
+] as const;
+export type GuideColumnVariable = (typeof GUIDE_COLUMN_VARIABLES)[number];
+
+export type GuideLengthUnit = 'px' | 'rem';
+export interface GuideLength {
+  readonly amount: number;
+  readonly unit: GuideLengthUnit;
+}
+
+/** What the menu holds for a margin, gutter or maximum width. */
+export type GuideSize =
+  | { readonly kind: 'length'; readonly length: GuideLength }
+  | { readonly kind: 'variable'; readonly name: string };
+
+/**
+ * The variables a Lumos project declares the layout with, measured by the
+ * frame under these names (electron/preload/frameGuide.ts keeps its own copy).
+ */
+export const GUIDE_PROJECT_VARIABLES = {
+  margin: '--site-margin',
+  gutter: '--site-gutter',
+  widthMax: '--max-width-main',
+} as const;
+
+/** A custom property name the menu accepts: two dashes, then a CSS identifier. */
+export const GUIDE_VARIABLE_PATTERN = /^--[A-Za-z0-9_-]+$/;
+
+/** A Lumos fluid range: its size at the narrow and the wide end, in px at a 16px root. */
+export interface GuideFluidRange {
+  readonly pxMin: number;
+  readonly pxMax: number;
+}
+
+/** Lumos's starting ranges, used when neither the project nor the menu sets a value. */
+export const GUIDE_FLUID_DEFAULTS = {
+  margin: { pxMin: 16, pxMax: 48 },
+  gutter: { pxMin: 16, pxMax: 32 },
+} as const satisfies Record<string, GuideFluidRange>;
+// The viewport widths a Lumos fluid value runs between, and the root size its
+// rem values are written for.
+const LUMOS_VIEWPORT_PX_MIN = 320;
+const LUMOS_VIEWPORT_PX_MAX = 1440;
+const LUMOS_ROOT_FONT_PX = 16;
+
+/** What the frame measured, in CSS pixels of the frame. Absent: not declared. */
+export interface GuideMetrics {
+  readonly viewportWidthPx: number;
+  readonly rootFontPx: number;
+  readonly marginPx: number | undefined;
+  readonly gutterPx: number | undefined;
+  readonly widthMaxPx: number | undefined;
+  readonly columns: { readonly count: number; readonly variable: GuideColumnVariable } | undefined;
+  /** The menu's own variables, by name; a name the page does not declare is absent. */
+  readonly variablesPx: Readonly<Record<string, number | undefined>>;
+  /** The same names read as column counts; absent unless a whole number. */
+  readonly variableCounts: Readonly<Record<string, number | undefined>>;
+}
+
+export interface GuideSettings {
+  readonly visible: boolean;
+  readonly columns: GuideColumnSetting;
+  /** The menu's list: sorted, each count once, within the pick range and the list bound. */
+  readonly columnChoices: readonly number[];
+  /** The project's count is read from this variable; absent, from the ones the guide knows. */
+  readonly columnVariable: string | undefined;
+  readonly color: string;
+  readonly opacity: number;
+  readonly numbers: boolean;
+  /** Absent: the fluid default. */
+  readonly margin: GuideSize | undefined;
+  /** Absent: the fluid default. */
+  readonly gutter: GuideSize | undefined;
+  /** Absent: the content box is never capped. */
+  readonly widthMax: GuideSize | undefined;
+}
+
+export const GUIDE_DEFAULTS: GuideSettings = {
+  visible: false,
+  columns: 'project',
+  columnChoices: GUIDE_COLUMN_CHOICES_DEFAULT,
+  columnVariable: undefined,
+  // A neutral grey, barely there.
+  color: 'rgb(146, 146, 146)',
+  opacity: 0.06,
+  numbers: true,
+  margin: undefined,
+  gutter: undefined,
+  widthMax: undefined,
+};
+
+/** Where a value came from: Lumos's variable, the menu's variable or length, or the default. */
+export type GuideSource = 'project' | 'variable' | 'fixed' | 'default';
+export interface GuideValue {
+  readonly px: number;
+  readonly source: GuideSource;
+}
+export type GuideColumnSource = 'project' | 'stacki';
+
+/** Every value the guide is drawn with, and where each one came from. */
+export interface ResolvedGuide {
+  readonly viewportWidthPx: number;
+  readonly rootFontPx: number;
+  readonly columnCount: number;
+  readonly columnSource: GuideColumnSource;
+  readonly margin: GuideValue;
+  readonly gutter: GuideValue;
+  /** Absent: the content box is never capped. */
+  readonly widthMax: GuideValue | undefined;
+}
+
+/** One column's horizontal extent, in CSS pixels of the frame. */
+export interface GuideColumn {
+  readonly xPx: number;
+  readonly widthPx: number;
+}
+
+export function resolveGuide(metrics: GuideMetrics, settings: GuideSettings): ResolvedGuide {
+  assert(metrics.viewportWidthPx >= 0, 'Guide: viewport width is nonnegative');
+  assert(metrics.rootFontPx > 0, 'Guide: root font size is positive');
+  return {
+    viewportWidthPx: metrics.viewportWidthPx,
+    rootFontPx: metrics.rootFontPx,
+    ...columnCountOf(metrics, settings),
+    margin: spacingValue(metrics.marginPx, settings.margin, metrics, GUIDE_FLUID_DEFAULTS.margin),
+    gutter: spacingValue(metrics.gutterPx, settings.gutter, metrics, GUIDE_FLUID_DEFAULTS.gutter),
+    widthMax: widthMaxValue(metrics, settings.widthMax),
+  };
+}
+
+/**
+ * The columns of the content box: as wide as the viewport less a margin on
+ * each side, capped at the maximum width and centred — Lumos's `.container`.
+ * Empty when the gutters leave no room for a column.
+ */
+export function guideColumns(guide: ResolvedGuide): readonly GuideColumn[] {
+  assert(Number.isSafeInteger(guide.columnCount), 'Guide: column count is an integer');
+  assert(guide.columnCount >= GUIDE_LIMITS.columnPickMin, 'Guide: column count within range');
+  assert(guide.columnCount <= GUIDE_LIMITS.columnPickMax, 'Guide: column count within range');
+  const available = Math.max(0, guide.viewportWidthPx - 2 * guide.margin.px);
+  const widthMax = guide.widthMax?.px ?? Number.POSITIVE_INFINITY;
+  const contentWidthPx = Math.min(available, widthMax);
+  const guttersPx = guide.gutter.px * (guide.columnCount - 1);
+  const columnWidthPx = (contentWidthPx - guttersPx) / guide.columnCount;
+  if (columnWidthPx > 0) {
+    const leftPx = (guide.viewportWidthPx - contentWidthPx) / 2;
+    const columns = Array.from({ length: guide.columnCount }, (_, index) => ({
+      xPx: leftPx + index * (columnWidthPx + guide.gutter.px),
+      widthPx: columnWidthPx,
+    }));
+    assert(columns.length === guide.columnCount, 'Guide: one box per column');
+    return columns;
+  }
+  return [];
+}
+
+export function lengthPx(length: GuideLength, rootFontPx: number): number {
+  assert(length.amount >= 0, 'Guide: length is nonnegative');
+  assert(rootFontPx > 0, 'Guide: root font size is positive');
+  return length.unit === 'px' ? length.amount : length.amount * rootFontPx;
+}
+
+const LENGTH_PATTERN = /^(\d+(?:\.\d+)?|\.\d+)\s*(px|rem)?$/i;
+
+/** A length typed into the menu: a number in px or rem; a bare number is px. */
+export function parseGuideLength(text: string): GuideLength | undefined {
+  const match = LENGTH_PATTERN.exec(text.trim());
+  if (match === null) {
+    return undefined;
+  }
+  const amount = Number.parseFloat(match[1] ?? '');
+  const unit = (match[2] ?? 'px').toLowerCase() === 'rem' ? 'rem' : 'px';
+  const maximum = unit === 'px' ? GUIDE_LIMITS.lengthPxMax : GUIDE_LIMITS.lengthRemMax;
+  if (Number.isFinite(amount)) {
+    return amount <= maximum ? { amount, unit } : undefined;
+  }
+  return undefined;
+}
+
+export function guideLengthText(length: GuideLength): string {
+  return `${roundTo(length.amount, 1_000)}${length.unit}`;
+}
+
+const VARIABLE_REFERENCE_PATTERN = /^var\(\s*(--[^\s()]+)\s*\)$/;
+
+/**
+ * A value typed into the menu: a length, or a variable of the project's own,
+ * written as `--name` or `var(--name)`. Undefined for anything else.
+ */
+export function parseGuideSize(text: string): GuideSize | undefined {
+  const trimmed = text.trim();
+  const reference = VARIABLE_REFERENCE_PATTERN.exec(trimmed)?.[1] ?? trimmed;
+  if (reference.startsWith('--')) {
+    const name = parseGuideVariableName(reference);
+    return name === undefined ? undefined : { kind: 'variable', name };
+  }
+  const length = parseGuideLength(trimmed);
+  return length === undefined ? undefined : { kind: 'length', length };
+}
+
+/** A custom property name, within the length bound, or undefined. */
+export function parseGuideVariableName(input: unknown): string | undefined {
+  if (typeof input !== 'string') {
+    return undefined;
+  }
+  if (input.length > GUIDE_LIMITS.variableCharsMax) {
+    return undefined;
+  }
+  return GUIDE_VARIABLE_PATTERN.test(input) ? input : undefined;
+}
+
+/** A menu value as the field shows it: the length as typed, a variable as `var()`. */
+export function guideSizeText(size: GuideSize): string {
+  switch (size.kind) {
+    case 'length':
+      return guideLengthText(size.length);
+    case 'variable':
+      return `var(${size.name})`;
+    default: {
+      const exhaustive: never = size;
+      return exhaustive;
+    }
+  }
+}
+
+/** The variables the frame has to measure for these settings, each once. */
+export function guideVariableNames(settings: GuideSettings): readonly string[] {
+  const names = new Set<string>();
+  for (const size of [settings.margin, settings.gutter, settings.widthMax]) {
+    if (size?.kind === 'variable') {
+      names.add(size.name);
+    }
+  }
+  if (settings.columnVariable !== undefined) {
+    names.add(settings.columnVariable);
+  }
+  assert(names.size <= GUIDE_LIMITS.variablesMax, 'Guide: one variable per value at most');
+  return [...names];
+}
+
+/**
+ * A Lumos fluid value at this viewport width: Lumos's own `clamp()`, growing
+ * linearly from its narrow-end size at 320px to its wide-end size at 1440px.
+ * Its rem terms follow the root font size; its vw term follows the viewport.
+ */
+export function fluidPx(range: GuideFluidRange, viewportWidthPx: number, rootFontPx: number) {
+  assert(range.pxMin <= range.pxMax, 'Guide: a fluid range grows');
+  assert(rootFontPx > 0, 'Guide: root font size is positive');
+  const viewportSpanPx = LUMOS_VIEWPORT_PX_MAX - LUMOS_VIEWPORT_PX_MIN;
+  const slope = (range.pxMax - range.pxMin) / viewportSpanPx;
+  const remScale = rootFontPx / LUMOS_ROOT_FONT_PX;
+  const preferredPx = (range.pxMin - slope * LUMOS_VIEWPORT_PX_MIN) * remScale;
+  const valuePx = preferredPx + slope * viewportWidthPx;
+  return Math.min(range.pxMax * remScale, Math.max(range.pxMin * remScale, valuePx));
+}
+
+/** A fluid range as the field's placeholder reads it. */
+export function fluidText(range: GuideFluidRange): string {
+  return `Fluid ${range.pxMin}–${range.pxMax}px`;
+}
+
+/** An opacity on the menu's own scale: clamped to its range, on its step. */
+export function clampGuideOpacity(value: number): number {
+  const stepped = Math.round(value / GUIDE_LIMITS.opacityStep) * GUIDE_LIMITS.opacityStep;
+  const clamped = Math.min(GUIDE_LIMITS.opacityMax, Math.max(GUIDE_LIMITS.opacityMin, stepped));
+  return roundTo(clamped, 100);
+}
+
+/**
+ * The project's column count: from the menu's variable when the page declares
+ * it as a count, else from the variables the guide knows. Either one counts
+ * only within the menu's own range. Undefined for none.
+ */
+export function guideProjectCount(
+  metrics: GuideMetrics,
+  settings: Pick<GuideSettings, 'columnVariable'>,
+): number | undefined {
+  if (settings.columnVariable !== undefined) {
+    const declared = metrics.variableCounts[settings.columnVariable];
+    if (isGuideColumnPick(declared)) {
+      return declared;
+    }
+  }
+  const detected = metrics.columns?.count;
+  return isGuideColumnPick(detected) ? detected : undefined;
+}
+
+/** One entry of the menu's column list; `project` and `default` are the count it defers to. */
+export interface GuideColumnOption {
+  readonly count: number;
+  readonly source: 'project' | 'default' | 'list';
+}
+
+/** A count the menu takes: a whole number within its range. */
+export function isGuideColumnPick(value: unknown): value is number {
+  if (typeof value !== 'number') {
+    return false;
+  }
+  if (!Number.isSafeInteger(value)) {
+    return false;
+  }
+  if (value < GUIDE_LIMITS.columnPickMin) {
+    return false;
+  }
+  return value <= GUIDE_LIMITS.columnPickMax;
+}
+
+// The digits of a count up to the pick maximum, and nothing else.
+const COUNT_PATTERN = /^\d{1,2}$/;
+
+/** A count typed into the menu: a whole number within the pick range, else undefined. */
+export function parseGuideColumnCount(text: string): number | undefined {
+  assert(String(GUIDE_LIMITS.columnPickMax).length <= 2, 'Guide: the pattern holds every pick');
+  if (!COUNT_PATTERN.test(text)) {
+    return undefined;
+  }
+  const count = Number.parseInt(text, 10);
+  return isGuideColumnPick(count) ? count : undefined;
+}
+
+/**
+ * A stored column list, or undefined when it is not one: each count a pick,
+ * once, the default count among them, within the list bound. Sorted.
+ */
+export function parseGuideColumnChoices(input: unknown): readonly number[] | undefined {
+  if (!Array.isArray(input)) {
+    return undefined;
+  }
+  const entries: readonly unknown[] = input;
+  if (entries.length > GUIDE_LIMITS.columnChoicesMax) {
+    return undefined;
+  }
+  const counts = new Set<number>();
+  for (const entry of entries) {
+    if (!isGuideColumnPick(entry)) {
+      return undefined;
+    }
+    counts.add(entry);
+  }
+  if (counts.size < entries.length) {
+    return undefined;
+  }
+  return counts.has(GUIDE_COLUMN_COUNT_DEFAULT) ? sortedCounts(counts) : undefined;
+}
+
+/**
+ * The menu's entries in order: the list, with the count the setting defers to
+ * (the project's, else the default) among them once. A project count outside
+ * the list is still offered, so it can make the list one longer.
+ */
+export function guideColumnOptions(
+  choices: readonly number[],
+  projectCount: number | undefined,
+): readonly GuideColumnOption[] {
+  assert(choices.includes(GUIDE_COLUMN_COUNT_DEFAULT), 'Guide: the list keeps the default');
+  assert(choices.length <= GUIDE_LIMITS.columnChoicesMax, 'Guide: the list within its bound');
+  const deferred = projectCount ?? GUIDE_COLUMN_COUNT_DEFAULT;
+  const counts = sortedCounts(new Set([...choices, deferred]));
+  return counts.map((count) => ({ count, source: columnOptionSource(count, projectCount) }));
+}
+
+/** The list with `count` added, or unchanged when it is there already or the menu is full. */
+export function addGuideColumnChoice(
+  choices: readonly number[],
+  count: number,
+  projectCount: number | undefined,
+): readonly number[] {
+  assert(isGuideColumnPick(count), 'Guide: an added count is a pick');
+  if (choices.includes(count)) {
+    return choices;
+  }
+  const next = sortedCounts(new Set([...choices, count]));
+  if (next.length > GUIDE_LIMITS.columnChoicesMax) {
+    return choices;
+  }
+  const full = guideColumnOptions(next, projectCount).length > GUIDE_LIMITS.columnChoicesMax;
+  return full ? choices : next;
+}
+
+/** The settings without `count` in the list; a guide drawn with it goes back to the project's. */
+export function removeGuideColumnChoice(settings: GuideSettings, count: number): GuideSettings {
+  assert(count !== GUIDE_COLUMN_COUNT_DEFAULT, 'Guide: the default count stays in the list');
+  assert(settings.columnChoices.includes(count), 'Guide: a removed count is in the list');
+  const columnChoices = settings.columnChoices.filter((choice) => choice !== count);
+  const columns = settings.columns === count ? 'project' : settings.columns;
+  return { ...settings, columns, columnChoices };
+}
+
+/** The settings with the default list back; a pick it lacks goes back to the project's. */
+export function resetGuideColumnChoices(settings: GuideSettings): GuideSettings {
+  const columnChoices = GUIDE_COLUMN_CHOICES_DEFAULT;
+  assert(columnChoices.includes(GUIDE_COLUMN_COUNT_DEFAULT), 'Guide: the default list keeps it');
+  if (settings.columns === 'project') {
+    return { ...settings, columnChoices };
+  }
+  const columns = columnChoices.includes(settings.columns) ? settings.columns : 'project';
+  return { ...settings, columns, columnChoices };
+}
+
+function columnOptionSource(
+  count: number,
+  projectCount: number | undefined,
+): GuideColumnOption['source'] {
+  if (projectCount === undefined) {
+    return count === GUIDE_COLUMN_COUNT_DEFAULT ? 'default' : 'list';
+  }
+  return count === projectCount ? 'project' : 'list';
+}
+
+function sortedCounts(counts: ReadonlySet<number>): readonly number[] {
+  return [...counts].sort((left, right) => left - right);
+}
+
+// A count picked in Stacki; else the project's, from the menu's variable when
+// the page declares it as a count, then from the variables the guide knows;
+// else the default.
+function columnCountOf(
+  metrics: GuideMetrics,
+  settings: GuideSettings,
+): Pick<ResolvedGuide, 'columnCount' | 'columnSource'> {
+  if (settings.columns !== 'project') {
+    return { columnCount: settings.columns, columnSource: 'stacki' };
+  }
+  const projectCount = guideProjectCount(metrics, settings);
+  if (projectCount === undefined) {
+    return { columnCount: GUIDE_COLUMN_COUNT_DEFAULT, columnSource: 'stacki' };
+  }
+  return { columnCount: projectCount, columnSource: 'project' };
+}
+
+// A margin or gutter: the menu's, else the project's own, else Lumos's fluid
+// starting range at this width. A menu variable the page does not declare
+// falls through to the next source.
+function spacingValue(
+  projectPx: number | undefined,
+  setting: GuideSize | undefined,
+  metrics: GuideMetrics,
+  fluid: GuideFluidRange,
+): GuideValue {
+  const chosen = settingValue(setting, metrics);
+  if (chosen !== undefined) {
+    return chosen;
+  }
+  if (projectPx !== undefined) {
+    return { px: projectPx, source: 'project' };
+  }
+  const px = fluidPx(fluid, metrics.viewportWidthPx, metrics.rootFontPx);
+  return { px, source: 'default' };
+}
+
+// The maximum width in the same order as the margin, with no default: the
+// content box is then never capped. A width that resolves to nothing (`none`,
+// a percentage of an empty probe) caps nothing, so it is skipped too.
+function widthMaxValue(
+  metrics: GuideMetrics,
+  setting: GuideSize | undefined,
+): GuideValue | undefined {
+  const chosen = settingValue(setting, metrics);
+  if (chosen !== undefined) {
+    if (chosen.px > 0) {
+      return chosen;
+    }
+  }
+  if (metrics.widthMaxPx !== undefined) {
+    if (metrics.widthMaxPx > 0) {
+      return { px: metrics.widthMaxPx, source: 'project' };
+    }
+  }
+  return undefined;
+}
+
+// What the menu sets, in pixels: a length as written, a variable as the page
+// resolves it. Undefined when nothing is set or the variable is not declared.
+function settingValue(
+  setting: GuideSize | undefined,
+  metrics: GuideMetrics,
+): GuideValue | undefined {
+  if (setting === undefined) {
+    return undefined;
+  }
+  switch (setting.kind) {
+    case 'length':
+      return { px: lengthPx(setting.length, metrics.rootFontPx), source: 'fixed' };
+    case 'variable': {
+      const px = metrics.variablesPx[setting.name];
+      return px === undefined ? undefined : { px, source: 'variable' };
+    }
+    default: {
+      const exhaustive: never = setting;
+      return exhaustive;
+    }
+  }
+}
+
+function roundTo(value: number, scale: number): number {
+  return Math.round(value * scale) / scale;
+}
diff --git a/src/features/preview/guideSettings.ts b/src/features/preview/guideSettings.ts
new file mode 100644
index 00000000..92033e9c
--- /dev/null
+++ b/src/features/preview/guideSettings.ts
@@ -0,0 +1,277 @@
+// The column guide's settings, kept per project in this app's local storage —
+// never in the project, which the guide only reads. A project opened again
+// shows the guide as it was left: on or off, its colour, its count and list.
+//
+// Stored records outlive app versions, so what storage holds is parsed like
+// any other input. Each field is parsed on its own: one that does not parse
+// takes its default, and the others are kept.
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { assert } from '../../../shared/core/assert';
+import { BOUNDARY_LIMITS } from '../../../shared/core/boundary';
+import {
+  GUIDE_DEFAULTS,
+  GUIDE_LIMITS,
+  clampGuideOpacity,
+  guideVariableNames,
+  isGuideColumnPick,
+  parseGuideColumnChoices,
+  parseGuideLength,
+  parseGuideVariableName,
+  resolveGuide,
+  type GuideMetrics,
+  type GuideSettings,
+  type GuideSize,
+  type ResolvedGuide,
+} from './guideModel';
+import type { GuideMenuProps } from './GuideMenu';
+
+const GUIDE_STORAGE_PREFIX = 'stacki.columnGuide:';
+// A stored record is a handful of short fields; anything longer is not one.
+const GUIDE_STORED_CHARS_MAX = 2_048;
+
+export type GuideUpdate = (update: (settings: GuideSettings) => GuideSettings) => void;
+
+/** How a host reaches its preview frame: the desktop canvas and Studio each link their own way. */
+export interface GuideFrameLink {
+  readonly post: (message: unknown) => void;
+  /** Calls the listener each time a frame loads; returns the unsubscribe. */
+  readonly subscribeLoad: (listener: () => void) => () => void;
+}
+
+/** What the canvas draws: present while the guide is on and the frame has measured. */
+export interface ShownGuide {
+  readonly guide: ResolvedGuide;
+  readonly settings: GuideSettings;
+}
+
+/**
+ * The column guide of one canvas, as the desktop preview and Studio both use
+ * it: the settings saved under `projectKey`, the variables the frame is told
+ * to measure, and what the toolbar's menu and the overlay are drawn from.
+ */
+export function useColumnGuide(options: {
+  readonly projectKey: string | undefined;
+  readonly metrics: GuideMetrics | undefined;
+  readonly available: boolean;
+  readonly frame: GuideFrameLink;
+}): { readonly menu: GuideMenuProps; readonly shown: ShownGuide | undefined } {
+  const [settings, update] = useGuideSettings(options.projectKey);
+  useGuideVariables(guideVariableNames(settings), options.frame);
+  const metrics = options.metrics;
+  const guide = metrics === undefined ? undefined : resolveGuide(metrics, settings);
+  const menu = { settings, update, metrics, guide, available: options.available };
+  if (guide === undefined) {
+    return { menu, shown: undefined };
+  }
+  return { menu, shown: settings.visible ? { guide, settings } : undefined };
+}
+
+/** The settings for the open project, and the one way to change them. */
+export function useGuideSettings(
+  projectKey: string | undefined,
+): readonly [GuideSettings, GuideUpdate] {
+  const [settings, setSettings] = useState<GuideSettings>(() => loadGuideSettings(projectKey));
+  useEffect(() => setSettings(loadGuideSettings(projectKey)), [projectKey]);
+  const update = useCallback<GuideUpdate>(
+    (change) =>
+      setSettings((previous) => {
+        const next = change(previous);
+        saveGuideSettings(projectKey, next);
+        return next;
+      }),
+    [projectKey],
+  );
+  useGuideShortcut(update);
+  return [settings, update] as const;
+}
+
+// The frame measures the menu's variables once told their names: whenever they
+// change, and on every load, since a new page starts from none. The names are
+// compared as one key, and the link is read through a ref, so a host whose
+// functions change on every render sends nothing extra.
+function useGuideVariables(names: readonly string[], frame: GuideFrameLink): void {
+  const key = names.join('\n');
+  const link = useRef(frame);
+  useEffect(() => {
+    link.current = frame;
+  });
+  useEffect(() => {
+    const send = (): void =>
+      link.current.post({ type: 'avb:guide-variables', names: key === '' ? [] : key.split('\n') });
+    send();
+    return link.current.subscribeLoad(send);
+  }, [key]);
+}
+
+/** A stored record as settings; every field it lacks or garbles is the default. */
+export function parseGuideSettings(input: unknown): GuideSettings {
+  if (typeof input !== 'object' || input === null) {
+    return GUIDE_DEFAULTS;
+  }
+  const value = new Map<string, unknown>(Object.entries(input));
+  const visible = value.get('visible');
+  const numbers = value.get('numbers');
+  const columnChoices = parseGuideColumnChoices(value.get('columnChoices'));
+  return {
+    visible: typeof visible === 'boolean' ? visible : GUIDE_DEFAULTS.visible,
+    ...columnsOr(value.get('columns'), columnChoices ?? GUIDE_DEFAULTS.columnChoices),
+    columnVariable: parseGuideVariableName(value.get('columnVariable')),
+    color: colorOr(value.get('color')),
+    opacity: opacityOr(value.get('opacity')),
+    numbers: typeof numbers === 'boolean' ? numbers : GUIDE_DEFAULTS.numbers,
+    margin: sizeOr(value.get('margin')),
+    gutter: sizeOr(value.get('gutter')),
+    widthMax: sizeOr(value.get('widthMax')),
+  };
+}
+
+/** A colour the guide can paint: a literal CSS colour, within the length bound. */
+export function parseGuideColor(input: unknown): string | undefined {
+  if (typeof input !== 'string') {
+    return undefined;
+  }
+  const value = input.trim();
+  if (value.length === 0) {
+    return undefined;
+  }
+  if (value.length > GUIDE_LIMITS.colorCharsMax) {
+    return undefined;
+  }
+  // A variable means nothing in the app's document, where the guide is drawn.
+  if (value.includes('var(')) {
+    return undefined;
+  }
+  return CSS.supports('color', value) ? value : undefined;
+}
+
+// ⇧G shows or hides the guide, outside fields. The canvas replays it as the
+// key "G" with no modifier flags (electron/preload/frameDesign.ts), so the
+// capital letter is what says Shift.
+function useGuideShortcut(update: GuideUpdate): void {
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.metaKey || event.ctrlKey || event.altKey) {
+        return;
+      }
+      if (event.key !== 'G') {
+        return;
+      }
+      const target = event.target;
+      if (target instanceof HTMLElement) {
+        if (target.closest('input, textarea, select, [contenteditable="true"]')) {
+          return;
+        }
+      }
+      event.preventDefault();
+      update((settings) => ({ ...settings, visible: !settings.visible }));
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [update]);
+}
+
+function storageKey(projectKey: string): string {
+  assert(projectKey.length > 0, 'Guide settings: project key is non-empty');
+  assert(projectKey.length <= BOUNDARY_LIMITS.pathLengthMax, 'Guide settings: key within limit');
+  return GUIDE_STORAGE_PREFIX + projectKey;
+}
+
+function loadGuideSettings(projectKey: string | undefined): GuideSettings {
+  if (projectKey === undefined) {
+    return GUIDE_DEFAULTS;
+  }
+  const key = storageKey(projectKey);
+  try {
+    const raw = localStorage.getItem(key);
+    if (raw === null) {
+      return GUIDE_DEFAULTS;
+    }
+    if (raw.length > GUIDE_STORED_CHARS_MAX) {
+      return GUIDE_DEFAULTS;
+    }
+    const stored: unknown = JSON.parse(raw);
+    return parseGuideSettings(stored);
+  } catch {
+    // Unreadable storage or a corrupt record: the defaults, never a failed load.
+    return GUIDE_DEFAULTS;
+  }
+}
+
+function saveGuideSettings(projectKey: string | undefined, settings: GuideSettings): void {
+  if (projectKey === undefined) {
+    return;
+  }
+  const key = storageKey(projectKey);
+  const raw = JSON.stringify(settings);
+  assert(raw.length <= GUIDE_STORED_CHARS_MAX, 'Guide settings: record within limit');
+  try {
+    localStorage.setItem(key, raw);
+  } catch {
+    // Storage can be unavailable; the live setting still applies.
+  }
+}
+
+// A picked count stands only while the list still offers it; otherwise the
+// guide defers to the project's count.
+function columnsOr(
+  input: unknown,
+  columnChoices: readonly number[],
+): Pick<GuideSettings, 'columns' | 'columnChoices'> {
+  if (isGuideColumnPick(input)) {
+    if (columnChoices.includes(input)) {
+      return { columns: input, columnChoices };
+    }
+  }
+  return { columns: GUIDE_DEFAULTS.columns, columnChoices };
+}
+
+function colorOr(input: unknown): string {
+  return parseGuideColor(input) ?? GUIDE_DEFAULTS.color;
+}
+
+function opacityOr(input: unknown): number {
+  if (typeof input === 'number') {
+    return Number.isFinite(input) ? clampGuideOpacity(input) : GUIDE_DEFAULTS.opacity;
+  }
+  return GUIDE_DEFAULTS.opacity;
+}
+
+// A menu value is stored as the record it is, and read back through the
+// parsers a typed one goes through, so both answer to the same bounds. Absent
+// or unreadable, it is unset: the default applies.
+function sizeOr(input: unknown): GuideSize | undefined {
+  if (typeof input !== 'object' || input === null) {
+    return undefined;
+  }
+  const value = new Map<string, unknown>(Object.entries(input));
+  switch (value.get('kind')) {
+    case 'length':
+      return storedLength(value.get('length'));
+    case 'variable': {
+      const name = parseGuideVariableName(value.get('name'));
+      return name === undefined ? undefined : { kind: 'variable', name };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function storedLength(input: unknown): GuideSize | undefined {
+  if (typeof input !== 'object' || input === null) {
+    return undefined;
+  }
+  const value = new Map<string, unknown>(Object.entries(input));
+  const amount = value.get('amount');
+  const unit = value.get('unit');
+  if (typeof amount !== 'number') {
+    return undefined;
+  }
+  if (unit !== 'px') {
+    if (unit !== 'rem') {
+      return undefined;
+    }
+  }
+  const length = parseGuideLength(`${amount}${unit}`);
+  return length === undefined ? undefined : { kind: 'length', length };
+}
diff --git a/src/features/preview/previewMessages.ts b/src/features/preview/previewMessages.ts
index 6efc73cf..0293f997 100644
--- a/src/features/preview/previewMessages.ts
+++ b/src/features/preview/previewMessages.ts
@@ -12,6 +12,13 @@ import {
 } from '../../../shared/core/boundary';
 import type { Digest } from '../../../shared/core/brand';
 import { parsePreviewRender, type PreviewRender } from '../../../shared/page/previewToken';
+import {
+  GUIDE_COLUMN_VARIABLES,
+  GUIDE_LIMITS,
+  parseGuideVariableName,
+  type GuideColumnVariable,
+  type GuideMetrics,
+} from './guideModel';
 
 export type PreviewMessage =
   | {
@@ -35,6 +42,8 @@ export type PreviewMessage =
   | ({ readonly kind: 'click-node'; readonly outside: boolean } & LocatedEvent)
   | ({ readonly kind: 'open-node' } & LocatedEvent)
   | { readonly kind: 'canvas-ready' }
+  /** What the column guide is drawn from (electron/preload/frameGuide.ts). */
+  | { readonly kind: 'guide'; readonly metrics: GuideMetrics }
   /** The rendering the canvas shows: its manifest and token (plan §9, step 7). */
   | { readonly kind: 'render'; readonly render: PreviewRender }
   /** The canvas reloaded instead of patching, and why (step 7). */
@@ -164,6 +173,8 @@ function parseKnownMessage(value: Readonly<Record<string, unknown>>): PreviewMes
       return { kind: 'open-node', ...parseLocatedMessage(value) };
     case 'avb:canvas-ready':
       return { kind: 'canvas-ready' };
+    case 'avb:guide':
+      return { kind: 'guide', metrics: parseGuideMetrics(value) };
     case 'avb:render':
       return { kind: 'render', render: parsePreviewRender(value) };
     case 'avb:preview-reload':
@@ -184,6 +195,81 @@ function parseRects(value: Readonly<Record<string, unknown>>): PreviewMessage {
   };
 }
 
+function parseGuideMetrics(value: Readonly<Record<string, unknown>>): GuideMetrics {
+  const rootFontPx = guideLength(value['rootFontSize']);
+  if (rootFontPx === 0) {
+    throw new Error('Preview guide: expected a positive root font size');
+  }
+  if (rootFontPx > GUIDE_LIMITS.rootFontPxMax) {
+    throw new Error('Preview guide: root font size exceeds limit');
+  }
+  return {
+    viewportWidthPx: guideLength(value['viewportWidth']),
+    rootFontPx,
+    marginPx: optional(guideLength)(value['margin']),
+    gutterPx: optional(guideLength)(value['gutter']),
+    widthMaxPx: optional(guideLength)(value['widthMax']),
+    columns: parseGuideColumns(value['columnCount'], value['columnVariable']),
+    variablesPx: Object.fromEntries(
+      guideVariableEntries(value['variables']).map(([name, px]) => [
+        name,
+        optional(guideLength)(px),
+      ]),
+    ),
+    variableCounts: Object.fromEntries(
+      guideVariableEntries(value['counts']).map(([name, input]) => [name, declaredCount(input)]),
+    ),
+  };
+}
+
+// The menu's own variables, as measured: at most one per value, each a custom
+// property name.
+function guideVariableEntries(input: unknown): ReadonlyArray<readonly [string, unknown]> {
+  const entries = Object.entries(record(input));
+  if (entries.length > GUIDE_LIMITS.variablesMax) {
+    throw new Error('Preview guide: too many variables');
+  }
+  for (const [name] of entries) {
+    if (parseGuideVariableName(name) === undefined) {
+      throw new Error('Preview guide: not a variable name');
+    }
+  }
+  return entries;
+}
+
+function guideLength(input: unknown): number {
+  const value = nonnegativeFinite(input);
+  if (value > GUIDE_LIMITS.lengthPxMax) {
+    throw new Error('Preview guide: length exceeds limit');
+  }
+  return value;
+}
+
+// The count the page found and the variable it came from; undefined when the
+// page declares none.
+function parseGuideColumns(countInput: unknown, variableInput: unknown): GuideMetrics['columns'] {
+  if (countInput === undefined) {
+    return undefined;
+  }
+  const variable = parseGuideColumnVariable(variableInput);
+  const columnCount = declaredCount(countInput);
+  return columnCount === undefined ? undefined : { count: columnCount, variable };
+}
+
+// A whole number as the page read it. Whether the guide can use it is the
+// model's to decide (guideProjectCount), so the menu can say why it does not.
+function declaredCount(input: unknown): number | undefined {
+  return optional(count)(input);
+}
+
+function parseGuideColumnVariable(input: unknown): GuideColumnVariable {
+  const variable = GUIDE_COLUMN_VARIABLES.find((name) => name === input);
+  if (variable === undefined) {
+    throw new Error('Preview guide: unknown column variable');
+  }
+  return variable;
+}
+
 function parseReloadReason(input: unknown): PreviewReloadReason {
   const found = PREVIEW_RELOAD_REASONS.find((reason) => reason === input);
   if (found === undefined) {
diff --git a/src/features/preview/previewRuntime.ts b/src/features/preview/previewRuntime.ts
index dd046fb8..7cef5a1a 100644
--- a/src/features/preview/previewRuntime.ts
+++ b/src/features/preview/previewRuntime.ts
@@ -3,6 +3,7 @@ import type React from 'react';
 import type { OverlayInfo, RectMap, SpacingMap } from './PreviewOverlays';
 import type { PreviewDevice } from './PreviewToolbar';
 import type { PreviewMessage, PreviewReloadReason } from './previewMessages';
+import type { GuideMetrics } from './guideModel';
 import { parsePreviewMessage } from './previewMessages';
 import { outlineBoxPath, sameCopy } from './outlineBoxes';
 import { setModifiers } from '../../editor/heldModifiers';
@@ -57,8 +58,14 @@ export interface PreviewRuntime {
   readonly selOcc: number | undefined;
   readonly hoverPath: string | undefined;
   readonly hoverOcc: number | undefined;
+  /** What the column guide is drawn from; undefined until the frame reports. */
+  readonly guide: GuideMetrics | undefined;
   readonly registerFrame: () => void;
   readonly sendTrack: () => void;
+  /** Sends a message to the current frame. */
+  readonly post: (message: unknown) => void;
+  /** Calls the listener each time a frame registers; returns the unsubscribe. */
+  readonly subscribeLoad: (listener: () => void) => () => void;
 }
 
 export function usePreviewRuntime(
@@ -71,6 +78,7 @@ export function usePreviewRuntime(
   const [canvasHover, setCanvasHover] = useState<string | undefined>(undefined);
   const [selectedOccurrence, setSelectedOccurrence] = useState<number | undefined>(undefined);
   const [hoverOcc, setHoverOcc] = useState(0);
+  const [guide, setGuide] = useState<GuideMetrics | undefined>(undefined);
   const hoverPath = props.navHoverPath ?? canvasHover;
   const selectedBoxPath = props.selPath
     ? outlineBoxPath(props.selPath, props.overlayInfo?.(props.selPath)?.nodeKind)
@@ -86,6 +94,7 @@ export function usePreviewRuntime(
       setCanvasHover,
       setSelectedOccurrence,
       setHoverOcc,
+      setGuide,
     }),
     [],
   );
@@ -97,25 +106,24 @@ export function usePreviewRuntime(
     () => trackedPaths(props.selPath, hoverPath, props.focusPath, selectedBoxPath, hoverBoxPath),
     [props.focusPath, hoverPath, hoverBoxPath, props.selPath, selectedBoxPath],
   );
+  const link = useFrameLink(iframeRef);
   const registerFrame = useCallback((): void => {
     const frame = iframeRef.current?.contentWindow;
     setCanvasFrame(frame ?? undefined);
     // The frame may have announced its rendering before this listener mounted.
     // The load handler repeats this handshake after the preload is ready.
     frame?.postMessage({ type: 'avb:request-render' }, '*');
-  }, []);
+    link.notify();
+  }, [link]);
   const sendTrack = useCallback((): void => {
-    iframeRef.current?.contentWindow?.postMessage(
-      {
-        type: 'avb:track',
-        paths: trackPaths,
-        scope: props.pathScope ?? '',
-        focus: props.focusPath ?? '',
-        focusOcc: props.focusOcc ?? 0,
-      },
-      '*',
-    );
-  }, [props.focusOcc, props.focusPath, props.pathScope, trackPaths]);
+    link.post({
+      type: 'avb:track',
+      paths: trackPaths,
+      scope: props.pathScope ?? '',
+      focus: props.focusPath ?? '',
+      focusOcc: props.focusOcc ?? 0,
+    });
+  }, [link, props.focusOcc, props.focusPath, props.pathScope, trackPaths]);
   useFrameRegistration(props, url, registerFrame, sendTrack);
   useSelectionScroll(props, iframeRef, refs);
   useResetOnReload(props, url, refs, setters);
@@ -126,8 +134,11 @@ export function usePreviewRuntime(
     selOcc: selectedOccurrence,
     hoverPath,
     hoverOcc: props.navHoverPath ? 0 : hoverOcc,
+    guide,
     registerFrame,
     sendTrack,
+    post: link.post,
+    subscribeLoad: link.subscribe,
   };
 }
 
@@ -220,6 +231,36 @@ interface RuntimeSetters {
   readonly setCanvasHover: React.Dispatch<React.SetStateAction<string | undefined>>;
   readonly setSelectedOccurrence: React.Dispatch<React.SetStateAction<number | undefined>>;
   readonly setHoverOcc: React.Dispatch<React.SetStateAction<number>>;
+  readonly setGuide: React.Dispatch<React.SetStateAction<GuideMetrics | undefined>>;
+}
+
+// A plain link to the current frame for the features built on the canvas:
+// sending to it, and hearing each time a frame registers (a reloaded page
+// starts from nothing, so what they told the last one has to be said again).
+// The listeners live in a ref, so subscribing never re-renders the canvas.
+function useFrameLink(iframeRef: React.RefObject<HTMLIFrameElement>): {
+  readonly post: (message: unknown) => void;
+  readonly notify: () => void;
+  readonly subscribe: (listener: () => void) => () => void;
+} {
+  const listeners = useRef(new Set<() => void>());
+  return useMemo(
+    () => ({
+      post: (message: unknown) => iframeRef.current?.contentWindow?.postMessage(message, '*'),
+      notify: () => {
+        for (const listener of listeners.current) {
+          listener();
+        }
+      },
+      subscribe: (listener: () => void) => {
+        listeners.current.add(listener);
+        return () => {
+          listeners.current.delete(listener);
+        };
+      },
+    }),
+    [iframeRef],
+  );
 }
 
 function useMessageListener(
@@ -290,6 +331,9 @@ function applyMessage(message: PreviewMessage, refs: RuntimeRefs, setters: Runti
     case 'canvas-ready':
       noteCanvasReady();
       break;
+    case 'guide':
+      setters.setGuide(message.metrics);
+      break;
     case 'query-result':
       receiveCanvasReply(message.input);
       break;
diff --git a/src/features/style/LayerPopover.tsx b/src/features/style/LayerPopover.tsx
index 95ea1189..148945af 100644
--- a/src/features/style/LayerPopover.tsx
+++ b/src/features/style/LayerPopover.tsx
@@ -16,11 +16,15 @@ export default function LayerPopover({
   anchorEl: anchorElement,
   onClose,
   ariaLabel,
+  span: placedSpan,
   children,
 }: {
   anchorEl: HTMLElement;
   onClose: () => void;
   ariaLabel?: string;
+  /** Where it sits across, for an anchor outside the style panel (the preview
+   *  toolbar): there is no panel to span, so the caller places it. */
+  span?: { readonly left: number; readonly width: number };
   children: ReactNode;
 }) {
   const ref = useRef<HTMLDivElement>(null);
@@ -37,7 +41,7 @@ export default function LayerPopover({
   const scrolls = usePopoverOverflow(boxRef);
   // Read once, at mount, so the popover has its real width for the very first
   // layout — the flip decision below measures a height that depends on it.
-  const [span] = useState(() => panelSpan(anchorElement));
+  const [span] = useState(() => placedSpan ?? panelSpan(anchorElement));
   const top = usePopoverTop(ref, anchorElement);
   usePopoverDismiss(ref, anchorElement, onClose);
   return createPortal(
diff --git a/src/ui/Icons.tsx b/src/ui/Icons.tsx
index df765a3b..5c126ba5 100644
--- a/src/ui/Icons.tsx
+++ b/src/ui/Icons.tsx
@@ -48,6 +48,15 @@ export const ComponentIcon = (props: IconProps) => (
   </I>
 );
 
+// Columns between two margins: the preview's column guide.
+export const GuideIcon = (props: IconProps) => (
+  <I {...props}>
+    <path d="M2.5 2.5v11M13.5 2.5v11" />
+    <rect x="4.75" y="2.5" width="2.5" height="11" rx="0.5" />
+    <rect x="8.75" y="2.5" width="2.5" height="11" rx="0.5" />
+  </I>
+);
+
 export const LayoutIcon = (props: IconProps) => (
   <I {...props}>
     <rect x="2" y="2.5" width="12" height="11" rx="1.5" />
diff --git a/studio/scripts/shared-source.json b/studio/scripts/shared-source.json
index 3a74b02a..5c4ee960 100644
--- a/studio/scripts/shared-source.json
+++ b/studio/scripts/shared-source.json
@@ -42,6 +42,7 @@
     "electron/parse/astroTemplate.ts",
     "electron/preload/frameAuthoredStyles.ts",
     "electron/preload/frameBasics.ts",
+    "electron/preload/frameGuide.ts",
     "electron/preload/frameMeasure.ts",
     "electron/preload/frameRegions.ts",
     "electron/preload/frameStyleSources.ts",
@@ -203,9 +204,14 @@
     "src/features/palette/insertRank.ts",
     "src/features/palette/paletteModel.ts",
     "src/features/preview/CanvasView.tsx",
+    "src/features/preview/GuideMenu.tsx",
+    "src/features/preview/GuideOverlay.tsx",
     "src/features/preview/PreviewOverlays.tsx",
     "src/features/preview/PreviewSizeControls.tsx",
     "src/features/preview/PreviewToolbar.tsx",
+    "src/features/preview/guide.css",
+    "src/features/preview/guideModel.ts",
+    "src/features/preview/guideSettings.ts",
     "src/features/preview/outlineBoxes.ts",
     "src/features/preview/previewMessages.ts",
     "src/features/preview/previewViewport.css",
diff --git a/studio/src/app/Editor.tsx b/studio/src/app/Editor.tsx
index 234a686f..09f8f1ea 100644
--- a/studio/src/app/Editor.tsx
+++ b/studio/src/app/Editor.tsx
@@ -132,6 +132,7 @@ function EditorContent({
         onDevice={setDevice}
         dimensions={props.view.dimensions}
         file={props.file}
+        projectName={props.project.name}
         showSettings={() => {
           setMobileSettings(!mobileSettings);
           setPanel(undefined);
diff --git a/studio/src/features/preview/PreviewCanvas.tsx b/studio/src/features/preview/PreviewCanvas.tsx
index 4a9388d7..9132c912 100644
--- a/studio/src/features/preview/PreviewCanvas.tsx
+++ b/studio/src/features/preview/PreviewCanvas.tsx
@@ -6,6 +6,11 @@ import type { Peer } from '../collaboration/presence';
 import { spacingHover } from './spacingHover';
 import { useLiveValue } from '../../../vendor/stacki/src/ui/liveValue';
 import { PreviewOverlays } from '../../../vendor/stacki/src/features/preview/PreviewOverlays';
+import { GuideOverlay } from '../../../vendor/stacki/src/features/preview/GuideOverlay';
+import {
+  useColumnGuide,
+  type ShownGuide,
+} from '../../../vendor/stacki/src/features/preview/guideSettings';
 import { outlineInfo } from './outlineInfo';
 import type { CSSProperties } from 'react';
 import {
@@ -23,6 +28,8 @@ import type { usePreview } from './usePreview';
 interface Props {
   readonly dimensions: ReturnType<typeof usePreviewDimensions>;
   readonly file: string;
+  /** The project's folder name: with the site's address, the column guide's settings key. */
+  readonly projectName: string;
   readonly collaborators: readonly Peer[];
   readonly collection: boolean;
   readonly document: SharedDocument | undefined;
@@ -38,6 +45,14 @@ interface Props {
 export function PreviewCanvas(props: Props) {
   const sizing = usePreviewSizing(props.device, props.dimensions, props.onDevice);
   useCursorScale(props.preview, sizing.viewport.scale);
+  // The browser keeps storage per site address; the folder name keeps two
+  // projects served from the same local address apart.
+  const columnGuide = useColumnGuide({
+    projectKey: `${location.origin} ${props.projectName}`,
+    metrics: props.preview.guide,
+    available: props.device !== 'canvas' && !props.collection,
+    frame: { post: props.preview.send, subscribeLoad: props.preview.subscribeLoad },
+  });
   return (
     <main className="studio-center">
       <div className="studio-preview-toolbar">
@@ -56,6 +71,7 @@ export function PreviewCanvas(props: Props) {
                   onFit: () => props.onDevice('desktop'),
                 },
               })}
+          guide={columnGuide.menu}
         />
 
         <CursorChatButton
@@ -69,7 +85,7 @@ export function PreviewCanvas(props: Props) {
       {props.collection && props.document ? (
         <CollectionEditor document={props.document} />
       ) : (
-        <PreviewSurface props={props} sizing={sizing} />
+        <PreviewSurface props={props} sizing={sizing} shownGuide={columnGuide.shown} />
       )}
     </main>
   );
@@ -77,9 +93,11 @@ export function PreviewCanvas(props: Props) {
 function PreviewSurface({
   props,
   sizing,
+  shownGuide,
 }: {
   readonly props: Props;
   readonly sizing: ReturnType<typeof usePreviewSizing>;
+  readonly shownGuide: ShownGuide | undefined;
 }) {
   const loading = usePreviewLoading(
     props.preview.url,
@@ -106,6 +124,7 @@ function PreviewSurface({
             key={loading.attempt}
             props={props}
             sizing={sizing}
+            shownGuide={shownGuide}
             loaded={loading.loaded}
           />
         ))}
@@ -116,10 +135,12 @@ function PreviewSurface({
 function DesignFrame({
   props,
   sizing,
+  shownGuide,
   loaded,
 }: {
   readonly props: Props;
   readonly sizing: ReturnType<typeof usePreviewSizing>;
+  readonly shownGuide: ShownGuide | undefined;
   readonly loaded: () => void;
 }) {
   return (
@@ -161,16 +182,18 @@ function DesignFrame({
           </div>
         )}
       </div>
-      <CanvasOverlays props={props} sizing={sizing} />
+      <CanvasOverlays props={props} sizing={sizing} shownGuide={shownGuide} />
     </>
   );
 }
 function CanvasOverlays({
   props,
   sizing,
+  shownGuide,
 }: {
   readonly props: Props;
   readonly sizing: ReturnType<typeof usePreviewSizing>;
+  readonly shownGuide: ShownGuide | undefined;
 }) {
   const spacing = useLiveValue(spacingHover);
   const style: CSSProperties = {
@@ -180,6 +203,8 @@ function CanvasOverlays({
   };
   return (
     <div className={`preview-overlay-layer ${sizing.width ? '' : 'full'}`} style={style}>
+      {/* First in the layer, so the outlines and spacing bands paint over it. */}
+      {shownGuide && <GuideOverlay {...shownGuide} scale={sizing.viewport.scale} />}
       <CollaboratorOutlines
         peers={props.collaborators}
         nodes={props.nodes}
diff --git a/studio/src/features/preview/previewClient.ts b/studio/src/features/preview/previewClient.ts
index 35656040..6e5a2472 100644
--- a/studio/src/features/preview/previewClient.ts
+++ b/studio/src/features/preview/previewClient.ts
@@ -3,6 +3,7 @@ import { receiveLiveText, applyLiveText } from './liveTextClient';
 import { installCursorPresence } from '../collaboration/cursorClient';
 import { receiveRenderPush } from './renderPushClient';
 import { rectsForPath } from '../../../vendor/stacki/electron/preload/frameMeasure';
+import { startGuide } from '../../../vendor/stacki/electron/preload/frameGuide';
 import {
   taggedPlaces,
   inFocus,
@@ -19,6 +20,7 @@ const studioOrigin =
   location.origin;
 const post = (message: unknown) => window.parent.postMessage(message, studioOrigin);
 const cursorPresence = installCursorPresence(post);
+const columnGuide = startGuide(post);
 // This async module is appended after page markup. Reveal that markup without
 // waiting for slow images or the separate morph module to finish loading.
 requestAnimationFrame(() => post({ type: 'studio:preview-ready' }));
@@ -164,6 +166,7 @@ window.addEventListener('message', (event) => {
   receiveLiveText(data);
   receiveLiveNumericStyles(data);
   cursorPresence.receive(data);
+  columnGuide.receive(data);
   if (data.type === 'studio:collaborators' && 'paths' in data && Array.isArray(data.paths)) {
     collaborators = data.paths
       .filter((path: unknown): path is string => typeof path === 'string' && path.length <= 1000)
diff --git a/studio/src/features/preview/previewKeys.ts b/studio/src/features/preview/previewKeys.ts
index 0b17b094..8b5e45e4 100644
--- a/studio/src/features/preview/previewKeys.ts
+++ b/studio/src/features/preview/previewKeys.ts
@@ -7,6 +7,8 @@ const keys = new Set([
   'v',
   'f',
   'e',
+  // ⇧G shows or hides the column guide (guideSettings.ts).
+  'g',
   'backspace',
   'delete',
   '1',
diff --git a/studio/src/features/preview/usePreview.ts b/studio/src/features/preview/usePreview.ts
index 02f46d18..879a40c9 100644
--- a/studio/src/features/preview/usePreview.ts
+++ b/studio/src/features/preview/usePreview.ts
@@ -6,6 +6,8 @@ import {
   setCanvasFrame,
   noteCanvasReady,
 } from '../../../vendor/stacki/src/editor/canvasQuery';
+import { parsePreviewMessage } from '../../../vendor/stacki/src/features/preview/previewMessages';
+import type { GuideMetrics } from '../../../vendor/stacki/src/features/preview/guideModel';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { request, routeFor } from '../project/projectClient';
 import { record, string } from '../../shared/validation';
@@ -18,6 +20,8 @@ export function usePreview(
   onOpen?: (id: string, occurrence: number) => void,
 ) {
   const [outlines, setOutlines] = useState(emptyOutlines);
+  // What the column guide is drawn from; undefined until the page reports.
+  const [guide, setGuide] = useState<GuideMetrics | undefined>(undefined);
   const frame = useRef<HTMLIFrameElement>(null);
   const loadListeners = useRef(new Set<() => void>());
   const subscribeLoad = useCallback((listener: () => void) => {
@@ -31,11 +35,12 @@ export function usePreview(
   const callbacks = useRef({ onSelect, onOpen, report });
   callbacks.current = { onSelect, onOpen, report };
   const target = usePreviewTarget(file, enabled, callbacks);
-  usePreviewMessages(frame, target, callbacks, setOutlines);
+  usePreviewMessages(frame, target, callbacks, { setOutlines, setGuide });
 
   return {
     frame,
     outlines,
+    guide,
     subscribeLoad,
     reveal: (id: string, occurrence = 0) => {
       reveal.current = { type: 'studio:reveal', id, occurrence };
@@ -66,8 +71,12 @@ function usePreviewMessages(
     onOpen: ((id: string, occurrence: number) => void) | undefined;
     report: (error: unknown) => void;
   }>,
-  setOutlines: (state: OutlineState) => void,
+  setters: {
+    readonly setOutlines: (state: OutlineState) => void;
+    readonly setGuide: (metrics: GuideMetrics) => void;
+  },
 ) {
+  const { setOutlines, setGuide } = setters;
   useEffect(() => {
     let timer: ReturnType<typeof setTimeout>;
     const patch = () => {
@@ -86,10 +95,7 @@ function usePreviewMessages(
       ) {
         return;
       }
-      const outlines = parseOutlines(event.data);
-      if (outlines) {
-        setOutlines(outlines);
-      }
+      receiveMeasurements(event.data, setOutlines, setGuide);
       receiveStudioSignals(event.data, patch);
       if (isMessage(event.data, 'avb:query-result')) {
         receiveCanvasReply(event.data);
@@ -122,7 +128,23 @@ function usePreviewMessages(
       window.removeEventListener('studio:source-updated', patch);
       window.removeEventListener('message', receive);
     };
-  }, [target, frame, callbacks, setOutlines]);
+  }, [target, frame, callbacks, setOutlines, setGuide]);
+}
+// What the page measured: the outlines it draws, and what the column guide is
+// drawn from, read through the shared parser.
+function receiveMeasurements(
+  data: unknown,
+  setOutlines: (state: OutlineState) => void,
+  setGuide: (metrics: GuideMetrics) => void,
+) {
+  const outlines = parseOutlines(data);
+  if (outlines) {
+    setOutlines(outlines);
+  }
+  const message = parsePreviewMessage(data);
+  if (message?.kind === 'guide') {
+    setGuide(message.metrics);
+  }
 }
 function messageOccurrence(data: Record<string, unknown>) {
   const value = data['occurrence'];
diff --git a/test/renderer/preview/guideModel.test.js b/test/renderer/preview/guideModel.test.js
new file mode 100644
index 00000000..05075b9e
--- /dev/null
+++ b/test/renderer/preview/guideModel.test.js
@@ -0,0 +1,326 @@
+// Goal: the column guide lands where the project's content box is, takes each
+// value from the right source, and refuses what it cannot draw. Methodology:
+// resolve hand-built measurements against settings — Lumos's values, a project
+// that declares nothing (fluid defaults at both ends and the middle), menu
+// lengths and menu variables declared or missing, a capped wide screen — then
+// corrupt the inputs (zero columns, gutters wider than the box, lengths and
+// names out of bounds) and check the assertions and parsers say so. The menu's
+// column list is built, added to and cut back around its bounds: the default
+// count, the project's count, and eight entries.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const {
+  GUIDE_DEFAULTS,
+  GUIDE_FLUID_DEFAULTS,
+  GUIDE_LIMITS,
+  addGuideColumnChoice,
+  clampGuideOpacity,
+  fluidPx,
+  guideColumnOptions,
+  guideColumns,
+  guideLengthText,
+  guideProjectCount,
+  guideSizeText,
+  guideVariableNames,
+  parseGuideColumnCount,
+  parseGuideLength,
+  parseGuideSize,
+  removeGuideColumnChoice,
+  resetGuideColumnChoices,
+  resolveGuide,
+} = require('../../helpers/rendererModule')('src/features/preview/guideModel.ts');
+
+// Lumos at a 1440px viewport: 48px margins, 32px gutters, a 1440px cap.
+const LUMOS_WIDE = {
+  viewportWidthPx: 1440,
+  rootFontPx: 16,
+  marginPx: 48,
+  gutterPx: 32,
+  widthMaxPx: 1440,
+  columns: { count: 12, variable: '--_column-count' },
+  variablesPx: {},
+  variableCounts: {},
+};
+const NOTHING_DECLARED = {
+  viewportWidthPx: 1000,
+  rootFontPx: 16,
+  marginPx: undefined,
+  gutterPx: undefined,
+  widthMaxPx: undefined,
+  columns: undefined,
+  variablesPx: {},
+  variableCounts: {},
+};
+const length = (amount, unit) => ({ kind: 'length', length: { amount, unit } });
+const variable = (name) => ({ kind: 'variable', name });
+
+test('project values win for the margin, gutter and maximum width', () => {
+  const guide = resolveGuide(LUMOS_WIDE, GUIDE_DEFAULTS);
+  assert.deepEqual(guide.margin, { px: 48, source: 'project' });
+  assert.deepEqual(guide.gutter, { px: 32, source: 'project' });
+  assert.deepEqual(guide.widthMax, { px: 1440, source: 'project' });
+  assert.equal(guide.columnCount, 12);
+  assert.equal(guide.columnSource, 'project');
+});
+
+test('a count picked in Stacki overrides the project count', () => {
+  const guide = resolveGuide(LUMOS_WIDE, { ...GUIDE_DEFAULTS, columns: 16 });
+  assert.equal(guide.columnCount, 16);
+  assert.equal(guide.columnSource, 'stacki');
+  assert.deepEqual(guide.margin, { px: 48, source: 'project' });
+});
+
+test('a project that declares nothing is drawn from the menu, else the fluid defaults', () => {
+  const settings = { ...GUIDE_DEFAULTS, margin: length(2, 'rem') };
+  const guide = resolveGuide(NOTHING_DECLARED, settings);
+  assert.deepEqual(guide.margin, { px: 32, source: 'fixed' });
+  // At 1000px, Lumos's 16→32px gutter range (320→1440px) is at 16 + 16 × 680 / 1120.
+  assert.equal(guide.gutter.source, 'default');
+  assert.ok(Math.abs(guide.gutter.px - (16 + (16 * 680) / 1120)) < 1e-9);
+  assert.equal(guide.widthMax, undefined);
+  assert.equal(guide.columnCount, 12);
+  assert.equal(guide.columnSource, 'stacki');
+});
+
+test('fluid defaults hold their ends outside 320–1440px and follow the root font', () => {
+  const margin = GUIDE_FLUID_DEFAULTS.margin;
+  assert.equal(fluidPx(margin, 200, 16), 16);
+  assert.equal(fluidPx(margin, 320, 16), 16);
+  assert.equal(fluidPx(margin, 880, 16), 32);
+  assert.equal(fluidPx(margin, 1440, 16), 48);
+  assert.equal(fluidPx(margin, 2560, 16), 48);
+  // A 20px root scales the rem ends: 20 and 60px, as Lumos's own clamp() would.
+  assert.equal(fluidPx(margin, 200, 20), 20);
+  assert.equal(fluidPx(margin, 4000, 20), 60);
+  assert.throws(() => fluidPx({ pxMin: 2, pxMax: 1 }, 500, 16), /a fluid range grows/);
+});
+
+test('a menu variable is used as the page resolves it, and a missing one falls back', () => {
+  const metrics = { ...NOTHING_DECLARED, variablesPx: { '--pad': 40, '--wide': 900 } };
+  const settings = {
+    ...GUIDE_DEFAULTS,
+    margin: variable('--pad'),
+    gutter: variable('--missing'),
+    widthMax: variable('--wide'),
+  };
+  const guide = resolveGuide(metrics, settings);
+  assert.deepEqual(guide.margin, { px: 40, source: 'variable' });
+  assert.equal(guide.gutter.source, 'default');
+  assert.deepEqual(guide.widthMax, { px: 900, source: 'variable' });
+  const missingCap = resolveGuide(metrics, { ...settings, widthMax: variable('--none') });
+  assert.equal(missingCap.widthMax, undefined);
+});
+
+test('the menu outranks the project, whose value is the default it falls back to', () => {
+  const metrics = { ...LUMOS_WIDE, variablesPx: { '--pad': 10 } };
+  const settings = {
+    ...GUIDE_DEFAULTS,
+    margin: variable('--pad'),
+    gutter: length(1, 'rem'),
+    widthMax: length(1000, 'px'),
+  };
+  const guide = resolveGuide(metrics, settings);
+  assert.deepEqual(guide.margin, { px: 10, source: 'variable' });
+  assert.deepEqual(guide.gutter, { px: 16, source: 'fixed' });
+  assert.deepEqual(guide.widthMax, { px: 1000, source: 'fixed' });
+  // A menu variable the page does not declare falls back to the project's value.
+  const missing = resolveGuide(metrics, { ...settings, margin: variable('--missing') });
+  assert.deepEqual(missing.margin, { px: 48, source: 'project' });
+  // A menu maximum width that caps nothing falls back to the project's too.
+  const empty = resolveGuide(metrics, { ...settings, widthMax: length(0, 'px') });
+  assert.deepEqual(empty.widthMax, { px: 1440, source: 'project' });
+});
+
+test('typed values: a length, a variable name or var(), anything else refused', () => {
+  assert.deepEqual(parseGuideSize('32px'), length(32, 'px'));
+  assert.deepEqual(parseGuideSize('--pad'), variable('--pad'));
+  assert.deepEqual(parseGuideSize(' var( --container_2 ) '), variable('--container_2'));
+  for (const text of ['', '-pad', '--', '--a b', 'var(--a', 'var(pad)', '--a;color:red', '4em']) {
+    assert.equal(parseGuideSize(text), undefined, text);
+  }
+  const longest = `--${'a'.repeat(GUIDE_LIMITS.variableCharsMax - 2)}`;
+  assert.deepEqual(parseGuideSize(longest), variable(longest));
+  assert.equal(parseGuideSize(`${longest}a`), undefined);
+  assert.equal(guideSizeText(variable('--pad')), 'var(--pad)');
+  assert.equal(guideSizeText(length(2, 'rem')), '2rem');
+});
+
+test('the frame is asked about each menu variable once', () => {
+  const settings = {
+    ...GUIDE_DEFAULTS,
+    margin: variable('--pad'),
+    gutter: variable('--pad'),
+    widthMax: length(1200, 'px'),
+  };
+  assert.deepEqual(guideVariableNames(settings), ['--pad']);
+  assert.deepEqual(guideVariableNames(GUIDE_DEFAULTS), []);
+  const counted = { ...settings, gutter: variable('--gap'), columnVariable: '--cols' };
+  assert.deepEqual(guideVariableNames(counted), ['--pad', '--gap', '--cols']);
+});
+
+test('the project count: the menu variable as a count, then the known ones, then 12', () => {
+  const ownVariable = { ...GUIDE_DEFAULTS, columnVariable: '--cols' };
+  const declared = { ...LUMOS_WIDE, variableCounts: { '--cols': 10 } };
+  assert.equal(guideProjectCount(declared, ownVariable), 10);
+  assert.equal(resolveGuide(declared, ownVariable).columnCount, 10);
+  assert.equal(resolveGuide(declared, ownVariable).columnSource, 'project');
+  // Undeclared, or not a whole number, the variable gives way to the known ones.
+  const undeclared = { ...LUMOS_WIDE, variableCounts: { '--cols': undefined } };
+  assert.equal(guideProjectCount(undeclared, ownVariable), 12);
+  assert.equal(guideProjectCount(NOTHING_DECLARED, ownVariable), undefined);
+  assert.equal(resolveGuide(NOTHING_DECLARED, ownVariable).columnCount, 12);
+  assert.equal(resolveGuide(NOTHING_DECLARED, ownVariable).columnSource, 'stacki');
+  // A count picked in the menu still wins over the variable.
+  assert.equal(resolveGuide(declared, { ...ownVariable, columns: 16 }).columnCount, 16);
+});
+
+test('a project count outside 4 to 24 gives way, from either variable', () => {
+  const ownVariable = { ...GUIDE_DEFAULTS, columnVariable: '--cols' };
+  for (const count of [3, 25, 40]) {
+    const own = { ...LUMOS_WIDE, variableCounts: { '--cols': count } };
+    assert.equal(guideProjectCount(own, ownVariable), 12, `own ${count}`);
+    const detected = { ...NOTHING_DECLARED, columns: { count, variable: '--site-columns' } };
+    assert.equal(guideProjectCount(detected, GUIDE_DEFAULTS), undefined, `detected ${count}`);
+    assert.equal(resolveGuide(detected, GUIDE_DEFAULTS).columnCount, 12);
+    assert.equal(resolveGuide(detected, GUIDE_DEFAULTS).columnSource, 'stacki');
+  }
+  const edges = { ...NOTHING_DECLARED, variableCounts: { '--cols': 4 } };
+  assert.equal(guideProjectCount(edges, ownVariable), GUIDE_LIMITS.columnPickMin);
+  const top = { ...NOTHING_DECLARED, columns: { count: 24, variable: '--site-columns' } };
+  assert.equal(guideProjectCount(top, GUIDE_DEFAULTS), GUIDE_LIMITS.columnPickMax);
+});
+
+test('a maximum width the page resolves to nothing caps nothing', () => {
+  const guide = resolveGuide({ ...LUMOS_WIDE, widthMaxPx: 0 }, GUIDE_DEFAULTS);
+  assert.equal(guide.widthMax, undefined);
+});
+
+test('columns fill the content box between the margins, gutters between them', () => {
+  const columns = guideColumns(resolveGuide(LUMOS_WIDE, GUIDE_DEFAULTS));
+  assert.equal(columns.length, 12);
+  // 1440 − 2 × 48 = 1344; less 11 gutters of 32 = 992; twelve columns of 82.67.
+  assert.equal(columns[0].xPx, 48);
+  assert.ok(Math.abs(columns[0].widthPx - 992 / 12) < 1e-9);
+  const last = columns[11];
+  assert.ok(Math.abs(last.xPx + last.widthPx - (1440 - 48)) < 1e-9);
+  assert.ok(Math.abs(columns[1].xPx - (columns[0].xPx + columns[0].widthPx) - 32) < 1e-9);
+});
+
+test('past the maximum width the content box stays centred', () => {
+  const guide = resolveGuide({ ...LUMOS_WIDE, viewportWidthPx: 2000 }, GUIDE_DEFAULTS);
+  const columns = guideColumns(guide);
+  assert.equal(columns[0].xPx, (2000 - 1440) / 2);
+  const last = columns[11];
+  assert.ok(Math.abs(last.xPx + last.widthPx - (2000 + 1440) / 2) < 1e-9);
+});
+
+test('gutters that leave no room draw no columns', () => {
+  const crowded = { ...LUMOS_WIDE, viewportWidthPx: 400, gutterPx: 40 };
+  assert.deepEqual(guideColumns(resolveGuide(crowded, { ...GUIDE_DEFAULTS, columns: 24 })), []);
+  const marginsOnly = { ...LUMOS_WIDE, viewportWidthPx: 80 };
+  assert.deepEqual(guideColumns(resolveGuide(marginsOnly, GUIDE_DEFAULTS)), []);
+});
+
+test('column counts the guide cannot draw are assertion failures', () => {
+  const guide = resolveGuide(LUMOS_WIDE, GUIDE_DEFAULTS);
+  assert.throws(() => guideColumns({ ...guide, columnCount: 2.5 }), /column count is an integer/);
+  for (const columnCount of [0, 3, 25]) {
+    assert.throws(() => guideColumns({ ...guide, columnCount }), /column count within range/);
+  }
+  assert.throws(() => resolveGuide({ ...LUMOS_WIDE, rootFontPx: 0 }, GUIDE_DEFAULTS), /root font/);
+});
+
+test('typed lengths take px or rem, a bare number is px, anything else is refused', () => {
+  assert.deepEqual(parseGuideLength('48px'), { amount: 48, unit: 'px' });
+  assert.deepEqual(parseGuideLength(' 3 REM '), { amount: 3, unit: 'rem' });
+  assert.deepEqual(parseGuideLength('24'), { amount: 24, unit: 'px' });
+  assert.deepEqual(parseGuideLength('.5rem'), { amount: 0.5, unit: 'rem' });
+  for (const text of ['', 'px', '-4px', '4em', '4 px rem', 'var(--x)', '1e3px', 'Infinitypx']) {
+    assert.equal(parseGuideLength(text), undefined, text);
+  }
+  assert.equal(parseGuideLength(`${GUIDE_LIMITS.lengthPxMax + 1}px`), undefined);
+  assert.equal(parseGuideLength(`${GUIDE_LIMITS.lengthRemMax + 1}rem`), undefined);
+  assert.deepEqual(parseGuideLength(`${GUIDE_LIMITS.lengthPxMax}px`), {
+    amount: GUIDE_LIMITS.lengthPxMax,
+    unit: 'px',
+  });
+});
+
+test('lengths read back as they were typed', () => {
+  assert.equal(guideLengthText({ amount: 1.23456, unit: 'rem' }), '1.235rem');
+  assert.equal(guideLengthText({ amount: 32, unit: 'px' }), '32px');
+});
+
+test('the default list is 6, 8, 10, 12 and 16', () => {
+  assert.deepEqual(GUIDE_DEFAULTS.columnChoices, [6, 8, 10, 12, 16]);
+});
+
+test('a typed count is a whole number within 4 and 24, else refused', () => {
+  assert.equal(parseGuideColumnCount('4'), GUIDE_LIMITS.columnPickMin);
+  assert.equal(parseGuideColumnCount('10'), 10);
+  assert.equal(parseGuideColumnCount('24'), GUIDE_LIMITS.columnPickMax);
+  for (const text of [
+    '0',
+    '1',
+    '3',
+    '25',
+    '99',
+    '100',
+    '04x',
+    '',
+    ' 8',
+    'ten',
+    '-8',
+    '8.5',
+    '8,5',
+  ]) {
+    assert.equal(parseGuideColumnCount(text), undefined, text);
+  }
+});
+
+test('the list names the count the guide defers to, once and in order', () => {
+  const list = [6, 8, 10, 12, 16];
+  const labels = (projectCount) =>
+    guideColumnOptions(list, projectCount).map(({ count, source }) => `${count} ${source}`);
+  assert.deepEqual(labels(undefined), ['6 list', '8 list', '10 list', '12 default', '16 list']);
+  assert.deepEqual(labels(12), ['6 list', '8 list', '10 list', '12 project', '16 list']);
+  assert.deepEqual(labels(10), ['6 list', '8 list', '10 project', '12 list', '16 list']);
+  assert.deepEqual(labels(14).slice(3, 6), ['12 list', '14 project', '16 list']);
+  assert.throws(() => guideColumnOptions([6, 8], undefined), /keeps the default/);
+});
+
+test('adding stops at eight entries, the project count included', () => {
+  const seven = [4, 6, 8, 10, 12, 16, 20];
+  assert.deepEqual(addGuideColumnChoice(seven, 24, undefined), [4, 6, 8, 10, 12, 16, 20, 24]);
+  assert.deepEqual(addGuideColumnChoice(seven, 24, 14), seven);
+  assert.deepEqual(addGuideColumnChoice(seven, 14, 14), [4, 6, 8, 10, 12, 14, 16, 20]);
+  assert.equal(addGuideColumnChoice(seven, 8, undefined), seven);
+  assert.throws(() => addGuideColumnChoice(seven, 3, undefined), /is a pick/);
+  // A project count added once the list is full leaves nine entries until one goes.
+  const eight = [4, 6, 8, 10, 12, 16, 20, 24];
+  assert.equal(guideColumnOptions(eight, 14).length, GUIDE_LIMITS.columnChoicesMax + 1);
+  assert.equal(addGuideColumnChoice(eight, 18, 14), eight);
+});
+
+test('removing a count or resetting the list drops a pick it no longer offers', () => {
+  const picked = { ...GUIDE_DEFAULTS, columns: 8 };
+  assert.deepEqual(removeGuideColumnChoice(picked, 6).columnChoices, [8, 10, 12, 16]);
+  assert.equal(removeGuideColumnChoice(picked, 6).columns, 8);
+  assert.equal(removeGuideColumnChoice(picked, 8).columns, 'project');
+  assert.throws(() => removeGuideColumnChoice(picked, 12), /stays in the list/);
+  assert.throws(() => removeGuideColumnChoice(picked, 20), /is in the list/);
+  const custom = { ...GUIDE_DEFAULTS, columns: 20, columnChoices: [12, 20] };
+  assert.deepEqual(resetGuideColumnChoices(custom).columnChoices, GUIDE_DEFAULTS.columnChoices);
+  assert.equal(resetGuideColumnChoices(custom).columns, 'project');
+  assert.equal(resetGuideColumnChoices({ ...custom, columns: 12 }).columns, 12);
+});
+
+test('opacity stays within 0.06 and 0.2, on 0.01 steps', () => {
+  assert.equal(clampGuideOpacity(0.1), 0.1);
+  assert.equal(clampGuideOpacity(0.123), 0.12);
+  assert.equal(clampGuideOpacity(0), GUIDE_LIMITS.opacityMin);
+  assert.equal(clampGuideOpacity(0.05), 0.06);
+  assert.equal(clampGuideOpacity(0.9), GUIDE_LIMITS.opacityMax);
+  assert.equal(clampGuideOpacity(0.19999), 0.2);
+});
diff --git a/test/renderer/preview/guideSettings.test.js b/test/renderer/preview/guideSettings.test.js
new file mode 100644
index 00000000..423614a2
--- /dev/null
+++ b/test/renderer/preview/guideSettings.test.js
@@ -0,0 +1,118 @@
+// Goal: a stored guide record from any app version reads back as usable
+// settings, and a bad field costs only that field. Methodology: parse a full record,
+// then records missing or garbling each field in turn, and check every other
+// field survives. The column list and the count picked from it are checked
+// together, since a pick only stands while the list offers it. Colours go
+// through CSS.supports, which Node lacks, so a stand-in accepts the literal
+// colours a browser would.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+globalThis.CSS = {
+  supports: (property, value) =>
+    property === 'color' && /^(#[0-9a-f]{3,8}|rgba?\([^()]*\)|red)$/i.test(value),
+};
+
+const { parseGuideColor, parseGuideSettings } = require('../../helpers/rendererModule')(
+  'src/features/preview/guideSettings.ts',
+);
+const { GUIDE_DEFAULTS, GUIDE_LIMITS } = require('../../helpers/rendererModule')(
+  'src/features/preview/guideModel.ts',
+);
+
+const STORED = {
+  visible: true,
+  columns: 16,
+  columnChoices: [6, 8, 12, 16],
+  columnVariable: '--grid-columns',
+  color: '#00ff88',
+  opacity: 0.15,
+  numbers: false,
+  margin: { kind: 'length', length: { amount: 2, unit: 'rem' } },
+  gutter: { kind: 'variable', name: '--gap' },
+  widthMax: { kind: 'length', length: { amount: 1200, unit: 'px' } },
+};
+
+test('a stored record reads back whole', () => {
+  assert.deepEqual(parseGuideSettings(STORED), STORED);
+  assert.deepEqual(parseGuideSettings({ ...STORED, columns: 'project' }).columns, 'project');
+});
+
+test('the guide is off by default, grey at 0.06, numbered, deferring to the project', () => {
+  assert.equal(GUIDE_DEFAULTS.visible, false);
+  assert.equal(GUIDE_DEFAULTS.color, 'rgb(146, 146, 146)');
+  assert.equal(GUIDE_DEFAULTS.opacity, 0.06);
+  assert.equal(GUIDE_DEFAULTS.numbers, true);
+  assert.equal(GUIDE_DEFAULTS.columns, 'project');
+});
+
+test('anything that is not a record is the defaults', () => {
+  const PLATFORM_NULL = JSON.parse('null');
+  for (const input of [undefined, PLATFORM_NULL, 3, 'guide', true]) {
+    assert.deepEqual(parseGuideSettings(input), GUIDE_DEFAULTS);
+  }
+});
+
+test('a garbled field falls back alone', () => {
+  const garbled = {
+    visible: 'yes',
+    columns: 12.5,
+    columnChoices: [6, 6, 12],
+    columnVariable: 'cols;color:red',
+    color: 'var(--brand)',
+    opacity: Number.NaN,
+    numbers: 0,
+    margin: { kind: 'length', length: { amount: -1, unit: 'px' } },
+    gutter: { kind: 'variable', name: 'gap;color:red' },
+    widthMax: { kind: 'length', length: { amount: 4, unit: 'em' } },
+  };
+  for (const [field, bad] of Object.entries(garbled)) {
+    const parsed = parseGuideSettings({ ...STORED, [field]: bad });
+    assert.deepEqual(parsed[field], GUIDE_DEFAULTS[field], field);
+    for (const other of Object.keys(STORED).filter((key) => key !== field)) {
+      assert.deepEqual(parsed[other], STORED[other], `${field} kept ${other}`);
+    }
+  }
+});
+
+test('margin, gutter and maximum width are unset by default, and a stored size can be', () => {
+  assert.equal(GUIDE_DEFAULTS.margin, undefined);
+  assert.equal(GUIDE_DEFAULTS.gutter, undefined);
+  assert.equal(GUIDE_DEFAULTS.widthMax, undefined);
+  for (const unset of [undefined, 'none', { kind: 'other' }, { kind: 'variable' }]) {
+    assert.equal(parseGuideSettings({ ...STORED, margin: unset }).margin, undefined);
+  }
+});
+
+test('a stored list reads back sorted, and a bad one is the default list', () => {
+  const read = (columnChoices) => parseGuideSettings({ ...STORED, columnChoices }).columnChoices;
+  assert.deepEqual(read([16, 12, 4]), [4, 12, 16]);
+  assert.deepEqual(read([12]), [12]);
+  const tooLong = [4, 5, 6, 7, 8, 9, 10, 11, 12];
+  assert.equal(tooLong.length, GUIDE_LIMITS.columnChoicesMax + 1);
+  for (const bad of [undefined, '12', [6, 8], [3, 12], [12, 25], [12, 7.5], [12, '8'], tooLong]) {
+    assert.deepEqual(read(bad), GUIDE_DEFAULTS.columnChoices, JSON.stringify(bad));
+  }
+});
+
+test('a picked count the list does not offer defers to the project', () => {
+  assert.equal(parseGuideSettings({ ...STORED, columns: 13 }).columns, 'project');
+  assert.equal(parseGuideSettings({ ...STORED, columns: 24 }).columns, 'project');
+  const listed = { ...STORED, columns: 13, columnChoices: [12, 13] };
+  assert.equal(parseGuideSettings(listed).columns, 13);
+});
+
+test('a stored opacity is pulled back into range', () => {
+  assert.equal(parseGuideSettings({ ...STORED, opacity: 2 }).opacity, GUIDE_LIMITS.opacityMax);
+  assert.equal(parseGuideSettings({ ...STORED, opacity: 0 }).opacity, GUIDE_LIMITS.opacityMin);
+});
+
+test('colours: literal, bounded, never a variable', () => {
+  assert.equal(parseGuideColor(' #ff5c5c '), '#ff5c5c');
+  assert.equal(parseGuideColor('rgb(1, 2, 3)'), 'rgb(1, 2, 3)');
+  assert.equal(parseGuideColor(''), undefined);
+  assert.equal(parseGuideColor('not a colour'), undefined);
+  assert.equal(parseGuideColor('var(--brand)'), undefined);
+  assert.equal(parseGuideColor(42), undefined);
+  assert.equal(parseGuideColor(`rgb(${' '.repeat(GUIDE_LIMITS.colorCharsMax)}1, 2, 3)`), undefined);
+});
diff --git a/test/renderer/preview/previewMessages.test.js b/test/renderer/preview/previewMessages.test.js
index c3bea988..9bebb17e 100644
--- a/test/renderer/preview/previewMessages.test.js
+++ b/test/renderer/preview/previewMessages.test.js
@@ -174,3 +174,67 @@ test('forwarded shortcuts parse each variant and ignore every other or malformed
     assert.equal(parseShortcutMessage(input), undefined);
   }
 });
+
+test('guide measurements parse, absent values stay absent, and bounds hold', () => {
+  const guide = {
+    type: 'avb:guide',
+    viewportWidth: 1440,
+    rootFontSize: 16,
+    margin: 48,
+    gutter: 32,
+    widthMax: undefined,
+    columnCount: 12,
+    columnVariable: '--_column-count',
+    variables: { '--pad': 40, '--missing': undefined },
+    counts: { '--cols': 10, '--pad': undefined },
+  };
+  assert.deepEqual(parsePreviewMessage(guide), {
+    kind: 'guide',
+    metrics: {
+      viewportWidthPx: 1440,
+      rootFontPx: 16,
+      marginPx: 48,
+      gutterPx: 32,
+      widthMaxPx: undefined,
+      columns: { count: 12, variable: '--_column-count' },
+      variablesPx: { '--pad': 40, '--missing': undefined },
+      variableCounts: { '--cols': 10, '--pad': undefined },
+    },
+  });
+  // Counts arrive as the page read them: the range is the model's to apply.
+  for (const count of [0, 49, 140, 999]) {
+    const counts = { '--cols': count };
+    assert.equal(parsePreviewMessage({ ...guide, counts }).metrics.variableCounts['--cols'], count);
+    const site = { ...guide, columnCount: count };
+    assert.equal(parsePreviewMessage(site).metrics.columns.count, count);
+  }
+  for (const variable of ['--site-column-count', '--site-columns', '--_column-count']) {
+    const site = { ...guide, columnCount: 10, columnVariable: variable };
+    assert.deepEqual(parsePreviewMessage(site).metrics.columns, { count: 10, variable });
+  }
+  assert.equal(
+    parsePreviewMessage({ ...guide, columnCount: undefined }).metrics.columns,
+    undefined,
+  );
+  for (const bad of [
+    { margin: -1 },
+    { gutter: Number.NaN },
+    { widthMax: 100_001 },
+    { viewportWidth: '1440' },
+    { rootFontSize: 0 },
+    { rootFontSize: 1_001 },
+    { columnCount: 2.5 },
+    { columnVariable: '--anything' },
+    { margin: PLATFORM_NULL },
+    { variables: undefined },
+    { variables: { '--pad': -1 } },
+    { variables: { 'pad;color:red': 4 } },
+    { variables: { '--a': 1, '--b': 2, '--c': 3, '--d': 4, '--e': 5 } },
+    { counts: undefined },
+    { counts: { '--cols': 2.5 } },
+    { counts: { 'cols;color:red': 4 } },
+    { counts: { '--a': 1, '--b': 2, '--c': 3, '--d': 4, '--e': 5 } },
+  ]) {
+    assert.equal(parsePreviewMessage({ ...guide, ...bad }), undefined, JSON.stringify(bad));
+  }
+});