Repository navigation
docs(bare): add reference pages for the Swift, Kotlin and Python host packages - #450
Merged
Merged
Conversation
…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>
Preview deployments for pear-docs published ⚡️
Commit: Deployment ID: Static site name: |
Preview deployments for pear-docs preview ⚡️
Commit: Deployment ID: Static site name: |
… 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
force-pushed
the
docs/native-bindings-refs
branch
from
November 12, 2026 16:40
3d45327 to
4543cba
Compare
lucas-tortora
changed the base branch from
published
to
docs/bare-kit-3-migration
November 12, 2026 16:40
…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>
- 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>
lucas-tortora
marked this pull request as ready for review
November 13, 2026 14:53
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdxandbare-stow.mdx.The pages are split by language, because a native developer works in one language and uses these packages together:
/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/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/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.0Each 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:
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 inscripts/bare-refgen/layouts/bare-stow.patches.json, sogen:bare-refs -- --only bare-stow --pinned --writereproduces 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:
mainof its dependencies.Not run: Android, iOS, Linux, Windows, Python 3.10–3.12.
Compatibility facts the pages state
UNKNOWN_MESSAGEwhen 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.Package.swiftdeclares 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_ERRORfor request/response,DECODE_ERRORfor 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 withexact:.framed: false, or a schema created before 1.25.0, for the encodings to match.versionwhen it decodes a versioned type.Upstream issues found (not filed; this repo is pull-only)
For maintainers to raise upstream if they want:
_OutgoingStream.destroyawaits a call that bare-rpc ≥ 0.2 made synchronous, so it raisesTypeErrorafter sending. The fix is onmainbut unreleased.Nonemakes the client fail to decode.kill=lambda: sidecar.kill(signal.SIGKILL)raisesTypeError, and it never callsipc.exited().hyperschema, soschema.pycomes out as JavaScript.async forexamples never end.wait()fails after a crash, but it returnsnull.Test plan
npm run types:checknpm run build(runspostbuild)npm run check:internal-links,check:cross-links,check:doctypes,check:bare-refs,check:agent-ready,check:redirectsnpm run gen:bare-refs -- --only bare-stow --pinned --writereproducesbare-stow.mdx(onlygeneratedAtchanges)vale --minAlertLevel=erroron the new pagesFollow-ups
published. docs(bare): add a Bare Kit 3 migration guide and document Bare 1.37 and Bare Kit 3.1.0 #451 lands as one squash commit, so the rebase collapses it. Expect a conflict inscripts/bare-refgen/layouts/bare-stow.patches.json: keeppublished's version, re-add the Protocol patch, and rerungen:bare-refs -- --only bare-stow --pinned --write.scripts/upstream-commits.jsonso drift scans catch new releases. Today the resolver watches one file per npm module.🤖 Generated with Claude Code