Engine Call Contract

The engine call contract

Two rules decide almost every API question in this package. Both were arrived at by getting them wrong first.

A call answers, or it throws where it was written

An engine call is synchronous and takes no resource that could be missing: a font is required at construction, text and spans are validated there, and constraints are checked by the call itself. Nothing is left to wait for and nothing is left for a caller to get wrong, so there is no failure to hand back.

• Return the answer. layout() returns metrics. glyphs() returns the inspection. No { ok } union, no nullable, no out-of-band error to consult afterwards.
• Throw for input the language let them express but which has no meaning. { mode: 'at-most', size: NaN } is well-typed and means nothing; there is no width it could stand for, so there is nothing to return, clamp, or guess. Throw from the call, name the axis or the span or the offset, and let the stack point at the caller. Silently accepting it turns a wiring bug into wrong text on screen, which is worse than an exception.
• Never return or proactively scan for a failure the caller cannot cause. A result union for an engine defect makes every caller write if (result.ok) forever -- inside a flexbox measure callback, many times per layout -- to guard a branch that only means this package is broken. A deep runtime validator adds the same ceremony inside Glyph. Prove package-owned invariants at their producer; if corruption is encountered naturally, let the operation throw.
• Never enter a broken state that outlives the call. A rejected frame must not leave the engine refusing work, recompiling an invalid frame at frame rate, or holding a latch a caller has to clear. Report once, stop, and keep the rest of the scene live: transforms, visibility, and render order belong to the last accepted publication and never entered the frame that was refused.

The distinction that matters, in one line: a throw is the caller's arithmetic; a persistent failure is our defect. Neither is a return value.

Making the throw unnecessary

Prefer a shape that cannot express the mistake over a check that catches it.

• Structural authoring beats offsets. txt and span derive ranges from what was written, so an inverted range, a past-end range, and a partial overlap are unrepresentable rather than validated.
• A brand beats a convention. GlyphRenderer.decode() receives one borrowed CommandBufferView whose projected sequences expire with that synchronous call; the public API has no owned render-publication escape hatch. Cross-realm font movement is instead explicit through FontFace.clone(), whose serialized data and transfer list have their own versioned contract.
• Where the language cannot express the domain -- there is no finite-nonnegative number type -- the throw is the honest floor. Record it as a known limit rather than defending it as ideal.