fix(npm): ship native/*/examples/ + document perry-ffi sibling-checkout (v0.3.1)

Two issues reported against the v0.3.0 npm tarball:

1. native/{macos,ios,windows,linux}/Cargo.toml declare [[example]] blocks
   pointing at examples/demo_editor.rs etc., but examples/ wasn't in the
   tarball — `cargo build` failed with "can't find demo_editor example at
   examples/demo_editor.rs". Fix: add `native/*/examples/**` to `files:`.
   Tarball grew from 121 → 140 files / 265 KB → 347 KB.

2. native/{macos,ios}/Cargo.toml have `perry-ffi = { path =
   "../../../../perry/perry/crates/perry-ffi" }` — a sibling-checkout-only
   path that doesn't survive `npm install`. perry-ffi isn't on crates.io, so
   the real fix requires Perry to publish it (filed PerryTS/perry#1112).
   Until that lands, document the [patch.crates-io] workaround in:
     - native/NATIVE_CRATES.md (new) — full consumer setup guide
     - README "Consuming the native crates from npm" section
     - comment block above the perry-ffi line in each affected Cargo.toml

Web target is unaffected by either — Perry compiles the TS editor itself to
WASM and the renderer is plain TypeScript at native/web/dom-ffi.ts, no Rust
build path at all.

Found by: @honeide/editor consumers using the macOS native crate from a
Perry app after `npm install`.

Author: proggeramlug

README.md

@@ -167,6 +167,23 @@ cargo run --example demo_editor_ios
 
 Launches a fully interactive editor in the iOS Simulator with touch input, soft keyboard, and syntax highlighting.
 
+## Consuming the native crates from npm
+
+The npm tarball ships every native rendering crate's Rust source so consumers
+can build them as part of their Perry-AOT pipeline. Two prerequisites apply
+until upstream Perry work lands — see [`native/NATIVE_CRATES.md`](native/NATIVE_CRATES.md)
+for the full story:
+
+1. `perry-ffi` is currently an unpublished workspace crate inside Perry's
+   monorepo. Either keep a Perry checkout next to your project, or add a
+   `[patch.crates-io]` in your workspace root pointing at it. Tracking issue:
+   [PerryTS/perry#1112](https://github.com/PerryTS/perry/issues/1112).
+2. Each crate's `Cargo.toml` declares `[[example]]` blocks; the `examples/`
+   directory is shipped as of `0.3.1`.
+
+The **web target** doesn't need any of this — it compiles TypeScript → WASM
+via Perry and the renderer is TypeScript, so there's no Rust crate to build.
+
 ## Design Decisions
 
 - **No external editor dependencies** — no CodeMirror, Monaco, or ProseMirror. Fully self-contained.

native/NATIVE_CRATES.md

@@ -0,0 +1,69 @@
+# Building the native crates after `npm install @honeide/editor`
+
+The npm tarball ships the Rust source for every native rendering crate
+(`native/macos/`, `native/ios/`, `native/windows/`, `native/linux/`,
+`native/android/`) so consumers can build them as part of their Perry-AOT
+pipeline. To make those builds resolve, two prerequisites must be in place
+locally — both are Perry-side constraints we hope to remove once Perry ships
+the missing pieces.
+
+## 1. `perry-ffi` must be resolvable to Cargo
+
+The crates' `Cargo.toml` files declare:
+
+```toml
+perry-ffi = { path = "../../../../perry/perry/crates/perry-ffi" }
+```
+
+That relative path resolves in a **sibling-checkout layout**:
+
+```
+~/code/
+├── hone/hone-editor/     ← your fork / clone
+└── perry/perry/          ← Perry monorepo checkout
+```
+
+After `npm install @honeide/editor`, the editor lands at
+`node_modules/@honeide/editor/`, so the `../../../../perry/...` path no longer
+points anywhere useful. You'll see:
+
+```
+error: no matching package found for `perry-ffi`
+```
+
+**Workaround until [PerryTS/perry#1112](https://github.com/PerryTS/perry/issues/1112) lands** (publishing `perry-ffi` to crates.io):
+
+Add a `[patch.crates-io]` to **your workspace's root** `Cargo.toml` pointing
+at a local Perry checkout:
+
+```toml
+[patch.crates-io]
+perry-ffi = { path = "/absolute/path/to/perry-checkout/crates/perry-ffi" }
+```
+
+Or, if you're a Perry user, add a workspace `Cargo.toml` at your project root
+that includes the editor's native crate as a member and uses the same `[patch]`.
+
+Once Perry publishes `perry-ffi` to crates.io, we'll switch this dep to a
+version-based requirement (`perry-ffi = "0.5"`) and this workaround goes away.
+
+## 2. Building the demos requires the `examples/` directory
+
+Each native crate ships its `examples/` folder in the npm tarball as of
+`@honeide/editor@0.3.1+`. You can run them with:
+
+```bash
+cd node_modules/@honeide/editor/native/macos
+cargo run --example demo_editor
+```
+
+(Older `@honeide/editor@0.3.0` was missing `examples/` in the tarball even
+though `Cargo.toml` declared `[[example]]` blocks — that gap is fixed in
+0.3.1.)
+
+## Web doesn't need any of this
+
+The web target compiles the editor TS itself to WASM via Perry. The
+"renderer" on web is plain TypeScript (`native/web/dom-ffi.ts`) — no Rust
+crate, no `perry-ffi`, no Cargo. See [`../examples/web/`](../examples/web/)
+for the build pipeline.

native/ios/Cargo.toml

@@ -18,4 +18,8 @@ objc = "0.2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 libc = "0.2"
+# perry-ffi is currently unpublished; this relative path assumes a sibling
+# Perry checkout. After `npm install @honeide/editor` you'll need a workspace
+# `[patch.crates-io] perry-ffi = { path = "..." }` pointing at your Perry
+# checkout — see native/NATIVE_CRATES.md and PerryTS/perry#1112.
 perry-ffi = { path = "../../../../perry/perry/crates/perry-ffi" }

native/macos/Cargo.toml

@@ -16,6 +16,10 @@ objc = "0.2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 libc = "0.2"
+# perry-ffi is currently unpublished; this relative path assumes a sibling
+# Perry checkout. After `npm install @honeide/editor` you'll need a workspace
+# `[patch.crates-io] perry-ffi = { path = "..." }` pointing at your Perry
+# checkout — see native/NATIVE_CRATES.md and PerryTS/perry#1112.
 perry-ffi = { path = "../../../../perry/perry/crates/perry-ffi" }
 
 # Tree-sitter for TextMate-quality highlighting. Phase 0 PoC validated TS+Python;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@honeide/editor",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "High-performance, cross-platform code editor surface",
   "main": "core/index.ts",
   "types": "core/index.ts",
@@ -13,11 +13,13 @@
     "perry/",
     "view-model/",
     "perry.config.ts",
+    "native/NATIVE_CRATES.md",
     "native/*/src/**",
     "native/*/Cargo.toml",
     "native/*/Cargo.lock",
     "native/*/README.md",
     "native/*/build.rs",
+    "native/*/examples/**",
     "native/web/dom-ffi.ts",
     "native/web/tree-sitter-bridge.ts"
   ],