package reference

Registry keys

An element declaration 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 extension guide, 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: a Leaf element 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 user 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 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 originates a standing Ask for the user.

Full contract

The Ask states when it is answered as a condition on the widget's standing state (answered), so the answer is a reading of state the fold already keeps rather than a flag beside it, and the action whose admission makes that condition hold is the one admission marks as the answer. The banner's count, the a/A ask walk that steps asks, and the command reference dialog's row 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-thread-seat puts a box under its own Ask, and a thread standing in that box takes the Ask off the user'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. An ordinary reply or resolve hands the thread back. 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 Leaf elements that originate Asks, answered says which standing state answers one, and all names a blanket answer offered by the banner.

x-bound

The element holds its own height and scrolls inside it, so a long log or feed never grows the page: start opens at its first line and end follows its newest entry while the user is at the end, and stays where the user scrolled back to otherwise. An authored occurrence may state or override it with data-bound=start|end; the runtime paints it as data-lf-bound.

x-content

The content model: markup (children are the author's markup), members (children are this element's own member elements and nothing else), data (one <pre> holding text in the notation the description names, with & < > escaped as &amp; &lt; &gt; — <pre> because it is the only thing in HTML that says whitespace is load-bearing without a stylesheet to read), or empty. Required.

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. The input follows the source's 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 element declaration, 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-history

true: the module renders the page's history, so a page whose markup holds one is served the history reading beside its state and a page without one does not pay for it.

Full contract

The reading is the newest 50 logged moves, newest first, each naming who moved, what they did, the thread it belongs to and that thread's title, whether a later undo took it back, and for a widget gesture the words its ids had in the document it was made in, so a later version rewording or removing what was chosen leaves the row as made. The module reads it through watchHistory.

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 line references into the nearest data body — the element's own <pre>, or its enclosing data element's (a note's at names a line of its code block) — which version check refuses outside the body.

Full contract

A reference names a line by the number that body's x-numbering gives it, 1-based when it has none; a number inside a gap the numbering leaves is in the body.

x-measure

How the element uses the width of the frame holding it.

Full contract

text keeps the reading measure inside a frame wider than the column, and is what an undeclared element is unless it is made of members (x-content: members), which groups them by default. A members element declares text when its members are the cells of one block it draws: a choose group's frame, dividers and marks belong to its options, so the group keeps the measure as a whole and each option fills it, where grouping left every option at the measure inside a frame drawn across the whole cell. surface (a chart, table, log or listing) fills the frame; x-space wide or available implies it. group only holds other blocks (tabs, a comparison, a grid, a pane), so it passes the measure through to them instead of holding everything it contains to the width of a paragraph. The runtime paints the declaration as data-lf-measure; the theme declares the plain HTML elements the same way.

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-name

The attribute whose value is this tag's title: what the page calls one of these elements when it names it away from itself, as the activity feed does for where something happened.

Full contract

Leave it off where the authoring contract already titles the element: a section by its heading, a disclosure by its summary, a titled member by its leading <strong>. Declare it where an attribute is the title instead, as a column's or a tab's label is. An attribute the element merely shows first, such as a metric's value or a chronology entry's time, is not its title.

x-numbering

The attribute giving the source line numbers a data body quotes, as ascending ranges ("1505-1507,1520-1527").

Full contract

version check holds it to one number per body line; a gap between ranges is lines the body leaves out, and every x-lines reference into that body names lines by these numbers.

x-outline

The element that lists the page's own headings.

Full contract

version check advises a page with two or more headings below its title and no such element to place one near its opening, and names the tag declared here. A layer that ships no outline widget draws no such advice. What the outline shows and how it sits is the widget's own.

x-owners

The element declarations that may directly own a Leaf element.

Full contract

Read from an owner, this defines which direct child Leaf elements are its members rather than nested elements it merely contains; a gesture the owner takes on its whole box stops at those members.

x-page-navigation

The first such element placed directly in main becomes the page's view navigation, whatever else main holds beside it. version check then treats it as the page's outline and does not advise an aside.sidebar of contents. Other placements retain the element's embedded presentation.

x-paints

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

Full contract

The runtime speaks each to a user 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-reading-role

The structural role an element supplies: workspace keeps task regions together between optional header/footer slots around exactly one body element, pane is one labeled reading region with exactly one body element between its optional header and footer, and grid places its direct children as cells in two dimensions.

Full contract

Role-derived validation reads this declaration rather than tag names, and version check advises against page CSS that places an element declaring a role. Every role keeps markup content so packages may contribute differently named structural elements without joining a closed parent-child vocabulary. Every role requires a string id; a pane also requires a string label, which names its accessible region while a visible heading belongs in its authored header. A workspace or pane may hold one direct native header first and one footer last.

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. In the browser a declared attribute is what a module hands navigateToDatum and the experimental indicate to reach the named widget, which each resolves in the owner's own authored document first (its message's markup, for a widget in a reply) and then in the page.

x-request

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

Full contract

Authored holders use offers to name direct child controls; each live holder offers at least one verb. A projected holder uses records to name an x-data input whose contract declares the row array and stable string key; its verbs are offered without authored children. verbs declares each command's complete detail schema. bind checks required string detail fields against immutable holder attributes or required string fields in the selected record. ask: true makes the ready lifecycle a user Ask: acceptance hands the turn to the host, pending and completed leave the user's list, and failure returns it. region: true says the holder supplies the commands but not its own question title, so every matching Leaf element stands inside an x-ask-surface whose leading direct heading owns the reading and arrival. Every request has a document, widget, and unit seat. Authored requests use the holder id as their unit; projected requests use the record key. A page seat lasts for its revision, while a thread seat lasts for that document. A projected holder contributes one Ask while any displayed row is ready. Pending excludes another request on that seat, failure reopens it, and success completes it. Each request is durable and not undoable because the host may already have acted. leaf experimental receipt appends exactly one linked succeeded or failed outcome, and the widget controller supplies the server-projected request seat, exact request/receipt attempts, latest attempt, and ready/pending/completed phase to its package module. A projected row reads and dispatches through request(key) on that controller. 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-required-members

Required role-complete members.

Full contract

Each member names a direct child element declaration, and one-each names that member's required string-enum attribute. A compound owner must contain exactly one such member for every enum value, so a package can declare fixed semantic slots without teaching Leaf its tags or roles. The owner uses x-content: members, and the member names the owner in x-owners.

x-retired-when

On a member: the owner's decision outcome that takes this element off the page (a suggestion's lf-old under accept).

Full contract

Requires x-owners. The outcome is a value of the outcome detail field on the owner's one deciding verb, 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 owner and data-lf-retired on the members that outcome retires, takes both off when undo or a retraction removes the deciding action from the fold, and one theme rule hides the marked members — so no module owes any of it, though one may paint the same sooner as its own gesture (renderRetired). Those attributes are rendered output for CSS, export, and checks; semantic consumers read the publisher's explicit outcome rather than reading them back. The file's reading takes the fact from the log, and version check licenses dropping the member's ids on it; version check --render reports a settled member still showing words, or a mark the log never decided.

x-says

Attributes whose values the user 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 a declaration names two at that edge they render in the order the declaration 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-space

The default width capacity an element needs beyond the prose measure: wide takes the vocabulary's shared capped evidence width, while available takes all room the page shell can give after enclosing frames, chrome, and actual margin residents.

Full contract

The declaration says nothing about how the package arranges content inside that allocation. An authored occurrence may override the default with data-width=column|wide|available; the runtime resolves that choice into data-lf-space and the theme allocates it without moving the prose axis.

x-state

What x-state declares, once per widget with state: each verb's detail schema (the payload half of the log's forever-contract), its fold unit, the record form its state takes in markup, and who writes it.

Full contract

A verb is the user's unless it declares writer: "agent": the user writes theirs through the page as action events, and the agent reports its own through leaf experimental report as report events, so every coordinate has one writer. A user verb may declare a created child (creates). An agent verb requires a record form other than body, since a report moves declared state and never the page's words, which keeps the passage reading untouched by it; it may name with update the required non-empty string detail field that is the report's short human-readable news, which the canonical update feed exposes without guessing from a widget, verb, or field name. The runtime paints a standing report live (data-lf-reported); it is provisional news, standing only until a version answers it, as $report says. Each verb is its own state: the owning Leaf element, the unit, and the verb together name one independently standing fact, the latest surviving action of that verb there supersedes its predecessors, and different verbs coexist. The framework composes the last surviving action per coordinate with typed authored values and gives every widget its complete state through renderState, keyed by verb, 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, except for a position whose container the version changes, which it writes), construction-linked inspection, the runtime's user- and report-origin readings, and the version diff's state half. When an action's admission makes its widget's x-awaits answered condition hold, admission records meaning.answer on it: the widget's authored resolves attribute, read from the sending document, names the comment thread the answer closes, and null answers without closing one, which is also what a decision whose outcome is the widget's x-withdrawn-as records: it leaves the page as if nothing had been proposed. Historical settlement uses the admitted owner-unit-verb coordinate even after the widget retires. One detail field name is reserved: outcome, on the one user widget-unit verb that decides which retirable members leave the page (x-retired-when). The unit, creates, and record forms are $state's.

x-text-format

Inline Markdown in this element's direct text nodes.

Full contract

Its existing element children remain HTML. The browser formats those words with the shared safe Markdown parser, while file-side passage and revision readings use the same visible words. A generated child with this declaration interprets the user's line breaks as hard breaks; source HTML line wraps remain ordinary whitespace.

x-thread-seat

The module places a threadBox in each matching Leaf element, selected by authored, static when attributes (an attribute written by an x-state 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 user deals with it in words: the Ask leaves their list while that thread 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 the Ask still reads as unanswered. A hold comment is a seat thread 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-thread-surface

The upgraded widget can seat the canonical response composer and Thread views beside exact projected datums.

Full contract

Its module subscribes through consumeThreads, selects Threads from the public collection, and places them in its own outlets. The returned handle can open Comment from one of the widget's projected elements. Leaf owns anchors, drafts, response modes, submission, Thread rendering, reply and reaction state, settlement, focus, receipts, and margin-projection fallback. A placement claims that active composer or Thread locally for the current reconciliation; unloaded, filtered, collapsed, outdated, or otherwise undisplayable datums receive no placement 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 that preserves its own authored words and the order and identity of nested upgraded widget boundaries, which makes those words quotable.

Full contract

Each nested upgraded widget keeps its own word and fence contract, so its generated rendering is not a claim by the wrapper. Without this promise the passage reader treats the widget as opaque, since its module may insert or replace words. The render gate refuses changed wrapper prose or removed and reordered nested ownership boundaries.

x-visual

How a rendered picture exposes stable Comment targets.

Full contract

whole anchors the picture on the authored widget. Every declared provider also supplies its own visual surface for whole-widget aim and marks, so chrome paint stays above the widget's drawing. For {parts: ATTR} or {prefixes: [PREFIX, …]}, its module calls registerVisualParts(source, read) once; read returns the complete current {id, element, label, surface?} inventory. Core admits only ids authored in ATTR or, under prefixes, any longer id one of them begins, such as commit:3f2a under commit:: a picture drawn from data whose parts the author cannot list declares their kinds rather than enumerating them. Core 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. A visual that draws its parts over time passes registerVisualParts(source, read, {reveal}): reveal(id) synchronously draws a state whose inventory holds that declared part. A declared part absent from the current state then places its threads on the whole picture, and thread travel calls reveal before landing on the part. The registration's update() signals any rendering or geometry change, including an in-place attribute or style change. The render gate validates every record, requires each authored token to resolve, in the current state or after its reveal, and refuses a registered id its prefixes do not admit.

x-withdrawn-as

On a holder with retirable slots: the outcome an undecided Leaf element stands as when a later version takes it back unanswered — a withdrawn suggestion leaves the page where a reject outcome would — which is what lets that version drop the ids inside the slots the outcome retires.

Full contract

The same outcome chosen by the user declines the proposal, so it answers the Ask without closing the widget's resolves thread. 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

true: this widget is a block prose seat that can admit leaf status --on without a pending user move, so the work shows as local chrome beside its authored markup.

Full contract

Only a block widget whose x-content is markup may declare it. Once admitted, a page-widget claim appears at the page edge through its target margin entry even if a later layer drops x-work. The declaration is permission for runtime chrome, not a consequence of x-content: markup may itself be an owner gesture or sit in a hidden panel.