Crate pathland_core 

pathland-core

The 16-byte fixed-size opcode engine for Pathland: fixed-size opcodes, a single-producer ring buffer, a bump arena for variable-length data, and the linear-memory layout shared with host renderers.

This crate is no_std + alloc. It has no runtime dependencies.

Producer (guest engine)

use pathland_core::{init_memory, Guest, MemoryLayout};

let layout = MemoryLayout::default();
let mut mem = vec![0u8; layout.total_bytes()];
init_memory(&mut mem, &layout);

let mut guest = Guest::new(&mut mem, &layout);
guest.begin_frame();
guest.create_node(1, pathland_core::component_type::VSTACK).unwrap();
guest.insert_child(0, 1, pathland_core::APPEND).unwrap();
guest.set_property(1, pathland_core::property_id::SPACING, pathland_core::value_type::F32, 4.0f32.to_bits()).unwrap();
guest.end_frame(); // publishes frameCount

Consumer (host renderer)

use pathland_core::{init_memory, Guest, Host, MemoryLayout};
let mut host = Host::new(&mut mem, &layout);
for frame in host.frames() {
    for op in frame.opcodes() {
        println!("{:?}", op);
    }
}

Modules

border_edges

Bits for the BORDER_EDGES style property (a u32 bitmask).

category

Opcode categories (Category field, u8).

component_type

Component types (u16, encoded in the low half of B of TREE::CREATE_NODE).

environment

Environment field ids for META::ENVIRONMENT (host → guest).

event

Commands within the EVENT category.

fit

The SizeThatFits fit rule — the single spec’d selection algorithm every renderer and host share (spec/PRIMITIVES.md §SizeThatFits). Given the slot’s allocated width and the app-declared candidate thresholds (ascending), it returns the selected candidate index.

flag

Flag bits used across categories.

icon

Canonical icon names (ICON_NAME values; spec/ICONS.md).

listener

Bits for the EVENT_LISTENERS semantic property (a u32 bitmask).

meta

Commands within the META category.

parameter

Commands within the PARAMETER category.

property_id

Property IDs (u16, encoded in the low half of B of PARAMETER::SET_PROPERTY).

role

Semantic-role codes for the ROLE semantic property (0x2001).

size

Special size constants for WIDTH / HEIGHT.

text_style

Predefined typography codes for the TEXT_STYLE property (see spec/MODIFIERS.md). Each value selects a whole typography from the design system (font size/weight/design). The heading styles (LargeTitle through Headline) imply a heading element when applied to a TEXT: the renderer emits <h1>–<h5> (the level comes from the style — no ROLE needed). The non-heading styles render as plain <span> text. A raw font modifier (FONT_SIZE, FONT_WEIGHT, FONT_FAMILY, …) never implies a heading — it only overrides the typography’s visual.

tokens

Design-token resolution (spec/TOKENS.md) — the reference implementation.

tree

Commands within the TREE category.

value_type

Value types for PARAMETER properties (u8, encoded in the high byte of B).

Structs

Frame

A completed frame produced by the guest: a sequence of opcodes plus arena access.

FrameIter

Iterator over the opcodes in a Frame.

Guest

Producer side: the guest engine writing opcodes and arena data into shared linear memory. Owns the header, ring, and arena regions as disjoint slices.

Host

Consumer side: the host renderer reading completed frames.

MemoryLayout

The fixed layout of the shared linear memory.

Opcode

A fixed-size 16-byte opcode.

SharedHeader

Accessor for a shared-memory ring header, for consumers that read the ring in place (zero-copy) without a Host handle — e.g. a foreign driver that holds a raw pointer to the shared linear memory.

Enums

ArenaError

Errors produced by the arena.

Event

A raw-input event (host → guest).

EventError

Error decoding a raw-input event from an opcode.

RingError

Errors produced by the ring producer.

Constants

APPEND

Sentinel for append positions (index = u32::MAX).

OPCODE_SIZE

Size of one opcode in bytes.

Functions

init_memory

Initialize the linear memory header for a layout. Call once at startup before creating a Guest or Host.

value_type_for

The protocol value type for a property id.