@canvist/lynx 0.0.0-stage → 0.2.0

package/CanvistLynx.podspec

@@ -0,0 +1,31 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name = "CanvistLynx"
+  s.version = package["version"]
+  s.summary = package["description"]
+  s.homepage = package["homepage"]
+  s.license = { type: package["license"] }
+  s.author = { "Ifiok Jr." => "support@canvist.dev" }
+  s.source = { git: "https://github.com/canvist/canvist.git", tag: "v#{s.version}" }
+
+  s.platforms = { ios: "17.0" }
+  s.source_files = "ios/**/*.{h,m}"
+  # Apps register the element by its tag and import only the module.
+  s.public_header_files = "ios/CanvistLynxModule.h"
+
+  # The native editor and its hosting (`CanvistHostView`, `CanvistHostCalls`):
+  # `platforms/apple/Canvist.podspec` in the canvist repository, which the
+  # app's Podfile points at.
+  s.dependency "Canvist", s.version.to_s
+  s.dependency "Lynx"
+
+  # No Intel simulator slice, like `Canvist`, and `Canvist-Swift.h`, which a
+  # static Swift pod does not put on its dependents' search paths.
+  s.pod_target_xcconfig = {
+    "EXCLUDED_ARCHS[sdk=iphonesimulator*]" => "x86_64",
+    "HEADER_SEARCH_PATHS" => '"$(PODS_CONFIGURATION_BUILD_DIR)/Canvist/Swift Compatibility Header"',
+  }
+end

package/android/build.gradle

@@ -0,0 +1,35 @@
+// The Lynx glue for canvist's Android editor (`io.github.ifiokjr:canvist-android`).
+// The element is Java so Lynx's annotation processor, which generates its
+// attribute setters, runs without kapt; the module is Kotlin, which Lynx
+// reaches by reflection.
+import groovy.json.JsonSlurper
+
+plugins {
+  id "com.android.library"
+}
+
+// The editor is released in step with this package, so they share a version.
+def canvistVersion = new JsonSlurper().parse(file("../package.json")).version
+def lynxVersion = rootProject.findProperty("lynxVersion") ?: "4.1.0"
+
+android {
+  namespace "io.github.ifiokjr.canvist.lynx"
+  compileSdk 37
+
+  defaultConfig {
+    minSdk 24
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+dependencies {
+  api "io.github.ifiokjr:canvist-android:${canvistVersion}"
+  implementation "androidx.annotation:annotation:1.9.1"
+  // The app brings Lynx itself.
+  compileOnly "org.lynxsdk.lynx:lynx:${lynxVersion}"
+  annotationProcessor "org.lynxsdk.lynx:lynx-processor:${lynxVersion}"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/io/github/ifiokjr/canvist/lynx/CanvistLynx.java

@@ -0,0 +1,33 @@
+package io.github.ifiokjr.canvist.lynx;
+
+import com.lynx.tasm.LynxEnv;
+import com.lynx.tasm.behavior.Behavior;
+import com.lynx.tasm.behavior.LynxContext;
+import com.lynx.tasm.behavior.ui.LynxUI;
+
+/**
+ * Registers canvist with Lynx: call {@link #registerModule()} after
+ * {@code LynxEnv.inst().init(...)}, and add {@link #behavior()} to each
+ * {@code LynxViewBuilder} with {@code addBehavior}.
+ */
+public final class CanvistLynx {
+  /** The element's tag. */
+  public static final String TAG = "canvist-editor";
+
+  private CanvistLynx() {}
+
+  /** Register the {@code CanvistEditors} native module with every LynxView. */
+  public static void registerModule() {
+    LynxEnv.inst().registerModule(CanvistLynxModule.NAME, CanvistLynxModule.class);
+  }
+
+  /** The behavior that creates {@code <canvist-editor>} elements. */
+  public static Behavior behavior() {
+    return new Behavior(TAG) {
+      @Override
+      public LynxUI createUI(LynxContext context) {
+        return new CanvistLynxEditor(context);
+      }
+    };
+  }
+}

package/android/src/main/java/io/github/ifiokjr/canvist/lynx/CanvistLynxEditor.java

@@ -0,0 +1,142 @@
+package io.github.ifiokjr.canvist.lynx;
+
+import android.content.Context;
+import androidx.annotation.NonNull;
+import com.lynx.react.bridge.Callback;
+import com.lynx.react.bridge.ReadableArray;
+import com.lynx.react.bridge.ReadableMap;
+import com.lynx.tasm.behavior.LynxContext;
+import com.lynx.tasm.behavior.LynxProp;
+import com.lynx.tasm.behavior.LynxUIMethod;
+import com.lynx.tasm.behavior.LynxUIMethodConstants;
+import com.lynx.tasm.behavior.ui.LynxUI;
+import com.lynx.tasm.event.LynxCustomEvent;
+import io.github.ifiokjr.canvist.CanvistHostView;
+import io.github.ifiokjr.canvist.EditorChange;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * {@code <canvist-editor>}: a {@link CanvistHostView} created from the
+ * element's first attributes, sending {@code ready}, {@code change},
+ * {@code focuschange}, and {@code error} events.
+ */
+public class CanvistLynxEditor extends LynxUI<CanvistHostView> implements CanvistHostView.Listener {
+  private String editorId;
+  private List<String> extensions = new ArrayList<>();
+  private String contentFormat;
+  private String content;
+
+  public CanvistLynxEditor(LynxContext context) {
+    super(context);
+  }
+
+  @Override
+  protected CanvistHostView createView(Context context) {
+    CanvistHostView host = new CanvistHostView(context);
+    host.setListener(this);
+    return host;
+  }
+
+  @LynxProp(name = "editor-id")
+  public void setEditorId(String value) {
+    editorId = value;
+  }
+
+  @LynxProp(name = "extensions")
+  public void setExtensions(ReadableArray value) {
+    List<String> names = new ArrayList<>();
+    for (int index = 0; value != null && index < value.size(); index++) {
+      names.add(value.getString(index));
+    }
+    extensions = names;
+  }
+
+  @LynxProp(name = "content-format")
+  public void setContentFormat(String value) {
+    contentFormat = value;
+  }
+
+  @LynxProp(name = "content")
+  public void setContent(String value) {
+    content = value;
+  }
+
+  @LynxProp(name = "text-size")
+  public void setTextSize(float value) {
+    mView.setFontSize(value);
+  }
+
+  /**
+   * The editor starts once the first attributes have all arrived; later
+   * changes to {@code extensions} and {@code content} have no effect, as the
+   * JavaScript API documents.
+   */
+  @Override
+  public void onPropsUpdated() {
+    super.onPropsUpdated();
+
+    if (editorId == null || editorId.isEmpty()) {
+      return;
+    }
+
+    mView.start(editorId, extensions, emptyAsNull(contentFormat), emptyAsNull(content));
+  }
+
+  @Override
+  public void destroy() {
+    mView.stop();
+    super.destroy();
+  }
+
+  @LynxUIMethod
+  public void focus(ReadableMap params, Callback callback) {
+    mView.focusEditor();
+    callback.invoke(LynxUIMethodConstants.SUCCESS);
+  }
+
+  @LynxUIMethod
+  public void blur(ReadableMap params, Callback callback) {
+    mView.blurEditor();
+    callback.invoke(LynxUIMethodConstants.SUCCESS);
+  }
+
+  @Override
+  public void onReady(@NonNull CanvistHostView view, @NonNull String editorId) {
+    LynxCustomEvent event = new LynxCustomEvent(getSign(), "ready");
+    event.addDetail("editorId", editorId);
+    emit(event);
+  }
+
+  @Override
+  public void onChange(@NonNull CanvistHostView view, @NonNull EditorChange change) {
+    LynxCustomEvent event = new LynxCustomEvent(getSign(), "change");
+    event.addDetail("document", change.getDocument());
+    event.addDetail("selection", change.getSelection());
+    event.addDetail("composition", change.getComposition());
+    emit(event);
+  }
+
+  @Override
+  public void onFocusChange(@NonNull CanvistHostView view, boolean focused) {
+    LynxCustomEvent event = new LynxCustomEvent(getSign(), "focuschange");
+    event.addDetail("focused", focused);
+    emit(event);
+  }
+
+  @Override
+  public void onError(@NonNull CanvistHostView view, @NonNull String code, @NonNull String message) {
+    LynxCustomEvent event = new LynxCustomEvent(getSign(), "error");
+    event.addDetail("code", code);
+    event.addDetail("message", message);
+    emit(event);
+  }
+
+  private void emit(LynxCustomEvent event) {
+    getLynxContext().getEventEmitter().sendCustomEvent(event);
+  }
+
+  private static String emptyAsNull(String value) {
+    return value == null || value.isEmpty() ? null : value;
+  }
+}

package/android/src/main/kotlin/io/github/ifiokjr/canvist/lynx/CanvistLynxModule.kt

@@ -0,0 +1,109 @@
+package io.github.ifiokjr.canvist.lynx
+
+import android.content.Context
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+import io.github.ifiokjr.canvist.Command
+import io.github.ifiokjr.canvist.Editor
+import io.github.ifiokjr.canvist.HostedEditorException
+import io.github.ifiokjr.canvist.HostedEditors
+import io.github.ifiokjr.canvist.docFormat
+import io.github.ifiokjr.canvist.selectRangeJson
+import io.github.ifiokjr.canvist.selectionJson
+import org.json.JSONObject
+
+/**
+ * The `CanvistEditors` native module: synchronous calls, on the JavaScript
+ * thread, into the editors of `<canvist-editor>` elements. Every method
+ * answers with a JSON envelope, `{"value": ...}` or `{"error": message}`,
+ * because Lynx reports native exceptions to the host rather than to
+ * JavaScript.
+ */
+class CanvistLynxModule(
+    context: Context,
+) : LynxModule(context) {
+    @LynxMethod
+    fun run(
+        editorId: String,
+        name: String,
+        args: String,
+    ): String = reply(editorId) { it.run(Command(name, args)).json() }
+
+    @LynxMethod
+    fun can(
+        editorId: String,
+        name: String,
+        args: String,
+    ): String = reply(editorId) { it.can(Command(name, args)).json() }
+
+    @LynxMethod
+    fun query(
+        editorId: String,
+        name: String,
+        args: String,
+    ): String = reply(editorId) { it.query(name, args) }
+
+    @LynxMethod
+    fun load(
+        editorId: String,
+        format: String,
+        content: String,
+    ): String =
+        reply(editorId) {
+            it.load(docFormat(format), content)
+            "true"
+        }
+
+    @LynxMethod
+    fun exportDocument(
+        editorId: String,
+        format: String,
+    ): String = reply(editorId) { JSONObject.quote(it.export(docFormat(format))) }
+
+    @LynxMethod
+    fun selection(editorId: String): String = reply(editorId) { it.selectionJson() }
+
+    @LynxMethod
+    fun select(
+        editorId: String,
+        range: String,
+    ): String = reply(editorId) { it.selectRangeJson(range).json() }
+
+    @LynxMethod
+    fun selectAll(editorId: String): String = reply(editorId) { it.selectAll().json() }
+
+    @LynxMethod
+    fun insertText(
+        editorId: String,
+        text: String,
+    ): String = reply(editorId) { it.insertText(text).json() }
+
+    @LynxMethod
+    fun undo(editorId: String): String = reply(editorId) { it.undo().json() }
+
+    @LynxMethod
+    fun redo(editorId: String): String = reply(editorId) { it.redo().json() }
+
+    @LynxMethod
+    fun canUndo(editorId: String): String = reply(editorId) { it.canUndo().json() }
+
+    @LynxMethod
+    fun canRedo(editorId: String): String = reply(editorId) { it.canRedo().json() }
+
+    companion object {
+        const val NAME = "CanvistEditors"
+    }
+}
+
+/** The envelope for [body]'s JSON answer on the editor [editorId] names, or for its failure. */
+private fun reply(
+    editorId: String,
+    body: (Editor) -> String,
+): String =
+    try {
+        "{\"value\":${HostedEditors.call(editorId, body)}}"
+    } catch (error: HostedEditorException) {
+        "{\"error\":${JSONObject.quote(error.message)}}"
+    }
+
+private fun Boolean.json() = if (this) "true" else "false"

package/dist/bridge.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The bridge from the typed editor to one `<canvist-editor>`: synchronous
+ * calls through the `CanvistEditors` native module, and focus through the
+ * element's UI methods.
+ *
+ * @module
+ */
+import type { NativeBridge } from "@canvist/headless/native";
+import type { NodesRef } from "@lynx-js/types";
+import type { CanvistEditorsModule } from "./native.ts";
+/**
+ * A bridge to the editor `editorId` names through `module`, focusing the
+ * element `element` returns. Focus calls do nothing once the element is gone.
+ */
+export declare function nativeBridge(module: CanvistEditorsModule, editorId: string, element: () => NodesRef | null): NativeBridge;

package/dist/bridge.js

@@ -0,0 +1,64 @@
+/**
+ * A bridge to the editor `editorId` names through `module`, focusing the
+ * element `element` returns. Focus calls do nothing once the element is gone.
+ */
+export function nativeBridge(module, editorId, element) {
+    const invoke = (method) => {
+        element()?.invoke({ method }).exec();
+    };
+    return {
+        run: (name, args) => boolean(module.run(editorId, name, args)),
+        can: (name, args) => boolean(module.can(editorId, name, args)),
+        query: (name, args) => JSON.stringify(value(module.query(editorId, name, args))),
+        load: (format, content) => {
+            value(module.load(editorId, format, content));
+        },
+        export: (format) => string(module.exportDocument(editorId, format)),
+        selection: () => JSON.stringify(value(module.selection(editorId))),
+        select: (range) => {
+            value(module.select(editorId, range));
+        },
+        selectAll: () => {
+            value(module.selectAll(editorId));
+        },
+        insertText: (text) => boolean(module.insertText(editorId, text)),
+        undo: () => boolean(module.undo(editorId)),
+        redo: () => boolean(module.redo(editorId)),
+        canUndo: () => boolean(module.canUndo(editorId)),
+        canRedo: () => boolean(module.canRedo(editorId)),
+        focus: () => invoke("focus"),
+        blur: () => invoke("blur"),
+    };
+}
+/** The value in `reply`, throwing its error instead when it has one. */
+function value(reply) {
+    const parsed = JSON.parse(reply);
+    if (!isReply(parsed)) {
+        throw new Error(`[canvist:editor] the native module answered ${reply}`);
+    }
+    if ("error" in parsed) {
+        throw new Error(parsed.error);
+    }
+    return parsed.value;
+}
+function boolean(reply) {
+    const answer = value(reply);
+    if (typeof answer !== "boolean") {
+        throw new Error(`[canvist:editor] expected a boolean, not ${reply}`);
+    }
+    return answer;
+}
+function string(reply) {
+    const answer = value(reply);
+    if (typeof answer !== "string") {
+        throw new Error(`[canvist:editor] expected a string, not ${reply}`);
+    }
+    return answer;
+}
+function isReply(reply) {
+    if (typeof reply !== "object" || reply === null) {
+        return false;
+    }
+    return "value" in reply ||
+        ("error" in reply && typeof reply.error === "string");
+}

package/dist/editor.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The editor component and hooks.
+ *
+ * @module
+ */
+import type { CanvistError, Content, StarterKit } from "@canvist/headless";
+import { NativeEditor } from "@canvist/headless/native";
+import { type ReactNode } from "@lynx-js/react";
+import type { StandardProps } from "@lynx-js/types";
+import type { CanvistEditorElementProps } from "./native.ts";
+/** The extensions the native editors compile in: TipTap's StarterKit, or some of it. */
+export type NativeExtensions = readonly StarterKit[number][];
+/**
+ * A native editor whose commands, queries, and documents are typed from
+ * the extensions `E`, with the same API as `@canvist/web`'s editor.
+ */
+export type Editor<E extends NativeExtensions> = NativeEditor<E>;
+/** Options for {@link useCanvistEditor} and {@link CanvistEditor}. */
+export interface EditorOptions<E extends NativeExtensions> {
+    /** The extensions to register: every StarterKit extension by default. Read once. */
+    readonly extensions?: E;
+    /** The document to start with: one empty paragraph by default. Read once. */
+    readonly content?: Content<E>;
+    /** The body text size before the user's text size setting; the platform's body size by default. */
+    readonly textSize?: number;
+    /** Called when the element could not create its editor or load `content`. */
+    readonly onError?: (error: CanvistError) => void;
+}
+/**
+ * Props for {@link CanvistView}: what {@link useCanvistEditor} returns, plus
+ * the element's own, such as `style` and `accessibility-label`.
+ */
+export type CanvistViewProps = CanvistEditorElementProps;
+/** What {@link useCanvistEditor} returns. */
+export interface CanvistEditorHandle<E extends NativeExtensions> {
+    /** The editor, once the element has created it; `null` before that. */
+    readonly editor: Editor<E> | null;
+    /** Spread onto a {@link CanvistView}, alongside its style and accessibility props. */
+    readonly props: CanvistViewProps;
+}
+/** The `<canvist-editor>` element. Give it a size, as it scrolls its own document. */
+export declare function CanvistView(props: CanvistViewProps): ReactNode;
+/**
+ * Create an editor in the {@link CanvistView} you spread `props` onto.
+ * `extensions` and `content` are read when the element is created; later
+ * changes to them have no effect.
+ *
+ * ```tsx
+ * function Notes() {
+ * 	const { editor, props } = useCanvistEditor({ extensions: [bold, heading] });
+ *
+ * 	return (
+ * 		<view>
+ * 			<text bindtap={() => editor?.commands.toggleBold()}>Bold</text>
+ * 			<CanvistView {...props} style={{ flex: 1 }} />
+ * 		</view>
+ * 	);
+ * }
+ * ```
+ */
+export declare function useCanvistEditor<const E extends NativeExtensions = StarterKit>(options?: EditorOptions<E>): CanvistEditorHandle<E>;
+/**
+ * Read `select(editor)` and re-render whenever it changes: after any edit,
+ * selection change, or change of focus. `select` must return a primitive
+ * or a value that stays the same object while nothing changed, as with
+ * `useSyncExternalStore`. Until the editor exists, the value is `fallback`.
+ */
+export declare function useEditorState<E extends NativeExtensions, T>(editor: Editor<E> | null, select: (editor: Editor<E>) => T, fallback: T): T;
+/** Props for {@link CanvistEditor}: the editor's options and the element's. */
+export interface CanvistEditorProps<E extends NativeExtensions> extends EditorOptions<E>, StandardProps {
+    /** Called once the editor is ready. */
+    readonly onReady?: (editor: Editor<E>) => void;
+    /** Called after every change to the document, the selection, or focus. */
+    readonly onUpdate?: (editor: Editor<E>) => void;
+}
+/**
+ * A native canvist editor: the iOS or Android `CanvistView`. Give it a
+ * size, as it scrolls its own document.
+ *
+ * ```tsx
+ * <CanvistEditor
+ * 	content={{ format: "markdown", input: "# Notes" }}
+ * 	onUpdate={(editor) => save(editor.export("markdown"))}
+ * 	style={{ flex: 1 }}
+ * />
+ * ```
+ */
+export declare function CanvistEditor<const E extends NativeExtensions = StarterKit>(props: CanvistEditorProps<E>): ReactNode;

package/dist/editor.jsx

@@ -0,0 +1,145 @@
+import { starterKit } from "@canvist/headless/extensions";
+import { nativeCanvistError, NativeEditor } from "@canvist/headless/native";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "@lynx-js/react";
+import { nativeBridge } from "./bridge.js";
+/** The `<canvist-editor>` element. Give it a size, as it scrolls its own document. */
+export function CanvistView(props) {
+    return <canvist-editor {...props}/>;
+}
+let editors = 0;
+/** A key for one element's editor, unique in this JavaScript runtime. */
+function nextEditorId() {
+    editors += 1;
+    return `canvist-${editors}`;
+}
+/**
+ * Create an editor in the {@link CanvistView} you spread `props` onto.
+ * `extensions` and `content` are read when the element is created; later
+ * changes to them have no effect.
+ *
+ * ```tsx
+ * function Notes() {
+ * 	const { editor, props } = useCanvistEditor({ extensions: [bold, heading] });
+ *
+ * 	return (
+ * 		<view>
+ * 			<text bindtap={() => editor?.commands.toggleBold()}>Bold</text>
+ * 			<CanvistView {...props} style={{ flex: 1 }} />
+ * 		</view>
+ * 	);
+ * }
+ * ```
+ */
+export function useCanvistEditor(options = {}) {
+    const [editorId] = useState(nextEditorId);
+    const [editor, setEditor] = useState(null);
+    const initial = useRef(options);
+    const element = useRef(null);
+    // Events arrive through callbacks made once, so they read the editor here.
+    const current = useRef(null);
+    const onError = useLatest(options.onError);
+    const bindready = useCallback(() => {
+        const module = NativeModules.CanvistEditors;
+        if (module === undefined) {
+            reportError(nativeCanvistError("config", "the CanvistEditors native module is not registered; see @canvist/lynx's setup"), onError.current);
+            return;
+        }
+        // Without extensions, `E` is the default: the whole StarterKit.
+        const extensions = (initial.current.extensions ?? starterKit);
+        const created = new NativeEditor(nativeBridge(module, editorId, () => element.current), extensions);
+        current.current = created;
+        setEditor(created);
+    }, [editorId, onError]);
+    const bindchange = useCallback(() => {
+        current.current?.notifyChange();
+    }, []);
+    const bindfocuschange = useCallback((event) => {
+        current.current?.notifyFocus(event.detail.focused);
+    }, []);
+    const binderror = useCallback((event) => {
+        const { code, message } = event.detail;
+        reportError(nativeCanvistError(code, message), onError.current);
+    }, [onError]);
+    const { textSize } = options;
+    const props = useMemo(() => {
+        const { extensions = starterKit, content } = initial.current;
+        return {
+            ref: element,
+            "editor-id": editorId,
+            extensions: extensions.map((extension) => extension.name),
+            ...documentProps(content),
+            ...(textSize === undefined ? {} : { "text-size": textSize }),
+            bindready,
+            bindchange,
+            bindfocuschange,
+            binderror,
+        };
+    }, [editorId, textSize, bindready, bindchange, bindfocuschange, binderror]);
+    return { editor, props };
+}
+/**
+ * Read `select(editor)` and re-render whenever it changes: after any edit,
+ * selection change, or change of focus. `select` must return a primitive
+ * or a value that stays the same object while nothing changed, as with
+ * `useSyncExternalStore`. Until the editor exists, the value is `fallback`.
+ */
+export function useEditorState(editor, select, fallback) {
+    const subscribe = useCallback((listener) => editor?.subscribe(listener) ?? noop, [editor]);
+    return useSyncExternalStore(subscribe, () => editor === null ? fallback : select(editor), () => fallback);
+}
+/**
+ * A native canvist editor: the iOS or Android `CanvistView`. Give it a
+ * size, as it scrolls its own document.
+ *
+ * ```tsx
+ * <CanvistEditor
+ * 	content={{ format: "markdown", input: "# Notes" }}
+ * 	onUpdate={(editor) => save(editor.export("markdown"))}
+ * 	style={{ flex: 1 }}
+ * />
+ * ```
+ */
+export function CanvistEditor(props) {
+    const { extensions, content, textSize, onError, onReady, onUpdate, ...element } = props;
+    const { editor, props: editorProps } = useCanvistEditor({
+        ...(extensions === undefined ? {} : { extensions }),
+        ...(content === undefined ? {} : { content }),
+        ...(textSize === undefined ? {} : { textSize }),
+        ...(onError === undefined ? {} : { onError }),
+    });
+    const callbacks = useLatest({ onReady, onUpdate });
+    useEffect(() => {
+        if (editor === null) {
+            return;
+        }
+        callbacks.current.onReady?.(editor);
+        return editor.subscribe(() => callbacks.current.onUpdate?.(editor));
+    }, [editor, callbacks]);
+    return <CanvistView {...element} {...editorProps}/>;
+}
+/** The element attributes for the starting document. */
+function documentProps(content) {
+    if (content === undefined) {
+        return {};
+    }
+    return "format" in content
+        ? { "content-format": content.format, content: content.input }
+        : { "content-format": "json", content: JSON.stringify(content) };
+}
+/** A ref that always holds the latest `value`. */
+function useLatest(value) {
+    const ref = useRef(value);
+    useEffect(() => {
+        ref.current = value;
+    });
+    return ref;
+}
+function reportError(error, onError) {
+    if (onError === undefined) {
+        console.error(error);
+    }
+    else {
+        onError(error);
+    }
+}
+function noop() { }

package/dist/mod.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The canvist rich-text editor for Lynx.
+ *
+ * `CanvistEditor` shows the native iOS or Android editor as a
+ * `<canvist-editor>` element: canvist's Rust engine, painted natively and
+ * edited through the platform's own text input. Commands, queries, and
+ * documents are typed from the extensions you register, with the same API
+ * as `@canvist/web` and `@canvist/react-native`: calling a command you did
+ * not register is a type error. Calls are synchronous.
+ *
+ * ```tsx
+ * import { CanvistEditor, bold, heading } from "@canvist/lynx";
+ *
+ * <CanvistEditor
+ * 	extensions={[bold, heading]}
+ * 	content={{ format: "markdown", input: "# Notes" }}
+ * 	onReady={(editor) => editor.commands.toggleHeading({ level: 2 })}
+ * 	style={{ flex: 1 }}
+ * />
+ * ```
+ *
+ * @module
+ */
+export type { CanvistError, CommandName, CommandParams, Commands, Content, DocJson, ErrorCode, ExtensionDescriptor, Extensions, Format, Position, Queries, QueryName, QueryParams, QueryResult, Range, Registered, StarterKit, } from "@canvist/headless";
+export * from "@canvist/headless/extensions";
+export { isCanvistError } from "@canvist/headless/native";
+export { CanvistEditor, type CanvistEditorHandle, type CanvistEditorProps, CanvistView, type CanvistViewProps, type Editor, type EditorOptions, type NativeExtensions, useCanvistEditor, useEditorState, } from "./editor.tsx";
+export type { CanvistEditorElementProps, CanvistEditorsModule, EditorChangeDetail, EditorErrorDetail, EditorFocusDetail, EditorReadyDetail, } from "./native.ts";

package/dist/mod.js

@@ -0,0 +1,3 @@
+export * from "@canvist/headless/extensions";
+export { isCanvistError } from "@canvist/headless/native";
+export { CanvistEditor, CanvistView, useCanvistEditor, useEditorState, } from "./editor.jsx";

package/dist/native.d.ts

@@ -0,0 +1,80 @@
+/**
+ * What the native side of `@canvist/lynx` provides: the `<canvist-editor>`
+ * element and the `CanvistEditors` native module, typed for ReactLynx.
+ *
+ * @module
+ */
+import type { BaseEvent, StandardProps } from "@lynx-js/types";
+/** What changed, after every change to the document or selection. */
+export interface EditorChangeDetail {
+    readonly document: boolean;
+    readonly selection: boolean;
+    readonly composition: boolean;
+}
+/** The element gained or lost focus. */
+export interface EditorFocusDetail {
+    readonly focused: boolean;
+}
+/** The element could not create its editor or load its content. */
+export interface EditorErrorDetail {
+    readonly code: string;
+    readonly message: string;
+}
+/** The element's editor is ready for calls through `CanvistEditors`. */
+export interface EditorReadyDetail {
+    readonly editorId: string;
+}
+/** The attributes and events of `<canvist-editor>`. */
+export interface CanvistEditorElementProps extends StandardProps {
+    /** The key the `CanvistEditors` module finds this element's editor by. */
+    "editor-id": string;
+    /** The extensions to register, by name. Read when the element is created. */
+    extensions: readonly string[];
+    /** The format of `content`. Read when the element is created. */
+    "content-format"?: string;
+    /** The document to start with. Read when the element is created. */
+    content?: string;
+    /** The body text size before the user's text size setting; 0 is the platform's default. */
+    "text-size"?: number;
+    bindready?: (event: BaseEvent<"ready", EditorReadyDetail>) => void;
+    bindchange?: (event: BaseEvent<"change", EditorChangeDetail>) => void;
+    bindfocuschange?: (event: BaseEvent<"focuschange", EditorFocusDetail>) => void;
+    binderror?: (event: BaseEvent<"error", EditorErrorDetail>) => void;
+}
+/**
+ * The `CanvistEditors` native module. Every method is synchronous and
+ * answers with a JSON envelope: `{"value": ...}`, or `{"error": message}`
+ * with `[canvist:<code>] <reason>` in the message, because Lynx reports
+ * native exceptions to the host rather than to JavaScript.
+ */
+export interface CanvistEditorsModule {
+    run(editorId: string, name: string, args: string): string;
+    can(editorId: string, name: string, args: string): string;
+    query(editorId: string, name: string, args: string): string;
+    load(editorId: string, format: string, content: string): string;
+    exportDocument(editorId: string, format: string): string;
+    selection(editorId: string): string;
+    select(editorId: string, range: string): string;
+    selectAll(editorId: string): string;
+    insertText(editorId: string, text: string): string;
+    undo(editorId: string): string;
+    redo(editorId: string): string;
+    canUndo(editorId: string): string;
+    canRedo(editorId: string): string;
+}
+declare module "@lynx-js/types" {
+    interface IntrinsicElements {
+        "canvist-editor": CanvistEditorElementProps;
+    }
+    interface NativeModules {
+        /** Registered by the app with `@canvist/lynx`'s native setup. */
+        CanvistEditors?: CanvistEditorsModule;
+    }
+}
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements {
+            "canvist-editor": CanvistEditorElementProps;
+        }
+    }
+}

package/dist/native.js

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

package/ios/CanvistLynxEditor.h

@@ -0,0 +1,12 @@
+#import <Lynx/LynxUI.h>
+
+#import "CanvistSwift.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// `<canvist-editor>`: a `CanvistHostView` created from the element's first
+/// attributes, sending `ready`, `change`, `focuschange`, and `error` events.
+@interface CanvistLynxEditor : LynxUI <CanvistHostView *>
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/CanvistLynxEditor.m

@@ -0,0 +1,109 @@
+#import "CanvistLynxEditor.h"
+
+#import <Lynx/LynxComponentRegistry.h>
+#import <Lynx/LynxPropsProcessor.h>
+#import <Lynx/LynxUIMethodProcessor.h>
+
+#import "CanvistSwift.h"
+
+@implementation CanvistLynxEditor {
+  NSString *_editorId;
+  NSArray<NSString *> *_extensions;
+  NSString *_contentFormat;
+  NSString *_content;
+}
+
+LYNX_LAZY_REGISTER_UI("canvist-editor")
+
+- (CanvistHostView *)createView
+{
+  CanvistHostView *host = [CanvistHostView new];
+  __weak CanvistLynxEditor *weakSelf = self;
+  host.onReady = ^(NSString *editorId) {
+    [weakSelf emit:@"ready" detail:@{@"editorId" : editorId}];
+  };
+  host.onChange = ^(BOOL document, BOOL selection, BOOL composition) {
+    [weakSelf emit:@"change" detail:@{@"document" : @(document), @"selection" : @(selection), @"composition" : @(composition)}];
+  };
+  host.onFocusChange = ^(BOOL focused) {
+    [weakSelf emit:@"focuschange" detail:@{@"focused" : @(focused)}];
+  };
+  host.onError = ^(NSString *code, NSString *message) {
+    [weakSelf emit:@"error" detail:@{@"code" : code, @"message" : message}];
+  };
+
+  return host;
+}
+
+- (void)dealloc
+{
+  [self.view stop];
+}
+
+LYNX_PROP_SETTER("editor-id", setEditorId, NSString *)
+{
+  _editorId = value;
+}
+
+LYNX_PROP_SETTER("extensions", setExtensions, NSArray *)
+{
+  NSMutableArray<NSString *> *names = [NSMutableArray arrayWithCapacity:value.count];
+  for (id name in value) {
+    if ([name isKindOfClass:NSString.class]) {
+      [names addObject:name];
+    }
+  }
+  _extensions = names;
+}
+
+LYNX_PROP_SETTER("content-format", setContentFormat, NSString *)
+{
+  _contentFormat = value;
+}
+
+LYNX_PROP_SETTER("content", setContent, NSString *)
+{
+  _content = value;
+}
+
+LYNX_PROP_SETTER("text-size", setTextSize, CGFloat)
+{
+  self.view.fontSize = value;
+}
+
+// The editor starts once the first attributes have all arrived; later
+// changes to `extensions` and `content` have no effect, as the JavaScript API
+// documents.
+- (void)propsDidUpdate
+{
+  [super propsDidUpdate];
+
+  if (_editorId.length == 0) {
+    return;
+  }
+
+  [self.view startWithEditorId:_editorId
+                    extensions:_extensions ?: @[]
+                        format:_contentFormat.length > 0 ? _contentFormat : nil
+                       content:_content.length > 0 ? _content : nil];
+}
+
+LYNX_UI_METHOD(focus)
+{
+  [self.view focus];
+  callback(kUIMethodSuccess, nil);
+}
+
+LYNX_UI_METHOD(blur)
+{
+  [self.view blur];
+  callback(kUIMethodSuccess, nil);
+}
+
+- (void)emit:(NSString *)name detail:(NSDictionary *)detail
+{
+  LynxDetailEvent *event = [[LynxDetailEvent alloc] initWithName:name targetSign:[self sign] detail:detail];
+  [self.context.eventEmitter dispatchCustomEvent:event];
+}
+
+@end

package/ios/CanvistLynxModule.h

@@ -0,0 +1,14 @@
+#import <Foundation/Foundation.h>
+#import <Lynx/LynxModule.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The `CanvistEditors` native module: synchronous calls, on the JavaScript
+/// thread, into the editors of `<canvist-editor>` elements. Every method
+/// answers with a JSON envelope, `{"value": ...}` or `{"error": message}`,
+/// because Lynx reports native exceptions to the host rather than to
+/// JavaScript. Register it with `[config registerModule:CanvistLynxModule.class]`.
+@interface CanvistLynxModule : NSObject <LynxModule>
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/CanvistLynxModule.m

@@ -0,0 +1,136 @@
+#import "CanvistLynxModule.h"
+
+#import "CanvistSwift.h"
+
+/// `text` as a JSON string literal.
+static NSString *JSONString(NSString *text)
+{
+  NSData *data = [NSJSONSerialization dataWithJSONObject:text options:NSJSONWritingFragmentsAllowed error:nil];
+  return [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
+}
+
+/// The envelope for `json`, a JSON value, or for `error` when the call failed.
+static NSString *Reply(NSString *_Nullable json, NSError *_Nullable error)
+{
+  if (json == nil) {
+    return [NSString stringWithFormat:@"{\"error\":%@}", JSONString(error.localizedDescription ?: @"[canvist:editor] unknown failure")];
+  }
+
+  return [NSString stringWithFormat:@"{\"value\":%@}", json];
+}
+
+static NSString *_Nullable JSONBool(NSNumber *_Nullable value)
+{
+  return value == nil ? nil : (value.boolValue ? @"true" : @"false");
+}
+
+static NSString *_Nullable JSONText(NSString *_Nullable value)
+{
+  return value == nil ? nil : JSONString(value);
+}
+
+@implementation CanvistLynxModule
+
++ (NSString *)name
+{
+  return @"CanvistEditors";
+}
+
++ (NSDictionary<NSString *, NSString *> *)methodLookup
+{
+  return @{
+    @"run" : NSStringFromSelector(@selector(run:name:args:)),
+    @"can" : NSStringFromSelector(@selector(can:name:args:)),
+    @"query" : NSStringFromSelector(@selector(query:name:args:)),
+    @"load" : NSStringFromSelector(@selector(load:format:content:)),
+    @"exportDocument" : NSStringFromSelector(@selector(exportDocument:format:)),
+    @"selection" : NSStringFromSelector(@selector(selection:)),
+    @"select" : NSStringFromSelector(@selector(select:range:)),
+    @"selectAll" : NSStringFromSelector(@selector(selectAll:)),
+    @"insertText" : NSStringFromSelector(@selector(insertText:text:)),
+    @"undo" : NSStringFromSelector(@selector(undo:)),
+    @"redo" : NSStringFromSelector(@selector(redo:)),
+    @"canUndo" : NSStringFromSelector(@selector(canUndo:)),
+    @"canRedo" : NSStringFromSelector(@selector(canRedo:)),
+  };
+}
+
+- (NSString *)run:(NSString *)editorId name:(NSString *)name args:(NSString *)args
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls runWithId:editorId name:name args:args error:&error]), error);
+}
+
+- (NSString *)can:(NSString *)editorId name:(NSString *)name args:(NSString *)args
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls canWithId:editorId name:name args:args error:&error]), error);
+}
+
+- (NSString *)query:(NSString *)editorId name:(NSString *)name args:(NSString *)args
+{
+  NSError *error = nil;
+  return Reply([CanvistHostCalls queryWithId:editorId name:name args:args error:&error], error);
+}
+
+- (NSString *)load:(NSString *)editorId format:(NSString *)format content:(NSString *)content
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls loadWithId:editorId format:format content:content error:&error]), error);
+}
+
+- (NSString *)exportDocument:(NSString *)editorId format:(NSString *)format
+{
+  NSError *error = nil;
+  return Reply(JSONText([CanvistHostCalls exportWithId:editorId format:format error:&error]), error);
+}
+
+- (NSString *)selection:(NSString *)editorId
+{
+  NSError *error = nil;
+  return Reply([CanvistHostCalls selectionWithId:editorId error:&error], error);
+}
+
+- (NSString *)select:(NSString *)editorId range:(NSString *)range
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls selectWithId:editorId range:range error:&error]), error);
+}
+
+- (NSString *)selectAll:(NSString *)editorId
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls selectAllWithId:editorId error:&error]), error);
+}
+
+- (NSString *)insertText:(NSString *)editorId text:(NSString *)text
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls insertTextWithId:editorId text:text error:&error]), error);
+}
+
+- (NSString *)undo:(NSString *)editorId
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls undoWithId:editorId error:&error]), error);
+}
+
+- (NSString *)redo:(NSString *)editorId
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls redoWithId:editorId error:&error]), error);
+}
+
+- (NSString *)canUndo:(NSString *)editorId
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls canUndoWithId:editorId error:&error]), error);
+}
+
+- (NSString *)canRedo:(NSString *)editorId
+{
+  NSError *error = nil;
+  return Reply(JSONBool([CanvistHostCalls canRedoWithId:editorId error:&error]), error);
+}
+
+@end

package/ios/CanvistSwift.h

@@ -0,0 +1,3 @@
+// The Objective-C face of the `Canvist` pod's Swift: `CanvistHostView` and
+// `CanvistHostCalls`. The podspec puts its directory on the search path.
+#import "Canvist-Swift.h"

package/package.json

@@ -1,6 +1,56 @@
 {
-  "name": "@canvist/lynx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@canvist/lynx",
+	"version": "0.2.0",
+	"description": "The canvist rich-text editor for Lynx: the native iOS and Android editors as a Lynx element, with commands and queries typed from the extensions you register.",
+	"license": "Unlicense",
+	"homepage": "https://github.com/canvist/canvist/tree/main/packages/canvist-lynx#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/canvist/canvist.git",
+		"directory": "packages/canvist-lynx"
+	},
+	"bugs": {
+		"url": "https://github.com/canvist/canvist/issues",
+		"email": "support@canvist.dev"
+	},
+	"keywords": ["lynx", "reactlynx", "rich-text", "editor", "ios", "android"],
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"default": "./dist/mod.js"
+		}
+	},
+	"files": [
+		"dist",
+		"ios",
+		"android/build.gradle",
+		"android/src/main",
+		"CanvistLynx.podspec"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"check:types": "tsc --noEmit",
+		"test": "rstest run",
+		"build": "tsc -p tsconfig.build.json",
+		"prepack": "npm run build"
+	},
+	"dependencies": {
+		"@canvist/headless": "^0.2.0"
+	},
+	"peerDependencies": {
+		"@lynx-js/react": ">=0.120.0",
+		"@lynx-js/types": ">=4.1.0"
+	},
+	"devDependencies": {
+		"@lynx-js/react": "^0.127.0",
+		"@lynx-js/react-rsbuild-plugin": "^0.20.3",
+		"@lynx-js/types": "^4.3.0",
+		"@rstest/core": "^0.12.1",
+		"@testing-library/dom": "^10.4.1",
+		"@testing-library/jest-dom": "^7.0.0",
+		"@types/react": "^19.2.0",
+		"jsdom": "^27.4.0",
+		"typescript": "^7.0.2"
+	}
+}

package/readme.md

@@ -0,0 +1,110 @@
+<p align="center">
+  <a href="https://github.com/canvist/canvist">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup-dark.svg">
+      <img width="220" src="https://raw.githubusercontent.com/canvist/canvist/main/assets/brand/vector/lockup.svg" alt="canvist" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/quick-start/lynx.md"><strong>Quick start</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/readme.md"><strong>Docs</strong></a> ·
+  <a href="https://github.com/canvist/canvist/blob/main/docs/src/reference/contributing.md"><strong>Contributing</strong></a> ·
+  <a href="https://github.com/canvist/canvist"><strong>canvist</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/canvist/canvist/actions/workflows/lynx.yml"><img src="https://github.com/canvist/canvist/actions/workflows/lynx.yml/badge.svg?branch=main" alt="lynx status" /></a>
+  <a href="https://unlicense.org"><img src="https://img.shields.io/badge/license-Unlicense-3B2CF5" alt="Unlicense" /></a>
+</p>
+
+# @canvist/lynx
+
+canvist's rich-text editor for [Lynx](https://lynxjs.org): the native iOS and Android `CanvistView`s as a `<canvist-editor>` element, not a web view. Typing goes through each platform's own text input, and the Rust engine lays out and paints every line. Commands, queries, and documents are typed from the extensions you register, with the same API as [`@canvist/web`](../canvist-web) and [`@canvist/react-native`](../canvist-react-native).
+
+```tsx
+import { CanvistEditor } from "@canvist/lynx";
+
+<CanvistEditor
+	content={{ format: "markdown", input: "# Notes" }}
+	onUpdate={(editor) => save(editor.export("markdown"))}
+	accessibility-label="Note"
+	style={{ flex: 1 }}
+/>;
+```
+
+Needs ReactLynx, Lynx 4.1, iOS 17, and Android 7 (API 24).
+
+## A toolbar that follows the selection
+
+```tsx
+import {
+	bold,
+	CanvistView,
+	heading,
+	useCanvistEditor,
+	useEditorState,
+} from "@canvist/lynx";
+
+function Notes() {
+	const { editor, props } = useCanvistEditor({ extensions: [bold, heading] });
+	const isBold = useEditorState(editor, (e) => e.query.isBold(), false);
+
+	return (
+		<view style={{ flex: 1 }}>
+			{/* `ignore-focus` keeps the keyboard up while you tap the toolbar. */}
+			<view ignore-focus bindtap={() => editor?.commands.toggleBold()}>
+				<text>{isBold ? "Unbold" : "Bold"}</text>
+			</view>
+			<CanvistView {...props} style={{ flex: 1 }} />
+		</view>
+	);
+}
+```
+
+The editor has the same calls as on React Native: `commands`, `can`, `query`, `run`, `ask`, `setContent`, `export`, `toJson`, `selection`, `select`, `insertText`, `undo`, `redo`, `focus`, `blur`, and `subscribe`. They are synchronous, and failures throw a `CanvistError` with a stable `code`.
+
+## Install
+
+The native editors aren't on a package registry yet, so build them from the repository, and register the element and its native module in your host app.
+
+**iOS.** Build the engine with `platforms/apple/build.sh`, add both pods to your Podfile, and register the module on your `LynxConfig`. The element registers itself as `<canvist-editor>`:
+
+```ruby
+pod "Canvist", path: "path/to/canvist/platforms/apple"
+pod "CanvistLynx", path: "path/to/canvist/packages/canvist-lynx"
+```
+
+```swift
+let config = LynxConfig(provider: provider)
+config.register(CanvistLynxModule.self)
+```
+
+**Android.** Publish `canvist-android` to Maven Local with `platforms/android/build.sh` and `./gradlew :canvist:publishToMavenLocal`, include `packages/canvist-lynx/android` as a Gradle project, and register both pieces:
+
+```kotlin
+LynxEnv.inst().init(application, null, null, null)
+CanvistLynx.registerModule()
+
+val lynxView = LynxViewBuilder()
+	.setTemplateProvider(provider)
+	.addBehavior(CanvistLynx.behavior())
+	.build(context)
+```
+
+Lynx knows neither the safe area nor the keyboard, so size your LynxView to fit between them, as [`examples/lynx`](../../examples/lynx) does.
+
+<details>
+<summary><strong>Development</strong></summary>
+
+```sh
+npm test                               # rstest: the typed editor, the element's attributes and events
+npx tsc --noEmit                       # types, including the type-level tests
+../../examples/lynx/e2e/test.sh ios    # the example on a simulator, driven by Maestro
+../../examples/lynx/e2e/test.sh android
+```
+
+The build keeps the JSX (`dist/*.jsx`) for the app's ReactLynx compiler, as Lynx libraries do. The native module answers with a JSON envelope rather than throwing, because Lynx reports native exceptions to the host rather than to JavaScript.
+
+</details>

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.