@next-buildr/editor 0.0.0-stage → 2.0.1

package/dist/persistence/persistence.test.js

@@ -0,0 +1,483 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// @vitest-environment jsdom
+import { createRegistryMeta, createSeededIdGenerator, } from '@next-buildr/core';
+import { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { MessagesProvider } from '../messages/index.js';
+import { createEditorStore, EditorStoreProvider } from '../store/index.js';
+import { ToastProvider } from '../ui/index.js';
+import { createPersistence, EXTERNAL_CHECK_INTERVAL_MS, RETRY_DELAYS_MS, } from './controller.js';
+import { LoadError, loadDocument } from './load.js';
+import { PersistenceProvider, SaveStatus, useSaveAction } from './react.js';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const item = {
+    type: 'buildr/item',
+    version: 1,
+    label: 'Item',
+    category: 'content',
+    props: {},
+    contentCategories: ['flow'],
+    styles: { groups: [] },
+    runtime: 'shared',
+    slots: { default: {} },
+};
+const page = {
+    ...item,
+    type: 'buildr/page',
+    label: 'Page',
+    capabilities: { root: true },
+};
+const registryMeta = createRegistryMeta({ components: [page, item] });
+const fixture = () => ({
+    schemaVersion: 1,
+    root: 'root',
+    nodes: {
+        root: { id: 'root', type: 'buildr/page', slots: { default: ['itemAAAAA1', 'itemBBBBB1'] } },
+        itemAAAAA1: { id: 'itemAAAAA1', type: 'buildr/item' },
+        itemBBBBB1: { id: 'itemBBBBB1', type: 'buildr/item' },
+    },
+    components: {},
+});
+const ref = { collection: 'pages', id: '1' };
+function fakeAdapter() {
+    const saves = [];
+    let revision = 1;
+    const fake = {
+        saves,
+        next: () => ({ ok: true, revision: ++revision, updatedAt: `t${revision}` }),
+        loaded: {
+            title: 'Home',
+            status: 'draft',
+            updatedAt: 't1',
+            revision: 5,
+            document: fixture(),
+        },
+        canEdit: true,
+        remote: { revision: 1 },
+        revisionCalls: 0,
+        adapter: {
+            getRevision: async () => {
+                fake.revisionCalls += 1;
+                return { updatedAt: 't', ...fake.remote };
+            },
+            getSession: async () => ({ canEdit: fake.canEdit, canPublish: false }),
+            load: async () => fake.loaded,
+            save: async (_ref, request) => {
+                saves.push(request);
+                return fake.next(request);
+            },
+            publish: async () => ({ ok: true, revision: 1, updatedAt: 't' }),
+            getDataSchema: async () => ({ scopes: {}, entities: {} }),
+            getContext: async () => {
+                throw new Error('unused');
+            },
+            media: { search: async () => ({ items: [] }) },
+            previewUrl: () => '/preview',
+        },
+    };
+    return fake;
+}
+function setup(fake = fakeAdapter(), revision = 1, extra = {}) {
+    const store = createEditorStore({
+        doc: fixture(),
+        registry: registryMeta,
+        generateId: createSeededIdGenerator(9),
+        validationDelayMs: null,
+    });
+    const controller = createPersistence({
+        store,
+        adapter: fake.adapter,
+        ref,
+        revision,
+        debounceMs: 2000,
+        maxWaitMs: 20_000,
+        ...extra,
+    });
+    const stop = controller.start();
+    return { fake, store, controller, stop };
+}
+let counter = 0;
+const edit = (store, id = 'itemAAAAA1') => act(() => {
+    counter += 1;
+    store.dispatch({
+        type: 'node.setAttr',
+        payload: { id, key: 'name', value: `v${counter}` },
+    });
+});
+const advance = (ms) => act(async () => vi.advanceTimersByTimeAsync(ms));
+const status = (c) => c.state.getState().status;
+beforeEach(() => vi.useFakeTimers());
+afterEach(() => vi.useRealTimers());
+describe('autosave', () => {
+    it('is clean until something changes, then saves after the debounce', async () => {
+        const { fake, store, controller } = setup();
+        expect(status(controller)).toBe('clean');
+        edit(store);
+        expect(status(controller)).toBe('dirty');
+        await advance(1999);
+        expect(fake.saves).toHaveLength(0);
+        await advance(1);
+        expect(fake.saves).toHaveLength(1);
+        expect(fake.saves[0]).toMatchObject({ baseRevision: 1, autosave: true });
+        expect(status(controller)).toBe('clean');
+        expect(controller.state.getState().revision).toBe(2);
+        expect(store.getState().savedCursorId).toBe(store.getState().cursorId);
+    });
+    it('restarts the debounce with every change but saves at the max wait', async () => {
+        const { fake, store } = setup();
+        for (let i = 0; i < 12; i++) {
+            edit(store);
+            await advance(1900);
+        }
+        // 12 x 1.9 s of typing without a 2 s pause: the max wait (20 s) forced one save.
+        expect(fake.saves).toHaveLength(1);
+    });
+    it('is clean again after undoing back to the saved state', async () => {
+        const { fake, store, controller } = setup();
+        edit(store);
+        expect(status(controller)).toBe('dirty');
+        act(() => {
+            store.undo();
+        });
+        expect(status(controller)).toBe('clean');
+        await advance(30_000);
+        expect(fake.saves).toHaveLength(0);
+    });
+    it('runs one save at a time and saves what changed meanwhile afterwards', async () => {
+        const fake = fakeAdapter();
+        let release = () => undefined;
+        fake.next = () => new Promise((resolve) => (release = resolve));
+        const { store, controller } = setup(fake);
+        edit(store);
+        await advance(2000);
+        expect(status(controller)).toBe('saving');
+        edit(store, 'itemBBBBB1');
+        await advance(30_000);
+        expect(fake.saves).toHaveLength(1); // nothing overlaps
+        fake.next = () => ({ ok: true, revision: 3, updatedAt: 't3' });
+        await act(async () => release({ ok: true, revision: 2, updatedAt: 't2' }));
+        expect(status(controller)).toBe('dirty');
+        await advance(2000);
+        expect(fake.saves).toHaveLength(2);
+        expect(fake.saves[1]?.baseRevision).toBe(2);
+        expect(status(controller)).toBe('clean');
+    });
+    it('saves at once on request, without autosave', async () => {
+        const { fake, store, controller } = setup();
+        edit(store);
+        await act(async () => controller.saveNow());
+        expect(fake.saves).toHaveLength(1);
+        expect(fake.saves[0]?.autosave).toBe(false);
+        await act(async () => controller.saveNow()); // nothing to save
+        expect(fake.saves).toHaveLength(1);
+    });
+    it('does not save a read-only document', async () => {
+        const { fake, store, controller } = setup();
+        edit(store);
+        store.setReadOnly(true);
+        await act(async () => controller.saveNow());
+        await advance(30_000);
+        expect(fake.saves).toHaveLength(0);
+    });
+    it('stops for good when stopped', async () => {
+        const { fake, store, stop } = setup();
+        edit(store);
+        stop();
+        await advance(60_000);
+        expect(fake.saves).toHaveLength(0);
+    });
+});
+describe('failures', () => {
+    it('retries after a network error with growing delays and stays dirty', async () => {
+        const fake = fakeAdapter();
+        fake.next = () => Promise.reject(new Error('offline'));
+        const { store, controller } = setup(fake);
+        edit(store);
+        await advance(2000);
+        expect(status(controller)).toBe('error');
+        expect(controller.state.getState().error).toMatchObject({ kind: 'network', attempt: 1 });
+        expect(controller.hasUnsavedWork()).toBe(true);
+        await advance((RETRY_DELAYS_MS[0] ?? 0) - 1);
+        expect(fake.saves).toHaveLength(1);
+        await advance(1);
+        expect(fake.saves).toHaveLength(2);
+        await advance(RETRY_DELAYS_MS[1] ?? 0);
+        expect(fake.saves).toHaveLength(3);
+        await advance(RETRY_DELAYS_MS[2] ?? 0);
+        expect(fake.saves).toHaveLength(4);
+        fake.next = () => ({ ok: true, revision: 2, updatedAt: 't2' });
+        await advance(RETRY_DELAYS_MS[2] ?? 0);
+        expect(status(controller)).toBe('clean');
+        expect(controller.state.getState().error).toBeUndefined();
+    });
+    it('treats a malformed reply as a failed save', async () => {
+        const fake = fakeAdapter();
+        fake.next = () => ({ nope: true });
+        const { store, controller } = setup(fake);
+        edit(store);
+        await advance(2000);
+        expect(status(controller)).toBe('error');
+        expect(store.getState().savedCursorId).not.toBe(store.getState().cursorId);
+    });
+    it('does not retry a rejected document, and a change tries it again', async () => {
+        const fake = fakeAdapter();
+        fake.next = () => ({
+            ok: false,
+            kind: 'invalid',
+            diagnostics: [{ code: 'x', message: 'bad', severity: 'error' }],
+        });
+        const { store, controller } = setup(fake);
+        edit(store);
+        await advance(2000);
+        expect(controller.state.getState().error?.kind).toBe('invalid');
+        await advance(60_000);
+        expect(fake.saves).toHaveLength(1);
+        edit(store);
+        expect(status(controller)).toBe('dirty');
+        await advance(2000);
+        expect(fake.saves).toHaveLength(2);
+    });
+});
+describe('conflicts', () => {
+    const conflict = () => ({ ok: false, kind: 'conflict', currentRevision: 9 });
+    it('stops saving and keeps the local work', async () => {
+        const fake = fakeAdapter();
+        fake.next = conflict;
+        const { store, controller } = setup(fake);
+        edit(store);
+        await advance(2000);
+        expect(status(controller)).toBe('conflict');
+        expect(controller.state.getState().conflictRevision).toBe(9);
+        edit(store);
+        await advance(60_000);
+        expect(fake.saves).toHaveLength(1);
+        expect(controller.hasUnsavedWork()).toBe(true);
+    });
+    it('overwrites on the revision the backend has', async () => {
+        const fake = fakeAdapter();
+        fake.next = conflict;
+        const { store, controller } = setup(fake);
+        edit(store);
+        await advance(2000);
+        fake.next = () => ({ ok: true, revision: 10, updatedAt: 't10' });
+        await act(async () => controller.overwrite());
+        expect(fake.saves[1]?.baseRevision).toBe(9);
+        expect(status(controller)).toBe('clean');
+        expect(controller.state.getState().revision).toBe(10);
+    });
+    it('reloads the backend document and drops the local changes', async () => {
+        const fake = fakeAdapter();
+        fake.next = conflict;
+        const { store, controller } = setup(fake);
+        edit(store);
+        await advance(2000);
+        const theirs = fixture();
+        const nodes = theirs.nodes;
+        delete nodes['itemBBBBB1'];
+        nodes['root'] = { id: 'root', type: 'buildr/page', slots: { default: ['itemAAAAA1'] } };
+        fake.loaded = { ...fake.loaded, revision: 9, document: theirs };
+        await act(async () => controller.reload());
+        expect(status(controller)).toBe('clean');
+        expect(controller.state.getState().revision).toBe(9);
+        expect(Object.keys(store.getState().doc.nodes).sort()).toEqual(['itemAAAAA1', 'root']);
+        expect(controller.hasUnsavedWork()).toBe(false);
+    });
+});
+describe('external changes', () => {
+    it('offers a reload when somebody saved and the document is unchanged', async () => {
+        const { fake, controller } = setup();
+        await advance(EXTERNAL_CHECK_INTERVAL_MS - 1);
+        expect(fake.revisionCalls).toBe(0);
+        await advance(1);
+        expect(fake.revisionCalls).toBe(1);
+        expect(controller.state.getState().external).toBeUndefined();
+        fake.remote = { revision: 2, updatedBy: 'agent@example.com' };
+        await advance(EXTERNAL_CHECK_INTERVAL_MS);
+        expect(controller.state.getState().external).toEqual({
+            revision: 2,
+            updatedBy: 'agent@example.com',
+        });
+        expect(status(controller)).toBe('clean');
+        fake.loaded = { ...fake.loaded, revision: 2 };
+        await act(async () => controller.reload());
+        expect(controller.state.getState()).toMatchObject({ revision: 2, external: undefined });
+    });
+    it('turns local edits after a seen external save into an immediate conflict', async () => {
+        const { fake, store, controller } = setup();
+        fake.remote = { revision: 4 };
+        await advance(EXTERNAL_CHECK_INTERVAL_MS);
+        expect(controller.state.getState().external?.revision).toBe(4);
+        edit(store);
+        expect(status(controller)).toBe('conflict');
+        expect(controller.state.getState().conflictRevision).toBe(4);
+        expect(fake.saves).toHaveLength(0);
+        // Overwrite builds on the revision that was seen, so it needs no second round trip.
+        await act(async () => controller.overwrite());
+        expect(fake.saves[0]).toMatchObject({ baseRevision: 4 });
+        expect(status(controller)).toBe('clean');
+    });
+    it('finds a save made elsewhere while dirty before the autosave is refused', async () => {
+        const { fake, store, controller } = setup(fakeAdapter(), 1, {
+            debounceMs: 60_000,
+            maxWaitMs: 90_000,
+        });
+        edit(store);
+        fake.remote = { revision: 5 };
+        await advance(EXTERNAL_CHECK_INTERVAL_MS);
+        expect(status(controller)).toBe('conflict');
+        expect(controller.state.getState().conflictRevision).toBe(5);
+        expect(fake.saves).toHaveLength(0);
+    });
+    it('does not poll while the tab is hidden, and checks on demand when it is shown again', async () => {
+        let visible = false;
+        const { fake, controller } = setup(fakeAdapter(), 1, { isVisible: () => visible });
+        await advance(EXTERNAL_CHECK_INTERVAL_MS * 3);
+        expect(fake.revisionCalls).toBe(0);
+        visible = true;
+        fake.remote = { revision: 2 };
+        await act(async () => controller.checkExternal());
+        expect(fake.revisionCalls).toBe(1);
+        expect(controller.state.getState().external?.revision).toBe(2);
+    });
+    it('stops polling when stopped, ignores failures, and needs getRevision', async () => {
+        const fake = fakeAdapter();
+        const { controller, stop } = setup(fake);
+        fake.adapter.getRevision = async () => {
+            fake.revisionCalls += 1;
+            throw new Error('offline');
+        };
+        await advance(EXTERNAL_CHECK_INTERVAL_MS);
+        expect(fake.revisionCalls).toBe(1);
+        expect(status(controller)).toBe('clean');
+        expect(controller.state.getState().external).toBeUndefined();
+        stop();
+        await advance(EXTERNAL_CHECK_INTERVAL_MS * 3);
+        expect(fake.revisionCalls).toBe(1);
+        const bare = fakeAdapter();
+        delete bare.adapter.getRevision;
+        const other = setup(bare);
+        await advance(EXTERNAL_CHECK_INTERVAL_MS * 2);
+        await other.controller.checkExternal();
+        expect(bare.revisionCalls).toBe(0);
+    });
+    it('ignores an answer that a save overtook', async () => {
+        const fake = fakeAdapter();
+        const { store, controller } = setup(fake);
+        let release = () => undefined;
+        fake.adapter.getRevision = () => new Promise((resolve) => {
+            release = () => resolve({ revision: 2, updatedAt: 't' });
+        });
+        const pending = controller.checkExternal();
+        edit(store);
+        await advance(2000);
+        expect(controller.state.getState().revision).toBe(2);
+        release();
+        await act(async () => pending);
+        expect(controller.state.getState().external).toBeUndefined();
+        expect(status(controller)).toBe('clean');
+    });
+});
+describe('loadDocument', () => {
+    it('returns the validated document', async () => {
+        const fake = fakeAdapter();
+        const loaded = await loadDocument(fake.adapter, ref);
+        expect(loaded.revision).toBe(5);
+        expect(loaded.readOnly).toBe(false);
+    });
+    it('keeps the context the canvas binds against by default', async () => {
+        const fake = fakeAdapter();
+        fake.loaded = { ...fake.loaded, contextRef: 'pages:7' };
+        expect((await loadDocument(fake.adapter, ref)).contextRef).toBe('pages:7');
+    });
+    it('opens a document read-only when the session cannot edit or the backend says so', async () => {
+        const fake = fakeAdapter();
+        fake.canEdit = false;
+        expect((await loadDocument(fake.adapter, ref)).readOnly).toBe(true);
+        fake.canEdit = true;
+        fake.loaded = { ...fake.loaded, readOnly: true };
+        expect((await loadDocument(fake.adapter, ref)).readOnly).toBe(true);
+    });
+    it('refuses malformed replies and invalid documents', async () => {
+        const fake = fakeAdapter();
+        fake.loaded = { title: 1 };
+        await expect(loadDocument(fake.adapter, ref)).rejects.toBeInstanceOf(LoadError);
+        fake.loaded = { ...fakeAdapter().loaded, document: { nope: true } };
+        await expect(loadDocument(fake.adapter, ref)).rejects.toBeInstanceOf(LoadError);
+    });
+});
+describe('PersistenceProvider', () => {
+    let container;
+    let root;
+    let saveAction;
+    function Probe() {
+        saveAction = useSaveAction();
+        return _jsx(SaveStatus, {});
+    }
+    async function mount(fake) {
+        const { store, controller } = setup(fake);
+        await act(async () => root.render(_jsx(MessagesProvider, { locale: "en", children: _jsx(ToastProvider, { children: _jsx(EditorStoreProvider, { store: store, children: _jsx(PersistenceProvider, { controller: controller, children: _jsx(Probe, {}) }) }) }) })));
+        return { store, controller };
+    }
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.append(container);
+        root = createRoot(container);
+    });
+    afterEach(() => {
+        act(() => root.unmount());
+        document.body.innerHTML = '';
+    });
+    it('shows the status and saves on the save action', async () => {
+        const fake = fakeAdapter();
+        const { store } = await mount(fake);
+        expect(container.textContent).toContain('All changes saved');
+        edit(store);
+        expect(container.textContent).toContain('Unsaved changes');
+        await act(async () => {
+            expect(saveAction()).toBe(true);
+        });
+        expect(fake.saves).toHaveLength(1);
+        expect(container.textContent).toContain('All changes saved');
+    });
+    it('warns before the tab closes while there is unsaved work', async () => {
+        const fake = fakeAdapter();
+        const { store } = await mount(fake);
+        const clean = new Event('beforeunload', { cancelable: true });
+        window.dispatchEvent(clean);
+        expect(clean.defaultPrevented).toBe(false);
+        edit(store);
+        const dirty = new Event('beforeunload', { cancelable: true });
+        window.dispatchEvent(dirty);
+        expect(dirty.defaultPrevented).toBe(true);
+    });
+    it('announces who saved in the toast region, and reloads from it', async () => {
+        const fake = fakeAdapter();
+        const { controller } = await mount(fake);
+        const banner = () => container.ownerDocument.querySelector('.bd-toast-region [role=status]');
+        expect(banner()?.textContent).toBe('');
+        fake.remote = { revision: 2, updatedBy: 'Claude agent' };
+        fake.loaded = { ...fake.loaded, revision: 2 };
+        await act(async () => window.dispatchEvent(new Event('focus')));
+        expect(banner()?.textContent).toContain('Claude agent saved a newer version');
+        const reload = banner()?.querySelector('button');
+        expect(reload?.textContent).toBe('Reload the latest version');
+        await act(async () => reload?.click());
+        expect(banner()?.textContent).toBe('');
+        expect(controller.state.getState().revision).toBe(2);
+    });
+    it('asks the author to choose in a conflict', async () => {
+        const fake = fakeAdapter();
+        fake.next = () => ({ ok: false, kind: 'conflict', currentRevision: 9 });
+        const { store, controller } = await mount(fake);
+        edit(store);
+        await advance(2000);
+        const dialog = document.querySelector('[role=dialog]');
+        expect(dialog?.textContent).toContain('This page was changed elsewhere');
+        fake.next = () => ({ ok: true, revision: 10, updatedAt: 't10' });
+        const overwrite = [...(dialog?.querySelectorAll('button') ?? [])].find((b) => b.textContent?.includes('Overwrite'));
+        await act(async () => overwrite?.click());
+        expect(status(controller)).toBe('clean');
+        expect(document.querySelector('[role=dialog]')).toBeNull();
+    });
+});

package/dist/persistence/react.d.ts

@@ -0,0 +1,18 @@
+import { type ReactNode } from 'react';
+import type { PersistenceController } from './controller.ts';
+import type { PersistenceState } from './types.ts';
+export declare function usePersistence(): PersistenceController;
+export declare function usePersistenceState<T>(selector: (state: PersistenceState) => T): T;
+/**
+ * Runs the autosave of `controller`, warns before the tab is closed while work would be lost, and
+ * shows the conflict dialog. `useSaveAction` gives the handler for the Ctrl+S shortcut.
+ */
+export declare function PersistenceProvider(props: {
+    readonly controller: PersistenceController;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;
+/** For `<ShortcutProvider actions={{ save }}>`: Ctrl+S saves now and takes the key from the browser. */
+export declare function useSaveAction(): () => boolean;
+/** A short status line for the toolbar (PB-083): saved, unsaved, saving, failed, conflict. */
+export declare function SaveStatus(): import("react").JSX.Element;
+//# sourceMappingURL=react.d.ts.map

package/dist/persistence/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/persistence/react.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAyB,MAAM,OAAO,CAAC;AAK7E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInD,wBAAgB,cAAc,IAAI,qBAAqB,CAMtD;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,CAAC,GAAG,CAAC,CAElF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B,+BA8BA;AAED,wGAAwG;AACxG,wBAAgB,aAAa,IAAI,MAAM,OAAO,CAM7C;AAwDD,8FAA8F;AAC9F,wBAAgB,UAAU,gCAqBzB"}

package/dist/persistence/react.js

@@ -0,0 +1,105 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useEffect } from 'react';
+import { useStore } from 'zustand';
+import { useT } from '../messages/index.js';
+import { useEditorState } from '../store/index.js';
+import { Button, Dialog, useToast } from '../ui/index.js';
+const PersistenceContext = createContext(undefined);
+export function usePersistence() {
+    const controller = useContext(PersistenceContext);
+    if (controller === undefined) {
+        throw new Error('usePersistence must be used inside <PersistenceProvider>');
+    }
+    return controller;
+}
+export function usePersistenceState(selector) {
+    return useStore(usePersistence().state, selector);
+}
+/**
+ * Runs the autosave of `controller`, warns before the tab is closed while work would be lost, and
+ * shows the conflict dialog. `useSaveAction` gives the handler for the Ctrl+S shortcut.
+ */
+export function PersistenceProvider(props) {
+    const { controller, children } = props;
+    useEffect(() => controller.start(), [controller]);
+    useEffect(() => {
+        const warn = (event) => {
+            if (!controller.hasUnsavedWork())
+                return;
+            event.preventDefault();
+            // Some browsers still want a return value to show their prompt.
+            event.returnValue = '';
+        };
+        window.addEventListener('beforeunload', warn);
+        return () => window.removeEventListener('beforeunload', warn);
+    }, [controller]);
+    useEffect(() => {
+        // Coming back to the tab or window is when somebody else's save is most likely to matter.
+        const check = () => void controller.checkExternal();
+        window.addEventListener('focus', check);
+        document.addEventListener('visibilitychange', check);
+        return () => {
+            window.removeEventListener('focus', check);
+            document.removeEventListener('visibilitychange', check);
+        };
+    }, [controller]);
+    return (_jsxs(PersistenceContext.Provider, { value: controller, children: [children, _jsx(ExternalChangeBanner, {}), _jsx(ConflictDialog, {})] }));
+}
+/** For `<ShortcutProvider actions={{ save }}>`: Ctrl+S saves now and takes the key from the browser. */
+export function useSaveAction() {
+    const controller = usePersistence();
+    return () => {
+        void controller.saveNow();
+        return true;
+    };
+}
+/**
+ * A non-blocking notice, shown as a persistent toast, that somebody else saved while this document
+ * is unchanged: one click reloads. It goes away when the external change is gone.
+ */
+function ExternalChangeBanner() {
+    const t = useT();
+    const toast = useToast();
+    const controller = usePersistence();
+    const external = usePersistenceState((state) => state.external);
+    const updatedBy = external?.updatedBy;
+    const present = external !== undefined;
+    useEffect(() => {
+        if (!present) {
+            toast.dismiss('external-changes');
+            return;
+        }
+        toast.show({
+            id: 'external-changes',
+            variant: 'info',
+            duration: null,
+            message: updatedBy === undefined
+                ? t('external.banner')
+                : t('external.banner.by').replace('{name}', updatedBy),
+            action: { label: t('external.reload'), onSelect: () => void controller.reload() },
+        });
+    }, [present, updatedBy, toast, t, controller]);
+    return null;
+}
+function ConflictDialog() {
+    const t = useT();
+    const controller = usePersistence();
+    const status = usePersistenceState((state) => state.status);
+    return (_jsx(Dialog, { open: status === 'conflict', hideClose: true, 
+        // The choice is the only way out: closing without one would leave the editor stuck in conflict.
+        onOpenChange: () => undefined, title: t('save.conflict.title'), description: t('save.conflict.description'), footer: _jsxs(_Fragment, { children: [_jsx(Button, { onClick: () => void controller.reload(), children: t('save.conflict.reload') }), _jsx(Button, { variant: "danger", onClick: () => void controller.overwrite(), children: t('save.conflict.overwrite') })] }) }));
+}
+/** A short status line for the toolbar (PB-083): saved, unsaved, saving, failed, conflict. */
+export function SaveStatus() {
+    const t = useT();
+    const controller = usePersistence();
+    const status = usePersistenceState((state) => state.status);
+    const error = usePersistenceState((state) => state.error);
+    const readOnly = useEditorState((state) => state.readOnly);
+    const text = readOnly
+        ? t('save.readOnly')
+        : status === 'error' && error?.kind === 'invalid'
+            ? t('save.invalid')
+            : t(`save.${status}`);
+    return (_jsxs("span", { className: "bd-save-status", "data-status": readOnly ? 'readOnly' : status, role: "status", children: [text, !readOnly && (status === 'dirty' || status === 'error') && (_jsx(Button, { variant: "ghost", onClick: () => void controller.saveNow(), children: t('save.now') }))] }));
+}