@widgetic/editor 4.0.9 → 4.0.11

package/dist/composition/compositionEditorController.js

@@ -0,0 +1,734 @@
+/**
+ * The state and the behaviour of an embedded composition editor, with no user interface in it.
+ *
+ * It loads a composition and what is needed to edit it (the widget's preview address and its two schemas),
+ * keeps the values being edited, tells the preview page what changed, and saves: when asked, and by itself a
+ * moment after the last edit. A Svelte component draws it; a test can drive it with a fake API and fake timers.
+ *
+ * The rules that keep a customer's work safe live here:
+ *
+ *   - "Unsaved changes" is counted, not flagged. Every edit raises a revision; a save remembers the revision it
+ *     saved. An edit made while a save is on its way therefore stays unsaved when the save returns (the page
+ *     this was taken from cleared the flag and lost track of it).
+ *   - There is one save on the way at a time. A save asked for meanwhile waits for it, then saves what is new.
+ *   - What is sent is a copy taken when the save starts, so edits made while it travels cannot change it, and
+ *     sending it again after a 401 sends exactly the same thing.
+ *   - A save that fails leaves everything unsaved and says so. An autosave that fails because of the network or
+ *     the server is tried again a few times, further and further apart; a failure that retrying cannot fix
+ *     (the session ended, the field is refused) is not.
+ *   - The embed settings the composition already has (anything set by the site or by the partner's own backend)
+ *     are sent back with the new size, never replaced by it.
+ *   - The size that is saved is the one the user gave the preview (by dragging its corner or typing it in), and
+ *     nothing else. Looking at the preview as on a phone changes how it is drawn, not what is saved, and the
+ *     size a small box forces on the preview is not the user's choice, so it is never saved either (the page this
+ *     was taken from saved both, so opening a composition in a small window, or trying the mobile view, changed
+ *     the size of the widget embedded on a site).
+ *   - After `dispose()` nothing more happens: no request goes out, and answers still on their way are ignored.
+ */
+import { buildPropsEditorContentSchema, compositionWidgetId, contentItemsToEditorValueMap, ensureSubtitleFontInDesignSchema, extractContentItemsFromCompositionRaw, extractContentValuesFromCompositionRaw, flattenContentItemsForPreview, flattenDesignValuesForPreview, getCompositionEmbedSettings, mergeContentItemsWithSchema, mergeMissingContentValues, normalizeContentSchemaFromApiResponse, normalizeDesignSchemaFromApiResponse, parseEmbedDimension, seedMissingFontFaces } from './compositionHelpers.js';
+/** Time to wait after the last edit before saving by itself. */
+export const DEFAULT_AUTOSAVE_DELAY_MS = 2500;
+/** How long to wait before trying an autosave again after it failed for a reason that may pass: first, second, third time. */
+export const DEFAULT_AUTOSAVE_RETRY_DELAYS_MS = [5_000, 15_000, 45_000];
+export const DEFAULT_PREVIEW_WIDTH = 800;
+export const DEFAULT_PREVIEW_HEIGHT = 600;
+/** The size the preview is drawn at in its mobile view. */
+export const MOBILE_PREVIEW_WIDTH = 480;
+export const MOBILE_PREVIEW_HEIGHT = 600;
+/** The smallest size, in pixels, the preview can be given. */
+export const MIN_PREVIEW_SIZE = 50;
+/** Saving again and again while edits keep coming in must end: this many rounds at most when flushing. */
+const MAX_FLUSH_ROUNDS = 10;
+/**
+ * Whether `error` came from the API client. It is recognized by what it is called and carries, not by its class:
+ * a page that loads a second copy of the client makes errors a class check would not know.
+ */
+function isCompositionApiError(error) {
+    const candidate = error;
+    return (error instanceof Error &&
+        error.name === 'CompositionApiError' &&
+        typeof candidate?.code === 'string' &&
+        typeof candidate?.status === 'number');
+}
+/** What went wrong, from whatever was thrown. */
+export function describeFailure(error) {
+    if (isCompositionApiError(error)) {
+        return {
+            message: error.message,
+            code: error.code,
+            status: error.status,
+            retryable: error.retryable === true,
+            sessionEnded: error.sessionEnded === true,
+            correlationId: error.correlationId
+        };
+    }
+    return {
+        message: error instanceof Error && error.message ? error.message : 'Something went wrong.',
+        code: 'UNKNOWN',
+        status: 0,
+        retryable: false,
+        sessionEnded: false
+    };
+}
+/** A failure in words for the person using the editor. */
+export function failureMessage(failure, doing) {
+    if (failure.code === 'WIDGET_NOT_PUBLISHED')
+        return 'Publish the widget before editing a composition.';
+    if (failure.sessionEnded) {
+        return doing === 'save'
+            ? 'Your session has ended, so your changes could not be saved. Reload the page to continue.'
+            : 'Your session has ended. Reload the page to continue.';
+    }
+    if (failure.status === 404)
+        return 'This composition could not be found.';
+    if (failure.status === 403)
+        return 'You do not have access to this composition.';
+    if (failure.retryable) {
+        return doing === 'save'
+            ? 'Your changes could not be saved. Check the connection and try again.'
+            : 'The editor could not be loaded. Check the connection and try again.';
+    }
+    return (failure.message ||
+        (doing === 'save' ? 'Your changes could not be saved.' : 'The editor could not be loaded.'));
+}
+/** A refusal that makes every other answer worthless: the session is over, or it may not see this composition. */
+function refusesAccess(failure) {
+    return failure.sessionEnded || failure.status === 403;
+}
+/** Why there is no preview, in words for a person. */
+function previewFailureMessage(failure) {
+    if (failure.status === 404)
+        return 'The widget this composition is made with could not be found.';
+    return failureMessage(failure, 'load');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** What a request gave, or `null` when it failed. */
+function valueOf(result) {
+    return result.status === 'fulfilled' ? result.value : null;
+}
+/** Why a request failed, or `null` when it did not. */
+function failureOf(result) {
+    return result.status === 'rejected' ? describeFailure(result.reason) : null;
+}
+/** The content items the schema lists, wherever it keeps them. */
+function schemaContentItems(contentSchema) {
+    const items = contentSchema?.contentItems ?? contentSchema?.data?.contentItems;
+    return Array.isArray(items) ? items : [];
+}
+export class CompositionEditorController {
+    options;
+    timers;
+    now;
+    logger;
+    autosaveDelayMs;
+    autosaveRetryDelaysMs;
+    abortController = new AbortController();
+    stateListeners = new Set();
+    eventListeners = new Set();
+    state;
+    /** Counts the edits made. */
+    revision = 0;
+    /** The revision the last successful save took. */
+    savedRevision = 0;
+    /** How many autosaves in a row have failed. */
+    failedAutosaves = 0;
+    /** The embed settings the composition has, sent back with the size on every save. */
+    storedEmbedSettings = {};
+    autosaveTimer = null;
+    /** What `getPropsEditorContentSchema` and `getPropsEditorContentValues` last made, and from what. */
+    propsEditorSchemaCache = null;
+    propsEditorValuesCache = null;
+    loadPromise = null;
+    savePromise = null;
+    disposed = false;
+    constructor(options) {
+        if (typeof options?.compositionId !== 'string' || options.compositionId.trim() === '') {
+            throw new TypeError('CompositionEditorController needs a composition id');
+        }
+        if (!options.api)
+            throw new TypeError('CompositionEditorController needs an api');
+        this.options = options;
+        this.timers = options.timers ?? {
+            setTimeout: (callback, milliseconds) => setTimeout(callback, milliseconds),
+            clearTimeout: (handle) => clearTimeout(handle)
+        };
+        this.now = options.now ?? Date.now;
+        this.logger = options.logger ?? console;
+        this.autosaveDelayMs = options.autosaveDelayMs ?? DEFAULT_AUTOSAVE_DELAY_MS;
+        this.autosaveRetryDelaysMs = options.autosaveRetryDelaysMs ?? DEFAULT_AUTOSAVE_RETRY_DELAYS_MS;
+        this.state = {
+            phase: 'idle',
+            compositionId: options.compositionId,
+            name: 'Untitled Composition',
+            widgetId: '',
+            preview: null,
+            previewError: null,
+            designSchema: null,
+            contentSchema: null,
+            schemasLoading: false,
+            schemasError: null,
+            designValues: {},
+            contentValues: {},
+            contentItems: [],
+            previewWidth: DEFAULT_PREVIEW_WIDTH,
+            previewHeight: DEFAULT_PREVIEW_HEIGHT,
+            embedWidth: DEFAULT_PREVIEW_WIDTH,
+            embedHeight: DEFAULT_PREVIEW_HEIGHT,
+            deviceView: 'desktop',
+            dirty: false,
+            saving: false,
+            saveError: null,
+            loadError: null,
+            lastSavedAt: null
+        };
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Watching
+    // ---------------------------------------------------------------------------------------------
+    /** The state now. It is never changed in place: a change makes a new object. */
+    getState() {
+        return this.state;
+    }
+    /** Svelte store contract: calls `listener` with the state now, and again after every change. */
+    subscribe(listener) {
+        this.stateListeners.add(listener);
+        listener(this.state);
+        return () => {
+            this.stateListeners.delete(listener);
+        };
+    }
+    /** Calls `listener` with every event: `ready`, `dirty`, `saved`, `error`. */
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => {
+            this.eventListeners.delete(listener);
+        };
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Loading
+    // ---------------------------------------------------------------------------------------------
+    /** Loads the composition, its preview address and its schemas. Asking again while it loads waits for the same load. */
+    load() {
+        if (this.disposed)
+            return Promise.resolve();
+        if (this.loadPromise)
+            return this.loadPromise;
+        // (No other load can have taken its place: while this one is set, `load()` hands it out instead of starting one.)
+        const running = this.runLoad().finally(() => {
+            this.loadPromise = null;
+        });
+        this.loadPromise = running;
+        return running;
+    }
+    async runLoad() {
+        const { api, compositionId } = this.options;
+        const { signal } = this.abortController;
+        this.patch({
+            phase: 'loading',
+            loadError: null,
+            previewError: null,
+            schemasLoading: true,
+            schemasError: null
+        });
+        // None of the four needs another's answer, so they travel together.
+        const [compositionResult, previewResult, designResult, contentResult] = await Promise.allSettled([
+            api.getComposition(compositionId, { signal }),
+            api.getPreview(compositionId, { signal }),
+            api.getDesignSchema(compositionId, { signal }),
+            api.getContentSchema(compositionId, { signal })
+        ]);
+        if (this.disposed)
+            return;
+        // What stops the load: no composition, or a refusal that makes every other answer worthless.
+        if (compositionResult.status === 'rejected') {
+            this.failLoad(describeFailure(compositionResult.reason));
+            return;
+        }
+        const refusal = [previewResult, designResult, contentResult]
+            .map(failureOf)
+            .find((failure) => failure !== null && refusesAccess(failure));
+        if (refusal) {
+            this.failLoad(refusal);
+            return;
+        }
+        const composition = compositionResult.value;
+        const widgetId = compositionWidgetId(composition);
+        if (!widgetId) {
+            this.failLoad({
+                message: 'This composition has no widget.',
+                code: 'COMPOSITION_HAS_NO_WIDGET',
+                status: 0,
+                retryable: false,
+                sessionEnded: false
+            });
+            return;
+        }
+        // The preview: its absence is told in the preview's place; the settings can still be edited.
+        const previewInfo = valueOf(previewResult);
+        const previewFailure = failureOf(previewResult);
+        if (previewFailure) {
+            this.logger.warn('[CompositionEditor] The preview address could not be loaded:', previewFailure.code, previewFailure.message);
+        }
+        const preview = previewInfo
+            ? {
+                previewUrl: previewInfo.previewUrl,
+                widgetId: previewInfo.widgetId,
+                version: previewInfo.version
+            }
+            : null;
+        const schemas = this.readSchemas(designResult, contentResult);
+        // The values being edited: what the composition saved, with the schema's defaults for what it never saved.
+        const rawContent = (isRecord(composition.content) ? composition.content : {});
+        const designValues = seedMissingFontFaces((rawContent.design ?? composition.design ?? {}));
+        const contentValues = mergeMissingContentValues(extractContentValuesFromCompositionRaw(rawContent), schemas.contentSchema);
+        // (With no items in the schema, the items are the saved ones as they are.)
+        const contentItems = mergeContentItemsWithSchema(extractContentItemsFromCompositionRaw(rawContent), schemaContentItems(schemas.contentSchema));
+        this.storedEmbedSettings = getCompositionEmbedSettings(composition);
+        const embedWidth = parseEmbedDimension(this.storedEmbedSettings.width, DEFAULT_PREVIEW_WIDTH);
+        const embedHeight = parseEmbedDimension(this.storedEmbedSettings.height, DEFAULT_PREVIEW_HEIGHT);
+        this.revision = 0;
+        this.savedRevision = 0;
+        this.patch({
+            phase: 'ready',
+            name: String(composition.name || 'Untitled Composition'),
+            widgetId,
+            preview,
+            previewError: previewFailure ? previewFailureMessage(previewFailure) : null,
+            designSchema: schemas.designSchema,
+            contentSchema: schemas.contentSchema,
+            schemasLoading: false,
+            schemasError: schemas.schemasError,
+            designValues,
+            contentValues,
+            contentItems,
+            previewWidth: embedWidth,
+            previewHeight: embedHeight,
+            embedWidth,
+            embedHeight,
+            deviceView: 'desktop',
+            dirty: false,
+            saveError: null,
+            loadError: null
+        });
+        this.emit({ type: 'ready' });
+        this.reportMissingSchemas(schemas);
+    }
+    failLoad(failure) {
+        this.logger.error('[CompositionEditor] The composition could not be loaded:', failure.code, failure.message);
+        this.patch({ phase: 'failed', schemasLoading: false, loadError: failure });
+        this.emit({ type: 'error', during: 'load', failure, fatal: true });
+    }
+    /**
+     * Turns the answers for the two schemas into what the editor draws, and into words when there is nothing to draw.
+     * A schema whose request failed is the `previous` one when there is one (asking again must not lose what is there).
+     */
+    readSchemas(designResult, contentResult, previous) {
+        const designFailure = failureOf(designResult);
+        const contentFailure = failureOf(contentResult);
+        if (designFailure)
+            this.logger.warn('[CompositionEditor] The design schema could not be loaded:', designFailure.code, designFailure.message);
+        if (contentFailure)
+            this.logger.warn('[CompositionEditor] The content schema could not be loaded:', contentFailure.code, contentFailure.message);
+        // Either schema may be missing, but not both.
+        const designSchema = designFailure
+            ? (previous?.designSchema ?? null)
+            : ensureSubtitleFontInDesignSchema(normalizeDesignSchemaFromApiResponse(valueOf(designResult)));
+        const contentSchema = contentFailure
+            ? (previous?.contentSchema ?? null)
+            : normalizeContentSchemaFromApiResponse(valueOf(contentResult));
+        const failure = designFailure ?? contentFailure;
+        let schemasError = null;
+        if (!designSchema && !contentSchema) {
+            schemasError = failure
+                ? 'The editor settings could not be loaded. Try again.'
+                : 'No editable settings found. Generate and publish the widget first.';
+        }
+        return { designSchema, contentSchema, schemasError, failure };
+    }
+    /** Tells the watchers that there is nothing to edit, when that is so. */
+    reportMissingSchemas(schemas) {
+        if (!schemas.schemasError)
+            return;
+        this.emit({
+            type: 'error',
+            during: 'schemas',
+            failure: schemas.failure ?? {
+                message: schemas.schemasError,
+                code: 'NO_EDITABLE_SETTINGS',
+                status: 0,
+                retryable: false,
+                sessionEnded: false
+            },
+            fatal: false
+        });
+    }
+    /** Asks for the two schemas again (after they failed to load). Values already edited are kept. */
+    async reloadSchemas() {
+        if (this.disposed || this.state.phase !== 'ready')
+            return;
+        const { api, compositionId } = this.options;
+        const { signal } = this.abortController;
+        this.patch({ schemasLoading: true, schemasError: null });
+        const [designResult, contentResult] = await Promise.allSettled([
+            api.getDesignSchema(compositionId, { signal }),
+            api.getContentSchema(compositionId, { signal })
+        ]);
+        if (this.disposed)
+            return;
+        const schemas = this.readSchemas(designResult, contentResult, this.state);
+        // The defaults of the schema fill in what is missing; what is there (edited or saved) stays.
+        const itemsOfSchema = schemaContentItems(schemas.contentSchema);
+        this.patch({
+            designSchema: schemas.designSchema,
+            contentSchema: schemas.contentSchema,
+            schemasLoading: false,
+            schemasError: schemas.schemasError,
+            contentValues: mergeMissingContentValues(this.state.contentValues, schemas.contentSchema),
+            contentItems: itemsOfSchema.length > 0
+                ? mergeContentItemsWithSchema(this.state.contentItems, itemsOfSchema)
+                : this.state.contentItems
+        });
+        this.reportMissingSchemas(schemas);
+    }
+    // ---------------------------------------------------------------------------------------------
+    // What the props editor gets, and what the preview page is told
+    // ---------------------------------------------------------------------------------------------
+    /**
+     * The content schema the props editor draws: the widget's, with the composition's items merged into it.
+     * The same object comes back until the schema or the items change, so a component can hand it down without
+     * the props editor being told of a change that is none.
+     */
+    getPropsEditorContentSchema() {
+        const { contentSchema, contentItems } = this.state;
+        const cached = this.propsEditorSchemaCache;
+        if (cached && cached.contentSchema === contentSchema && cached.contentItems === contentItems)
+            return cached.result;
+        const result = buildPropsEditorContentSchema(contentSchema, contentItems);
+        this.propsEditorSchemaCache = { contentSchema, contentItems, result };
+        return result;
+    }
+    /** The values the props editor starts from: the content values, and the items by id. The same object comes back until they change. */
+    getPropsEditorContentValues() {
+        const { contentValues, contentItems } = this.state;
+        const cached = this.propsEditorValuesCache;
+        if (cached && cached.contentValues === contentValues && cached.contentItems === contentItems)
+            return cached.result;
+        const result = {
+            ...contentValues,
+            items: contentItemsToEditorValueMap(contentItems)
+        };
+        this.propsEditorValuesCache = { contentValues, contentItems, result };
+        return result;
+    }
+    /** Tells the preview page everything it needs to look like the composition (once its page has loaded). */
+    syncPreview() {
+        for (const message of this.buildPreviewSnapshot())
+            this.options.onPreviewMessage?.(message);
+    }
+    buildPreviewSnapshot() {
+        const { designValues, contentValues, contentItems } = this.state;
+        const messages = [];
+        if (Object.keys(designValues).length > 0) {
+            messages.push({
+                type: 'widgetic:update',
+                design: flattenDesignValuesForPreview(designValues)
+            });
+        }
+        if (Object.keys(contentValues).length > 0) {
+            messages.push({ type: 'widgetic:update', content: contentValues });
+        }
+        if (contentItems.length > 0) {
+            messages.push({
+                type: 'widgetic:update',
+                contentItems: flattenContentItemsForPreview(contentItems)
+            });
+        }
+        return messages;
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Editing
+    // ---------------------------------------------------------------------------------------------
+    /** One property was changed in the props editor. */
+    changeProperty(change) {
+        if (this.disposed || this.state.phase !== 'ready')
+            return;
+        const { schema, propertyId, value, itemId } = change;
+        if (schema === 'design') {
+            const designValues = { ...this.state.designValues, [propertyId]: value };
+            this.patch({ designValues });
+            this.options.onPreviewMessage?.({
+                type: 'widgetic:update',
+                design: flattenDesignValuesForPreview(designValues)
+            });
+        }
+        else if (schema === 'content') {
+            const key = itemId ? `${itemId}__${propertyId}` : propertyId;
+            const contentValues = { ...this.state.contentValues, [key]: value };
+            this.patch({ contentValues });
+            this.options.onPreviewMessage?.({ type: 'widgetic:update', content: contentValues });
+        }
+        else {
+            this.logger.warn('[CompositionEditor] A change to an unknown kind of property was ignored:', schema);
+            return;
+        }
+        this.markEdited();
+    }
+    /** The content items (slides, rows, cards...) were changed in the props editor. */
+    changeContentItems(items) {
+        if (this.disposed || this.state.phase !== 'ready')
+            return;
+        const incoming = Array.isArray(items) ? items : [];
+        const contentItems = mergeContentItemsWithSchema(incoming, schemaContentItems(this.state.contentSchema));
+        this.patch({ contentItems });
+        this.options.onPreviewMessage?.({
+            type: 'widgetic:update',
+            contentItems: flattenContentItemsForPreview(contentItems)
+        });
+        this.markEdited();
+    }
+    /**
+     * The user gave the preview a size, by dragging its corner or typing it in. That is the size saved with the
+     * composition, and the preview is drawn at it (in the desktop view). A size that is not the user's choice
+     * (the one a small box forces on the preview) must not be passed here.
+     */
+    setPreviewSize(width, height) {
+        if (this.disposed || this.state.phase !== 'ready')
+            return;
+        const previewWidth = Math.max(MIN_PREVIEW_SIZE, Math.round(width));
+        const previewHeight = Math.max(MIN_PREVIEW_SIZE, Math.round(height));
+        if (!Number.isFinite(previewWidth) || !Number.isFinite(previewHeight))
+            return;
+        // (The preview reports the size it was just given, too: that is not a new size.)
+        if (previewWidth === this.state.previewWidth && previewHeight === this.state.previewHeight)
+            return;
+        const embedChanged = previewWidth !== this.state.embedWidth || previewHeight !== this.state.embedHeight;
+        this.patch({
+            previewWidth,
+            previewHeight,
+            embedWidth: previewWidth,
+            embedHeight: previewHeight,
+            deviceView: 'desktop'
+        });
+        if (embedChanged)
+            this.markEdited();
+    }
+    /**
+     * The mobile and desktop buttons: the preview is drawn at a phone's size, or back at the saved size. That is a
+     * way of looking, not an edit: nothing becomes unsaved, and a save still sends the size the user gave the preview.
+     */
+    setDeviceView(deviceView) {
+        if (this.disposed || this.state.phase !== 'ready' || deviceView === this.state.deviceView)
+            return;
+        const mobile = deviceView === 'mobile';
+        this.patch({
+            deviceView,
+            previewWidth: mobile ? MOBILE_PREVIEW_WIDTH : this.state.embedWidth,
+            previewHeight: mobile ? MOBILE_PREVIEW_HEIGHT : this.state.embedHeight
+        });
+    }
+    /**
+     * The page saved the composition's embed settings itself (a page can have its own screen for them), so the ones
+     * this editor loaded, and sends back with every save, are out of date. From now on a save carries these, with the
+     * size the preview has, and the desktop view is drawn at the size they name. Nothing becomes unsaved: the page
+     * saved them already. Call it when no save of the editor is on its way (after `flush()`): the answer to a save
+     * that is replaces them.
+     */
+    adoptEmbedSettings(settings) {
+        if (this.disposed || this.state.phase !== 'ready' || !isRecord(settings))
+            return;
+        // A copy: the page may go on using, and changing, the object it gave.
+        let copiedSettings;
+        try {
+            copiedSettings = JSON.parse(JSON.stringify(settings));
+        }
+        catch (error) {
+            this.logger.warn('[CompositionEditor] The embed settings could not be copied, so they were ignored:', error);
+            return;
+        }
+        this.storedEmbedSettings = copiedSettings;
+        const embedWidth = parseEmbedDimension(settings.width, this.state.embedWidth);
+        const embedHeight = parseEmbedDimension(settings.height, this.state.embedHeight);
+        if (embedWidth === this.state.embedWidth && embedHeight === this.state.embedHeight)
+            return;
+        const desktop = this.state.deviceView === 'desktop';
+        this.patch({
+            embedWidth,
+            embedHeight,
+            ...(desktop ? { previewWidth: embedWidth, previewHeight: embedHeight } : {})
+        });
+    }
+    /** An edit was made: there is something new to save, the wait for the next autosave starts again, and so does the count of failures. */
+    markEdited() {
+        this.revision += 1;
+        this.failedAutosaves = 0;
+        this.patch({ dirty: true });
+        this.scheduleAutosave(this.autosaveDelayMs);
+    }
+    hasUnsavedChanges() {
+        return this.revision !== this.savedRevision;
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Saving
+    // ---------------------------------------------------------------------------------------------
+    /**
+     * Saves what has been edited. Resolves `true` when there is nothing unsaved afterwards, `false` when the save
+     * failed (see `saveError`) or the editor is not ready.
+     */
+    save(reason = 'manual') {
+        if (this.disposed || this.state.phase !== 'ready')
+            return Promise.resolve(false);
+        if (this.savePromise) {
+            // One save at a time: wait for the one on its way, then save what is new since, if it worked.
+            return this.savePromise.then((worked) => worked && this.hasUnsavedChanges() ? this.save(reason) : worked);
+        }
+        if (!this.hasUnsavedChanges())
+            return Promise.resolve(true);
+        // (No other save can have taken its place: while this one is set, `save()` waits for it instead of starting one.)
+        const running = this.runSave(reason).finally(() => {
+            this.savePromise = null;
+        });
+        this.savePromise = running;
+        return running;
+    }
+    /**
+     * Saves everything that is unsaved, now, and waits until it is. Resolves `true` when nothing is left unsaved,
+     * `false` when a save failed. For closing the editor.
+     */
+    async flush() {
+        // A round saves what is unsaved (waiting for a save on its way first, and saving that save's newer edits after it).
+        // Edits that keep coming in while it saves are chased for a few rounds, not for ever.
+        for (let round = 0; round < MAX_FLUSH_ROUNDS; round++) {
+            if (!this.hasUnsavedChanges())
+                return true;
+            if (!(await this.save('flush')))
+                return false;
+        }
+        return !this.hasUnsavedChanges();
+    }
+    async runSave(reason) {
+        this.clearAutosaveTimer();
+        const savingRevision = this.revision;
+        this.patch({ saving: true, saveError: null });
+        try {
+            const body = this.buildSaveBody();
+            const updated = await this.options.api.saveComposition(this.options.compositionId, body, {
+                signal: this.abortController.signal
+            });
+            if (this.disposed)
+                return false;
+            const savedAt = this.now();
+            this.savedRevision = savingRevision;
+            // What the API now holds for the embed settings, else what was just sent.
+            const settingsNow = getCompositionEmbedSettings(updated);
+            this.storedEmbedSettings =
+                Object.keys(settingsNow).length > 0 ? settingsNow : (body.embedSettings ?? {});
+            this.patch({
+                saving: false,
+                saveError: null,
+                lastSavedAt: savedAt,
+                dirty: this.hasUnsavedChanges()
+            });
+            this.emit({ type: 'saved', composition: updated, savedAt });
+            // (Edits made while this save travelled are still unsaved: the autosave they started waits for its turn.)
+            return true;
+        }
+        catch (error) {
+            if (this.disposed)
+                return false;
+            const failure = describeFailure(error);
+            this.logger.warn('[CompositionEditor] Saving failed:', failure.code, failure.message);
+            this.patch({ saving: false, saveError: failure });
+            this.emit({ type: 'error', during: 'save', failure, fatal: false });
+            if (reason === 'autosave' && failure.retryable)
+                this.scheduleAutosaveRetry();
+            return false;
+        }
+    }
+    /** What a save sends: a copy of the values as they are now, so later edits cannot change it. */
+    buildSaveBody() {
+        const { name, designValues, contentValues, contentItems, embedWidth, embedHeight } = this.state;
+        const content = { design: designValues, content: contentValues };
+        if (contentItems.length > 0)
+            content.contentItems = contentItems;
+        const body = {
+            name,
+            content,
+            embedSettings: {
+                ...this.storedEmbedSettings,
+                width: String(embedWidth),
+                height: String(embedHeight)
+            }
+        };
+        return JSON.parse(JSON.stringify(body));
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Autosave timing
+    // ---------------------------------------------------------------------------------------------
+    /** Starts the wait for an autosave of what is unsaved (for callers that have something unsaved). */
+    scheduleAutosave(delayMs) {
+        if (this.disposed || this.autosaveDelayMs <= 0 || this.state.phase !== 'ready')
+            return;
+        this.clearAutosaveTimer();
+        this.autosaveTimer = this.timers.setTimeout(() => {
+            this.autosaveTimer = null;
+            void this.save('autosave');
+        }, delayMs);
+    }
+    /** After an autosave failed for a reason that may pass: try again later, but only so many times. */
+    scheduleAutosaveRetry() {
+        const delayMs = this.autosaveRetryDelaysMs[this.failedAutosaves];
+        this.failedAutosaves += 1;
+        if (delayMs === undefined) {
+            this.logger.warn('[CompositionEditor] Autosave gave up after repeated failures; the next edit or a manual save tries again');
+            return;
+        }
+        this.scheduleAutosave(delayMs);
+    }
+    clearAutosaveTimer() {
+        if (this.autosaveTimer === null)
+            return;
+        this.timers.clearTimeout(this.autosaveTimer);
+        this.autosaveTimer = null;
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Ending
+    // ---------------------------------------------------------------------------------------------
+    /** Stops everything: timers, requests on their way, and any answer that arrives later. Unsaved edits are lost; `flush()` first to keep them. */
+    dispose() {
+        this.disposed = true;
+        this.clearAutosaveTimer();
+        this.abortController.abort();
+        this.stateListeners.clear();
+        this.eventListeners.clear();
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------------------------
+    /** Makes the next state out of the changes, tells the watchers, and says when the unsaved flag turned over. */
+    patch(changes) {
+        const wasDirty = this.state.dirty;
+        this.state = { ...this.state, ...changes };
+        for (const listener of [...this.stateListeners]) {
+            try {
+                listener(this.state);
+            }
+            catch (error) {
+                this.logger.error('[CompositionEditor] A state listener failed:', error);
+            }
+        }
+        if (this.state.dirty !== wasDirty)
+            this.emit({ type: 'dirty', dirty: this.state.dirty });
+    }
+    emit(event) {
+        for (const listener of [...this.eventListeners]) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                this.logger.error('[CompositionEditor] An event listener failed:', error);
+            }
+        }
+    }
+}