feat(web): mount() text I/O + per-range diagnostics (gh#1, gh#2) (v0.4.0)

Surface text I/O and precise diagnostics across the FFI to the web mount() controller, and add the shared Editor methods for all platforms.

gh#1: cross-realm WASM<->JS bridge — push buffer text out via hone_editor_set_buffer_text (drives getText/onTextChange); pull setText/setCursor through the editor's poll loop (has_/take_pending_*). Adds getText/setText/onTextChange/setCursor/focus.

gh#2: setRangeDiagnostics/clearRangeDiagnostics — severity-colored squiggles + hover tooltip on web (full, pointer hit-tested), wavy-underline rendering on macOS; link-resolving stubs on ios/windows/linux/android/harmonyos (same status as their line-diagnostics).

+10 FFI functions in the perry.nativeLibrary manifest; 15 new tests in tests/web-controller.test.ts; web bundle rebuild verified.

Author: proggeramlug

CLAUDE.md

@@ -159,11 +159,28 @@ ALL interaction directly by mutating `frame_lines` in place and calling `setNeed
 - Android: ⬜ Canvas/Skia JNI — needs `tokenizer.rs` port + same EditorView patterns
 - Web: ✅ TypeScript DOM renderer at `native/web/dom-ffi.ts`. No Rust crate — Perry's
   web target compiles the editor TS to WASM and imports JS-side `hone_editor_*`. Find
-  highlights / diagnostics / breakpoints / fold ranges render as DOM overlay layers.
-  Syntax highlighting works structurally but token COLORS are blocked on Perry
-  PerryTS/perry#1071 (cross-module nested-object access returns `undefined`). Build:
+  highlights / line diagnostics / per-range diagnostics / breakpoints / fold ranges render
+  as DOM overlay layers. Syntax highlighting works structurally but token COLORS are blocked
+  on Perry PerryTS/perry#1071 (cross-module nested-object access returns `undefined`). Build:
   `bun run examples/web/build.ts` → `examples/web/dist/{hone-editor.wasm, hone-editor.js, index.html}`.
 
+### `mount()` controller bridge (gh#1, gh#2)
+The `mount(el, opts)` controller spans the WASM↔JS realm boundary: the buffer lives in the
+Perry-compiled WASM, the controller in plain JS. Two FFI patterns bridge them, both polled by
+the editor's existing 8ms `setInterval` (which **does** fire on web, unlike macOS):
+- **Push (editor → host):** the Editor calls `hone_editor_set_buffer_text` after every change;
+  dom-ffi stores it (`ed.bufferText`) and fires `onTextChange` listeners. `getText()` reads it.
+- **Pull (host → editor):** `setText`/`setCursor` queue a request on the EditorState; the WASM
+  poll loop drains it via `hone_editor_has_pending_*` / `take_pending_*` (see
+  `Editor.flushEvents`). On **native** the host holds the Editor directly so the `has_*` probes
+  return 0 — these FFIs are link-resolving no-ops in every Rust crate (same status as line
+  diagnostics: only macOS + web render).
+- **Per-range diagnostics** (`setRangeDiagnostics`): squiggle the exact span (severity-colored
+  wavy underline) + a pointer-hit-tested hover tooltip. Implemented on web (`dom-ffi.ts`,
+  full incl. hover) and macOS (`editor_view.rs`, squiggle rendering; native hover is a follow-up).
+  Pure helpers `computeDiagSegments` / `rangeDiagAtPosition` / `severityColor` are unit-tested in
+  `tests/web-controller.test.ts`.
+
 ## Commands
 Run tests: `bun test`
 Run single test file: `bun test tests/buffer.test.ts`
@@ -176,7 +193,7 @@ Build Windows crate: `cd native/windows && cargo build`
 Run Windows interactive demo: `cd native/windows && cargo run --example demo_editor`
 Run iOS interactive demo: `cd native/ios && cargo run --example demo_editor_ios`
 Run Android interactive demo: `cd native/android && bash run-demo.sh`
-Build for web: `bun run examples/web/build.ts` — produces `examples/web/dist/{hone-editor.wasm, hone-editor.js, index.html}`. The build orchestrates: (1) `perry compile examples/web/entry.ts --target web --output hone-editor.wasm` for the raw WASM; (2) a second Perry compile to .html to extract the JS runtime bridge; (3) bundles `native/web/dom-ffi.ts` + the bridge + a `mount()` API into `hone-editor.js`. Consumers: `import { mount } from './hone-editor.js'; await mount(document.getElementById('editor'));`
+Build for web: `bun run examples/web/build.ts` — produces `examples/web/dist/{hone-editor.wasm, hone-editor.js, index.html}`. The build orchestrates: (1) `perry compile examples/web/entry.ts --target web --output hone-editor.wasm` for the raw WASM; (2) a second Perry compile to .html to extract the JS runtime bridge; (3) bundles `native/web/dom-ffi.ts` + the bridge + a `mount()` API into `hone-editor.js`. Consumers: `import { mount } from './hone-editor.js'; const ed = await mount(document.getElementById('editor'));`. The returned controller exposes overlay setters plus `getText()`, `setText(v)`, `onTextChange(cb)`, `setCursor(line,col)`, `focus()` (gh#1) and `setRangeDiagnostics(json)` / `clearRangeDiagnostics()` (gh#2).
 
 ## Development Phases (from PROJECT_PLAN.md)
 

examples/web/README.md

@@ -16,6 +16,41 @@ Produces `examples/web/dist/index.html`. Open it directly in a browser:
 open examples/web/dist/index.html
 ```
 
+## Controller API
+
+`mount(el, opts)` returns a controller:
+
+```js
+import { mount } from './hone-editor.js';
+const ed = await mount(document.getElementById('editor'), {
+  content: 'const x = 1;', language: 'typescript', theme: 'dark',
+});
+
+// Text I/O + change observation (gh#1)
+const src = ed.getText();                 // current buffer text
+ed.setText('// loaded example\n');         // replace all text
+const off = ed.onTextChange((text) => {    // observe edits; returns unsubscribe
+  localStorage.setItem('draft', text);
+});
+ed.setCursor(12, 4);                       // 0-based; scrolls the line into view
+ed.focus();
+
+// Per-range diagnostics: squiggles + hover tooltip (gh#2). 0-based ranges.
+ed.setRangeDiagnostics([
+  { startLine: 4, startCol: 10, endLine: 4, endCol: 20, severity: 1,
+    message: "Type 'string' is not assignable to type 'number'", code: 'ts(2322)' },
+]);
+ed.clearRangeDiagnostics();
+
+// Overlays (existing)
+ed.setFindHighlights('[{"line":2,"col":13,"len":6,"current":1}]');
+ed.setLineDiagnostics('5:2:#cca700:unused variable');
+ed.setBreakpoints('3\n7');
+ed.setFoldRanges('2:1');
+```
+
+`severity`: 1=error, 2=warning, 3=info, 4=hint.
+
 ## What the build does
 
 1. `perry compile perry/editor-component.ts --target web` → a self-contained

examples/web/build.ts

@@ -138,8 +138,22 @@ async function loadWasmAsBase64(url) {
  *     object: explicit URL map, e.g. { typescript: '...', javascript: '...' }.
  *     false / omit: use keyword tokenizer only.
  *
- * Returns a controller object exposing the underlying Editor instance for
- * setting find highlights, diagnostics, breakpoints, etc.
+ * Returns a controller object:
+ *   handle              {number}
+ *   // overlays
+ *   setFindHighlights(json), clearFindHighlights()
+ *   setLineDiagnostics(packed), clearDiagnostics()
+ *   setBreakpoints(packed), setFoldRanges(packed)
+ *   // text I/O + change observation (gh#1)
+ *   getText()                       -> string   current buffer text
+ *   setText(value)                              replace all text (loads examples / permalinks)
+ *   onTextChange(cb)                -> () => void  subscribe to edits; returns unsubscribe
+ *   setCursor(line, column)                     0-based; scrolls the line into view
+ *   focus()                                     give the editor keyboard focus
+ *   // per-range diagnostics: squiggles + hover tooltip (gh#2)
+ *   setRangeDiagnostics(json)                   json (string or array) of
+ *       [{startLine,startCol,endLine,endCol,severity,message,code?}, …] (0-based)
+ *   clearRangeDiagnostics()
  */
 export async function mount(el, opts = {}) {
   if (!el || typeof el.appendChild !== 'function') {
@@ -198,12 +212,23 @@ export async function mount(el, opts = {}) {
   const ffi = ctx.ffi;
   return {
     handle: h,
+    // Overlay setters
     setFindHighlights: (json) => ffi.hone_editor_set_find_highlights(h, json),
     clearFindHighlights: () => ffi.hone_editor_clear_find_highlights(h),
     setLineDiagnostics: (packed) => ffi.hone_editor_set_line_diagnostics(h, packed),
     clearDiagnostics: () => ffi.hone_editor_clear_diagnostics(h),
     setBreakpoints: (packed) => ffi.hone_editor_set_breakpoints(h, packed),
     setFoldRanges: (packed) => ffi.hone_editor_set_fold_ranges(h, packed),
+    // Text I/O + change observation (gh#1)
+    getText: () => ctx.getText(h),
+    setText: (value) => ctx.requestSetText(h, value),
+    onTextChange: (cb) => ctx.onTextChange(h, cb),
+    setCursor: (line, column) => ctx.requestSetCursor(h, line, column),
+    focus: () => ffi.hone_editor_focus(h),
+    // Per-range diagnostics: squiggles + hover tooltip (gh#2)
+    setRangeDiagnostics: (json) =>
+      ffi.hone_editor_set_range_diagnostics(h, typeof json === 'string' ? json : JSON.stringify(json)),
+    clearRangeDiagnostics: () => ffi.hone_editor_clear_range_diagnostics(h),
   };
 }
 `;
@@ -252,8 +277,22 @@ export class Editor {
     });
     // Drive the overlay layers to demonstrate them at runtime.
     ed.setFindHighlights('[{"line":2,"col":13,"len":6,"current":1}]');
-    ed.setLineDiagnostics('5:2:#f87171:cursorLine is implicitly typed as number — declare it\\n13:1:#f87171:Type \\'string\\' is not assignable to parameter of type \\'number\\'');
     ed.setBreakpoints('3\\n7');
+
+    // Per-range diagnostics (gh#2): squiggle the exact span + hover tooltip.
+    ed.setRangeDiagnostics([
+      { startLine: 4, startCol: 10, endLine: 4, endCol: 20, severity: 2,
+        message: 'cursorLine is implicitly typed as number — declare it', code: 'ts(7008)' },
+      { startLine: 12, startCol: 24, endLine: 12, endCol: 28, severity: 1,
+        message: "Argument of type 'string' is not assignable to parameter of type 'number'", code: 'ts(2345)' },
+    ]);
+
+    // Text I/O (gh#1): read the live buffer + observe edits.
+    ed.onTextChange((text) => {
+      console.log('buffer changed — ' + text.length + ' chars');
+    });
+    // e.g. read on demand: const source = ed.getText();
+    // e.g. jump to a diagnostic: ed.setCursor(12, 24); ed.focus();
   </script>
 </body>
 </html>

native/android/src/lib.rs

@@ -997,6 +997,31 @@ pub extern "C" fn hone_editor_clear_diagnostics(_view: *mut EditorView) {}
 pub extern "C" fn hone_editor_set_breakpoints(_view: *mut EditorView, _data: f64) {}
 #[no_mangle]
 pub extern "C" fn hone_editor_set_fold_ranges(_view: *mut EditorView, _data: f64) {}
+
+// === gh#1 host bridge + gh#2 range diagnostics (link-resolving stubs) ===
+// Range-diagnostic squiggles and the host text/cursor bridge are implemented
+// on macOS + web; these exist so Perry apps embedding the editor link cleanly.
+// (Android already stubs line diagnostics above — same status.)
+#[no_mangle]
+pub extern "C" fn hone_editor_set_range_diagnostics(_view: *mut EditorView, _json: i64) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_clear_range_diagnostics(_view: *mut EditorView) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_focus(_view: *mut EditorView) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_set_buffer_text(_view: *mut EditorView, _text: i64) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_has_pending_set_text(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_take_pending_set_text(_view: *mut EditorView) -> i64 { 0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_has_pending_cursor(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_pending_cursor_line(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_pending_cursor_col(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_clear_pending_cursor(_view: *mut EditorView) {}
 /// Set persistent find highlights (NOT cleared by begin_frame).
 #[no_mangle]
 pub extern "C" fn hone_editor_set_find_highlights(view: *mut EditorView, json: *const u8) {

native/harmonyos/src/lib.rs

@@ -464,6 +464,31 @@ pub extern "C" fn hone_editor_set_fold_ranges(_view: *mut EditorView, _packed_da
 #[no_mangle]
 pub extern "C" fn hone_editor_clear_diagnostics(_view: *mut EditorView) {}
 
+// === gh#1 host bridge + gh#2 range diagnostics (link-resolving stubs) ===
+// As with every other symbol in this crate, these exist purely so Perry apps
+// embedding @honeide/editor load on HarmonyOS. Real rendering + the host
+// text/cursor bridge land with the ArkTS-side renderer.
+#[no_mangle]
+pub extern "C" fn hone_editor_set_range_diagnostics(_view: *mut EditorView, _json: *const u8) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_clear_range_diagnostics(_view: *mut EditorView) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_focus(_view: *mut EditorView) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_set_buffer_text(_view: *mut EditorView, _text: *const u8) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_has_pending_set_text(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_take_pending_set_text(_view: *mut EditorView) -> i64 { 0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_has_pending_cursor(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_pending_cursor_line(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_pending_cursor_col(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_clear_pending_cursor(_view: *mut EditorView) {}
+
 #[no_mangle]
 pub extern "C" fn hone_editor_poll_touch(_view: *mut EditorView) -> f64 {
     0.0

native/ios/src/lib.rs

@@ -42,6 +42,31 @@ pub extern "C" fn hone_editor_set_breakpoints(_view: *mut EditorView, _data: f64
 #[no_mangle]
 pub extern "C" fn hone_editor_set_fold_ranges(_view: *mut EditorView, _data: f64) {}
 
+// === gh#1 host bridge + gh#2 range diagnostics (link-resolving stubs) ===
+// Range-diagnostic squiggles and the host text/cursor bridge are implemented
+// on macOS + web; these exist so Perry apps embedding the editor link cleanly.
+// (iOS already stubs line diagnostics above — same status.)
+#[no_mangle]
+pub extern "C" fn hone_editor_set_range_diagnostics(_view: *mut EditorView, _json: i64) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_clear_range_diagnostics(_view: *mut EditorView) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_focus(_view: *mut EditorView) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_set_buffer_text(_view: *mut EditorView, _text: i64) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_has_pending_set_text(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_take_pending_set_text(_view: *mut EditorView) -> i64 { 0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_has_pending_cursor(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_pending_cursor_line(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_pending_cursor_col(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_clear_pending_cursor(_view: *mut EditorView) {}
+
 /// Poll active touch — returns scroll delta Y since last poll.
 /// touchesMoved never fires in Perry's UIView embedding, so TypeScript
 /// polls the saved UITouch's current position via setInterval.

native/linux/src/lib.rs

@@ -637,6 +637,31 @@ pub extern "C" fn hone_editor_set_fold_ranges(
     // Stub — fold indicators not yet implemented on Linux
 }
 
+// === gh#1 host bridge + gh#2 range diagnostics (link-resolving stubs) ===
+// Range-diagnostic squiggles and the host text/cursor bridge are implemented
+// on macOS + web; these exist so Perry apps embedding the editor link cleanly.
+// (Linux already stubs line diagnostics above — same status.)
+#[no_mangle]
+pub extern "C" fn hone_editor_set_range_diagnostics(_view: *mut EditorView, _json: i64) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_clear_range_diagnostics(_view: *mut EditorView) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_focus(_view: *mut EditorView) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_set_buffer_text(_view: *mut EditorView, _text: i64) {}
+#[no_mangle]
+pub extern "C" fn hone_editor_has_pending_set_text(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_take_pending_set_text(_view: *mut EditorView) -> i64 { 0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_has_pending_cursor(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_pending_cursor_line(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_pending_cursor_col(_view: *mut EditorView) -> f64 { 0.0 }
+#[no_mangle]
+pub extern "C" fn hone_editor_clear_pending_cursor(_view: *mut EditorView) {}
+
 /// Copy text to clipboard (called by TypeScript).
 /// Perry params: ["i64", "i64"]
 #[no_mangle]