Bitfield Docs

When one package prepares data and another package needs it, the consumer should read a data name. It should not import the producer package, parse its files, or guess the storage address.

A project-preview package prepares a list of preview URLs and statuses. A web-frame package wants to render the active URL. The web-frame should not import project-preview storage code. It should read the view it was given.The producer can change how records are prepared. The consumer should keep reading the same public input shape.

Traditional app shape

import { getPreviewRecords } from '../project-preview/store';

export function WebFrame() {
  const preview = getPreviewRecords().find(item => item.active);
  return renderUrl(preview.url);
}

This ties the web frame to the project-preview package. The consumer now depends on the producer’s module path, function name, record shape, and selection logic.

Bitfield shape

producer package prepares records
Runtime Kit exposes a data name
consumer package reads that input
consumer decodes only the public view it asked for

The consumer can read source-by-label, source-by-address, selected-file, current-project, or any other input that the package file exposes. It does not read producer private code.

Code translation

Traditional path

import { previewStore } from '../project-preview/store';

const active = previewStore.getActivePreview();

Bitfield path

const active = readInput('project-preview-surface');

React adapter example

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

type PreviewSurface = {
  projectId: string;
  name?: string;
  url?: string;
  isConnected?: boolean;
  status?: string;
};

export function PreviewPanel() {
  const preview = useBitfieldData<PreviewSurface>('project-preview-surface');

  if (preview.loading) return <p>Loading preview</p>;
  if (preview.error) return <p>Could not load preview.</p>;
  if (!preview.data?.url) return <p>No preview URL yet.</p>;

  return <iframe title={preview.data.name ?? 'Project preview'} src={preview.data.url} />;
}

Descriptor-projected records

Some consumers need a different view of the same source. That should be data, not a new import path.

source-by-label:
  params.source_address_label = project-preview-surface
  field map says which public field is the URL

This lets the consumer read a projected view. It does not make the consumer depend on the producer’s private data layout.

Four prepared-read situations

Preview surface

Private preview helper

import { getPreviewUrl } from '../project-preview/build-preview';

const url = await getPreviewUrl(projectId);

Read the prepared preview

const preview = readInput('project-preview-surface');

The preview package prepares the public view. The consumer renders the view without importing the preview package’s builder code.

Selected file content

Private file reader

import { readSelectedFileText } from '../file-editor/files';

const text = await readSelectedFileText();

Read the file-facing public values

const selectedFile = readInput('selected-file');
const fileContent = readInput('selected-file-content');

The selected file fact and the prepared content are separate public reads. The consumer does not become the file package.

Help content

Private help file

const markdown = await fetch('/packages/help/content/getting-started.md').then((r) => r.text());

Read the prepared help

const help = readInput('getting-started-help');

The package can change how it ships or prepares the help content while the consumer keeps the same public read.

Worktree records

Private record cache

import { records } from '../git-worktree/private-record-cache';

const current = records.filter((record) => record.projectId === projectId);

Read the prepared records

const worktrees = readInput('git-worktree-records');

The consumer asks for the public prepared records it needs. It does not import the producer’s cache or storage shape.

Consumer boundary checklist

Question	Correct answer
Does the consumer import the package that prepared the data?	No. It reads a data name.
Does the consumer parse another package’s boundary file?	No. Runtime Kit resolves package material.
Does the consumer build storage addresses by string operations?	No. It uses public input names or descriptors.
Does the consumer assume producer field names are permanent?	No. Descriptor data maps the public view.
Does the consumer work outside React?	Yes. Any shell can follow the same input boundary.

Full before and after

Traditional feature request

“Show the preview URL beside the current file and include help text if the user opens the command palette.”

Bad implementation

import { fileTreeStore } from '../file-tree/store';
import { getPreviewUrl } from '../project-preview/private-preview';
import helpMarkdown from '../help/content/getting-started.md?raw';

export async function buildPanel() {
  return {
    file: fileTreeStore.selectedFile,
    previewUrl: await getPreviewUrl(fileTreeStore.projectId),
    help: helpMarkdown,
  };
}

This code makes one consumer depend on three private details: file tree state shape, preview implementation, and help package folder layout.

Public read version

const selectedFile = readInput('selected-file');
const preview = readInput('project-preview-surface');
const help = readInput('getting-started-help');

The consumer reads three public names. Each preparing package can change its private code without forcing this panel to change.The same translation works for a native app, terminal view, or future shell. The adapter changes. The public inputs do not.

What this prevents

Bad shape	Why it breaks	Better shape
Consumer imports producer package.	Moving the producer breaks the consumer.	Consumer reads a data name.
Consumer parses `things-to-store-and-run.json`.	UI code becomes package-loader code.	Runtime Kit resolves the package file.
Consumer builds storage addresses by string concatenation.	Address rules leak into app code.	Consumer uses a named input.
Consumer assumes producer field names forever.	Producer cannot change its private shape safely.	Descriptor data maps the public view.

React is one adapter for reading a data name. A Swift, Kotlin, terminal, or future shell should follow the same boundary: read the named input, not the package that prepared it.

Review check

If consumer code says import ... from '../other-package', ask why. A consumer package should receive a data name or an action name. It should not inspect another package’s source files.

Share product facts safely: Share state between packages
Request work from another package: Ask another package to do work
Look up read contracts: Runtime Kit API

Use Runtime Kit

Understand Runtime Kit

Build without tangled code

Runtime Kit Cookbook

Reference

Read data another package prepared

Traditional app shape

Bitfield shape

Code translation

Traditional path

Bitfield path

React adapter example

Descriptor-projected records

Four prepared-read situations

Preview surface

Private preview helper

Read the prepared preview

Selected file content

Private file reader

Read the file-facing public values

Help content

Private help file

Read the prepared help

Worktree records

Private record cache

Read the prepared records

Consumer boundary checklist

Full before and after

Traditional feature request

Bad implementation

Public read version

What this prevents

Review check

Next

​Traditional app shape

​Bitfield shape

​Code translation

​Traditional path

​Bitfield path

​React adapter example

​Descriptor-projected records

​Four prepared-read situations

​Preview surface

​Private preview helper

​Read the prepared preview

​Selected file content

​Private file reader

​Read the file-facing public values

​Help content

​Private help file

​Read the prepared help

​Worktree records

​Private record cache

​Read the prepared records

​Consumer boundary checklist

​Full before and after

​Traditional feature request

​Bad implementation

​Public read version

​What this prevents

​Review check

​Next

Traditional app shape

Bitfield shape

Code translation

Traditional path

Bitfield path

React adapter example

Descriptor-projected records

Four prepared-read situations

Preview surface

Private preview helper

Read the prepared preview

Selected file content

Private file reader

Read the file-facing public values

Help content

Private help file

Read the prepared help

Worktree records

Private record cache

Read the prepared records

Consumer boundary checklist

Full before and after

Traditional feature request

Bad implementation

Public read version

What this prevents

Review check

Next