Bitfield Docs

When many packages need to cooperate, do not create one giant store that everyone imports. Let packages meet through Bitfield state, data names, and action requests.

A command center has a file tree, file editor, AI chat, project preview, notifications, keyboard shortcuts, and a sidebar. Each package has its own job. The user still needs one coherent product.The goal is cooperation without fusion: packages share public Bitfield handles instead of turning into one tangled codebase.

Traditional app shape

import { appStore } from '../app-store';
import { previewService } from '../project-preview/service';
import { notificationService } from '../notifications/service';
import { chatContext } from '../chat/context';

export async function runEverything() {
  const file = appStore.fileTree.selectedFile;
  chatContext.attachFile(file);
  await previewService.refresh(appStore.currentProject);
  notificationService.setMode(appStore.settings.notificationMode);
}

This code is convenient because everything is reachable. It is dangerous for the same reason.

Bitfield shape

selected-file -> shared Bitfield state
current-project -> shared Bitfield state
project-preview-surface -> data name
notification-mode.update -> action request
chat.attach-context -> action request

Each package uses the public name it needs. No package imports every other package.

Cooperation map

State

Editor, AI context, and breadcrumbs read the same product fact.

Input

Preview UI reads a prepared view of project status and URL.

Request

A settings surface asks the notification package to change mode.

Private

Temporary UI details stay inside the package rendering them.

Larger chain

Start with a normal product flow:

User selects a file.
Editor opens that file.
AI context panel uses that file.
Preview panel shows the current project preview.
Keyboard shortcut changes the selected agent.
Notification package shows whether work finished.
Help package provides context text for the command palette.

Traditional app architecture tends to collapse that into one central store:

appStore.selectedFile = fileTreeStore.selectedFile;
appStore.editor.open(appStore.selectedFile);
appStore.ai.attachFile(appStore.selectedFile);
appStore.preview.refresh(appStore.currentProject);
appStore.selectedAgent = keyboardStore.nextAgent();
appStore.notifications.mode = settingsStore.notificationMode;
appStore.help.index = helpPackage.searchIndex;

That looks convenient until every package depends on the central store shape and the central store imports every package.

Shared names, separate packages

selected-file -> product fact read by editor and AI context
current-project -> product fact read by preview and package filters
project-preview-surface -> data name rendered by preview shell
selected-agent.update -> action request from keyboard or command palette
notification-mode.update -> action request from settings or shortcuts
getting-started-help -> data name from package-owned help content
dropdown open state -> private UI state inside the surface

Now each package meets the others through public facts, data names, and action names. There is no private central product object.

What this prevents

Bad shape	Why it breaks	Better shape
One giant app store.	Every feature depends on every other feature’s private state shape.	Shared product facts in Bitfield.
One central service imports all packages.	Adding a package means editing the central service.	Packages expose inputs and targets.
Shell coordinates package-specific UI rules.	Layout becomes business logic.	Shell places; packages read/call.
Code gets patched wherever it is easiest.	The code compiles but boundaries collapse.	Choose state, input, target, private UI state, or package bytes.

React is one adapter that can show this chain. The chain itself is Runtime Kit: shared product facts, data names, action requests, private UI state, and package files.

Complete translation example

Product need	Traditional answer	Bitfield answer
Editor needs active file.	Import file tree store.	Read `selected-file`.
AI chat needs active file.	Import editor state.	Read `selected-file`.
Preview panel needs URL.	Import project preview service.	Read `project-preview-surface`.
Button refreshes preview.	Call preview implementation.	Request `project-preview.refresh-status`.
Keyboard changes selected agent.	Import selected-agent service.	Request `selected-agent.update`.
Dropdown opens.	Global app store.	Private UI state.

Add a new package without retangling

Imagine you add a “recent activity” package.

Traditional addition

import { editorStore } from '../editor/store';
import { previewService } from '../project-preview/service';
import { notificationSettings } from '../notifications/settings';

export function RecentActivity() {
  return buildActivity(editorStore.file, previewService.status, notificationSettings.mode);
}

Bitfield addition:

const selectedFile = readInput('selected-file');
const preview = readInput('project-preview-surface');
const notificationMode = readInput('notification-mode');

The new package reads the public facts it needs. Existing packages do not change.

Central-store shortcut

recentActivityStore.copyFrom(appStore);

Read public facts instead

const activityInputs = [
  readInput('selected-file'),
  readInput('project-preview-surface'),
  readInput('notification-mode'),
];

Multi-package review checklist

Check	Good answer
Does adding the new package require editing existing package imports?	No.
Does the shell branch on package-specific UI rules?	No. It places descriptors and surfaces.
Does one package become the central product store?	No. Shared facts live in Bitfield.
Can keyboard, command palette, and buttons request the same work?	Yes. They send the same action request.
Can a non-React shell follow the same chain?	Yes. React is one adapter, not the architecture.

Why this scales past the first screen

The first screen can survive traditional coupling. The tenth screen usually cannot. The problem is not that stores, services, or contexts are evil. The problem is that they make every feature depend on another feature’s private state shape.Bitfield keeps the product language outside any one package:

Product language	Public name
”The file the user is working on”	`selected-file`
”The project the workspace is showing”	`current-project`
”The preview surface to render”	`project-preview-surface`
”Change the selected agent”	`selected-agent.update`
”Search help”	`help.search`

That is what lets package eleven join the product without becoming a patch inside package two.

Review check

When more than two packages are involved, do not solve it by creating appStore, platformStore, globalState, or sharedService. First classify each relationship:

same fact needed by many packages -> Bitfield state
prepared view from package material -> data name
work to run -> action request
visual-only detail -> private UI state
bytes shipped with package -> package file

Start with the overview: Build without tangled code
Build a full example: Placeable surface product loop
Review AI coding rules: Rules for AI agents

Use Runtime Kit

Understand Runtime Kit

Build without tangled code

Runtime Kit Cookbook

Reference

Let many packages work together

Traditional app shape

Bitfield shape

Cooperation map

Larger chain

Shared names, separate packages

What this prevents

Complete translation example

Add a new package without retangling

Traditional addition

Central-store shortcut

Read public facts instead

Multi-package review checklist

Why this scales past the first screen

Review check

Next

​Traditional app shape

​Bitfield shape

​Cooperation map

​Larger chain

​Shared names, separate packages

​What this prevents

​Complete translation example

​Add a new package without retangling

​Traditional addition

​Central-store shortcut

​Read public facts instead

​Multi-package review checklist

​Why this scales past the first screen

​Review check

​Next

Traditional app shape

Bitfield shape

Cooperation map

Larger chain

Shared names, separate packages

What this prevents

Complete translation example

Add a new package without retangling

Traditional addition

Central-store shortcut

Read public facts instead

Multi-package review checklist

Why this scales past the first screen

Review check

Next