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.