Save and Save as

Overview

Save persists the current editor canvas — sections, elements, attributes, styles, inline jsCode, and block metadata — to the backend. There are two modes, both surfaced by the same Dropdown.Button on the right side of the toolbar.

• Save (overwrite) — updates the current draft block_version in place. Allowed only when the version's status is 'draft' (Dev Portal) or 'draft'/'active' (Store Editor). Bound to Ctrl+S / Cmd+S.
• Save as... (new version) — clones the block into a new block_version_code = MAX + 1 row, uploads a fresh JSON blob to GCS, then redirects the editor to the new URL via window.location.href (full reload so history/clipboard reset). Bound to Ctrl+Shift+S / Cmd+Shift+S.

Independent of either, the in-memory canvas state is mirrored to IndexedDB on every store mutation (keyed per dev-app / store-theme / block via deriveEditorScope) so a tab refresh restores unsaved work without a server round-trip. The history slice tracks every change as a delta — Save itself does not consume history, it only flips hasUnsavedChanges back to false so the green dot on the toolbar disappears.

How it works

The dropdown lives in theme-editor/editor/StoreEditor.tsx (Store Editor) and dev/editor/DevEditor.tsx (Dev Portal). Both pass a <SaveBlock /> component into CommmerceEditor via the customUIElements prop, which the editor's toolbar (common/components/commmerce-editor/control/index.tsx) renders on the right side of the second bar next to Publish.

When the user clicks Save or presses Ctrl+S, handleSaveBlock("overwrite") runs. It safety-coerces the mode to "new_version" if the current block_version_status is not a draft (Dev Portal blocks active/published versions; Store Editor blocks only published), then builds the payload, calls the backend, and clears the hasUnsavedChanges flag on the createHistorySlice store.

The save payload always carries the full children tree (sections and nested elements as BaseNode[]), inline jsCode, and optional block metadata (block_name, block_slug, block_version_slug, block_image, block_version_settings). Global blocks referenced inside the tree are stripped to reference stubs by stripGlobalBlockData in backend/src/controllers/api/dev-portal/blocks.ts — the parent only stores wrapper metadata while each global block lives at its own block_id route.

Server-side, the controller validates the URL params and the block-mapping row, then either UPDATEs block_version_tb + overwrites the GCS blob (overwrite mode) or INSERTs a new row, uploads to a new path ${app_slug}/v${app_version_code}/blocks/block_${block_id}_v${next_code}, and refreshes the app_block_mapping_tb entry (new_version mode). Any dirty global blocks tracked in editedBlocks / dirtyBlockKeys on the store are saved in sequence after the primary save.

On success, the editor shows a green message ("Block saved successfully") via useMessageStore, flips setHasUnsavedChanges(false), and clears the dirty global-block map. On failure, it surfaces the server-side error message verbatim — typically "Cannot overwrite ... status is 'active'" when the version is locked.

Key features

• Two-mode dropdown — single button with primary action (overwrite) and split-menu fork (new_version). The menu auto-disables "Save (Ctrl+S)" when the version is non-draft so the only safe path is a fork. USE CASE: a designer iterating on a draft never needs to think about modes; a developer revisiting a published v2 sees Save disabled and is funneled into v3.
• Status-aware coercion — Ctrl+S on a published/active version silently rewrites the request to mode: "new_version" so the user never hits the backend validation error. USE CASE: muscle-memory Ctrl+S on a live page still saves work, just as a brand-new v3 draft instead of mutating production.
• Delta-based history — every store mutation is wrapped in saveToHistory() on createHistorySlice; only the diff between snapshots is stored. History caps at maxHistorySize = 50. Save does not consume history — it just flips hasUnsavedChanges. USE CASE: undoing the last 50 edits after a Save still works because Save doesn't clear the history stack.
• Per-tab IndexedDB scope — deriveEditorScope in common/components/commmerce-editor/store/storage/deriveScope.ts builds a unique key per (app_id, app_version_code, block_id, block_version_code) tuple. Multiple tabs editing different blocks never clobber each other. Restore happens automatically via useCommmerceEditor.persist.rehydrate() on mount. USE CASE: an author keeps Home, Product Page, and Footer open in three tabs — each tab restores its own unsaved work on refresh without leaking.
• Global block tracking — when the user edits a referenced global block in-place, its full tree is captured in editedBlocks and the key pushed onto dirtyBlockKeys. Save iterates over dirtyBlockKeys after the main save and writes each as mode: "overwrite". USE CASE: tweaking the nav bar inside the Home page editor and pressing Save persists both the Home page AND the global Header in one click.
• GCS round-trip — block JSON is uploaded by uploadAppDataAsJson in backend/src/packages/GoogleStorage.ts; only the resulting URL is stored in block_version_tb.block_data. USE CASE: a 500 KB section tree never bloats MySQL; the database stores one URL, the JSON lives on GCS where the SSR layer can stream it.
• Settings persistence is separate — Global Settings (typography, colors, breakpoints, SEO, layout) go through their own dedicated save flow and are no longer bundled into the block-save payload. USE CASE: changing a brand color saves only the settings row, not the entire 500 KB page tree.
• Auto-save before publish — handlePublish in DevEditor / StoreEditor checks hasUnsavedChanges and runs an inline save against the same saveBlock / saveStoreBlock endpoint before invoking the publish call. USE CASE: clicking Publish on dirty edits ships the in-memory tree, not the last saved one — the author never has to remember to Save first.
• Locked breakpoints / settings cache — the toolbar additionally mirrors the breakpoint config and editor settings to localStorage (keys breakpoints-theme-*, editor-settings-*) so a hard reload on a slow connection still shows the last-known good values while the API call completes. USE CASE: on a flaky network the editor doesn't flash default breakpoints for 2 seconds before the server response arrives.
• Server-side child mapping sync — extractAllChildBlockRefs scans the new block_data for nested block references and the controller adds/removes app_block_mapping_tb rows so the bundle resolver sees the right children. USE CASE: dragging a global Footer into the page and pressing Save automatically registers the parent-child mapping needed for SSR composition.

State store methods

The editor's save flow touches two slices of the main useCommmerceEditor store. Both expose actions the toolbar wires up directly.

Workflows

Keyboard shortcuts

All shortcut handlers live in control/index.tsx (undo/redo) and inside each project's SaveBlock component (save). They no-op when saving === true or when there are no unsaved changes.

Tips & gotchas

• The primary Save button is gated on hasUnsavedChanges. The dropdown trigger is always interactive, but the primary click is disabled when there's nothing to save. This is why landing on a freshly-loaded editor shows a greyed-out button.
• Save as... always navigates away. Because the backend mints a new block_version_code, the editor does a hard reload to the new URL. Any open dialogs, expanded sidebar panels, and the undo history all reset on the new fork.
• Global Settings have their own save path through the Settings dialog and the useSaveSettings hook. Editing typography and pressing Ctrl+S in the canvas does not save those — open the Settings dialog and click its Save button, which uses the dedicated settings save flow and clears the localStorage draft cache.
• Server overwrites are status-strict. Dev Portal will refuse to overwrite anything that is not 'draft'; Store Editor refuses only 'published' — Store's 'active' blocks are the editing surface. The frontend mirrors this in overwriteDisallowed.
• Dirty global blocks are saved sequentially, not atomically. A successful primary save can be followed by a partial global-block save failure ("Page saved. 2 global block(s) saved, 1 failed."). Check the warning message after a multi-block save.
• Per-tab IndexedDB is keyed by URL. Hot-swapping between blocks within the same tab triggers resetEditorState() followed by a re-hydrate against the new key — this is intentional and prevents one block's unsaved tree from leaking into another.
• Hardware reload during an in-flight save can leave the canvas behind. The IndexedDB write happens on every mutation, so the canvas state survives. But if the server save failed mid-flight, you'll see your edits restored locally and a stale block_data URL on the server until you press Save again.
• New-version mode auto-promotes the previous draft to active if no version of this block was already active in the current app_version. This guarantees the storefront keeps rendering a known-good version while the user iterates on the new draft.
• Slug changes UPDATE the routing table separately. When block_slug is included in the payload, the controller does an extra UPDATE on app_page_routes — so the route change goes live the next time the bundle is rebuilt, not retroactively against existing visits.