package reference

Registry keys

A widget entry begins as JSON Schema. Its x-* keys tell Leaf how the element reads, renders, changes, and joins the collaboration loop. Choose a key below to jump to its summary. Longer contracts open in place.

This reference is generated from the registry's $keys, the same entry an agent can query in a page's merged registry.json. Start with the package tutorial, or read the complete package contract.

Find a declaration

The index jumps to a summary. Longer entries keep their full contract one click away.

x-ask-surface

What x-ask-surface declares: an instance is the complete reading and arrival region for exactly one non-quoted nested local Ask declared by x-awaits or x-request.ask.

Full contract

The region begins with one direct heading, then carries any context and evidence the reader needs before the control; the nested widget still owns the answer and its fold or Request lifecycle. The banner, Asks tray, a/A ask walk, standing ring, and page state name the region while action eligibility, replay, and Request projection name the nested widget. An arrival focuses that widget's answering control but scrolls to the region's start. version check requires the leading heading and one non-quoted nested Ask source so the two identities cannot be ambiguous.

x-awaits

What x-awaits declares: a tag either originates a standing Ask for the reader or, with rollup: true, aggregates descendant Asks through a nested plan.

Full contract

A local Ask always names the x-state verbs that answer it. The standing answer is identified by its owning widget and verb, so its complete durable record may fold on the widget or on a detail-named part; no parallel completion flag is needed. A roll-up owner can expose and gate on descendant Asks without entering the Asks list itself. The banner's count, the a/A ask walk that steps asks, the ? overlay's row, and conditional x-state actions are readings of one projection, so nothing names a tag and a new widget joins by declaring. Quoted material decides nothing — an exhibited Ask is a mention (x-exhibit). region says the widget supplies the answer control but not its own title: every matching local Ask must stand inside an x-ask-surface, whose direct heading owns the question's reading and arrival. A widget that also declares x-conversation puts a box under its own Ask, and a conversation standing in that box takes the Ask off the reader's list for as long as it waits on the agent — whoever opened it. That is not an answer: the widget's state is untouched, so a version still has to record what the words settled, and an action's requires reads the Ask as open. An ordinary reply or resolve hands the conversation back. A version-response conversation takes no reply; only authored state in a later version that answers an originating open Ask, or changes its declared answer when the Ask was already answered, unlocks the agent's resolve. Reader actions in the log do not substitute for that version. A widget inside a thread presents an Ask like one on the page, with one bound set by frozen thread markup: the thread's own reply box is already that seat, so only an action can answer it there. when selects Ask instances, answers names exactly the x-state verbs that settle one, rollup carries the logical OR of descendant Asks, until can require a distinct completion verb for a matching thread Ask, and all names a blanket answer offered by the banner.

x-children

Required role-complete item children.

Full contract

Each member names a direct child widget and one-each names that child's required string-enum attribute. An instance must contain exactly one such child for every enum value, so a package can declare fixed semantic slots without teaching Leaf its tags or roles. The parent uses x-content: items, and the child names the parent in x-parent.

x-content

The content model: prose (children are the author's markup), items (children are this widget's own item elements and nothing else), data (one <pre> holding text in the notation the description names, < > escaped — <pre> because it is the only thing in HTML that says whitespace is load-bearing without a stylesheet to read), or none. Required.

x-conversation

The module places a conversationBox in each page instance matching authored, static when attributes (an attribute written by an x-state or x-report value record cannot drive this predicate).

Full contract

It projects exact-section threads textually from the whole log; Threads keeps the complete interactive view. Thread markup and quoted material take no second view. Where the widget also originates a local x-awaits Ask, the seat is where the reader deals with it in words: the Ask leaves their list while that conversation waits on the agent, rather than being counted a second time under a box they have already used. It is not an answer — the widget's own state is untouched, so its controls still work and an action's requires still reads the Ask as open. A conversation with response: {kind: version, verb: <answer>} carries that declaration on its root comment, has no inline reply control, and refuses leaf reply: the agent either incorporates it in a later version or opens a separate thread when that revision depends on the reader. To unlock resolve, authored state in the later version must answer an originating open Ask, or change the named answer's authored record when the Ask was already answered. Reader actions in the log do not substitute for that version. The named verb must be one of x-awaits' answers with an attribute or value record, so the resolve gate can compare the originating and current versions without naming a widget. A hold comment is such a conversation like any other. hold labels a stronger send route whose comment carries holds naming this widget: that route remains available after ordinary roots, the unresolved held thread is the hold, resolution releases it, and undoing resolution restores it atomically. Dropping the widget drops only the inline view.

x-data

The widget's named external-data inputs.

Full contract

Each input names a $data.contracts contract and the declared canonical string attribute whose authored value is this page's source id. An optional snapshot names a declared positive-decimal attribute that selects an immutable source snapshot; without it the input follows the current value. An optional source attribute leaves that input absent; watchData delivers null. Several widgets may bind the same source to the same contract. Across immutable versions and widgets frozen into threads, one source cannot mean two contracts; use a new source id for a new meaning. A module subscribes by widget and input name, never by a package-owned source name.

x-example

Authored markup exhibiting the widget, valid against the merged registry: an agent reads it with the widget entry, writes from it, and the lint refuses one that does not validate.

x-exhibit

The element quotes what it holds rather than speaking it — a mention, not a use: interactive widgets inside take no input (a choose group no clicks, a board no drags, a suggestion no decision), and an Ask inside it counts for nothing. A module asks quoted(el) before wiring any input, and the theme's affordance rules — the hand, the lift, the joined shape — stand down inside it on their own.

x-guidance

Audience-specific authoring or operating guidance owned by this widget. page guidance composes it with data-contract guidance and package-wide guidance, so instructions travel with the contribution they explain rather than with whichever package happened to distribute it.

x-inline

The element is set among the words around it, so the render gate holds its box to no width of its own and the rule that a block widget stands in a block slot passes over it.

x-language

The attribute that names a code language, held to $languages.names — the one list this page colors from — so a second tag taking a language costs a declaration and no new reader.

x-lines

Attributes holding 1-based line references into the nearest data body — the element's own <pre>, or its holder's (a note's at names a line of its code block) — which version check refuses outside the body.

x-measured

A scalar in authored content pinned to one x-data input at an aware instant.

Full contract

input names the widget's data input and at names its required date-time attribute. The authored words remain frozen with the version; when that source's stored updated instant moves past at, version check advises that the measurement is stale and page state reports the same debt. The declaration compares runs, not age: a source that never updates creates no warning.

x-paints

Attributes the theme renders as paint alone — for example, a status marker's tint or an event's kind.

Full contract

The runtime speaks each to a reader listening (the value, or a flag attribute's own name), silently on screen and out of every selection, so a fact stated in ink is not silent to whoever cannot see it.

x-parent

The widgets an instance may be a direct child of — an item's holder — and, read the other way, what a container is made of: a gesture a container takes on its whole box stops at what it holds, and this is where it reads which children are its own rather than things it merely contains.

x-refers

A map from attributes whose values name another element to their target contracts.

Full contract

An empty contract accepts any element id (an option's for). A typed contract names a shared registry map with via and an equality predicate with where; version check then requires both an existing id and a target tag whose declaration in that package-owned map matches the predicate. This lets a package distinguish a goal, worker, or evidence reference without Leaf knowing those roles or tags. The runtime renders every valid value as a reference the reader can follow.

x-report

What x-report declares, once per widget with an agent channel: report verbs a worker folds onto the page through leaf report, each with a detail schema (the payload half of the log's forever-contract, exactly as x-state's), a semantic facet, a fold unit, and a required record form drawn from $state's vocabulary minus body.

Full contract

An optional update names the required non-empty string detail field that is the report's short human-readable news; naming it lets the canonical update feed expose those words without guessing from a widget, verb, or field name. The owning widget instance, unit, and facet together name one independently standing fact; verbs on the same tag and facet share their unit and record form, and an action outranks a report at that coordinate. A report moves declared state only, never the page's words, which is what keeps the passage reading untouched by it. The runtime paints a standing report live (data-lf-reported); it is provisional news, standing only until a version answers it. How a version answers a standing report is $report's.

x-request

One-shot operations the reader asks the external host to perform.

Full contract

offers maps each direct child widget tag to its required string-enum verb attribute, deriving the commands a particular holder presents; every live holder must carry at least one such direct offer and may offer each verb only once. verbs declares every command's complete detail schema. Optional bind maps required string detail fields to required immutable string attributes on this widget, so a crafted request cannot retarget the operation. ask: true makes the ready lifecycle a reader Ask: acceptance hands the turn to the host, pending and completed leave the reader's list, and failure returns it. region: true says the holder supplies the commands but not its own question title, so every instance stands inside an x-ask-surface whose leading direct heading owns the reading and arrival. A page holder has one lifecycle per revision; a holder in frozen thread markup has one for that document's whole lifetime. Pending excludes another request, failure reopens it, and success completes it. Each request is durable and not undoable because the host may already have acted. leaf receipt appends exactly one linked succeeded or failed outcome, and watchRequestLifecycle supplies the holder's server-projected request seat, exact request/receipt attempts, latest attempt, and ready/pending/completed phase to its package module. Leaf transports and validates the protocol but does not interpret verbs or execute them; package-owned guidance tells the host what each verb means, and external data carries replaceable evidence produced by it.

x-retired-when

On a slot: the holder's action outcome that takes this element off the page (a suggestion's lf-old under accept).

Full contract

Requires x-parent. Every outcome named by one holder's slots belongs to the same facet, so only one settlement can stand. The layer renders the settlement whole, following the log's standing state both ways — reconciliation paints data-lf-state="<outcome>" on the holder and data-lf-retired on the slots that outcome retires, takes both off when a later widget-unit verb on that facet displaces the decision in the fold, and one theme rule hides the marked slots — so no module owes any of it, though one may paint the same sooner as its own gesture (renderRetired). The file's reading takes the fact from the log, and version check licenses dropping the slot's ids on it; version check --render reports a settled slot still showing words, or a mark the log never decided.

x-says

Attributes whose values the reader sees as words, and where each renders.

Full contract

after goes inside the element's own content, ahead of the apparatus that ends it, so a word does not land on the far side of a control that closes the row. before goes at the element's start, ahead of chrome as well: leading chrome is not something the words stand beside, it is a module speaking for the whole element, so an element's opening words go above it; where an entry declares two at that edge they render in the order the entry lists them. The runtime writes them as selectable text the user can quote and comment on, where content: attr() would paint glyphs into no text node.

x-shadow

The module renders the page's words into an open shadow tree, which the passage walk, the selection capture and every question asked by id cross; a shadow root on a host whose entry lacks it is a render-gate finding.

x-state

What x-state declares, once per widget with an action channel: each verb's detail schema (the payload half of the log's forever-contract), its semantic facet, fold unit, optional current-state requires, optional generated-child creates, optional completion, and the record form its state takes in markup.

Full contract

The owning widget instance, unit, and facet together name one independently standing fact: verbs on the same tag and facet share their unit and record form, competing verbs there supersede one another, and distinct facets coexist. The framework composes the last surviving action per coordinate with typed authored values and gives every widget its complete state through renderState, and one declaration drives the POST and re-vendor contract gates, version check's state gate (a version whose markup actively contradicts the fold without restated is refused; writing the folded state is honoring; re-emitting the previous version's state is blessed silence), construction-linked inspection, the runtime's reader-origin mark, and the version diff's state half. The browser uses requires for its controls and common send door; POST interprets the same prerequisite against the authoritative fold under the append lock. One detail field name is reserved: resolves names the comment thread an x-awaits answer closes. Admission records its effect in meaning.answer: a thread id closes it, null answers without closing, and an absent field means the action is not an answer. Historical settlement uses the admitted owner-unit-facet coordinate even after the widget retires; independent facets on the widget coexist. A report cannot declare resolves. Optional references names additional string or string-array detail fields carrying element identities; fold units and attribute-set or position records already declare their own references. Admission snapshots those direct identities while retraction keeps reading current containment. The facet, unit, requires, creates, and record forms are $state's.

x-thread-surface

The upgraded widget can seat canonical Thread views beside exact projected datums.

Full contract

Its module registers one adapter through registerThreadSurface; the adapter owns only outlet geometry and visibility, while Leaf owns Thread rendering, reply and reaction state, settlement, focus, receipts, and living-margin fallback. Returning an outlet claims that thread locally for the current reconciliation; unloaded, filtered, collapsed, outdated, or otherwise undisplayable datums return no outlet and remain in the global Threads index plus the ordinary fallback.

x-tone

The attribute that names one of the layer's semantic tints, held to $tones.names, which the theme has a rule for.

x-upgrade

A module at widgets/<tag>.js enhances the element in the browser, imported where a page's markup carries the tag rather than for the whole layer. page init refuses a layer declaring it with no module beside it, and the render gate a module that defines no element for a widget the page contains. Required.

x-verbatim

An upgraded element whose body reaches the reader as its own words — the module leaves it in place — which is what makes it quotable; a body without it is source the widget renders (a diagram's notation). The render gate refuses an x-verbatim whose rendered words differ from the file's.

x-visual

How a rendered picture exposes stable Comment targets.

Full contract

whole anchors the picture on the authored widget. For {parts: ATTR}, its module calls registerVisualParts(source, read) once; read returns the complete current {id, element, label, surface?} inventory. Core admits only ids authored in ATTR and derives token lookup and deepest-part hit testing from that inventory. surface defaults to element and may name one descendant whose native paint excludes decoration from the contour. It changes paint only: element remains the semantic hit and travel target. Marks and aim follow an SVG surface's painted geometry primitives; a surface with none, and every other element, uses the shown box. Targeting a mapped part stores its id as anchor.visual while the widget remains the semantic seat. A missing token or registration detaches on replay rather than widening to the whole picture. The registration's update() signals any rendering or geometry change, including an in-place attribute or style change. The render gate validates every record and requires each authored token to resolve.

x-wide

The width model, for evidence set to its content rather than to the measure prose is read at: box (the widget lays its content out into whatever width it is given, a board's columns, so it stands at the one width the whole vocabulary shares) or drawing (the widget renders one thing drawn at a size of its own, a diagram's graph, so its box is the clip around it — the room the page has, with the drawing as near the column's axis as the claimed margins allow, and scrolling where even the room is short).

Full contract

A drawing declares no x-says: that box is laid out as a row holding what was drawn, so a word the layer writes into it would stand beside the drawing rather than over it, and the registry refuses the pair. Nothing is authored for it and no page asks: the theme grows the element out of the column into whichever margins are free. A margin holding something of the page's gives nothing where it holds it, and only there: an exhibit level with a note drops below it and then takes the whole width; one level with a suggestion's controls keeps its place and declines their side, a positioned row being nothing an exhibit can drop below; and one that nothing reaches keeps its place and grows both ways.

x-withdrawn-as

On a holder with retirable slots: the outcome an undecided instance stands as when a later version takes it back unanswered — a withdrawn suggestion leaves the page where a reject would — which is what lets that version drop the ids inside the slots the outcome retires. Hedged, because there the author asserts a state the user never gave: only whole, and never while a thread is anchored in it.

x-word

What x-word declares: this tag's own word for what it is comes from its module, which answers lfWord() on the element, rather than from the tag's name.

Full contract

Almost no widget declares it, and none needs to while one tag is one kind of thing: a name away from the page is then the tag with its prefix dropped. It is wrong where a tag holds several kinds. Every shape of lf-suggestion came out as "suggestion", so a row in the Asks tray named a deletion by the words it proposed to remove and read exactly like the insertion above it. The word is asked for wherever the page names an element away from itself — a tray row, a comment's anchor label — and an element that has not upgraded yet, or answers nothing, falls back to the tag. The same declaration lets the module answer lfSays() with its own words, for a tag whose text nodes run together away from its paint (a rewrite's old and new); an element answering nothing is read as text.

x-work

Where this widget can admit leaf status --on without a pending reader move: content names a block prose seat; conversation names the widget's declared x-conversation box and therefore inherits that box's own predicate.

Full contract

An optional when narrows the instances that may admit work under their replayed attributes. Once admitted, a page-widget claim appears at the page edge through its Target Button even if a later layer changes x-work. The declaration is permission for runtime chrome, not a consequence of x-content: prose may itself be a holder gesture or sit in a hidden panel.