@riverbankcms/sdk 0.147.0 → 0.148.0

package/dist/_dts/content-editor/src/hooks/useDebouncedLatestSave.d.ts

@@ -1,12 +1,14 @@
-export type DebouncedLatestSaveHandle = {
+export type DebouncedLatestSaveHandle<TResult = void, TSnapshot = unknown> = {
     trigger: () => void;
     cancel: () => void;
-    flush: () => Promise<void>;
+    flush: () => Promise<TResult | undefined>;
     isPending: () => boolean;
+    whenIdle: () => Promise<TResult | undefined>;
+    run: (snapshot: TSnapshot) => Promise<TResult | undefined>;
 };
 export type DebouncedLatestSaveConfig<TSnapshot, TPayload, TResult> = {
     getSnapshot: () => TSnapshot;
-    buildPayload: (snapshot: TSnapshot) => TPayload | null | undefined;
+    buildPayload: (snapshot: TSnapshot, preceding?: TResult) => TPayload | null | undefined;
     save: (payload: TPayload) => Promise<TResult>;
     shouldSkip?: (snapshot: TSnapshot) => boolean;
     onSaving?: (snapshot: TSnapshot) => void;
@@ -19,6 +21,6 @@ export type DebouncedLatestSaveConfig<TSnapshot, TPayload, TResult> = {
     delay?: number;
     maxWait?: number;
     enabled?: boolean;
-    retryDelay?: number;
 };
-export declare function useDebouncedLatestSave<TSnapshot, TPayload, TResult>(config: DebouncedLatestSaveConfig<TSnapshot, TPayload, TResult>): DebouncedLatestSaveHandle;
+/** Timing and serial execution only. Request identity and save eligibility remain in the value store. */
+export declare function useDebouncedLatestSave<TSnapshot, TPayload, TResult>(config: DebouncedLatestSaveConfig<TSnapshot, TPayload, TResult>): DebouncedLatestSaveHandle<TResult, TSnapshot>;

package/dist/_dts/content-editor/src/hooks/useEditLease.d.ts

@@ -0,0 +1,28 @@
+import type { ApiClient } from '../../../api/src/request';
+import type { EditLeaseScope } from '../../../core/src/index';
+import type { EditorLeaseUiState } from '../ui/editorLeaseUiState';
+type LeaseUiPort = Readonly<{
+    getState: () => Pick<EditorLeaseUiState, 'setEditability' | 'setLeaseDiscardedChanges'>;
+}>;
+import type { EditLeaseLossSignal } from '../controller/editLeaseLossSignal';
+type LeaseParams = Readonly<{
+    siteId: string;
+    nodeType: EditLeaseScope['nodeType'];
+    nodeId: string;
+}>;
+export type EditLeaseChangeSubscription = (scope: Pick<LeaseParams, 'nodeType' | 'nodeId'>, listener: () => void) => () => void;
+export type UseEditLeaseOptions = Readonly<{
+    scope: LeaseParams;
+    apiClient: ApiClient;
+    uiStore: LeaseUiPort;
+    subscribeToLeaseChanges?: EditLeaseChangeSubscription;
+    onGranted?: (takingBack: boolean, isCurrent: () => boolean) => Promise<void> | void;
+    onAccessChanged?: () => void;
+    leaseLossSignal: EditLeaseLossSignal;
+}>;
+export declare function useEditLease({ scope, apiClient, uiStore, subscribeToLeaseChanges, onGranted, onAccessChanged, leaseLossSignal, }: UseEditLeaseOptions): {
+    takeOver: () => void;
+    retry: () => void;
+    recheck: () => void;
+};
+export {};

package/dist/_dts/content-editor/src/hooks/useEntryActions.d.ts

@@ -1,65 +1,51 @@
 import { type ContentEntrySnapshot, type RoutingHelpers } from '../../../content-model/src/index';
 import type { EditorUiStoreInstance } from '../ui/editorUiStore';
+import type { LifecycleOutcome } from '../ui/stores/types';
 import type { BlockedPublishPlan } from './blockedPublishPlan';
-import type { PublishEntryResult } from '../services/contentEntryServices';
-/** Services interface for entry operations */
-export type EntryServices = {
-    deleteEntry?: () => Promise<void>;
-};
-export type PublishOptions = {
-    mode?: 'default' | 'now';
-};
-/** Definition with services */
-export type EntryDefinition = {
-    services: EntryServices;
-    publish?: {
-        buildPayload?: (values: Record<string, unknown>, entry: ContentEntrySnapshot) => unknown;
-    };
-};
+import type { DiscardDraftInput, DiscardLifecycleResult, EditorDeletion, PublishLifecycleResult } from '../services/contentEntryServices';
+export type PublishOptions = Readonly<{
+    whenUnchanged?: 'publish' | 'skip';
+}>;
+export type EntryActions = Readonly<{
+    saveDraft: () => Promise<LifecycleOutcome>;
+    publish: (options?: PublishOptions) => Promise<LifecycleOutcome>;
+    discardDraft: () => Promise<LifecycleOutcome>;
+    deletion: Readonly<{
+        kind: 'deletable';
+        deleteEntry: () => Promise<LifecycleOutcome>;
+    }> | Readonly<{
+        kind: 'deletedWithOwner';
+    }>;
+}>;
 export type EntryActionsOptions<TEntry extends ContentEntrySnapshot> = {
     /** Current entry snapshot */
     entry: TEntry;
     /** UI store instance (to read latest metadata values at call time) */
     uiStore: EditorUiStoreInstance;
-    /** Whether this entry has a route (pages vs content) */
-    hasRoute: boolean;
     /** Routing helpers (for routable published baseline derivations). */
     routing?: RoutingHelpers;
     /** Publish mutation from react-query */
     publishMutation: {
-        mutateAsync: (payload?: unknown) => Promise<PublishEntryResult<TEntry>>;
+        mutateAsync: () => Promise<PublishLifecycleResult<TEntry>>;
     };
     /** Discard draft mutation from react-query */
     discardMutation: {
-        mutateAsync: () => Promise<TEntry>;
+        mutateAsync: (input: DiscardDraftInput) => Promise<DiscardLifecycleResult<TEntry>>;
     };
     /** Entry definition with services */
-    definition: EntryDefinition;
-    /** Function to sync entry and create snapshot */
-    syncEntry: (nextEntry: TEntry, opts?: {
-        clearError?: boolean;
-    }) => {
+    deletion: EditorDeletion;
+    /** The metadata values an entry snapshot holds, as the store holds them (`normalizedMetadataBaseline`). */
+    metadataOf: (nextEntry: TEntry) => {
         baseline: Record<string, unknown>;
         values: Record<string, unknown>;
     };
-    /** Function to reset form from snapshot */
-    resetFromSnapshot: (snapshot: {
-        baseline: Record<string, unknown>;
-        values: Record<string, unknown>;
-    }) => void;
-    /** Function to set error message */
-    setErrorMessage: (message: string | null) => void;
     setBlockedPublishPlan?: (plan: Extract<BlockedPublishPlan, {
         type: 'blocked';
     }> | null) => void;
 };
 /**
- * Hook to handle entry actions (publish, discard, delete).
- * Extracts action handler logic from the provider for better separation of concerns.
+ * Hook to handle entry actions (save draft, publish, discard, delete). Each returns a
+ * `LifecycleOutcome`; expected refusals are results, and the error banner and status
+ * derive from the lifecycle failure it records (issue 1553).
  */
-export declare function useEntryActions<TEntry extends ContentEntrySnapshot>({ entry, uiStore, hasRoute, routing, publishMutation, discardMutation, definition, syncEntry, resetFromSnapshot, setErrorMessage, setBlockedPublishPlan: setBlockedPlan, }: EntryActionsOptions<TEntry>): {
-    saveDraft: () => Promise<void>;
-    publish: (options?: PublishOptions) => Promise<void>;
-    discardDraft: () => Promise<void>;
-    deleteEntry: () => Promise<void>;
-};
+export declare function useEntryActions<TEntry extends ContentEntrySnapshot>({ entry, uiStore, routing, publishMutation, discardMutation, deletion, metadataOf, setBlockedPublishPlan: setBlockedPlan, }: EntryActionsOptions<TEntry>): EntryActions;

package/dist/_dts/content-editor/src/hooks/useEntryMutations.d.ts

@@ -1,28 +1,26 @@
+import { useQueryClient } from '@tanstack/react-query';
 import type { ContentEntrySnapshot } from '../../../content-model/src/index';
-import type { EditorUiState } from '../ui/editorUiStore';
-import type { PublishEntryResult } from '../services/contentEntryServices';
-type StoreApi<T> = {
-    getState: () => T;
+import type { DocumentBlockState } from '@riverbankcms/api/content-entries';
+import type { DiscardDraftInput, DiscardLifecycleResult, PublishLifecycleResult } from '../services/contentEntryServices';
+type BlockCacheContext = {
+    queryClient: ReturnType<typeof useQueryClient>;
+    siteId: string;
+    type: string;
+    entryId: string;
 };
-export declare function usePublishEntryMutation<TEntry extends ContentEntrySnapshot = ContentEntrySnapshot, TPublishPayload = unknown>({ publishFn, siteId, type, entryId, isPage, pageId, uiStore, }: {
-    publishFn?: (payload: TPublishPayload | undefined) => Promise<PublishEntryResult<TEntry>>;
+export declare function reconcileBlockCache(context: BlockCacheContext, state: DocumentBlockState): void;
+export declare function usePublishEntryMutation<TEntry extends ContentEntrySnapshot = ContentEntrySnapshot>({ publishFn, siteId, type, entryId, }: {
+    publishFn?: () => Promise<PublishLifecycleResult<TEntry>>;
     siteId: string;
     type: string;
     entryId: string;
-    isPage?: boolean;
-    pageId?: string;
-    uiStore?: StoreApi<EditorUiState>;
-}): import("@tanstack/react-query").UseMutationResult<Readonly<{
-    snapshot: TEntry;
-    publishedContent?: Record<string, unknown> | null;
-    publishedBlocks?: readonly import("../../../api/src/index").PublishedBlockBaseline[];
-}>, Error, TPublishPayload | undefined, unknown>;
-export declare function useDiscardDraftMutation<TEntry = unknown>({ discardFn, siteId, type, entryId, isPage, pageId, }: {
-    discardFn?: () => Promise<TEntry>;
+}): import("@tanstack/react-query").UseMutationResult<PublishLifecycleResult<TEntry>, Error, void, unknown>;
+export declare function useDiscardDraftMutation<TEntry extends ContentEntrySnapshot>({ discardFn, siteId, type, entryId, }: {
+    discardFn?: (input: DiscardDraftInput) => Promise<DiscardLifecycleResult<TEntry>>;
     siteId: string;
     type: string;
     entryId: string;
-    isPage?: boolean;
-    pageId?: string;
-}): import("@tanstack/react-query").UseMutationResult<TEntry, Error, void, unknown>;
+}): import("@tanstack/react-query").UseMutationResult<DiscardLifecycleResult<TEntry>, Error, Readonly<{
+    contentRevision: string | null;
+}>, unknown>;
 export {};

package/dist/_dts/content-editor/src/hooks/useLinkedEntryAutosave.d.ts

@@ -1,23 +1,20 @@
-import type { ApiClient } from '../services';
-import type { LinkedContentEntryId, LinkedContentTypeKey } from '../linkedEntries/domain';
+import { type LinkedContentEntryId, type LinkedContentTypeKey } from '../linkedEntries/domain';
 import type { EditorUiStoreInstance } from '../ui/editorUiStore';
 export type PendingLinkedEntrySave = Readonly<{
     entryId: LinkedContentEntryId;
     contentTypeKey: LinkedContentTypeKey;
     content: Record<string, unknown>;
-    optimisticHash: string | null;
-    acknowledgedVersion: number;
+    optimisticHash: string;
 }>;
 export type LinkedEntrySaveResult = Readonly<{
     entryId: LinkedContentEntryId;
     content: Record<string, unknown>;
-    optimisticHash: string | null;
+    optimisticHash: string;
 }>;
 export type LinkedEntryAutosaveOptions = Readonly<{
     uiStore: EditorUiStoreInstance;
-    apiClient: ApiClient;
     siteId: string;
     saveLinkedEntry?: (save: PendingLinkedEntrySave) => Promise<LinkedEntrySaveResult>;
 }>;
-export declare function collectPendingLinkedEntrySaves(uiStore: EditorUiStoreInstance): PendingLinkedEntrySave[];
-export declare function useLinkedEntryAutosave({ uiStore, apiClient, siteId, saveLinkedEntry, }: LinkedEntryAutosaveOptions): import("./useSimpleAutosave").AutosaveHandle;
+/** Linked-entry autosave: the linked-entry family's adapter for `useValueAutosave`. */
+export declare function useLinkedEntryAutosave(options: LinkedEntryAutosaveOptions): import("../ui/editorUiStore").AutosaveHandle;

package/dist/_dts/content-editor/src/hooks/useValueAutosave.d.ts

@@ -0,0 +1,64 @@
+import type { BaselineRevision, SaveFailure, SavedBlockContentVersion } from '../../../core/src/index';
+import type { EditorUiState, EditorUiStoreInstance, EditorValueKey, StartedSend } from '../ui/editorUiStore';
+import type { AutosaveHandle, AutosaveType } from '../ui/stores/types';
+import { type FlushCheckpoint, type SendAcknowledgement } from '../sync/sendPlanning';
+import type { SendMode } from '../sync/valueSync';
+/** What the server stored for one request. */
+export type SavedValue = Readonly<{
+    blockVersion?: SavedBlockContentVersion;
+    values: Record<string, unknown> | null;
+    revision: BaselineRevision;
+    published?: Readonly<{
+        kind: 'known';
+        values: Record<string, unknown> | null;
+    } | {
+        kind: 'unknown';
+    }>;
+}>;
+/**
+ * One value family's part of autosave: which scheduler it is, and how one started request
+ * is sent. `send` resolves with what the server stored and throws on failure.
+ */
+export type ValueAutosaveAdapter<TSaved extends SavedValue = SavedValue> = Readonly<{
+    uiStore: EditorUiStoreInstance;
+    scheduler: AutosaveType;
+    send: (send: StartedSend) => Promise<TSaved>;
+    onSaved?: (send: StartedSend, saved: TSaved) => void;
+    enabled?: boolean;
+    delay?: number;
+    maxWait?: number;
+}>;
+/** One batch: the values to send and how a failure among them is treated (`canSend`). */
+export type SendBatch = Readonly<{
+    keys: readonly EditorValueKey[];
+    mode: SendMode;
+    checkpoints?: readonly FlushCheckpoint[];
+    completed?: readonly SendAcknowledgement[];
+    signal?: AbortSignal;
+}>;
+/** A save that can't be compared-and-set: the editor never received the value's revision. */
+export declare function missingRevisionError(): Error;
+/** A send found the tab no longer holds the value's lease before it reached the server. */
+export declare class LeaseLostError extends Error {
+    constructor();
+}
+/** Losing the lease leaves edits unsaved, not failed; they send again once writable (W1). */
+export declare function saveFailureOf(error: unknown): SaveFailure;
+/**
+ * The next batch for a scheduler: what the background would send, plus any values a
+ * flush asked for, which are sent explicitly so a failure is retried (row S3b). A
+ * requested value still has to be writable and saveable now: the lease or a block's
+ * validity can change between the flush's plan and this batch.
+ */
+export declare function nextSendBatch(state: EditorUiState, scheduler: AutosaveType, requested: readonly EditorValueKey[]): SendBatch;
+/**
+ * The whole send effect: start every planned request under its own id, send them
+ * together, and settle each response against its id only.
+ */
+export declare function sendPlanned<TSaved extends SavedValue>(adapter: ValueAutosaveAdapter<TSaved>, batch: SendBatch): Promise<readonly SendAcknowledgement[]>;
+/**
+ * The one autosave hook (issue 1553). `useDebouncedLatestSave` is the timing shell
+ * (debounce, max wait, one batch at a time); the store's request slots say what is
+ * outstanding and `planSends` says what may send.
+ */
+export declare function useValueAutosave<TSaved extends SavedValue>(adapter: ValueAutosaveAdapter<TSaved>): AutosaveHandle;

package/dist/_dts/content-editor/src/hooks/validateBlocksForPublish.d.ts

@@ -1,10 +1,3 @@
-/**
- * Pre-publish validation for blocks.
- *
- * Validates all block content using strict mode validation before allowing publish.
- * This catches empty required fields and other validation errors that were allowed
- * during editing (draft mode) but must be fixed before publishing.
- */
 import type { FieldValidationDescriptor } from '../../../blocks/src/index';
 import type { EditorBlockId } from '../../../core/src/index';
 import type { EditorUiStoreInstance } from '../ui/editorUiStore';

package/dist/_dts/content-editor/src/index.d.ts

@@ -1,20 +1,39 @@
+export { canWriteLinkedEntry } from './ui/stores/linkedEntryLeaseStore';
+export { LinkedEntryLeaseBanner } from './controller/LinkedEntryLeaseBanner';
 export * from './registry';
+export { getEditorClientId } from './controller/editorClientId';
+export { useEditLeaseActions, type EditLeaseControllerActions, type EditorLeaseConfig, } from './controller/EditLeaseController';
+export { EditLeaseDiscardedNotice, EditLeaseModal, EditorWriteGate, EditorWriteSurface, } from './controller/EditorWriteGate';
+export { planLeaseNotice, type LeaseNotice, type LeaseNoticeAction } from './controller/editLeaseNotice';
+export { VIEWING_PARTICIPATION, type EditorLeaseParticipation, } from './controller/editorLeaseParticipation';
+export { canEditorWrite, unmanagedSurfaceEditability } from './controller/editorEditability';
+export { liveDraftRole, type LiveDraftsClient, type LiveDraftsConfig, type LiveDraftRole, } from './liveDrafts/useLiveDrafts';
+export { remoteDraftValues, renderedFieldChanges, renderSourceFor, resolveRenderedValues, type RemoteDraftEntry, type RenderSource, type RemoteDraftOverlay, } from './liveDrafts/remoteDraftOverlay';
+export { activeLinkedSaveHandover, planLinkedSaveHandoverRetention, type LinkedSaveHandover, type LinkedSaveHandovers, type RenderedLinkedRevisions, } from './liveDrafts/linkedSaveHandovers';
+export { useRetentionTicks } from './liveDrafts/useRetentionTicks';
+export type { EditorEditability } from './controller/editorEditability';
 export * from './services';
 export { useDebouncedLatestSave, type DebouncedLatestSaveConfig, type DebouncedLatestSaveHandle, } from './hooks/useDebouncedLatestSave';
-export { useSimpleAutosave, useMultiAutosave } from './hooks/useSimpleAutosave';
-export { useStoreAutosave, type StoreAutosaveConfig, type AutosaveScope, } from './hooks/useStoreAutosave';
+export { useAutosaveStatus } from './hooks/useAutosaveStatus';
+export { selectAutosaveStatus } from './sync/schedulerValues';
+export { lifecycleOutcomeMessage, requireSavedDraft } from './sync/lifecycleFailure';
+export type { LifecycleFailure, LifecycleOutcome } from './ui/stores/types';
+export type { RouteWrites, RouteWriteOperation } from './controller/routeWrites';
+export { documentSince, type DocumentSince } from './sync/runLifecycle';
+export type { FlushPolicy, FlushResult } from './sync/sendPlanning';
+export { baselineRevisionOf, displayedValues, hasOutstandingRequest, isEdited, syncStateOf, valueStatus, type ValueStatus, } from './sync/valueSync';
 export { useBlockAutosave, type BlockAutosaveOptions, } from './hooks/useBlockAutosave';
-export { collectPendingLinkedEntrySaves, useLinkedEntryAutosave, type LinkedEntryAutosaveOptions, type LinkedEntrySaveResult, type PendingLinkedEntrySave, } from './hooks/useLinkedEntryAutosave';
+export { useLinkedEntryAutosave, type LinkedEntryAutosaveOptions, type LinkedEntrySaveResult, type PendingLinkedEntrySave, } from './hooks/useLinkedEntryAutosave';
 export { unsafeAsLinkedContentEntryId, unsafeAsLinkedContentTypeKey, type LinkedContentEntryId, type LinkedContentTypeKey, } from './linkedEntries/domain';
 export { useEntryActions, type EntryActionsOptions, } from './hooks/useEntryActions';
 export { useReactiveToolbar } from './hooks/useReactiveToolbar';
+export { canDiscardDraft } from './controller/deriveEditorUnpublishedState';
 export { isInvalidSaveability, selectHasInvalidBlocks, } from './hooks/invalidBlockSelectors';
 export { useHistoryShortcuts } from './hooks/useHistoryShortcuts';
 export { validateAllBlocks, type BlockValidationError, type PublishEditorTarget, } from './hooks/validateBlocksForPublish';
 export type { BlockedPublishPlan, PublishValidationDiagnostic, } from './hooks/blockedPublishPlan';
-export { EntryControllerProvider, useEntryEditorController, useEntryController, useAutosave, useEntryUiStore, } from './controller/EntryControllerProvider';
-export type { EntryDraftBlockPatch, EntryDraftCompositePatch, EntryDraftsActions, EntryDraftsSlice, } from './controller/EntryControllerProvider';
-export type { EntryEditorDriver } from './controller/driver';
+export { EntryControllerProvider, useEntryEditorController, useEntryController, } from './controller/EntryControllerProvider';
+export type { EntryDraftBlockPatch, EntryDraftCompositePatch, EntryDraftsActions, EntryDraftsSlice, EntryActions, } from './controller/EntryControllerProvider';
 export { EditableBlockProvider, useBlockData, } from './components/EditableBlockProvider';
 export { ContentFieldsForm, type ContentFieldsFormProps, } from './components/ContentFieldsForm';
 export { useUISelector } from './ui/useUISelector';
@@ -39,4 +58,4 @@ export { buildFooterBlocksUpdatePayload, createInitialFooterBlocksEditorState, f
 export { asContentEntrySnapshotSource, createContentEntriesDefinitionPlan, createPageSnapshot, createPagesDefinitionPlan, createSnapshotDefaults, getDefaultEntityLabel, mapPageRecordToSnapshot, type ContentEntriesDefinitionPlanOptions, type ContentEntryDefinitionPlan, type DefinitionServices, type PageEntrySnapshot, type PagesDefinitionPlanOptions, type SnapshotDefaults, } from './definitions/factory';
 export { canRedoHistory, canUndoHistory, createHistoryState, unsafeAsEditorBlockId, pushHistoryEntry, redoHistory, replaceHistoryPresent, undoHistory, type HistoryState, type EditorBlockId, } from './ui/editorHistory';
 export { classifyHistoryShortcut, isNativeHistoryTarget, type HistoryShortcutCommand, } from './historyShortcuts';
-export type { ContentEntryControllerOptions, ContentEntryControllerState, DraftWorkflowStatus, MetadataAutosaveConfig, MetadataKindConfig, } from './types';
+export type { EditLeaseChangeSubscription } from './hooks/useEditLease';

package/dist/_dts/content-editor/src/linkedEntries/domain.d.ts

@@ -6,3 +6,15 @@ export type LinkedContentTypeKey = string & {
 };
 export declare function unsafeAsLinkedContentEntryId(value: string): LinkedContentEntryId;
 export declare function unsafeAsLinkedContentTypeKey(value: string): LinkedContentTypeKey;
+export type LinkedEntryOpenTarget = {
+    entryId: string;
+    contentTypeKey: string;
+    contentTypeLabel: string;
+    title: string;
+    optimisticHash?: string | null;
+    content: Record<string, unknown>;
+    contentType: {
+        titleField?: string | null;
+        fields: readonly Record<string, unknown>[];
+    };
+};

package/dist/_dts/content-editor/src/linkedEntries/owner.d.ts

@@ -0,0 +1,9 @@
+import type { ValueRefresh } from '../ui/editorRefresh';
+import { type EditorCommand, type EditorHistorySnapshot, type EditorLinkedEntrySnapshot, type EditorValueKey } from '../ui/editorHistory';
+/** A reference to the document itself is another view of its existing content. */
+export declare function linkedEntrySnapshot(snapshot: EditorHistorySnapshot, entryId: string, ownerEntryId?: string): EditorLinkedEntrySnapshot | null;
+/** Sync events for the document's own entry apply to its content. */
+export declare function routeValueKey(key: EditorValueKey, ownerEntryId?: string): EditorValueKey;
+/** A server read of the document's own entry refreshes its content. */
+export declare function routeRefresh(refresh: ValueRefresh, ownerEntryId?: string): ValueRefresh;
+export declare function routeLinkedEntryCommand(command: EditorCommand, ownerEntryId?: string): EditorCommand;

package/dist/_dts/content-editor/src/liveDrafts/draftProjection.d.ts

@@ -0,0 +1,66 @@
+import { type DraftItem, type DraftTarget, type DroppedDraftItem } from '../../../realtime/src/index';
+import type { EditorHistorySnapshot } from '../ui/editorHistory';
+/** The inputs of one projection: the editor state, what was last sent, and who may write what. */
+export type DraftProjectionInput = Readonly<{
+    snapshot: EditorHistorySnapshot;
+    previouslySent: readonly DraftItem[];
+    contentOwnerEntryId?: string;
+    /** Per-item write authority (`canWriteDraftTarget`): a tab only speaks for what it may write. */
+    canWrite: (target: DraftTarget) => boolean;
+}>;
+/**
+ * Pure projection of the editor state into the items to stream.
+ *
+ * - An item this tab may not write (a linked entry whose own lease moved elsewhere)
+ *   is omitted before anything else, so it is never sent as unsaved or as saved. A
+ *   viewer treats the omission as that item being gone and drops it.
+ * - Every value the person has edited is sent as `unsaved` with what it shows.
+ * - A value that was sent as `unsaved` last time and is now pristine (saved,
+ *   discarded, or undone) is sent once as `saved` with the baseline and its server
+ *   revision, so a viewer can hand over to its own refreshed baseline without
+ *   flashing the old value. Without a known revision it is simply omitted.
+ *
+ * Diffing against what was last *sent* (not last observed) keeps saved markers
+ * correct when sends are throttled.
+ */
+export declare function projectDraftItems(input: DraftProjectionInput): DraftItem[];
+/**
+ * Why the emitter is considering a send:
+ * - `change`: the store changed; send only when the items differ from the last send.
+ * - `heartbeat`: keep viewers' unsaved items alive while anything is unsaved.
+ * - `sync`: a viewer asked for the current state; always answer.
+ */
+export type DraftPublishReason = 'change' | 'heartbeat' | 'sync';
+/** `dropped` is reported on both outcomes: an oversized item can be dropped on a skip too. */
+export type DraftPublishPlan = Readonly<{
+    kind: 'skip';
+    dropped: readonly DroppedDraftItem[];
+}> | Readonly<{
+    kind: 'send';
+    items: readonly DraftItem[];
+    dropped: readonly DroppedDraftItem[];
+}>;
+/**
+ * What the emitter sends, decided purely: project, keep what fits the message
+ * budget, then send or skip by reason. `items` is exactly what goes on the wire,
+ * so the emitter keeps it as the next `previouslySent`.
+ */
+export declare function planDraftPublish(input: DraftProjectionInput & Readonly<{
+    reason: DraftPublishReason;
+}>): DraftPublishPlan;
+/**
+ * The dropped items not already reported, so each oversized item warns once while it
+ * stays oversized, and again only if it fits and later outgrows the budget again.
+ */
+export declare function newlyDroppedDraftItems(previouslyDropped: ReadonlySet<string>, dropped: readonly DroppedDraftItem[]): readonly DroppedDraftItem[];
+/**
+ * The next sequence number for an emitter. Viewers ignore a seq that isn't newer
+ * than the last one from the same origin, and the origin outlives an editor mount,
+ * so a new mount starts from the clock rather than from zero.
+ */
+export declare function nextDraftSeq(previous: number, now: number): number;
+/**
+ * The server revision of the viewer's own baselines, keyed like the overlay. Built
+ * once per retention check rather than once per overlay entry.
+ */
+export declare function baselineRevisions(snapshot: EditorHistorySnapshot): ReadonlyMap<string, string | null>;

package/dist/_dts/content-editor/src/liveDrafts/linkedSaveHandovers.d.ts

@@ -0,0 +1,37 @@
+import type { BaselineRevision, EditorValueRecord, ValueSync } from '../../../core/src/index';
+import { type LinkedContentEntryId } from '../linkedEntries/domain';
+import type { EditorValueKey } from '../ui/editorSnapshot';
+import { type RetentionPlan, type SavedHandover } from './remoteDraftOverlay';
+/**
+ * This tab's accepted linked-entry save, handing over to the rendered data (issue 1553, D).
+ * No content is copied: the render reads the record's own baseline while the handover applies.
+ */
+export type LinkedSaveHandover = Readonly<{
+    revision: string;
+    since: number;
+    phase: SavedHandover;
+}>;
+/** Outside history, beside `remoteDrafts`; only the renderer reads it. */
+export type LinkedSaveHandovers = ReadonlyMap<LinkedContentEntryId, LinkedSaveHandover>;
+export declare const EMPTY_LINKED_SAVE_HANDOVERS: LinkedSaveHandovers;
+/** Every rendered occurrence's `optimisticHash` for each linked entry. */
+export type RenderedLinkedRevisions = ReadonlyMap<LinkedContentEntryId, readonly (string | null)[]>;
+/** A later accepted save replaces the entry's earlier handover (row H7). */
+export declare function recordLinkedSaveHandover(handovers: LinkedSaveHandovers, entryId: LinkedContentEntryId, revision: string, since: number): LinkedSaveHandovers;
+/**
+ * What an accepted save leaves behind: a linked entry's save, at a known revision, hands
+ * over to the rendered data, including a save that lands after a discard (rows H1, H5).
+ * Other values render from the store and need no handover.
+ */
+export declare function handoversAfterAcceptedSave(handovers: LinkedSaveHandovers, key: EditorValueKey, revision: BaselineRevision, at: string): LinkedSaveHandovers;
+/**
+ * The handover that applies to a record, if any. It holds only while the record is
+ * pristine at the saved revision: an edit, a refresh to another baseline or a later
+ * save ends it by derivation (rows H3, H4).
+ */
+export declare function activeLinkedSaveHandover(handovers: LinkedSaveHandovers | undefined, entryId: LinkedContentEntryId, sync: ValueSync<EditorValueRecord | null>): LinkedSaveHandover | null;
+/**
+ * Local retention (rows H1b, H2): a caught-up handover drops with no refresh; otherwise
+ * the shared `decideSavedHandover` timing applies.
+ */
+export declare function planLinkedSaveHandoverRetention(handovers: LinkedSaveHandovers, rendered: RenderedLinkedRevisions, now: number): RetentionPlan<LinkedContentEntryId, LinkedSaveHandover>;

package/dist/_dts/content-editor/src/liveDrafts/remoteDraftOverlay.d.ts

@@ -0,0 +1,113 @@
+import { type DraftItem, type DraftStateMessage, type DraftTarget } from '../../../realtime/src/index';
+import { type EditorValueRecord, type ValueSync } from '../../../core/src/index';
+import type { EditorEditability } from '../controller/editorEditability';
+/**
+ * A preview tab's read-only overlay of another tab's live drafts (issue 1545).
+ * It lives outside history, snapshots, autosave and the lease: nothing here is
+ * ever edited, saved or undone, it is only read by the renderer.
+ */
+/** No message from an unsaved item's origin for this long means its editor went away. */
+export declare const UNSAVED_DRAFT_TTL_MS = 15000;
+/** A saved item whose baseline has not caught up by then asks the host for one refresh. */
+export declare const SAVED_DRAFT_REFRESH_AFTER_MS = 10000;
+/** After the refresh, a saved item that still has not matched is dropped. */
+export declare const SAVED_DRAFT_DROP_AFTER_REFRESH_MS = 10000;
+/** Where a saved value's wait for fresh data stands: before or after its one refresh. */
+export type SavedHandover = Readonly<{
+    kind: 'awaiting-baseline';
+}> | Readonly<{
+    kind: 'refresh-requested';
+    at: number;
+}>;
+export type RemoteDraftEntry = Readonly<{
+    kind: 'unsaved';
+    item: DraftItem;
+    origin: string;
+    receivedAt: number;
+}> | Readonly<{
+    kind: 'saved';
+    item: DraftItem;
+    origin: string;
+    revision: string;
+    receivedAt: number;
+    handover: SavedHandover;
+}>;
+/** Keyed by `draftItemKey`. */
+export type RemoteDraftOverlay = ReadonlyMap<string, RemoteDraftEntry>;
+export declare const EMPTY_REMOTE_DRAFTS: RemoteDraftOverlay;
+/**
+ * Apply an accepted draft-state. It replaces everything unsaved from the same
+ * origin: an unsaved item it omits is gone (discarded or undone). Saved items
+ * stay until their own retention rule drops them, and other origins are untouched.
+ */
+export declare function applyRemoteDraftState(overlay: RemoteDraftOverlay, message: Pick<DraftStateMessage, 'origin' | 'items'>, now: number): RemoteDraftOverlay;
+export type OverlayRetentionPlan = Readonly<{
+    overlay: RemoteDraftOverlay;
+    changed: boolean;
+    /** Ask the host to refresh its server baselines once. */
+    refresh: boolean;
+}>;
+export type SavedHandoverDecision = 'keep' | 'request-refresh' | 'drop';
+/**
+ * How long a saved value keeps showing while the data it hands over to catches up
+ * (issue 1553, DP5). Shared by a viewer's saved remote drafts and this tab's own
+ * linked-entry saves; each caller decides what "caught up" means for its data.
+ * - Caught up: drop, so the fresh data shows in the same render.
+ * - Not caught up after `SAVED_DRAFT_REFRESH_AFTER_MS`: ask the host for one refresh.
+ * - Still not caught up `SAVED_DRAFT_DROP_AFTER_REFRESH_MS` after that: drop.
+ */
+export declare function decideSavedHandover(timing: Readonly<{
+    since: number;
+    phase: SavedHandover;
+}>, caughtUp: boolean, now: number): SavedHandoverDecision;
+export type RetentionDecision<E> = Readonly<{
+    kind: 'keep';
+}> | Readonly<{
+    kind: 'drop';
+}> | Readonly<{
+    kind: 'request-refresh';
+    entry: E;
+}>;
+export type RetentionPlan<K, E> = Readonly<{
+    entries: ReadonlyMap<K, E>;
+    changed: boolean;
+    /** Ask the host to refresh its server baselines once. */
+    refresh: boolean;
+}>;
+/** Applies one retention decision per entry; an unchanged map keeps its identity. */
+export declare function planRetention<K, E>(entries: ReadonlyMap<K, E>, decide: (key: K, entry: E) => RetentionDecision<E>): RetentionPlan<K, E>;
+/** A saved-handover decision as a retention decision, recording the refresh on the entry. */
+export declare function savedRetentionDecision<E>(decision: SavedHandoverDecision, withRefreshRequested: () => E): RetentionDecision<E>;
+/**
+ * Pure retention rule for the overlay.
+ * - Unsaved items expire after `UNSAVED_DRAFT_TTL_MS` without a message from their origin.
+ * - Saved items follow `decideSavedHandover`, caught up once the viewer's own baseline
+ *   for the item has the saved revision. The overlay and that baseline are read in the
+ *   same render, so the swap is atomic and nothing flashes.
+ */
+export declare function planOverlayRetention(overlay: RemoteDraftOverlay, baselineRevision: (key: string) => string | null, now: number): OverlayRetentionPlan;
+/** The remote value for a target, if another tab is streaming one. */
+export declare function remoteDraftValues(overlay: RemoteDraftOverlay | undefined, target: DraftTarget): EditorValueRecord | null;
+/**
+ * Where a tab's rendered values come from. A tab that is only viewing renders
+ * what the editing tab streams; any other tab renders its own edits.
+ */
+export type RenderSource = 'own-edits' | 'live-drafts';
+export declare function renderSourceFor(editability: EditorEditability): RenderSource;
+type LocalValues = Readonly<{
+    sync: ValueSync<EditorValueRecord | null>;
+}>;
+/**
+ * Render precedence, in one place.
+ * - `own-edits`: the tab's current value (its dirty edit, or the baseline). It never
+ *   holds a remote overlay, so none is read.
+ * - `live-drafts`: another tab's live draft, then the baseline. Local values are never
+ *   used, so edits a viewer abandoned can't outrank what the editing tab streams.
+ */
+export declare function resolveRenderedValues(source: RenderSource, local: LocalValues | null, remote: EditorValueRecord | null): EditorValueRecord | null;
+/**
+ * The top-level fields whose rendered value (after the precedence above) differs
+ * from the baseline, e.g. entry fields a template page must bind in again.
+ */
+export declare function renderedFieldChanges(source: RenderSource, local: LocalValues | null, remote: EditorValueRecord | null): Readonly<Record<string, unknown>>;
+export {};

package/dist/_dts/content-editor/src/liveDrafts/useLiveDrafts.d.ts

@@ -0,0 +1,32 @@
+import { type RealtimeEditScope } from '../../../realtime/src/index';
+import { type DraftRealtimeClient, type UseDraftChannelAuth } from '../../../realtime/src/client';
+import type { EditorEditability } from '../controller/editorEditability';
+import type { EditorUiStoreInstance } from '../ui/editorUiStore';
+/**
+ * What the host app supplies for live drafts: its own Supabase client (the
+ * preview uses a dedicated one, because token auth pins the token client-wide),
+ * how the channel authenticates, the document, and how a viewer refreshes its
+ * server baselines when a saved value has not arrived.
+ */
+export type LiveDraftsConfig = Readonly<{
+    client: DraftRealtimeClient;
+    auth: UseDraftChannelAuth;
+    siteId: string;
+    scope: RealtimeEditScope;
+    refreshBaselines?: () => void;
+}>;
+/** The structural slice of a Supabase client the drafts channel needs. */
+export type LiveDraftsClient = DraftRealtimeClient;
+export type LiveDraftRole = 'emit' | 'view' | 'off';
+/**
+ * A tab that holds the lease streams its drafts; a preview tab that is only
+ * viewing shows other tabs' drafts; any other tab (acquiring, read-only,
+ * unleased surfaces) takes no part.
+ */
+export declare function liveDraftRole(editability: EditorEditability): LiveDraftRole;
+/**
+ * Live drafts for one editor mount (issue 1545): joins the private drafts
+ * channel while the tab emits or views, streams this tab's dirty values while
+ * it holds the lease, and keeps the remote overlay while it only views.
+ */
+export declare function useLiveDrafts(uiStore: EditorUiStoreInstance, config: LiveDraftsConfig | null): void;