Simon Klee
3ab0b954a1
`EditBuffer.measureText(text)` returns the editor offset at the end of a
text: its cells under the buffer's width method, tab width, and control
notation, plus one per line break. The result depends only on the text
and those three settings, but an app needed a live native `EditBuffer`
to get it. opencode passed a measure closure into otherwise pure helpers,
kept a spare detached `EditBuffer` for when no textarea was mounted, and
built a renderer and a textarea in tests only to measure strings.
`measureEditText(text, { widthMethod, tabWidth })` returns what
`measureText()` and the end offset after `setText()` give on an edit
buffer with those settings, without a buffer or an owner. `tabWidth`
defaults to the tab width of a new edit buffer and rounds as
`setTabWidth()` does. It calls the new `ot_edit_measure_text(context,
bytes, byte_count, width_method, tab_width, out_width)`. That entry point
checks the width method as `ot_unicode_create` does, rejects a tab width
over 255 and rounds it as `ot_edit_buffer_set_tab_width` does, applies
the byte limit and UTF-8 check of `set_text`, and leaves the output
unchanged on failure. Tab width 0 rounds to the tab width of a new
buffer, so TypeScript passes 0 for the default and keeps no second copy
of it.
Both entry points share one native function, `Context.measureEditText`.
It adds the width of each line between LF, CR, and CRLF, as
`textToSegments` splits them, and one per break. It does not build
segments, so neither entry point allocates any more. `validateTextBytes`
takes the tab width instead of a buffer.
Each native call needs a Context, so the library owns one for these
measures: `FFIRenderLib` creates it on the first call and releases it in
`dispose()`, as it does for audio engines. A module-level
`ResourceContext` would be smaller, but `dispose()` refuses while any
other Context is live, so one measure would make the public
`resolveRenderLib().dispose()` fail with no way to release that Context.
No test or tool otherwise checks for leaked Contexts. Creating the
Context and measuring need no Yoga mutation and use read admission, so a
measure works in input handlers, during render, and in a layout
callback, as `EditBuffer.measureText()` does.
A differential table in `edit-buffer.test.ts` runs under Bun and Node.
For every public width method and the tab widths default, 0, 1, 3, 8,
and 255, it measures C0 controls, DEL, C1, tabs, CJK with a combining
mark, ZWJ, skin-tone, and flag emoji, CR, LF, CRLF, mixed lines, a CRLF
across the 16-byte blocks of `findLineBreaks` before a long line, and the
empty string. `measureEditText()`, `measureText()`, and the end offset
after `setText()` agree on each. New rows in the native malformed-argument
table cover a null span, malformed UTF-8, an unknown width method, tab
width 256, a null output, and one byte over the limit; one byte less
measures the widest tabs within u32. The dispose test measures first in
a Yoga callback, keeps the measure Context through a refused dispose,
and releases it in the next. Hidden controls, CRLF as two breaks, LF-only
breaks, no break count, no tab rounding, a wrong default, each removed
argument check, write admission, an `assertMutable()` guard, and each
dispose change make a test fail.
Native API
OpenTUI uses Context-owned scenes and Sessions for production rendering, including text, editors, custom paint hooks, images, detached surfaces, and split output. Standalone resources use the same checked ownership model without a terminal.
Read Resources and ownership for resource bindings, text copy units, and scoped framebuffer access. Frames and output defines mutation admission, painted drafts, and transport completion. How Core uses native explains TypeScript staging and resource ownership. Host I/O and time defines Context file operations, Session deadlines, and native diagnostic clocks.
API surfaces
src/opentui.zigis the public Zig module. It exports the checkedContextAPI and raw Zig primitives, includingCliRenderer,NativeRenderable,OptimizedBuffer, text buffers, and pools. Callers manage the lifetimes of raw primitives. Importing a raw primitive does not add Context checks to it.include/opentui.hdefines the checkedot_*C ABI for Contexts, Sessions, scenes, drawing, text, editors, styles, leases, clipboard, and diagnostics. The ABI is experimental and at version 1. Core renders through it.../core/src/zig.tssupplies TypeScript wrappers over that checked ABI. Its checked signatures, callbacks, constants, and record layouts come fromnative-abi.generated.ts.
ABI generation and builds
Use C headers and libraries from the same revision. Set each versioned record's
exact struct_size and abi_version, and leave unused flags and reserved fields
zero. Follow the output and failure contract of each operation in the header.
From packages/core:
bun run generate:abi
bun run check:abi
bun run test:abi
scripts/native-abi.ts uses Zig Translate-C and
scripts/native-abi.zig reflection to derive scalar
widths, signatures, callback types, constants, record sizes, alignment, and field
offsets from the header. Pointer nullability, retention, address fields, and portable
buffer/ptr policy live in
scripts/native-abi-pointers.ts, because C
types cannot prove lifetimes. Review that metadata when ownership contracts change.
Do not edit generated bindings. check:abi detects stale output. Use
bun run check:abi --all-targets to also compare the layouts of all supported targets.
An unsupported record shape or calling convention fails the script. It does not
produce partial metadata. C compiler assertions also check complete function and
callback prototypes, record layouts, field types, and constant values. Translate-C
alone is not enough, because it can drop callback calling-convention attributes and
ignore #pragma pack.
From packages/native, bun run build installs the header and libraries under
lib/<target>/ for the host target. Linux and macOS produce libopentui.a beside
the shared library. Windows produces opentui-static.lib, opentui.lib for DLL
imports, and opentui.dll. Static linkage also needs the platform and C++ runtime
libraries. zig build -Dall builds all supported targets.
zig build -Dlibrary-target=<target> builds one target.
zig build test-abi --summary all
This command runs the C fixture against the static and shared libraries on the host.
On a glibc Linux host, the fixture targets glibc 2.17. check:abi --all-targets
checks layouts for all eight supported targets. It does not test macOS or Windows
runtime linkage or terminal behavior.
The external examples/hello package imports the public Zig module
without JavaScript.