feat(arx): base64url wire encoding (B. prefix) for chat-safe ARX

[baanish]

Summary

Adds a fourth binary-to-text option inside the existing arx codec (not a new schema codec): base64url (A-Za-z0-9-_, no padding) with wire prefix B. so it is distinguishable from base1k/baseBMP and detectable in arxDecompress.

Implementation

• encodeBase64url / decodeBase64url / isBase64urlEncoded in arx-codec.ts
• arxCompressBase64url — same pipeline as other ARX variants (dict → brotli → encode)
• arxDecompress tries base64url when isBase64urlEncoded; if Brotli fails, falls back to base76 (covers the rare case where base76’s length prefix is also B., e.g. 140-byte payloads)
• buildArxCandidates in fragment.ts adds a base64url candidate; selection still uses smallest transportLength (so base64url wins when percent-encoded Unicode inflates Unicode encodings)

Tests & docs

• Extended tests/arx-codec.test.ts (roundtrip, empty B., URL-safe charset, detection)
• Updated docs/payload-format.md, docs/architecture.md, skills/agent-render-linking/SKILL.md, and scripts/codec-poc.mjs for the new tier

Verification

• npm test
• npm run lint / npm run typecheck

  

Summary by CodeRabbit

• New Features

  • ARX codec now supports base64url as an additional wire shape and may choose it when smallest by transport length.

• Behavior Changes

  • Encoder selects fragments by shortest transport-length (percent-encoded UTF-8) rather than shortest encoded fragment; chat-style surfaces may favor base64url.
  • Updated example timing to ~8–14ms and revised compression ratio wording (~6.1x).

• Documentation

  • Architecture and payload docs updated with base64url details and benchmark revisions.

• Tests

  • Added tests validating base64url round-trips and auto-selection behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4be0b9db-2516-447f-9bb0-ce95be967221

📥 Commits

Reviewing files that changed from the base of the PR and between b3de0ca and 612859e.

📒 Files selected for processing (2)

• src/lib/payload/fragment.ts
• tests/arx-codec.test.ts

✅ Files skipped from review due to trivial changes (1)

• tests/arx-codec.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/payload/fragment.ts

---

📝 Walkthrough

Walkthrough

Adds base64url as a fourth arx wire shape, switches encoder candidate selection to shortest transport length (percent-encoded UTF‑8), updates decoder probing order and Brotli handling, and adjusts docs, benchmarks, tests, and fragment selection to include base64url (B. prefix).

Changes

Cohort / File(s)	Summary
Documentation Updates docs/architecture.md, docs/payload-format.md, skills/agent-render-linking/SKILL.md	Replace “three encoding tiers” with four “wire shapes”; document base64url (B. prefix), transport-length selection (percent-encoded UTF‑8), detection/fallback behavior, and updated benchmark/timing figures.
Core Codec Implementation src/lib/payload/arx-codec.ts	Add encodeBase64url/decodeBase64url/isBase64urlEncoded and arxCompressBase64url; change baseBMP marker check to U+FFF0; modify arxDecompress probing order (baseBMP → base64url → base76 → base1k) and factor brotli + dict decode into decompressFromBytes.
Fragment Candidate Selection src/lib/payload/fragment.ts	Add base64url ARX candidate via arxCompressBase64url; change computeTransportLength to account for percent-encoding of non-chat-safe ASCII, affecting candidate selection for encodeEnvelopeAsync.
Benchmarking Script scripts/codec-poc.mjs	Add encBase64url(bytes) helper; measure encode time for base64url and compare against existing baselines; add ARX+base64url entry to timing summaries.
Tests tests/arx-codec.test.ts	Add tests covering encodeBase64url/decodeBase64url round trips, isBase64urlEncoded validation, prefix-required error, arxCompressBase64url pipeline, and auto-selection producing B.-prefixed fragments.

Sequence Diagram(s)

sequenceDiagram
participant Client
participant Encoder
participant Brotli
participant Transport
participant Viewer
participant Decompressor

Client->>Encoder: provide payload (JSON)
Encoder->>Encoder: apply dictionary substitution
Encoder->>Brotli: compress bytes
Brotli-->>Encoder: compressed bytes
Encoder->>Transport: generate wire candidates (baseBMP, base1k, base64url, base76)
Transport-->>Encoder: compute transport lengths (percent-encoded UTF-8)
Encoder->>Transport: select shortest transport-length candidate
Encoder-->>Client: return fragment (`v1.arx.<dict>.<payload>`)

Client->>Viewer: deliver fragment
Viewer->>Decompressor: detect wire shape (prefers baseBMP, then base64url, base76, base1k)
Decompressor->>Brotli: brotli-decompress bytes
Brotli-->>Decompressor: decompressed bytes
Decompressor->>Viewer: reconstruct original JSON
Viewer-->>Client: present payload

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat: add arx codec with domain dictionary and multi-tier Unicode encoding #4 — Introduced the original ARX codec this change extends by adding base64url and transport-length selection.
• Add compression algorithm selection to link creator #11 — Touches payload codec selection flow that interacts with encodeEnvelopeAsync and candidate selection logic.
• Header homepage navigation #6 — Adds JSDoc/comments in the same arx-codec.ts area; relevant to newly exported helpers and behavior changes.

Poem

🐰 I nibble bytes and count the hops, now four—
A tiny B. prefix opens a new door,
Brotli hums, the transport length decides,
Shorter hops mean fewer meadow strides,
Hooray—small payloads and bigger naps! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding base64url wire encoding with B. prefix to the ARX codec for chat-safe transport.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/arx-base64url-encoding-f81f

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cloudflare-workers-and-pages]

Deploying agent-render with    Cloudflare Pages

Latest commit:	612859e
Status:	✅  Deploy successful!
Preview URL:	https://80cac995.agent-render.pages.dev
Branch Preview URL:	https://cursor-arx-base64url-encodin.agent-render.pages.dev

View logs

[kilo-code-bot]

Code Review Summary

Status: No New Issues | Recommendation: Merge

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	0

Resolution of Existing Comment

The inline comment on line 175 regarding base64url not being automatically selectable has been addressed in this PR:

1. computeTransportLength fix (fragment.ts:50-60): The function now treats ASCII punctuation outside the URL-unreserved set (CHAT_SAFE_ASCII_FRAGMENT_CHARS = /^[A-Za-z0-9\-._~=#]+$/) as escape-prone, counting them as 3 characters instead of 1. This makes base64url more competitive against base76 in auto-selection since base76 uses punctuation-heavy encoding.

2. Test validation (arx-codec.test.ts): A new test async arx selection can choose the chat-safe base64url wire form verifies that the auto-selection correctly picks base64url for appropriate payloads.

Changes Reviewed (7 files)

File	Summary
docs/architecture.md	Updated ARX codec documentation with four wire shapes
docs/payload-format.md	Updated payload format docs with base64url details
scripts/codec-poc.mjs	Added base64url to benchmarking script
skills/agent-render-linking/SKILL.md	Updated skill documentation
src/lib/payload/arx-codec.ts	Added base64url encode/decode functions with B. prefix
src/lib/payload/fragment.ts	Integrated base64url into async candidate selection with transport length fix
tests/arx-codec.test.ts	Comprehensive tests for base64url functionality

Implementation Quality

• ✅ Follows existing code patterns
• ✅ Proper error handling with fallback to base76 for edge cases
• ✅ Tests cover edge cases (empty input, various byte sequences, validation)
• ✅ Uses standard RFC 4648 base64url alphabet
• ✅ Auto-selection now works correctly with the transport length fix

Files Reviewed (7 files)

• docs/architecture.md
• docs/payload-format.md
• scripts/codec-poc.mjs
• skills/agent-render-linking/SKILL.md
• src/lib/payload/arx-codec.ts
• src/lib/payload/fragment.ts
• tests/arx-codec.test.ts

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b3de0ca657

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Make the new base64url ARX candidate actually selectable

Any caller that relies on encodeEnvelopeAsync to choose the best arx wire shape will still never emit the new B. form. selectCandidate ranks candidates by transportLength, and computeTransportLength treats both base76 and base64url as plain ASCII; since arxCompress encodes the same Brotli bytes with a denser 77-symbol alphabet than base64url’s 64 symbols, the base76 candidate is always no longer than arxCompressBase64url. So auto mode keeps producing the old punctuation-heavy base76 fragments, and the chat-safe base64url path introduced here is effectively unreachable unless a caller bypasses encodeEnvelopeAsync and invokes arxCompressBase64url directly.

Useful? React with 👍 / 👎.