@gogitcms/editor 0.41.0 → 0.42.0

package/app/src/App.tsx

@@ -33,17 +33,19 @@ import {
   pluginNavKey,
   usePluginRegistry,
   type PluginDocument,
+  type PluginFieldFocus,
   type PluginTabSpec,
 } from "@gogitcms/plugin-sdk";
 import { pluginRegistry } from "./plugins";
 import {
   DraftBus,
+  FocusBus,
   PluginDocumentActions,
   PluginTabBody,
   pluginTabId,
   type PluginTabRef,
 } from "./previewHost";
-import { useDocCollab, type DocCollab } from "@gogitcms/realtime";
+import { colorForId, useDocCollab, type DocCollab } from "@gogitcms/realtime";
 import { client, setAuthToken, getAuthToken } from "./apollo";
 import { config, analyticsConfig } from "./config";
 import { AnalyticsEvent, AnalyticsProvider, useAnalytics, useIdentify } from "@gogitcms/analytics";
@@ -1388,6 +1390,8 @@ function CmsView({
   // One per browser instance, never recreated — a new bus would silently drop
   // every existing subscription.
   const draftBus = useRef(new DraftBus()).current;
+  // Who is focused on which field of each open document, for the same tabs.
+  const focusBus = useRef(new FocusBus()).current;
 
   // Current user identity for collaborative presence (email local-part as label).
   const { data: meData } = useQuery(ME);
@@ -1411,6 +1415,50 @@ function CmsView({
       return next;
     });
   }, []);
+  // Field focus, merged per document from two sources: the field this editor's
+  // author is in (ContentBrowser's onFieldFocus) and the fields collaborators
+  // are in (the document's awareness, the same presence the form shows as
+  // coloured outlines). Refs rather than state: both move on every focus
+  // change and awareness tick, and nothing here re-renders on them — the bus
+  // fans the merged set straight out to the preview panes.
+  const localFocusRef = useRef<Record<string, string | null>>({});
+  const loadedRef = useRef(loaded);
+  loadedRef.current = loaded;
+  const collabRef = useRef(collabById);
+  collabRef.current = collabById;
+  const collabUserRef = useRef(collabUser);
+  collabUserRef.current = collabUser;
+  const publishFocus = useCallback(
+    (id: string) => {
+      const path = loadedRef.current[id]?.path ?? "";
+      const me = collabUserRef.current;
+      const focus: PluginFieldFocus[] = [];
+      const local = localFocusRef.current[id];
+      // The author's own colour is the one collab derives for them, so the
+      // ring on the page matches the outline a collaborator sees in the form.
+      if (local && me) {
+        focus.push({ documentId: id, path, field: local, user: { id: me.id, name: me.name, color: colorForId(me.id) }, self: true });
+      }
+      const collab = collabRef.current[id];
+      if (collab) {
+        for (const p of collab.participants()) {
+          if (!p.focus) continue;
+          focus.push({ documentId: id, path, field: p.focus, user: { id: p.id, name: p.name, color: p.color }, self: false });
+        }
+      }
+      focusBus.publish(id, focus);
+    },
+    [focusBus],
+  );
+  useEffect(() => {
+    const offs = Object.entries(collabById).map(([id, collab]) => {
+      publishFocus(id);
+      return collab.subscribeAwareness(() => publishFocus(id));
+    });
+    return () => {
+      for (const off of offs) off();
+    };
+  }, [collabById, publishFocus]);
   // The URL-selected document always materializes as a tab.
   useEffect(() => {
     // The changes surface has no editor tabs — its selection is a diff, not an
@@ -2034,6 +2082,7 @@ function CmsView({
             tabId={t.id}
             tab={p}
             bus={draftBus}
+            focusBus={focusBus}
             initialDocument={anchor ? toPluginDoc(anchor, anchorCollection) : null}
             workspaceId={params.workspaceId}
             repositoryId={repo.id}
@@ -2369,6 +2418,16 @@ function CmsView({
               });
             }
       }
+      // Which field the author is in, for the preview panes to ring on the
+      // page. Nothing on the changes surface has a field to be in.
+      onFieldFocus={
+        changesMode
+          ? undefined
+          : (id, path) => {
+              localFocusRef.current[id] = path;
+              publishFocus(id);
+            }
+      }
       renderField={renderField}
       media={media}
       forms={forms}

package/app/src/previewHost.tsx

@@ -13,6 +13,7 @@ import {
   usePluginRegistry,
   type PluginDocument,
   type PluginDocumentActionContext,
+  type PluginFieldFocus,
   type PluginRegistry,
   type PluginTabSpec,
 } from "@gogitcms/plugin-sdk";
@@ -93,6 +94,77 @@ export class DraftBus {
   }
 }
 
+// --- the focus bus ----------------------------------------------------------
+
+type FocusListener = (focus: PluginFieldFocus[]) => void;
+
+/**
+ * Who is focused on which field, per document, fanned out to the plugin tabs
+ * open on it.
+ *
+ * Same shape as the draft bus and for the same reason. The value is the
+ * whole set for the document — the author at this editor plus every
+ * collaborator in its session — so a subscriber paints exactly what it is
+ * handed and never has to reconcile deltas. Retained per document so a tab
+ * opened while a field is already focused rings it on arrival.
+ */
+export class FocusBus {
+  private listeners = new Map<string, Set<FocusListener>>();
+  private last = new Map<string, PluginFieldFocus[]>();
+
+  publish(documentId: string, focus: PluginFieldFocus[]): void {
+    const previous = this.last.get(documentId);
+    if (previous && sameFocus(previous, focus)) return;
+    this.last.set(documentId, focus);
+    const set = this.listeners.get(documentId);
+    if (!set) return;
+    for (const l of set) {
+      try {
+        l(focus);
+      } catch (err) {
+        console.error(`[plugins] a focus subscriber threw: ${String(err)}`);
+      }
+    }
+  }
+
+  subscribe(documentId: string, listener: FocusListener): () => void {
+    let set = this.listeners.get(documentId);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(documentId, set);
+    }
+    set.add(listener);
+    listener(this.last.get(documentId) ?? []);
+    return () => {
+      set!.delete(listener);
+      if (set!.size === 0) this.listeners.delete(documentId);
+    };
+  }
+
+  forget(documentId: string): void {
+    this.last.delete(documentId);
+    this.listeners.delete(documentId);
+  }
+}
+
+// Awareness ticks for reasons other than focus (a cursor, a heartbeat), and
+// each one would otherwise re-post the same set to every preview frame.
+function sameFocus(a: PluginFieldFocus[], b: PluginFieldFocus[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every((x, i) => {
+    const y = b[i];
+    return (
+      x.documentId === y.documentId &&
+      x.path === y.path &&
+      x.field === y.field &&
+      x.self === y.self &&
+      x.user.id === y.user.id &&
+      x.user.name === y.user.name &&
+      x.user.color === y.user.color
+    );
+  });
+}
+
 // --- toolbar buttons --------------------------------------------------------
 
 export type DocumentActionsProps = {
@@ -181,6 +253,8 @@ export type PluginTabBodyProps = {
   tabId: string;
   tab: PluginTabRef;
   bus: DraftBus;
+  /** Who is focused where, for the tab's document. Optional for older hosts. */
+  focusBus?: FocusBus;
   /** The document as last loaded, for a tab opened before any edit. */
   initialDocument: PluginDocument | null;
   workspaceId: string;
@@ -195,13 +269,18 @@ export type PluginTabBodyProps = {
 
 /** Renders a plugin route inside a column, with its tab context attached. */
 export function PluginTabBody(props: PluginTabBodyProps) {
-  const { bus, tab, initialDocument } = props;
+  const { bus, focusBus, tab, initialDocument } = props;
 
   const onDraft = useCallback(
     (cb: (doc: PluginDocument) => void) =>
       tab.documentId ? bus.subscribe(tab.documentId, cb) : () => {},
     [bus, tab.documentId],
   );
+  const onFocus = useCallback(
+    (cb: (focus: PluginFieldFocus[]) => void) =>
+      focusBus && tab.documentId ? focusBus.subscribe(tab.documentId, cb) : () => {},
+    [focusBus, tab.documentId],
+  );
 
   // The tab context is memoized on its inputs: it is a prop of the plugin's
   // component, and a fresh object each render would re-run every effect the
@@ -211,10 +290,11 @@ export function PluginTabBody(props: PluginTabBodyProps) {
       id: props.tabId,
       document: initialDocument,
       onDraft,
+      onFocus,
       openDocument: props.openDocument,
       close: props.close,
     }),
-    [props.tabId, initialDocument, onDraft, props.openDocument, props.close],
+    [props.tabId, initialDocument, onDraft, onFocus, props.openDocument, props.close],
   );
 
   return (

package/app/vendor/design-system/src/__tests__/ContentBrowser.fieldfocus.test.tsx

@@ -0,0 +1,109 @@
+// Which field the author is in, reported as a dotted path — what a preview
+// pane uses to ring the matching part of the page. Read off the DOM's focus
+// events and the `data-cms-field` attribute every control's wrapper carries,
+// so it works for every kind of control and for a lone author with no live
+// session.
+import React from "react";
+import { render, screen, fireEvent, act } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import { ContentBrowser, type CmsEntry, type CmsNavSection, type EntryField } from "../components/ContentBrowser";
+
+jest.mock("../ThemeProvider", () => {
+  const actual = jest.requireActual("../ThemeProvider");
+  return { ...actual, useResponsive: () => ({ width: 1300, height: 900, isDesktop: true, isMobile: false }) };
+});
+
+const wrap = (ui: React.ReactElement) => <ThemeProvider>{ui}</ThemeProvider>;
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "pages", label: "Pages", icon: "newspaper" }] },
+];
+
+const fields: EntryField[] = [
+  { name: "title", label: "Title", type: "string", value: "Home", required: true },
+  {
+    name: "blocks",
+    label: "Blocks",
+    type: "array",
+    component: "mixedList",
+    value: [{ _variant: "hero", heading: "Hi", stats: [{ label: "a", value: "1" }] }],
+    variants: [
+      {
+        name: "hero",
+        fields: [
+          { name: "heading", label: "Heading", type: "string", value: null },
+          {
+            name: "stats",
+            label: "Stats",
+            type: "array",
+            of: "object",
+            value: null,
+            fields: [
+              { name: "label", label: "Label", type: "string", value: null },
+              { name: "value", label: "Value", type: "string", value: null },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+];
+
+const entry: CmsEntry = { id: "doc-1", path: "content/pages/home.json", title: "Home", body: "", fields };
+
+function renderBrowser(onFieldFocus = jest.fn()) {
+  render(
+    wrap(
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="pages"
+        onSelectNav={() => {}}
+        entries={[entry]}
+        userInitials="ED"
+        onSaveEntry={jest.fn()}
+        onFieldFocus={onFieldFocus}
+      />,
+    ),
+  );
+  return onFieldFocus;
+}
+
+// The blur report is deferred a tick so a move between fields never passes
+// through null; flush it.
+const settle = () => act(() => new Promise((r) => setTimeout(r, 5)));
+
+describe("onFieldFocus", () => {
+  it("reports a top-level field by name and null when it blurs", async () => {
+    const onFieldFocus = renderBrowser();
+    const title = screen.getByDisplayValue("Home");
+    fireEvent.focusIn(title);
+    expect(onFieldFocus).toHaveBeenLastCalledWith("doc-1", "title");
+    fireEvent.focusOut(title);
+    await settle();
+    expect(onFieldFocus).toHaveBeenLastCalledWith("doc-1", null);
+  });
+
+  it("composes the path of a field inside a mixed-list item and a nested list", async () => {
+    const onFieldFocus = renderBrowser();
+    const heading = screen.getByDisplayValue("Hi");
+    fireEvent.focusIn(heading);
+    expect(onFieldFocus).toHaveBeenLastCalledWith("doc-1", "blocks.0.heading");
+
+    const statLabel = screen.getByDisplayValue("a");
+    // Straight from one field to the next: no null in between.
+    fireEvent.focusOut(heading);
+    fireEvent.focusIn(statLabel);
+    await settle();
+    expect(onFieldFocus).not.toHaveBeenCalledWith("doc-1", null);
+    expect(onFieldFocus).toHaveBeenLastCalledWith("doc-1", "blocks.0.stats.0.label");
+  });
+
+  it("annotates every control's wrapper with its path", () => {
+    renderBrowser();
+    const paths = Array.from(document.querySelectorAll("[data-cms-field]")).map((el) => el.getAttribute("data-cms-field"));
+    expect(paths).toEqual(
+      expect.arrayContaining(["title", "blocks", "blocks.0", "blocks.0.heading", "blocks.0.stats", "blocks.0.stats.0", "blocks.0.stats.0.label", "blocks.0.stats.0.value"]),
+    );
+  });
+});

package/app/vendor/design-system/src/components/ContentBrowser.tsx

@@ -336,6 +336,15 @@ export type ContentBrowserProps = {
   // already separated from the frontmatter.
   onEntryDraft?: (draft: EntrySaveChange, entry: CmsEntry) => void;
 
+  // Which field of an open document has keyboard focus, as the author moves
+  // between controls: the field's dotted path (`title`, `seo.description`,
+  // `blocks.0.heading`), or null when nothing in that document is focused.
+  // Web only — it reads the DOM's focus events. This is what lets a preview
+  // ring the part of the page the author is editing (§4.4 of the preview
+  // design), and it is separate from live collaboration: a lone author gets
+  // it too.
+  onFieldFocus?: (entryId: string, path: string | null) => void;
+
   // Optional per-field renderer. When it returns a node for a field, that node
   // replaces the built-in control (used to inject the markdown body editor).
   renderField?: RenderField;
@@ -782,8 +791,40 @@ type FieldControlProps = {
   // (see FieldSlotArgs.resetNonce); every built-in control is controlled and
   // re-renders from `value` on its own.
   resetNonce?: number;
+  // The field's full dotted path, when the caller knows better than
+  // "parent path + field name" — a list item, whose control is named after
+  // the list but sits at `list.<index>`.
+  fieldPath?: string;
 };
 
+// The dotted path of the field being rendered, for the controls under it:
+// a group's children append their names to it, a list's items append their
+// index. It exists so every control can carry its own path as a DOM
+// attribute (`data-cms-field`) without any of them threading a prop through
+// — the focus reporting in EntryDetail reads that attribute off whichever
+// element the keyboard lands in.
+//
+// Deliberately separate from the collab `path` prop: that one is threaded
+// only where a CRDT binding exists (top-level fields and drilled-in groups),
+// whereas this is present for every field including list items, which the
+// collab layer treats as one register.
+const FieldPathContext = React.createContext<string>("");
+
+function FieldControl(props: FieldControlProps) {
+  const prefix = React.useContext(FieldPathContext);
+  const fullPath = props.fieldPath ?? (prefix ? `${prefix}.${props.field.name}` : props.field.name);
+  return (
+    <FieldPathContext.Provider value={fullPath}>
+      <View
+        // @ts-expect-error react-native-web maps dataSet -> data-* attributes
+        dataSet={{ cmsField: fullPath }}
+      >
+        <FieldControlInner {...props} />
+      </View>
+    </FieldPathContext.Provider>
+  );
+}
+
 // The scalar type an array's `of` maps to when rendering item controls.
 function ofToType(of?: string): string {
   switch (of) {
@@ -794,7 +835,7 @@ function ofToType(of?: string): string {
   }
 }
 
-function FieldControl(props: FieldControlProps) {
+function FieldControlInner(props: FieldControlProps) {
   const { field, value, onChange, renderField, readOnly = false, error, hideLabel, onOpenGroup, collab, path, focusSignal, resetNonce } = props;
   const t = useTheme();
   const label = hideLabel ? "" : field.label || field.name;
@@ -1631,11 +1672,14 @@ function ListControl({
     ...(field.media ? { component: "media", media: field.media, storeAs: field.storeAs } : {}),
   };
 
+  // The list's own path, from the FieldControl wrapping this control; an item
+  // sits at `<list>.<index>`.
+  const listPath = React.useContext(FieldPathContext);
   return (
     <View style={{ gap: t.space(2) }}>
       {items.map((it, i) => (
         <ItemFrame key={i} index={i} count={items.length} readOnly={readOnly || !canRemove} onRemove={() => removeItem(i)} onMove={(d) => moveItem(i, d)}>
-          <FieldControl field={itemField} value={it} onChange={(v) => setItem(i, v)} renderField={renderField} readOnly={readOnly} hideLabel />
+          <FieldControl field={itemField} value={it} onChange={(v) => setItem(i, v)} renderField={renderField} readOnly={readOnly} hideLabel fieldPath={listPath ? `${listPath}.${i}` : String(i)} />
         </ItemFrame>
       ))}
       {!readOnly && canAdd ? (
@@ -1675,15 +1719,25 @@ function MixedListControl({
     onChange(next);
   };
   const addItem = () => onChange([...items, { [key]: variants[0]?.name ?? "" }]);
+  const listPath = React.useContext(FieldPathContext);
 
   return (
     <View style={{ gap: t.space(2) }}>
       {items.map((it, i) => {
         const variantName = String(it?.[key] ?? "");
         const variant = variants.find((v) => v.name === variantName);
+        const itemPath = listPath ? `${listPath}.${i}` : String(i);
         return (
           <ItemFrame key={i} index={i} count={items.length} readOnly={readOnly || !canRemove} onRemove={() => removeItem(i)} onMove={(d) => moveItem(i, d)}>
-            <View style={{ gap: t.space(2) }}>
+            {/* The item's fields compose under `<list>.<index>`; the item
+                itself carries that path so focusing its variant picker
+                reports the item rather than the whole list. */}
+            <FieldPathContext.Provider value={itemPath}>
+            <View
+              style={{ gap: t.space(2) }}
+              // @ts-expect-error react-native-web maps dataSet -> data-* attributes
+              dataSet={{ cmsField: itemPath }}
+            >
               <SelectControl
                 value={variantName}
                 options={variants.map((v) => v.name)}
@@ -1701,6 +1755,7 @@ function MixedListControl({
                 />
               ) : null}
             </View>
+            </FieldPathContext.Provider>
           </ItemFrame>
         );
       })}
@@ -1745,7 +1800,13 @@ function BodyField({
     readOnly,
   });
   return (
-    <View style={{ gap: t.space(2), flex: 1 }}>
+    <View
+      style={{ gap: t.space(2), flex: 1 }}
+      // The schema-less body is the document's one field; a preview rings
+      // it under the same name the schema form would give it.
+      // @ts-expect-error react-native-web maps dataSet -> data-* attributes
+      dataSet={{ cmsField: "body" }}
+    >
       <View style={{ flexDirection: "row", justifyContent: "space-between", alignItems: "center" }}>
         <Text variant="label" color="tertiary">Body</Text>
         <Text variant="monoSm" color="tertiary">Markdown</Text>
@@ -2597,6 +2658,7 @@ function EntryDetail({
   entry,
   documentActions,
   onEntryDraft,
+  onFieldFocus,
   renderField,
   onSaveEntry,
   readOnly = false,
@@ -2619,6 +2681,8 @@ function EntryDetail({
   documentActions?: (entry: CmsEntry) => React.ReactNode;
   // Debounced in-flight draft (see ContentBrowserProps.onEntryDraft).
   onEntryDraft?: (draft: EntrySaveChange, entry: CmsEntry) => void;
+  // The focused field's path, or null (see ContentBrowserProps.onFieldFocus).
+  onFieldFocus?: (entryId: string, path: string | null) => void;
   renderField?: RenderField;
   onSaveEntry?: SaveEntry;
   readOnly?: boolean;
@@ -2972,8 +3036,54 @@ function EntryDetail({
   // The field list + nested value object for the active frame.
   const frame = resolveFrame(editFields, values, groupPath);
 
+  // Which field has the keyboard. One pair of DOM focus listeners on the
+  // column rather than an onFocus on every control: the controls are many
+  // (inputs, selects, the ProseMirror body, plugin fields) and every one of
+  // them renders inside the FieldControl wrapper that carries the path as
+  // `data-cms-field` — so the element the focus landed in is enough.
+  //
+  // focusout fires before the next focusin, so a blur is reported a tick
+  // late and cancelled if focus went straight to another field: moving
+  // between two controls reads as one change, not a flicker through null.
+  const focusRoot = useRef<View>(null);
+  const fieldFocus = useRef(onFieldFocus);
+  fieldFocus.current = onFieldFocus;
+  const entryId = entry.id;
+  useEffect(() => {
+    if (Platform.OS !== "web") return;
+    const node = focusRoot.current as unknown as HTMLElement | null;
+    if (!node || typeof node.addEventListener !== "function") return;
+    let pending: ReturnType<typeof setTimeout> | null = null;
+    let last: string | null = null;
+    const report = (path: string | null) => {
+      if (path === last) return;
+      last = path;
+      fieldFocus.current?.(entryId, path);
+    };
+    const onFocusIn = (ev: Event) => {
+      if (pending) { clearTimeout(pending); pending = null; }
+      const target = ev.target as Element | null;
+      const el = target && typeof target.closest === "function" ? target.closest("[data-cms-field]") : null;
+      report(el?.getAttribute("data-cms-field") || null);
+    };
+    const onFocusOut = () => {
+      if (pending) clearTimeout(pending);
+      pending = setTimeout(() => { pending = null; report(null); }, 0);
+    };
+    node.addEventListener("focusin", onFocusIn);
+    node.addEventListener("focusout", onFocusOut);
+    return () => {
+      node.removeEventListener("focusin", onFocusIn);
+      node.removeEventListener("focusout", onFocusOut);
+      if (pending) clearTimeout(pending);
+      // The column is going away with the field still focused: nothing in
+      // this document has focus any more.
+      if (last !== null) fieldFocus.current?.(entryId, null);
+    };
+  }, [entryId]);
+
   return (
-    <View style={{ flex: 1 }}>
+    <View style={{ flex: 1 }} ref={focusRoot}>
       {/* breadcrumb + actions. position/zIndex lift this row (and the "..." menu
           dropdown it hosts) above the content pane so the menu receives clicks. */}
       <View
@@ -3129,6 +3239,8 @@ function EntryDetail({
               <Text variant="monoSm" color="tertiary">{frame.labels.join(" / ")}</Text>
             </Pressable>
           ) : null}
+          {/* Drilled into a group, every field's path starts with the group's. */}
+          <FieldPathContext.Provider value={groupPath.join(".")}>
           {frame.fields.map((f) => (
             <FieldControl
               key={f.name}
@@ -3147,6 +3259,7 @@ function EntryDetail({
               resetNonce={resetNonces[f.name]}
             />
           ))}
+          </FieldPathContext.Provider>
         </ScrollView>
         </DocumentPathProvider>
       ) : (
@@ -4133,6 +4246,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
           documentActions={props.documentActions}
           history={props.history}
           onEntryDraft={props.onEntryDraft}
+          onFieldFocus={props.onFieldFocus}
           renderField={renderField}
           onSaveEntry={props.onSaveEntry}
           readOnly={col.readOnly}
@@ -5009,6 +5123,7 @@ function MobileBrowser(props: ContentBrowserProps) {
           documentActions={props.documentActions}
           history={props.history}
           onEntryDraft={props.onEntryDraft}
+          onFieldFocus={props.onFieldFocus}
           renderField={renderField}
           onSaveEntry={props.onSaveEntry}
           readOnly={readOnly}

package/app/vendor/plugin-sdk/src/index.ts

@@ -5,6 +5,7 @@ export type {
   PluginDocumentAction,
   PluginDocumentActionContext,
   PluginFieldComponent,
+  PluginFieldFocus,
   PluginFieldProps,
   PluginFieldType,
   PluginLoadEntry,

package/app/vendor/plugin-sdk/src/types.ts

@@ -32,6 +32,24 @@ export type PluginDocument = {
   bodyField?: string;
 };
 
+/**
+ * One field somebody is focused on in the editor, and who.
+ *
+ * Structurally the preview protocol's `PreviewFocus`, so a preview plugin can
+ * hand the list straight to the page. `self` marks the user driving this
+ * editor; the rest are collaborators from the document's live session, with
+ * the presence colour the editor already shows beside their field.
+ */
+export type PluginFieldFocus = {
+  documentId: string;
+  /** Repo-relative path of the document. */
+  path: string;
+  /** Dotted field path: `title`, `seo.description`, `blocks.0.heading`. */
+  field: string;
+  user: { id: string; name: string; color: string };
+  self: boolean;
+};
+
 /**
  * Extra props a route gets when it is rendered as a *tab* beside the editor
  * rather than as a full screen at its URL.
@@ -51,6 +69,14 @@ export type PluginTabContext = {
    * unsubscribe function.
    */
   onDraft: (cb: (doc: PluginDocument) => void) => () => void;
+  /**
+   * Subscribe to who is focused on which of that document's fields — the
+   * user at this editor and every collaborator in its live session. Called
+   * with the full set on every change, and once on subscribe with the current
+   * one. Optional: an older host has no notion of it, and a plugin treats its
+   * absence as "nobody is focused".
+   */
+  onFocus?: (cb: (focus: PluginFieldFocus[]) => void) => () => void;
   /** Open a document in the editor — the inverse direction, for click-to-edit. */
   openDocument: (id: string, field?: string) => void;
   /** Close this tab. */

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@gogitcms/editor",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@gogitcms/editor",
-      "version": "0.41.0",
+      "version": "0.42.0",
       "dependencies": {
         "@apollo/client": "^3.11.8",
         "@handlewithcare/react-prosemirror": "^3.2.7",
@@ -47,11 +47,11 @@
         "node": ">=20"
       },
       "optionalDependencies": {
-        "@gogitcms/gitcms-local-darwin-arm64": "0.41.0",
-        "@gogitcms/gitcms-local-darwin-x64": "0.41.0",
-        "@gogitcms/gitcms-local-linux-arm64": "0.41.0",
-        "@gogitcms/gitcms-local-linux-x64": "0.41.0",
-        "@gogitcms/gitcms-local-win32-x64": "0.41.0"
+        "@gogitcms/gitcms-local-darwin-arm64": "0.42.0",
+        "@gogitcms/gitcms-local-darwin-x64": "0.42.0",
+        "@gogitcms/gitcms-local-linux-arm64": "0.42.0",
+        "@gogitcms/gitcms-local-linux-x64": "0.42.0",
+        "@gogitcms/gitcms-local-win32-x64": "0.42.0"
       }
     },
     "node_modules/@apollo/client": {
@@ -751,9 +751,9 @@
       }
     },
     "node_modules/@gogitcms/gitcms-local-darwin-arm64": {
-      "version": "0.41.0",
-      "resolved": "https://registry.npmjs.org/@gogitcms/gitcms-local-darwin-arm64/-/gitcms-local-darwin-arm64-0.41.0.tgz",
-      "integrity": "sha512-5B5P0S3S714jXMTBMTM61h4H1hDS3TF0zCzZWUO59yGjJue0t7sIRyHvHjwcJJMYrdzBUKmX6LiGRnd5nqLI2Q==",
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@gogitcms/gitcms-local-darwin-arm64/-/gitcms-local-darwin-arm64-0.42.0.tgz",
+      "integrity": "sha512-rPnqWdexcwEU+jlQc8gRjbYI89uXjBpJYewD5wZz41bRFDVwW93klZw8tJHu108GHihzFh5WnVz0ga1AMWisIw==",
       "cpu": [
         "arm64"
       ],
@@ -764,9 +764,9 @@
       ]
     },
     "node_modules/@gogitcms/gitcms-local-darwin-x64": {
-      "version": "0.41.0",
-      "resolved": "https://registry.npmjs.org/@gogitcms/gitcms-local-darwin-x64/-/gitcms-local-darwin-x64-0.41.0.tgz",
-      "integrity": "sha512-+o9YTQbf5luKlGeLcvVtRgR9oXJ8pZ4herLYaIgICp+rXpxSLEbevL2jlemYDwInG950zdEZ/CgFBMadtXdmWw==",
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@gogitcms/gitcms-local-darwin-x64/-/gitcms-local-darwin-x64-0.42.0.tgz",
+      "integrity": "sha512-cqziOuLSOFJOTGzXmVSrkXROtcvJm44Dro+fjB4iluTdRdtvmt/g4KmJEuATKYVpwBn7nJqKnv+eIwezwkaAFQ==",
       "cpu": [
         "x64"
       ],
@@ -776,6 +776,32 @@
         "darwin"
       ]
     },
+    "node_modules/@gogitcms/gitcms-local-linux-x64": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@gogitcms/gitcms-local-linux-x64/-/gitcms-local-linux-x64-0.42.0.tgz",
+      "integrity": "sha512-hjcY5voX1Do9+BDg9QAAC2SEVLswsm/rHt38teLHKoXCEcFa6E90O2sVj9DqTsxS3HKYJoI8dy92iGoU3kkNYA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "UNLICENSED",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@gogitcms/gitcms-local-win32-x64": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@gogitcms/gitcms-local-win32-x64/-/gitcms-local-win32-x64-0.42.0.tgz",
+      "integrity": "sha512-0Po8OeY9Q43zhvEc6JnzQTInlZ4VVcgli6MDOYxrenTSyTDQmKVySrKeZkqOnDZfZzibqkcLe/JNlR7WOgOHvw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "UNLICENSED",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
     "node_modules/@graphql-typed-document-node/core": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/@graphql-typed-document-node/core/-/core-3.2.0.tgz",
@@ -4032,9 +4058,9 @@
       "license": "MIT"
     },
     "node_modules/posthog-js": {
-      "version": "1.427.0",
-      "resolved": "https://registry.npmjs.org/posthog-js/-/posthog-js-1.427.0.tgz",
-      "integrity": "sha512-FXrddoXpyLCcJAwIQ2Vhy6mwP6Ku2AdOlXJ5HUPS3BS8LmZvGDFe6zIBk4j8UGQdG4F9vIH10ASl8RKp5FAQEQ==",
+      "version": "1.427.1",
+      "resolved": "https://registry.npmjs.org/posthog-js/-/posthog-js-1.427.1.tgz",
+      "integrity": "sha512-jPKpF5qQS+SIzg2kJH6mTqkMEVY9YVBEywIccLFdl8A7zn+9aSnXQVv4xbF5gIjPtQe2MdcDugcyyJqfVrImLw==",
       "license": "(Apache-2.0 AND MIT)",
       "dependencies": {
         "@posthog/browser-common": "^0.7.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gogitcms/editor",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Terminal UI for setting up and running the Go·Git CMS content editor",
   "type": "module",
   "bin": {
@@ -65,10 +65,10 @@
     "@gogitcms/frontend": "workspace:*"
   },
   "optionalDependencies": {
-    "@gogitcms/gitcms-local-darwin-arm64": "0.41.0",
-    "@gogitcms/gitcms-local-darwin-x64": "0.41.0",
-    "@gogitcms/gitcms-local-linux-arm64": "0.41.0",
-    "@gogitcms/gitcms-local-linux-x64": "0.41.0",
-    "@gogitcms/gitcms-local-win32-x64": "0.41.0"
+    "@gogitcms/gitcms-local-darwin-arm64": "0.42.0",
+    "@gogitcms/gitcms-local-darwin-x64": "0.42.0",
+    "@gogitcms/gitcms-local-linux-arm64": "0.42.0",
+    "@gogitcms/gitcms-local-linux-x64": "0.42.0",
+    "@gogitcms/gitcms-local-win32-x64": "0.42.0"
   }
 }