Bitfield Docs

Runtime Kit is the public plug between your app and Bitfield. Your app reads named data, sends target requests, and stays out of the setup work that makes packages, storage, and runnable slots work.

What this is

Runtime Kit lets a product use Bitfield without turning every screen, feature, and package into one tangled codebase.Start with the product moment:

A screen wants data.
A user clicks a button.
A package owns the data and the work.
Runtime Kit keeps the screen from importing package setup.

The public JavaScript surface is intentionally small:

import { sendRequestToBitfieldTarget } from '@bitfield/runtime-kit';
import { useBitfieldData } from '@bitfield/runtime-kit/react';

That small surface is not a small system. It is the stable app-facing edge of a larger Runtime Kit flow:

package file
  -> package material admitted by Runtime Kit
  -> named data or callable target
  -> app code reads or sends a request

React is one surface in that flow. It is not the whole Runtime Kit.If you want the full concept chain first, read Runtime Kit concept map. If you want the full build path first, read Package to screen. It walks through the first complete Runtime Kit feature: package folder, boundary file, package admission, named data read, target request, React surface, verification, and failure checks.

Choose your path

Runtime Kit has several reader paths. Pick the one that matches your job.

If you need to…	Start here	Why
Understand how all Runtime Kit concepts fit together.	Runtime Kit concept map	It connects package files, named data reads, callable targets, local state, and placeable surfaces.
Build the first complete feature.	Package to screen	It gives the whole chain in order.
Understand the public model.	This page, then Placeable surfaces	It explains package/app separation and generic UI placement.
Avoid accidental Bitfield request bytes on public pages.	Use Runtime Kit where it should run	It explains when to keep a page static and when opening the page sends Bitfield request bytes.
Look up exact API shapes.	Runtime Kit API and Package file	Reference pages are for exact contracts.
Debug a broken feature.	Troubleshooting	It maps symptoms to the failed public link.
Keep generated changes inside the public files and names.	Build with AI agents	Use this only when an AI agent is writing the feature.

The first feature shape

Most Runtime Kit features start as the same four-part slice:

Part	Product question	Public Runtime Kit answer
Package file	What does this feature bring?	`things-to-store-and-run.json` declares records, stored bytes, or slots.
Named data read	What does the screen need to show?	`useBitfieldData(...)` reads a prepared input name.
Target request	What work can the user ask for?	`sendRequestToBitfieldTarget(...)` calls a named target.
Surface state	What does the user see while this happens?	The app renders loading, error, empty, success, and request result states.

That slice can power a welcome panel, a search box, a settings screen, a local game menu, a support assistant, or a dashboard card. The feature changes. The boundary shape stays steady.

The mental model

Think of Runtime Kit as the plug board for your product.Your package says what it brings: data to store, bytes it owns, or callable slots. Bitfield admits that package into local state. Runtime Kit prepares the app-facing view. Your app then does one of two jobs: read data that is already prepared for it, or ask a named target to do work.The important part is what your app does not do. It does not open storage files. It does not choose data plumbing. It does not parse package files. It does not import or call the callable target implementation. That is the point. Your feature code stays calm while Runtime Kit can get faster, more flexible, and more replaceable.The fastest way to ruin the architecture is to let the first feature bypass the public API. If the first screen imports a package file directly, the second screen will copy that direct import, the third screen will add another direct import, and by month six the product has a maze instead of an architecture.

How it works technically

Runtime Kit separates four public roles:

Role	What it owns	Public file or call
Package author	Declares records, stored bytes, and callable slots.	`things-to-store-and-run.json`
Runtime Kit	Admits package material and prepares app-facing reads or targets.	Runtime Kit setup outside the public app surface
App surface	Reads named data and sends target requests.	`useBitfieldData(...)`, `sendRequestToBitfieldTarget(...)`
Bitfield account/device	Controls whether this device can use the product.	Account portal and local activation state

The public app call chain looks like this:

React component
  -> useBitfieldData(...)
  -> named data chosen by Runtime Kit
  -> { data, loading, error }

button or user action
  -> sendRequestToBitfieldTarget({ target, payload })
  -> target receives bytes
  -> reply bytes return to app code

The public package chain looks like this:

package folder
  -> things-to-store-and-run.json
  -> record, stored_bytes, or slot declarations
  -> Runtime Kit admits the package
  -> app code sees stable reads and targets

What app code should own

App code should own names and product behavior:

Which named data a component wants.
Which target a button or action calls.
How to render loading, empty, error, and success states.
How to decode reply bytes when the target returns JSON, text, or another public format.

App code should not own Runtime Kit setup:

No direct package parsing.
No hand-built storage addresses.
No low-level data wiring choices.
No unpublished Runtime Kit deep imports.
No private implementation wiring.

Before / after

Before Runtime Kit	With Runtime Kit
Features import each other because it is the fastest way to ship today.	Features talk through package data and named targets.
A React component imports storage and package details.	A React component reads `{ data, loading, error }`.
Replacing a feature means tracing imports across the app.	Replacing a package keeps the public data shape or target name stable.
Fast feature work tangles new features into old ones.	The public surface is smaller and the boundaries are clearer.

The two app-facing calls

`useBitfieldData(...)`

Use this when a component needs named data.

const welcome = useBitfieldData<{ headline: string; body: string }>('welcome');

The hook returns:

{
  data: T | null;
  loading: boolean;
  error: Error | null;
}

Read the focused guide: Read data in React.

`sendRequestToBitfieldTarget(...)`

Use this when app code needs a named target to do work.

const reply = await sendRequestToBitfieldTarget({
  target: 'product.search',
  payload: { query: 'blue jacket' },
});

The reply is bytes. Decode it according to the action reply shape your package exposes.Read the focused guide: Send a request.

Runtime Kit is not React-only

React is the first documented app surface because a lot of products start there. Runtime Kit is broader than that.

Runtime Kit area	Why it matters
Package file	Lets a package declare what it stores and runs.
Package sets	Lets one product or project hold a named collection of packages.
Stored bytes	Lets a package bring owned files without reaching outside itself.
Callable slots	Lets a package expose a named target your app can ask for work.
Local state	Keeps customer-visible Bitfield state on the device.
App surfaces	Lets React, and later other SDKs, read and request without importing private setup.

The public invariant is the same outside React:

surface asks for named data
surface sends a named target request
package owns the data and implementation for those public names

React gives you useBitfieldData(...) today. The Runtime Kit idea is bigger than one UI framework.

Terms to keep straight

Term	Plain meaning	Common mistake
Package set	A named collection of packages for a product or project.	Treating one package folder like the whole product.
Package	A unit that brings declared data, bytes, or callable slots.	Letting app code import package implementation files.
Boundary file	The public file that says what the package brings.	Adding undeclared files and expecting app code to find them.
Prepared input	A surface-facing name Runtime Kit can read for the app.	Treating the name as a storage path.
Target	A public callable name app code can ask for work.	Importing the private implementation.
Reply bytes	The bytes returned by a target call.	Parsing bytes without a reply shape.
Placeable surface	A UI descriptor a shell can arrange without importing package-specific UI code.	Hardcoding product-specific layout policy into the shell.

Common mistakes

Treating the hook like a database queryuseBitfieldData(...) reads data Runtime Kit has already prepared for the surface. It is not where app code should build storage addresses or recreate package setup.Turning target names into importsA target name like product.search is the public call. Keep calling that target. Do not import the private implementation from your component.Making React the architectureReact is a surface. Runtime Kit is the boundary. If you build a non-React surface later, the Runtime Kit idea stays the same: named data reads and named target requests.Publishing secrets in package examplesPackage records and stored bytes are product material. Do not put private keys, tokens, or account secrets into public package examples.Triggering Runtime Kit for static public pagesDo not add Runtime Kit just to render static copy, images, links, or a brochure page. Use Use Runtime Kit where it should run before wiring public pages that do not need live Bitfield data or Bitfield request bytes.

Quick reference

Need	Use
See the whole feature chain	Package to screen
Understand generic surface placement	Placeable surfaces
Copy a full package-to-shell example	Placeable surface product loop
Show prepared app data	`useBitfieldData(...)`
Ask a package target to work	`sendRequestToBitfieldTarget(...)`
Declare package data or callable slots	`things-to-store-and-run.json`
Understand package shapes	Packages
Avoid accidental Bitfield request bytes on public pages	Use Runtime Kit where it should run
Look up exact API shape	Runtime Kit API
Keep AI-written changes inside the public files and names	Build with AI agents
Find a broken link in the chain	Troubleshooting

Now build the bigger version

Build one complete feature slice with the Runtime Kit shape.

Declare one package record for data the UI reads.
Declare one package-owned file for help, copy, rules, or config.
Declare one slot target for work the user can trigger.
Read the named data with useBitfieldData(...).
Call the target with sendRequestToBitfieldTarget(...).

That is enough to build a real feature without scattering feature setup through the app.

package data      -> useBitfieldData(...)
package file      -> package-owned bytes
package slot      -> sendRequestToBitfieldTarget(...)
React component   -> renders states and user actions

Repeat that slice for the next feature. The 10th feature should still have the same calm shape as the first.

Contract to keep beside the code

For each feature, write the public Runtime Kit contract in the feature ticket or README:

## Runtime Kit contract

- Package set:
- Package:
- Boundary file:
- Prepared inputs:
- Targets:
- Request payloads:
- Reply payloads:
- React surfaces:
- Public imports only:
  - @bitfield/runtime-kit
  - @bitfield/runtime-kit/react

That tiny contract prevents three common failures: app code reading package files, buttons importing target implementations, and new features inventing a second data path.

​What this is

​Choose your path

​The first feature shape

​The mental model

​How it works technically

​What app code should own

​Before / after

​The two app-facing calls

​useBitfieldData(...)

​sendRequestToBitfieldTarget(...)

​Runtime Kit is not React-only

​Terms to keep straight

​Common mistakes

​Quick reference

​Now build the bigger version

​Contract to keep beside the code