@simmalugnt-se/payload-editor-assistant 0.3.3 → 0.5.0

package/dist/components/assistant-api.js

@@ -1,5 +1,99 @@
 import { CSRF_HEADER, ENDPOINT_PREFIX } from "../package-name.js";
 export async function assistantRequest(apiBase, path, body, signal) {
+    const response = await post(apiBase, path, body, signal);
+    if (!(response instanceof Response)) {
+        return response;
+    }
+    const payload = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        return {
+            ok: false,
+            error: payload.error ?? "provider_error",
+            message: payload.message,
+            status: response.status,
+        };
+    }
+    return { ok: true, data: payload };
+}
+/**
+ * Like `assistantRequest`, for a turn answered as NDJSON: `onEvent` gets each `step` and `proposal`
+ * event as it arrives, and the result is the final `done` (or `error`) event. A server that answers
+ * with plain JSON instead still works.
+ */
+export async function assistantStream(apiBase, path, body, onEvent, signal) {
+    const response = await post(apiBase, path, { ...body, stream: true }, signal);
+    if (!(response instanceof Response)) {
+        return response;
+    }
+    const type = response.headers.get("content-type") ?? "";
+    if (!response.ok || !response.body || !type.includes("ndjson")) {
+        const payload = (await response.json().catch(() => ({})));
+        return response.ok
+            ? { ok: true, data: payload }
+            : {
+                ok: false,
+                error: payload.error ?? "provider_error",
+                message: payload.message,
+                status: response.status,
+            };
+    }
+    let final;
+    await readNdjson(response.body, (event) => {
+        if (event.type === "done") {
+            final = { ok: true, data: event.result };
+        }
+        else if (event.type === "error") {
+            final = {
+                ok: false,
+                error: typeof event.error === "string" ? event.error : "provider_error",
+                message: typeof event.message === "string" ? event.message : undefined,
+                status: response.status,
+            };
+        }
+        else {
+            onEvent(event);
+        }
+    });
+    return final ?? { ok: false, error: "provider_error", status: response.status };
+}
+/** Calls `handle` with each JSON object line; chunks may split a line anywhere. */
+export async function readNdjson(body, handle) {
+    const parse = (line) => {
+        if (!line.trim()) {
+            return;
+        }
+        try {
+            const event = JSON.parse(line);
+            if (event && typeof event.type === "string") {
+                handle(event);
+            }
+        }
+        catch {
+            // A line that is not JSON is skipped.
+        }
+    };
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffered = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        buffered += decoder.decode(value, { stream: true });
+        const lines = buffered.split("\n");
+        buffered = lines.pop() ?? "";
+        for (const line of lines) {
+            parse(line);
+        }
+    }
+    parse(buffered + decoder.decode());
+}
+/**
+ * Posts with a fresh CSRF token. Fetching one replaces the cookie, so requests must not overlap: the
+ * earlier one would carry a token that no longer matches.
+ */
+async function post(apiBase, path, body, signal) {
     const csrfResponse = await fetch(`${apiBase}${ENDPOINT_PREFIX}/csrf`, {
         credentials: "include",
         signal,
@@ -11,7 +105,7 @@ export async function assistantRequest(apiBase, path, body, signal) {
     if (!csrf.token) {
         return { ok: false, error: "unauthorized", status: 401 };
     }
-    const response = await fetch(`${apiBase}${ENDPOINT_PREFIX}${path}`, {
+    return fetch(`${apiBase}${ENDPOINT_PREFIX}${path}`, {
         method: "POST",
         credentials: "include",
         signal,
@@ -21,14 +115,4 @@ export async function assistantRequest(apiBase, path, body, signal) {
         },
         body: JSON.stringify(body),
     });
-    const payload = (await response.json().catch(() => ({})));
-    if (!response.ok) {
-        return {
-            ok: false,
-            error: payload.error ?? "provider_error",
-            message: payload.message,
-            status: response.status,
-        };
-    }
-    return { ok: true, data: payload };
 }

package/dist/components/assistant-context.d.ts

@@ -30,11 +30,21 @@ export type PendingApproval = {
         data: Record<string, unknown>;
         changedPaths: string[];
     };
-    /** Set once the preview is in the form: what to restore on undo. */
+    /**
+     * Set once the preview is in the form: what to restore on undo (the form before the first step)
+     * and `basis`, the form this proposal was made for, which keeping it is checked against.
+     */
     applied?: {
         before: Record<string, unknown>;
         beforeModified: boolean;
+        basis: Record<string, unknown>;
     };
+    /** Earlier proposals this one refines, oldest first; kept or undone together with it. */
+    earlier?: Array<{
+        approvalId: string;
+        nonce: string;
+        basis: Record<string, unknown>;
+    }>;
 };
 export type AssistantMessage = {
     id: string;
@@ -58,11 +68,17 @@ type AssistantContextValue = {
     pendingApproval: PendingApproval | null;
     /** What the editor last clicked or focused in the open form. */
     selection: DomSelection | null;
-    setOpen: (open: boolean) => void;
+    /** A prompt to put in the message box, e.g. from a work list link; the panel takes it once. */
+    prefill: string | null;
+    /** `remember: false` when the panel makes way on its own (see nav-room.ts), not the editor. */
+    setOpen: (open: boolean, options?: {
+        remember?: boolean;
+    }) => void;
     setBridge: (bridge: DocumentBridgeSnapshot | null) => void;
     setFormAdapter: (adapter: FormAdapter | null) => void;
     setPendingApproval: (pending: PendingApproval | null) => void;
     setSelection: (selection: DomSelection | null) => void;
+    setPrefill: (prefill: string | null) => void;
     setStatus: (status: AssistantChromeStatus) => void;
     setMessages: (updater: (current: AssistantMessage[]) => AssistantMessage[]) => void;
     resetConversation: () => void;
@@ -70,10 +86,12 @@ type AssistantContextValue = {
     abortController: AbortController | null;
     setAbortController: (controller: AbortController | null) => void;
 };
-export declare function AssistantStateProvider({ children, shortcuts, collections, }: {
+export declare function AssistantStateProvider({ children, shortcuts, collections, userId, }: {
     children: ReactNode;
     shortcuts: AssistantShortcut[];
     collections: string[];
+    /** Whose conversations the browser keeps; none are kept without a signed-in user. */
+    userId?: string | number;
 }): import("react").JSX.Element;
 export declare function useAssistantState(): AssistantContextValue;
 export {};

package/dist/components/assistant-context.js

@@ -1,8 +1,9 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { carriesOver, conversationKey, readConversation, sameConversation, writeConversation, } from "./conversation-store.js";
 const AssistantContext = createContext(null);
-export function AssistantStateProvider({ children, shortcuts, collections, }) {
+export function AssistantStateProvider({ children, shortcuts, collections, userId, }) {
     const [open, setOpenState] = useState(false);
     const [status, setStatus] = useState("idle");
     const [messages, setMessages] = useState([]);
@@ -11,15 +12,47 @@ export function AssistantStateProvider({ children, shortcuts, collections, }) {
     const [pendingApproval, setPendingApproval] = useState(null);
     const [abortController, setAbortController] = useState(null);
     const [selection, setSelection] = useState(null);
+    const [prefill, setPrefill] = useState(null);
     // Read after mount, so the server render (closed) and the first client render agree.
     useEffect(() => {
         if (readStoredOpen())
             setOpenState(true);
     }, []);
-    const setOpen = useCallback((next) => {
+    const setOpen = useCallback((next, { remember = true } = {}) => {
         setOpenState(next);
-        storeOpen(next);
+        if (remember) {
+            storeOpen(next);
+        }
     }, []);
+    // One conversation per document: switching documents stores the thread and loads the next one.
+    // An open proposal belongs to the form it was made for, so it does not follow; an unfinished
+    // request is stopped so its answer does not land in another document's thread.
+    const collectionSlug = bridge?.collectionSlug;
+    const globalSlug = bridge?.globalSlug;
+    const documentId = bridge?.documentId;
+    const hasBridge = bridge !== null;
+    const key = useMemo(() => conversationKey(userId, hasBridge ? { collectionSlug, globalSlug, documentId } : null), [userId, hasBridge, collectionSlug, globalSlug, documentId]);
+    const [loadedKey, setLoadedKey] = useState(null);
+    const abortRef = useRef(abortController);
+    abortRef.current = abortController;
+    useEffect(() => {
+        if (!key || sameConversation(key, loadedKey)) {
+            return;
+        }
+        abortRef.current?.abort();
+        setAbortController(null);
+        setStatus("idle");
+        setPendingApproval(null);
+        if (!carriesOver(loadedKey, key)) {
+            setMessages(readConversation(key));
+        }
+        setLoadedKey(key);
+    }, [key, loadedKey]);
+    useEffect(() => {
+        if (loadedKey && sameConversation(key, loadedKey)) {
+            writeConversation(loadedKey, messages);
+        }
+    }, [key, loadedKey, messages]);
     const stop = useCallback(() => {
         abortController?.abort();
         setAbortController(null);
@@ -42,11 +75,13 @@ export function AssistantStateProvider({ children, shortcuts, collections, }) {
         formAdapter,
         pendingApproval,
         selection,
+        prefill,
         setOpen,
         setBridge,
         setFormAdapter,
         setPendingApproval,
         setSelection,
+        setPrefill,
         setStatus,
         setMessages,
         resetConversation,
@@ -63,6 +98,7 @@ export function AssistantStateProvider({ children, shortcuts, collections, }) {
         formAdapter,
         pendingApproval,
         selection,
+        prefill,
         setOpen,
         resetConversation,
         stop,

package/dist/components/conversation-store.d.ts

@@ -0,0 +1,18 @@
+import type { AssistantMessage, DocumentBridgeSnapshot } from "./assistant-context.tsx";
+export type ConversationKey = {
+    kind: "stored";
+    key: string;
+}
+/** A create view: the thread lives in memory until the document is saved. */
+ | {
+    kind: "unsaved";
+    entity: string;
+};
+export declare function conversationKey(userId: string | number | undefined, bridge: Pick<DocumentBridgeSnapshot, "collectionSlug" | "globalSlug" | "documentId"> | null): ConversationKey | null;
+export declare function sameConversation(a: ConversationKey | null, b: ConversationKey | null): boolean;
+/** Saving a new document: the thread that created it becomes the document's own. */
+export declare function carriesOver(from: ConversationKey | null, to: ConversationKey): boolean;
+/** Storage can be unavailable or hold anything; a thread that cannot be read starts empty. */
+export declare function readConversation(key: ConversationKey): AssistantMessage[];
+export declare function writeConversation(key: ConversationKey, messages: AssistantMessage[]): void;
+export declare function parseStored(raw: string, now: number): AssistantMessage[];

package/dist/components/conversation-store.js

@@ -0,0 +1,102 @@
+/**
+ * Conversations are kept in the browser, one per user and document, plus one for everything outside
+ * a document (lists, dashboard). A document that is not saved yet has none of its own: its thread is
+ * carried over to the document once it gets an id.
+ */
+const PREFIX = "payload-editor-assistant:chat";
+const MAX_MESSAGES = 50;
+const MAX_AGE_MS = 30 * 24 * 60 * 60_000;
+export function conversationKey(userId, bridge) {
+    if (userId === undefined) {
+        return null;
+    }
+    const user = `${PREFIX}:${userId}`;
+    if (!bridge || (!bridge.collectionSlug && !bridge.globalSlug)) {
+        return { kind: "stored", key: `${user}:general` };
+    }
+    if (bridge.globalSlug) {
+        return { kind: "stored", key: `${user}:global:${bridge.globalSlug}` };
+    }
+    if (bridge.documentId === undefined || bridge.documentId === null || bridge.documentId === "") {
+        return { kind: "unsaved", entity: `collection:${bridge.collectionSlug}` };
+    }
+    return {
+        kind: "stored",
+        key: `${user}:collection:${bridge.collectionSlug}:${bridge.documentId}`,
+    };
+}
+export function sameConversation(a, b) {
+    if (!a || !b) {
+        return a === b;
+    }
+    return a.kind === "stored"
+        ? b.kind === "stored" && a.key === b.key
+        : b.kind === "unsaved" && a.entity === b.entity;
+}
+/** Saving a new document: the thread that created it becomes the document's own. */
+export function carriesOver(from, to) {
+    return (from?.kind === "unsaved" &&
+        to.kind === "stored" &&
+        to.key.includes(`:${from.entity}:`) &&
+        readConversation(to).length === 0);
+}
+/** Storage can be unavailable or hold anything; a thread that cannot be read starts empty. */
+export function readConversation(key) {
+    if (key.kind !== "stored") {
+        return [];
+    }
+    try {
+        const raw = window.localStorage.getItem(key.key);
+        return raw ? parseStored(raw, Date.now()) : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function writeConversation(key, messages) {
+    if (key.kind !== "stored") {
+        return;
+    }
+    try {
+        if (messages.length === 0) {
+            window.localStorage.removeItem(key.key);
+            return;
+        }
+        const stored = { savedAt: Date.now(), messages: messages.slice(-MAX_MESSAGES) };
+        window.localStorage.setItem(key.key, JSON.stringify(stored));
+    }
+    catch {
+        // Not remembered (full or blocked storage); the thread still works for this page.
+    }
+}
+export function parseStored(raw, now) {
+    try {
+        const stored = JSON.parse(raw);
+        if (typeof stored.savedAt !== "number" || now - stored.savedAt > MAX_AGE_MS) {
+            return [];
+        }
+        return Array.isArray(stored.messages)
+            ? stored.messages.filter(isMessage).map((message) => ({
+                id: message.id,
+                role: message.role,
+                text: message.text,
+                candidates: Array.isArray(message.candidates)
+                    ? message.candidates.filter(isCandidate)
+                    : undefined,
+            }))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+function isMessage(value) {
+    const message = value;
+    return (typeof message?.id === "string" &&
+        typeof message.text === "string" &&
+        (message.role === "user" || message.role === "assistant" || message.role === "system"));
+}
+function isCandidate(value) {
+    const candidate = value;
+    return typeof candidate?.href === "string" && typeof candidate.label === "string";
+}

package/dist/components/copy.d.ts

@@ -14,6 +14,16 @@ export declare const COPY: {
         readonly send: "Send";
         readonly stop: "Stop";
         readonly working: "Working…";
+        readonly steps: {
+            readonly thinking: "Thinking…";
+            readonly searching: "Searching the content…";
+            readonly reading: "Reading a document…";
+            readonly reading_form: "Reading the form…";
+            readonly proposing: "Preparing the change…";
+            readonly drafting: "Preparing the draft…";
+            readonly navigating: "Finding the page…";
+            readonly writing: "Writing the reply…";
+        };
         readonly selected: "Selected";
         readonly clearSelection: "Clear selection";
         readonly approve: "Approve";
@@ -25,6 +35,7 @@ export declare const COPY: {
         readonly previewHint: "Shown in the form and the preview. Nothing is saved yet.";
         readonly previewHintAutosave: "Shown in the form and the preview. The draft saves itself, but nothing is published.";
         readonly undoLosesEdits: "You edited the form after the suggestion. Undo removes those edits too.";
+        readonly refinedHint: "The list shows the latest adjustment. Undo takes the form back to before the first suggestion.";
         readonly requestFailed: "I could not complete that request.";
         readonly done: "Done.";
         readonly proposalFailed: "The proposal could not be applied.";
@@ -65,6 +76,16 @@ export declare const COPY: {
         readonly send: "Skicka";
         readonly stop: "Stoppa";
         readonly working: "Arbetar…";
+        readonly steps: {
+            readonly thinking: "Tänker…";
+            readonly searching: "Söker bland innehållet…";
+            readonly reading: "Läser ett dokument…";
+            readonly reading_form: "Läser formuläret…";
+            readonly proposing: "Förbereder ändringen…";
+            readonly drafting: "Förbereder utkastet…";
+            readonly navigating: "Letar upp sidan…";
+            readonly writing: "Skriver svaret…";
+        };
         readonly selected: "Markerat";
         readonly clearSelection: "Ta bort markering";
         readonly approve: "Godkänn";
@@ -76,6 +97,7 @@ export declare const COPY: {
         readonly previewHint: "Syns i formuläret och förhandsvisningen. Inget är sparat än.";
         readonly previewHintAutosave: "Syns i formuläret och förhandsvisningen. Utkastet sparas automatiskt, men inget publiceras.";
         readonly undoLosesEdits: "Du har ändrat i formuläret efter förslaget. Ångra tar bort de ändringarna också.";
+        readonly refinedHint: "Listan visar den senaste justeringen. Ångra tar formuläret tillbaka till hur det var före första förslaget.";
         readonly requestFailed: "Jag kunde inte slutföra det.";
         readonly done: "Klart.";
         readonly proposalFailed: "Förslaget kunde inte genomföras.";

package/dist/components/copy.js

@@ -15,6 +15,16 @@ export const COPY = {
         send: "Send",
         stop: "Stop",
         working: "Working…",
+        steps: {
+            thinking: "Thinking…",
+            searching: "Searching the content…",
+            reading: "Reading a document…",
+            reading_form: "Reading the form…",
+            proposing: "Preparing the change…",
+            drafting: "Preparing the draft…",
+            navigating: "Finding the page…",
+            writing: "Writing the reply…",
+        },
         selected: "Selected",
         clearSelection: "Clear selection",
         approve: "Approve",
@@ -26,6 +36,7 @@ export const COPY = {
         previewHint: "Shown in the form and the preview. Nothing is saved yet.",
         previewHintAutosave: "Shown in the form and the preview. The draft saves itself, but nothing is published.",
         undoLosesEdits: "You edited the form after the suggestion. Undo removes those edits too.",
+        refinedHint: "The list shows the latest adjustment. Undo takes the form back to before the first suggestion.",
         requestFailed: "I could not complete that request.",
         done: "Done.",
         proposalFailed: "The proposal could not be applied.",
@@ -66,6 +77,16 @@ export const COPY = {
         send: "Skicka",
         stop: "Stoppa",
         working: "Arbetar…",
+        steps: {
+            thinking: "Tänker…",
+            searching: "Söker bland innehållet…",
+            reading: "Läser ett dokument…",
+            reading_form: "Läser formuläret…",
+            proposing: "Förbereder ändringen…",
+            drafting: "Förbereder utkastet…",
+            navigating: "Letar upp sidan…",
+            writing: "Skriver svaret…",
+        },
         selected: "Markerat",
         clearSelection: "Ta bort markering",
         approve: "Godkänn",
@@ -77,6 +98,7 @@ export const COPY = {
         previewHint: "Syns i formuläret och förhandsvisningen. Inget är sparat än.",
         previewHintAutosave: "Syns i formuläret och förhandsvisningen. Utkastet sparas automatiskt, men inget publiceras.",
         undoLosesEdits: "Du har ändrat i formuläret efter förslaget. Ångra tar bort de ändringarna också.",
+        refinedHint: "Listan visar den senaste justeringen. Ångra tar formuläret tillbaka till hur det var före första förslaget.",
         requestFailed: "Jag kunde inte slutföra det.",
         done: "Klart.",
         proposalFailed: "Förslaget kunde inte genomföras.",

package/dist/components/nav-room.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Where Admin is too narrow for both, Payload's nav and the panel take turns: whichever the editor
+ * opened last stays, and the other comes back when it closes.
+ *
+ * - Opening the panel closes the nav; closing the panel opens it again.
+ * - Opening the nav closes the panel; closing the nav opens it again. Not while the assistant
+ *   answers or a proposal waits for Keep or Undo: then both stay, so the decision stays in view.
+ *
+ * Payload's saved nav preference and the editor's own panel choice are not changed.
+ */
+export declare function useNavRoom(): void;

package/dist/components/nav-room.js

@@ -0,0 +1,94 @@
+"use client";
+import { useNav } from "@payloadcms/ui";
+import { useEffect, useRef, useState } from "react";
+import { useAssistantState } from "./assistant-context.js";
+/**
+ * Payload lays out Admin by the window's width, not knowing the panel takes part of it. It closes
+ * its nav at 1440px and below; with the panel open, the space left is that narrow up to 1840px
+ * (the panel is `clamp(320px, 22vw, 400px)` wide, see assistant.css). Keep the two in step.
+ */
+const LEAVES_NARROW_ADMIN = "(max-width: 1840px)";
+/**
+ * Where Admin is too narrow for both, Payload's nav and the panel take turns: whichever the editor
+ * opened last stays, and the other comes back when it closes.
+ *
+ * - Opening the panel closes the nav; closing the panel opens it again.
+ * - Opening the nav closes the panel; closing the nav opens it again. Not while the assistant
+ *   answers or a proposal waits for Keep or Undo: then both stay, so the decision stays in view.
+ *
+ * Payload's saved nav preference and the editor's own panel choice are not changed.
+ */
+export function useNavRoom() {
+    const { navOpen, setNavOpen } = useNav();
+    const { open, setOpen, status, pendingApproval } = useAssistantState();
+    const busy = status === "streaming" || pendingApproval !== null;
+    const [narrow, setNarrow] = useState(false);
+    const navOpenRef = useRef(navOpen);
+    navOpenRef.current = navOpen;
+    /** The editor opened the nav with its toggler (not Payload restoring it on load). */
+    const editorOpenedNav = useRef(false);
+    /** The nav was opened while the panel was busy; leave it open until the panel closes. */
+    const navKept = useRef(false);
+    const closedNav = useRef(false);
+    const closedPanel = useRef(false);
+    useEffect(() => {
+        const query = window.matchMedia(LEAVES_NARROW_ADMIN);
+        const update = () => setNarrow(query.matches);
+        update();
+        query.addEventListener("change", update);
+        return () => query.removeEventListener("change", update);
+    }, []);
+    useEffect(() => {
+        const onClick = (event) => {
+            if (event.target instanceof Element &&
+                event.target.closest(".nav-toggler") &&
+                !navOpenRef.current) {
+                editorOpenedNav.current = true;
+            }
+        };
+        document.addEventListener("click", onClick, true);
+        return () => document.removeEventListener("click", onClick, true);
+    }, []);
+    useEffect(() => {
+        if (!navOpen) {
+            editorOpenedNav.current = false;
+            navKept.current = false;
+            if (closedPanel.current) {
+                closedPanel.current = false;
+                setOpen(true, { remember: false });
+            }
+            return;
+        }
+        if (!open || !narrow) {
+            editorOpenedNav.current = false;
+            return;
+        }
+        if (editorOpenedNav.current) {
+            editorOpenedNav.current = false;
+            if (busy) {
+                navKept.current = true;
+            }
+            else {
+                closedNav.current = false;
+                closedPanel.current = true;
+                setOpen(false, { remember: false });
+            }
+            return;
+        }
+        // The panel opened, or Payload opened the nav from the saved preference after the page loaded.
+        if (!navKept.current) {
+            closedNav.current = true;
+            setNavOpen(false);
+        }
+    }, [open, narrow, navOpen, busy, setNavOpen, setOpen]);
+    useEffect(() => {
+        if (open) {
+            return;
+        }
+        if (closedNav.current) {
+            setNavOpen(true);
+        }
+        closedNav.current = false;
+        navKept.current = false;
+    }, [open, setNavOpen]);
+}

package/dist/components/proposal-chain.d.ts

@@ -0,0 +1,22 @@
+import type { PendingApproval } from "./assistant-context.tsx";
+/** One server-side proposal and the form it was made for; keeping it is checked against that form. */
+export type ProposalStep = {
+    approvalId: string;
+    nonce: string;
+    basis: Record<string, unknown>;
+};
+/**
+ * A suggestion the editor refined before keeping it ("shorter", "another tone"). The new proposal
+ * was made against the form with the earlier one in it, so the chain keeps the form from before the
+ * first step for undo, and every step so each can be kept in order against its own form.
+ */
+export declare function refineProposal(open: PendingApproval, next: PendingApproval, basis: Record<string, unknown>): PendingApproval;
+/** Every step of an applied proposal, oldest first. */
+export declare function proposalSteps(pending: PendingApproval): ProposalStep[];
+/**
+ * The same turn produced a second proposal. It was made against the same form as the one it
+ * replaces, so it takes that step's place: undo and the earlier steps stay as they were.
+ */
+export declare function replaceLatestStep(current: PendingApproval, next: PendingApproval, basis: Record<string, unknown>): PendingApproval;
+/** A form proposal with the form it would produce: the only kind shown in the form before keeping. */
+export declare function isFormProposal(value: unknown): value is PendingApproval;

package/dist/components/proposal-chain.js

@@ -0,0 +1,57 @@
+/**
+ * A suggestion the editor refined before keeping it ("shorter", "another tone"). The new proposal
+ * was made against the form with the earlier one in it, so the chain keeps the form from before the
+ * first step for undo, and every step so each can be kept in order against its own form.
+ */
+export function refineProposal(open, next, basis) {
+    if (!open.applied) {
+        return next;
+    }
+    const changed = new Set([
+        ...(open.preview?.changedPaths ?? []),
+        ...(next.preview?.changedPaths ?? []),
+    ]);
+    return {
+        ...next,
+        preview: next.preview && { ...next.preview, changedPaths: [...changed] },
+        earlier: proposalSteps(open),
+        applied: { ...open.applied, basis },
+    };
+}
+/** Every step of an applied proposal, oldest first. */
+export function proposalSteps(pending) {
+    if (!pending.applied) {
+        return [];
+    }
+    return [
+        ...(pending.earlier ?? []),
+        { approvalId: pending.approvalId, nonce: pending.nonce, basis: pending.applied.basis },
+    ];
+}
+/**
+ * The same turn produced a second proposal. It was made against the same form as the one it
+ * replaces, so it takes that step's place: undo and the earlier steps stay as they were.
+ */
+export function replaceLatestStep(current, next, basis) {
+    if (!current.applied) {
+        return next;
+    }
+    const changed = new Set([
+        ...(current.preview?.changedPaths ?? []),
+        ...(next.preview?.changedPaths ?? []),
+    ]);
+    return {
+        ...next,
+        preview: next.preview && { ...next.preview, changedPaths: [...changed] },
+        earlier: current.earlier,
+        applied: { ...current.applied, basis },
+    };
+}
+/** A form proposal with the form it would produce: the only kind shown in the form before keeping. */
+export function isFormProposal(value) {
+    const pending = value;
+    return (pending?.capability === "form.propose" &&
+        typeof pending.approvalId === "string" &&
+        typeof pending.nonce === "string" &&
+        Boolean(pending.preview && typeof pending.preview.data === "object"));
+}