gitmost/apps/client/src/features/editor/extensions/dictation-interim/dictation-interim.ts

import { Extension } from "@tiptap/core";
import type { Editor } from "@tiptap/core";
import { Plugin, PluginKey } from "@tiptap/pm/state";
import { Decoration, DecorationSet } from "@tiptap/pm/view";

// Plugin key shared by the extension and the imperative helpers below so they
// dispatch/read the same plugin state.
const dictationInterimKey = new PluginKey<DictationInterimState>(
  "dictationInterim",
);

interface DictationInterimState {
  // The current interim (partial) transcript. Empty string means "no ghost".
  text: string;
}

/**
 * Pure interim-state reducer (extracted for unit testing): a meta-only update
 * replaces the interim text; any other transaction passes the previous state
 * through unchanged. The decoration follows the caret on its own because it is
 * recomputed against the live selection on every render — so non-meta edits do
 * not need to touch this state.
 */
export function applyInterimMeta(
  meta: DictationInterimState | undefined,
  prev: DictationInterimState,
): DictationInterimState {
  if (meta) {
    return { text: meta.text };
  }
  return prev;
}

/**
 * B2 editor decoration: shows the realtime interim (partial) transcript as a
 * ghost widget at the caret. The interim is held ONLY in plugin meta state and
 * rendered as a widget Decoration — it is NEVER written into the document, so
 * it produces no Yjs update and no history entry. Only final segments are
 * committed (by the dictation-group / chat consumers).
 */
export const DictationInterim = Extension.create({
  name: "dictationInterim",

  addProseMirrorPlugins() {
    return [
      new Plugin<DictationInterimState>({
        key: dictationInterimKey,
        state: {
          init: (): DictationInterimState => ({ text: "" }),
          apply: (tr, value): DictationInterimState => {
            const meta = tr.getMeta(dictationInterimKey) as
              | DictationInterimState
              | undefined;
            return applyInterimMeta(meta, value);
          },
        },
        props: {
          decorations(state) {
            const pluginState = dictationInterimKey.getState(state);
            const text = pluginState?.text ?? "";
            if (!text) {
              return null;
            }

            // Render the interim as an inline ghost at the caret. Inline styles
            // keep this self-contained — no global CSS is required.
            const widget = Decoration.widget(
              state.selection.head,
              () => {
                const span = document.createElement("span");
                span.textContent = text;
                span.setAttribute("contenteditable", "false");
                span.style.opacity = "0.5";
                span.style.fontStyle = "italic";
                return span;
              },
              { side: 1, ignoreSelection: true },
            );

            return DecorationSet.create(state.doc, [widget]);
          },
        },
      }),
    ];
  },
});

/**
 * Set the interim ghost text via a META-ONLY transaction — no doc steps, so it
 * generates no Yjs update and no history entry.
 */
export function setDictationInterim(editor: Editor, text: string): void {
  editor.view.dispatch(
    editor.state.tr.setMeta(dictationInterimKey, { text }),
  );
}

/**
 * Clear the interim ghost text via a META-ONLY transaction (same no-op-on-doc
 * guarantee as setDictationInterim).
 */
export function clearDictationInterim(editor: Editor): void {
  editor.view.dispatch(
    editor.state.tr.setMeta(dictationInterimKey, { text: "" }),
  );
}

export default DictationInterim;