Bitfield Docs

Most software gets tangled because one part of the app directly imports or depends on another part’s private state. Runtime Kit gives you a different shape: put shared product facts in Bitfield, read prepared views, and ask named targets to do work.

You are building a product with files, panels, settings, search, AI context, background jobs, and multiple package areas. The first version works. Then feature twenty needs to know what feature seven selected. Feature thirty needs to run the same work from a different place. The traditional fix is another store, another service import, another prop path, or another global. That is how every feature starts depending on every other feature. This section shows the replacement.This section teaches the translation move: see the normal app-code instinct, then turn it into the Bitfield shape without guessing, importing private code, or making React the architecture.

The translation

Import another feature’s store, service, file path, or implementation.

Is this shared state, named data, work to request, private UI state, or package-owned bytes?

Bitfield state, data name, action request, local UI state, or package file.

The real split

If the code wants to…	Do this	Do not do this
Share state across packages.	Put the shared product fact in Bitfield and read it as an input.	Share a mutable object from one package.
Read data another package prepared.	Read a data name.	Import the producer package or parse its files.
Ask another package to do work.	Send a request to a named target.	Call the implementation function directly.
Track hover, open menus, draft text, or drag position.	Keep it private in the component/package.	Store it in Bitfield just because state exists.
Ship files with a package.	Keep bytes inside the package file.	Import or read random app folders from consumer code.
Coordinate many packages.	Combine Bitfield facts, data names, and action requests.	Make one package become the private shared store for everyone.

Why this section exists

Most app examples teach the traditional shape: stores, services, imports, reducers, contexts, and direct calls.

The old app shape

One feature imports another feature’s state or implementation because that is the shortest path in ordinary app code.Bitfield uses a different shape. The pattern is not “make a better global store.” The pattern is:

shared product fact -> Bitfield state
named data -> named input
work to run -> named action request
visual-only detail -> private local UI state
package material -> package file

React, Swift, Kotlin, Rust, Python, terminal shells, web shells, and future adapters all wrap the same idea. React is one example, not the architecture.

What this prevents

Traditional shape	Why it gets tangled	Bitfield shape
`editor` reads `fileTree.selectedFile`.	Editor directly depends on file-tree private code.	Editor reads the `selected-file` input.
A button imports `runSearch()` from another package.	The button is tied to the implementation.	The button sends a request to `search.run`.
A panel parses another package’s JSON file.	Consumer code depends on package storage layout.	The panel reads data the package prepared.
A shell branches on every product area.	The shell becomes product-specific.	The shell reads descriptors and places what it is given.
A new app store appears for every problem.	The app grows competing sources of truth.	Choose Bitfield state, local state, input, or target.

The coupled version

The product request says: “When I select a file, show it in the editor, let the AI panel use it, and let the command palette open actions for it.”

The tangled version

import { fileTreeStore } from '../file-tree/store';
import { editorStore } from '../editor/store';
import { aiContextStore } from '../ai/context';
import { openCommandPalette } from '../command-palette/actions';

export function onFileSelected(filePath: string) {
  fileTreeStore.selectedFile = filePath;
  editorStore.open(fileTreeStore.selectedFile);
  aiContextStore.attachFile(fileTreeStore.selectedFile);
  openCommandPalette({ filePath: fileTreeStore.selectedFile });
}

That code feels fast because every store is directly importable. It is also the start of the coupling problem. The editor directly depends on the file-tree store. The AI context directly depends on editor timing. The command palette directly depends on the selection source. Every future package has to depend on the old package graph before it can do a simple job.

The Bitfield split

selected-file becomes a Bitfield product fact
editor reads selected-file
AI context reads selected-file
command palette reads selected-file or asks a target to run work
each package keeps its own private UI details private

React adapter example

const selectedFile = useBitfieldData<string>('selected-file');

Request example

await sendRequestToBitfieldTarget({
  target: 'command-palette.open-for-file',
  payload: { input: 'selected-file' },
});

The difference is not syntax. The difference is dependency direction. In the traditional code, every package imports or depends on other packages. In the Bitfield code, packages use named public facts, data names, and targets.

Bigger translation matrix

Product situation	Traditional answer	Bitfield translation
Editor and AI panel both need active file.	Put selected file in `fileTreeStore` and import it.	Write/read the `selected-file` product fact.
Preview panel needs a URL prepared by another package.	Import `getPreviewUrl()` from the preview package.	Read a data name such as `project-preview-surface`.
Keyboard shortcut changes selected agent.	Import `selectedAgentService.set(...)`.	Send an action request such as `selected-agent.update`.
Notification mode changes from settings and command palette.	Both call the same implementation file.	Both send the public action request for notification mode.
Dropdown opens while a user hovers.	Write `globalUiStore.dropdownOpen`.	Keep it private UI state.
Help page ships with a package.	Import `../help/content/start.md` from consumer code.	Package owns the bytes; consumer reads the prepared content.
Shell decides where product surfaces go.	`if package === 'preview' render PreviewPanel`.	Shell reads descriptors and places what it is given.
A feature gets added quickly.	Create a new store/service because that is the familiar app pattern.	Classify state, named data, work, UI-only state, and package material before code.

Review checklist

Reject the answer when any of these are true:

Check	Reject when you see	Accept when you see
Package file	A package imports another package’s store, service, or file.	It uses a public input or target.
Shared state	A value used by many packages lives inside one package object.	It is a named Bitfield product fact.
Named data	Consumer code parses producer package files.	Consumer reads data the package prepared.
Work request	A button calls another package implementation.	It sends a named action request.
UI-only state	Hover, focus, draft text, or open menu state is written as product state.	It stays local to the UI that uses it.
Adapter boundary	React context becomes the architecture.	React is one adapter over Runtime Kit reads and requests.

Read these pages by job

Your job	Page
The code has stores, service imports, direct calls, or shell branches.	Translate traditional code
Two packages need the same state.	Share state between packages
A package named data and another package needs to read it.	Read data another package prepared
A package needs another package to run work.	Ask another package to do work
You are unsure whether state belongs in Bitfield.	Keep private UI state private
A package ships files or bytes.	Store files inside a package
Several packages need to cooperate.	Let many packages work together
An AI agent keeps writing traditional architecture.	Rules for AI agents

Build the first full chain: Package to screen
Understand the pieces together: Runtime Kit concept map
Look up the public API: Runtime Kit API

Use Runtime Kit

Understand Runtime Kit

Build without tangled code

Runtime Kit Cookbook

Reference

Build without tangled code

The translation

The real split

Why this section exists

The old app shape

What this prevents

The coupled version

The tangled version

The Bitfield split

React adapter example

Request example

Bigger translation matrix

Review checklist

Read these pages by job

Next

​The translation

​The real split

​Why this section exists

​The old app shape

​What this prevents

​The coupled version

​The tangled version

​The Bitfield split

​React adapter example

​Request example

​Bigger translation matrix

​Review checklist

​Read these pages by job

​Next

The translation

The real split

Why this section exists

The old app shape

What this prevents

The coupled version

The tangled version

The Bitfield split

React adapter example

Request example

Bigger translation matrix

Review checklist

Read these pages by job

Next