Struct InkRoot

Source

pub struct InkRoot { /* private fields */ }

Expand description

The real InkRoot: owns the persistent DOM arena, the per-frame transport writer, the JS transform dispatcher, and the cursor-dirty gate.

Implementations§

Source §

impl InkRoot

Source

pub fn new( transform_dispatcher: Function<'_, FnArgs<(u32, String, u32)>, String>, ) -> Result<Self>

new(transform_dispatcher) — immediately create_ref() the supplied Function and store the resulting FunctionRef. The Function handle itself does not outlive this call; the FunctionRef does. The arena and frame writer start empty; the JS reconciler builds the tree via commit.

Source

pub fn commit(&mut self, ops: Buffer) -> Result<()>

commit(ops) — apply a batch of DOM mutations transactionally.

Decodes the ENTIRE op buffer first (M3-C decode_ops). Because the decoder is all-or-nothing, a malformed buffer returns a typed napi error with ZERO arena mutation — prior DOM state is preserved. Only a fully decoded Vec<Op> is handed to dom::apply. The id-magnitude bound runs before apply to keep the arena’s resize_with out of OOM-abort range.

Source

pub fn render_frame( &mut self, env: Env, mode: RenderMode, opts: RenderOpts, ) -> Result<Option<FrameResult>>

render_frame(env, mode, opts) -> Option<FrameResult> — the production render path (M3-E keystone).

Pipeline: style the arena through the core entry (render_styled, M3-B), dispatching each has_transform node’s transform to the stored JS dispatcher mid-walk; render the <Static> subtree once via render_static (renderer.ts’s second pass — "" when the tree has no static node); then wire the live (string, height) plus the static string into FrameWriter::write_frame and return its diffed bytes.

Ordering (the M3-0 throw-discard template): render_styled builds the whole styled string into LOCALS, firing every dispatcher call during its walk — BEFORE any FrameWriter mutation. A dispatcher throw is captured in err_cell and surfaces as this method’s Err before write_frame runs, so a failed render leaves the writer’s diff baseline untouched.

Returns None when write_frame produced no bytes (a no-change frame: FrameWriter returns an empty Vec for an unchanged output), mirroring rt’s “willRender” no-op semantics; Some(FrameResult) otherwise.

Source

pub fn render_to_string( &mut self, env: Env, width: u16, color_level: u8, ) -> Result<String>

render_to_string(width, colorLevel) — one-shot debug render: a plain full frame of the committed arena at width, with NO diff-state mutation (it routes through render_frame’s Debug mode + throwaway writer). This is the surface the npm renderToString (M3-L) wires; it returns the visible string, so it MUST honor the detected color level just like render_frame.

color_level is the JS-detected chalk.level (0–3, the SAME value the npm renderToString threads into render_frame for the static-capture pass), so the returned border/Box-bg SGR matches ink: none at level 0, downgraded at 1/2, truecolor at 3.

Returns the plain styled output string (mode-independent: the same string render_styled produces), which is what renderToString returns. The transport bytes are irrelevant to a string query, so they are discarded.

Source

pub fn free(&mut self, id: u32) -> Result<()>

free(id) — JS-driven lifecycle without a Rust finalizer.

JS owns the u32 id space and calls this on detachDeletedInstance (M3-G). It applies a single Free op to the arena (drop one slot, no cascade — dom::apply semantics).

Reentrancy-guarded like commit/render_frame: free is a third &mut self.arena mutation, so a transform dispatcher re-entering it mid-walk would take &mut self.arena while the render holds &self.arena (aliasing UB) AND drop a node out of the very tree being walked. It reads rendering FIRST and rejects a reentrant call with the same catchable typed error. Returning Result<()> is what surfaces that throw to JS — the reconciler’s detachDeletedInstance must handle the (vanishingly rare) reentry rejection.

Source

pub fn set_cursor(&mut self, pos: Option<CursorPos>) -> Result<()>

set_cursor(pos) — store the cursor position and flip the cursor_dirty gate.

Mirrors ink’s render.setCursorPosition (log-update.ts:163-166) EXACTLY: cursorPosition = position; cursorDirty = true. inkferro now STORES pos in cursor_position (mapping the napi u32 CursorPos onto rt’s usize RtCursorPos) AND sets the dirty gate. The next render_frame resolves the ACTIVE cursor as active = cursor_dirty ? cursor_position : None (getActiveCursor, log-update.ts:43), passes it into FrameParams.cursor, and the rt composes the ink-faithful cursor escape bytes — so a cursor-only change on unchanged content now produces a frame (the useCursor/IME behavior).

None mirrors setCursorPosition(undefined): it CLEARS the stored position and (still) sets dirty, so the next render’s active cursor is None and the rt emits the hide sequence if a cursor was shown.

Reentrancy-guarded like commit: it writes &mut self.cursor_dirty/ &mut self.cursor_position, which a transform dispatcher re-entering mid-render would alias against the render’s read of the same fields. Reads rendering FIRST and rejects a reentrant call with the same catchable typed error, touching nothing else.

Source

pub fn measure(&self, id: u32) -> Rect

measure(id) -> Rect — read a node’s computed layout (M3-F).

Mirrors ink’s measureElement (dom.ts): returns a node’s computed {width, height, left, top}. inkferro has no stored engine (ADR-3 rebuilds per frame), so measure rebuilds the layout engine from the persistent arena at the last-rendered WIDTH and reads computed(id).

SEMANTICS — current-DOM-at-last-width, NOT a frozen last-layout snapshot. The rebuild reads the arena as it stands NOW, laid out at the last render’s width. In ink’s reconciler every commit is followed by a render in resetAfterCommit, so the arena and the last layout never diverge at a measure call (the M3-J call pattern is render→measure). Reading the live arena is also what makes the trust cases fall out for free: a node freed after the last render rebuilds WITHOUT it, so computed(id) is None → zero Rect — exactly the freed-id contract below. A cached last-layout rect would instead return STALE non-zero geometry for that freed id, which is why this rebuilds rather than caches. The only divergence from ink is the pathological commit-without-render-then-measure, which the reconciler flow does not produce.

TRUST BOUNDARY: id is an arbitrary u32 from JS. An unknown, freed, out-of-range, or never-laid-out id (including the no-render-yet case, where last_render_width is None) returns a ZERO Rect — NEVER a panic, NEVER an Err. This matches ink’s measureElement on an unmounted ref (yields zeros). measure is therefore infallible by contract.

Reentrancy: it takes &self, but a &self read aliased against render_frame’s &mut self is STILL UB under napi-rs v3. So it is guarded too — but, because measure must stay infallible for bad input, a reentry returns the SAME safe zero-Rect sentinel instead of erroring.

Source

pub fn measure_absolute(&self, id: u32) -> Rect

measureAbsolute(id) -> Rect — like InkRoot::measure, but left/ top are ABSOLUTE (root-relative) coordinates: the sum of the rounded parent-relative offsets down the ancestor chain, i.e. the cell where the renderer paints the node (#124). width/height are identical to measure’s.

Mirrors the jacob314/ink fork’s getBoundingBox accumulation (measure-element.ts: summing getComputedLeft/Top up parentNode), which compat6’s getBoundingBox shim is built on. ADDITIVE: measure’s parent-relative contract is untouched (wire/API covenant).

Same semantics, trust boundary, and reentrancy contract as measure: rebuilds the layout at the last-rendered width; an unknown, freed, out-of-range, never-laid-out, or no-render-yet id returns the ZERO Rect — never a panic, never an Err; a reentrant call returns the same zero sentinel.

Source

pub fn clear(&mut self) -> Result<Buffer>

clear() -> Buffer — ink’s log.clear() (M3-K3): erase the live frame and zero the diff baseline, returning the erase bytes for the JS Ink (the sole stream writer) to emit.

Thin bridge over FrameWriter::clear: returns eraseLines(prevHeight) and zeroes the LineDiff baseline so the next repaint is full, while PRESERVING last_output* (so restore_last_output/sync_baseline can repaint / re-pin afterwards). The one shared erase-emitting gesture the K3 orchestration composes: interactive writeToStdout, instance.clear(), and resize-shrink all start here.

Reentrancy-guarded like commit/render_frame: it mutates &mut self.frame_writer, which a transform dispatcher re-entering mid-render would alias against the render’s own &mut frame_writer (the napi-v3 segfault-on-reentry path). Reads rendering FIRST and rejects a reentrant call with the same catchable typed error, touching nothing else.

Source

pub fn sync_baseline(&mut self) -> Result<()>

sync_baseline() — ink’s log.sync(lastOutputToRender || lastOutput + '\n') (M3-K3): re-pin the diff baseline to the current on-screen frame WITHOUT emitting any bytes.

Thin bridge over FrameWriter::sync_baseline. Returns nothing (it writes no bytes — the pure-path LineDiff::sync is byte-free): instance.clear() composes write(clear()); sync_baseline() so a subsequent unchanged re-render diffs to a no-op (ink’s “unmount’s final onRender sees it as unchanged and log-update skips it”).