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 & < > — <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-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.