yawn/docs/packages/core.md

Core and render data

@yawn/core is a protocol client. It manages the command ring, payload handshakes, graph lifecycle, and typed views over shared render-data arrays.

Fast-path shared writes

Standard instance APIs validate [slot, generation], then write the corresponding guarded SOA row. They do not enqueue a renderer command.

core.setInstanceTransform(instanceHandle, matrix);
core.setInstanceType(instanceHandle, sixteenU32Words);

The convenience Instance methods in @yawn/mesh-handles call exactly these APIs.

Request an SOA column

Array creation is intentionally an infrequent worker command. Choose a domain so core can keep the array's logical length synchronized with fixed, mesh, or instance capacity.

const velocity = await core.allocateArray({
  name: "instance.velocity",
  domain: "instance",
  scalar: "f32",
  lanes: 4,
});

velocity.write(instanceHandle[0], [1, 0, 0, 0]);

Every stride is a multiple of 16 bytes, keeping rows suitable for vectorized consumers. SharedSoaArray uses atomic lane access and refreshes its typed views when shared WASM memory grows.

Share a column with another worker

Use share() only during setup. It returns the shared backing buffer and wire descriptor needed to construct a compatible view in another package or worker.

const { buffer, descriptor } = velocity.share();
simulationWorker.postMessage({ type: "velocity-layout", buffer, descriptor });

The SharedArrayBuffer is shared, not transferred. Once installed, the simulation worker should mutate rows directly and reserve messages for layout or lifecycle changes.

Graph lifecycle

Core accepts one graph format: the serialized S-expression produced by @yawn/render-graph-ast.

const compiled = await core.compileGraph(serializedAst);
await core.switchCompiledGraph(compiled.compiledId);
await core.dropCompiledGraph(oldCompiledId);

Graph operations are serialized by the client so compile, switch, and drop cannot race each other on one core instance.