@octane-xplat/tiptap 0.9.0 → 0.11.0

package/src/TiptapEditor.tsrx

@@ -1,8 +1,8 @@
 /** @jsxImportSource @nativescript-community/octane */
-import { useCallback, useEffect, useRef } from 'octane'
+import { useState, useImperativeHandle, useCallback, useEffect, useRef } from 'octane'
 import { RichTextEditor, supported as leafSupported } from '@octane-xplat/richtext'
 import type { RichTextEditorHandle } from '@octane-xplat/richtext'
-import type { TiptapEditorHandle, TiptapEditorProps } from './types'
+import type { TiptapEditorHandle, TiptapEditorProps, TiptapJSON } from './types'
 import { ensureJSONBridge, htmlToJSON, jsonBridgeReady, jsonToHTML } from './json-bridge'
 
 export const supported = leafSupported
@@ -12,22 +12,47 @@ export const supported = leafSupported
  *  renderToHTMLString) handles JSON interchange on top of it. */
 export function TiptapEditor(props: TiptapEditorProps) @{
 	const inner = useRef<RichTextEditorHandle | null>(null)
-	const jsonReady = useRef(false)
+	const [exposedHandle, setHandle] = useState<TiptapEditorHandle | null>(null)
+	useImperativeHandle<TiptapEditorHandle | null>(props.ref, () => exposedHandle, [exposedHandle])
 	const lastJSON = useRef<string | undefined>(undefined)
+	const appliedHost = useRef<RichTextEditorHandle | null>(null)
+	// Latest doc requested for the host — by `json` prop or `setJSON`. Kept
+	// after a successful push so a rebound (recreated) host still gets it.
+	const desiredDoc = useRef<TiptapJSON | undefined>(undefined)
 
-	const bindHost = useCallback((h: RichTextEditorHandle) => {
+	// Push the requested doc once both halves are up — the JSON bridge
+	// (async module load) and the bound host (ref/onReady timing). Skips the
+	// stamp the host already shows, so editor-emitted echoes and repeat props
+	// never reach setHTML; a different host always gets its own copy.
+	const applyDoc = () => {
+		const host = inner.current
+		const doc = desiredDoc.current
+		if (!host || doc === undefined || !jsonBridgeReady()) return
+		const stamp = JSON.stringify(doc)
+		if (stamp === lastJSON.current && appliedHost.current === host) return
+		const html = jsonToHTML(doc)
+		if (html != null) {
+			lastJSON.current = stamp
+			appliedHost.current = host
+			host.setHTML(html)
+		}
+	}
+
+	const bindHost = useCallback((h: RichTextEditorHandle | null) => {
 		inner.current = h
+		if (h) {
+			// The ref binds inside the leaf's commit, before its own `value`
+			// seed — defer so `json` keeps precedence over `value`.
+			queueMicrotask(applyDoc)
+		}
 
-		props.bind?.({
+		setHandle((previous) => previous?.native === h?.native ? previous : h ? ({
 			getHTML: () => h.getHTML(),
 			setHTML: (html: string) => h.setHTML(html),
 			getJSON: () => (jsonBridgeReady() ? htmlToJSON(h.getHTML()) : null),
 			setJSON: (doc) => {
-				const html = jsonBridgeReady() ? jsonToHTML(doc) : null
-				if (html != null) {
-					lastJSON.current = JSON.stringify(doc)
-					h.setHTML(html)
-				}
+				desiredDoc.current = doc
+				applyDoc()
 			},
 			apply: (format) => h.apply(format),
 			linkTo: (url, anchor) => h.linkTo(url, anchor),
@@ -39,29 +64,32 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 			blur: () => h.blur(),
 			isFocused: () => h.isFocused(),
 			native: h.native,
-		} satisfies TiptapEditorHandle)
+		} satisfies TiptapEditorHandle) : null)
 	}, [])
 
 	// The bridge loads once per process — dynamic imports of the DOM-free
-	// tiptap slices, plus the zeed-dom parse shim.
+	// tiptap slices, plus the zeed-dom parse shim. A doc that arrived before
+	// it settles is applied here, not dropped.
 	useEffect(() => {
+		let alive = true
 		ensureJSONBridge().then((ok) => {
-			jsonReady.current = ok
+			if (!alive) return
 			props.onJSONReady?.(ok)
+			applyDoc()
 		})
+
+		return () => {
+			alive = false
+		}
 	}, [])
 
-	// `json` prop → editor content, when the bridge is up and the doc wasn't
-	// emitted by the editor itself.
+	// `json` prop → editor content. It may land before the bridge settles or
+	// before the host binds — park it in desiredDoc and let the readiness
+	// flushes apply it.
 	useEffect(() => {
-		if (!props.json || !jsonBridgeReady() || !inner.current) return
-		const stamp = JSON.stringify(props.json)
-		if (stamp === lastJSON.current) return
-		const html = jsonToHTML(props.json)
-		if (html != null) {
-			lastJSON.current = stamp
-			inner.current.setHTML(html)
-		}
+		if (!props.json) return
+		desiredDoc.current = props.json
+		applyDoc()
 	}, [props.json])
 
 	const emitJSON = () => {
@@ -69,6 +97,7 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 		const doc = htmlToJSON(inner.current.getHTML())
 		if (doc) {
 			lastJSON.current = JSON.stringify(doc)
+			appliedHost.current = inner.current
 			props.onJSONChange?.(doc)
 		}
 	}
@@ -81,7 +110,12 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 		placeholder={props.placeholder}
 		editable={props.editable}
 		autofocus={props.autofocus}
-		onReady={props.onReady}
+		onReady={() => {
+			// Host signalled ready after the leaf's own initial content seed —
+			// the last apply point that still outranks a `value` prop.
+			applyDoc()
+			props.onReady?.()
+		}}
 		onChange={(html) => {
 			props.onChange?.(html)
 			emitJSON()
@@ -89,7 +123,7 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 		onSelectionChange={props.onSelectionChange}
 		onFocus={props.onFocus}
 		onBlur={props.onBlur}
-		bind={bindHost}
+		ref={bindHost}
 		android={props.android}
 		ios={props.ios}
 		row={props.row}

package/src/TiptapEditor.web.test.tsrx

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it, vi } from 'vitest'
+import { act, createRoot } from 'octane'
+import { Extension, Mark, Node } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { TiptapEditor } from './TiptapEditor.web.tsrx'
+import type { TiptapEditorHandle } from './types'
+
+const Spoiler = Mark.create({
+	name: 'spoiler',
+	parseHTML: () => [{ tag: 'span[data-spoiler]' }],
+	renderHTML: () => ['span', { 'data-spoiler': '' }, 0],
+})
+
+const Shout = Extension.create({
+	name: 'shout',
+	addCommands() {
+		return {
+			shout: () => ({ commands }: any) => commands.setContent('<p>SHOUT</p>'),
+		}
+	},
+})
+
+// Minimal schema for the starterKit:false path — callers dropping the
+// built-in kit supply the base nodes themselves.
+const Doc = Node.create({ name: 'doc', topNode: true, content: 'block+' })
+const Paragraph = Node.create({
+	name: 'paragraph',
+	group: 'block',
+	content: 'inline*',
+	parseHTML: () => [{ tag: 'p' }],
+	renderHTML: () => ['p', 0],
+})
+
+const Text = Node.create({ name: 'text', group: 'inline' })
+
+const roots: any[] = []
+
+function mount(props: any = {}) {
+	const el = document.createElement('div')
+	document.body.append(el)
+	const root = createRoot(el)
+	roots.push(root)
+	let handle: TiptapEditorHandle | null = null
+	act(() =>
+		root.render(
+			<TiptapEditor
+				{...props}
+				ref={(next: TiptapEditorHandle | null) => {
+					handle = next
+				}}
+			/>,
+		),
+	)
+
+	return { el, root, get handle() { return handle } }
+}
+
+afterEach(() => {
+	for (const root of roots.splice(0)) act(() => root.unmount())
+	document.body.innerHTML = ''
+	vi.restoreAllMocks()
+})
+
+it('mounts StarterKit by default', () => {
+	const { handle } = mount({ value: '<p>Travel notes</p>' })
+	const editor = handle!.native
+	expect(editor.schema.marks.bold).toBeTruthy()
+	expect(editor.schema.nodes.heading).toBeTruthy()
+	expect(handle!.getHTML()).toContain('<p>Travel notes</p>')
+})
+
+it('registers caller mark extensions alongside StarterKit', () => {
+	const { handle } = mount({
+		value: '<p>shh <span data-spoiler>secret</span></p>',
+		web: { extensions: [Spoiler] },
+	})
+
+	const editor = handle!.native
+	expect(editor.schema.marks.spoiler).toBeTruthy()
+	expect(editor.schema.marks.bold).toBeTruthy()
+
+	const doc = handle!.getJSON()!
+	const marks = JSON.stringify(doc)
+	expect(marks).toContain('"spoiler"')
+	expect(handle!.getHTML()).toContain('data-spoiler')
+})
+
+it('exposes commands added by caller extensions', () => {
+	const { handle } = mount({ web: { extensions: [Shout] } })
+	handle!.native.commands.shout()
+	expect(handle!.getHTML()).toContain('SHOUT')
+})
+
+it('passes starterKit options to the built-in kit', () => {
+	const { handle } = mount({ web: { starterKit: { link: false } } })
+	const editor = handle!.native
+	expect(editor.schema.marks.link).toBeUndefined()
+	expect(editor.schema.marks.bold).toBeTruthy()
+})
+
+it('hands the schema to caller extensions when starterKit is false', () => {
+	const { handle } = mount({
+		web: { starterKit: false, extensions: [Doc, Paragraph, Text, Spoiler] },
+	})
+
+	const editor = handle!.native
+	expect(editor.schema.marks.spoiler).toBeTruthy()
+	expect(editor.schema.marks.bold).toBeUndefined()
+	expect(editor.schema.nodes.heading).toBeUndefined()
+})
+
+it('never registers StarterKit twice', () => {
+	const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+	const { handle } = mount({
+		web: { extensions: [StarterKit.configure({ link: false })] },
+	})
+
+	const kits = handle!.native.extensionManager.extensions.filter(
+		(extension: any) => extension.name === 'starterKit',
+	)
+
+	expect(kits).toHaveLength(1)
+	expect(handle!.native.schema.marks.link).toBeUndefined()
+	expect(warn).not.toHaveBeenCalledWith(
+		expect.stringContaining('Duplicate extension names'),
+	)
+})

package/src/TiptapEditor.web.tsrx

@@ -1,7 +1,8 @@
-import { useEffect, useRef } from 'octane'
+import { useImperativeHandle, useEffect, useMemo, useRef } from 'octane'
 import { EditorContent, useEditor } from '@octanejs/tiptap'
 import StarterKit from '@tiptap/starter-kit'
-import type { TiptapEditorHandle, TiptapEditorProps, TiptapFormat } from './types'
+import type { Extensions } from '@tiptap/core'
+import type { TiptapEditorHandle, TiptapEditorProps, TiptapFormat, TiptapWebOptions } from './types'
 
 export const supported = true
 
@@ -27,19 +28,6 @@ const COMMAND: Record<WebFormat, (chain: any) => any> = {
 	heading6: (c) => c.toggleHeading({ level: 6 }),
 }
 
-const IS_ACTIVE: Partial<Record<TiptapFormat, (editor: any) => boolean>> = {
-	bold: (e) => e.isActive('bold'),
-	italic: (e) => e.isActive('italic'),
-	underline: (e) => e.isActive('underline'),
-	strikethrough: (e) => e.isActive('strike'),
-	code: (e) => e.isActive('code'),
-	blockquote: (e) => e.isActive('blockquote'),
-	bulletList: (e) => e.isActive('bulletList'),
-	orderedList: (e) => e.isActive('orderedList'),
-	codeBlock: (e) => e.isActive('codeBlock'),
-	link: (e) => e.isActive('link'),
-}
-
 const ACTIVE_OF: [TiptapFormat, string, any?][] = [
 	['bold', 'bold'],
 	['italic', 'italic'],
@@ -69,16 +57,39 @@ function activeFormats(editor: any): TiptapFormat[] {
 	return out
 }
 
+/** Extension list for the web engine: the built-in StarterKit (optionally
+ *  configured) followed by caller extras. `starterKit: false` or a
+ *  starterKit-named caller entry hands the schema over to the caller —
+ *  registering two StarterKits trips tiptap's duplicate-name warning. */
+function resolveExtensions(web: TiptapWebOptions | undefined): Extensions {
+	const extras = web?.extensions ?? []
+	if (web?.starterKit === false || extras.some((ext) => ext?.name === 'starterKit')) {
+		return extras
+	}
+
+	const kit = web?.starterKit ? StarterKit.configure(web.starterKit) : StarterKit
+	return [kit, ...extras]
+}
+
 /** Unified editor facade, web half — a thin adapter over the published
  *  `@octanejs/tiptap` binding (useEditor + EditorContent + StarterKit). */
 export function TiptapEditor(props: TiptapEditorProps) @{
 	const lastEmitted = useRef<string | undefined>(undefined)
 	const lastJSON = useRef<string | undefined>(undefined)
+	const lastHTMLInput = useRef(JSON.stringify([props.json !== undefined, props.value]))
+	const lastJSONInput = useRef(JSON.stringify(props.json))
 	const bound = useRef<TiptapEditorHandle | undefined>(undefined)
 
+	// tiptap fixes the schema at construction; memoized on the option values
+	// so a stable caller config never re-triggers setOptions.
+	const extensions = useMemo(
+		() => resolveExtensions(props.web),
+		[props.web?.extensions, props.web?.starterKit],
+	)
+
 	const editor = useEditor({
-		extensions: [StarterKit],
-		content: (props.value ?? props.json ?? '') as any,
+		extensions,
+		content: (props.json ?? props.value ?? '') as any,
 		editable: props.editable !== false,
 		autofocus: props.autofocus ?? false,
 		onCreate: () => props.onReady?.(),
@@ -103,14 +114,21 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 	// External `value` changes push setContent; editor-emitted HTML is skipped
 	// (the transaction already owns the doc).
 	useEffect(() => {
-		if (!editor || props.value === undefined) return
+		if (!editor) return
+		const stamp = JSON.stringify([props.json !== undefined, props.value])
+		if (stamp === lastHTMLInput.current) return
+		lastHTMLInput.current = stamp
+		if (props.value === undefined || props.json !== undefined) return
 		if (props.value === lastEmitted.current) return
 		editor.commands.setContent(props.value)
-	}, [editor, props.value])
+	}, [editor, props.value, props.json])
 
 	useEffect(() => {
-		if (!editor || props.json === undefined) return
-		if (JSON.stringify(props.json) === lastJSON.current) return
+		if (!editor) return
+		const stamp = JSON.stringify(props.json)
+		if (stamp === lastJSONInput.current) return
+		lastJSONInput.current = stamp
+		if (props.json === undefined || stamp === lastJSON.current) return
 		editor.commands.setContent(props.json as any)
 	}, [editor, props.json])
 
@@ -121,8 +139,8 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 
 	// The handle rebinds whenever the editor instance appears — stable
 	// afterward (useEditor keeps the instance identity).
-	useEffect(() => {
-		if (!editor || bound.current?.native === editor) return
+	useImperativeHandle<TiptapEditorHandle | null>(props.ref, () => {
+		if (!editor) return null
 		const e: any = editor
 		bound.current = {
 			getHTML: () => e.getHTML(),
@@ -141,7 +159,7 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 				}
 			},
 			removeLink: () => e.chain().focus().unsetLink().run(),
-			isActive: (format) => IS_ACTIVE[format]?.(e) ?? false,
+			isActive: (format) => activeFormats(e).includes(format),
 			undo: () => e.commands.undo(),
 			redo: () => e.commands.redo(),
 			focus: () => e.commands.focus(),
@@ -150,7 +168,7 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 			native: e,
 		}
 
-		props.bind?.(bound.current)
+		return bound.current
 	}, [editor])
 
 	<div className={['vx-richtext', props.className]} style={props.style}>

package/src/browser-entry.web.tsx

@@ -0,0 +1,5 @@
+import { createRoot } from 'octane'
+import { TiptapEditor } from './TiptapEditor.web.tsrx'
+import { installEditorDocument } from '@octane-xplat/richtext/browser-transport'
+const root = createRoot(document.getElementById('root')!)
+installEditorDocument((props) => root.render(<TiptapEditor {...props} />))

package/src/index.macos.ts

@@ -1,19 +1,13 @@
-import type { TiptapEditorProps } from './types'
-
-export const supported = false
-
-/** AppKit host has no rich-text surface yet. */
-export function TiptapEditor(_props: TiptapEditorProps): null {
-	return null
-}
-
+export { TiptapEditor } from './Editor.macos'
+/** The AppKit/WKWebView backend is implemented. */
+export const supported = true
 export type * from './types'
 
-/** No editor, no bridge. */
-export function ensureJSONBridge(): Promise<boolean> {
-	return Promise.resolve(false)
+/** The local bundle includes its JSON model; wait for onReady before reading a document. */
+export async function ensureJSONBridge(): Promise<boolean> {
+	return true
 }
 
 export function jsonBridgeReady(): boolean {
-	return false
+	return true
 }

package/src/types.ts

@@ -1,3 +1,7 @@
+import type { Octane } from 'octane/jsx-runtime'
+import type { Extensions } from '@tiptap/core'
+import type { StarterKitOptions } from '@tiptap/starter-kit'
+
 /** Format vocabulary shared by the web (tiptap StarterKit) and native
  *  (Aztec) backends. On web, starter-kit covers everything except
  *  taskList/highlight/subscript/superscript/align* — those no-op there and
@@ -33,13 +37,34 @@ export type TiptapFormat =
  *  callers round-trip through tiptap's own schema on both platforms. */
 export type TiptapJSON = { type: string; content?: unknown[] } & Record<string, unknown>
 
+/** Engine options for the web target only. The `.web` entry mounts a real
+ *  tiptap `Editor`, so callers can extend its schema here. The Android
+ *  facade (Aztec leaf) and the bundled AppKit engine cannot host DOM-bound
+ *  ProseMirror/tiptap extension objects and ignore these options. Caller
+ *  plugins, node views, and browser menus are web behavior, not shared
+ *  contract. */
+export interface TiptapWebOptions {
+	/** Extra tiptap extensions appended after the built-in StarterKit — any
+	 *  `Extension`/`Node`/`Mark` from `@tiptap/*` or app code. An entry named
+	 *  `starterKit` replaces the built-in instead of registering it twice.
+	 *  The editor fixes its schema at construction; keep the list
+	 *  referentially stable across renders. */
+	extensions?: Extensions
+	/** `StarterKit.configure()` options for the built-in StarterKit, or
+	 *  `false` to omit it — `extensions` must then supply a complete schema
+	 *  (document, paragraph, and text nodes at minimum). */
+	starterKit?: StarterKitOptions | false
+}
+
 export interface TiptapEditorHandle {
+	/** AppKit: returns the latest WebKit snapshot; commands are asynchronous. */
 	getHTML(): string
 	/** Web: `commands.setContent` (undo-aware). Native: Aztec `fromHtml` —
 	 *  resets undo history. */
 	setHTML(html: string): void
 	/** Doc JSON, or null while the native schema modules are still loading /
 	 *  on a runtime that can't host them (`json` flag). Web is always ready. */
+	/** AppKit: latest live engine JSON snapshot; null before onReady. */
 	getJSON(): TiptapJSON | null
 	setJSON(doc: TiptapJSON): void
 	apply(format: TiptapFormat): void
@@ -53,6 +78,7 @@ export interface TiptapEditorHandle {
 	isFocused(): boolean
 	/** The platform surface — a tiptap `Editor` on web, `AztecText` on
 	 *  Android. */
+	/** AppKit: the XplatEditorHost transport, not the browser engine instance. */
 	native: any
 }
 
@@ -64,7 +90,9 @@ export interface TiptapEditorProps {
 	 *  setContent, preserving the diff loop the editor emitted is skipped). */
 	value?: string
 	/** Document JSON. Takes precedence over `value` when both arrive. On
-	 *  native it waits for the schema modules (see `onJSONReady`). */
+	 *  native it waits for the schema modules and host readiness (see
+	 *  `onJSONReady`); a doc that arrives early is applied once both are up
+	 *  rather than dropped. */
 	json?: TiptapJSON
 	placeholder?: string
 	editable?: boolean
@@ -73,15 +101,19 @@ export interface TiptapEditorProps {
 	/** Fires once when the native JSON bridge settles — `true` if the
 	 *  DOM-free tiptap modules loaded, `false` on runtimes that can't host
 	 *  them (JSON calls then no-op / return null). Never fires on web. */
+	/** AppKit: fires true with mounted engine readiness; no headless conversion bridge. */
 	onJSONReady?: (ready: boolean) => void
 	onChange?: (html: string) => void
 	onJSONChange?: (doc: TiptapJSON) => void
 	onSelectionChange?: (event: { start: number; end: number; active: TiptapFormat[] }) => void
 	onFocus?: () => void
 	onBlur?: () => void
-	bind?: (handle: TiptapEditorHandle) => void
+	ref?: Octane.Ref<TiptapEditorHandle>
 	android?: Record<string, any>
 	ios?: Record<string, any>
+	/** Web-target engine configuration — tiptap extensions and StarterKit
+	 *  options. See `TiptapWebOptions`; ignored on native and AppKit. */
+	web?: TiptapWebOptions
 	row?: number | string
 	col?: number | string
 	rowSpan?: number

package/types/index.macos.d.ts

@@ -0,0 +1,7 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { TiptapEditorProps } from '../src/types'
+export declare const TiptapEditor: UniversalComponent<TiptapEditorProps>
+export declare const supported: boolean
+export type * from '../src/types'
+export declare function ensureJSONBridge(): Promise<boolean>
+export declare function jsonBridgeReady(): boolean

package/types/types.d.ts

@@ -1,3 +1,6 @@
+import type { Octane } from 'octane/jsx-runtime';
+import type { Extensions } from '@tiptap/core';
+import type { StarterKitOptions } from '@tiptap/starter-kit';
 /** Format vocabulary shared by the web (tiptap StarterKit) and native
  *  (Aztec) backends. On web, starter-kit covers everything except
  *  taskList/highlight/subscript/superscript/align* — those no-op there and
@@ -9,13 +12,33 @@ export type TiptapJSON = {
     type: string;
     content?: unknown[];
 } & Record<string, unknown>;
+/** Engine options for the web target only. The `.web` entry mounts a real
+ *  tiptap `Editor`, so callers can extend its schema here. The Android
+ *  facade (Aztec leaf) and the bundled AppKit engine cannot host DOM-bound
+ *  ProseMirror/tiptap extension objects and ignore these options. Caller
+ *  plugins, node views, and browser menus are web behavior, not shared
+ *  contract. */
+export interface TiptapWebOptions {
+    /** Extra tiptap extensions appended after the built-in StarterKit — any
+     *  `Extension`/`Node`/`Mark` from `@tiptap/*` or app code. An entry named
+     *  `starterKit` replaces the built-in instead of registering it twice.
+     *  The editor fixes its schema at construction; keep the list
+     *  referentially stable across renders. */
+    extensions?: Extensions;
+    /** `StarterKit.configure()` options for the built-in StarterKit, or
+     *  `false` to omit it — `extensions` must then supply a complete schema
+     *  (document, paragraph, and text nodes at minimum). */
+    starterKit?: StarterKitOptions | false;
+}
 export interface TiptapEditorHandle {
+    /** AppKit: returns the latest WebKit snapshot; commands are asynchronous. */
     getHTML(): string;
     /** Web: `commands.setContent` (undo-aware). Native: Aztec `fromHtml` —
      *  resets undo history. */
     setHTML(html: string): void;
     /** Doc JSON, or null while the native schema modules are still loading /
      *  on a runtime that can't host them (`json` flag). Web is always ready. */
+    /** AppKit: latest live engine JSON snapshot; null before onReady. */
     getJSON(): TiptapJSON | null;
     setJSON(doc: TiptapJSON): void;
     apply(format: TiptapFormat): void;
@@ -29,6 +52,7 @@ export interface TiptapEditorHandle {
     isFocused(): boolean;
     /** The platform surface — a tiptap `Editor` on web, `AztecText` on
      *  Android. */
+    /** AppKit: the XplatEditorHost transport, not the browser engine instance. */
     native: any;
 }
 export interface TiptapEditorProps {
@@ -39,7 +63,9 @@ export interface TiptapEditorProps {
      *  setContent, preserving the diff loop the editor emitted is skipped). */
     value?: string;
     /** Document JSON. Takes precedence over `value` when both arrive. On
-     *  native it waits for the schema modules (see `onJSONReady`). */
+     *  native it waits for the schema modules and host readiness (see
+     *  `onJSONReady`); a doc that arrives early is applied once both are up
+     *  rather than dropped. */
     json?: TiptapJSON;
     placeholder?: string;
     editable?: boolean;
@@ -48,6 +74,7 @@ export interface TiptapEditorProps {
     /** Fires once when the native JSON bridge settles — `true` if the
      *  DOM-free tiptap modules loaded, `false` on runtimes that can't host
      *  them (JSON calls then no-op / return null). Never fires on web. */
+    /** AppKit: fires true with mounted engine readiness; no headless conversion bridge. */
     onJSONReady?: (ready: boolean) => void;
     onChange?: (html: string) => void;
     onJSONChange?: (doc: TiptapJSON) => void;
@@ -58,9 +85,12 @@ export interface TiptapEditorProps {
     }) => void;
     onFocus?: () => void;
     onBlur?: () => void;
-    bind?: (handle: TiptapEditorHandle) => void;
+    ref?: Octane.Ref<TiptapEditorHandle>;
     android?: Record<string, any>;
     ios?: Record<string, any>;
+    /** Web-target engine configuration — tiptap extensions and StarterKit
+     *  options. See `TiptapWebOptions`; ignored on native and AppKit. */
+    web?: TiptapWebOptions;
     row?: number | string;
     col?: number | string;
     rowSpan?: number;