Extending Leaf

Parts of a page

The agent writes an HTML document containing the page's title, description, content, and layout. When the server delivers it, Leaf adds the page identity, visual theme, browser JavaScript, and canonical URL. The browser runtime supplies the commenting and collaboration interface. Authors build the content with these tools, starting with ordinary HTML:

1. Ordinary HTML. Leaf's reading theme, which a page takes by default, styles headings, paragraphs, tables, code, and details without requiring CSS classes. These elements provide most of a page's content.
2. Theme classes. The theme supplies classes for common presentation patterns, including .eyebrow, .lede, .callout, aside.note in a layout-note row for a margin note, and ol.steps for a numbered sequence like this list.
3. Widgets. A widget is a complete page feature, authored as a custom HTML element, such as <lf-options> for choices and <lf-board> for cards in columns. Other lf-* elements provide structure, such as <lf-pane> for a pane. The registry declares each element’s attributes and behavior using JSON Schema. The browser, validator, and agent instructions read those same declarations.
4. Page-specific presentation. A local <style> and inline SVG can define arrangements and drawings specific to the page. They use the theme's shared color and type tokens to stay consistent with the rest of Leaf. The Layout tab's drawings use this approach.

Leaf elements load their JavaScript modules when the page uses them. Behavior specific to one page can use inline module scripts or local modules under page/. Reusable behavior belongs in a package, a directory containing element declarations and their supporting files. The page-behavior reference defines module and dependency rules.

Widgets

These examples are interactive parts of this page. Their choices, card moves, and comments share its event log and Undo; as samples, they ask nothing, so On Me stays empty. Each activity feed shows the same page history, including actions in other examples.

The widget catalog also includes diagrams, charts, diffs with collapsible files, annotated code, editable drafts, playgrounds, and recorded browser traces. The examples gallery opens complete pages using them.

Asking the user

Any widget can ask, whether bundled, from a package or the page’s own, by declaring x-awaits in its registry entry, which names the actions that answer it. To ask about content that asks nothing, such as a paragraph or a chart, or to leave the user a step such as trying a build, the agent opens a thread on that content or the page with a message sent with --obligation, and the user’s reply answers it. Nothing goes On Me that neither a widget nor a thread answers, so no item carries a generic Done, and Leaf adds no answer to a widget beyond those the widget declares.

Each ask joins the user's On Me list until the widget or thread that asks it is answered (On Me and the agent’s list).

Styles and overrides

The user chooses the visual direction. A theme supplies shared colors, type and reusable styles; widget packages draw their own controls; the author arranges the page and makes local adjustments.

flowchart TD
  accTitle: A page captures its selected theme
  accDescr: The author selects Editorial from the user's themes. Leaf captures that theme in the release-review page, and the export carries the same theme. Changing the user's default later changes neither existing copy.
  Themes["User's themes<br/>Editorial · Dense"] -->|select Editorial| Page["Release review<br/>Captured: Editorial"]
  Page -->|export| Export["Exported review<br/>Same Editorial theme"]

For stylesheet roles, cascade precedence and nested widget boundaries, see the CSS tab's contract.

Layouts

Leaf supplies page layouts and a layout for blocks within a page. A column, sidebar, or workspace sets the page’s shape; tiles arrange a block’s children and can be used within any of them. The table and drawings below show the same classes in the same order.

Leaf's Layout classes are ordinary CSS, applied beneath the page's own stylesheet in the cascade. A page can adjust them with CSS rules, for example to change a column's share of the width or a gap. It can also use its own grid when the supplied layouts do not fit.

The reading column

On a layout-column page, headings, paragraphs, lists, and code occupy a centred column up to 720px wide. On a sidebar page too, the theme limits paragraphs, list items, and headings to that reading width. A workspace applies neither the reading width nor the limits below: every block fills its pane.

A diagram, board, or wide table can extend into the margins beyond the reading column. The text above and below it keeps its width and position. These width settings control the block:

• column is the text measure. In a wider region, such as a sidebar page's body, a column block starts at the same left edge as the text.
• wide starts at the edge the text starts from (the left, in a left-to-right page) and extends toward its end, up to about 910px, enough for 100 columns of code. Wide blocks share this width so they align with one another.
• available uses the window's width after subtracting the outer page margins and space for margin notes and controls.

The registry, which declares each element's behavior, also gives it a default width. For example, lf-options uses column, lf-diff uses wide, and lf-board uses available. A data-width attribute asks for wide or available on any block, overriding the default. If the margins have unequal space, an available block extends farther into the wider margin. A table given one of these widths uses its columns' natural width, up to that limit, rather than stretching across the extra space.

A log, feed, or long listing with data-bound scrolls within a limited height and opens at its newest entry. Its growing content therefore does not make the whole page longer.

Margins

A sufficiently wide window places these controls and notes beside the reading column:

• The rail, on the right, where Leaf places a marker beside each commented or decided passage. It needs a window about 960px wide, or about 1010px on a touch screen. A sidebar page shows it from about 1920px, or from 640px with data-rail="right" on body. A workspace has no rail; a comment there shows as a pin on its block.
• A sidebar, an aside beside the body in layout-sidebar. Its authored layout-track holds contents, a legend or reference facts, and stays in view while the body scrolls when both fit beside each other.
• Sidenotes, each an aside.note paired with its passage in a layout-note row, on the right when the row has enough room.

The browser places these compositions as soon as the HTML arrives. In a narrow window, the sidebar stacks in source order and each note follows its passage. Notes never shift the reading column.

Sidebar pages

layout-sidebar on main places the header across the top, with a body and a narrower side column below it. The page fills the window up to 1600px, with an outer margin that grows from 24px to 64px. Its blocks and title share a left edge, while paragraphs still wrap at 720px.

The side column is an aside; placing it before or after the body in the HTML puts it on the left or right. The regions stack in HTML order below about 870px, or when the body's content needs the full width, such as a board with many columns.

For a reading page, give the body layout-column: prose keeps its reading measure while wide exhibits use the remaining room. A section.panel groups a region by its compact heading and spacing, without a surrounding card.

<main class="layout-sidebar">
  <header><h1>Release 4.2 rollout</h1></header>
  <div>…</div>      <!-- body: the work in progress -->
  <aside><div class="layout-track">…</div></aside>
</main>

Examples: Live progress, Triage board, Command hub.

Workspace

layout-workspace fits the page to the window above Leaf's panel. A single-row header holds the title and status tags. The body takes the remaining height and contains an lf-pane, a widget that arranges its own panes, or a grid of panes defined by the page's CSS. Each pane scrolls its content beneath its own header. A pane's footer stays visible, keeping its actions within reach.

An lf-tabs list="side" in the workspace body displays a list of tabs as a queue, such as tickets or findings. The selected item's content appears beside that list.

The workspace fills the window's height when the window is at least 720px wide and 480px tall. In a smaller window, panes expand to fit their content and the whole page scrolls.

<main class="layout-workspace density-working">
  <header><h1>Payments alerts</h1></header>
  <div id="regions">
    <lf-pane label="Queue">…</lf-pane>
    <lf-pane label="Alert">…</lf-pane>
  </div>
</main>

<style>
  #regions { display: grid; grid-template-columns: 1fr 2fr; }
  @media (width < 720px) { #regions { grid-template-columns: 1fr; } }
</style>

density-working reduces type size and spacing for a compact working surface. It is independent of the Layout: a workspace can use ordinary reading sizes, and a pane or table on another page can use working density.

Examples: Notification playground, Merge a worktree, Alert review.

Tiles

layout-tiles arranges an element's children in equal cells at least 9rem wide, placing as many cells in each row as fit. Cells in the same row have equal heights. A page can set its own columns when it needs a particular grouping, such as four tiles in two rows of two. A row of headline numbers can use a layout-tiles block of native dl elements with labels in dt and values in dd.

Tabs and parts

An lf-tabs at the top of a page creates tabs like the ones on this page. Their tab strip stays at the window's top while the page scrolls, and one tab's content is visible at a time. All tabs share the page's width, Layout, threads, and version history.

When different parts of the work need different layouts, lf-parts holds an lf-part for each. Each part contains its own layout container; main itself carries no Layout. For example, one part can hold an interactive workspace and another a proposal read in a column. Parts share the page’s history, threads, and On Me list. The page-layout reference gives the markup.

Narrow windows

In a narrow window, page regions stack vertically in HTML order. Margin notes move into the reading column, a side column appears above or below its body, and workspace panes expand to fit their content. Tiles can still fit two per row on a 390px phone.

Who is responsible for what

The user sets the goal and preferences. The author composes the page; packages supply its visual language and widget behavior. Leaf core keeps the shared record of what the user does.

flowchart TD
  accTitle: Ownership boundaries in a Leaf page
  accDescr: The user gives the author a goal and selects a theme. Within the authored page, the author owns content and layout, and the widget package owns controls and action meaning. Theme inputs style both. Widgets send actions to Leaf core, which owns the record, current state and Undo.
  User([User])
  Theme["Theme package<br/>Color, type and spacing"]
  subgraph Page["Authored page"]
    Content["Page author<br/>Content and layout"]
    Widget["Widget package<br/>Controls<br/>Action meaning"]
    Content -->|places and configures| Widget
  end
  Core["Leaf core<br/>Record, state and Undo"]
  User -->|goal| Page
  User -->|theme preference| Theme
  Theme -.->|visual inputs| Page
  Widget -->|actions| Core
  Core -->|current state| Widget

Try the example in the Pages tab: a release review. Choose an audience and undo a choice to see these responsibilities at work.

These are contribution boundaries, not a sandbox: package and page scripts run in the same document. Each package's selectors decide where its rules match, and inheritance connects nested content's presentation. The CSS contract describes selector reach and cascade precedence. The package checks validate declarations and rendered behavior.

Choose the extension boundary

1. One page. Semantic HTML, existing Leaf elements, a page-local <style>, and inline SVG shape one document. Keep presentation here when no other page needs it.
2. A package. A reusable element, theme, browser behavior, or author instructions belong in a package. A project-local package, an installed package, and a package bundled with Leaf all use the same composition format.
3. Leaf's kernel. Runtime, chrome, and protocol behavior shared by every page belongs in Leaf itself. A package consumes those capabilities; it does not add a parallel runtime path.

Package interfaces

Packages connect through declared inputs, outputs and actions. A release review can use one package to read a patch and another to navigate its files, without either package knowing the other’s implementation.

Data connects widgets

flowchart TD
  accTitle: A typed output connects independent widgets
  accDescr: The author supplies a patch. The Diff widget publishes its changed files using the file-list contract. The page binds a File tree widget to that output, without either widget knowing the other's implementation.
  Patch["Author supplies a patch"] --> Diff["Diff widget"]
  Diff -->|files: file-list| Tree["File tree widget"]

Widgets delegate recorded state to Leaf

flowchart TD
  accTitle: A choice is drawn immediately and recorded by Leaf
  accDescr: The user's choice starts two paths. The browser draws it before the next frame, while Leaf validates the action and appends it to the log. Shared state then reconciles the browser's selection.
  Choose["Choose Canary clients"]
  Choose --> Draw["Browser<br/>Draw now"]
  Choose --> Admit["Leaf<br/>Admit action"]
  Admit --> State["Shared state"]
  Draw --> Reconcile["Browser<br/>Reconcile choice"]
  State --> Reconcile

Build a package with two files

Create a package in the project, then check the empty composition:

$ leaf package init packages/callout
$ leaf package check packages/callout

The widget in this tutorial needs only these files:

packages/callout/
  registry.json
  defaults.css

Every package beyond the bundled default joins a page with --package. In the commands below, PAGE is the page directory to create or update:

$ leaf page init --package packages/callout PAGE

The complete package contract covers installed and bundled packages, contribution directories, composition order, and replacement rules.

package init also creates empty contribution directories for instructions, browser modules, widgets, and vendor files. The CSS-only widget here leaves them untouched.

To start with behavior instead, name the first element while creating the package:

$ leaf package init packages/risk-notes --widget lf-risk-note

Leaf writes a valid markup-widget element declaration and its one-shot browser module, then checks the complete candidate before changing the package. The tutorial below stays with the smaller CSS-only form so each contract remains visible. A behavior module imports Leaf's package API from /runtime/widget-api.js; it declares each interactive capability once, as the lfCommands of the element it applies in. The same live command rows feed keyboard dispatch, help, accessibility shortcuts, and—when decision names the action—the controls shown inline for an obligation.

Style the element

A package's defaults.css joins Leaf's existing cascade as written, so its rules name the elements they style, starting with lf-callout itself:

lf-callout {
  display: block;
  padding: var(--sp-3);
  border: 1px solid var(--rule);
  border-radius: var(--r);
  background: var(--field);
  --lf-block-frame: 1;
}

--lf-block-frame: 1 tells the shared layout that this rule draws the widget's inset. The style contract distinguishes theme inputs such as --accent from layout declarations, runtime outputs, and vendor bridges. The CSS contract explains how widget, theme and control sheets compose.

Declare the element

The page will author the callout as ordinary readable markup:

<lf-callout id="migration-warning">
  <strong>Migration window</strong>
  Writes pause for about two minutes.
</lf-callout>

Its complete registry.json entry validates the attributes and tells Leaf that the body is prose. x-example is the sample an author queries with the entry:

{
  "lf-callout": {
    "description": "A short warning or constraint that belongs in the reading flow.",
    "type": "object",
    "properties": {
      "id": { "type": "string" }
    },
    "required": ["id"],
    "additionalProperties": false,
    "x-content": "markup",
    "x-upgrade": false,
    "x-example": "<lf-callout id=\"migration-warning\"><strong>Migration window</strong> Writes pause for about two minutes.</lf-callout>"
  }
}

x-content and x-upgrade are the two Leaf declarations every widget requires. The ordinary JSON Schema fields validate its attributes, and Leaf adds the grammar an id follows; description and x-example make the merged registry useful to an author.

The registry-key reference lists every x-* declaration. A CSS-only widget stops here.

Compose and check the page

$ leaf package check packages/callout
$ leaf page init --package packages/callout PAGE
$ leaf page vocabulary PAGE | jq '.["lf-callout"], .["$keys"]'
$ leaf page check PAGE --render

A page keeps its own copy of a package it selects by path, so re-running page init --package is the explicit update for an existing page.

leaf package install packages/callout copies the checked package into ~/.local/state/leaf/packages/, after which --package callout reaches it by name from any project on this machine.

Registry keys

The generated reference for declarations such as x-data and x-state.

Event log

How a widget's x-state verbs become logged events and folded state.

Package contract

Composition, instructions, browser modules, external data, and validation.

Bundled default package

A complete package containing the widgets used across Leaf pages.

CSS contracts

Widget packages style their own elements; theme packages supply presentation across the page. Stylesheet roles set where rules reach, and the cascade sets which rule wins. Styles and overrides, in the Pages tab, covers selecting a theme and making local page adjustments.

Which rule wins

Leaf sorts CSS into tiers by who wrote it. The tiers are CSS cascade layers (@layer), and a rule in a higher tier wins. Each switch below puts the rule beside it into the tier its page or package writes into, for the same card, so the card shows what the browser decides.

A lower tier's rule loses however specific its selector is, as the widget package's lf-card.featured shows. Within a tier, the more specific selector wins, and between equally specific selectors the later rule wins. !important reverses the order of the tiers, so a page's !important loses to Leaf's own; an ordinary rule is all an override needs.

The tiers

flowchart TD
  accTitle: CSS precedence in the page document
  accDescr: For normal declarations, unlayered page rules have the highest precedence, then the page's own layers, lf-state, lf-overrides, lf-layouts, lf-base and lf-reset. Each arrow points from a higher tier to a lower tier.
  Page["Page rules · unlayered"] --> Layers["Page's own layers"]
  Layers --> State["lf-state · Leaf"]
  State --> Theme["lf-overrides · packages"]
  Theme --> Layout["lf-layouts · Leaf"]
  Layout --> Base["lf-base · Leaf and widgets"]
  Base --> Reset["lf-reset · Leaf"]

flowchart TD
  accTitle: CSS precedence inside a widget's shadow tree
  accDescr: For normal declarations, Leaf's marks have the highest precedence, then lf-state, lf-overrides, lf-shadow and lf-base. Page rules and Layouts do not enter the shadow tree.
  Marks["Marks · Leaf"] --> State["lf-state · Leaf"]
  State --> Theme["lf-overrides · theme packages"]
  Theme --> Shadow["lf-shadow · Leaf and widgets"]
  Shadow --> Base["lf-base · widget defaults"]

A nested widget owns its interior

Put a choice inside a release review: the review package arranges the choice's box, and the default package styles its Options widget inside. Leaf adds no boundary between them, so the review package keeps its rules off the choice's interior by naming its own structure: a child combinator such as lf-release-review > p, or its own classes. Shared theme inputs, such as color and type, flow through both.

flowchart TD
  accTitle: A nested widget keeps its own styling when the outer package names its own structure
  accDescr: Shared theme inputs inherit through the review widget and its nested Options widget. The review package styles its own heading and evidence with selectors that name them, and arranges the nested widget's host box. The default package styles the Options interior.
  Theme["Shared theme inputs<br/>Color, type and spacing"]
  subgraph Review["Review widget"]
    Content["Review package<br/>Heading and evidence"]
    subgraph Host["Nested widget host"]
      Options["Default package<br/>Options interior"]
    end
    Content -->|arranges| Host
  end
  Theme -.->|inherit through both| Review

These are styling conventions, not a security sandbox. Page and theme rules deliberately have wider reach; packages run in the same document. A widget's presentation depends on its allotted box and supported theme inputs, so it can move between page layouts.

Choose a bundled package

The core product gallery shows Leaf’s default widgets and controls. The pages below demonstrate optional packages; the Code review package provides authoring instructions.

Playground also powers the structured data explorer and the built-output A/B comparison. Those pages keep their task-specific state, schema, and behavior while reusing the same package mechanics.

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. The index jumps to a key's summary, and a longer contract opens 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. The complete package contract says how the keys combine.