@octane-xplat/tiptap 0.9.0 → 0.10.0

package/dist/native/index3.js

@@ -1,14 +1,16 @@
 import { ensureJSONBridge, htmlToJSON, jsonBridgeReady, jsonToHTML } from "./index2.js";
-import { defineUniversalComponent, hookSlots, universalComponent, universalPlan, universalProps, universalValue, useCallback, useEffect, useRef } from "@nativescript-community/octane";
+import { defineUniversalComponent, hookSlots, universalComponent, universalPlan, universalProps, universalValue, useCallback, useEffect, useImperativeHandle, useRef, useState } from "@nativescript-community/octane";
 import { RichTextEditor, supported } from "@octane-xplat/richtext";
 //#region src/TiptapEditor.tsrx
-var _hs$ = /* @__PURE__ */ hookSlots(6);
+var _hs$ = /* @__PURE__ */ hookSlots(8);
 var _h$0 = /* @__PURE__ */ Symbol(_hs$);
 var _h$1 = /* @__PURE__ */ Symbol(_hs$ + 1);
 var _h$2 = /* @__PURE__ */ Symbol(_hs$ + 2);
 var _h$3 = /* @__PURE__ */ Symbol(_hs$ + 3);
 var _h$4 = /* @__PURE__ */ Symbol(_hs$ + 4);
 var _h$5 = /* @__PURE__ */ Symbol(_hs$ + 5);
+var _h$6 = /* @__PURE__ */ Symbol(_hs$ + 6);
+var _h$7 = /* @__PURE__ */ Symbol(_hs$ + 7);
 var __octaneUniversalPlan0 = universalPlan("nativescript", {
 	"kind": "slot",
 	"slot": 0
@@ -16,11 +18,13 @@ var __octaneUniversalPlan0 = universalPlan("nativescript", {
 var supported$1 = supported;
 var TiptapEditor = defineUniversalComponent("nativescript", function TiptapEditor(props) {
 	const inner = useRef(null, _h$0);
-	const jsonReady = useRef(false, _h$1);
-	const lastJSON = useRef(void 0, _h$2);
+	const [exposedHandle, setHandle] = useState(null, _h$1);
+	useImperativeHandle(props.ref, () => exposedHandle, [exposedHandle], _h$2);
+	const jsonReady = useRef(false, _h$3);
+	const lastJSON = useRef(void 0, _h$4);
 	const bindHost = useCallback((h) => {
 		inner.current = h;
-		props.bind?.({
+		setHandle((previous) => previous?.native === h?.native ? previous : h ? {
 			getHTML: () => h.getHTML(),
 			setHTML: (html) => h.setHTML(html),
 			getJSON: () => jsonBridgeReady() ? htmlToJSON(h.getHTML()) : null,
@@ -41,14 +45,14 @@ var TiptapEditor = defineUniversalComponent("nativescript", function TiptapEdito
 			blur: () => h.blur(),
 			isFocused: () => h.isFocused(),
 			native: h.native
-		});
-	}, [], _h$3);
+		} : null);
+	}, [], _h$5);
 	useEffect(() => {
 		ensureJSONBridge().then((ok) => {
 			jsonReady.current = ok;
 			props.onJSONReady?.(ok);
 		});
-	}, [], _h$4);
+	}, [], _h$6);
 	useEffect(() => {
 		if (!props.json || !jsonBridgeReady() || !inner.current) return;
 		const stamp = JSON.stringify(props.json);
@@ -58,7 +62,7 @@ var TiptapEditor = defineUniversalComponent("nativescript", function TiptapEdito
 			lastJSON.current = stamp;
 			inner.current.setHTML(html);
 		}
-	}, [props.json], _h$5);
+	}, [props.json], _h$7);
 	const emitJSON = () => {
 		if (!inner.current || !jsonBridgeReady()) return;
 		const doc = htmlToJSON(inner.current.getHTML());
@@ -133,7 +137,7 @@ var TiptapEditor = defineUniversalComponent("nativescript", function TiptapEdito
 		],
 		[
 			"set",
-			"bind",
+			"ref",
 			bindHost
 		],
 		[

package/dist/native/octane-client-build.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "buildId": "02534c50-4097-48da-93e0-5e219c2d5b5c",
+  "buildId": "3880e698-2b9a-436f-af5a-a7ec180643bf",
   "mode": "production",
   "capabilities": {
     "independentHydration": false

package/dist/web/index2.js

@@ -1,11 +1,11 @@
-import { __s, bag3, clone, componentSlot, hookSlots, setStyle, template, useEffect, useRef, withSlot } from "octane";
+import { __s, bag3, clone, componentSlot, hookSlots, setStyle, template, useEffect, useImperativeHandle, useRef, withSlot } from "octane";
 import { updateFreshClassName } from "octane/internal/client";
 import { EditorContent, useEditor } from "@octanejs/tiptap";
 import StarterKit from "@tiptap/starter-kit";
 //#region src/TiptapEditor.web.tsrx
 var _t$0 = /* @__PURE__ */ template("<div></div>");
-var _hs$ = /* @__PURE__ */ hookSlots(8);
-var _h$3 = /* @__PURE__ */ Symbol(_hs$ + 3);
+var _hs$ = /* @__PURE__ */ hookSlots(10);
+var _h$5 = /* @__PURE__ */ Symbol(_hs$ + 5);
 var supported = true;
 var COMMAND = {
 	bold: (c) => c.toggleBold(),
@@ -26,18 +26,6 @@ var COMMAND = {
 	heading5: (c) => c.toggleHeading({ level: 5 }),
 	heading6: (c) => c.toggleHeading({ level: 6 })
 };
-var IS_ACTIVE = {
-	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")
-};
 var ACTIVE_OF = [
 	["bold", "bold"],
 	["italic", "italic"],
@@ -89,10 +77,12 @@ function activeFormats(editor) {
 var TiptapEditor = /* @__PURE__ */ __s(function TiptapEditor(props, __s, __extra) {
 	const lastEmitted = useRef(void 0, _hs$ + 0);
 	const lastJSON = useRef(void 0, _hs$ + 1);
-	const bound = useRef(void 0, _hs$ + 2);
-	const editor = withSlot(_h$3, useEditor, {
+	const lastHTMLInput = useRef(JSON.stringify([props.json !== void 0, props.value]), _hs$ + 2);
+	const lastJSONInput = useRef(JSON.stringify(props.json), _hs$ + 3);
+	const bound = useRef(void 0, _hs$ + 4);
+	const editor = withSlot(_h$5, useEditor, {
 		extensions: [StarterKit],
-		content: props.value ?? props.json ?? "",
+		content: props.json ?? props.value ?? "",
 		editable: props.editable !== false,
 		autofocus: props.autofocus ?? false,
 		onCreate: () => props.onReady?.(),
@@ -113,21 +103,32 @@ var TiptapEditor = /* @__PURE__ */ __s(function TiptapEditor(props, __s, __extra
 		})
 	});
 	useEffect(() => {
-		if (!editor || props.value === void 0) return;
+		if (!editor) return;
+		const stamp = JSON.stringify([props.json !== void 0, props.value]);
+		if (stamp === lastHTMLInput.current) return;
+		lastHTMLInput.current = stamp;
+		if (props.value === void 0 || props.json !== void 0) return;
 		if (props.value === lastEmitted.current) return;
 		editor.commands.setContent(props.value);
-	}, [editor, props.value], _hs$ + 4);
+	}, [
+		editor,
+		props.value,
+		props.json
+	], _hs$ + 6);
 	useEffect(() => {
-		if (!editor || props.json === void 0) 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 === void 0 || stamp === lastJSON.current) return;
 		editor.commands.setContent(props.json);
-	}, [editor, props.json], _hs$ + 5);
+	}, [editor, props.json], _hs$ + 7);
 	useEffect(() => {
 		if (!editor) return;
 		editor.setEditable(props.editable !== false);
-	}, [editor, props.editable], _hs$ + 6);
-	useEffect(() => {
-		if (!editor || bound.current?.native === editor) return;
+	}, [editor, props.editable], _hs$ + 8);
+	useImperativeHandle(props.ref, () => {
+		if (!editor) return null;
 		const e = editor;
 		bound.current = {
 			getHTML: () => e.getHTML(),
@@ -150,7 +151,7 @@ var TiptapEditor = /* @__PURE__ */ __s(function TiptapEditor(props, __s, __extra
 				else e.chain().focus().extendMarkRange("link").setLink({ href: url }).run();
 			},
 			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(),
@@ -158,8 +159,8 @@ var TiptapEditor = /* @__PURE__ */ __s(function TiptapEditor(props, __s, __extra
 			isFocused: () => e.isFocused,
 			native: e
 		};
-		props.bind?.(bound.current);
-	}, [editor], _hs$ + 7);
+		return bound.current;
+	}, [editor], _hs$ + 9);
 	if (__s.block.pending && !__s.block.crossRenderUpdate) return;
 	let _b = __s.slots[0];
 	if (_b === void 0) {
@@ -176,7 +177,7 @@ var TiptapEditor = /* @__PURE__ */ __s(function TiptapEditor(props, __s, __extra
 			_b.c = _v;
 		}
 	}
-	componentSlot(__s, 1, _b.b, EditorContent, { "editor": editor }, void 0, void 0, 2, void 0, void 0, "c:077f1c5f");
+	componentSlot(__s, 1, _b.b, EditorContent, { "editor": editor }, void 0, void 0, 2, void 0, void 0, "c:e9be3bbb");
 });
 //#endregion
 export { TiptapEditor, supported };

package/dist/web/octane-client-build.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "buildId": "877d10c5-3430-4ba4-9762-2bd655451b3d",
+  "buildId": "e01adeb4-b2cd-4b21-9fdd-57831df35c5b",
   "mode": "production",
   "capabilities": {
     "independentHydration": false

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@octane-xplat/tiptap",
-  "version": "0.9.0",
-  "description": "Unified rich-text editor facade for Octane xplat — @octanejs/tiptap on web, @octane-xplat/richtext (Aztec) + tiptap doc model on native",
+  "version": "0.10.0",
+  "description": "Unified rich-text editor facade for Octane xplat — live tiptap on web/AppKit, Aztec + tiptap document model on Android",
   "keywords": [
     "cross-platform",
     "editor",
@@ -29,7 +29,7 @@
   "exports": {
     ".": {
       "macos": {
-        "types": "./types/index.d.ts",
+        "types": "./types/index.macos.d.ts",
         "default": "./src/index.macos.ts"
       },
       "web": {
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@octane-xplat/richtext": "0.9.0",
+    "@octane-xplat/richtext": "0.10.0",
     "@octanejs/tiptap": "0.0.51",
     "@tiptap/core": "3.28.0",
     "@tiptap/pm": "3.28.0",
@@ -59,6 +59,7 @@
   "devDependencies": {
     "@nativescript-community/octane": "0.2.4",
     "@nativescript/core": "9.1.2",
+    "@octane-xplat/macos-renderer": "0.10.0",
     "@octanejs/vite-plugin": "0.1.61",
     "octane": "0.6.3",
     "typescript": "5.9.3",
@@ -87,6 +88,6 @@
     }
   },
   "scripts": {
-    "build": "vite build && vite build --mode native && tsc -p tsconfig.types.json && node ../../scripts/check-native-dist.mjs"
+    "build": "vite build && vite build --mode native && tsc -p tsconfig.types.json && node ../../scripts/check-native-dist.mjs && node ../richtext/build-browser.mjs"
   }
 }

package/src/Editor.macos.tsx

@@ -0,0 +1,9 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import type { TiptapEditorProps } from './types'
+import browser from '../dist/macos/browser.js'
+import { NativeEditor } from '@octane-xplat/richtext/macos-host'
+
+/** AppKit mounts the local editor engine in WKWebView. */
+export function TiptapEditor(props: TiptapEditorProps) {
+	return <NativeEditor {...props} browser={browser} />
+}

package/src/TiptapEditor.tsrx

@@ -1,5 +1,5 @@
 /** @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'
@@ -12,13 +12,15 @@ export const supported = leafSupported
  *  renderToHTMLString) handles JSON interchange on top of it. */
 export function TiptapEditor(props: TiptapEditorProps) @{
 	const inner = useRef<RichTextEditorHandle | null>(null)
+	const [exposedHandle, setHandle] = useState<TiptapEditorHandle | null>(null)
+	useImperativeHandle<TiptapEditorHandle | null>(props.ref, () => exposedHandle, [exposedHandle])
 	const jsonReady = useRef(false)
 	const lastJSON = useRef<string | undefined>(undefined)
 
-	const bindHost = useCallback((h: RichTextEditorHandle) => {
+	const bindHost = useCallback((h: RichTextEditorHandle | null) => {
 		inner.current = h
 
-		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),
@@ -39,7 +41,7 @@ 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
@@ -89,7 +91,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.tsrx

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'octane'
+import { useImperativeHandle, useEffect, useRef } from 'octane'
 import { EditorContent, useEditor } from '@octanejs/tiptap'
 import StarterKit from '@tiptap/starter-kit'
 import type { TiptapEditorHandle, TiptapEditorProps, TiptapFormat } from './types'
@@ -27,19 +27,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'],
@@ -74,11 +61,13 @@ function activeFormats(editor: any): TiptapFormat[] {
 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)
 
 	const editor = useEditor({
 		extensions: [StarterKit],
-		content: (props.value ?? props.json ?? '') as any,
+		content: (props.json ?? props.value ?? '') as any,
 		editable: props.editable !== false,
 		autofocus: props.autofocus ?? false,
 		onCreate: () => props.onReady?.(),
@@ -103,14 +92,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 +117,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 +137,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 +146,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,5 @@
+import type { Octane } from 'octane/jsx-runtime'
+
 /** 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
@@ -34,12 +36,14 @@ export type TiptapFormat =
 export type TiptapJSON = { type: string; content?: unknown[] } & Record<string, unknown>
 
 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 +57,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
 }
 
@@ -73,13 +78,14 @@ 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>
 	row?: number | string

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,4 @@
+import type { Octane } from 'octane/jsx-runtime';
 /** 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
@@ -10,12 +11,14 @@ export type TiptapJSON = {
     content?: unknown[];
 } & Record<string, unknown>;
 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 +32,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 {
@@ -48,6 +52,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,7 +63,7 @@ export interface TiptapEditorProps {
     }) => void;
     onFocus?: () => void;
     onBlur?: () => void;
-    bind?: (handle: TiptapEditorHandle) => void;
+    ref?: Octane.Ref<TiptapEditorHandle>;
     android?: Record<string, any>;
     ios?: Record<string, any>;
     row?: number | string;