Skip to content

docs(bare): add reference pages for the Swift, Kotlin and Python host packages - #450

Merged
lucas-tortora merged 14 commits into
publishedfrom
docs/native-bindings-refs
Nov 13, 2026
Merged

lucas-tortora merged 14 commits into
publishedfrom
docs/native-bindings-refs

Conversation

@lucas-tortora

@lucas-tortora lucas-tortora commented Nov 12, 2026 •

Copy link
Copy Markdown

Stacked on #451 (Bare Kit 3 migration). The base is docs/bare-kit-3-migration, so the diff shows only this PR's work. Merge #451 first; this PR then needs a rebase onto published before it merges. #451's review fixes are merged in (17c5626), because both PRs change bare-stow.patches.json.

Summary

Adds API reference pages for the Bare ecosystem's non-JavaScript host packages. These are the Swift, Kotlin and Python libraries that let a native host run Bare and talk to it. Until now they had only a few lines across bare-kit.mdx and bare-stow.mdx.

The pages are split by language, because a native developer works in one language and uses these packages together:

  • Swift packages (/bare/reference/bare/native-hosts/swift): bare-sidecar-swift 0.1.3, bare-stow-host-swift 0.2.1, bare-rpc-swift 3.0.0, compact-encoding-swift 1.0.1, hyperschema-swift 1.0.1, hrpc-swift 1.0.0
  • Kotlin packages (/bare/reference/bare/native-hosts/kotlin): bare-stow-host-kotlin 0.2.2, bare-rpc-kotlin 0.6.0, compact-encoding-kotlin 0.3.0
  • Python packages (/bare/reference/bare/native-hosts/python): bare-sidecar 0.1.3, bare-stow-host 0.2.1, bare-rpc 0.3.0, compact-encoding 0.1.1, hrpc-python 0.1.1, hyperschema-python 0.1.0

Each package section covers the install line, supported platforms, a minimal usage example, and every public type and member. The pages are reference only, with no per-symbol source links. There is no Kotlin sidecar and no Kotlin HRPC or Hyperschema generator, so none is documented. bare-kit-swift, bare-kit-kotlin and bare-kit-python stay in bare-kit.mdx; the Bare Kit 3 migration branch covers them.

Nav: a new "Native host packages" folder under Reference > Bare, after Bare Kit. The modules index gets a table of the 15 packages in "Native development kits", linking to the page anchors. Before this PR, none of these repos was listed there.

Links from the pages #451 changes:

  • The Python page links bare-kit#python (added by docs(bare): add a Bare Kit 3 migration guide and document Bare 1.37 and Bare Kit 3.1.0 #451) for running Bare in a worklet instead of a sidecar.
  • bare-stow.mdx's Protocol section now links the stow-host bullets to these pages instead of the raw GitHub repos. This is a layout patch in scripts/bare-refgen/layouts/bare-stow.patches.json, so gen:bare-refs -- --only bare-stow --pinned --write reproduces the page.

How it was verified

Each page is documented against the latest published release (PyPI, npm, SwiftPM tags, JitPack) and checked by running code on macOS arm64:

  • Test suites: each package's own suite was run against the published version. All pass except hrpc-swift 1.0.0, whose Swift-building tests target main of its dependencies.
  • Examples: the usage examples on the pages were run, or compiled where a run needs a bundle.
  • bare-stow end to end: a bundle was stowed with bare-stow 0.3.7 and booted from the generated harness. On the JVM it ran in a real bare-kit-kotlin worklet with bare-stow-host-kotlin and bare-rpc-kotlin. In Python it ran through bare-sidecar and bare-stow-host. Request/reply worked, a timeout cancel against JS bare-rpc 2.0.0 left the session usable, and terminate returned exit code 0.
  • Swift: bare-rpc-swift was run over a sidecar against JS bare-rpc 2.0.0, and bare-stow-host-swift with a real worker in a sidecar.
  • Code generators: hyperschema-swift and hyperschema-python output was compared byte for byte with JS hyperschema 1.26.2; the mismatches are listed on the pages.

Not run: Android, iOS, Linux, Windows, Python 3.10–3.12.

Compatibility facts the pages state

  • Cancellation: bare-rpc-swift 3.0.0, bare-rpc-kotlin 0.6.0 and bare-rpc 0.3.0 (Python) send a CANCEL message (type 4), as JS bare-rpc 2.0.0 does. A JS peer on bare-rpc 1.x fails its session with UNKNOWN_MESSAGE when it receives one. Everything else interoperates with 1.x. JS hrpc 4.3.1 still depends on bare-rpc ^1.1.0, so cancelling a call to a JS HRPC server ends the session.
  • hrpc-swift 1.0.0 generates code for the bare-rpc-swift 1.x delegate API, which bare-rpc-swift 2.0.0 replaced. Its generated Package.swift declares macOS 11, but its dependencies and the generated Schema package need macOS 13, so raise it in every case. With bare-rpc-swift 1.1.x, calls without arguments fail: HANDLER_ERROR for request/response, DECODE_ERROR for streamed responses, and send commands never reach their handler. The working pair, tested with every command shape, is bare-rpc-swift 1.0.1 with compact-encoding-swift 1.0.0, both pinned with exact:.
  • hyperschema-swift / hyperschema-python:
    • Versioned types registered on hyperschema ≥ 1.25.0 are framed in JS but not in the generated code. Use framed: false, or a schema created before 1.25.0, for the encodings to match.
    • Inline fields (Python), constant fields, and bool arrays don't match the JS encoding. Bool arrays are lost silently in Python and as optional fields in Swift, and a required bool array generates Swift that doesn't compile.
    • Compact structs with 9 or more flags encode their flags differently in Swift.
    • hyperschema-python drops version when it decodes a versioned type.

Upstream issues found (not filed; this repo is pull-only)

For maintainers to raise upstream if they want:

  • hrpc-python 0.1.1: the generated _OutgoingStream.destroy awaits a call that bare-rpc ≥ 0.2 made synchronous, so it raises TypeError after sending. The fix is on main but unreleased.
  • hrpc-python 0.1.1, unary commands: a command without a handler never gets a reply, and a handler that returns None makes the client fail to decode.
  • README fixes:
    • bare-stow-host-python: the example's kill=lambda: sidecar.kill(signal.SIGKILL) raises TypeError, and it never calls ipc.exited().
    • hyperschema-python: the example builds the schema with base hyperschema, so schema.py comes out as JavaScript.
    • bare-sidecar (Swift and Python): the async for examples never end.
    • compact-encoding-swift: calls the sized integers varints, but they're fixed-width.
    • bare-stow-host-kotlin: says wait() fails after a crash, but it returns null.
  • Python client vs JS hrpc 4.3.1: a duplex call hung, because the JS side never sent the end of the response stream. Plain bare-rpc duplex works both ways. Root cause not confirmed, so the pages don't mention it.

Test plan

  • npm run types:check
  • npm run build (runs postbuild)
  • npm run check:internal-links, check:cross-links, check:doctypes, check:bare-refs, check:agent-ready, check:redirects
  • npm run gen:bare-refs -- --only bare-stow --pinned --write reproduces bare-stow.mdx (only generatedAt changes)
  • vale --minAlertLevel=error on the new pages

Follow-ups

🤖 Generated with Claude Code

lucas-tortora and others added 5 commits November 12, 2026 11:14
…ferences

Runtime reference: the freertos and watchos platforms and the riscv32,
armv8m and arm64-32 architectures (with Since badges and the target.h
macros), V8 15.7 with the DrumBrake WebAssembly interpreter, the iOS
extended virtual addressing entitlement, the dropped-transition fix, and
bare-host-parser for addon conditions. The doc-states are regenerated:
1.37.0 and 1.37.1 enter the window and push out 1.31.0 and 1.28.2, so the
1.31/1.32 markers on Addon and Thread become prose.

WebAssembly on iOS: bare-wasm, the WebAssembly addons explanation and the
sandboxed-addon how-to no longer say WebAssembly is unavailable on iOS.

Module references: bare-rpc 2.0.0 (cancellation, with a "Changes in
v2.0.0" section), bare-addon-resolve 1.12.0, bare-pack 3.1.0, bare-realm
2.1.1, bare-type 1.6.0, bare-module 7.5.2, bare-module-traverse 2.7.6,
bare-logger 2.0.6, bare-stow 0.3.7, bare-sidecar 0.5.16, bare-tls 3.2.1,
bare-system-logger 1.0.7, bare-wasm-abi 0.1.2, and pin bumps for bare-dns,
bare-make, bare-path and bare-wasi. Prose lives in the refgen layouts, so a
--pinned regeneration leaves every page byte-identical.

Release overview: Bare v1.37.0, v1.37.1, Bare Kit 3.1.0 and the module
updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…thon

bare-kit-swift 2.3.0, bare-kit-kotlin 0.2.3 and bare-kit-python 0.2.1
build Bare Kit 3.1.0, which embeds Bare 1.37.1. Adds a Python section
written from src/bare_kit/worklet.py, an iOS entitlement section for the
extended virtual addressing entitlement that Bare 1.37 needs on devices,
and a table of which Bare each Bare Kit release embeds. The Swift and
Python examples were run on macOS against an echo bundle.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Walks a React Native or native app from Bare Kit 2 and
react-native-bare-kit 0.16 to Bare Kit 3: linking Bare Kit with
bare-stow, Bare.IPC instead of the BareKit global, resources instead of
the assets option, porting to the Swift, Kotlin or Python bindings, the
iOS entitlement, and WebAssembly on iOS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The React Native, suspension and RPC bridge how-tos used the BareKit
global, which Bare Kit 3 removed, and linked addons with bare-link, which
react-native-bare-kit 0.17 no longer builds into the app. They now use
Bare.IPC and bare-stow link. The RPC bridge's streaming snippet never sent
its request; it now calls req.send() and notes that bare-rpc 2.0
cancellation needs a cancel-aware peer. The Bluetooth setup guide notes
that its link script is for react-native-bare-kit 0.16.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Migration guide: bare-stow lays out worklet assets under the name
  bare-stow and starts bare-stow.bundle with the source inline, so the
  assets step now packs with bare-stow instead of starting 'app.bundle'.
  The Swift and Kotlin snippets close the IPC before wait(), which
  otherwise never returns.
- WebAssembly on iOS: the fallback to an addon's .wasm build happens only
  when wasi-wasm32 is among the resolved hosts, which the bare-pack mobile
  presets and the bare-stow bare-kit/react-native targets leave out; the
  x64 iOS simulator's V8 build leaves WebAssembly out; the WebAssembly
  global was missing before 1.37, not throwing.
- bare-stow 0.3.2 to 0.3.6 wrote `from: "2.2.0"` for bare-kit-swift, so a
  package update alone brings an app onto Bare Kit 3.1.0 and the iOS
  entitlement requirement.
- Release overview: the bindings shipped on 2026-11-12, and bare-stow
  0.3.3 exported link() and resources from its type declarations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kinsta

kinsta Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Preview deployments for pear-docs published ⚡️

Status Branch preview Commit preview
✅ Ready Visit preview Visit preview

Commit: 5bee2360b0efea1775b3a0bd4ad354908a61879d

Deployment ID: a4f852c8-6419-4459-a4a2-13fcdb264766

Static site name: pear-docs-published-i1yp5

@kinsta

kinsta Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Preview deployments for pear-docs preview ⚡️

Status Branch preview Commit preview
✅ Ready Visit preview Visit preview

Commit: 5bee2360b0efea1775b3a0bd4ad354908a61879d

Deployment ID: 53dfa2b2-8716-4e65-8412-8443a81eb66b

Static site name: pear-docs-preview-iimt7

lucas-tortora and others added 2 commits November 12, 2026 13:37
… packages

Document the 15 non-JavaScript packages that let a native host run Bare and
talk to it, one page per language under Reference > Bare > Native host
packages:

- Swift: bare-sidecar-swift 0.1.3, bare-stow-host-swift 0.2.1,
  bare-rpc-swift 3.0.0, compact-encoding-swift 1.0.1, hyperschema-swift
  1.0.1, hrpc-swift 1.0.0
- Kotlin: bare-stow-host-kotlin 0.2.2, bare-rpc-kotlin 0.6.0,
  compact-encoding-kotlin 0.3.0
- Python: bare-sidecar 0.1.3, bare-stow-host 0.2.1, bare-rpc 0.3.0,
  compact-encoding 0.1.1, hrpc-python 0.1.1, hyperschema-python 0.1.0

Each section covers install, platforms, a minimal example and every public
type and member, written from the source at the latest release. The
examples and behavior were verified by running the packages on macOS,
including a bare-stow bundle booted through the generated Kotlin (JVM
worklet) and Python (sidecar) harnesses against JS bare-rpc 2.0.0.

The pages state the cross-version facts readers trip over: cancellation
needs JS bare-rpc 2.0.0, hrpc-swift 1.0.0 output targets the bare-rpc-swift
1.x delegate API, and versioned Hyperschema types framed by hyperschema
1.25+ don't match the generated Swift and Python codecs.

The modules index lists the 15 packages under Native development kits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Python page now links bare-kit#python for running Bare in a worklet
instead of a sidecar. The Protocol section of bare-stow points its
stow-host bullets at the native host package pages instead of the raw
GitHub repositories, through a layout patch so regenerating the page
keeps the links.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lucas-tortora and others added 3 commits November 12, 2026 14:45
…e pages

An adversarial review against the released sources found these problems,
each re-checked against the code before changing the page.

Swift:
- The hrpc-swift JS example called schema.namespace('chat') twice, which
  throws "Namespace already exists". It now creates the namespace once.
- The list of mismatches with JS Hyperschema now covers compact-struct
  flags (fixed-width in JS, a uint in Swift), bool arrays (an optional one
  becomes a single flag, a required one doesn't compile), and decoding data
  written before optional fields were added. Versioned framing applies only
  to versions that aren't compact structs.
- hrpc-swift: the generated package needs macOS 13 / iOS 15 in every case,
  because the Schema package does. Empty payloads also break send
  commands. The error table adds STREAM_ERROR and PROTOCOL_ERROR.
- WORKER_CLOSED: a transport that ends before ready is a crash, reported
  as WORKER_EXITED or WORKER_KILLED. ready() is documented to match.
- spawn() can throw a POSIXError while creating the IPC socket, and a
  failed transport write fails an RPC session.

Python:
- hyperschema-python loses bool arrays without an error, and drops
  `version` when it decodes a versioned type (the `map` of a version isn't
  applied either). Constant fields aren't supported, and the page says how
  they break.
- The supported primitives are now listed explicitly. int8/16/32/64 aren't
  ported, but int24 to int56 are. `json` shadows a module, not a builtin.
- WORKER_CLOSED, ready, read() and write() match the released IPC. A
  Sidecar drops writes instead of raising.
- Leaving `async with RPC(...)` ends the worker. A cancelled caller gets
  asyncio.CancelledError. The generated schema.py and hrpc.py share names
  with PyPI packages. The harness example closes the sidecar after exited().

Kotlin:
- FrameDecoder doesn't validate the length, so it can throw, hang or lose
  sync rather than always throwing.
- write() and TRANSPORT_ERROR: WORKER_CLOSED once terminating or exited.
  The WORKER_CLOSED and ready() rows match the crash handling, as in Swift.
- Rpc.close() returns at once from a streamed body too. Messages.encode
  skips more data than listed. DecodingException has a public constructor.
- The stow example closes the transport and worklet, as the bare-stow
  harness does. The maintainer note names bare-kit-kotlin v0.2.3.

Modules index: only the sidecar packages start Bare. The worklet bindings
are pointed to in the Bare Kit reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… 3 pages

Migration guide and React Native how-to:
- Install bare-stow-runtime. The code bare-stow wraps around each entry
  imports it, so `bare-stow link` fails with MODULE_NOT_FOUND without it.
- The `pack --target react-native` path needs bare-stow-target-react-native,
  the generated package as an app dependency, and an entry that takes its
  stream as an argument rather than using Bare.IPC.
- Android needs JitPack among the repositories, Kotlin 2.4 or later and
  minSdk 29.
- bare-stow 0.2.0 through 0.3.6, not 0.3.2 through 0.3.6, wrote a `from:`
  requirement for bare-kit-swift that now resolves to 2.3.0.
- Note the shared V8 heap reservation, say "the same API" rather than
  "the same stream", make the bare-stow folder conditional, add
  troubleshooting rows, and fix the react-native-bare-kit version name.

Bare Kit reference: give binding version ranges in the Bundled Bare version
table, list the exact bare-kit-kotlin pin of each bare-stow release, and say
the app still needs JitPack.

Bare 1.37:
- Document pointer compression on all 64-bit targets, which makes every
  heap in a process share one reservation of about 4 GiB.
- The dynamic import() wasi bug was in libjs, which kept only the first
  import attribute, and Bare 1.37.0 fixed it. Correct bare-module, the
  sandboxed-addon how-to and the release overview.
- Add the new and removed ABI exports, align the transition no-op wording
  with the runtime page, and qualify the WebAssembly callout.

Module references (layouts, regenerated with --pinned):
- bare-rpc: onrequest defaults to an empty CommandRouter that answers
  UNKNOWN_COMMAND, not a no-op; RPCIncomingRequest.reply sends nothing once
  cancelled; opts takes AbortController from v2.0.0.
- bare-stow: a JavaScript harness also moved to bare-rpc 2.x, and v0.3.7
  links bare-kit-swift from 2.3.0 and bare-kit-kotlin v0.2.+.
- bare-system-logger: fatal() ends the process.
- Release overview: bare-module-traverse parses every host with
  bare-host-parser, and bare-sidecar 0.5.16 adds two builtin addons.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in the review fixes from #451. Both branches change bare-stow.patches.json; the merge keeps #451's patches, adds the Protocol link patch, and regenerates bare-stow with --pinned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lucas-tortora and others added 3 commits November 12, 2026 14:55
- Migration guide: trim the WebAssembly step to what a migrating app has to
  check, and leave the explanation to the WebAssembly addons page. Note that
  Bare Kit 3 no longer builds in bare-crypto, bare-os, bare-pipe and
  bare-ipc, so a worklet that uses them must link them. Drop "now" from the
  open-IPC sentence, because a Bare Kit 2 IPC kept the worklet alive too.
- bare-path: path.resolve() reads a working directory of any length from
  v3.1.3. Before, one of 4,096 bytes or more threw ENOBUFS. Added as a layout
  patch and regenerated with --pinned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Bare Kit 3 guide, the Bare Kit reference, the RPC explanation, the
native RPC bridge how-to and the HRPC helper page linked bare-sidecar-swift,
bare-sidecar-python and hrpc-swift to their GitHub repos, and named the
bare-rpc ports without links. They now point at the Swift, Kotlin and
Python reference pages. The modules index keeps its repo links, because each
row already has a reference link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Base automatically changed from docs/bare-kit-3-migration to published November 13, 2026 14:53
@lucas-tortora
lucas-tortora marked this pull request as ready for review November 13, 2026 14:53
published now carries #451 as a squash whose files match the #451 head
this branch already merged, plus #439 and #449. Merged with the #451 head
as the base, so this branch's changes and theirs touch no common file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lucas-tortora
lucas-tortora merged commit 689f718 into published Nov 13, 2026
11 checks passed
@lucas-tortora
lucas-tortora deleted the docs/native-bindings-refs branch November 13, 2026 15:12

This branch was successfully deployed

1 active deployment
preview — 5bee2360 Deployed Nov 13, 2026 by kinsta[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant