@jini-ai/ui 0.4.3 → 0.4.5

package/dist/features/panel-kit/hooks/use-settings-slice.hooks.js

@@ -0,0 +1,382 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useSerialWrites } from "./use-serial-writes.hooks.js";
+import { useSettlementGeneration } from "./use-settlement-generation.hooks.js";
+/** Debounce for text fields: tabs are controlled and fire on every keystroke,
+ *  and each ledger write is an append-only revision. Without this, typing into
+ *  a textarea would write one revision per character. */
+export const SAVE_DEBOUNCE_MS = 600;
+/**
+ * Runs one save-chain link: calls `runSave`, then paints the ticket-owning outcome onto
+ * `saveState` — unless a newer save has since taken the ticket (`currentTicket()` no longer matches
+ * `ticket`), or the operator has queued another edit behind this one (`hasUnsavedEdits()`). Pulled
+ * out of `onChange`'s debounce-timer closure (2026-08-06, complexity pass) — it was the deepest
+ * nesting in this file, three closures in (`onChange` > the `setTimeout` callback > the
+ * `saveChain.current.then(async () => …)` link) — so the ticket/staleness handling is directly
+ * assertable against a fake `runSave`, without a real timer or save chain.
+ *
+ * The ref reads are passed as thunks rather than plain booleans specifically so this keeps the
+ * original "read at run time, not schedule time" contract this whole file's header calls out:
+ * `deps.currentTicket()`/`deps.hasUnsavedEdits()` are called from inside this function, at the same
+ * points the inline version read `saveTicket.current`/`hasUnsavedEdits.current` directly, so a
+ * ticket or edit that changes while `runSave` is in flight is still seen correctly.
+ *
+ * @param ticket - This link's own ticket, taken by the caller when the debounce timer fired.
+ */
+export async function commitQueuedSave({ ticket, deps }, _options = {}) {
+    try {
+        const written = await deps.runSave();
+        if (deps.currentTicket() !== ticket)
+            return;
+        // A newer edit is already queued behind this one, so "Saved" would be a claim about state
+        // that is not saved. Stay in "saving".
+        if (deps.hasUnsavedEdits())
+            return;
+        deps.setSaveState(written.length > 0 ? { status: "saved" } : { status: "idle" });
+    }
+    catch (error) {
+        if (deps.currentTicket() !== ticket)
+            return;
+        deps.setSaveState({
+            status: "error",
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Whether a background `refresh()` reload may still land, given what is true about the slice's
+ * uncommitted-work state at the moment of the check.
+ *
+ * Pulled out of `refresh` (2026-08-06, complexity pass, third pass): the same four-flag shape is
+ * checked TWICE inside `refresh` — once before the `load()` await (where `mounted`/`commitsUnchanged`
+ * are trivially true, since nothing could have unmounted or committed a save before the function has
+ * even started awaiting), once after (where all four are live) — and collapsing the check into one
+ * named function removes the duplicated branch count rather than moving it. This does not change
+ * WHEN any ref is read: every call site below still reads `timer.current`/`hasUnsavedEdits.current`/
+ * `mounted.current`/`commits.current` at exactly the point in `refresh`'s own body the inline version
+ * did, in the same tick — this function only names the boolean combination those reads produce. See
+ * `refresh`'s own doc for why a re-check after the await is necessary at all.
+ */
+export function canAcceptRefresh(state, _options = {}) {
+    return !state.timerPending && !state.hasUnsavedEdits && state.mounted && state.commitsUnchanged;
+}
+/**
+ * @complexity O(1) per edit — one debounce timer reset plus one link appended
+ * to the save chain.
+ *
+ * @complexityExemption (2026-08-06, complexity pass, third pass; bar raised to ≤9/≤9 same day,
+ * exemption reconfirmed against the new bar) **Score: this hook's own lexical scope is 1
+ * cyclomatic / ~0 cognitive under ESLint — every closure inside it is independently ≤9/≤9 too
+ * (`onChange`'s debounce callback is 2/1, the unmount-flush cleanup is 3/2, `refresh` is 5/4 as of
+ * this pass — see below). What is exempted here is a DIFFERENT, unmeasurable-by-me number: the
+ * dispatch brief's owner-tool score of 17/23, which rolls every nested closure's branches into the
+ * hook's total. Bar: ≤9/≤9 on whichever view is scored — ESLint's view already clears it; the
+ * owner-tool aggregate does not, and I have no local tool that reproduces that aggregate to
+ * re-measure against the new bar.**
+ *
+ * Same shape as `use-assistant-chats.hooks.ts`'s `useAssistantChats` exemption — see that one for
+ * the full reasoning. `commitQueuedSave` (first pass) and `canAcceptRefresh` (this pass, pulled out
+ * of `refresh`'s two duplicated guard checks — see its own doc) are the two pieces of this hook's
+ * logic that genuinely fit a top-level pure-function shape (0–4 plain params, no ref reads);
+ * `refresh` itself dropped from 9/5 to 5/4 as a result, its own per-function score real progress,
+ * not exempted. What remains (`runSave`/`onChange`/the unmount cleanup/the rest of `refresh`) each
+ * reads or writes 3–6 of this hook's own refs (`io`, `persisted`, `latest`, `timer`,
+ * `saveTicket`, `hasUnsavedEdits`, `commits`, `mounted`) plus the shared `writes` lane, and several of
+ * them call each other
+ * (`onChange` schedules a link that calls `runSave`; the unmount cleanup calls `runSave` directly),
+ * so none of them can become a top-level function without threading that whole ref set through as a
+ * parameter object. This file's own header states the reason that is dangerous here specifically:
+ * "a value read at schedule time is a claim about the store that may already be false by the time
+ * the code using it runs," and every ref above exists because an earlier version of exactly this
+ * logic got that ordering wrong (four distinct data-loss bugs, per the header). A previous pass
+ * already tried this kind of extraction on this file and the total was unchanged, 25 → 25 — the
+ * honest reading of that result is that the remaining closures do not have a top-level-shaped cut
+ * available at the risk level a time-boxed pass allows, not that the attempt was done wrong.
+ * Declined for the remainder; flagged to the coordinator. See this session's report for the full
+ * reasoning.
+ */
+export function useSettingsSlice(options, _optional = {}) {
+    const { defaultValue } = options;
+    const [value, setValue] = useState(null);
+    const [loadError, setLoadError] = useState(null);
+    const [saveState, setSaveState] = useState({ status: "idle" });
+    /** Guards `refresh`'s own `setValue`/`persisted`/`latest` write against a second background
+     *  refresh started after it: `canAcceptRefresh`'s `commitsUnchanged` check cannot tell two
+     *  refreshes apart when no save happens between them (both sample the same `commits.current`),
+     *  so without this an older refresh call that happens to SETTLE last could still land over a
+     *  newer one's result (S2, plan-components.md 2026-09-20; two rapid SSE frames from another
+     *  tab's writes is the trigger). Same guard `use-admin-execution-credential.hooks.ts`'s `refresh`
+     *  and `use-admin-locale.hooks.ts`'s `fetchLocale` already use for the identical shape. */
+    const refreshSettlement = useSettlementGeneration();
+    /** `load`/`save` are usually inline arrows at the call site, so a new
+     *  identity arrives on every render. Holding them in a ref keeps the effect
+     *  and callback below from re-running (and re-loading, and dropping pending
+     *  timers) once per render. */
+    const io = useRef(options);
+    io.current = options;
+    /** Last value known to be persisted — the diff base handed to `save`. */
+    const persisted = useRef(defaultValue);
+    /** The newest value the operator has produced, saved or not. A queued save
+     *  writes THIS rather than whatever was current when it was scheduled, so a
+     *  save that waited behind another still persists the latest state instead
+     *  of resurrecting an intermediate one. */
+    const latest = useRef(defaultValue);
+    const timer = useRef(null);
+    /**
+     * Saves run strictly one at a time, queued through this lane.
+     *
+     * The debounce alone does NOT prevent overlap: it only cancels a save that
+     * has not STARTED. Once one is in flight, the next edit schedules a fresh
+     * timer that can fire while the first is still running, and then two saves
+     * race — their per-key writes interleave (so the ledger can end on the older
+     * value), and both diff against the same `persisted` base, which the slower
+     * one then overwrites on completion. That leaves the diff base claiming a
+     * value was persisted that never was, so the next edit skips writing the
+     * fields it thinks are already saved.
+     */
+    const writes = useSerialWrites();
+    /** Monotonic ticket, so only the newest save may write the status
+     *  indicator. Without it a slow earlier save resolving last would paint
+     *  "Saved" over a newer save's error, or vice versa. */
+    const saveTicket = useRef(0);
+    /**
+     * True whenever `latest` has moved ahead of `persisted` — i.e. the operator
+     * has edited something no save has committed yet.
+     *
+     * The ticket alone does NOT cover this. A ticket is only taken when a
+     * DEBOUNCE TIMER FIRES, so an edit made while an earlier save is still in
+     * flight has no ticket yet: the in-flight save still owns the newest one,
+     * completes, and paints "Saved" over changes that are not saved at all. If
+     * the operator then navigates away, unmount clears the pending timer and
+     * those edits are gone — with the UI's last word having been "Saved".
+     */
+    const hasUnsavedEdits = useRef(false);
+    /**
+     * Bumped every time a save commits and advances `persisted`.
+     *
+     * `refresh` samples it before its `load()` round trip and discards the
+     * response if it moved. The two flag checks cannot cover this on their own:
+     * `timer` and `hasUnsavedEdits` describe work that is still OUTSTANDING, and
+     * a save that both started and finished inside the reload's await window
+     * clears them, so a response that predates that write passes every check.
+     * Letting it through does not merely repaint a stale value — it installs it
+     * as the diff base, so the next edit diffs against a value the store never
+     * held and skips writing the fields that differ.
+     */
+    const commits = useRef(0);
+    /** Guards every post-await `setState` in {@link refresh}, which — unlike the
+     *  mount load — can be invoked at any time by an external publisher. */
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    // `defaultValue` is a module-level constant at every call site; re-running
+    // this on a new identity would re-issue the load and clobber live edits.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `defaultValue` is a module-level constant; re-running on a new identity would re-issue the load and clobber live edits.
+    useEffect(() => {
+        let alive = true;
+        io.current
+            .load({}, {})
+            .then((loaded) => {
+            if (!alive)
+                return;
+            // `persisted` always takes the raw load, same as `refresh()` — it is the diff base the next
+            // save diffs against, and the server's real state is a strictly better base than the
+            // never-actually-persisted `defaultValue` this ref started at, whether or not the operator
+            // has since edited.
+            persisted.current = loaded;
+            // Guards the same hazard `refresh()` guards via `canAcceptRefresh`'s `hasUnsavedEdits` check,
+            // on the OTHER load path: `onChange` has no documented precondition requiring `value` to be
+            // non-null first, so nothing stops an edit from landing before this initial `load()` settles.
+            // Without this check, that edit is silently overwritten the instant the response arrives —
+            // the same class of data loss this file's four prior audited bugs all belong to.
+            if (hasUnsavedEdits.current)
+                return;
+            latest.current = loaded;
+            setValue(loaded);
+        })
+            .catch((error) => {
+            if (!alive)
+                return;
+            setLoadError(error instanceof Error ? error.message : String(error));
+            if (hasUnsavedEdits.current)
+                return;
+            setValue(defaultValue);
+        });
+        return () => {
+            alive = false;
+        };
+    }, []);
+    /**
+     * The only place a save is ever issued.
+     *
+     * Both the target and the diff base are read at RUN time, never at schedule
+     * time. By the time a chained link runs, an earlier save may already have
+     * advanced `persisted` and the operator may have edited further, so anything
+     * captured when the link was queued is potentially a lie about the store.
+     *
+     * This exists as one function rather than two call sites because the second
+     * call site is exactly where that invariant was lost: the unmount flush used
+     * to snapshot both values as it queued itself behind an in-flight save, so
+     * edit A→B, revert B→A, unmount produced `save(A, A)` — an empty diff — and
+     * the revert was dropped while the store kept B. Sharing the runner makes the
+     * rule structural instead of something each caller has to remember.
+     */
+    const runSave = useCallback(async () => {
+        const target = latest.current;
+        const written = await io.current.save({ next: target, previous: persisted.current }, {});
+        // `persisted` is deliberately advanced only here, after a resolved save, so
+        // a rejection leaves the base alone and the next save re-attempts the
+        // fields this one could not write.
+        persisted.current = target;
+        commits.current += 1;
+        // Only clear the flag if nothing was edited WHILE this save ran.
+        if (latest.current === target)
+            hasUnsavedEdits.current = false;
+        // Notify same-tab siblings this slice has no direct connection to — same rationale
+        // `settings-refresh-bus.ts`'s own doc comment gives for `AssistantDock`: this slice and
+        // whatever else reads this namespace (e.g. `useAdminLocale()`, read by ~30 screens outside the
+        // Settings dialog for `core.language`) are unrelated subtrees under `App.tsx` with no shared
+        // state. Without this, a language switch only reached OTHER tabs via SSE — the tab that made
+        // the change never re-read its own write, so it looked "stuck" until a hard reload. Scoped to
+        // this slice's own declared `namespaces`, so an unrelated slice's save doesn't trigger a
+        // pointless refetch elsewhere; a slice that never declared `namespaces` publishes nothing,
+        // matching that it never subscribed to anything either.
+        if (io.current.namespaces && io.current.namespaces.length > 0) {
+            io.current.refreshPort.publish({ namespaces: io.current.namespaces }, {});
+        }
+        return written;
+    }, []);
+    // On unmount, don't just drop a debounced edit — run it. Cancelling the
+    // timer silently discards whatever the operator typed in the last 600ms.
+    useEffect(() => () => {
+        if (!timer.current)
+            return;
+        clearTimeout(timer.current);
+        if (!hasUnsavedEdits.current)
+            return;
+        // Fire-and-forget: the component is going away, so there is no status
+        // left to paint. The write itself still has to happen — through the same
+        // lane as the debounce path, so it diffs against the base that is
+        // current when it RUNS, not the one that was current when it was queued.
+        void writes.run({ task: () => runSave().then(() => { }, () => { }) });
+    }, [runSave, writes]);
+    const onChange = useCallback((next) => {
+        setValue(next);
+        latest.current = next;
+        hasUnsavedEdits.current = true;
+        if (timer.current)
+            clearTimeout(timer.current);
+        timer.current = setTimeout(() => {
+            // Cleared as the timer FIRES, so `timer.current` means "a debounce is still pending" rather
+            // than "one was ever scheduled". The unmount flush below already pairs it with
+            // `hasUnsavedEdits`, so it tolerated a stale handle; `refresh` reads it alone as the
+            // "operator has work in flight" signal, and a handle that never cleared would refuse every
+            // external refresh for the rest of the component's life after the first keystroke.
+            timer.current = null;
+            const ticket = ++saveTicket.current;
+            setSaveState({ status: "saving" });
+            void writes.run({ task: () => commitQueuedSave({ ticket, deps: {
+                        runSave,
+                        currentTicket: () => saveTicket.current,
+                        hasUnsavedEdits: () => hasUnsavedEdits.current,
+                        setSaveState,
+                    } }, {}) });
+        }, SAVE_DEBOUNCE_MS);
+    }, [runSave, writes]);
+    /**
+     * Re-reads the persisted value on an external notification.
+     *
+     * **Refuses whenever the operator has uncommitted work**, rather than merging. Three states count
+     * as uncommitted: a pending debounce timer, `hasUnsavedEdits`, and a non-idle save. Overwriting
+     * any of them replaces what the operator typed with a value from somewhere else, mid-keystroke —
+     * data loss, and the same class of bug the audit already found twice in this file. Refusing costs
+     * only a missed update, and the operator's own save re-establishes agreement a moment later.
+     *
+     * The check runs AGAIN after the await: `load()` is a network round trip, and an edit begun while
+     * it was in flight would otherwise be clobbered by a response that predates it.
+     *
+     * Re-checking the flags is necessary but NOT sufficient, which is why {@link commits} is sampled
+     * too. Both flags describe work that is still outstanding, so a save that started and finished
+     * entirely within the await window leaves them clear and the stale response sails through — see
+     * the counter's own doc for why that is worse than a wrong repaint.
+     *
+     * A failed reload is swallowed on purpose. This is a background refresh the operator never asked
+     * for; surfacing `loadError` here would replace a working panel with an error state because of a
+     * transient blip. The mount load still reports its failures.
+     */
+    const refresh = useCallback(async () => {
+        if (!canAcceptRefresh({
+            timerPending: timer.current !== null,
+            hasUnsavedEdits: hasUnsavedEdits.current,
+            mounted: true,
+            commitsUnchanged: true,
+        })) {
+            return;
+        }
+        const seenCommits = commits.current;
+        const generation = refreshSettlement.next();
+        let loaded;
+        try {
+            loaded = await io.current.load({}, {});
+        }
+        catch {
+            return;
+        }
+        if (!refreshSettlement.isCurrent({ generation }) ||
+            !canAcceptRefresh({
+                timerPending: timer.current !== null,
+                hasUnsavedEdits: hasUnsavedEdits.current,
+                mounted: mounted.current,
+                commitsUnchanged: commits.current === seenCommits,
+            })) {
+            return;
+        }
+        // `persisted` tracks what `load`/`save` actually manage, so it takes the RAW reload — a
+        // reconciled field like a never-persisted API key has no business in the diff base `save` will
+        // next diff against. `latest`/`value` are what the operator sees and edits next, so THEY take
+        // the reconciled result.
+        const reconciled = io.current.reconcileRefresh ? io.current.reconcileRefresh({ current: latest.current, loaded }, {}) : loaded;
+        persisted.current = loaded;
+        latest.current = reconciled;
+        setValue(reconciled);
+    }, []);
+    /**
+     * Subscribes to out-of-band changes — an assistant run that wrote a setting, or an SSE frame from
+     * a write in another tab. `namespaces` narrows which notifications matter; see the option's doc
+     * for why omitting it means "refresh on everything" rather than "never".
+     */
+    const refreshPort = options.refreshPort;
+    useEffect(() => {
+        return refreshPort.subscribe({ listener: (scope) => {
+                const mine = io.current.namespaces;
+                if (scope && mine && !mine.some((ns) => scope.includes(ns)))
+                    return;
+                void refresh();
+            } }, {});
+    }, [refresh, refreshPort]);
+    return { value, loadError, saveState, onChange, refresh };
+}
+/**
+ * Collapses several slices' save states into the single one the page chrome
+ * renders.
+ *
+ * Precedence is error > saving > saved > idle, and it is deliberate: an error
+ * is the only state the operator must act on, so it must not be hidden by
+ * another tab's cheerful "Saved". "Saving" outranks "saved" for the same
+ * reason in miniature — while anything is still in flight, claiming everything
+ * is saved is false.
+ */
+export function mergeSaveStates({ states }, _options = {}) {
+    const failed = states.find((state) => state.status === "error");
+    if (failed)
+        return failed;
+    if (states.some((state) => state.status === "saving"))
+        return { status: "saving" };
+    if (states.some((state) => state.status === "saved"))
+        return { status: "saved" };
+    return { status: "idle" };
+}
+//# sourceMappingURL=use-settings-slice.hooks.js.map

package/dist/features/panel-kit/hooks/use-standing-draft-autosave.hooks.d.ts

@@ -0,0 +1,179 @@
+import type { createStandingDraftLocalBackup } from "../helpers/standing-draft-local-backup.js";
+/**
+ * @file Standing-draft autosave (2026-09-06 dispatch, owner's own words: "even if they haven't
+ * saved it, temp save it whenever they make a draft... it's just saving to... the database. It
+ * should be a standing draft anytime something is updated"). Persists to the server
+ * (`server/inbound/admin-http/routes/posts/autosave.ts`, `posts.autosave_json`) so a reload or an
+ * accidental exit never loses unsaved edits — browser storage alone was rejected.
+ *
+ * Feature-agnostic on purpose, matching `use-dirty-guard.hooks.ts`'s own precedent: nothing here
+ * imports `features/posts` or `features/pages`, so `PostEditorPort`/`PageEditorPort` each satisfy
+ * {@link StandingDraftAutosavePort} structurally (same three method shapes, declared independently
+ * per that DI-seam convention) with zero cross-feature import. This is the mechanism that lets one
+ * implementation serve both editors with no branch between them.
+ *
+ * Two things this hook does NOT do, deliberately:
+ * - Never auto-applies a recovered draft. {@link StandingDraftAutosaveController.recoverableDraft}
+ *   is exposed for the caller to render an explicit "restore or discard" banner; silently splicing
+ *   in a recovered draft is dangerous with two tabs or two operators open on the same entry.
+ * - Never compares `recoverableDraft.baseVersion` against the entry's current version itself — the
+ *   caller (which already has the freshly-loaded record) decides whether to label a recovered draft
+ *   "outdated" because a real save happened since it was captured.
+ *
+ * STALE BASIS (added 2026-09-06, fixing silent data loss). `putAutosave` answers `{ applied }`, and
+ * `applied: false` means the row's `version` moved under this tab — another tab or operator saved,
+ * so every further write against this basis will be refused too (the guard is
+ * `host features/post/repo.sqlite.ts`'s `writeAutosave`). That flag used to be thrown
+ * away: the hook kept firing refused ticks forever, nothing was ever parked, and a reload produced
+ * no recovery banner because there was nothing to recover — an hour of typing could vanish with the
+ * operator never told anything. Now a refusal:
+ * 1. records {@link StandingDraftStaleBasis} (exposed so the editor can say something true),
+ * 2. stops scheduling further writes until the caller supplies a draft on a DIFFERENT `baseVersion`
+ *    — i.e. until the editor reloads the row; no manual reset call is needed,
+ * 3. mirrors the refused text into `lib/standing-draft-local-backup.ts`, the only place it can
+ *    survive a tab close while the server refuses it, and offers it back through the existing
+ *    `recoverableDraft` banner on the next mount when the server has nothing parked.
+ * The operator's in-memory text is never touched by any of this.
+ *
+ * The gate and the mirror have DIFFERENT lifetimes on purpose. The gate lifts the instant the
+ * caller edits on a fresh basis; the mirror survives until the server has actually accepted a write
+ * (or a real Save/discard superseded it), because between those two moments nothing has been
+ * persisted anywhere and the mirror is still the only copy of the refused text that outlives the
+ * tab. Collapsing the two back into one "clear it all" step reintroduces a window in which a failed
+ * request loses the work.
+ */
+/** The fields a standing draft carries — see `PostAutosaveSnapshot`'s own server-side doc for why
+ *  `status` is deliberately absent (a draft must never change whether a row is live). */
+export type StandingDraftAutosaveInput = {
+    bodyFormat: "doc";
+    bodyJson: Record<string, unknown>;
+    title: string;
+    slug: string;
+    baseVersion: number;
+} | {
+    bodyFormat: "html";
+    bodyHtml: string;
+    title: string;
+    slug: string;
+    baseVersion: number;
+};
+export interface StandingDraftAutosaveSnapshot {
+    bodyFormat: "doc" | "html";
+    bodyJson?: Record<string, unknown>;
+    bodyHtml?: string;
+    title: string;
+    slug: string;
+    baseVersion: number;
+    savedAt: string;
+    savedByPrincipalId: string;
+    /** Fresh server timestamp used only for the explicit recovery comparison. */
+    serverUpdatedAt?: string | undefined;
+}
+/** What this hook needs from the outside world — see this file's header for why it is declared
+ *  here rather than imported from either feature's own port. */
+export interface StandingDraftAutosavePort {
+    /** Captured before expiry so late failures cannot borrow the next operator's identity. */
+    getBackupPrincipalId?: (requiredArgs: Record<string, never>, optionalArgs?: Record<string, never>) => string | null;
+    /**
+     * `options.keepalive` (2026-09-07) asks for an UNLOAD-SAFE transport, and is set only by the exit
+     * flush below. An ordinary `fetch` started from `pagehide` or `visibilitychange`→hidden is
+     * cancelled when the browser tears the document down — so the newest edit, the one still sitting
+     * in the debounce window, was precisely the one those listeners could not actually rescue.
+     *
+     * Opt-in rather than always-on because `keepalive` carries a 64 KiB body ceiling an ordinary
+     * request does not; an implementation that cannot honour it may ignore it (the parameter is
+     * optional), which is exactly the behavior this path had before.
+     */
+    putAutosave(required: {
+        id: string;
+        draft: StandingDraftAutosaveInput;
+    }, options?: {
+        keepalive?: boolean;
+    }): Promise<{
+        applied: boolean;
+    }>;
+    getAutosave(required: {
+        id: string;
+    }, optional?: Record<string, never>): Promise<{
+        autosave: StandingDraftAutosaveSnapshot | null;
+    }>;
+    discardAutosave(required: {
+        id: string;
+    }, optional?: Record<string, never>): Promise<{
+        ok: boolean;
+    }>;
+}
+/** A write the server refused because the row moved on — see this file's header. Carries the
+ *  operator's refused text itself, not just a flag: it is the copy nothing else on the client has
+ *  a claim to, and a conflict notice that drops the work would be worse than the silent drop. */
+export interface StandingDraftStaleBasis {
+    /** The `baseVersion` the refused draft was built on. The gate lifts when a later
+     *  `scheduleAutosave` arrives on a different one. */
+    baseVersion: number;
+    /** Exactly what was refused. */
+    draft: StandingDraftAutosaveInput;
+}
+export interface StandingDraftAutosaveController {
+    /** Non-null once the mount-time recovery check resolves and finds a parked draft. Stays exactly
+     *  as read until {@link dismissRecoverable}/{@link clearStandingDraft} clears it — never
+     *  overwritten by a later `scheduleAutosave` tick from THIS session, since a session that is
+     *  actively autosaving has, by definition, already accounted for whatever it found on mount. */
+    recoverableDraft: StandingDraftAutosaveSnapshot | null;
+    /** Non-null once the server has refused a write for this entry, and until the caller edits on a
+     *  fresh basis (or a real Save/discard runs). While it is set, `scheduleAutosave` deliberately
+     *  sends nothing — every such write would be refused. The editor should tell the operator that
+     *  another save happened, that reloading is what resumes autosaving, and that their text is kept.
+     *  Purely additive: a caller that ignores it behaves exactly as before EXCEPT that refused writes
+     *  are no longer retried forever. */
+    staleBasis: StandingDraftStaleBasis | null;
+    /** Clears `recoverableDraft` locally only (no server call) — the "Discard" affordance calls
+     *  {@link clearStandingDraft} instead, which also tells the server; this is for a caller that
+     *  wants to stop showing the banner without discarding anything (e.g. "Restore" applied it into
+     *  the editor, and a real Save moments later will clear the server-side draft on its own). */
+    dismissRecoverable: () => void;
+    /** Call on every content change the caller wants protected — cheap, debounced internally
+     *  (idle 3s / 15s hard ceiling while continuously typing), safe to call on every keystroke.
+     *  Whatever is still sitting in the debounce window when the editor goes away is written by the
+     *  flush this hook wires up itself — see the `flushPendingAutosave` effects below. */
+    scheduleAutosave: (draft: StandingDraftAutosaveInput) => void;
+    /**
+     * Clears the server-side standing draft — call after a real Save/Publish succeeds, or when the
+     * operator explicitly discards a recovered draft. Cancels any pending (not yet fired) debounce
+     * timer FIRST, then enqueues the discard onto the same serial request chain every
+     * `scheduleAutosave` tick uses, so a still-in-flight (already fired) autosave write is guaranteed
+     * to reach the server before this discard does, and no new one can be queued after it — the
+     * ordering guarantee that keeps a late autosave from resurrecting content a real save (or an
+     * explicit discard) just superseded.
+     */
+    clearStandingDraft: () => Promise<void>;
+    /**
+     * The caller replaced its basis with a newer saved row it did not write itself (an assistant
+     * write applied by `use-external-entry-refresh.hooks.ts`, silently or through Load latest). Every
+     * write built on an OLDER `baseVersion` is superseded from here on: a pending one is cancelled, a
+     * later `scheduleAutosave` on one is dropped (a render that committed before the replacement can
+     * still run its autosave effect after this call), and the refusal of one already in flight is
+     * ignored. Without this, that write reached the server, was refused, paused autosaving and
+     * mirrored text for a version the editor had already left (reviewer finding 2, 2026-09-16).
+     *
+     * A gate recorded on an older basis lifts, because the editor is no longer on it. That refusal's
+     * mirror is kept: nothing has accepted its text anywhere (see this file's header). Does not touch
+     * the server-side draft — Load latest also calls {@link clearStandingDraft} for that.
+     */
+    supersedeBasis: (baseVersion: number) => void;
+    preserveFailedSave: (requiredArgs: {
+        error: unknown;
+        draft: StandingDraftAutosaveInput;
+    }, optionalArgs?: Record<string, never>) => void;
+}
+export interface StandingDraftAutosaveOptions {
+    port: StandingDraftAutosavePort;
+    backup: ReturnType<typeof createStandingDraftLocalBackup>;
+    /** `null` before the entry has loaded (or for a not-yet-created entry) — every operation no-ops. */
+    entryId: string | null;
+    /** Gate for "this editor is in a state where autosave should run at all" (e.g. not while a save
+     *  or delete is already in flight). Recovery-check and scheduling both respect it. */
+    enabled: boolean;
+    serverUpdatedAt?: string | undefined;
+}
+export declare function useStandingDraftAutosave(deps: StandingDraftAutosaveOptions, _options?: Record<string, never>): StandingDraftAutosaveController;
+//# sourceMappingURL=use-standing-draft-autosave.hooks.d.ts.map