Not every state value belongs in Bitfield. Put state in Bitfield when it coordinates packages. Keep hover, menu, drag, focus, and draft UI details private.
A sidebar has hover state, an editor has unsaved text, a file tree has a selected file, and an assistant panel needs the selected file for context. These are not the same kind of state.The split is simple: Bitfield carries product facts that multiple packages need, while components keep visual-only details close to where they happen.The rule
Only this component cares -> keep it private
Many packages need to react -> put it in Bitfield
Traditional mistake
await writeBitfieldState('hovered-sidebar-item', itemId);
await writeBitfieldState('dropdown-open', true);
await writeBitfieldState('drag-position', { x, y });
Bitfield shape
function SidebarItem() {
const [isHovered, setHovered] = useState(false);
return <button onMouseEnter={() => setHovered(true)} />;
}
selected-file
current-project
active-conversation
selected-agent
The decision table
| State | Where it belongs | Why |
|---|
| Hovered button | Private UI state | Only the button cares. |
| Dropdown open | Private UI state | Usually only one component cares. |
| Current drag position | Private UI state | It changes too often and is visual. |
| Unsaved textarea draft | Usually private UI state | It is not real product state until submitted. |
| Selected file used by editor and AI context | Bitfield state | Multiple packages coordinate around it. |
| Current project used by many panels | Bitfield state | It changes what many packages show. |
| Active conversation used by chat, timeline, and notifications | Bitfield state | It is a shared product fact. |
Four decisions in real product code
Hovered row
Traditional over-globalized answer
await writeBitfieldState('hovered-row', rowId);
Keep hover local
const [hoveredRow, setHoveredRow] = useState<string | null>(null);
Open command menu
Traditional over-globalized answer
globalUiStore.commandMenuOpen = true;
setCommandMenuOpen(true);
Selected file
Traditional under-shared answer
const [selectedFile, setSelectedFile] = useState<string | null>(null);
const selectedFile = readInput('selected-file');
Draft text
Traditional over-shared answer
await writeBitfieldState('draft-message-text', text);
Keep draft text local
const [draftText, setDraftText] = useState('');
| Ask this | If yes | If no |
|---|
| Does another package need this value? | Consider Bitfield state or data name. | Keep it private. |
| Does changing it run real product work? | Send an action request. | Keep it private or write product state through the right boundary. |
| Is it only animation, hover, focus, drag, scroll, or draft typing? | Keep it private. | Continue classifying. |
| Would losing it on refresh lose customer-visible data or progress? | It may be product state. | It is probably UI state. |
| Would two packages disagree if they each kept a copy? | Put one public fact in Bitfield. | Keep package-local state. |
What this prevents
| Bad shape | Why it breaks | Better shape |
|---|
| Every UI event writes Bitfield state. | Shared state becomes noisy and expensive to understand. | Keep visual-only state private. |
| Shared product facts stay in React state. | Other packages cannot reliably react. | Put coordination state in Bitfield. |
| The shell owns product state because it sits above children. | The shell becomes the product brain. | Packages read shared facts from Bitfield. |
| AI stores everything globally. | The app has too many sources of truth. | Classify state before writing code. |
Review checklist
| Check | Good answer |
|---|
| Is the value hover, focus, scroll, drag, or draft typing? | Keep it private. |
| Does another package need it to make product decisions? | Promote it to a shared fact or data name. |
| Does changing it run work? | Use an action request. |
| Is React context being used as product coordination? | Replace it with Runtime Kit reads and requests. |
Full before and after
Traditional feature request
“When the user clicks a file row, highlight it, open it in the editor, and show the assistant panel context.”Bad implementation
const [hoveredRow, setHoveredRow] = useGlobalStore('hoveredRow');
const [selectedFile, setSelectedFile] = useState<string | null>(null);
function onClick(filePath: string) {
setSelectedFile(filePath);
}
Put each value where its readers are
const [hoveredRow, setHoveredRow] = useState<string | null>(null);
const selectedFile = useBitfieldData<string>('selected-file');
Review check
Before adding state, classify it:Is this only visual?
keep it private
Does another package need to read it?
make it Bitfield state
Does changing it require work to run?
send an action request
Next
