@octanejs/tiptap 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @octanejs/tiptap
+
+[TipTap](https://tiptap.dev) for the
+[Octane](https://github.com/octanejs/octane) UI framework.
+
+This package reuses the framework-independent `@tiptap/core` and `@tiptap/pm`
+packages and ports the editor binding layer from `@tiptap/react` to Octane. It is
+pinned to **TipTap 3.28.0** and re-exports the public `@tiptap/core` API from its
+root entry.
+
+```bash
+pnpm add @octanejs/tiptap @tiptap/starter-kit
+```
+
+```tsx
+import { EditorContent, useEditor } from '@octanejs/tiptap';
+import StarterKit from '@tiptap/starter-kit';
+
+export function RichTextEditor() @{
+	const editor = useEditor({
+		extensions: [StarterKit],
+		content: '<p>Hello from TipTap and Octane.</p>',
+	});
+
+	<EditorContent editor={editor} />
+}
+```
+
+## Current scope
+
+The initial binding includes:
+
+- `useEditor`, including create/update/recreate and deferred-destroy lifecycle
+  behavior;
+- `useEditorState`, with selector-based transaction subscriptions and deep-equal
+  bailout behavior;
+- `EditorContext`, `EditorProvider`, `EditorConsumer`, and `useCurrentEditor`;
+- `EditorContent` / `PureEditorContent` for adopting, switching, resetting, and
+  exposing the DOM of a normal `@tiptap/core` editor; and
+- `Tiptap`, `Tiptap.Content`, `useTiptap`, and `useTiptapState`.
+
+The portal bridge required by custom Octane NodeViews and MarkViews is the next
+stage. `ReactRenderer`, `ReactNodeViewRenderer`, `ReactMarkViewRenderer`,
+`useReactNodeView`, the NodeView wrapper/content components, and the `./menus`
+entry are therefore not part of this release yet. In particular, importing
+`@octanejs/tiptap/menus` is intentionally unsupported until `BubbleMenu` and
+`FloatingMenu` have working Octane implementations.
+
+On the server, editor construction is suppressed and hook snapshots use a `null`
+editor. Set `immediatelyRender: false` when the editor should remain nullable
+through the initial client render as well. The binding's SSR and hydration suite
+verifies deferred server output, adoption of the existing host DOM, and creation
+of the live editor after hydration.
+
+## Status
+
+Current scope, known divergences, and verification status are tracked in the
+generated [bindings status table](../../docs/bindings-status.md), sourced from
+this package's [`status.json`](./status.json).

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@octanejs/tiptap",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    },
+    "vite": {
+      "optimizeDeps": {
+        "exclude": [
+          "@tiptap/*"
+        ]
+      }
+    }
+  },
+  "description": "TipTap bindings for the Octane renderer — reuses @tiptap/core and @tiptap/pm and ports the React editor lifecycle, state subscriptions, contexts, content surface, and compound TipTap API onto Octane.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tiptap"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tiptap/core": "3.28.0",
+    "@tiptap/pm": "3.28.0",
+    "fast-equals": "^5.3.3"
+  },
+  "peerDependencies": {
+    "octane": "0.1.7"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@tiptap/react": "3.28.0",
+    "@tiptap/starter-kit": "3.28.0",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9",
+    "@octanejs/testing-library": "0.1.4",
+    "octane": "0.1.7"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/Context.ts

@@ -0,0 +1,16 @@
+import type { Editor } from '@tiptap/core';
+import { createContext, useContext } from 'octane';
+
+/** The editor value shared by the legacy TipTap context API. */
+export type EditorContextValue = {
+	editor: Editor | null;
+};
+
+export const EditorContext = createContext<EditorContextValue>({
+	editor: null,
+});
+
+/** Read the editor from the nearest `EditorProvider` or `Tiptap` component. */
+export function useCurrentEditor(): EditorContextValue {
+	return useContext(EditorContext);
+}

package/src/Context.tsrx

@@ -0,0 +1,42 @@
+// Ported from @tiptap/react 3.28.0 Context.tsx. Octane contexts intentionally
+// have no `.Consumer`; the compatibility component below implements the same
+// render-prop contract with useContext instead.
+import { isChildrenBlock, useMemo } from 'octane';
+
+import { EditorContext, useCurrentEditor } from './Context';
+import { EditorContent } from './EditorContent.tsrx';
+import { useEditor } from './useEditor';
+
+export function EditorConsumer(props) {
+	const value = useCurrentEditor();
+	const children = props.children;
+
+	if (typeof children !== 'function' || isChildrenBlock(children)) {
+		throw new TypeError('EditorConsumer expects a function as its only child.');
+	}
+
+	return children(value);
+}
+
+/**
+ * Create an editor and expose it to descendants through the legacy context.
+ */
+export function EditorProvider(props) @{
+	const { children, slotAfter, slotBefore, editorContainerProps = {}, ...editorOptions } = props;
+	const editor = useEditor(editorOptions);
+	const contextValue = useMemo(() => ({ editor }), [editor]);
+
+	if (!editor) {
+		return null;
+	}
+
+	<EditorContext.Provider value={contextValue}>
+		{slotBefore}
+		<EditorConsumer>
+			{({ editor: currentEditor }) =>
+				<EditorContent editor={currentEditor} {...editorContainerProps} />}
+		</EditorConsumer>
+		{children}
+		{slotAfter}
+	</EditorContext.Provider>
+}

package/src/Context.tsrx.d.ts

@@ -0,0 +1,23 @@
+import type { EditorContentProps } from './EditorContent.tsrx';
+import type { EditorContextValue } from './Context';
+import type { UseEditorOptions } from './useEditor';
+
+export interface EditorConsumerProps {
+	children: (value: EditorContextValue) => unknown;
+}
+
+export type EditorContainerProps = Omit<EditorContentProps, 'editor' | 'innerRef' | 'ref'> & {
+	editor?: never;
+	innerRef?: never;
+	ref?: never;
+};
+
+export type EditorProviderProps = UseEditorOptions & {
+	children?: unknown;
+	slotBefore?: unknown;
+	slotAfter?: unknown;
+	editorContainerProps?: EditorContainerProps;
+};
+
+export declare function EditorConsumer(props: EditorConsumerProps): unknown;
+export declare function EditorProvider(props: EditorProviderProps): unknown;

package/src/EditorContent.tsrx

@@ -0,0 +1,68 @@
+// DOM lifecycle bridge ported from @tiptap/react 3.28.0 EditorContent.tsx.
+// Portal-backed node and mark views intentionally arrive in the next stage;
+// this component owns only adoption, reset, editor switching, and host refs.
+import { memo, useLayoutEffect, useMemo, useRef } from 'octane';
+
+export function PureEditorContent(props) @{
+	const { editor, innerRef, ref, ...rest } = props;
+	const editorContentRef = useRef(null);
+
+	useLayoutEffect(() => {
+		if (!editor || editor.isDestroyed || editor.isEditorContentInitialized) {
+			return;
+		}
+
+		const element = editorContentRef.current;
+		const editorParent = editor.view.dom?.parentNode;
+
+		if (!element || !editorParent) {
+			return;
+		}
+
+		// The core Editor initially mounts into its own detached element. Move the
+		// complete ProseMirror-owned subtree into Octane's committed host element;
+		// moving nodes preserves the existing EditorView and DOM identity.
+		element.append(...editorParent.childNodes);
+		editor.setOptions({ element });
+		editor.createNodeViews();
+		editor.isEditorContentInitialized = true;
+
+		return () => {
+			editor.isEditorContentInitialized = false;
+
+			if (!editor.isDestroyed) {
+				editor.view.setProps({ nodeViews: {} });
+			}
+
+			// Reset the editor to a detached element so the still-live instance can
+			// safely be mounted by a later EditorContent. A view that has already
+			// been destroyed or never mounted has nothing left to transfer.
+			try {
+				const currentParent = editor.view.dom?.parentNode;
+
+				if (!currentParent) {
+					return;
+				}
+
+				const detachedElement = document.createElement('div');
+				detachedElement.append(...currentParent.childNodes);
+				editor.setOptions({ element: detachedElement });
+			} catch {
+				// The editor may have been destroyed before this layout cleanup.
+			}
+		};
+	}, [editor]);
+
+	<div {...rest} ref={[ref, innerRef, editorContentRef]} />
+}
+
+function EditorContentWithKey(props) @{
+	// Remount the host whenever the Editor identity changes, matching the keyed
+	// wrapper in @tiptap/react and preventing one editor from retaining another
+	// editor's managed DOM.
+	const key = useMemo(() => Math.floor(Math.random() * 4294967295).toString(), [props.editor]);
+
+	<PureEditorContent key={key} {...props} />
+}
+
+export const EditorContent = memo(EditorContentWithKey);

package/src/EditorContent.tsrx.d.ts

@@ -0,0 +1,21 @@
+import type { Editor } from '@tiptap/core';
+
+export type EditorContentRef<T> =
+	| { current: T | null }
+	| ((value: T | null) => void | (() => void))
+	| null;
+
+/**
+ * Props accepted by the Octane editor host. Unknown host attributes are passed
+ * through to the rendered `div` without introducing a React type dependency.
+ */
+export interface EditorContentProps {
+	editor: Editor | null;
+	ref?: EditorContentRef<HTMLDivElement>;
+	innerRef?: EditorContentRef<HTMLDivElement>;
+	children?: unknown;
+	[key: string]: unknown;
+}
+
+export declare function PureEditorContent(props: EditorContentProps): unknown;
+export declare const EditorContent: (props: EditorContentProps) => unknown;

package/src/Tiptap.tsrx

@@ -0,0 +1,73 @@
+// Ported from @tiptap/react 3.28.0 Tiptap.tsx. Refs remain ordinary props in
+// Octane, and the compound Tiptap.Content component needs no forwardRef layer.
+import { createContext, useContext, useMemo } from 'octane';
+
+import { EditorContext } from './Context';
+import { EditorContent } from './EditorContent.tsrx';
+import { splitSlot, subSlot } from './internal';
+import { useEditorState } from './useEditorState';
+
+export const TiptapContext = createContext({
+	get editor() {
+		throw new Error('useTiptap must be used within a <Tiptap> provider');
+	},
+});
+
+TiptapContext.displayName = 'TiptapContext';
+
+/** Read the editor instance provided by the nearest `Tiptap` component. */
+export function useTiptap() {
+	return useContext(TiptapContext);
+}
+
+/** Select a reactive slice of editor state from the context editor. */
+export function useTiptapState(selector, ...args) {
+	const [userArgs, slot] = splitSlot(args);
+	const equalityFn = userArgs[0];
+	const { editor } = useTiptap();
+
+	// Call through a non-hook-named alias because this source is itself compiled:
+	// the public call site's slot is already being forwarded explicitly here.
+	const selectEditorState = useEditorState;
+	return selectEditorState(
+		{
+			editor,
+			selector,
+			equalityFn,
+		},
+		subSlot(slot, 'tiptap:state'),
+	);
+}
+
+export function TiptapWrapper({ children, ...props }) @{
+	const resolvedEditor =
+		'editor' in props ? props.editor : props.instance;
+
+	if (!resolvedEditor) {
+		throw new Error('Tiptap: An editor instance is required. Pass a non-null `editor` prop.');
+	}
+
+	const tiptapContextValue = useMemo(() => ({ editor: resolvedEditor }), [resolvedEditor]);
+	const legacyContextValue = useMemo(() => ({ editor: resolvedEditor }), [resolvedEditor]);
+
+	<EditorContext.Provider value={legacyContextValue}>
+		<TiptapContext.Provider value={tiptapContextValue}>{children}</TiptapContext.Provider>
+	</EditorContext.Provider>
+}
+
+TiptapWrapper.displayName = 'Tiptap';
+
+/** Render EditorContent using the editor supplied by the nearest Tiptap root. */
+export function TiptapContent(props) @{
+	const { editor } = useTiptap();
+
+	<EditorContent editor={editor} {...props} />
+}
+
+TiptapContent.displayName = 'Tiptap.Content';
+
+export const Tiptap = Object.assign(TiptapWrapper, {
+	Content: TiptapContent,
+});
+
+export default Tiptap

package/src/Tiptap.tsrx.d.ts

@@ -0,0 +1,48 @@
+import type { Editor } from '@tiptap/core';
+import type { Context } from 'octane';
+
+import type { EditorContentProps } from './EditorContent.tsrx';
+import type { EditorStateSnapshot } from './useEditorState';
+
+export type TiptapContextType = {
+	/** The Tiptap editor instance. */
+	editor: Editor;
+};
+
+export declare const TiptapContext: Context<TiptapContextType> & {
+	displayName?: string;
+};
+
+export declare function useTiptap(): TiptapContextType;
+
+export declare function useTiptapState<TSelectorResult>(
+	selector: (context: EditorStateSnapshot<Editor>) => TSelectorResult,
+	equalityFn?: (a: TSelectorResult, b: TSelectorResult | null) => boolean,
+): TSelectorResult;
+
+export type TiptapWrapperEditorInstanceProps =
+	| {
+			editor: Editor;
+	  }
+	| {
+			/** @deprecated Use `editor` instead. */
+			instance: Editor;
+	  };
+
+export type TiptapWrapperProps = TiptapWrapperEditorInstanceProps & {
+	children: unknown;
+};
+
+export type TiptapContentProps = Omit<EditorContentProps, 'editor' | 'ref'> & {
+	editor?: never;
+	ref?: never;
+};
+
+export declare function TiptapWrapper(props: TiptapWrapperProps): unknown;
+export declare function TiptapContent(props: TiptapContentProps): unknown;
+
+export declare const Tiptap: typeof TiptapWrapper & {
+	Content: typeof TiptapContent;
+};
+
+export default Tiptap;

package/src/index.ts

@@ -0,0 +1,9 @@
+'use client';
+
+export * from './Context';
+export * from './Context.tsrx';
+export * from './EditorContent.tsrx';
+export * from './Tiptap.tsrx';
+export * from './useEditor';
+export * from './useEditorState';
+export * from '@tiptap/core';

package/src/internal.ts

@@ -0,0 +1,37 @@
+// Slot mechanics for @octanejs/tiptap's plain-`.ts` hooks. The Octane
+// compiler injects a per-call-site Symbol as the final argument of every
+// custom-hook call. Binding hooks split that argument from their public
+// options and derive one stable sub-slot for each base hook they compose.
+
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+const bareSlotCache = new Map<string, symbol>();
+
+export function subSlot(slot: symbol | undefined, tag: string): symbol {
+	if (slot === undefined) {
+		let bare = bareSlotCache.get(tag);
+		if (bare === undefined) {
+			bare = Symbol.for(`@octanejs/tiptap:${tag}`);
+			bareSlotCache.set(tag, bare);
+		}
+		return bare;
+	}
+
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) {
+		byTag = new Map();
+		subSlotCache.set(slot, byTag);
+	}
+
+	let result = byTag.get(tag);
+	if (result === undefined) {
+		result = Symbol.for(`${slot.description ?? ''}:@octanejs/tiptap:${tag}`);
+		byTag.set(tag, result);
+	}
+	return result;
+}
+
+/** Split a compiler-owned trailing slot from a custom hook's user arguments. */
+export function splitSlot(args: readonly unknown[]): [readonly unknown[], symbol | undefined] {
+	const tail = args.at(-1);
+	return typeof tail === 'symbol' ? [args.slice(0, -1), tail] : [args, undefined];
+}

package/src/useEditor.ts

@@ -0,0 +1,282 @@
+import { type EditorOptions, Editor } from '@tiptap/core';
+import { useDebugValue, useEffect, useRef, useState, useSyncExternalStore } from 'octane';
+
+import { splitSlot, subSlot } from './internal';
+import { useEditorState, type UseEditorStateOptions } from './useEditorState';
+
+type DependencyList = readonly unknown[];
+type MutableRefObject<T> = { current: T };
+
+const isDev = process.env.NODE_ENV !== 'production';
+const isSSR = typeof window === 'undefined';
+const isNext = isSSR || Boolean(typeof window !== 'undefined' && (window as any).next);
+
+export type UseEditorOptions = Partial<EditorOptions> & {
+	/**
+	 * Whether to create the editor during the first render. Set this to `false`
+	 * for server-rendered applications.
+	 * @default true
+	 */
+	immediatelyRender?: boolean;
+	/**
+	 * Whether every editor transaction should re-render the component.
+	 * @default false
+	 */
+	shouldRerenderOnTransaction?: boolean;
+};
+
+const editorCallbackOptions = new Set<keyof UseEditorOptions>([
+	'onBeforeCreate',
+	'onBlur',
+	'onCreate',
+	'onDestroy',
+	'onFocus',
+	'onSelectionUpdate',
+	'onTransaction',
+	'onUpdate',
+	'onContentError',
+	'onDrop',
+	'onPaste',
+	'onDelete',
+	'onMount',
+	'onUnmount',
+]);
+
+/** Manages editor creation, option updates, recreation, and deferred teardown. */
+class EditorInstanceManager {
+	private editor: Editor | null = null;
+
+	private options: MutableRefObject<UseEditorOptions>;
+
+	private subscriptions = new Set<() => void>();
+
+	private scheduledDestructionTimeout: ReturnType<typeof setTimeout> | undefined;
+
+	private isComponentMounted = false;
+
+	private previousDeps: DependencyList | null = null;
+
+	public instanceId = '';
+
+	constructor(options: MutableRefObject<UseEditorOptions>) {
+		this.options = options;
+		this.setEditor(this.getInitialEditor());
+		this.scheduleDestroy();
+
+		this.getEditor = this.getEditor.bind(this);
+		this.getServerSnapshot = this.getServerSnapshot.bind(this);
+		this.subscribe = this.subscribe.bind(this);
+		this.refreshEditorInstance = this.refreshEditorInstance.bind(this);
+		this.scheduleDestroy = this.scheduleDestroy.bind(this);
+		this.onRender = this.onRender.bind(this);
+		this.createEditor = this.createEditor.bind(this);
+	}
+
+	private setEditor(editor: Editor | null): void {
+		this.editor = editor;
+		this.instanceId = Math.random().toString(36).slice(2, 9);
+		this.subscriptions.forEach((callback) => callback());
+	}
+
+	private getInitialEditor(): Editor | null {
+		const explicit = this.options.current.immediatelyRender;
+		let immediatelyRender = explicit ?? true;
+
+		if (isSSR) {
+			if (immediatelyRender && isDev) {
+				console.warn(
+					'SSR detected. `immediatelyRender` has been set to false to avoid hydration mismatches',
+				);
+			}
+			immediatelyRender = false;
+		} else if (isNext && explicit === undefined) {
+			immediatelyRender = false;
+			if (isDev) {
+				console.warn(
+					'Next.js detected. `immediatelyRender` defaults to false to avoid hydration mismatches. Pass `immediatelyRender: true` explicitly if you are rendering the editor only on the client.',
+				);
+			}
+		}
+
+		return immediatelyRender ? this.createEditor() : null;
+	}
+
+	private createEditor(): Editor {
+		const optionsToApply: Partial<EditorOptions> = {
+			...this.options.current,
+			onBeforeCreate: (...args) => this.options.current.onBeforeCreate?.(...args),
+			onBlur: (...args) => this.options.current.onBlur?.(...args),
+			onCreate: (...args) => this.options.current.onCreate?.(...args),
+			onDestroy: (...args) => this.options.current.onDestroy?.(...args),
+			onFocus: (...args) => this.options.current.onFocus?.(...args),
+			onSelectionUpdate: (...args) => this.options.current.onSelectionUpdate?.(...args),
+			onTransaction: (...args) => this.options.current.onTransaction?.(...args),
+			onUpdate: (...args) => this.options.current.onUpdate?.(...args),
+			onContentError: (...args) => this.options.current.onContentError?.(...args),
+			onDrop: (...args) => this.options.current.onDrop?.(...args),
+			onPaste: (...args) => this.options.current.onPaste?.(...args),
+			onDelete: (...args) => this.options.current.onDelete?.(...args),
+			onMount: (...args) => this.options.current.onMount?.(...args),
+			onUnmount: (...args) => this.options.current.onUnmount?.(...args),
+		};
+
+		return new Editor(optionsToApply);
+	}
+
+	getEditor(): Editor | null {
+		return this.editor;
+	}
+
+	getServerSnapshot(): null {
+		return null;
+	}
+
+	subscribe(onStoreChange: () => void): () => void {
+		this.subscriptions.add(onStoreChange);
+		return () => {
+			this.subscriptions.delete(onStoreChange);
+		};
+	}
+
+	static compareOptions(left: UseEditorOptions, right: UseEditorOptions): boolean {
+		return (Object.keys(left) as (keyof UseEditorOptions)[]).every((key) => {
+			if (editorCallbackOptions.has(key)) {
+				return true;
+			}
+
+			if (key === 'extensions' && left.extensions && right.extensions) {
+				return (
+					left.extensions.length === right.extensions.length &&
+					left.extensions.every((extension, index) => extension === right.extensions?.[index])
+				);
+			}
+
+			return left[key] === right[key];
+		});
+	}
+
+	onRender(deps: DependencyList): () => () => void {
+		return () => {
+			this.isComponentMounted = true;
+			clearTimeout(this.scheduledDestructionTimeout);
+
+			if (this.editor && !this.editor.isDestroyed && deps.length === 0) {
+				if (!EditorInstanceManager.compareOptions(this.options.current, this.editor.options)) {
+					this.editor.setOptions({
+						...this.options.current,
+						editable: this.editor.isEditable,
+					});
+				}
+			} else {
+				this.refreshEditorInstance(deps);
+			}
+
+			return () => {
+				this.isComponentMounted = false;
+				this.scheduleDestroy();
+			};
+		};
+	}
+
+	private refreshEditorInstance(deps: DependencyList): void {
+		if (this.editor && !this.editor.isDestroyed) {
+			if (this.previousDeps === null) {
+				this.previousDeps = deps;
+				return;
+			}
+
+			const depsAreEqual =
+				this.previousDeps.length === deps.length &&
+				this.previousDeps.every((dependency, index) => dependency === deps[index]);
+			if (depsAreEqual) {
+				return;
+			}
+		}
+
+		if (this.editor && !this.editor.isDestroyed) {
+			this.editor.destroy();
+		}
+
+		this.setEditor(this.createEditor());
+		this.previousDeps = deps;
+	}
+
+	private scheduleDestroy(): void {
+		const currentInstanceId = this.instanceId;
+		const currentEditor = this.editor;
+
+		this.scheduledDestructionTimeout = setTimeout(() => {
+			if (this.isComponentMounted && this.instanceId === currentInstanceId) {
+				currentEditor?.setOptions(this.options.current);
+				return;
+			}
+
+			if (currentEditor && !currentEditor.isDestroyed) {
+				currentEditor.destroy();
+				if (this.instanceId === currentInstanceId) {
+					this.setEditor(null);
+				}
+			}
+		}, 1);
+	}
+}
+
+export function useEditor(
+	options: UseEditorOptions & { immediatelyRender: false },
+	deps?: DependencyList,
+): Editor | null;
+export function useEditor(options: UseEditorOptions, deps?: DependencyList): Editor;
+export function useEditor(
+	...args: [options?: UseEditorOptions, deps?: DependencyList, slot?: symbol]
+): Editor | null {
+	const [userArgs, slot] = splitSlot(args);
+	const options = (userArgs[0] as UseEditorOptions | undefined) ?? {};
+	const deps = (userArgs[1] as DependencyList | undefined) ?? [];
+	const mostRecentOptions = useRef(options, subSlot(slot, 'editor:options'));
+
+	mostRecentOptions.current = options;
+
+	const [instanceManager] = useState(
+		() => new EditorInstanceManager(mostRecentOptions),
+		subSlot(slot, 'editor:manager'),
+	);
+	const editor = useSyncExternalStore(
+		instanceManager.subscribe,
+		instanceManager.getEditor,
+		instanceManager.getServerSnapshot,
+		subSlot(slot, 'editor:store'),
+	);
+
+	useDebugValue(editor, undefined, subSlot(slot, 'editor:debug'));
+
+	// TipTap intentionally performs this lifecycle pass after every render. In
+	// Octane, `null` is the explicit opt-out from inferred dependency arrays.
+	useEffect(instanceManager.onRender(deps), null, subSlot(slot, 'editor:lifecycle'));
+
+	const useEditorStateWithSlot = useEditorState as <TSelectorResult>(
+		options: UseEditorStateOptions<TSelectorResult, Editor | null>,
+		slot: symbol,
+	) => TSelectorResult | null;
+	useEditorStateWithSlot(
+		{
+			editor,
+			selector: ({ transactionNumber }) => {
+				if (
+					options.shouldRerenderOnTransaction === false ||
+					options.shouldRerenderOnTransaction === undefined
+				) {
+					return null;
+				}
+
+				if (options.immediatelyRender && transactionNumber === 0) {
+					return 0;
+				}
+
+				return transactionNumber + 1;
+			},
+		},
+		subSlot(slot, 'editor:state'),
+	);
+
+	return editor;
+}

package/src/useEditorState.ts

@@ -0,0 +1,137 @@
+import type { Editor } from '@tiptap/core';
+import { deepEqual } from 'fast-equals';
+import { useDebugValue, useEffect, useLayoutEffect, useState } from 'octane';
+
+import { splitSlot, subSlot } from './internal';
+import { useSyncExternalStoreWithSelector } from './useSyncExternalStoreWithSelector';
+
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
+export type EditorStateSnapshot<TEditor extends Editor | null = Editor | null> = {
+	editor: TEditor;
+	transactionNumber: number;
+};
+
+export type UseEditorStateOptions<
+	TSelectorResult,
+	TEditor extends Editor | null = Editor | null,
+> = {
+	/** The editor instance to observe. */
+	editor: TEditor;
+	/** Select the value that should drive component re-renders. */
+	selector: (context: EditorStateSnapshot<TEditor>) => TSelectorResult;
+	/** @default `deepEqual` from `fast-equals`. */
+	equalityFn?: (left: TSelectorResult, right: TSelectorResult | null) => boolean;
+};
+
+/**
+ * Synchronizes a TipTap editor's transactions with a stable external-store
+ * snapshot, independently of component re-renders.
+ */
+class EditorStateManager<TEditor extends Editor | null = Editor | null> {
+	private transactionNumber = 0;
+
+	private lastTransactionNumber = 0;
+
+	private lastSnapshot: EditorStateSnapshot<TEditor>;
+
+	private editor: TEditor;
+
+	private subscribers = new Set<() => void>();
+
+	constructor(initialEditor: TEditor) {
+		this.editor = initialEditor;
+		this.lastSnapshot = { editor: initialEditor, transactionNumber: 0 };
+
+		this.getSnapshot = this.getSnapshot.bind(this);
+		this.getServerSnapshot = this.getServerSnapshot.bind(this);
+		this.watch = this.watch.bind(this);
+		this.subscribe = this.subscribe.bind(this);
+	}
+
+	getSnapshot(): EditorStateSnapshot<TEditor> {
+		if (this.transactionNumber === this.lastTransactionNumber) {
+			return this.lastSnapshot;
+		}
+
+		this.lastTransactionNumber = this.transactionNumber;
+		this.lastSnapshot = { editor: this.editor, transactionNumber: this.transactionNumber };
+		return this.lastSnapshot;
+	}
+
+	getServerSnapshot(): EditorStateSnapshot<null> {
+		return { editor: null, transactionNumber: 0 };
+	}
+
+	subscribe(callback: () => void): () => void {
+		this.subscribers.add(callback);
+		return () => {
+			this.subscribers.delete(callback);
+		};
+	}
+
+	watch(nextEditor: Editor | null): undefined | (() => void) {
+		if (this.editor !== nextEditor) {
+			this.editor = nextEditor as TEditor;
+			this.lastTransactionNumber = this.transactionNumber;
+			this.lastSnapshot = {
+				editor: this.editor,
+				transactionNumber: this.transactionNumber,
+			};
+			this.subscribers.forEach((callback) => callback());
+		}
+
+		if (!this.editor) {
+			return undefined;
+		}
+
+		const onTransaction = () => {
+			this.transactionNumber += 1;
+			this.subscribers.forEach((callback) => callback());
+		};
+		const currentEditor = this.editor;
+
+		currentEditor.on('transaction', onTransaction);
+		return () => {
+			currentEditor.off('transaction', onTransaction);
+		};
+	}
+}
+
+export function useEditorState<TSelectorResult>(
+	options: UseEditorStateOptions<TSelectorResult, Editor>,
+): TSelectorResult;
+export function useEditorState<TSelectorResult>(
+	options: UseEditorStateOptions<TSelectorResult, Editor | null>,
+): TSelectorResult | null;
+export function useEditorState<TSelectorResult>(
+	options:
+		| UseEditorStateOptions<TSelectorResult, Editor>
+		| UseEditorStateOptions<TSelectorResult, Editor | null>,
+	...args: [slot?: symbol]
+): TSelectorResult | null {
+	const [, slot] = splitSlot(args);
+	const [editorStateManager] = useState(
+		() => new EditorStateManager(options.editor),
+		subSlot(slot, 'editor-state:manager'),
+	);
+
+	const selectedState = useSyncExternalStoreWithSelector(
+		editorStateManager.subscribe,
+		editorStateManager.getSnapshot,
+		editorStateManager.getServerSnapshot,
+		options.selector as UseEditorStateOptions<TSelectorResult, Editor | null>['selector'],
+		options.equalityFn ?? deepEqual,
+		subSlot(slot, 'editor-state:selector'),
+	);
+
+	useIsomorphicLayoutEffect(
+		() => editorStateManager.watch(options.editor),
+		[options.editor, editorStateManager],
+		subSlot(slot, 'editor-state:watch'),
+	);
+
+	useDebugValue(selectedState, undefined, subSlot(slot, 'editor-state:debug'));
+
+	return selectedState;
+}

package/src/useSyncExternalStoreWithSelector.ts

@@ -0,0 +1,104 @@
+// Port of `use-sync-external-store/with-selector` onto Octane's native
+// useSyncExternalStore. Snapshot memoization preserves the previous selected
+// reference when the equality function accepts a new selection.
+import { useEffect, useMemo, useRef, useSyncExternalStore } from 'octane';
+
+import { splitSlot, subSlot } from './internal';
+
+const objectIs: (left: unknown, right: unknown) => boolean =
+	typeof Object.is === 'function'
+		? Object.is
+		: (left: any, right: any) =>
+				(left === right && (left !== 0 || 1 / left === 1 / right)) ||
+				(left !== left && right !== right);
+
+export function useSyncExternalStoreWithSelector<Snapshot, Selection>(
+	subscribe: (onStoreChange: () => void) => () => void,
+	getSnapshot: () => Snapshot,
+	getServerSnapshot: undefined | null | (() => Snapshot),
+	selector: (snapshot: Snapshot) => Selection,
+	...args: [isEqual?: (left: Selection, right: Selection) => boolean, slot?: symbol]
+): Selection {
+	const [userArgs, slot] = splitSlot(args);
+	const isEqual = userArgs[0] as ((left: Selection, right: Selection) => boolean) | undefined;
+	const instRef = useRef<{ hasValue: boolean; value: Selection | null } | null>(
+		null,
+		subSlot(slot, 'selector:instance'),
+	);
+
+	let inst: { hasValue: boolean; value: Selection | null };
+	if (instRef.current === null) {
+		inst = { hasValue: false, value: null };
+		instRef.current = inst;
+	} else {
+		inst = instRef.current;
+	}
+
+	const [getSelection, getServerSelection] = useMemo(
+		() => {
+			let hasMemo = false;
+			let memoizedSnapshot: Snapshot;
+			let memoizedSelection: Selection;
+
+			const memoizedSelector = (nextSnapshot: Snapshot): Selection => {
+				if (!hasMemo) {
+					hasMemo = true;
+					memoizedSnapshot = nextSnapshot;
+					const nextSelection = selector(nextSnapshot);
+
+					if (isEqual !== undefined && inst.hasValue) {
+						const currentSelection = inst.value as Selection;
+						if (isEqual(currentSelection, nextSelection)) {
+							memoizedSelection = currentSelection;
+							return currentSelection;
+						}
+					}
+
+					memoizedSelection = nextSelection;
+					return nextSelection;
+				}
+
+				const currentSelection = memoizedSelection;
+				if (objectIs(memoizedSnapshot, nextSnapshot)) {
+					return currentSelection;
+				}
+
+				const nextSelection = selector(nextSnapshot);
+				if (isEqual !== undefined && isEqual(currentSelection, nextSelection)) {
+					memoizedSnapshot = nextSnapshot;
+					return currentSelection;
+				}
+
+				memoizedSnapshot = nextSnapshot;
+				memoizedSelection = nextSelection;
+				return nextSelection;
+			};
+
+			const serverSnapshot = getServerSnapshot ?? undefined;
+			return [
+				() => memoizedSelector(getSnapshot()),
+				serverSnapshot === undefined ? undefined : () => memoizedSelector(serverSnapshot()),
+			] as const;
+		},
+		[getSnapshot, getServerSnapshot, selector, isEqual],
+		subSlot(slot, 'selector:memo'),
+	);
+
+	const value = useSyncExternalStore(
+		subscribe,
+		getSelection,
+		getServerSelection ?? getSelection,
+		subSlot(slot, 'selector:store'),
+	);
+
+	useEffect(
+		() => {
+			inst.hasValue = true;
+			inst.value = value;
+		},
+		[value],
+		subSlot(slot, 'selector:effect'),
+	);
+
+	return value;
+}