@octane-xplat/richtext 0.0.0-stage → 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,22 @@
-# Temporary Holding Version
+# `@octane-xplat/richtext`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The native rich-text editing leaf: WordPress Aztec's `AztecText` on Android —
+a `Spannable`-backed `EditText`, not a WebView. iOS mounts an unsupported
+placeholder until the Aztec-iOS Swift facade lands; web, macOS, and Windows
+return `supported: false` (the `@octane-xplat/tiptap` facade covers web).
+
+```ts
+import { RichTextEditor, supported } from '@octane-xplat/richtext'
+```
+
+Content in/out is document HTML via Aztec `fromHtml`/`toPlainHtml`. The
+`bind` callback returns an imperative handle (`getHTML`/`setHTML`,
+`apply(format)`, `linkTo`/`removeLink`, `isActive`, `undo`/`redo`,
+`focus`/`blur`, `native`) once the editor exists, and `onSelectionChange`
+reports the active `RichTextFormat` set at the caret.
+
+The Android Aztec dependency (`org.wordpress:aztec:v2.1.7`) arrives through
+the leaf's `platforms/android/include.gradle` — no app-level gradle work.
+See the framework guide for the full contract and the demo:
+[`docs/rich-text.md`](../../docs/rich-text.md) and
+[`packages/demos/src/RichTextEditorDemo.tsrx`](../demos/src/RichTextEditorDemo.tsrx).

package/dist/native/RichTextEditor.android.js

@@ -0,0 +1,234 @@
+import { defineUniversalComponent, hookSlots, registerElement, universalPlan, universalValue, useCallback, useEffect, useRef } from "@nativescript-community/octane";
+import { View } from "@nativescript/core";
+//#region src/RichTextEditor.android.tsrx
+var _hs$ = /* @__PURE__ */ hookSlots(10);
+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 _h$8 = /* @__PURE__ */ Symbol(_hs$ + 8);
+var _h$9 = /* @__PURE__ */ Symbol(_hs$ + 9);
+var __octaneUniversalPlan0 = universalPlan("nativescript", {
+	"kind": "host",
+	"type": "xplatrichtext",
+	"bindings": [
+		["ref", 0],
+		["id", 1],
+		["className", 2],
+		["style", 3],
+		["row", 4],
+		["col", 5],
+		["rowSpan", 6],
+		["colSpan", 7],
+		["dock", 8],
+		["left", 9],
+		["top", 10],
+		["flexGrow", 11],
+		["flexShrink", 12],
+		["alignSelf", 13],
+		["order", 14]
+	]
+});
+var aztec = globalThis.org?.wordpress?.aztec;
+var androidText = globalThis.android?.text;
+var androidView = globalThis.android?.view;
+var FORMATS = {
+	bold: () => aztec.AztecTextFormat.FORMAT_BOLD,
+	italic: () => aztec.AztecTextFormat.FORMAT_ITALIC,
+	underline: () => aztec.AztecTextFormat.FORMAT_UNDERLINE,
+	strikethrough: () => aztec.AztecTextFormat.FORMAT_STRIKETHROUGH,
+	code: () => aztec.AztecTextFormat.FORMAT_CODE,
+	blockquote: () => aztec.AztecTextFormat.FORMAT_QUOTE,
+	bulletList: () => aztec.AztecTextFormat.FORMAT_UNORDERED_LIST,
+	orderedList: () => aztec.AztecTextFormat.FORMAT_ORDERED_LIST,
+	taskList: () => aztec.AztecTextFormat.FORMAT_TASK_LIST,
+	codeBlock: () => aztec.AztecTextFormat.FORMAT_PREFORMAT,
+	horizontalRule: () => aztec.AztecTextFormat.FORMAT_HORIZONTAL_RULE,
+	highlight: () => aztec.AztecTextFormat.FORMAT_MARK,
+	subscript: () => aztec.AztecTextFormat.FORMAT_SUBSCRIPT,
+	superscript: () => aztec.AztecTextFormat.FORMAT_SUPERSCRIPT,
+	paragraph: () => aztec.AztecTextFormat.FORMAT_PARAGRAPH,
+	heading1: () => aztec.AztecTextFormat.FORMAT_HEADING_1,
+	heading2: () => aztec.AztecTextFormat.FORMAT_HEADING_2,
+	heading3: () => aztec.AztecTextFormat.FORMAT_HEADING_3,
+	heading4: () => aztec.AztecTextFormat.FORMAT_HEADING_4,
+	heading5: () => aztec.AztecTextFormat.FORMAT_HEADING_5,
+	heading6: () => aztec.AztecTextFormat.FORMAT_HEADING_6,
+	alignLeft: () => aztec.AztecTextFormat.FORMAT_ALIGN_LEFT,
+	alignCenter: () => aztec.AztecTextFormat.FORMAT_ALIGN_CENTER,
+	alignRight: () => aztec.AztecTextFormat.FORMAT_ALIGN_RIGHT
+};
+var AZTEC_OF = Object.entries(FORMATS);
+var formatOf = (format) => format === "link" ? aztec.AztecTextFormat.FORMAT_LINK : FORMATS[format]();
+var AztecEditor = class extends View {
+	createNativeView() {
+		return new aztec.AztecText(this._context);
+	}
+};
+registerElement("xplatrichtext", AztecEditor);
+var supported = true;
+var activeFormats = (editor) => {
+	const styles = editor.getAppliedStyles(editor.getSelectionStart(), editor.getSelectionEnd());
+	const count = styles?.size?.() ?? 0;
+	const active = /* @__PURE__ */ new Set();
+	for (let i = 0; i < count; i++) active.add(styles.get(i));
+	const out = [];
+	for (const [name, get] of AZTEC_OF) if (active.has(get())) out.push(name);
+	if (active.has(aztec.AztecTextFormat.FORMAT_LINK)) out.push("link");
+	return out;
+};
+var RichTextEditor = defineUniversalComponent("nativescript", function RichTextEditor(props) {
+	const host = useRef(null, _h$0);
+	const lastEmitted = useRef(void 0, _h$1);
+	const applyingValue = useRef(false, _h$2);
+	const keyListener = useRef(null, _h$3);
+	const emitTimer = useRef(null, _h$4);
+	const bindHost = useCallback((v) => {
+		host.current = v;
+	}, [], _h$5);
+	const editor = () => host.current?.android;
+	const setEditable = (next) => {
+		const e = editor();
+		if (!e) return;
+		if (keyListener.current == null) keyListener.current = e.getKeyListener();
+		if (next) {
+			e.setKeyListener(keyListener.current);
+			e.setFocusable(true);
+			e.setCursorVisible(true);
+		} else {
+			e.setKeyListener(null);
+			e.setFocusable(false);
+			e.setCursorVisible(false);
+		}
+	};
+	const showKeyboard = (e) => {
+		try {
+			e.getContext().getSystemService(globalThis.android.content.Context.INPUT_METHOD_SERVICE)?.showSoftInput(e, androidView.inputmethod.InputMethodManager.SHOW_IMPLICIT);
+		} catch {}
+	};
+	const emitChange = () => {
+		if (!editor() || applyingValue.current) return;
+		clearTimeout(emitTimer.current);
+		emitTimer.current = setTimeout(() => {
+			const current = editor();
+			if (!current || applyingValue.current) return;
+			const html = current.toPlainHtml(false);
+			lastEmitted.current = html;
+			props.onChange?.(html);
+		}, 150);
+	};
+	const handle = (e) => ({
+		getHTML: () => e.toPlainHtml(false),
+		setHTML: (html) => {
+			applyingValue.current = true;
+			try {
+				e.fromHtml(html, true);
+				lastEmitted.current = html;
+			} finally {
+				applyingValue.current = false;
+			}
+		},
+		apply: (format) => {
+			if (format === "link") return;
+			e.toggleFormatting(formatOf(format));
+			emitChange();
+		},
+		linkTo: (url, anchor) => {
+			e.link(url, anchor ?? url, false);
+			emitChange();
+		},
+		removeLink: () => {
+			e.removeLink();
+			emitChange();
+		},
+		isActive: (format) => {
+			const applied = e.getAppliedStyles(e.getSelectionStart(), e.getSelectionEnd());
+			const count = applied?.size?.() ?? 0;
+			const target = formatOf(format);
+			for (let i = 0; i < count; i++) if (applied.get(i) === target) return true;
+			return false;
+		},
+		undo: () => e.undo(),
+		redo: () => e.redo(),
+		focus: () => {
+			e.requestFocus();
+			showKeyboard(e);
+		},
+		blur: () => e.clearFocus(),
+		isFocused: () => e.isFocused(),
+		native: e
+	});
+	useEffect(() => {
+		const e = editor();
+		if (!e || !aztec) return;
+		e.setOnSelectionChangedListener(new aztec.AztecText.OnSelectionChangedListener({ onSelectionChanged: (start, end) => props.onSelectionChange?.({
+			start,
+			end,
+			active: activeFormats(e)
+		}) }));
+		e.addTextChangedListener(new androidText.TextWatcher({
+			beforeTextChanged: () => {},
+			onTextChanged: () => {},
+			afterTextChanged: () => emitChange()
+		}));
+		e.setOnFocusChangeListener(new androidView.View.OnFocusChangeListener({ onFocusChange: (_v, focused) => focused ? props.onFocus?.() : props.onBlur?.() }));
+		if (props.placeholder !== void 0) e.setHint(props.placeholder);
+		setEditable(props.editable !== false);
+		if (props.value !== void 0) {
+			applyingValue.current = true;
+			try {
+				e.fromHtml(props.value, true);
+			} finally {
+				applyingValue.current = false;
+			}
+		}
+		if (props.autofocus) {
+			e.requestFocus();
+			showKeyboard(e);
+		}
+		if (props.android) Object.assign(e, props.android);
+		props.bind?.(handle(e));
+		props.onReady?.();
+	}, [], _h$6);
+	useEffect(() => {
+		const e = editor();
+		if (!e || props.value === void 0) return;
+		if (props.value === lastEmitted.current) return;
+		applyingValue.current = true;
+		try {
+			e.fromHtml(props.value, true);
+		} finally {
+			applyingValue.current = false;
+		}
+	}, [props.value], _h$7);
+	useEffect(() => {
+		setEditable(props.editable !== false);
+	}, [props.editable], _h$8);
+	useEffect(() => {
+		const e = editor();
+		if (e && props.placeholder !== void 0) e.setHint(props.placeholder);
+	}, [props.placeholder], _h$9);
+	return universalValue(__octaneUniversalPlan0, [
+		bindHost,
+		props.id,
+		props.className,
+		props.style,
+		props.row,
+		props.col,
+		props.rowSpan,
+		props.colSpan,
+		props.dock,
+		props.left,
+		props.top,
+		props.flexGrow,
+		props.flexShrink,
+		props.alignSelf,
+		props.order
+	]);
+}, { "module": "@nativescript-community/octane" });
+//#endregion
+export { RichTextEditor, supported };

package/dist/native/RichTextEditor.ios.js

@@ -0,0 +1,22 @@
+import { defineUniversalComponent, universalPlan, universalValue } from "@nativescript-community/octane";
+//#region src/RichTextEditor.ios.tsrx
+var __octaneUniversalPlan0 = universalPlan("nativescript", {
+	"kind": "host",
+	"type": "label",
+	"props": { "text": "Rich text editing is not supported on iOS yet." },
+	"bindings": [
+		["id", 0],
+		["className", 1],
+		["style", 2]
+	]
+});
+var supported = false;
+var RichTextEditor = defineUniversalComponent("nativescript", function RichTextEditor(props) {
+	return universalValue(__octaneUniversalPlan0, [
+		props.id,
+		props.className,
+		props.style
+	]);
+}, { "module": "@nativescript-community/octane" });
+//#endregion
+export { RichTextEditor, supported };

package/dist/native/index.js

@@ -0,0 +1,2 @@
+import { RichTextEditor, supported } from "./RichTextEditor";
+export { RichTextEditor, supported };

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

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "buildId": "f6769804-c57f-408a-9066-2cfebe36da4e",
+  "mode": "production",
+  "capabilities": {
+    "independentHydration": false
+  }
+}

package/dist/web/index.js

@@ -0,0 +1,9 @@
+//#region src/index.web.ts
+var supported = false;
+/** Web routes through @octane-xplat/tiptap — this leaf only exists for the
+*  native (Aztec) surface. */
+function RichTextEditor(_props) {
+	return null;
+}
+//#endregion
+export { RichTextEditor, supported };

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

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "buildId": "bd95f265-682a-446a-a284-1f3419b2fb06",
+  "mode": "production",
+  "capabilities": {
+    "independentHydration": false
+  }
+}

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "@octane-xplat/richtext",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0",
+  "description": "Native rich-text editing leaf for Octane xplat — WordPress Aztec on Android (iOS stubbed, deferred)",
+  "keywords": [
+    "android",
+    "aztec",
+    "cross-platform",
+    "editor",
+    "octane",
+    "rich-text",
+    "richtext",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/richtext",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
+    "directory": "packages/richtext"
+  },
+  "files": [
+    "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"
+  },
+  "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/platforms/android/include.gradle

@@ -0,0 +1,7 @@
+repositories {
+	maven { url "https://a8c-libs.s3.amazonaws.com/android" }
+}
+
+dependencies {
+	implementation "org.wordpress:aztec:v2.1.7"
+}

package/src/RichTextEditor.android.tsrx

@@ -0,0 +1,281 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useCallback, useEffect, useRef } from 'octane'
+import { View } from '@nativescript/core'
+import { registerElement } from '@nativescript-community/octane'
+import type { Attributes } from '@nativescript-community/octane/intrinsics'
+import type {
+	RichTextEditorHandle,
+	RichTextEditorProps,
+	RichTextFormat,
+} from './types'
+
+/** `org.wordpress.aztec` arrives through the leaf's aar — there are no
+ *  generated typings for it, so every touch goes through `as any` at one
+ *  boundary instead of `declare const org` per call site. */
+const aztec = (globalThis as any).org?.wordpress?.aztec
+const androidText = (globalThis as any).android?.text
+const androidView = (globalThis as any).android?.view
+
+const FORMATS: Record<Exclude<RichTextFormat, 'link'>, () => any> = {
+	bold: () => aztec.AztecTextFormat.FORMAT_BOLD,
+	italic: () => aztec.AztecTextFormat.FORMAT_ITALIC,
+	underline: () => aztec.AztecTextFormat.FORMAT_UNDERLINE,
+	strikethrough: () => aztec.AztecTextFormat.FORMAT_STRIKETHROUGH,
+	code: () => aztec.AztecTextFormat.FORMAT_CODE,
+	blockquote: () => aztec.AztecTextFormat.FORMAT_QUOTE,
+	bulletList: () => aztec.AztecTextFormat.FORMAT_UNORDERED_LIST,
+	orderedList: () => aztec.AztecTextFormat.FORMAT_ORDERED_LIST,
+	taskList: () => aztec.AztecTextFormat.FORMAT_TASK_LIST,
+	codeBlock: () => aztec.AztecTextFormat.FORMAT_PREFORMAT,
+	horizontalRule: () => aztec.AztecTextFormat.FORMAT_HORIZONTAL_RULE,
+	highlight: () => aztec.AztecTextFormat.FORMAT_MARK,
+	subscript: () => aztec.AztecTextFormat.FORMAT_SUBSCRIPT,
+	superscript: () => aztec.AztecTextFormat.FORMAT_SUPERSCRIPT,
+	paragraph: () => aztec.AztecTextFormat.FORMAT_PARAGRAPH,
+	heading1: () => aztec.AztecTextFormat.FORMAT_HEADING_1,
+	heading2: () => aztec.AztecTextFormat.FORMAT_HEADING_2,
+	heading3: () => aztec.AztecTextFormat.FORMAT_HEADING_3,
+	heading4: () => aztec.AztecTextFormat.FORMAT_HEADING_4,
+	heading5: () => aztec.AztecTextFormat.FORMAT_HEADING_5,
+	heading6: () => aztec.AztecTextFormat.FORMAT_HEADING_6,
+	alignLeft: () => aztec.AztecTextFormat.FORMAT_ALIGN_LEFT,
+	alignCenter: () => aztec.AztecTextFormat.FORMAT_ALIGN_CENTER,
+	alignRight: () => aztec.AztecTextFormat.FORMAT_ALIGN_RIGHT,
+}
+
+const AZTEC_OF: [RichTextFormat, () => any][] = Object.entries(FORMATS) as any
+
+const formatOf = (format: RichTextFormat) =>
+	format === 'link' ? aztec.AztecTextFormat.FORMAT_LINK : FORMATS[format]()
+
+class AztecEditor extends View {
+	createNativeView() {
+		return new aztec.AztecText(this._context)
+	}
+}
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		xplatrichtext: Attributes<typeof AztecEditor>
+	}
+}
+
+registerElement('xplatrichtext', AztecEditor)
+
+export const supported = true
+
+/** Active formats at the selection, mapped back to facade spellings. */
+const activeFormats = (editor: any): RichTextFormat[] => {
+	const styles = editor.getAppliedStyles(
+		editor.getSelectionStart(),
+		editor.getSelectionEnd(),
+	)
+
+	const count = styles?.size?.() ?? 0
+	const active = new Set<any>()
+	for (let i = 0; i < count; i++) active.add(styles.get(i))
+
+	const out: RichTextFormat[] = []
+	for (const [name, get] of AZTEC_OF) {
+		if (active.has(get())) out.push(name)
+	}
+
+	if (active.has(aztec.AztecTextFormat.FORMAT_LINK)) out.push('link')
+	return out
+}
+
+/** WordPress Aztec surface on Android — a true Spannable-backed editor, not
+ *  a WebView. Content in/out is HTML (`fromHtml`/`toPlainHtml`); JSON
+ *  interchange lives one layer up in @octane-xplat/tiptap. */
+export function RichTextEditor(props: RichTextEditorProps) @{
+	const host = useRef<any>(null)
+	const lastEmitted = useRef<string | undefined>(undefined)
+	const applyingValue = useRef(false)
+	const keyListener = useRef<any>(null)
+	const emitTimer = useRef<any>(null)
+
+	// Stable identity — an inline closure re-fires ref(null)/ref(v) per
+	// render, which would bounce host.current around the effects below.
+	const bindHost = useCallback((v: any) => {
+		host.current = v
+	}, [])
+
+	const editor = () => host.current?.android
+
+	const setEditable = (next: boolean) => {
+		const e = editor()
+		if (!e) return
+		if (keyListener.current == null) keyListener.current = e.getKeyListener()
+		if (next) {
+			e.setKeyListener(keyListener.current)
+			e.setFocusable(true)
+			e.setCursorVisible(true)
+		} else {
+			e.setKeyListener(null)
+			e.setFocusable(false)
+			e.setCursorVisible(false)
+		}
+	}
+
+	const showKeyboard = (e: any) => {
+		try {
+			const imm = e.getContext().getSystemService(
+				(globalThis as any).android.content.Context.INPUT_METHOD_SERVICE,
+			)
+
+			imm?.showSoftInput(e, androidView.inputmethod.InputMethodManager.SHOW_IMPLICIT)
+		} catch {}
+	}
+
+	const emitChange = () => {
+		const e = editor()
+		if (!e || applyingValue.current) return
+		clearTimeout(emitTimer.current)
+		emitTimer.current = setTimeout(() => {
+			const current = editor()
+			if (!current || applyingValue.current) return
+			const html = current.toPlainHtml(false)
+			lastEmitted.current = html
+			props.onChange?.(html)
+		}, 150)
+	}
+
+	const handle = (e: any): RichTextEditorHandle => ({
+		getHTML: () => e.toPlainHtml(false),
+		setHTML: (html: string) => {
+			applyingValue.current = true
+			try {
+				e.fromHtml(html, true)
+				lastEmitted.current = html
+			} finally {
+				applyingValue.current = false
+			}
+		},
+		apply: (format: RichTextFormat) => {
+			if (format === 'link') return
+			e.toggleFormatting(formatOf(format))
+			emitChange()
+		},
+		linkTo: (url: string, anchor?: string) => {
+			e.link(url, anchor ?? url, false)
+			emitChange()
+		},
+		removeLink: () => {
+			e.removeLink()
+			emitChange()
+		},
+		isActive: (format: RichTextFormat) => {
+			const applied = e.getAppliedStyles(e.getSelectionStart(), e.getSelectionEnd())
+			const count = applied?.size?.() ?? 0
+			const target = formatOf(format)
+			for (let i = 0; i < count; i++) {
+				if (applied.get(i) === target) return true
+			}
+
+			return false
+		},
+		undo: () => e.undo(),
+		redo: () => e.redo(),
+		focus: () => {
+			e.requestFocus()
+			showKeyboard(e)
+		},
+		blur: () => e.clearFocus(),
+		isFocused: () => e.isFocused(),
+		native: e,
+	})
+
+	useEffect(() => {
+		const e = editor()
+		if (!e || !aztec) return
+
+		e.setOnSelectionChangedListener(
+			new aztec.AztecText.OnSelectionChangedListener({
+				onSelectionChanged: (start: number, end: number) =>
+					props.onSelectionChange?.({
+						start,
+						end,
+						active: activeFormats(e),
+					}),
+			}),
+		)
+
+		e.addTextChangedListener(
+			new androidText.TextWatcher({
+				beforeTextChanged: () => {},
+				onTextChanged: () => {},
+				afterTextChanged: () => emitChange(),
+			}),
+		)
+
+		e.setOnFocusChangeListener(
+			new androidView.View.OnFocusChangeListener({
+				onFocusChange: (_v: any, focused: boolean) =>
+					focused ? props.onFocus?.() : props.onBlur?.(),
+			}),
+		)
+
+		if (props.placeholder !== undefined) e.setHint(props.placeholder)
+		setEditable(props.editable !== false)
+
+		if (props.value !== undefined) {
+			applyingValue.current = true
+			try {
+				e.fromHtml(props.value, true)
+			} finally {
+				applyingValue.current = false
+			}
+		}
+
+		if (props.autofocus) {
+			e.requestFocus()
+			showKeyboard(e)
+		}
+
+		if (props.android) Object.assign(e, props.android)
+		props.bind?.(handle(e))
+		props.onReady?.()
+	}, [])
+
+	// `value` lands like a controlled prop, minus the loop: text the editor
+	// emitted through onChange is never pushed back; any other change is an
+	// external reset (and resets Aztec's undo stack, like PM setContent).
+	useEffect(() => {
+		const e = editor()
+		if (!e || props.value === undefined) return
+		if (props.value === lastEmitted.current) return
+		applyingValue.current = true
+		try {
+			e.fromHtml(props.value, true)
+		} finally {
+			applyingValue.current = false
+		}
+	}, [props.value])
+
+	useEffect(() => {
+		setEditable(props.editable !== false)
+	}, [props.editable])
+
+	useEffect(() => {
+		const e = editor()
+		if (e && props.placeholder !== undefined) e.setHint(props.placeholder)
+	}, [props.placeholder])
+
+	<xplatrichtext
+		ref={bindHost}
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		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/RichTextEditor.ios.tsrx

@@ -0,0 +1,15 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { RichTextEditorProps } from './types'
+
+export const supported = false
+
+/** iOS bring-up is deferred — the Swift facade over Aztec-iOS lands in a
+ *  follow-up. Renders the placeholder so a shared screen still mounts. */
+export function RichTextEditor(props: RichTextEditorProps) @{
+	<label
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		text="Rich text editing is not supported on iOS yet."
+	/>;
+}

package/src/index.macos.ts

@@ -0,0 +1,10 @@
+import type { RichTextEditorProps } from './types'
+
+export const supported = false
+
+/** The macOS editor is deferred; the tiptap facade covers desktop needs. */
+export function RichTextEditor(_props: RichTextEditorProps): null {
+	return null
+}
+
+export type * from './types'

package/src/index.ts

@@ -0,0 +1,5 @@
+// Keep this relative import extensionless so the NativeScript resolver picks
+// the Android (Aztec) or iOS (stub until the Swift facade lands) component
+// for the current build target.
+export { RichTextEditor, supported } from './RichTextEditor'
+export type * from './types'

package/src/index.web.ts

@@ -0,0 +1,11 @@
+import type { RichTextEditorProps } from './types'
+
+export const supported = false
+
+/** Web routes through @octane-xplat/tiptap — this leaf only exists for the
+ *  native (Aztec) surface. */
+export function RichTextEditor(_props: RichTextEditorProps): null {
+	return null
+}
+
+export type * from './types'

package/src/types.ts

@@ -0,0 +1,97 @@
+/** Supported on Android today (WordPress Aztec); iOS is stubbed until the
+ *  Swift-facade bring-up. Web/macOS/Windows route through the tiptap facade
+ *  instead of this leaf. */
+export type RichTextFormat =
+	| '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'
+
+export interface RichTextEditorHandle {
+	/** Serialized document HTML (Aztec's "plain" HTML — no contenteditable
+	 *  markup). */
+	getHTML(): string
+	/** Replace the document; resets Aztec's undo history. */
+	setHTML(html: string): void
+	/** Toggle a format at the current selection. `link` needs
+	 *  `linkTo(url, anchor)` instead. */
+	apply(format: RichTextFormat): void
+	/** Insert or re-target a link over the current selection. */
+	linkTo(url: string, anchor?: string): void
+	removeLink(): void
+	/** Formats active at the selection — powers toolbar highlight state. */
+	isActive(format: RichTextFormat): boolean
+	/** Android: Aztec's history batches keyboard input only — format
+	 *  toggles and programmatic edits do not register. */
+	undo(): void
+	redo(): void
+	focus(): void
+	blur(): void
+	isFocused(): boolean
+	/** The platform surface — `AztecText` on Android. */
+	native: any
+}
+
+export interface RichTextSelectionChange {
+	start: number
+	end: number
+	/** Formats active at the caret/range, in facade spellings. */
+	active: RichTextFormat[]
+}
+
+export interface RichTextEditorProps {
+	id?: string
+	className?: string
+	style?: any
+	/** Initial document HTML. Re-applied only when the string changes
+	 *  externally — text the editor emitted back through `onChange` is never
+	 *  re-pushed, so typing doesn't reparse the document. */
+	value?: string
+	placeholder?: string
+	editable?: boolean
+	autofocus?: boolean
+	onReady?: () => void
+	onChange?: (html: string) => void
+	onSelectionChange?: (event: RichTextSelectionChange) => void
+	onFocus?: () => void
+	onBlur?: () => void
+	/** Imperative handle — fires once when the native editor exists. */
+	bind?: (handle: RichTextEditorHandle) => void
+	/** Per-platform escape bag — properties are assigned onto the native
+	 *  `AztecText` after the leaf's own props. */
+	android?: Record<string, any>
+	ios?: Record<string, any>
+	// NativeScript layout-child attributes the driver reads on this element.
+	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,6 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { RichTextEditorProps } from './types'
+
+export declare const RichTextEditor: UniversalComponent<RichTextEditorProps>
+export declare const supported: boolean
+export type * from './types'

package/types/types.d.ts

@@ -0,0 +1,68 @@
+/** Supported on Android today (WordPress Aztec); iOS is stubbed until the
+ *  Swift-facade bring-up. Web/macOS/Windows route through the tiptap facade
+ *  instead of this leaf. */
+export type RichTextFormat = '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';
+export interface RichTextEditorHandle {
+    /** Serialized document HTML (Aztec's "plain" HTML — no contenteditable
+     *  markup). */
+    getHTML(): string;
+    /** Replace the document; resets Aztec's undo history. */
+    setHTML(html: string): void;
+    /** Toggle a format at the current selection. `link` needs
+     *  `linkTo(url, anchor)` instead. */
+    apply(format: RichTextFormat): void;
+    /** Insert or re-target a link over the current selection. */
+    linkTo(url: string, anchor?: string): void;
+    removeLink(): void;
+    /** Formats active at the selection — powers toolbar highlight state. */
+    isActive(format: RichTextFormat): boolean;
+    /** Android: Aztec's history batches keyboard input only — format
+     *  toggles and programmatic edits do not register. */
+    undo(): void;
+    redo(): void;
+    focus(): void;
+    blur(): void;
+    isFocused(): boolean;
+    /** The platform surface — `AztecText` on Android. */
+    native: any;
+}
+export interface RichTextSelectionChange {
+    start: number;
+    end: number;
+    /** Formats active at the caret/range, in facade spellings. */
+    active: RichTextFormat[];
+}
+export interface RichTextEditorProps {
+    id?: string;
+    className?: string;
+    style?: any;
+    /** Initial document HTML. Re-applied only when the string changes
+     *  externally — text the editor emitted back through `onChange` is never
+     *  re-pushed, so typing doesn't reparse the document. */
+    value?: string;
+    placeholder?: string;
+    editable?: boolean;
+    autofocus?: boolean;
+    onReady?: () => void;
+    onChange?: (html: string) => void;
+    onSelectionChange?: (event: RichTextSelectionChange) => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    /** Imperative handle — fires once when the native editor exists. */
+    bind?: (handle: RichTextEditorHandle) => void;
+    /** Per-platform escape bag — properties are assigned onto the native
+     *  `AztecText` after the leaf's own props. */
+    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;
+}