agent-byte-index-builder

v1.1.2

Published

16 days ago

Dense-Agent-Byte-Routing (DABR) Compiler, Decompiler and CLI

Downloads

968

0High
0Medium
0Low

casisme

Agent Byte Index Builder (DABR Compiler & CLI)

An ultra-compact compiler, decompiler, and command-line utility for Dense-Agent-Byte-Routing (DABR) stream-encoded web applications.

DABR is a domain-specific bytecode representation designed for low-bandwidth environments, prompt engineering pipelines, and agentic workflows where page/payload size is critical. It compiles static layouts and client-side interactivity into high-density Base91-encoded bitstreams (.b91). The client runtime decompiles these streams back into standard DOM trees with an Atomic Interface Behavior Map runtime to manage client-side interactive state shifts with zero custom JavaScript.

How to use for Vibe Coding

Start installing the project: Installation & Setup

Use this prompt to make a new DABR project

You are a DABR compilation agent. Build the following project using only .b91 files and folders — no HTML, CSS, JavaScript, or any other file type.

Follow the DABR compilation rules exactly as specified in your SKILL file.

Project: [DESCRIBE YOUR PROJECT HERE]

Decompile and build

Use the CLI to build the project and see the HTML/CSS files fold out in the dist/ folder.

Build and Preview the Compiled Stream.

Key Features

Byte-Optimal Serialization: Tokenizes common HTML elements (e.g., div, button, span) and standard Tailwind CSS layout/styling tokens using a prefix-free binary representation.
Micro-Interactivity Runtime: Implements visibility and custom class-toggling mechanics using binary event-action opcodes, avoiding the weight of standard JS bundles.
Automated Tailwind Bundler: Built-in CLI step automatically parses decompiled static HTML structures, executes Tailwind's utility class extraction, and outputs a minified stylesheet (styles.css).
Bidirectional Development Flow: Edit files directly in standard HTML, then compile them down to compact .b91 streams, or decompile .b91 streams back to clean HTML for modification.

Installation & Setup

Ensure you have Node.js installed (version 18+ recommended).

Install Globally (CLI usage)

npm install -g agent-byte-index-builder

Install Locally (Development usage)

npm install --save-dev agent-byte-index-builder

Initializing a New Project

To create a new DABR-based project from scratch, follow these steps:

1. Structure Your Directory

Create a directory for your project containing your compiled streams (.b91) and a folder for the static output:

my-dabr-project/
├── index.b91         # Your compiled stream application (root)
└── dist/             # Target output directory (autogenerated on build)
    ├── index.html    # Native HTML preview & interface shell
    └── styles.css    # Minified Tailwind CSS styles bundle

2. Create an Initial HTML Page

Create a temporary native HTML structure that you want to serialize. Put it in dist/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>DABR Application</title>
</head>
<body class="bg-gray-50 text-gray-900 font-sans p-6">
    <div class="flex flex-col items-center justify-center p-8 bg-white shadow rounded-lg max-w-md mx-auto">
        <h1 class="text-2xl font-bold mb-4">Hello DABR!</h1>
        <p class="text-gray-500 mb-6 text-center">This interactive page is compiled into a Base91 bitstream.</p>
        <button id="trigger" dabr-event-click="0:target-panel" class="bg-blue-600 hover:bg-blue-700 text-white font-semibold px-4 py-2 rounded">
            Toggle Details
        </button>
        <div id="target-panel" class="hidden mt-4 p-4 bg-gray-100 rounded-md text-sm text-gray-700">
            DABR parses and manages this panel toggling interactively!
        </div>
    </div>
</body>
</html>

Notice the dabr-event-click="0:target-panel" attribute. This binds a click event that toggles the visibility (Tailwind's hidden class) of the element with the ID target-panel.

3. Compile HTML to DABR Stream

Run the compilation command from your project root:

npx agent-serialize compile --src ./dist --out ./

This compiles your native HTML file into a high-density, tokenized .b91 file: index.b91. If you open index.b91, you will see a single line of Base91 text.

4. Build and Preview the Compiled Stream

To decompile your .b91 stream back into standard HTML and automatically compile/minify Tailwind CSS styles, run:

npx agent-serialize build --src ./ --out ./dist

This command:

Decompiles index.b91 into native DOM structures inside dist/index.html.
Registers custom classes and tags.
Automatically triggers Tailwind CSS to bundle and minify all matching utility styles into dist/styles.css.
Attaches the Atomic Interactivity Runtime shell directly in the HTML.

Now you can host or open dist/index.html in any browser to verify that the layout and visibility toggle work perfectly!

CLI Command Reference

The library provides the binary command agent-serialize to manage bidirectional compilation.

`agent-serialize compile`

Compiles native HTML pages into token-optimized .b91 binary stream files.

Options:
- --src <dir>: Source directory containing index.html files (default: ./dist)
- --out <dir>: Output directory for compiled .b91 stream files (default: ./)
- --optimize: Enable Huffman coding, Tailwind class aliasing, and RLE loop generation
- --llm-token-optimized: Enable LLM tokenizer-friendly 1-Token words encoding (outputs a space-separated list of common English words instead of raw Base91 characters)

Example:

agent-serialize compile --src ./dist --out ./ --llm-token-optimized

`agent-serialize build`

Decompiles .b91 streams (including both Base91 and LLM Token-Optimized formats) into browser-ready HTML pages and bundles used styles with Tailwind CSS.

Options:
- --src <dir>: Source directory containing .b91 files (default: ./)
- --out <dir>: Target distribution directory for static HTML & styles (default: ./dist)

Example:

agent-serialize build --src ./src_b91 --out ./public

`agent-serialize instructions`

Prints the Dense-Agent-Byte-Routing (DABR) compilation framework rules and specifications (the content of SKILL.md) to standard output. This allows external AI agents to dynamically load the system instructions directly from the installed package.

Example:
```
agent-serialize instructions
```

Technical Specifications (DABR Protocol)

DABR encodes HTML document trees into binary bitstreams using variable-length instruction opcodes.

1. Variable Storage Allocation (256 Slots)

Each stream maintains a localized tape of 256 structural slots:

Static Native Dictionary (0x00 - 0x7F / 0-127): Pre-seeded slots containing 28 common HTML tags and 100 Tailwind classes. See the source dictionary at src/core/dictionary.ts.
Dynamic Runtime Slots (0x80 - 0xFF / 128-255): Sequential slots allocated at compile/decompile start, containing custom tags, classes, attribute-value pairs, or URL resources.

2. Opcode Matrix

Event Parameter Details:

Event Indices: 0000 = click, 0001 = input, 0010 = submit, 0011 = change, 0100 = mouseenter
Action Paradigms: 0 = Toggle Visibility Primitive (toggles class .hidden), 1 = Toggle Active Custom Token Modifier (toggles custom dynamic class/style modifier)
Target Memory Address: The exact 8-bit slot number assigned to the target DOM node.

3. Base91 Bitstream Packaging & `.b91` File Format

Once the compiler processes the DOM and outputs the sequence of bitstream instructions, it packs them into a .b91 file using the following procedure:

Bitstream Concatenation: All individual instruction bit sequences (opcodes, indexes, events, lengths, and character bytes) are concatenated from left to right.
Byte Boundary Padding: If the total bit length is not a multiple of 8, the stream is padded with trailing 0s to align it to the nearest byte boundary.
Byte Array Conversion: The padded bitstream is grouped into 8-bit chunks and converted into a Uint8Array.
Base91 Encoding: The resulting byte array is encoded into a single line of text using the standard Base91 character set: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!#$%&()*+,./:;<=>?@[]^_{|}~"`

This process yields a compact .b91 format representing the entire application layout, classes, text, and event mappings as a single ASCII string (e.g., |eAK|U_t#Fnv;LY6cj]hdQVEE|8y(*VT4tf,1opMMV).

4. LLM Token-Optimized Format (1-Token Words)

When compiling with --llm-token-optimized (e.g., for passing UI layout templates directly to/from AI coding agents), the bitstream is packed into a space-separated sequence of English words instead of a Base91 string:

Byte Representation: The process of Bitstream Concatenation, Byte Boundary Padding, and Byte Array Conversion is identical to the Base91 process.
1-Token Word Mapping: Each byte value (0 to 255) in the resulting Uint8Array is mapped directly to the word at that index in a static 256-word dictionary of highly common, BPE-optimal English words (e.g., 0 -> "the", 1 -> "of", 2 -> "and", ..., 255 -> "proud"). See src/core/llm-encoder.ts for the full vocabulary list.
Space-Separated String: The mapped words are joined by single spaces. The resulting file (retaining the .b91 file extension by default) contains only space-separated words, which look like: of country very plant because each work were point we are off need show kind before your because learn his together is read other animal then them form she house page can were sentence
Why Use This Format?: Standard Base91 strings are tokenized character-by-character or in small fragments, drastically increasing prompt token consumption and context window costs. Since every word in our 256-word vocabulary is chosen to map to exactly one token under popular BPE tokenizers (used by models like Gemini, Claude, GPT, and Llama), this format reduces prompt token consumption by up to 60-70% for complex layouts.
Auto-Detection: The build system and decompiler automatically detect the 1-Token Words format. During build execution, if the text splits by spaces and every word is present in the 256-word LLM vocabulary, the compiler decodes each word back to its 8-bit byte index and processes the underlying bitstream.

For a full step-by-step example of bitstream generation, Base91 encoding, and LLM Token-Optimized encoding, refer to SKILL.md.

Contributing

We welcome contributions to optimize the binary compression ratio, add tags/classes to the static dictionary, or improve compilation speeds.

1. Development Setup

To build the compiler locally, clone this repository and set up the development environment:

# Clone the repository
git clone https://github.com/CKReiff/agent-byte-index-builder.git
cd agent-byte-index-builder

# Install dependencies
npm install

# Compile TypeScript sources
npm run build

2. Running Tests

We run roundtrip integration tests verifying compiler/decompiler symmetry, dynamic slots registration, custom attributes mapping, and interactive event resolution. Run the test suite using:

npm test

Test configurations are written inside tests/roundtrip.test.ts.

3. Guidelines

Ensure that any modifications to src/core/compiler.ts or src/core/decompiler.ts maintain full roundtrip symmetry (a page compiled and decompiled must retain exact structural equivalency).
Do not alter the order of items in src/core/dictionary.ts since it will break backward compatibility for older .b91 files.
Document any new CLI flag or feature in this README.md.
Keep clean code structures with descriptive TypeScript types.