Explore linear memory interop frameworks
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 38/100
- Issue type
- Refactor
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- c, typescript, wasm
- Domain
- backend, build-system, performance
Research direction
Start with ops.ts, src/clayterm.c, and input.ts to map the existing render and input wire paths, then run the current size-report.yml baseline. Compare the listed framework candidates and shared-header approach across binary and bundle size, allocations, access cost, buffer size, toolchain integration, and direction coverage; document the findings without adopting a framework.
Written by the indexing model from the issue text.
Description
Context
Every WASM boundary crossing today goes through hand-written pack/unpack code
against a manual wire format:
- Render out (TS → C):
pack()/packSize()inops.tswrite a
Uint32Arrayinto WASM linear memory.reduce()insrc/clayterm.creverses
the exact same layout withrd()and offset arithmetic. - Input events (C → TS): the parser writes event structs into linear
memory;input.tswalks them back out with aDataView(seereadEvent).
The wire format is duplicated across the packer, the size calculator, and the
unpacker. Every field addition or reorder is a lockstep change across TS and C,
policed only by comments (see ops.ts:217-227, which explicitly warns that C
treats field order as an invariant).
This issue is to explore whether an off-the-shelf zero-copy interop
framework would serve us better. It is not a proposal to adopt one.
Candidate frameworks
Non-exhaustive; add more in comments.
- FlatBuffers — schema-driven, zero-copy reads via
vtable-guided field access, wide language support. - Cap'n Proto — similar model, more compact vtables,
wide language support. - Shared C headers only — skip the framework, share a
.hdescribing the
layout, generate TS accessors from it. Lightest possible dependency.
Potential benefits
- One schema as the single source of truth in place of three hand-synced code
paths. - Eliminates the explicit unpack step on the C side (zero-copy access, though
the exact cost model differs by framework — see open questions). - Type-safe generated accessors on both sides in place of offset math and bit
shifts. - Forward compatibility — schema-based frameworks allow adding fields with
defaults instead of hard-breaking every wire change. - Cross-language reach — third parties consuming
clayterm.wasmfrom Go, Rust,
Python, etc. get generated bindings instead of having to reimplement the
packer. - Debuggability — schema-based frameworks can dump a buffer to JSON for
inspection; the current format is opaque bytes.
Open questions to answer
- WASM binary size delta. The framework runtime lands in
clayterm.wasm.
How much does each candidate add? Compare against current baseline reported
bysize-report.yml. - JS bundle size delta. The builder/reader library ships to consumers.
How much does each candidate add over the ~600 lines of custom pack code? - Per-frame allocation profile. The current packer writes straight into
WASM linear memory with no intermediate objects. Do the candidate TS
builders introduce allocations that create GC pressure at frame rate? - Access cost on the C side. "Zero-copy" is not free — flatbuffers and
Cap'n Proto both use vtable-guided lookups. What is the actual per-op cost
vs. the currentrd()loop? - Buffer size delta. Current bit-packing (padding in a word, attrs in the
color alpha byte) is dense. How much larger does a typical frame get with
each candidate? - Toolchain cost.
flatc/capnpneed to plug into the Makefile and
Deno tasks. What does the dev setup look like? - Scope. Does the framework replace both directions (render + input),
or just one?
- Dominant language
- TypeScript
- Stars
- 42
- Forks
- 2
- Avg merge
- 2d 5h
- Merged PRs (30d)
- 12
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from bombshell-dev/tty
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
bombshell-dev/tty#61 · 1 reaction ·
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
bombshell-dev/tty#129 ·
-
enhancement high priority
Difficulty 3/5 1-2 days Newbie friendliness 68/100
bombshell-dev/tty#83 · 2 comments ·
-
enhancement
Difficulty 4/5 3-5 days Newbie friendliness 48/100
bombshell-dev/tty#82 ·
-
bug
bombshell-dev/tty#81 · 1 assignee ·
All issues in bombshell-dev/tty
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug clawsweeper:linked-pr-open clawsweeper:needs-live-repro clawsweeper:no-new-fix-pr impact:message-loss issue-rating: 🐚 platinum hermit P2 regression
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100
danielmiessler/LifeOS#2218 ·