@acms-subir/core 0.3.15 → 0.3.17

package/docs/environment-sync.md

@@ -0,0 +1,302 @@
+# Selective environment sync
+
+Use `acms sync` to transfer selected native ACMS content between two running
+sites. Both directions work: local → production, production → local, or staging
+→ production. Both sites must run a version that includes sync protocol 1.
+Run `acms sync --help` for the command reference or `acms docs sync` to read
+this guide from an installed package.
+
+This transfers content and portable configuration, not application code,
+database schemas, environment variables, or an entire database. Deploy theme
+code, collection definitions and enabled modules through the application's
+normal deployment process first. Secrets remain in each environment's own
+Infisical project/environment/folder. Backups remain the disaster recovery tool.
+
+## Connect and choose a direction
+
+An owner creates scoped keys under **Design → Access**. The existing design-key
+screen also offers these permissions:
+
+| Scope | Permission |
+| --- | --- |
+| `sync:read` | Read the portable inventory, drafts, media and transfer history |
+| `sync:write` | Create plans, upload media and apply draft transfers; also needs `sync:read` |
+| `sync:publish` | Apply live, publication and rollback plans; also needs both scopes above |
+
+Only an owner can issue sync keys. Existing design, agent and booking keys do
+not implicitly grant sync access. For a one-way transfer, the source needs
+read access and the destination needs read/write (plus publish for live work).
+Reverse transfers need the corresponding permissions in the other direction.
+
+Supply the keys privately through the named environment variables, preferably
+using the CLI's existing Infisical runtime-injection setup. Do not place tokens
+in command arguments, plan files, source control, or chat.
+
+```sh
+acms site connect http://localhost:4321 --site local --token-env ACMS_LOCAL_TOKEN
+acms site connect https://example.com --site production --token-env ACMS_PRODUCTION_TOKEN
+acms sync init --from local --to production
+```
+
+`site connect` is an existing command. It stores the URL and environment-variable
+name, not the credential. Remote sites require HTTPS; loopback HTTP is allowed.
+Sync accesses each site's authenticated HTTP API, so the CLI needs network
+access to both sites. It does not open a production database directly.
+
+`init` selects a direction and resumes that pair's saved selection. It does not
+transfer content. Switching directions keeps separate selections and baselines:
+
+```sh
+acms sync init --from production --to local
+```
+
+The CLI binds the pair to installation identities as well as URLs. A changed
+profile URL or replaced installation requires a fresh `init`. Two aliases for
+the same installation cannot be synchronized to each other. Cloning the entire
+database also clones its installation identity; use independent installations
+and content transfers rather than using a database clone as a second sync site.
+
+## Inspect and select
+
+```sh
+acms sync status
+acms sync status --type pages
+acms sync status --selected
+acms sync status --conflicts
+acms sync list
+acms sync list --type events --calendar community
+acms sync list --search welcome
+```
+
+Status distinguishes create, update, skip, preserve and conflict. The inventory
+shows references and stable keys. Use the full key when names are ambiguous.
+Posts accept `post:<collection>/<slug>`; `post:<slug>` also works when unique.
+Forms and places have names rather than slugs, so quote references containing
+spaces, such as `'form:Contact us'`.
+
+```sh
+acms sync add page:home page:about
+acms sync add post:posts/welcome
+acms sync add event:open-house
+acms sync add resource:meeting-room
+acms sync add 'form:Contact us'
+acms sync add calendar:community --include-events
+acms sync add --type navigation
+acms sync add --type booking-config
+acms sync add --all
+```
+
+`add --all` selects eligible changed source items, including conflicts for
+review. It never selects customer bookings, submissions, account credentials,
+secrets or deletions. `add --type` selects changed items in that category.
+Selecting a calendar alone does not select all its events; `--include-events`
+does. Selected events include the calendars and other referenced objects they
+need. Pages include referenced media and native ID-based dependencies. Links
+to arbitrary URLs are not crawled or copied.
+
+`acms sync select` is a terminal picker: it displays numbered items and accepts
+a comma-separated selection. Blank input preserves the selection. Explicit
+commands provide the equivalent workflow for scripts; interactive mode cannot
+be combined with `--json`.
+
+```sh
+acms sync remove page:test-landing
+acms sync remove --type events
+acms sync clear
+```
+
+Removing items only changes the pending selection. An explicitly removed
+dependency blocks its parent rather than silently reselecting it. Add the
+dependency again, preserve an existing destination version, or remove the parent.
+`clear` clears selections, exclusions and conflict decisions, not history or
+the last successful synchronization baseline.
+
+## Review differences and conflicts
+
+```sh
+acms sync diff
+acms sync diff page:home
+acms sync diff --selected
+acms sync resolve page:home --use source
+acms sync resolve page:home --use destination
+acms sync resolve page:home --interactive
+```
+
+Diff shows actual before/after field values. The source inventory includes
+saved pending drafts as the editable source version; it does not capture
+unsaved browser edits. Live versus draft behavior on the destination is chosen
+when planning.
+
+The CLI remembers the last successfully applied source and destination hashes:
+
+| Comparison | Default action |
+| --- | --- |
+| Same content on both sites | Skip |
+| Only the source changed since the baseline | Update |
+| Only the destination changed | Preserve destination |
+| Both changed differently | Conflict |
+| Existing item with no established baseline | Review before overwrite |
+| Previously transferred item deleted on destination | Conflict |
+| Item exists only on destination | Preserve |
+
+Matching uses recorded identities first. A unique natural-key candidate
+(such as a collection and slug) can be proposed for the initial match, but a
+differing existing item requires explicit resolution. Ambiguous names are
+blocked; fix ambiguity on the destination first. Slug changes keep an established
+identity. Sync does not automatically create redirects for renamed URLs;
+select the appropriate redirect records as well.
+
+`--use source` approves the source version; `--use destination` leaves the
+destination content intact. If a previously transferred item was deleted on
+the destination, `--use source` explicitly approves recreating it. Required
+preserved dependencies are linked without overwriting their data. Interactive
+resolution chooses whole top-level fields;
+it is not a text-editor or automatic rich-text/array merge. Conflict decisions
+are tied to the reviewed source and destination versions and expire when either
+changes. There is no `--force` bypass.
+
+## Plan, apply and publish
+
+```sh
+acms sync plan
+acms sync plan --mode draft --out deployment-plan.json
+acms sync plan --mode live
+acms sync show <plan-id>
+acms sync apply --plan <plan-id>
+acms sync apply --file deployment-plan.json
+```
+
+Draft is the default. Pages, posts, events, forms and design support draft
+transfers. New draft-capable records are created unpublished; existing live
+content retains its live version while changes are staged. New required media
+and tag records are added to their libraries. Updating existing media/tag
+metadata and transferring navigation, calendars, resources, booking links,
+places, redirects or portable settings requires an explicit live plan. A
+published form's definition can be staged; its name/kind/purpose changes need
+a live plan. An event with room holds must have those configured on the
+destination after transfer.
+
+Plans list selected operations, dependencies, field differences and whether
+changes affect drafts or live content. They are stored on the destination and
+bound to its installation ID, revision and exact payload. Planning changes
+transfer metadata only, never site content. Exported files include a human-
+readable copy, source/destination binding and a digest; editing their payload
+does not alter the immutable server plan. Create a new plan to change it.
+
+Apply displays the plan and asks for confirmation. Automation uses:
+
+```sh
+acms sync apply --plan <plan-id> --yes --json
+```
+
+`--yes` skips only the confirmation. It cannot bypass scopes, dependencies,
+schema/theme compatibility, conflicts or stale revisions. Apply does not need
+the current selection to match the saved plan; it applies that exact plan.
+
+The database checks the reviewed revision inside the same transaction as all
+record writes, identity links, search-index changes and the completed-run
+receipt. Content/draft changes through other APIs also advance the revision.
+The first implementation uses a conservative **site-wide revision**: unrelated
+content edits or booking/submission activity after planning can require a new
+plan too. This favors rejecting stale plans over overwriting concurrent work.
+
+Media is uploaded before that transaction to immutable checksum-based keys.
+Already present verified objects are skipped. Failed uploads or a rejected
+database transaction can leave unused files, but do not partially publish the
+database changes. Sync does not delete these files automatically.
+
+If a request or terminal is interrupted, rerun the same apply command. A
+completed server receipt is returned without repeating writes; otherwise
+verified files are reused and the database transaction can be retried if the
+reviewed revision still matches. There is no blind retry of stale writes.
+
+After reviewing staged content in the site's editors/previews:
+
+```sh
+acms sync plan --publish <run-id>
+acms sync apply --plan <publish-plan-id>
+```
+
+This publishes only the draft-capable items in that run. It rejects later edits
+to those items instead of implicitly publishing somebody else's changes.
+Design/layout changes conservatively share a settings guard.
+
+## History and rollback
+
+```sh
+acms sync history
+acms sync show <run-id>
+acms sync plan --rollback <run-id>
+acms sync apply --plan <rollback-plan-id>
+```
+
+History lists the latest 100 plans and runs. An older known ID can still be
+read with `show`. Rollback creates another reviewable live plan. It restores
+previous live/draft values for changed items and can delete items that the run
+created, provided they have not subsequently changed or acquired dependents or
+production activity. Media bytes are retained, even if their newly created
+library record is removed. Later design/settings edits may conservatively block
+rollback of a page layout. Rollback does not undo delivered emails, webhook
+deliveries, external effects or code deployments.
+
+## Transfer coverage
+
+| Category | Included | Environment-specific data preserved |
+| --- | --- | --- |
+| `pages` | Native rich text, legacy blocks, translations, layout, SEO and routing fields | Unselected pages |
+| `posts` | Native content, translations, metadata and byline references | Staff credentials and account authority |
+| `design` | Theme selection, design overrides and branding images | Theme source code; page layouts travel with pages |
+| `navigation` | Individual navigation records | Other destination navigation records |
+| `media` | Metadata, originals and variants, with checksums | Unselected assets |
+| `redirects` | Selected redirect records | Other destination redirects |
+| `calendars` | Calendar definitions | Feed tokens and source URLs |
+| `events` | Native events and registration-form definitions | Registrations and notification history |
+| `resources` | Resource configuration | Private busy-feed URLs, notification recipients and feed tokens |
+| `booking-config` | Booking-link definitions and calendar/booking defaults | Reservations, retry ledgers and private management links |
+| `forms` | Definitions/templates, native drafts | Submitted responses |
+| `site-settings` | Title, tagline, footer text, locale, timezone, announcement | Canonical site URL, integration/analytics configuration, injected code, secrets |
+| `places` | Saved place definitions | Other saved places |
+| `tags` | Tag metadata | Other tag records |
+
+Byline dependencies map to existing destination profiles. Sync never creates
+or edits user accounts; provision the intended profile separately and preserve
+its destination version when appropriate. Feed calendars must already exist
+on the destination with their own configured URL. Calendar and booking modules,
+post collections, theme code and section definitions must be deployed before
+their associated content can be applied.
+
+Events with existing destination reservations and resources with active
+reservations cannot be overwritten through sync. Use the destination editor
+for those operational changes. Bookings and submissions created after review
+invalidate the plan; rollback also checks for activity before deleting items.
+
+## Automation, storage and limits
+
+- `--json` returns the existing `acms.cli/1` envelope; exit 4 denotes conflicts,
+  3 authentication/permission failures, 5 network/server failures, and 2 invalid
+  usage/input. Diagnostics and interactive prompts use stderr.
+- `--dry-run` on selection commands does not save selection changes. On a
+  normal plan it asks the server to validate without storing a plan; on apply
+  it displays the saved plan without uploading or applying. Publication and
+  rollback plans are also validated without storing them in dry-run mode.
+- `--cwd <project>` chooses the project workspace. Selection, baselines and
+  exported-plan references are stored under
+  `${ACMS_CONFIG_DIR:-~/.config/acms}/sync/<workspace-hash>/`, with private file
+  permissions. They are not committed into the project. Exported plan files
+  contain unpublished content and should be kept out of source control.
+- A workspace lock prevents simultaneous CLI commands from losing selections.
+  After a crashed CLI process, verify that the PID in the reported lock file
+  is no longer running before removing that file.
+- Protocol 1 supports up to 2,000 inventory items, an 8 MiB inventory, 200
+  selected operations per plan and 16 MiB per media object. Oversized inputs
+  fail explicitly; split selections where possible. The inventory is bounded
+  rather than silently truncated. This version hashes media during inventory
+  reads; large media libraries may need a future paginated/cached inventory.
+  Hosting-platform request, subrequest and CPU limits can impose lower practical
+  limits; local D1 tests do not establish a live Cloudflare account's limits.
+- Sync history lives on the destination; it is not part of portable content
+  backups. Sync does not promise a cross-resource transaction with object
+  storage. Keep normal off-site backups and test disaster recovery separately.
+
+There is no automatic deletion propagation, background two-way synchronization,
+stash command, automatic text merge, or full database transfer.

package/integration.mjs

@@ -87,6 +87,8 @@ const ROUTES = [
   ['/api/ai/clean', 'api/ai/clean.ts'],
   ['/api/ai/draft', 'api/ai/draft.ts'],
   ['/api/design', 'api/design/index.ts'],
+  ['/api/sync', 'api/sync/index.ts'],
+  ['/api/sync/media', 'api/sync/media.ts'],
   ['/api/design/keys', 'api/design/keys.ts'],
   ['/api/design/capabilities', 'api/design/capabilities.ts'],
   ['/api/design/media', 'api/design/media.ts'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acms-subir/core",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "publishConfig": {
     "access": "public"
   },

package/src/components/DesignAccess.tsx

@@ -12,6 +12,9 @@ const SCOPES: { key: string; label: string; hint: string }[] = [
   { key: 'design:publish', label: 'Publish design', hint: 'Makes the draft live for visitors. Only grant this to tools you trust' },
   { key: 'media:read', label: 'Read media', hint: 'Browse the media library' },
   { key: 'media:write', label: 'Upload media', hint: 'Add images to the media library' },
+  { key: 'sync:read', label: 'Read environment content', hint: 'Read portable content, media and sync history, including drafts' },
+  { key: 'sync:write', label: 'Stage environment transfers', hint: 'Create plans, upload assets and apply draft transfers; also needs Read environment content' },
+  { key: 'sync:publish', label: 'Apply live environment transfers', hint: 'Publish content and apply reviewed live or rollback plans; also needs both sync permissions above' },
 ];
 const DEFAULT_SCOPES = ['design:read', 'design:write-draft'];
 

package/src/components/ThemeSectionsEditor.tsx

@@ -12,7 +12,7 @@ import { defaultValue, fieldVisible, initialData, normalizeData, normalizeValue,
 
 // Pages tab of the Design screen: lay out a page from the active theme's
 // section registry (builtins + the theme's own sections). Edits stay local
-// autosave into the design draft (1.2s after the last edit) through
+// until Save draft stages them through
 // POST /api/design; nothing here publishes, and a page's own content is
 // never touched (switching a page back to "Page content" keeps its layout).
 
@@ -76,7 +76,7 @@ export function useDesignApi() {
     }
   }, []);
   useEffect(() => { void load(); }, [load]);
-  /** update local state after our own write (e.g. an autosave) without a refetch */
+  /** update local state after our own write (e.g. Save draft) without a refetch */
   const patch = useCallback((fn: (d: DesignApiState) => DesignApiState) => setData((d) => (d ? fn(d) : d)), []);
   return { data, error, loading, loadCount, reload: load, patch };
 }
@@ -196,8 +196,8 @@ export default function ThemeSectionsEditor({ api, activeTheme, unsplashEnabled,
     return next;
   });
 
-  // `base` is what the server holds (the staged draft); edits autosave into
-  // it. A real reload rehydrates everything; our own autosaves only move
+  // `base` is what the server holds (the staged draft). A real reload
+  // rehydrates everything; our own saves only move
   // `base` and the revision forward, so typing is never overwritten.
   const [base, setBase] = useState<SectionPages>({});
   const revRef = useRef(0);
@@ -222,9 +222,12 @@ export default function ThemeSectionsEditor({ api, activeTheme, unsplashEnabled,
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [loadCount]);
 
-  // click-to-edit from the preview
+  // Consume each preview click once. A save patches `data`; it must not
+  // replay an old click and close the section the user is editing now.
+  const appliedFocus = useRef<SectionFocus | null>(null);
   useEffect(() => {
-    if (!focus || !data) return;
+    if (!focus || !data || appliedFocus.current === focus) return;
+    appliedFocus.current = focus;
     if (data.pages.some((p) => p.id === focus.pageId)) setPageId(focus.pageId);
     setOpenId(focus.sectionId);
   }, [focus, data]);
@@ -265,40 +268,44 @@ export default function ThemeSectionsEditor({ api, activeTheme, unsplashEnabled,
     if (!res.ok) { setSaveError(await errorText(res, `Couldn't save (${res.status}).`)); return null; }
     return (await res.json()) as { revision: number };
   };
-  // autosave: stage into the design draft 1.2s after the last edit
+  // Save an explicit snapshot. Edits made while the request is in flight
+  // remain local and dirty; another save must never silently include them.
   const [saveState, setSaveState] = useState<'idle' | 'saving' | 'saved' | 'error'>('idle');
-  const saving$ = useRef(false);
+  const saveInFlight = useRef<Promise<void> | null>(null);
   const staleRef = useRef(false);
-  const autosave = async () => {
-    if (saving$.current) return;
-    saving$.current = true;
-    setSaveState('saving');
-    const snapshot = pagesRef.current;
-    try {
-      const out = await post({ operation: 'stage', revision: revRef.current, patch: { sectionPages: snapshot } });
-      if (!out) { setSaveState('error'); return; }
-      revRef.current = out.revision;
-      setBase(snapshot);
-      setSaveState('saved');
-      patch((d) => ({ ...d, revision: out.revision, draft: { ...(d.draft ?? {}), sectionPages: snapshot } }));
-      // the preview couldn't swap (new layout / mode change): reload it now
-      if (staleRef.current) { staleRef.current = false; onSaved?.(); }
-    } catch {
-      setSaveState('error');
-      setSaveError("Couldn't reach the server. Your edits are kept here and will save when you're back online.");
-    } finally {
-      saving$.current = false;
-    }
-  };
-  const autosaveRef = useRef(autosave);
-  autosaveRef.current = autosave;
   const pagesRef = useRef(pages);
   pagesRef.current = pages;
-  useEffect(() => {
-    if (!data || !dirty || conflict) return;
-    const t = setTimeout(() => void autosaveRef.current(), 1200);
-    return () => clearTimeout(t);
-  }, [pages, dirty, conflict, data, saveState]);
+  const saveDraft = (): Promise<void> => {
+    if (saveInFlight.current) return saveInFlight.current;
+    if (conflict || JSON.stringify(pagesRef.current) === JSON.stringify(baseRef.current)) return Promise.resolve();
+    const task = (async () => {
+      setSaveState('saving');
+      setSaveError('');
+      setFlash('');
+      const snapshot = pagesRef.current;
+      try {
+        const out = await post({ operation: 'stage', revision: revRef.current, patch: { sectionPages: snapshot } });
+        if (!out) { setSaveState('error'); return; }
+        revRef.current = out.revision;
+        // Flush callers need the acknowledged snapshot immediately, before
+        // React commits the state update (Publish must not lose the click).
+        baseRef.current = snapshot;
+        setBase(snapshot);
+        setSaveState('saved');
+        patch((d) => ({ ...d, revision: out.revision, draft: { ...(d.draft ?? {}), sectionPages: snapshot } }));
+        if (staleRef.current) { staleRef.current = false; onSaved?.(); }
+      } catch {
+        setSaveState('error');
+        setSaveError("Couldn't reach the server. Your edits are kept here. Try Save draft again when you're back online.");
+      } finally {
+        saveInFlight.current = null;
+      }
+    })();
+    saveInFlight.current = task;
+    return task;
+  };
+  const saveDraftRef = useRef(saveDraft);
+  saveDraftRef.current = saveDraft;
 
   // live preview: render the unsaved layout ~0.35s after you pause typing
   const liveSent = useRef('');
@@ -397,15 +404,16 @@ export default function ThemeSectionsEditor({ api, activeTheme, unsplashEnabled,
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [pages, lang, i18nInfo?.drafts]);
 
-  // ⌘Z / ⌘⇧Z (Ctrl+Y) while editing sections; rich text keeps its own undo
+  // Save from any section field; rich text keeps its own undo shortcuts.
   const rootRef = useRef<HTMLDivElement>(null);
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
       if (!(e.metaKey || e.ctrlKey) || !rootRef.current || rootRef.current.offsetParent === null) return;
       const t = e.target as HTMLElement | null;
-      if (t?.isContentEditable) return;
       if (t && t !== document.body && !rootRef.current.contains(t)) return;
       const k = e.key.toLowerCase();
+      if (k === 's') { e.preventDefault(); void saveDraftRef.current(); return; }
+      if (t?.isContentEditable) return;
       if (k === 'z' && !e.shiftKey) { e.preventDefault(); undo(); }
       else if ((k === 'z' && e.shiftKey) || k === 'y') { e.preventDefault(); redo(); }
     };
@@ -545,8 +553,7 @@ export default function ThemeSectionsEditor({ api, activeTheme, unsplashEnabled,
   };
   /** save now (the Save button, and before publishing/upgrading) */
   const flush = async (): Promise<boolean> => {
-    if (!dirty) return true;
-    await autosaveRef.current();
+    await saveDraftRef.current();
     return JSON.stringify(pagesRef.current) === JSON.stringify(baseRef.current);
   };
   if (flushRef) flushRef.current = flush;
@@ -633,13 +640,13 @@ export default function ThemeSectionsEditor({ api, activeTheme, unsplashEnabled,
     <div className="te" ref={rootRef}>
       <p className="te-intro">
         Build a page from your theme's sections. Sections marked <b>coded</b> come from your theme's code: their look
-        changes in code, their content changes here. Edits save to a private draft as you type; visitors see them after you <b>Publish</b>.
+        changes in code, their content changes here. Click <b>Save draft</b> to keep your edits; visitors see them after you <b>Publish</b>.
       </p>
       <details className="te-help-panel">
         <summary>How editing works</summary>
         <ul>
           <li><b>Click anything in the preview</b> to open its section here. The preview updates as you type.</li>
-          <li><b>Your changes save themselves</b> to a draft. Undo with ⌘Z (Ctrl+Z), redo with ⌘⇧Z.</li>
+          <li><b>Save draft</b> (⌘S / Ctrl+S) keeps your changes without publishing them. Undo with ⌘Z (Ctrl+Z), redo with ⌘⇧Z.</li>
           <li><b>Publish</b> (top of this screen) makes every change live. <b>Publish this section</b> sends just one section and leaves the rest in the draft.</li>
           <li><b>Linked</b> sections (like upcoming events) fill themselves from your calendar or posts, so there's nothing to update here.</li>
           <li>Fields marked in red need fixing before that section can be published.</li>
@@ -788,7 +795,7 @@ export default function ThemeSectionsEditor({ api, activeTheme, unsplashEnabled,
                                 {s.variant !== 'default' && s.variant}
                                 {s.hidden && ' · hidden'}
                                 {!def && ' · unavailable'}
-                                {unsaved && ' · saving'}
+                                {unsaved && (saveState === 'saving' ? ' · saving' : ' · unsaved')}
                                 {(s.showFrom || s.showUntil) && ' · scheduled'}
                               </span>
                               {issueCount > 0 && <span className="te-issue-mark">{issueCount} to fix</span>}
@@ -977,13 +984,13 @@ export default function ThemeSectionsEditor({ api, activeTheme, unsplashEnabled,
       {saveError && <p className="flash error te-alert" role="alert">{saveError}</p>}
 
       <div className="te-savebar">
-        <span className={`te-savestate ${saveState === 'error' ? 'is-dirty' : ''}`} aria-live="polite">
-          {flash || (saveState === 'error' ? 'Not saved yet' : dirty || saveState === 'saving' ? 'Saving draft…' : saveState === 'saved' ? 'Draft saved · publish when ready' : 'All changes saved')}
+        <span className={`te-savestate ${dirty || saveState === 'error' ? 'is-dirty' : ''}`} aria-live="polite">
+          {flash || (saveState === 'error' ? 'Not saved yet' : saveState === 'saving' ? 'Saving draft…' : dirty ? 'Unsaved changes' : saveState === 'saved' ? 'Draft saved · publish when ready' : 'All changes saved')}
           {totalIssues > 0 && <> · <button type="button" className="te-issue-link" onClick={() => setOpenId(firstIssueId)}>{totalIssues} {totalIssues === 1 ? 'field needs' : 'fields need'} fixing before publishing</button></>}
         </span>
         <button className="btn sm ghost" type="button" onClick={undo} disabled={!past.current.length} title="Undo (⌘Z)">Undo</button>
         <button className="btn sm ghost" type="button" onClick={redo} disabled={!future.current.length} title="Redo (⌘⇧Z)">Redo</button>
-        {saveState === 'error' && <button className="btn sm" type="button" onClick={() => void autosaveRef.current()} disabled={conflict}>Try saving again</button>}
+        <button className="btn sm primary" type="button" onClick={() => void saveDraftRef.current()} disabled={!dirty || saveState === 'saving' || saving || conflict}>{saveState === 'saving' ? 'Saving…' : 'Save draft'}</button>
       </div>
 
       <ImagePicker

package/src/lib/repo/migrations.ts

@@ -7,6 +7,7 @@ import { EDITOR_MIGRATION, EDITOR_GRACE_MIGRATION } from '../editor/migration';
 import { CALENDAR_SETTINGS_MIGRATION, ROOM_HOLD_MIGRATION } from '../calendar/migration';
 import { PLACES_MIGRATION } from '../maps/migration';
 import { ROLES_MIGRATION } from '../permissions/migration';
+import { SYNC_MIGRATION } from '../sync/migration';
 // Versioned schema migrations shared by the two SQLite-dialect adapters
 // (D1 and libSQL). Applied versions are recorded in the `migrations` table;
 // each adapter's runner applies whatever is newer, in order, at startup.
@@ -632,6 +633,7 @@ export const MIGRATIONS: Migration[] = [
     `INSERT INTO backup_state (id) VALUES (1)`,
   ] },
   ROLES_MIGRATION,
+  SYNC_MIGRATION,
 ];
 
 export const LATEST_VERSION = MIGRATIONS[MIGRATIONS.length - 1].version;

package/src/lib/repo/sql.ts

@@ -1,4 +1,5 @@
 import { AUTH } from '../auth/config';
+import { SyncStore } from '../sync/store';
 import { AuthStore } from '../auth/store';
 import { FormStore, formInsert, submissionInsert } from '../forms/store';
 import { GuestStore } from '../mobile/guest-store';
@@ -260,6 +261,7 @@ function safeSnippet(raw: unknown): string {
 }
 
 export class SqlRepository implements ContentRepository {
+  readonly sync: SyncStore;
   private driver!: SqlDriver;
   private ready: Promise<void>;
   readonly auth: AuthStore;
@@ -274,6 +276,7 @@ export class SqlRepository implements ContentRepository {
 
   constructor(driver: SqlDriver | (() => Promise<SqlDriver>)) {
     this.ready = this.init(driver);
+    this.sync = new SyncStore(async () => { await this.ready; return this.driver; });
     this.forms = new FormStore(async () => { await this.ready; return this.driver; });
     this.guests = new GuestStore(async () => { await this.ready; return this.driver; });
     this.live = new LiveStore(async () => { await this.ready; return this.driver; });

package/src/lib/repo/types.ts

@@ -1,4 +1,5 @@
 import { AuthStore } from '../auth/store';
+import type { SyncStore } from '../sync/store';
 import type { FormStore } from '../forms/store';
 import type { BackupStore } from '../backup/store';
 import type { GuestStore } from '../mobile/guest-store';
@@ -53,6 +54,7 @@ export type EventUpdate = Partial<
 // The single contract both backends implement. The app only ever imports
 // this — never a concrete adapter.
 export interface ContentRepository {
+  readonly sync: SyncStore;
   readonly auth: AuthStore;
   readonly email: EmailStore;
   readonly forms: FormStore;

package/src/lib/schema.ts

@@ -637,6 +637,7 @@ export const API_SCOPES = [
   'bookings:read', 'bookings:write',
   'resources:read', 'resources:write',
   'design:read', 'design:write-draft', 'design:publish', 'media:read', 'media:write',
+  'sync:read', 'sync:write', 'sync:publish',
 ] as const;
 export const ApiScope = z.enum(API_SCOPES);
 export type ApiScope = z.infer<typeof ApiScope>;

package/src/lib/sync/auth.ts

@@ -0,0 +1,24 @@
+import { ApiError } from "../api";
+import { hashAgentKey } from "../ai-config";
+import type { ContentRepository } from "../repo/types";
+export const SYNC_SCOPES = ["sync:read", "sync:write", "sync:publish"] as const;
+export async function syncIdentity(
+  request: Request,
+  repo: ContentRepository,
+  required: readonly string[],
+) {
+  const origin = request.headers.get("origin");
+  if (
+    request.headers.get("sec-fetch-site") === "cross-site" ||
+    (origin && origin !== new URL(request.url).origin)
+  )
+    throw new ApiError(403, "Cross-origin sync requests are not allowed.");
+  const header = request.headers.get("authorization") ?? "";
+  if (!header.startsWith("Bearer "))
+    throw new ApiError(401, "Use a scoped sync key.");
+  const key = await repo.findApiKeyByHash(hashAgentKey(header.slice(7)));
+  if (!key) throw new ApiError(401, "Invalid sync key.");
+  if (required.some((s) => !key.scopes.includes(s as any)))
+    throw new ApiError(403, `Required scopes: ${required.join(", ")}`);
+  return { actor: `key:${key.id}`, scopes: key.scopes };
+}