@getrefino/react 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/RefinoProvider.d.ts

@@ -2,6 +2,7 @@ import type { CopyContent } from "@getrefino/core";
 import type { JSX, ReactNode } from "react";
 import type { CopyRequestHeaders } from "./store.js";
 import type { EditorEventSink } from "./telemetry.js";
+import type { IntegrationUpdateSource } from "./updates.js";
 export interface RefinoProviderProps {
     /** The canonical copy, usually `import copy from "./content/copy.json"`. */
     content: CopyContent;
@@ -32,6 +33,13 @@ export interface RefinoProviderProps {
      * sites get a sink that posts to Refino; everyone else gets silence.
      */
     onEvent?: EditorEventSink | undefined;
+    /**
+     * Lets the toolbar offer updates to the site's Refino integration. Asked
+     * once per editing session; nothing in the repository changes unless the
+     * owner presses "Update Refino". Refino-connected sites get this from
+     * their generated client; everyone else leaves it out and sees nothing.
+     */
+    updates?: IntegrationUpdateSource | undefined;
     /** Render the built-in toolbar in edit mode. Set false to use `useCopyEditor` with custom UI. */
     toolbar?: boolean | undefined;
     children?: ReactNode | undefined;

package/dist/RefinoProvider.js

@@ -13,7 +13,7 @@ import { CopyEditorToolbar } from "./Toolbar.js";
  * the toolbar and editor styles.
  */
 export function RefinoProvider(props) {
-    const { content, editing = false, endpoint = "/api/copy", headers, signInHref = "/edit", onExit, onEvent, toolbar = true, children } = props;
+    const { content, editing = false, endpoint = "/api/copy", headers, signInHref = "/edit", onExit, onEvent, updates, toolbar = true, children } = props;
     // Created once. The sink is read through the ref below, so a host that
     // passes a new closure on every render neither recreates the store nor
     // replays a lifecycle event.
@@ -53,6 +53,6 @@ export function RefinoProvider(props) {
             window.removeEventListener("keydown", onKeyDown);
         };
     }, [editing, store]);
-    const value = useMemo(() => ({ store, onExit, signInHref }), [store, onExit, signInHref]);
+    const value = useMemo(() => ({ store, onExit, signInHref, updates }), [store, onExit, signInHref, updates]);
     return (_jsxs(CopyContext.Provider, { value: value, children: [children, editing && (_jsxs(_Fragment, { children: [_jsx("style", { "data-refino-styles": "", children: EDITOR_STYLES }), toolbar && _jsx(CopyEditorToolbar, {})] }))] }));
 }

package/dist/Toolbar.js

@@ -1,7 +1,8 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { INSTRUCTIONS_ID } from "./dom.js";
+import { UpdateButton, UpdatePanel, useIntegrationUpdate } from "./UpdateNotice.js";
 import { useCopyEditor } from "./useCopyEditor.js";
 function plural(count, word) {
     return `${count} ${word}${count === 1 ? "" : "s"}`;
@@ -18,6 +19,8 @@ export function CopyEditorToolbar() {
     const dirtyCount = dirtyIds.length;
     const activeDirty = state.activeId !== null && dirtyIds.includes(state.activeId);
     const busy = state.status === "saving" || state.status === "loading";
+    const update = useIntegrationUpdate(editor.updates, state.loaded);
+    const updateButtonRef = useRef(null);
     const onRevertSelected = useCallback(() => {
         if (state.activeId)
             editor.revertValue(state.activeId);
@@ -50,5 +53,5 @@ export function CopyEditorToolbar() {
             statusText = dirtyCount > 0 ? `${plural(dirtyCount, "unsaved change")}` : "No changes";
             dotClass = dirtyCount > 0 ? "dirty" : "";
     }
-    return (_jsxs("div", { className: "refino-toolbar", role: "region", "aria-label": "Copy editor", children: [_jsx("p", { id: INSTRUCTIONS_ID, className: "refino-sr-only", children: "Editable text. Type to change it. Press Enter to finish or Escape to cancel this edit." }), state.status === "conflict" && (_jsxs("div", { className: "refino-toolbar__notice refino-toolbar__notice--conflict", role: "alert", children: [_jsx("p", { children: "The copy file changed in the repository while you were editing (an AI agent or developer probably pushed). Your edits were not saved and nothing was overwritten." }), _jsxs("p", { children: ["Reload the latest copy and your ", plural(dirtyCount, "unsaved edit"), " will be reapplied on top of it for you to review and save again."] })] })), state.status === "error" && state.error && (_jsxs("div", { className: "refino-toolbar__notice refino-toolbar__notice--error", role: "alert", children: [_jsx("p", { children: state.error.message }), _jsxs("p", { children: [_jsx("code", { children: state.error.code }), state.error.code === "UNAUTHORIZED" && (_jsxs(_Fragment, { children: [" ", _jsx("a", { className: "refino-toolbar__link", href: editor.signInHref, children: "Sign in again" })] }))] })] })), state.rebase && (_jsxs("div", { className: "refino-toolbar__notice", role: "status", children: [state.rebase.overlapping.length > 0 && (_jsxs("p", { children: ["Both you and the repository changed:", " ", state.rebase.overlapping.map((id, index) => (_jsxs("span", { children: [index > 0 ? ", " : "", _jsx("code", { children: id })] }, id))), ". Your wording is shown; review before saving."] })), state.rebase.dropped.length > 0 && (_jsxs("p", { children: ["Dropped edits for fields that no longer exist:", " ", state.rebase.dropped.map((id, index) => (_jsxs("span", { children: [index > 0 ? ", " : "", _jsx("code", { children: id })] }, id))), "."] }))] })), _jsxs("div", { className: "refino-toolbar__bar", role: "toolbar", "aria-label": "Copy editor controls", children: [_jsxs("span", { className: "refino-toolbar__status", "aria-live": "polite", children: [_jsx("span", { className: `refino-toolbar__dot${dotClass ? ` refino-toolbar__dot--${dotClass}` : ""}` }), statusText, state.status === "saved" && state.lastSave?.commitUrl && (_jsxs(_Fragment, { children: [" ", _jsx("a", { className: "refino-toolbar__link", href: state.lastSave.commitUrl, target: "_blank", rel: "noreferrer", children: "view commit" })] }))] }), state.activeId && (_jsx("span", { className: "refino-toolbar__key", title: state.activeId, children: state.activeId })), state.status === "conflict" ? (_jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void editor.reloadLatest(), children: "Reload latest" })) : (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "refino-toolbar__button", onMouseDown: (event) => event.preventDefault(), onClick: onRevertSelected, disabled: !activeDirty || busy, title: "Revert the selected text to its saved value", children: "Revert" }), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: editor.revertAll, disabled: dirtyCount === 0 || busy, title: "Discard all unsaved changes", children: "Revert all" }), _jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void editor.save(), disabled: dirtyCount === 0 || busy || !state.loaded, title: "Save all changes (Ctrl/Cmd+S)", children: state.status === "saving" ? "Saving…" : "Save" })] })), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: () => void editor.exit(), disabled: busy, children: "Exit" })] })] }));
+    return (_jsxs("div", { className: "refino-toolbar", role: "region", "aria-label": "Copy editor", children: [_jsx("p", { id: INSTRUCTIONS_ID, className: "refino-sr-only", children: "Editable text. Type to change it. Press Enter to finish or Escape to cancel this edit." }), _jsx(UpdatePanel, { control: update, saving: state.status === "saving", buttonRef: updateButtonRef }), state.status === "conflict" && (_jsxs("div", { className: "refino-toolbar__notice refino-toolbar__notice--conflict", role: "alert", children: [_jsx("p", { children: "The copy file changed in the repository while you were editing (an AI agent or developer probably pushed). Your edits were not saved and nothing was overwritten." }), _jsxs("p", { children: ["Reload the latest copy and your ", plural(dirtyCount, "unsaved edit"), " will be reapplied on top of it for you to review and save again."] })] })), state.status === "error" && state.error && (_jsxs("div", { className: "refino-toolbar__notice refino-toolbar__notice--error", role: "alert", children: [_jsx("p", { children: state.error.message }), _jsxs("p", { children: [_jsx("code", { children: state.error.code }), state.error.code === "UNAUTHORIZED" && (_jsxs(_Fragment, { children: [" ", _jsx("a", { className: "refino-toolbar__link", href: editor.signInHref, children: "Sign in again" })] }))] })] })), state.rebase && (_jsxs("div", { className: "refino-toolbar__notice", role: "status", children: [state.rebase.overlapping.length > 0 && (_jsxs("p", { children: ["Both you and the repository changed:", " ", state.rebase.overlapping.map((id, index) => (_jsxs("span", { children: [index > 0 ? ", " : "", _jsx("code", { children: id })] }, id))), ". Your wording is shown; review before saving."] })), state.rebase.dropped.length > 0 && (_jsxs("p", { children: ["Dropped edits for fields that no longer exist:", " ", state.rebase.dropped.map((id, index) => (_jsxs("span", { children: [index > 0 ? ", " : "", _jsx("code", { children: id })] }, id))), "."] }))] })), _jsxs("div", { className: "refino-toolbar__bar", role: "toolbar", "aria-label": "Copy editor controls", children: [_jsxs("span", { className: "refino-toolbar__status", "aria-live": "polite", children: [_jsx("span", { className: `refino-toolbar__dot${dotClass ? ` refino-toolbar__dot--${dotClass}` : ""}` }), statusText, state.status === "saved" && state.lastSave?.commitUrl && (_jsxs(_Fragment, { children: [" ", _jsx("a", { className: "refino-toolbar__link", href: state.lastSave.commitUrl, target: "_blank", rel: "noreferrer", children: "view commit" })] }))] }), state.activeId && (_jsx("span", { className: "refino-toolbar__key", title: state.activeId, children: state.activeId })), state.status === "conflict" ? (_jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void editor.reloadLatest(), children: "Reload latest" })) : (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "refino-toolbar__button", onMouseDown: (event) => event.preventDefault(), onClick: onRevertSelected, disabled: !activeDirty || busy, title: "Revert the selected text to its saved value", children: "Revert" }), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: editor.revertAll, disabled: dirtyCount === 0 || busy, title: "Discard all unsaved changes", children: "Revert all" }), _jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void editor.save(), disabled: dirtyCount === 0 || busy || !state.loaded, title: "Save all changes (Ctrl/Cmd+S)", children: state.status === "saving" ? "Saving…" : "Save" })] })), _jsx(UpdateButton, { control: update, buttonRef: updateButtonRef }), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: () => void editor.exit(), disabled: busy, children: "Exit" })] })] }));
 }

package/dist/UpdateNotice.d.ts

@@ -0,0 +1,51 @@
+import type { JSX, RefObject } from "react";
+import type { IntegrationUpdateResult, IntegrationUpdateSource, IntegrationUpdateStatus } from "./updates.js";
+type Available = Extract<IntegrationUpdateStatus, {
+    state: "available";
+}>;
+export type UpdatePhase = {
+    readonly kind: "hidden";
+} | {
+    readonly kind: "available";
+    readonly update: Available;
+} | {
+    readonly kind: "updating";
+    readonly update: Available;
+} | {
+    readonly kind: "updated";
+    readonly version: string;
+} | {
+    readonly kind: "failed";
+    readonly update: Available;
+    readonly result: Extract<IntegrationUpdateResult, {
+        ok: false;
+    }>;
+};
+export interface IntegrationUpdateControl {
+    readonly phase: UpdatePhase;
+    readonly open: boolean;
+    setOpen(open: boolean): void;
+    /** Install the offered version. The only path to a repository change, and only ever from a click. */
+    apply(): Promise<void>;
+    /** Close the panel after a success or failure; a success also retires the toolbar control. */
+    close(): void;
+}
+/**
+ * Asks once per editing session, after the copy has loaded, whether the
+ * site's integration has an update, and runs the update when (and only
+ * when) the owner asks for it. No polling, no retries, no background work.
+ */
+export declare function useIntegrationUpdate(source: IntegrationUpdateSource | undefined, ready: boolean): IntegrationUpdateControl;
+/** The toolbar control: absent unless there is something to offer. */
+export declare function UpdateButton({ control, buttonRef }: {
+    control: IntegrationUpdateControl;
+    buttonRef: RefObject<HTMLButtonElement | null>;
+}): JSX.Element | null;
+/** The compact panel above the toolbar. */
+export declare function UpdatePanel({ control, saving, buttonRef, }: {
+    control: IntegrationUpdateControl;
+    /** A save is in flight; an update now would race it for the branch. */
+    saving: boolean;
+    buttonRef: RefObject<HTMLButtonElement | null>;
+}): JSX.Element | null;
+export {};

package/dist/UpdateNotice.js

@@ -0,0 +1,136 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { readUpdateResult, readUpdateStatus } from "./updates.js";
+/**
+ * Asks once per editing session, after the copy has loaded, whether the
+ * site's integration has an update, and runs the update when (and only
+ * when) the owner asks for it. No polling, no retries, no background work.
+ */
+export function useIntegrationUpdate(source, ready) {
+    const [phase, setPhase] = useState({ kind: "hidden" });
+    const [open, setOpen] = useState(false);
+    const asked = useRef(false);
+    useEffect(() => {
+        if (!source || !ready || asked.current)
+            return;
+        asked.current = true;
+        // Whatever goes wrong while asking, the answer is "nothing to show".
+        void Promise.resolve()
+            .then(() => source.check())
+            .then(readUpdateStatus, () => ({ state: "current" }))
+            .then((status) => {
+            if (status.state === "available")
+                setPhase({ kind: "available", update: status });
+        });
+    }, [source, ready]);
+    const apply = useCallback(async () => {
+        if (!source || (phase.kind !== "available" && phase.kind !== "failed"))
+            return;
+        const update = phase.update;
+        if (!update.automatic)
+            return;
+        setPhase({ kind: "updating", update });
+        let result;
+        try {
+            result = readUpdateResult(await source.apply(update.version), update.version);
+        }
+        catch {
+            result = readUpdateResult(null, update.version);
+        }
+        setPhase(result.ok ? { kind: "updated", version: result.version } : { kind: "failed", update, result });
+    }, [phase, source]);
+    const close = useCallback(() => {
+        setOpen(false);
+        if (phase.kind === "updated")
+            setPhase({ kind: "hidden" });
+        else if (phase.kind === "failed")
+            setPhase({ kind: "available", update: phase.update });
+    }, [phase]);
+    return { phase, open, setOpen, apply, close };
+}
+function title(update) {
+    switch (update.urgency) {
+        case "required":
+            return "Refino update required";
+        case "recommended":
+            return "Refino update recommended";
+        default:
+            return "Refino update available";
+    }
+}
+function triggerLabel(phase) {
+    switch (phase.kind) {
+        case "available":
+        case "failed":
+            return phase.update.urgency === "required" ? "Update required" : phase.update.urgency === "recommended" ? "Update recommended" : "Update available";
+        case "updating":
+            return "Updating…";
+        case "updated":
+            return "Updated";
+        default:
+            return null;
+    }
+}
+/** The toolbar control: absent unless there is something to offer. */
+export function UpdateButton({ control, buttonRef }) {
+    const label = triggerLabel(control.phase);
+    if (!label)
+        return null;
+    return (_jsxs("button", { ref: buttonRef, type: "button", className: "refino-toolbar__button refino-toolbar__button--update", "aria-haspopup": "dialog", "aria-expanded": control.open, onClick: () => control.setOpen(!control.open), children: [_jsx("span", { className: "refino-toolbar__dot refino-toolbar__dot--update", "aria-hidden": "true" }), label] }));
+}
+/** The compact panel above the toolbar. */
+export function UpdatePanel({ control, saving, buttonRef, }) {
+    const { phase, open } = control;
+    const titleId = useId();
+    const focusRef = useRef(null);
+    const visible = open && phase.kind !== "hidden";
+    const dismiss = useCallback(() => {
+        if (phase.kind === "updating")
+            return;
+        control.close();
+        buttonRef.current?.focus();
+    }, [buttonRef, control, phase.kind]);
+    useEffect(() => {
+        if (visible)
+            focusRef.current?.focus();
+    }, [visible, phase.kind]);
+    if (!visible)
+        return null;
+    const onKeyDown = (event) => {
+        if (event.key === "Escape") {
+            event.stopPropagation();
+            dismiss();
+        }
+    };
+    let heading;
+    let body;
+    let actions;
+    switch (phase.kind) {
+        case "available": {
+            const { update } = phase;
+            heading = title(update);
+            body = (_jsxs(_Fragment, { children: [_jsxs("p", { children: ["Version ", update.version, " is available."] }), update.summary.length > 0 && (_jsx("ul", { className: "refino-update__summary", children: update.summary.map((line) => (_jsx("li", { children: line }, line))) })), update.automatic ? (_jsx("p", { className: "refino-update__note", children: "Your site redeploys with the update as usual. Your text and unsaved edits are not affected." })) : (_jsx("p", { className: "refino-update__note", children: update.message ?? "This update needs to be installed by whoever maintains your site's code." }))] }));
+            actions = update.automatic ? (_jsxs(_Fragment, { children: [_jsx("button", { ref: focusRef, type: "button", className: "refino-toolbar__button", onClick: dismiss, children: "Not now" }), _jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void control.apply(), disabled: saving, title: saving ? "Wait for the save to finish" : undefined, children: "Update Refino" })] })) : (_jsx("button", { ref: focusRef, type: "button", className: "refino-toolbar__button", onClick: dismiss, children: "Close" }));
+            break;
+        }
+        case "updating":
+            heading = "Updating Refino…";
+            body = _jsx("p", { children: "This usually takes a few seconds. Keep this page open." });
+            actions = _jsx(_Fragment, {});
+            break;
+        case "updated":
+            heading = `Refino updated to ${phase.version}`;
+            body = _jsx("p", { children: "Your site is redeploying with the update, which can take a few minutes. You can keep editing in the meantime." });
+            actions = (_jsx("button", { ref: focusRef, type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: dismiss, children: "Done" }));
+            break;
+        case "failed": {
+            const { result } = phase;
+            heading = result.unchanged ? "Refino was not updated" : "Update status unknown";
+            body = (_jsxs(_Fragment, { children: [_jsx("p", { children: result.message }), _jsx("p", { className: "refino-update__note", children: result.unchanged ? "Nothing on your site was changed." : "Reload this page in a minute to see whether the update went through." })] }));
+            actions = (_jsxs(_Fragment, { children: [_jsx("button", { ref: focusRef, type: "button", className: "refino-toolbar__button", onClick: dismiss, children: "Close" }), result.unchanged && (_jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void control.apply(), disabled: saving, children: "Try again" }))] }));
+            break;
+        }
+    }
+    return (_jsxs("div", { className: "refino-toolbar__notice refino-update", role: "dialog", "aria-labelledby": titleId, onKeyDown: onKeyDown, children: [_jsx("p", { id: titleId, className: "refino-update__title", "aria-live": "polite", children: heading }), body, phase.kind !== "updating" && _jsx("div", { className: "refino-update__actions", children: actions })] }));
+}

package/dist/context.d.ts

@@ -1,9 +1,12 @@
 import type { CopyEditorState, CopyStore } from "./store.js";
+import type { IntegrationUpdateSource } from "./updates.js";
 export interface CopyContextValue {
     readonly store: CopyStore;
     readonly onExit: (() => void | Promise<void>) | undefined;
     /** Where to send the owner when the session has ended. */
     readonly signInHref: string;
+    /** Where the toolbar asks about, and installs, updates to the site's Refino integration. */
+    readonly updates: IntegrationUpdateSource | undefined;
 }
 export declare const CopyContext: import("react").Context<CopyContextValue | null>;
 export declare function useCopyContext(): CopyContextValue | null;

package/dist/index.d.ts

@@ -8,4 +8,6 @@ export type { CopyEditor } from "./useCopyEditor.js";
 export { createCopyStore } from "./store.js";
 export type { CopyEditorState, CopyRequestHeaders, CopyStore, CopyStoreOptions, EditorError, EditorStatus, LastSave, RebaseInfo, } from "./store.js";
 export type { EditorEvent, EditorEventName, EditorEventProperties, EditorEventSink } from "./telemetry.js";
+export { readUpdateResult, readUpdateStatus } from "./updates.js";
+export type { IntegrationUpdateResult, IntegrationUpdateSource, IntegrationUpdateStatus, UpdateUrgency } from "./updates.js";
 export { EDITOR_STYLES } from "./styles.js";

package/dist/index.js

@@ -3,4 +3,5 @@ export { EditableText } from "./EditableText.js";
 export { CopyEditorToolbar } from "./Toolbar.js";
 export { useCopyEditor } from "./useCopyEditor.js";
 export { createCopyStore } from "./store.js";
+export { readUpdateResult, readUpdateStatus } from "./updates.js";
 export { EDITOR_STYLES } from "./styles.js";

package/dist/styles.d.ts

@@ -4,4 +4,4 @@
  * `outline` and `box-shadow` never affect layout, so text reflows exactly
  * as it does for visitors.
  */
-export declare const EDITOR_STYLES = "\n[data-refino-id] {\n  cursor: text;\n  outline: 1px dashed transparent;\n  outline-offset: 3px;\n  border-radius: 2px;\n  transition: outline-color 120ms ease, box-shadow 120ms ease;\n}\n[data-refino-id]:hover {\n  outline-color: rgba(37, 99, 235, 0.6);\n}\n[data-refino-id][data-refino-state=\"dirty\"] {\n  outline-color: rgba(217, 119, 6, 0.75);\n}\n[data-refino-id][data-refino-state=\"active\"],\n[data-refino-id]:focus,\n[data-refino-id]:focus-visible {\n  outline: 2px solid #2563eb;\n  outline-offset: 3px;\n  box-shadow: 0 0 0 5px rgba(37, 99, 235, 0.14);\n}\n[data-refino-id]:empty::before {\n  content: \"\\00a0\";\n}\n.refino-sr-only {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border: 0;\n}\n.refino-toolbar {\n  all: initial;\n  position: fixed;\n  left: 50%;\n  bottom: 16px;\n  transform: translateX(-50%);\n  z-index: 2147483000;\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  gap: 8px;\n  max-width: calc(100vw - 24px);\n  font-family: ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif;\n  font-size: 13px;\n  line-height: 1.3;\n  color: #f9fafb;\n  box-sizing: border-box;\n}\n.refino-toolbar *, .refino-toolbar *::before, .refino-toolbar *::after {\n  box-sizing: border-box;\n  font: inherit;\n  color: inherit;\n}\n.refino-toolbar__bar {\n  display: flex;\n  flex-wrap: wrap;\n  align-items: center;\n  justify-content: center;\n  gap: 6px;\n  padding: 8px 10px;\n  background: #111827;\n  border: 1px solid rgba(255, 255, 255, 0.12);\n  border-radius: 999px;\n  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.28);\n}\n.refino-toolbar__status {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  padding: 0 8px;\n  min-width: 0;\n  white-space: nowrap;\n  color: #d1d5db;\n}\n.refino-toolbar__dot {\n  width: 8px;\n  height: 8px;\n  border-radius: 50%;\n  background: #6b7280;\n  flex: none;\n}\n.refino-toolbar__dot--dirty { background: #f59e0b; }\n.refino-toolbar__dot--saving { background: #60a5fa; }\n.refino-toolbar__dot--saved { background: #34d399; }\n.refino-toolbar__dot--error, .refino-toolbar__dot--conflict { background: #f87171; }\n.refino-toolbar__key {\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;\n  font-size: 12px;\n  color: #9ca3af;\n  padding: 0 8px;\n  max-width: 220px;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n.refino-toolbar__button {\n  appearance: none;\n  cursor: pointer;\n  border: 1px solid transparent;\n  border-radius: 999px;\n  padding: 6px 12px;\n  background: transparent;\n  color: #e5e7eb;\n  font-weight: 500;\n}\n.refino-toolbar__button:hover:not(:disabled) {\n  background: rgba(255, 255, 255, 0.08);\n}\n.refino-toolbar__button:focus-visible {\n  outline: 2px solid #93c5fd;\n  outline-offset: 1px;\n}\n.refino-toolbar__button:disabled {\n  opacity: 0.45;\n  cursor: default;\n}\n.refino-toolbar__button--primary {\n  background: #2563eb;\n  color: #ffffff;\n}\n.refino-toolbar__button--primary:hover:not(:disabled) {\n  background: #1d4ed8;\n}\n.refino-toolbar__notice {\n  padding: 10px 14px;\n  border-radius: 12px;\n  background: #1f2937;\n  border: 1px solid rgba(255, 255, 255, 0.12);\n  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.28);\n  max-width: 560px;\n  color: #f3f4f6;\n}\n.refino-toolbar__notice--error { border-color: rgba(248, 113, 113, 0.6); }\n.refino-toolbar__notice--conflict { border-color: rgba(251, 191, 36, 0.6); }\n.refino-toolbar__notice p { margin: 0 0 6px; }\n.refino-toolbar__notice p:last-child { margin: 0; }\n.refino-toolbar__notice code {\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;\n  font-size: 12px;\n}\n.refino-toolbar__link {\n  color: #93c5fd;\n  text-decoration: underline;\n}\n@media (max-width: 520px) {\n  .refino-toolbar { bottom: 8px; }\n  .refino-toolbar__key { display: none; }\n}\n";
+export declare const EDITOR_STYLES = "\n[data-refino-id] {\n  cursor: text;\n  outline: 1px dashed transparent;\n  outline-offset: 3px;\n  border-radius: 2px;\n  transition: outline-color 120ms ease, box-shadow 120ms ease;\n}\n[data-refino-id]:hover {\n  outline-color: rgba(37, 99, 235, 0.6);\n}\n[data-refino-id][data-refino-state=\"dirty\"] {\n  outline-color: rgba(217, 119, 6, 0.75);\n}\n[data-refino-id][data-refino-state=\"active\"],\n[data-refino-id]:focus,\n[data-refino-id]:focus-visible {\n  outline: 2px solid #2563eb;\n  outline-offset: 3px;\n  box-shadow: 0 0 0 5px rgba(37, 99, 235, 0.14);\n}\n[data-refino-id]:empty::before {\n  content: \"\\00a0\";\n}\n.refino-sr-only {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border: 0;\n}\n.refino-toolbar {\n  all: initial;\n  position: fixed;\n  left: 50%;\n  bottom: 16px;\n  transform: translateX(-50%);\n  z-index: 2147483000;\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  gap: 8px;\n  max-width: calc(100vw - 24px);\n  font-family: ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif;\n  font-size: 13px;\n  line-height: 1.3;\n  color: #f9fafb;\n  box-sizing: border-box;\n}\n.refino-toolbar *, .refino-toolbar *::before, .refino-toolbar *::after {\n  box-sizing: border-box;\n  font: inherit;\n  color: inherit;\n}\n.refino-toolbar__bar {\n  display: flex;\n  flex-wrap: wrap;\n  align-items: center;\n  justify-content: center;\n  gap: 6px;\n  padding: 8px 10px;\n  background: #111827;\n  border: 1px solid rgba(255, 255, 255, 0.12);\n  border-radius: 999px;\n  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.28);\n}\n.refino-toolbar__status {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  padding: 0 8px;\n  min-width: 0;\n  white-space: nowrap;\n  color: #d1d5db;\n}\n.refino-toolbar__dot {\n  width: 8px;\n  height: 8px;\n  border-radius: 50%;\n  background: #6b7280;\n  flex: none;\n}\n.refino-toolbar__dot--dirty { background: #f59e0b; }\n.refino-toolbar__dot--saving { background: #60a5fa; }\n.refino-toolbar__dot--saved { background: #34d399; }\n.refino-toolbar__dot--error, .refino-toolbar__dot--conflict { background: #f87171; }\n.refino-toolbar__key {\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;\n  font-size: 12px;\n  color: #9ca3af;\n  padding: 0 8px;\n  max-width: 220px;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n.refino-toolbar__button {\n  appearance: none;\n  cursor: pointer;\n  border: 1px solid transparent;\n  border-radius: 999px;\n  padding: 6px 12px;\n  background: transparent;\n  color: #e5e7eb;\n  font-weight: 500;\n}\n.refino-toolbar__button:hover:not(:disabled) {\n  background: rgba(255, 255, 255, 0.08);\n}\n.refino-toolbar__button:focus-visible {\n  outline: 2px solid #93c5fd;\n  outline-offset: 1px;\n}\n.refino-toolbar__button:disabled {\n  opacity: 0.45;\n  cursor: default;\n}\n.refino-toolbar__button--primary {\n  background: #2563eb;\n  color: #ffffff;\n}\n.refino-toolbar__button--primary:hover:not(:disabled) {\n  background: #1d4ed8;\n}\n.refino-toolbar__notice {\n  padding: 10px 14px;\n  border-radius: 12px;\n  background: #1f2937;\n  border: 1px solid rgba(255, 255, 255, 0.12);\n  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.28);\n  max-width: 560px;\n  color: #f3f4f6;\n}\n.refino-toolbar__notice--error { border-color: rgba(248, 113, 113, 0.6); }\n.refino-toolbar__notice--conflict { border-color: rgba(251, 191, 36, 0.6); }\n.refino-toolbar__notice p { margin: 0 0 6px; }\n.refino-toolbar__notice p:last-child { margin: 0; }\n.refino-toolbar__notice code {\n  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;\n  font-size: 12px;\n}\n.refino-toolbar__button--update {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  border-color: rgba(147, 197, 253, 0.45);\n  color: #dbeafe;\n}\n.refino-toolbar__dot--update { background: #60a5fa; }\n.refino-update {\n  width: min(360px, calc(100vw - 24px));\n}\n.refino-update__title {\n  font-weight: 600;\n  font-size: 14px;\n}\n.refino-update__summary {\n  margin: 0 0 8px;\n  padding-left: 18px;\n}\n.refino-update__summary li { margin: 0 0 2px; }\n.refino-toolbar__notice p.refino-update__note {\n  color: #9ca3af;\n  font-size: 12px;\n}\n.refino-update__actions {\n  display: flex;\n  justify-content: flex-end;\n  gap: 6px;\n  margin-top: 10px;\n}\n.refino-toolbar__link {\n  color: #93c5fd;\n  text-decoration: underline;\n}\n@media (max-width: 520px) {\n  .refino-toolbar { bottom: 8px; }\n  .refino-toolbar__key { display: none; }\n}\n";

package/dist/styles.js

@@ -149,6 +149,36 @@ export const EDITOR_STYLES = `
   font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   font-size: 12px;
 }
+.refino-toolbar__button--update {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  border-color: rgba(147, 197, 253, 0.45);
+  color: #dbeafe;
+}
+.refino-toolbar__dot--update { background: #60a5fa; }
+.refino-update {
+  width: min(360px, calc(100vw - 24px));
+}
+.refino-update__title {
+  font-weight: 600;
+  font-size: 14px;
+}
+.refino-update__summary {
+  margin: 0 0 8px;
+  padding-left: 18px;
+}
+.refino-update__summary li { margin: 0 0 2px; }
+.refino-toolbar__notice p.refino-update__note {
+  color: #9ca3af;
+  font-size: 12px;
+}
+.refino-update__actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 6px;
+  margin-top: 10px;
+}
 .refino-toolbar__link {
   color: #93c5fd;
   text-decoration: underline;

package/dist/updates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Updating the site's Refino integration from the editor.
+ *
+ * The editor knows nothing about where updates come from. A host that can
+ * update itself passes an `IntegrationUpdateSource` (Refino-hosted sites get
+ * one generated for them) whose two methods resolve with whatever JSON the
+ * update service answered. Everything is validated here, in the package,
+ * rather than in the generated transport, so the generated code can stay a
+ * thin pipe that rarely needs to change, and an answer this version does not
+ * understand reads as "nothing to offer" rather than as an error.
+ */
+export type UpdateUrgency = "optional" | "recommended" | "required";
+export type IntegrationUpdateStatus = {
+    readonly state: "current";
+} | {
+    readonly state: "available";
+    /** The version the update installs. */
+    readonly version: string;
+    readonly urgency: UpdateUrgency;
+    /** Plain-language highlights of the release, possibly none. */
+    readonly summary: readonly string[];
+    /** False when the update needs a developer; `message` then says so in plain words. */
+    readonly automatic: boolean;
+    readonly message: string | null;
+};
+export type IntegrationUpdateResult = {
+    readonly ok: true;
+    readonly version: string;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+    /**
+     * Whether the repository was left exactly as it was. False only when
+     * the request's outcome is unknown (the connection dropped while it
+     * ran), never after a refusal.
+     */
+    readonly unchanged: boolean;
+};
+export interface IntegrationUpdateSource {
+    /** Resolve with the update service's JSON body for "is there an update?". */
+    check(): Promise<unknown>;
+    /** Resolve with the update service's JSON body for "install `version` now". */
+    apply(version: string): Promise<unknown>;
+}
+/** `{ ok: true, update: {...} }` → a status. Anything unexpected is "current": no noise. */
+export declare function readUpdateStatus(body: unknown): IntegrationUpdateStatus;
+/** `{ ok: true, result: { status: "updated", version } }` or `{ ok: false, error }` → a result. */
+export declare function readUpdateResult(body: unknown, requested: string): IntegrationUpdateResult;

package/dist/updates.js

@@ -0,0 +1,52 @@
+/**
+ * Updating the site's Refino integration from the editor.
+ *
+ * The editor knows nothing about where updates come from. A host that can
+ * update itself passes an `IntegrationUpdateSource` (Refino-hosted sites get
+ * one generated for them) whose two methods resolve with whatever JSON the
+ * update service answered. Everything is validated here, in the package,
+ * rather than in the generated transport, so the generated code can stay a
+ * thin pipe that rarely needs to change, and an answer this version does not
+ * understand reads as "nothing to offer" rather than as an error.
+ */
+const CURRENT = { state: "current" };
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const MAX_TEXT = 300;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function text(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim().slice(0, MAX_TEXT) : null;
+}
+/** `{ ok: true, update: {...} }` → a status. Anything unexpected is "current": no noise. */
+export function readUpdateStatus(body) {
+    const update = record(record(body)?.ok === true ? record(body).update : null);
+    if (!update || update.state !== "available")
+        return CURRENT;
+    const version = typeof update.version === "string" && VERSION.test(update.version) ? update.version : null;
+    if (!version)
+        return CURRENT;
+    const urgency = update.urgency === "recommended" || update.urgency === "required" ? update.urgency : "optional";
+    const summary = Array.isArray(update.summary) ? update.summary.map(text).filter((line) => line !== null).slice(0, 5) : [];
+    const automatic = update.automatic === true;
+    return { state: "available", version, urgency, summary, automatic, message: automatic ? null : text(update.message) };
+}
+const GENERIC_FAILURE = "Refino could not update this site.";
+const UNKNOWN_OUTCOME = "Refino could not confirm whether the update finished.";
+/** `{ ok: true, result: { status: "updated", version } }` or `{ ok: false, error }` → a result. */
+export function readUpdateResult(body, requested) {
+    const value = record(body);
+    const result = record(value?.ok === true ? value.result : null);
+    if (result && (result.status === "updated" || result.status === "current")) {
+        const version = typeof result.version === "string" && VERSION.test(result.version) ? result.version : requested;
+        return { ok: true, version };
+    }
+    const error = record(value?.error);
+    const code = typeof error?.code === "string" ? error.code : "UNEXPECTED";
+    // "Nothing was changed" is only ever said when the service says so. A
+    // dropped connection, a proxy error page or an answer this version cannot
+    // read leaves the outcome unknown, and the owner is told exactly that.
+    const unchanged = error?.repositoryUnchanged === true;
+    const message = text(error?.message) ?? (unchanged ? GENERIC_FAILURE : UNKNOWN_OUTCOME);
+    return { ok: false, code, message, unchanged };
+}

package/dist/useCopyEditor.d.ts

@@ -1,11 +1,14 @@
 import type { ContentId } from "@getrefino/core";
 import type { CopyEditorState } from "./store.js";
+import type { IntegrationUpdateSource } from "./updates.js";
 export interface CopyEditor {
     readonly state: CopyEditorState;
     readonly dirtyIds: readonly ContentId[];
     readonly isDirty: boolean;
     /** Login page to offer when the endpoint reports the session ended. */
     readonly signInHref: string;
+    /** The provider's update source, if the host offers integration updates. */
+    readonly updates: IntegrationUpdateSource | undefined;
     save(): Promise<void>;
     revertValue(id: ContentId): void;
     revertAll(): void;

package/dist/useCopyEditor.js

@@ -7,7 +7,7 @@ import { useCopyEditorState, useCopyStoreOrThrow } from "./context.js";
  * the default toolbar does not fit the host site.
  */
 export function useCopyEditor() {
-    const { store, onExit, signInHref } = useCopyStoreOrThrow();
+    const { store, onExit, signInHref, updates } = useCopyStoreOrThrow();
     const state = useCopyEditorState(store);
     const dirtyIds = useMemo(() => getDirtyIds(state.draft), [state.draft]);
     const exit = useCallback(async () => {
@@ -24,11 +24,12 @@ export function useCopyEditor() {
         dirtyIds,
         isDirty: dirtyIds.length > 0,
         signInHref,
+        updates,
         save: store.save,
         revertValue: store.revertValue,
         revertAll: store.revertAll,
         reloadLatest: store.reloadLatest,
         dismissError: store.dismissError,
         exit,
-    }), [state, dirtyIds, store, exit, signInHref]);
+    }), [state, dirtyIds, store, exit, signInHref, updates]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/react",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.5",
   "description": "React components for Refino: edit a website's existing copy in place on the rendered page and commit it to the repository. Click text. Edit text. Save.",
   "keywords": [
     "refino",
@@ -37,7 +37,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@getrefino/core": "0.1.0-rc.4"
+    "@getrefino/core": "0.1.0-rc.5"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",