Bitfield Docs

When a package ships files or bytes, keep them inside the package file. Consumer packages should receive named data or target replies, not random file paths into another package.

A help package ships markdown, a theme package ships images, and a file-preview package ships a small parser. A consumer wants the rendered result. The consumer should not read arbitrary files from the package folder.Package bytes should move with the package. Consumers should use public reads or requests, not private file paths that happen to work today.

Traditional app shape

const helpText = await fetch('/packages/help/content/getting-started.md');

or:

import helpText from '../help/content/getting-started.md?raw';

Now the consumer depends on the help package’s private file path. Rename the folder and consumers break.

Bitfield shape

help package file declares package-owned bytes
Runtime Kit admits the bytes with the package
consumer reads prepared help content or asks a help target

The package decides what bytes it brings. The consumer uses the public name exposed by the package file.

Boundary example

{
  "package": "help-package",
  "things": [
    {
      "type": "stored_bytes",
      "address": "package::help-package::bytes::getting-started",
      "file": "content/getting-started.md",
      "content_type": "text/markdown"
    }
  ]
}

The important part is not the exact content. The important part is the boundary: the package file reference stays inside the package.

Four file situations

Help markdown

Private help path

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

Prepared help read

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

The help package owns the file. The consumer reads prepared help content.

Preview HTML

Private preview bundle

import previewHtml from '../project-preview/dist/index.html?raw';

Prepared preview surface

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

The preview package decides how the surface is prepared. The shell receives a public view.

Review template

Private template import

import template from '../review-package/templates/review.md';

Prepared template read

const reviewTemplate = readInput('review-template');

The package can ship the template as package material. The caller should not read the package folder directly.

Search index

Private search index

import index from '../help/search-index.json';

Search through the package target

await sendRequestToBitfieldTarget({
  target: 'help.search',
  payload: { query },
});

The caller asks for search results. The help package can change its index format without breaking the caller.

Consumer rules

Rule	Meaning
A consumer may read a public data name.	It can use the handle the package exposes.
A consumer may send a public action request.	It can ask the package to do work.
A consumer may not import package files directly.	Folder structure is not public API.
A consumer may not copy bytes into app code.	Package material should stay package material.
A consumer may not assume file format unless the package exposes that format.	The public name is the data name or target reply.

What this prevents

Bad shape	Why it breaks	Better shape
Consumer imports another package’s file.	Folder structure becomes public API by accident.	Consumer reads named data.
Consumer builds a local filesystem path.	It only works on one machine/shell.	Package declares package-owned bytes.
Package references files outside itself.	The package cannot move cleanly.	Keep package file references inside the package folder.
App code copies package bytes into itself.	Data and code boundaries blur.	Keep bytes in package material and expose a public read/target.

React is one adapter that might render the bytes, but React does not define the package file. A web shell, native shell, terminal shell, or future adapter should receive named data from the same package-owned material.

Review checklist

Check	Good answer
Does consumer code import another package file?	No. It reads a data name or sends an action request.
Does the package reference material outside itself?	No. Package material stays inside the package file.
Does the consumer assume the file format?	Only when the public data name or reply shape says so.
Can the package move without breaking consumers?	Yes. Consumers rely on public names, not folders.

Full before and after

Traditional feature request

“Add a help panel that shows package help and lets the user search it.”

Bad implementation

import help from '../help/content/getting-started.md?raw';
import searchIndex from '../help/search-index.json';

export function HelpPanel() {
  return renderHelp(help, searchIndex);
}

This consumer now depends on two package files and one package layout. If the help package changes how it stores content or search data, the consumer breaks.

Public package version

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

const results = await sendRequestToBitfieldTarget({
  target: 'help.search',
  payload: { query },
});

The consumer gets content and search through public names. The package can keep markdown, JSON, a generated index, or something else behind that boundary.For React, Swift, Kotlin, terminal, or future adapters, the consumer rule stays the same: do not read package files directly.

Good consumer code

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

React adapter example

const help = useBitfieldData<{ title: string; body: string }>('getting-started-help');

The consumer asks for help content by public input name. It does not import or parse the package file that produced it.

Review check

If consumer code imports ../some-package/content/file.md, stop. Package files are package material. Consumers should read a data name or request a target.

Build package-owned bytes: Package-owned file
Learn package rules: Packages
Look up boundary fields: Package file

Use Runtime Kit

Understand Runtime Kit

Build without tangled code

Runtime Kit Cookbook

Reference

Store files inside a package

Traditional app shape

Bitfield shape

Boundary example

Four file situations

Help markdown

Private help path

Prepared help read

Preview HTML

Private preview bundle

Prepared preview surface

Review template

Private template import

Prepared template read

Search index

Private search index

Search through the package target

Consumer rules

What this prevents

Review checklist

Full before and after

Traditional feature request

Bad implementation

Public package version

Good consumer code

React adapter example

Review check

Next

​Traditional app shape

​Bitfield shape

​Boundary example

​Four file situations

​Help markdown

​Private help path

​Prepared help read

​Preview HTML

​Private preview bundle

​Prepared preview surface

​Review template

​Private template import

​Prepared template read

​Search index

​Private search index

​Search through the package target

​Consumer rules

​What this prevents

​Review checklist

​Full before and after

​Traditional feature request

​Bad implementation

​Public package version

​Good consumer code

​React adapter example

​Review check

​Next

Traditional app shape

Bitfield shape

Boundary example

Four file situations

Help markdown

Private help path

Prepared help read

Preview HTML

Private preview bundle

Prepared preview surface

Review template

Private template import

Prepared template read

Search index

Private search index

Search through the package target

Consumer rules

What this prevents

Review checklist

Full before and after

Traditional feature request

Bad implementation

Public package version

Good consumer code

React adapter example

Review check

Next