@octane-xplat/tiptap 0.0.1 → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+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

@@ -1,3 +1,26 @@
-# @octane-xplat/tiptap
+# `@octane-xplat/tiptap`
 
-Version 0.0.1 is a reservation stub so the automated release can publish this package name. It has no supported API. Use a later release for the implementation.
+The unified rich-text facade: one `TiptapEditor` component across web and
+native. Web renders a real tiptap `Editor` through `@octanejs/tiptap`'s
+`EditorContent`; native renders the `@octane-xplat/richtext` leaf (WordPress
+Aztec on Android, iOS stub) and layers tiptap document JSON on top through
+the DOM-free ProseMirror slices (`@tiptap/pm`, `@tiptap/static-renderer`)
+with a `zeed-dom` parse shim. No DOM-bound tiptap code (`EditorView`) ever
+enters a native bundle — divergence lives at the file-suffix boundary.
+
+```ts
+import { TiptapEditor, supported } from '@octane-xplat/tiptap'
+```
+
+`value`/`onChange` exchange document HTML. `getJSON`/`setJSON` exchange
+tiptap document JSON: synchronous on web, bridged on native after
+`onJSONReady(true)` — the lazy bridge reports `false` (and `getJSON()`
+returns `null`) on runtimes that cannot host the schema modules. On native,
+HTML is the canonical interchange format; JSON output is a best-effort
+mapping of Aztec's flat span list onto ProseMirror's tree.
+
+The tiptap family pins to `3.28.0` to match `@octanejs/tiptap@0.0.51` —
+extension `^` ranges float ahead of core and break (`getPreviousBlockSibling`),
+so consumers should keep the workspace override. See
+[`docs/rich-text.md`](../../docs/rich-text.md) for the shared contract,
+format vocabulary, and known limits.

package/dist/native/index.js

@@ -0,0 +1,3 @@
+import { ensureJSONBridge, jsonBridgeReady } from "./index2.js";
+import { TiptapEditor, supported } from "./index3.js";
+export { TiptapEditor, ensureJSONBridge, jsonBridgeReady, supported };

package/dist/native/index2.js

@@ -0,0 +1,82 @@
+//#region src/json-bridge.ts
+var bridge;
+/** zeed-dom's classList is a plain {contains,add,remove} object; tiptap's
+*  codeBlock parseHTML spreads it. Wrap the VElement getter so it hands back
+*  an iterable array that keeps the mutation methods. */
+function patchClassList(VElement) {
+	const proto = VElement?.prototype;
+	if (!proto) throw new Error("VElement.prototype unavailable");
+	const desc = Object.getOwnPropertyDescriptor(proto, "classList");
+	if (!desc?.get) throw new Error("classList is not a prototype getter");
+	if (desc.get.__xplatPatched) return;
+	const patched = function() {
+		const cl = desc.get.call(this);
+		if (cl && typeof cl[Symbol.iterator] !== "function") {
+			const tokens = String(this.getAttribute("class") ?? "").split(/\s+/).filter(Boolean);
+			return Object.assign(tokens, cl);
+		}
+		return cl;
+	};
+	patched.__xplatPatched = true;
+	Object.defineProperty(proto, "classList", {
+		configurable: true,
+		get: patched,
+		set: desc.set
+	});
+}
+/** Install the minimal parse globals generateJSON's elementFromString
+*  reads. Only installs when the host lacks them, so a real DOM (web
+*  target) is never clobbered. */
+function installDomShim(zeed) {
+	const g = globalThis;
+	if (g.window?.DOMParser) return;
+	class ZeedDOMParser {
+		parseFromString(html) {
+			const doc = zeed.createHTMLDocument();
+			doc.body.innerHTML = html;
+			return doc;
+		}
+	}
+	g.window = { DOMParser: ZeedDOMParser };
+	g.document = zeed.createHTMLDocument();
+}
+async function ensureJSONBridge() {
+	if (bridge !== void 0) return bridge !== null;
+	try {
+		const [core, sk, sr, zeed] = await Promise.all([
+			import("@tiptap/core"),
+			import("@tiptap/starter-kit"),
+			import("@tiptap/static-renderer"),
+			import("zeed-dom")
+		]);
+		patchClassList(zeed.VElement);
+		installDomShim(zeed);
+		const StarterKit = sk.default ?? sk.StarterKit;
+		bridge = {
+			generateJSON: core.generateJSON,
+			renderToHTMLString: sr.renderToHTMLString,
+			extensions: [StarterKit]
+		};
+		return true;
+	} catch {
+		bridge = null;
+		return false;
+	}
+}
+/** HTML → doc JSON through tiptap's own parseHTML rules. Null when the
+*  bridge hasn't loaded (call ensureJSONBridge first / check `ready`). */
+function htmlToJSON(html) {
+	return bridge?.generateJSON(html, bridge.extensions) ?? null;
+}
+/** Doc JSON → HTML via tiptap's own renderHTML rules (no DOM). */
+function jsonToHTML(doc) {
+	return bridge?.renderToHTMLString({
+		extensions: bridge.extensions,
+		content: doc
+	}) ?? null;
+}
+function jsonBridgeReady() {
+	return bridge != null;
+}
+//#endregion
+export { ensureJSONBridge, htmlToJSON, jsonBridgeReady, jsonToHTML };

package/dist/native/index3.js

@@ -0,0 +1,207 @@
+import { ensureJSONBridge, htmlToJSON, jsonBridgeReady, jsonToHTML } from "./index2.js";
+import { defineUniversalComponent, hookSlots, universalComponent, universalPlan, universalProps, universalValue, useCallback, useEffect, useRef } from "@nativescript-community/octane";
+import { RichTextEditor, supported } from "@octane-xplat/richtext";
+//#region src/TiptapEditor.tsrx
+var _hs$ = /* @__PURE__ */ hookSlots(6);
+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 __octaneUniversalPlan0 = universalPlan("nativescript", {
+	"kind": "slot",
+	"slot": 0
+});
+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 bindHost = useCallback((h) => {
+		inner.current = h;
+		props.bind?.({
+			getHTML: () => h.getHTML(),
+			setHTML: (html) => 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);
+				}
+			},
+			apply: (format) => h.apply(format),
+			linkTo: (url, anchor) => h.linkTo(url, anchor),
+			removeLink: () => h.removeLink(),
+			isActive: (format) => h.isActive(format),
+			undo: () => h.undo(),
+			redo: () => h.redo(),
+			focus: () => h.focus(),
+			blur: () => h.blur(),
+			isFocused: () => h.isFocused(),
+			native: h.native
+		});
+	}, [], _h$3);
+	useEffect(() => {
+		ensureJSONBridge().then((ok) => {
+			jsonReady.current = ok;
+			props.onJSONReady?.(ok);
+		});
+	}, [], _h$4);
+	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);
+		}
+	}, [props.json], _h$5);
+	const emitJSON = () => {
+		if (!inner.current || !jsonBridgeReady()) return;
+		const doc = htmlToJSON(inner.current.getHTML());
+		if (doc) {
+			lastJSON.current = JSON.stringify(doc);
+			props.onJSONChange?.(doc);
+		}
+	};
+	return universalValue(__octaneUniversalPlan0, [universalComponent("nativescript", RichTextEditor, universalProps([
+		[
+			"set",
+			"id",
+			props.id
+		],
+		[
+			"set",
+			"className",
+			props.className
+		],
+		[
+			"set",
+			"style",
+			props.style
+		],
+		[
+			"set",
+			"value",
+			props.value
+		],
+		[
+			"set",
+			"placeholder",
+			props.placeholder
+		],
+		[
+			"set",
+			"editable",
+			props.editable
+		],
+		[
+			"set",
+			"autofocus",
+			props.autofocus
+		],
+		[
+			"set",
+			"onReady",
+			props.onReady
+		],
+		[
+			"set",
+			"onChange",
+			(html) => {
+				props.onChange?.(html);
+				emitJSON();
+			}
+		],
+		[
+			"set",
+			"onSelectionChange",
+			props.onSelectionChange
+		],
+		[
+			"set",
+			"onFocus",
+			props.onFocus
+		],
+		[
+			"set",
+			"onBlur",
+			props.onBlur
+		],
+		[
+			"set",
+			"bind",
+			bindHost
+		],
+		[
+			"set",
+			"android",
+			props.android
+		],
+		[
+			"set",
+			"ios",
+			props.ios
+		],
+		[
+			"set",
+			"row",
+			props.row
+		],
+		[
+			"set",
+			"col",
+			props.col
+		],
+		[
+			"set",
+			"rowSpan",
+			props.rowSpan
+		],
+		[
+			"set",
+			"colSpan",
+			props.colSpan
+		],
+		[
+			"set",
+			"dock",
+			props.dock
+		],
+		[
+			"set",
+			"left",
+			props.left
+		],
+		[
+			"set",
+			"top",
+			props.top
+		],
+		[
+			"set",
+			"flexGrow",
+			props.flexGrow
+		],
+		[
+			"set",
+			"flexShrink",
+			props.flexShrink
+		],
+		[
+			"set",
+			"alignSelf",
+			props.alignSelf
+		],
+		[
+			"set",
+			"order",
+			props.order
+		]
+	]))]);
+}, { "module": "@nativescript-community/octane" });
+//#endregion
+export { TiptapEditor, supported$1 as supported };

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

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "buildId": "02534c50-4097-48da-93e0-5e219c2d5b5c",
+  "mode": "production",
+  "capabilities": {
+    "independentHydration": false
+  }
+}

package/dist/web/index.js

@@ -0,0 +1,12 @@
+import { TiptapEditor, supported } from "./index2.js";
+//#region src/index.web.ts
+/** Web needs no lazy bridge — tiptap is in the bundle already. Kept for
+*  call-site parity with the native entry. */
+function ensureJSONBridge() {
+	return Promise.resolve(true);
+}
+function jsonBridgeReady() {
+	return true;
+}
+//#endregion
+export { TiptapEditor, ensureJSONBridge, jsonBridgeReady, supported };

package/dist/web/index2.js

@@ -0,0 +1,182 @@
+import { __s, bag3, clone, componentSlot, hookSlots, setStyle, template, useEffect, 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 supported = true;
+var COMMAND = {
+	bold: (c) => c.toggleBold(),
+	italic: (c) => c.toggleItalic(),
+	underline: (c) => c.toggleUnderline(),
+	strikethrough: (c) => c.toggleStrike(),
+	code: (c) => c.toggleCode(),
+	blockquote: (c) => c.toggleBlockquote(),
+	bulletList: (c) => c.toggleBulletList(),
+	orderedList: (c) => c.toggleOrderedList(),
+	codeBlock: (c) => c.toggleCodeBlock(),
+	horizontalRule: (c) => c.setHorizontalRule(),
+	paragraph: (c) => c.setParagraph(),
+	heading1: (c) => c.toggleHeading({ level: 1 }),
+	heading2: (c) => c.toggleHeading({ level: 2 }),
+	heading3: (c) => c.toggleHeading({ level: 3 }),
+	heading4: (c) => c.toggleHeading({ level: 4 }),
+	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"],
+	["underline", "underline"],
+	["strikethrough", "strike"],
+	["code", "code"],
+	["blockquote", "blockquote"],
+	["bulletList", "bulletList"],
+	["orderedList", "orderedList"],
+	["codeBlock", "codeBlock"],
+	["link", "link"],
+	[
+		"heading1",
+		"heading",
+		{ level: 1 }
+	],
+	[
+		"heading2",
+		"heading",
+		{ level: 2 }
+	],
+	[
+		"heading3",
+		"heading",
+		{ level: 3 }
+	],
+	[
+		"heading4",
+		"heading",
+		{ level: 4 }
+	],
+	[
+		"heading5",
+		"heading",
+		{ level: 5 }
+	],
+	[
+		"heading6",
+		"heading",
+		{ level: 6 }
+	],
+	["paragraph", "paragraph"]
+];
+function activeFormats(editor) {
+	const out = [];
+	for (const [name, kind, attrs] of ACTIVE_OF) if (editor.isActive(kind, attrs)) out.push(name);
+	return out;
+}
+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, {
+		extensions: [StarterKit],
+		content: props.value ?? props.json ?? "",
+		editable: props.editable !== false,
+		autofocus: props.autofocus ?? false,
+		onCreate: () => props.onReady?.(),
+		onUpdate: ({ editor: e }) => {
+			const html = e.getHTML();
+			lastEmitted.current = html;
+			props.onChange?.(html);
+			const doc = e.getJSON();
+			lastJSON.current = JSON.stringify(doc);
+			props.onJSONChange?.(doc);
+		},
+		onFocus: () => props.onFocus?.(),
+		onBlur: () => props.onBlur?.(),
+		onSelectionUpdate: ({ editor: e }) => props.onSelectionChange?.({
+			start: e.state.selection.from,
+			end: e.state.selection.to,
+			active: activeFormats(e)
+		})
+	});
+	useEffect(() => {
+		if (!editor || props.value === void 0) return;
+		if (props.value === lastEmitted.current) return;
+		editor.commands.setContent(props.value);
+	}, [editor, props.value], _hs$ + 4);
+	useEffect(() => {
+		if (!editor || props.json === void 0) return;
+		if (JSON.stringify(props.json) === lastJSON.current) return;
+		editor.commands.setContent(props.json);
+	}, [editor, props.json], _hs$ + 5);
+	useEffect(() => {
+		if (!editor) return;
+		editor.setEditable(props.editable !== false);
+	}, [editor, props.editable], _hs$ + 6);
+	useEffect(() => {
+		if (!editor || bound.current?.native === editor) return;
+		const e = editor;
+		bound.current = {
+			getHTML: () => e.getHTML(),
+			setHTML: (html) => e.commands.setContent(html),
+			getJSON: () => e.getJSON(),
+			setJSON: (doc) => e.commands.setContent(doc),
+			apply: (format) => {
+				const run = COMMAND[format];
+				if (run) run(e.chain().focus()).run();
+			},
+			linkTo: (url, anchor) => {
+				if (anchor != null && anchor !== "") e.chain().focus().insertContent({
+					type: "text",
+					text: anchor,
+					marks: [{
+						type: "link",
+						attrs: { href: url }
+					}]
+				}).run();
+				else e.chain().focus().extendMarkRange("link").setLink({ href: url }).run();
+			},
+			removeLink: () => e.chain().focus().unsetLink().run(),
+			isActive: (format) => IS_ACTIVE[format]?.(e) ?? false,
+			undo: () => e.commands.undo(),
+			redo: () => e.commands.redo(),
+			focus: () => e.commands.focus(),
+			blur: () => e.commands.blur(),
+			isFocused: () => e.isFocused,
+			native: e
+		};
+		props.bind?.(bound.current);
+	}, [editor], _hs$ + 7);
+	if (__s.block.pending && !__s.block.crossRenderUpdate) return;
+	let _b = __s.slots[0];
+	if (_b === void 0) {
+		let _m1;
+		const _root = clone(_t$0);
+		_m1 = _root;
+		_b = bag3(__s, _root, void 0, _m1, void 0);
+	}
+	_b.a = updateFreshClassName(["vx-richtext", props.className], _b.a, _b.b);
+	{
+		const _v = props.style;
+		if (_b.c !== _v) {
+			setStyle(_b.b, _v, _b.c);
+			_b.c = _v;
+		}
+	}
+	componentSlot(__s, 1, _b.b, EditorContent, { "editor": editor }, void 0, void 0, 2, void 0, void 0, "c:077f1c5f");
+});
+//#endregion
+export { TiptapEditor, supported };

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

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "buildId": "877d10c5-3430-4ba4-9762-2bd655451b3d",
+  "mode": "production",
+  "capabilities": {
+    "independentHydration": false
+  }
+}

package/package.json

@@ -1,19 +1,92 @@
 {
   "name": "@octane-xplat/tiptap",
-  "version": "0.0.1",
+  "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",
+  "keywords": [
+    "cross-platform",
+    "editor",
+    "octane",
+    "prosemirror",
+    "rich-text",
+    "richtext",
+    "tiptap",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/tiptap",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/octane-xplat/octane-xplat.git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
     "directory": "packages/tiptap"
   },
-  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/tiptap",
-  "main": "./index.js",
-  "types": "./index.d.ts",
   "files": [
-    "README.md",
-    "index.js",
-    "index.d.ts"
-  ]
-}
+    "dist",
+    "types",
+    "src",
+    "platforms"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": {
+        "types": "./types/index.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "web": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/web/index.js"
+      },
+      "native": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/native/index.js"
+      },
+      "types": "./types/index.d.ts",
+      "default": "./dist/native/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@octane-xplat/richtext": "0.9.0",
+    "@octanejs/tiptap": "0.0.51",
+    "@tiptap/core": "3.28.0",
+    "@tiptap/pm": "3.28.0",
+    "@tiptap/starter-kit": "3.28.0",
+    "@tiptap/static-renderer": "3.28.0",
+    "zeed-dom": "^0.15.1"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.4",
+    "@nativescript/core": "9.1.2",
+    "@octanejs/vite-plugin": "0.1.61",
+    "octane": "0.6.3",
+    "typescript": "5.9.3",
+    "vite": "8.3.0"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "octane": ">=0.6.3 <1"
+  },
+  "peerDependenciesMeta": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    },
+    "octane": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "android": "9.1.0",
+      "ios": "9.1.0"
+    }
+  },
+  "scripts": {
+    "build": "vite build && vite build --mode native && tsc -p tsconfig.types.json && node ../../scripts/check-native-dist.mjs"
+  }
+}

package/src/TiptapEditor.tsrx

@@ -0,0 +1,107 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { 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 { ensureJSONBridge, htmlToJSON, jsonBridgeReady, jsonToHTML } from './json-bridge'
+
+export const supported = leafSupported
+
+/** Unified editor facade, native half. Rendering/editing run through the
+ *  Aztec leaf; the tiptap document model (schema, generateJSON,
+ *  renderToHTMLString) handles JSON interchange on top of it. */
+export function TiptapEditor(props: TiptapEditorProps) @{
+	const inner = useRef<RichTextEditorHandle | null>(null)
+	const jsonReady = useRef(false)
+	const lastJSON = useRef<string | undefined>(undefined)
+
+	const bindHost = useCallback((h: RichTextEditorHandle) => {
+		inner.current = h
+
+		props.bind?.({
+			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)
+				}
+			},
+			apply: (format) => h.apply(format),
+			linkTo: (url, anchor) => h.linkTo(url, anchor),
+			removeLink: () => h.removeLink(),
+			isActive: (format) => h.isActive(format),
+			undo: () => h.undo(),
+			redo: () => h.redo(),
+			focus: () => h.focus(),
+			blur: () => h.blur(),
+			isFocused: () => h.isFocused(),
+			native: h.native,
+		} satisfies TiptapEditorHandle)
+	}, [])
+
+	// The bridge loads once per process — dynamic imports of the DOM-free
+	// tiptap slices, plus the zeed-dom parse shim.
+	useEffect(() => {
+		ensureJSONBridge().then((ok) => {
+			jsonReady.current = ok
+			props.onJSONReady?.(ok)
+		})
+	}, [])
+
+	// `json` prop → editor content, when the bridge is up and the doc wasn't
+	// emitted by the editor itself.
+	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)
+		}
+	}, [props.json])
+
+	const emitJSON = () => {
+		if (!inner.current || !jsonBridgeReady()) return
+		const doc = htmlToJSON(inner.current.getHTML())
+		if (doc) {
+			lastJSON.current = JSON.stringify(doc)
+			props.onJSONChange?.(doc)
+		}
+	}
+
+	<RichTextEditor
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		value={props.value}
+		placeholder={props.placeholder}
+		editable={props.editable}
+		autofocus={props.autofocus}
+		onReady={props.onReady}
+		onChange={(html) => {
+			props.onChange?.(html)
+			emitJSON()
+		}}
+		onSelectionChange={props.onSelectionChange}
+		onFocus={props.onFocus}
+		onBlur={props.onBlur}
+		bind={bindHost}
+		android={props.android}
+		ios={props.ios}
+		row={props.row}
+		col={props.col}
+		rowSpan={props.rowSpan}
+		colSpan={props.colSpan}
+		dock={props.dock}
+		left={props.left}
+		top={props.top}
+		flexGrow={props.flexGrow}
+		flexShrink={props.flexShrink}
+		alignSelf={props.alignSelf}
+		order={props.order}
+	/>;
+}

package/src/TiptapEditor.web.tsrx

@@ -0,0 +1,159 @@
+import { useEffect, useRef } from 'octane'
+import { EditorContent, useEditor } from '@octanejs/tiptap'
+import StarterKit from '@tiptap/starter-kit'
+import type { TiptapEditorHandle, TiptapEditorProps, TiptapFormat } from './types'
+
+export const supported = true
+
+type WebFormat = Exclude<TiptapFormat, 'link' | 'taskList' | 'highlight' | 'subscript' | 'superscript' | 'alignLeft' | 'alignCenter' | 'alignRight'>
+
+const COMMAND: Record<WebFormat, (chain: any) => any> = {
+	bold: (c) => c.toggleBold(),
+	italic: (c) => c.toggleItalic(),
+	underline: (c) => c.toggleUnderline(),
+	strikethrough: (c) => c.toggleStrike(),
+	code: (c) => c.toggleCode(),
+	blockquote: (c) => c.toggleBlockquote(),
+	bulletList: (c) => c.toggleBulletList(),
+	orderedList: (c) => c.toggleOrderedList(),
+	codeBlock: (c) => c.toggleCodeBlock(),
+	horizontalRule: (c) => c.setHorizontalRule(),
+	paragraph: (c) => c.setParagraph(),
+	heading1: (c) => c.toggleHeading({ level: 1 }),
+	heading2: (c) => c.toggleHeading({ level: 2 }),
+	heading3: (c) => c.toggleHeading({ level: 3 }),
+	heading4: (c) => c.toggleHeading({ level: 4 }),
+	heading5: (c) => c.toggleHeading({ level: 5 }),
+	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'],
+	['underline', 'underline'],
+	['strikethrough', 'strike'],
+	['code', 'code'],
+	['blockquote', 'blockquote'],
+	['bulletList', 'bulletList'],
+	['orderedList', 'orderedList'],
+	['codeBlock', 'codeBlock'],
+	['link', 'link'],
+	['heading1', 'heading', { level: 1 }],
+	['heading2', 'heading', { level: 2 }],
+	['heading3', 'heading', { level: 3 }],
+	['heading4', 'heading', { level: 4 }],
+	['heading5', 'heading', { level: 5 }],
+	['heading6', 'heading', { level: 6 }],
+	['paragraph', 'paragraph'],
+]
+
+function activeFormats(editor: any): TiptapFormat[] {
+	const out: TiptapFormat[] = []
+	for (const [name, kind, attrs] of ACTIVE_OF) {
+		if (editor.isActive(kind, attrs)) out.push(name)
+	}
+
+	return out
+}
+
+/** 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 bound = useRef<TiptapEditorHandle | undefined>(undefined)
+
+	const editor = useEditor({
+		extensions: [StarterKit],
+		content: (props.value ?? props.json ?? '') as any,
+		editable: props.editable !== false,
+		autofocus: props.autofocus ?? false,
+		onCreate: () => props.onReady?.(),
+		onUpdate: ({ editor: e }: any) => {
+			const html = e.getHTML()
+			lastEmitted.current = html
+			props.onChange?.(html)
+			const doc = e.getJSON()
+			lastJSON.current = JSON.stringify(doc)
+			props.onJSONChange?.(doc)
+		},
+		onFocus: () => props.onFocus?.(),
+		onBlur: () => props.onBlur?.(),
+		onSelectionUpdate: ({ editor: e }: any) =>
+			props.onSelectionChange?.({
+				start: e.state.selection.from,
+				end: e.state.selection.to,
+				active: activeFormats(e),
+			}),
+	})
+
+	// External `value` changes push setContent; editor-emitted HTML is skipped
+	// (the transaction already owns the doc).
+	useEffect(() => {
+		if (!editor || props.value === undefined) return
+		if (props.value === lastEmitted.current) return
+		editor.commands.setContent(props.value)
+	}, [editor, props.value])
+
+	useEffect(() => {
+		if (!editor || props.json === undefined) return
+		if (JSON.stringify(props.json) === lastJSON.current) return
+		editor.commands.setContent(props.json as any)
+	}, [editor, props.json])
+
+	useEffect(() => {
+		if (!editor) return
+		editor.setEditable(props.editable !== false)
+	}, [editor, props.editable])
+
+	// The handle rebinds whenever the editor instance appears — stable
+	// afterward (useEditor keeps the instance identity).
+	useEffect(() => {
+		if (!editor || bound.current?.native === editor) return
+		const e: any = editor
+		bound.current = {
+			getHTML: () => e.getHTML(),
+			setHTML: (html: string) => e.commands.setContent(html),
+			getJSON: () => e.getJSON(),
+			setJSON: (doc) => e.commands.setContent(doc),
+			apply: (format) => {
+				const run = COMMAND[format as WebFormat]
+				if (run) run(e.chain().focus()).run()
+			},
+			linkTo: (url, anchor) => {
+				if (anchor != null && anchor !== '') {
+					e.chain().focus().insertContent({ type: 'text', text: anchor, marks: [{ type: 'link', attrs: { href: url } }] }).run()
+				} else {
+					e.chain().focus().extendMarkRange('link').setLink({ href: url }).run()
+				}
+			},
+			removeLink: () => e.chain().focus().unsetLink().run(),
+			isActive: (format) => IS_ACTIVE[format]?.(e) ?? false,
+			undo: () => e.commands.undo(),
+			redo: () => e.commands.redo(),
+			focus: () => e.commands.focus(),
+			blur: () => e.commands.blur(),
+			isFocused: () => e.isFocused,
+			native: e,
+		}
+
+		props.bind?.(bound.current)
+	}, [editor])
+
+	<div className={['vx-richtext', props.className]} style={props.style}>
+		<EditorContent editor={editor} />
+	</div>
+}

package/src/index.macos.ts

@@ -0,0 +1,19 @@
+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 type * from './types'
+
+/** No editor, no bridge. */
+export function ensureJSONBridge(): Promise<boolean> {
+	return Promise.resolve(false)
+}
+
+export function jsonBridgeReady(): boolean {
+	return false
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { TiptapEditor, supported } from './TiptapEditor.tsrx'
+export { ensureJSONBridge, jsonBridgeReady } from './json-bridge'
+export type * from './types'

package/src/index.web.ts

@@ -0,0 +1,12 @@
+export { TiptapEditor, supported } from './TiptapEditor.web.tsrx'
+export type * from './types'
+
+/** Web needs no lazy bridge — tiptap is in the bundle already. Kept for
+ *  call-site parity with the native entry. */
+export function ensureJSONBridge(): Promise<boolean> {
+	return Promise.resolve(true)
+}
+
+export function jsonBridgeReady(): boolean {
+	return true
+}

package/src/json-bridge.ts

@@ -0,0 +1,124 @@
+/** Lazy tiptap document-model bridge for native runtimes. The DOM-free
+ *  slices (@tiptap/core schema + generateJSON, @tiptap/static-renderer,
+ *  zeed-dom as the parser host) load on demand — on a runtime that can't
+ *  host them the bridge settles to unavailable and callers get null/no-op.
+ *
+ *  Import behavior was proven by the demos probe (see packages/demos
+ *  TiptapProbe): all four modules load cleanly on both NS engines; the
+ *  failure mode left is a future version or bundler regression, which the
+ *  catch below degrades instead of crashing. */
+
+import type { TiptapJSON } from './types'
+
+interface Bridge {
+	generateJSON: (html: string, extensions: any[]) => any
+	renderToHTMLString: (options: { extensions: any[]; content: any }) => string
+	extensions: any[]
+}
+
+let bridge: Bridge | null | undefined
+
+/** zeed-dom's classList is a plain {contains,add,remove} object; tiptap's
+ *  codeBlock parseHTML spreads it. Wrap the VElement getter so it hands back
+ *  an iterable array that keeps the mutation methods. */
+function patchClassList(VElement: any): void {
+	const proto = VElement?.prototype
+	if (!proto) {
+		throw new Error('VElement.prototype unavailable')
+	}
+
+	const desc = Object.getOwnPropertyDescriptor(proto, 'classList')
+	if (!desc?.get) {
+		throw new Error('classList is not a prototype getter')
+	}
+
+	if ((desc.get as any).__xplatPatched) {
+		return
+	}
+
+	const patched = function (this: any) {
+		const cl = desc.get!.call(this)
+		if (cl && typeof cl[Symbol.iterator] !== 'function') {
+			const tokens = String(this.getAttribute('class') ?? '')
+				.split(/\s+/)
+				.filter(Boolean)
+
+			return Object.assign(tokens, cl)
+		}
+
+		return cl
+	}
+
+	;(patched as any).__xplatPatched = true
+	Object.defineProperty(proto, 'classList', {
+		configurable: true,
+		get: patched,
+		set: desc.set,
+	})
+}
+
+/** Install the minimal parse globals generateJSON's elementFromString
+ *  reads. Only installs when the host lacks them, so a real DOM (web
+ *  target) is never clobbered. */
+function installDomShim(zeed: any): void {
+	const g = globalThis as any
+	if (g.window?.DOMParser) {
+		return
+	}
+
+	class ZeedDOMParser {
+		parseFromString(html: string) {
+			const doc = zeed.createHTMLDocument()
+			doc.body.innerHTML = html
+			return doc
+		}
+	}
+
+	g.window = { DOMParser: ZeedDOMParser }
+	g.document = zeed.createHTMLDocument()
+}
+
+export async function ensureJSONBridge(): Promise<boolean> {
+	if (bridge !== undefined) {
+		return bridge !== null
+	}
+
+	try {
+		const [core, sk, sr, zeed] = await Promise.all([
+			import('@tiptap/core'),
+			import('@tiptap/starter-kit'),
+			import('@tiptap/static-renderer'),
+			import('zeed-dom'),
+		])
+
+		patchClassList(zeed.VElement)
+		installDomShim(zeed)
+		const StarterKit = (sk as any).default ?? (sk as any).StarterKit
+
+		bridge = {
+			generateJSON: core.generateJSON,
+			renderToHTMLString: sr.renderToHTMLString,
+			extensions: [StarterKit],
+		}
+
+		return true
+	} catch {
+		bridge = null
+		return false
+	}
+}
+
+/** HTML → doc JSON through tiptap's own parseHTML rules. Null when the
+ *  bridge hasn't loaded (call ensureJSONBridge first / check `ready`). */
+export function htmlToJSON(html: string): TiptapJSON | null {
+	return (bridge?.generateJSON(html, bridge.extensions) as TiptapJSON | undefined) ?? null
+}
+
+/** Doc JSON → HTML via tiptap's own renderHTML rules (no DOM). */
+export function jsonToHTML(doc: TiptapJSON): string | null {
+	return bridge?.renderToHTMLString({ extensions: bridge.extensions, content: doc }) ?? null
+}
+
+export function jsonBridgeReady(): boolean {
+	return bridge != null
+}

package/src/types.ts

@@ -0,0 +1,96 @@
+/** 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
+ *  map to Aztec formats on Android. */
+export type TiptapFormat =
+	| 'bold'
+	| 'italic'
+	| 'underline'
+	| 'strikethrough'
+	| 'code'
+	| 'blockquote'
+	| 'bulletList'
+	| 'orderedList'
+	| 'taskList'
+	| 'codeBlock'
+	| 'horizontalRule'
+	| 'highlight'
+	| 'subscript'
+	| 'superscript'
+	| 'paragraph'
+	| 'heading1'
+	| 'heading2'
+	| 'heading3'
+	| 'heading4'
+	| 'heading5'
+	| 'heading6'
+	| 'alignLeft'
+	| 'alignCenter'
+	| 'alignRight'
+	| 'link'
+
+/** Tiptap document JSON (`{ type: 'doc', content: [...] }`). Opaque here —
+ *  callers round-trip through tiptap's own schema on both platforms. */
+export type TiptapJSON = { type: string; content?: unknown[] } & Record<string, unknown>
+
+export interface TiptapEditorHandle {
+	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. */
+	getJSON(): TiptapJSON | null
+	setJSON(doc: TiptapJSON): void
+	apply(format: TiptapFormat): void
+	linkTo(url: string, anchor?: string): void
+	removeLink(): void
+	isActive(format: TiptapFormat): boolean
+	undo(): void
+	redo(): void
+	focus(): void
+	blur(): void
+	isFocused(): boolean
+	/** The platform surface — a tiptap `Editor` on web, `AztecText` on
+	 *  Android. */
+	native: any
+}
+
+export interface TiptapEditorProps {
+	id?: string
+	className?: string
+	style?: any
+	/** Document HTML. Seed at mount; external changes re-push (web: via
+	 *  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`). */
+	json?: TiptapJSON
+	placeholder?: string
+	editable?: boolean
+	autofocus?: boolean
+	onReady?: () => void
+	/** 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. */
+	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
+	android?: Record<string, any>
+	ios?: Record<string, any>
+	row?: number | string
+	col?: number | string
+	rowSpan?: number
+	colSpan?: number
+	dock?: 'left' | 'top' | 'right' | 'bottom'
+	left?: number
+	top?: number
+	flexGrow?: number
+	flexShrink?: number
+	alignSelf?: 'auto' | 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+	order?: number
+}

package/types/index.d.ts

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

package/types/types.d.ts

@@ -0,0 +1,75 @@
+/** 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
+ *  map to Aztec formats on Android. */
+export type TiptapFormat = 'bold' | 'italic' | 'underline' | 'strikethrough' | 'code' | 'blockquote' | 'bulletList' | 'orderedList' | 'taskList' | 'codeBlock' | 'horizontalRule' | 'highlight' | 'subscript' | 'superscript' | 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading5' | 'heading6' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'link';
+/** Tiptap document JSON (`{ type: 'doc', content: [...] }`). Opaque here —
+ *  callers round-trip through tiptap's own schema on both platforms. */
+export type TiptapJSON = {
+    type: string;
+    content?: unknown[];
+} & Record<string, unknown>;
+export interface TiptapEditorHandle {
+    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. */
+    getJSON(): TiptapJSON | null;
+    setJSON(doc: TiptapJSON): void;
+    apply(format: TiptapFormat): void;
+    linkTo(url: string, anchor?: string): void;
+    removeLink(): void;
+    isActive(format: TiptapFormat): boolean;
+    undo(): void;
+    redo(): void;
+    focus(): void;
+    blur(): void;
+    isFocused(): boolean;
+    /** The platform surface — a tiptap `Editor` on web, `AztecText` on
+     *  Android. */
+    native: any;
+}
+export interface TiptapEditorProps {
+    id?: string;
+    className?: string;
+    style?: any;
+    /** Document HTML. Seed at mount; external changes re-push (web: via
+     *  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`). */
+    json?: TiptapJSON;
+    placeholder?: string;
+    editable?: boolean;
+    autofocus?: boolean;
+    onReady?: () => void;
+    /** 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. */
+    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;
+    android?: Record<string, any>;
+    ios?: Record<string, any>;
+    row?: number | string;
+    col?: number | string;
+    rowSpan?: number;
+    colSpan?: number;
+    dock?: 'left' | 'top' | 'right' | 'bottom';
+    left?: number;
+    top?: number;
+    flexGrow?: number;
+    flexShrink?: number;
+    alignSelf?: 'auto' | 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline';
+    order?: number;
+}

package/index.d.ts

@@ -1 +0,0 @@
-export {}

package/index.js

@@ -1,2 +0,0 @@
-// Reservation stub; implementation will arrive in a later release.
-module.exports = {}