Breakpoints

Overview

A breakpoint in the Commmerce Editor is a named viewport band that owns its own slice of a node's responsive style map. Switching the canvas device toggle from xl to tablet swaps which slice the right-sidebar property panels read from and write to; the canvas itself resizes to that breakpoint's canvasWidth, and the parser emits a matching @media block in the published CSS. The same model applies to custom breakpoints — they are just extra slices keyed under customResponsiveStyles[id] instead of one of the four default keys.

The whole system is dynamic. Default breakpoints can be retuned (margins, label, min-width — except mobile, whose min-width is anchored at null) and even deleted as long as one breakpoint remains. Adding a custom breakpoint automatically re-shuffles the surrounding bands: recalculateBreakpointRanges sets each band's maxWidth to the next-higher band's minWidth − 1, so ranges never overlap and never leave gaps.

How it works

Breakpoint state lives in the dedicated useBreakpointStore (store/useBreakpointStore.ts) — a standalone Zustand store separate from the page tree so breakpoint edits never enter the delta-history undo stack. It exposes the full BreakpointSettings object plus selectors such as getMediaQuery(id), getDeviceConfig(id), getOrderedBreakpoints() and getLayoutConfig(id). The store persists per theme — loadThemeBreakpoints(themeId) reads localStorage key breakpoints-theme-<themeId> on mount, and saveThemeBreakpoints(themeId) writes it back after every committed change. The control bar in control/index.tsx wires those calls to the current URL's store_theme_id or app_id param.

Reads from non-React code go through helper exports in the same file: getMediaQueryForBreakpoint, getDeviceConfigForBreakpoint, getAllMediaQueries, getAllBreakpoints, getBreakpointWithFallback and getLayoutConfigForBreakpoint. The parser uses the safe wrappers in utils/breakpoint.utils.ts — getMediaQuerySafe(id) first checks the store and falls back to the hard-coded MEDIA_QUERIES map for the four defaults, returning an empty string if the id is unknown (which short-circuits CSS emission for deleted breakpoints). getBreakpointIdFromMediaQuery(condition) performs the reverse lookup when the parser ingests existing CSS.

Editing happens in two layers. settings/BreakpointSettings.tsx keeps a local draftSettings state — changes there do not hit the store until the user clicks Save in the surrounding panel. While the draft is active, control/index.tsx reads useEditorSettingsStore.draftSettings.breakpoints in preference to the committed value, so the toolbar's device toggle reflects the in-progress edits immediately. Drafts are mirrored to localStorage under breakpoints-draft-<themeId> so a hard reload mid-edit doesn't lose them, and the entry is cleared on Save or Discard.

On Save, importSettings(settings) validates the entire set, re-runs recalculateBreakpointRanges for consistency, commits to the store, and triggers a write to breakpoints-theme-<themeId>. For brand-new breakpoints with copiedFrom set, the surrounding panel (GlobalSettingsPanel.tsx / Settings.tsx) then calls copyBreakpointStyles(source, target) on the page store to walk every node and clone the source slice onto the new id.

On the canvas, the active breakpoint is mirrored in useCommmerceEditorSetupStore.deviceMode. Switching it also flips applyStylesToResponsive — anything other than xl routes style writes into the responsive slice; xl writes the base style. The Base / Resp toggle on the floating bottom toolbar overrides that default when you want to edit the base style while previewing a smaller device.

Key features

• Dynamic ranges — every default and custom breakpoint is editable; ranges are recomputed automatically so they stay contiguous.
• Up to 10 custom breakpoints, plus the 4 shipped defaults — for a maximum of 14 total bands per theme.
• Per-band canvas widths so the editor renders each breakpoint at a realistic frame size (e.g. xl @ 1920px, tablet @ 768px).
• Per-band contained margins for switching the layout between full-width and contained on a per-device basis.
• Style cloning on creation via copiedFrom + copyBreakpointStyles, so a new breakpoint can start from an existing band instead of empty.
• Drafts + race-resistant restore — drafts cached at breakpoints-draft-<themeId>, committed values mirrored to breakpoints-theme-<themeId>; the control bar compares the two on mount and after every commit to defend against cross-tab server-load downgrades.
• Consolidated @media output — the parser merges every per-breakpoint style for a selector into one media query block per breakpoint, with pseudo-class hoisting when values match across all defaults.
• Safe fallbacks — deleted breakpoints emit no CSS (getMediaQuerySafe returns ""), and getBreakpointWithFallback degrades unknown ids to a default band so renders never crash.
• Cross-theme block import — the BreakpointMappingDialog translates a foreign block's responsive slices into the active theme's breakpoint set on insert.

Default breakpoints

DEFAULT_BREAKPOINT_SETTINGS in types/breakpoint.types.ts ships the four default bands. Min-width is immutable for the lowest band (mobile) but can be retuned for the others. The full BreakpointConfig field set is shown below so you can see exactly what gets written to breakpoints-theme-<themeId> at boot.

All four defaults carry isDefault: true, isDeletable: true, and containedWidth: 0 (full-width). Even though defaults are deletable, deleteBreakpoint still refuses to delete the last remaining breakpoint regardless of which one it is.

BreakpointConfig — fields reference

Every breakpoint is a BreakpointConfig record. New custom breakpoints only need minWidth; the rest is derived. Defaults in the table below are the values written for a freshly created custom breakpoint inserted between two existing bands.

The wrapping BreakpointSettings object also holds: version (schema version for future migrations, currently 1), breakpoints[], and customBreakpointCounter — a monotonically incrementing integer used to mint unique custom_${'{N}'} ids.

Validation rules & limits

Validation runs in three places: validateNewBreakpointMinWidth (only when adding or retuning a band's minWidth), validateBreakpointConfig (on every breakpoint after a recalc), and validateBreakpointOverlap (sanity-check before commit).

Media queries the parser emits

generateMediaQueryFromConfig turns each config into a real @media string. The breakpoint's minWidth becomes (min-width: Npx) and the maxWidth becomes (max-width: Npx); if both are present they are joined with and.

The XL band has no upper bound — its styles apply at every viewport wider than 1281px. The mobile band has no lower bound. Every other band carries both bounds, so a tablet override does not bleed into desktop or mobile. This is what makes the editor's responsive cascade min-width and max-width aware, instead of pure mobile-first inheritance.

Per-breakpoint consolidation

parser/jsonToHtmlCss.ts deliberately collects every style override for a selector into a single bucket per breakpoint before emitting any CSS. The renderer walks four sources in order:

1. node.responsiveStyles[breakpointId] — default breakpoint overrides for the four built-ins.
2. node.customResponsiveStyles[breakpointId] — overrides for every custom breakpoint.
3. node.layoutConfig.responsiveGrid[breakpointId] — grid column / gap overrides on grid-container nodes (default breakpoints only).
4. Root-section layoutSettings[breakpointId] — derives max-width, margin-left and margin-right from the per-breakpoint containedWidth (or resets all three when node.isFullWidth === true).

All four feed a single consolidatedBreakpointStyles[breakpointId] map, then the parser writes one @media block per breakpoint per selector. The same consolidation applies to pseudo-class styles: if :hover, :focus, etc. resolve to identical values across every default breakpoint, the parser hoists them out of the media queries and emits them once as a base rule. Anything that diverges per breakpoint stays inside its own @media block.

The same parser ships on both sides — common/components/commmerce-editor/parser/ (frontend editor) and backend/src/parser/ (SSR renderer). The consolidation pass is identical so editor preview and live SSR emit the same CSS byte-for-byte.

Persistence & race-condition restore

Two localStorage keys carry the breakpoint state through hard reloads and cross-tab edits:

The race-condition handler in control/index.tsx runs on every committedBreakpoints change. Its sequence is:

1. Read localStorage[breakpoints-theme-<themeId>].
2. Parse and count lsSettings.breakpoints.
3. If the localStorage count exceeds the just-committed count, the server load is downgrading — restore via useBreakpointStore.getState().importSettings(lsSettings) and return (the re-importSettings fires this effect again with the restored value, which then persists itself).
4. Otherwise, schedule a microtask saveThemeBreakpoints(breakpointStorageKey) so localStorage stays in lockstep with the committed value.

copyBreakpointStyles flow

When a user ticks "Copy styles from existing breakpoint" while adding a custom breakpoint, the BreakpointConfig.copiedFrom field is set to the source breakpoint id. That is metadata only — no styles are copied at create time. The actual clone happens on Save:

1. GlobalSettingsPanel.handleSave (or Settings.handleSave) saves the new breakpoint set to the server.
2. It then iterates the new breakpoints and, for any with copiedFrom set, calls copyBreakpointStyles(bp.copiedFrom, bp.id) on the page store.
3. createStyleSlice.copyBreakpointStyles walks the entire page tree. For each node it reads the source slice (responsiveStyles[from] for default, or customResponsiveStyles[from] for custom) and writes it to the new id under customResponsiveStyles[to]. Pseudo-class and pseudo-element style slices are copied the same way.
4. The page's hasUnsavedChanges flips to true; the user can then save the page to persist the cloned styles.

copy happens once, on first save. After that the two breakpoints are independent — editing the source does not propagate to the target. copiedFrom is preserved on the config purely as documentation; setting it on an already-saved breakpoint has no effect.

Workflows

Examples

{
  "version": 1,
  "customBreakpointCounter": 0,
  "breakpoints": [
    { "id": "xl",      "label": "Extra Large (80.0625rem+)",   "minWidth": 1281, "maxWidth": null, "canvasWidth": 1920, "containedWidth": 0, "icon": "TvMinimal",  "isDefault": true, "isDeletable": true, "order": 4 },
    { "id": "desktop", "label": "Desktop (48.0625rem - 80rem)","minWidth": 769,  "maxWidth": 1280, "canvasWidth": 1280, "containedWidth": 0, "icon": "Monitor",    "isDefault": true, "isDeletable": true, "order": 3 },
    { "id": "tablet",  "label": "Tablet (26.9375rem - 48rem)", "minWidth": 431,  "maxWidth": 768,  "canvasWidth": 768,  "containedWidth": 0, "icon": "Tablet",     "isDefault": true, "isDeletable": true, "order": 2 },
    { "id": "mobile",  "label": "Mobile (26.875rem and below)","minWidth": null, "maxWidth": 430,  "canvasWidth": 430,  "containedWidth": 0, "icon": "Smartphone", "isDefault": true, "isDeletable": true, "order": 1 }
  ]
}

useBreakpointStore.getState().addCustomBreakpoint({
  minWidth: 1100,
  containedWidth: 32,
  label: "Narrow Desktop",
  icon: "Laptop",
  copyStylesFrom: "desktop"
});

/*   The store generates id = "custom_0" (incrementing customBreakpointCounter),   */
/*   recalculates ranges so desktop becomes 769-1099 and the new band 1100-1280,   */
/*   and saves to localStorage under breakpoints-theme-<themeId>.                  */
/*   copiedFrom: "desktop" is stored as metadata — the actual styles are not        */
/*   cloned until the surrounding panel calls copyBreakpointStyles on Save.         */

.hero {
  padding: 64px;
  background: #111;
}

@media (min-width: 1281px) {
  .hero { padding: 96px; }
}

@media (min-width: 769px) and (max-width: 1280px) {
  .hero { padding: 48px; }
}

@media (min-width: 431px) and (max-width: 768px) {
  .hero { padding: 32px; }
}

@media (max-width: 430px) {
  .hero { padding: 20px; }
}

/*   With containedWidth = 80 on desktop (canvasWidth = 1280):   */
@media (min-width: 769px) and (max-width: 1280px) {
  .root-section {
    max-width: 1120px;   /*   1280 − 2 × 80   */
    margin-left: auto;
    margin-right: auto;
  }
}

/*   isFullWidth = true on the same section overrides for every breakpoint:   */
@media (min-width: 769px) and (max-width: 1280px) {
  .root-section {
    max-width: none;
    margin-left: 0;
    margin-right: 0;
  }
}

Tips & gotchas

• Mobile's minWidth is locked. The lowest breakpoint must have minWidth: null — updateBreakpointValue rejects any attempt to change it with the error "Cannot change minWidth for mobile breakpoint". If you delete mobile, the next-lowest band is promoted to lowest automatically by recalculateBreakpointRanges.
• Custom breakpoints can be inserted between defaults. recalculateBreakpointRanges sorts everything by minWidth descending and reassigns maxWidth + order across the entire set, so a custom band at 900px slots cleanly between desktop and xl.
• The toolbar only renders four breakpoints inline. Anything beyond that (defaults + custom > 4) folds into the three-dot overflow menu next to the device pill group; the active breakpoint highlight follows you into the menu.
• Editing breakpoints uses a draft. Until you click Save in the surrounding settings panel, the store is untouched. The toolbar reads the draft so the (+) button and overflow stay in sync, and the draft is cached to localStorage at breakpoints-draft-<themeId> so a hard reload does not lose in-progress edits.
• Reset to defaults wipes custom breakpoints. The Reset action in BreakpointSettings replays DEFAULT_BREAKPOINT_SETTINGS; any customResponsiveStyles in the page JSON become orphan data.
• Deleted breakpoints emit no CSS. getMediaQuerySafe returns an empty string for unknown ids, so the parser silently skips orphan style buckets — the styles still live in the JSON until you save the page, but they will not appear in the rendered output.
• Pseudo-class styles auto-deduplicate. If :hover resolves to the same value across every default breakpoint, the parser hoists it to a single base rule instead of repeating it inside each @media block. Custom breakpoints are always emitted in their own media query.
• Race-condition restore. The control bar compares the localStorage cache against whatever the server load returned on every committedBreakpoints change; if the cache has more breakpoints (a cross-tab save the current tab missed), it restores via importSettings instead of letting the server downgrade the toolbar.
• copyBreakpointStyles runs once. Copying happens at the moment the new breakpoint is saved; after that the breakpoints are independent. There is no live two-way binding.
• Grid layout overrides are default-only. The parser writes layoutConfig.responsiveGrid[breakpointId] CSS only for default breakpoints — custom breakpoints do not yet have a grid override editor. Plain customResponsiveStyles[id] entries work as usual.
• Parser sync rule. Both common/components/commmerce-editor/parser/ and backend/src/parser/ implement the same consolidation logic. If you change one, change the other in the same task — otherwise editor preview and live SSR will diverge.