Skip to content

Latest commit

 

History

History
4142 lines (3441 loc) · 220 KB

api-migrations.md

File metadata and controls

4142 lines (3441 loc) · 220 KB

LUI API migration guide

Shared typed slot appearance

menu_item, dropdown surfaces and items, toolbar controls and toolbar text accept one optional ~style:Slot_style.t argument. Their ordinary constructors accept the same value. The individual appearance arguments added earlier in this PR, including their signal twins, have been removed from constructors. Pre-existing constructor properties are unchanged.

Build appearance once with Slot_style.make: font_size, font_weight, font_family, font_style, line_height, letter_spacing, text_decoration, white_space, text_overflow, overflow, hover_background, hover_foreground, focus_within_background, focus_within_border, focus_shadow, shadow, collision_padding, cursor, user_select, disabled_opacity, pressed_opacity, hover_opacity and max_height_viewport. Typed signal twins are centralized in this builder only. Inside a style, current signal values win over static values and updates retain the node. Sources are borrowed; reactive derivations are created and owned at each mount through the PPX's style-scoping adapter. Omitted properties, an empty style and an omitted style preserve defaults. Slot_style.scoped is the PPX adapter; views should use reactive rather than calling this adapter directly.

Slot_style.merge base override is right-biased per property, including signal bindings: an overridden base binding is not installed. A style may only contain properties admitted by its target's existing wire kind. Reactive projections are deferred per property, so merging does not evaluate a replaced projection. The PPX passes the property's wire identifier to Slot_style.scoped; its callback must produce exactly that one property's binding. Unsupported properties are rejected before any style bindings are installed; for example, collision padding belongs on a dropdown surface, not a toolbar button.

let menu =
  let surface_style = Slot_style.make ~shadow:"0 4px 6px black"
    ~collision_padding:5. ~font_size:"14px" ~line_height:"20px" ~overflow:`auto () in
  menu_trigger ~text:"Actions" ~label:"Actions"
    (dropdown_menu ~style:surface_style
       [dropdown_menu_item ~text:"Open" []])

let actions selected = toolbar ~label:"Actions"
  [toolbar_button ~text:"Copy"
     ~style:(Slot_style.make ~font_size:"12px" ~line_height:"16px"
       ~hover_foreground:(reactive (fun active ->
         if active then "primary" else "foreground") selected) ()) []]

Restricted slot capabilities are unchanged: ordinary views cannot become toolbar or dropdown slots through post-mount decorators. Use the typed constructors and their existing reactive/scoped adapters instead. JSON adapters and view-contract metadata keep the same flat static appearance keys, including ordinary and toolbar buttons with text or icons. These keys are decoded through the shared style builder. No wire properties, admission rules, defaults or events changed. Web and SDL/native draw these existing appearance channels; Apple and Android retain native control/menu styling where their renderers do not consume them, as described below for menu items.

Move ordinary-view post-mount styling into a typed style rather than erasing or casting its restricted capability:

dropdown_menu
  [ dropdown_menu_item ~text:"Open"
      ~style:(Slot_style.make ~font_size:"0.875rem"
        ~line_height:"1.42857" ~hover_background:"muted"
        ~focus_shadow:"inset 0 0 0 2px blue" ()) [] ]

These are wire-level properties, not a promise of identical native menu styling on every renderer:

  • Web applies the typography and interaction properties to menu-item DOM nodes through its text styles and appearance channels.
  • SDL/native applies them through its common text and appearance renderer (platform/native/lui_paint), independently of OS-native menus.
  • Apple SwiftUI native menus keep platform menu-label typography. LUINativeMenuActions.itemLabel(for:) builds a native Label/Text without applying the item's typography or hover/focus overrides.
  • Android Material menu rows keep their native typography and state chrome. LuiMenuItem derives text style from Material/style classes rather than the item's typography properties, and neither it nor luiChrome consumes the hover/focus overrides.

The new menu-label typography and interaction overrides are currently drawn by Web and SDL/native only. Apple and Android still receive the properties; applications must not rely on them changing native menu labels there.

Web's default menu highlight honors each authored appearance channel independently. A foreground-only hover override preserves the default highlight background; a focus-background-only override wins on keyboard focus without requiring a hover background. An authored focus background keeps the item's normal foreground unless an active foreground channel overrides it, rather than assuming an inverted highlight background:

dropdown_menu_item ~text:"Open" ~style:(Slot_style.make ~hover_foreground:"red" ()) []
dropdown_menu_item ~text:"Save" ~style:(Slot_style.make ~focus_within_background:"muted" ()) []

Apple row intrinsic text priority

Non-growing text, heading, and paragraph children in Apple rows now retain intrinsic width ahead of growing siblings, without requiring single-line. For example, row [button ~grow:1.0 ~text:"Tab" []; text ~value:"✓" []] keeps its trailing glyph visible. No wire or caller changes are required. Flexible containers keep their existing priority; growing text still shares the growing-child priority. Explicit single-line priority is unchanged. Android and web layout are unchanged.

Foreground accent ink compatibility

primary and accent in a foreground slot retain their accent ink color; they are not remapped to primary-foreground or accent-foreground. This restores pre-ADR-0007 heading and icon contrast, including Android light themes where onPrimary is white. Theme overrides for primary and accent continue to select that ink on native backends. Explicit *-foreground values remain available for content painted on a corresponding filled control.

Container and surface tokens such as surface, card, secondary and muted still resolve to their ink counterparts in foreground slots. For example, keep text ~foreground:"primary" ~value:"General" [] for an accent-colored heading, and use ~background:"primary" with ~foreground:"primary-foreground" for text on a primary fill. Background and border resolution is unchanged on all backends.

Web separates accent ink from its neutral accent fill: foreground:"accent" uses --lui-accent-ink (#1d4ed8 in light mode, #93c5fd in dark mode, including system dark mode). These defaults meet 4.5:1 contrast against background, secondary and accent fills. The fill tokens are unchanged; foreground:"primary" still uses primary ink. Web themes can customize --lui-accent-ink on their [data-kb-theme] scope independently of --lui-accent. For example, use --lui-accent-ink: #1d4ed8 for blue text while keeping a pale neutral accent fill.

Dynamic platform tweak attachment order

Anchorless dynamic segments now reconcile child edges from descendants to ancestors. A platform tweak's child is attached before the tweak is inserted into its parent, including on if_ visibility changes. This preserves the host's exactly-one-child validation for nested tweaks and avoids rejected batches on Apple and Web. No application API changes are required; use the same if_ ~test around a tweaked subtree on initial mount and later toggles.

Phase 4 review: explicit sections in form sheets

Ui.form_sheet now supplies an inset-grouped list as its content container, so Ui.form_section nodes have an admitted list parent. Apple navigation forms consume these explicit sections, render their header/footer slot content, and keep one native row per supplied control. Existing heading-based raw Lui_element_combine.form_sheet content remains supported unchanged.

Outside a form sheet, place Ui.form_section inside an Elements.list, not directly inside a column. Gallery's Card example uses this admitted list parent.

An authored list with appearance, scroll-completion, or visible-range callbacks keeps its own renderer rather than being flattened into the native form. Apple uses appear-enabled, pointer-enabled (also enabled by the scroll callbacks), and track-visible-range to preserve that lifecycle and event delivery.

Phase 4 review: role-independent Apple text truncation

Apple now applies the single-line limit to heading, paragraph and label when ~truncate:true is supplied without ~role. Their existing default typography and heading accessibility behavior are preserved.

Phase 4 review: row content in form sections and data lists

Ui.form_section and Ui.data_list isolate supplied content inside a flow container within each native row. Passing an existing list_item or settings_row no longer creates a direct nested list-item pair, which Apple interprets as a collapsed disclosure. Existing row callbacks remain on the supplied row; no toggle handler or migration is required.

ADR 0007 Phase 4: tokens, semantic text and additive composites

Lui.Ui keeps all existing low-level context/node exports, with the same types and meanings. It adds semantic composites; it does not replace Ui.text, Ui.row, Ui.column, Ui.toolbar, Ui.card or Ui.panel. Lui.Raw = Lui_ui is the long-term home for low-level helpers. New application views should use Lui.Elements primitives and Lui.Ui composites. No new composite name collides with an existing low-level export: the semantic toolbar is nav_bar/action_toolbar, and stacks are hstack/vstack. Existing Lui_element_combine entry points remain unchanged.

Typed tokens

Lui.Tokens (also Lui.Ui.Tokens and Lui.Elements.Tokens) exports:

  • color: background, surface, surface_raised, card, foreground, muted_foreground, primary, secondary, accent, muted, destructive, warning, success, info, border, input, ring, glass, bar, transparent, hex of int, token of string;
  • space: none, xs, sm, md, lg, xl, page, px of int;
  • radius: none, sm, md, lg, xl, full, px of int;
  • text_role: display, title, headline, subheadline, body, caption, footnote, code.

These are closed polymorphic variants. Semantic colors and roles encode to the Phase 2 canonical vocabulary (surface_raised becomes "surface-raised"). color_value retains custom nonblank token strings; blank tokens become transparent. Hex values are clamped to unsigned 32-bit and emitted as RGB/RGBA hex strings. space_value resolves none/xs/sm/md/lg/xl/page to 0/4/8/12/16/24/16 logical units; radius_value resolves none/sm/md/lg/xl/full to 0/4/6/8/12/9999. Explicit px escapes clamp at zero. These numeric authoring recipes do not change the backend-native Phase 2 theme lookup tables (whose platform metrics can differ).

Existing numeric/string primitives are source-compatible. Convert at their boundary rather than reintroducing literals:

let open Lui.Elements in
column ~padding:(Lui.Tokens.space_value `page)
  ~background:(Lui.Tokens.color_value `surface)
  ~corner_radius:(Lui.Tokens.radius_value `lg) [text ~role:`body ~value:"Hello" []]

Container defaults

Card and panel now have host/wire-kind defaults, including nodes built through raw helpers or JSON: vertical, stretching flow, gap md (12), card padding lg (16), panel padding md (12). Explicit gap/padding/axis props still override defaults, including zero. Apple/Android card padding changes from 24 to 16; Web card padding changes from 24 to 16. Panel gains padding. Use stack/overlay for intentional overlap, not card/panel.

Ui.hstack ?key ?accessibility_identifier ?gap:space ?padding:space ?cross ?main children emits a Row with center cross-axis, sm gap and min-width zero. Ui.vstack has the same arguments, emits a Column with stretch cross-axis, md gap and min-height zero. These are constructor recipes, not new wire kinds. Their Web direct children also get min-width/min-height zero.

Read-only mobile audit: searched every /home/ubuntu/repos/mobile/shared/src/logseq/view*.ml for card/panel constructor, raw helper, qualified and aliased uses. No card or panel nodes are constructed, so no mobile call site's appearance changes due to these defaults. The card-named surfaces are actually columns and retain their explicit styling:

  • view_flashcards.ml:57: flashcard question column;
  • view_settings.ml:575,606: general settings columns;
  • view_query.ml:971: gallery card column, explicit gap 10/padding 16, secondary background, border 1/radius 12. view.ml:17 only registers the "card" theme token; it is not a container. No mobile files were edited. This is a source audit, not a mobile visual check.

Repository Gallery's Card example now demonstrates direct vertical children; its implicit card padding changes to 16. Explicitly padded examples keep their padding. Multi-child surfaces now flow instead of overlapping across all hosts. The Phone Card baselines include these defaults, the headline role, and the semantic-form example; their existing pixel budgets are unchanged.

Typography and truncation

text, heading, paragraph, label (and the toolbar text lift) add ?role:Lui.Tokens.text_role and ?truncate:bool. Role adds a canonical typography class while preserving caller classes. Explicit font properties remain overrides. Roles do not replace italic/oblique font_style. Truncation, when true, emits nowrap, ellipsis, hidden overflow, line-clamp 1 and min-width 0; it wins over conflicting explicit overflow/clamp properties. False/omitted leaves existing behavior unchanged. No new wire properties are introduced. These are OCaml authoring conveniences; JSON/EDN continues to use the canonical style-class and overflow properties rather than new role/truncate wire fields.

text ~role:`caption ~truncate:true ~value:(reactive title_signal) []

Composite entry points

All existing Lui_element_combine composites are also available from Lui.Ui: composer and attachment/send helpers, sidebar and sidebar_section, toolbar_item and action_toolbar, settings_section, empty_state, loading, confirm_dialog, feedback_banner, buttons, navigation/menu helpers. Their existing typed callbacks, borrowed signal ownership and native presentation recipes are retained. confirmation aliases confirm_dialog.

New entry points (content is Lui.Elements.t; optional keys omitted below):

Ui.page ~title ?navigation ?actions content
Ui.section ?title ?footer content
Ui.form_section ?title ?footer content
Ui.form_field ~label ?help ?error control
Ui.data_list ~label ?empty content
Ui.nav_bar ~title ?leading ?trailing ()
Ui.form_sheet ~title ?on_dismiss ?cancel ?confirm ?confirm_disabled content

Page uses a padded vertical stack with a title or supplied navigation and optional footer actions. Section uses semantic heading/body/footer typography. Form_section emits native list-section header/footer slots and typed rows. Form_field places its label above the control; error takes precedence over help. Its optional help_signal and error_signal carry string option values, override the corresponding static value, and are borrowed. Reactive validation updates only the message, retaining the mounted control and its editing state:

Ui.form_field ~label:"Name" ~error:(reactive Model.name_error model_s)
  (text_field ~placeholder:"Name" [])

The Ui form-sheet wrapper also accepts confirm_disabled_signal for ~confirm_disabled:(reactive predicate model_s); the existing direct ?confirm_disabled:bool Signal.signal parameter remains supported. Data_list emits a native inset-grouped list with a header slot and list-item rows; an optional empty view is used only when content is empty. Nav_bar emits an existing Toolbar with navigation placement; leading/trailing children must have the existing toolbar_el capability. Form_sheet wraps the existing sheet recipe, including navigation-form presentation and cancellation/confirmation toolbar metadata. The legacy Lui_element_combine.form_sheet ~content () signature is unchanged; only the newly added Ui entry point takes a final content list.

These recipes use existing kinds and admitted presentation metadata, so Apple selects native navigation/sheet/list chrome, Android keeps native Material controls and Web keeps existing toolbar/list/dialog semantics. Public composite signatures expose no raw classes or platform-specific dimensions. Internal recipe classes are implementation details. No changes to wire schema/version or event payloads are required.

Unreleased: Child capabilities and anchorless segments (ADR 0007 Phase 3c)

keyed_input_group_actions is removed: an input group admits at most one actions container. Keep input_group_actions as the single ~actions value and put keyed content inside it instead:

input_group
  ~actions:(input_group_actions
    [keyed ~source:actions ~key:action_id ~cmp:String.compare ~mount:action_button])
  (textarea [])

if_input_group_actions still permits an absent or single container; reactive_input_group_actions switches a single container in place.

Experimental EDN :if and :platform branches use the generated ordinary-view compatibility rules when unifying their results. For example, [:if true [:dropdown-menu] [:column]] is accepted in an ordinary view slot, just like explicitly lifting the dropdown with dropdown_menu_view in OCaml. Restricted slots still check every branch against their own child capability.

Restricted parents now take abstract slot elements, not arbitrary t children:

Parent Child type Builders
toolbar toolbar_el toolbar_button, toolbar_icon_button, and a toolbar_ builder for every admitted control, text, spacer, divider and menu
dropdown_menu, menu, submenu dropdown_menu_item_el dropdown_menu_item, dropdown_menu_trigger, dropdown_menu_submenu, dropdown_menu_divider, dropdown_menu_separator
context_menu context_menu_item_el context_menu_item, context_menu_separator
list_section list_section_item_el list_section_item
tree tree_el tree_row, tree_column, tree_panel, tree_card, tree_box, tree_list_item, tree_virtual_list
menu_trigger one mandatory dropdown_menu_el dropdown_menu (not a list)

reactive_dropdown_menu can replace a trigger's single dropdown. There is no if_dropdown_menu or keyed_dropdown_menu: those could violate its mandatory single-child cardinality. Conditionally render or key the enclosing trigger instead, using its parent's slot adapter.

Ordinary leaf constructors remain available with their existing signatures. Slot builders keep their ordinary constructor's properties and children, except context_menu_item: it requires ~on_press, ends in (), and has no children. Its only metadata is text, icon, foreground, variant, selected/checked, disabled (encoded as enabled), accessibility identifier, and press enablement. Their existing signal twins are supported. Submenus, arbitrary styling and raw event callbacks cannot be passed to a context-menu item.

toolbar ~label:"Actions"
  [toolbar_button ~text:"Save" ~on_press:save []];
menu_trigger ~text:"More"
  (dropdown_menu [dropdown_menu_item ~text:"Open" ~on_press:open_document []]);
context_menu [context_menu_item ~text:"Delete" ~on_press:delete ()]

Use keyed_toolbar, if_toolbar, reactive_toolbar, and their corresponding *_dropdown_menu_item, *_context_menu_item, *_list_section_item and *_tree adapters to retain a slot's capability across dynamic branches. Matching if_*, reactive_* and scoped_* adapters are also available for the existing restricted slots. reactive_dropdown_menu preserves the single menu capability; there is deliberately no keyed/conditional menu adapter that could violate menu_trigger's cardinality. Use dropdown_menu_view to display a dropdown menu as an ordinary overlay child. Composite menu actions now take typed dropdown entries too.

toolbar ~label:"Actions"
  [keyed_toolbar ~source:items ~key:Fun.id ~cmp:Int.compare
     ~mount:(fun item ->
       if_toolbar ~test:visible
         (toolbar_button ~text:(reactive string_of_int item) []))]

Nested dynamic branches now mount directly against the existing parent, without an intervening Box display=contents. Each branch owns a range, including empty and multi-node ranges; toggles and keyed reorders preserve surrounding static siblings. Root-level dynamics still need a transparent box when no parent exists. Error boundaries retain their recovery anchor and checkpoint behavior. Code or tests inspecting wire trees must no longer expect nested dynamic anchor nodes. No wire operation or host protocol encoding has changed. The experimental EDN renderer keeps its existing wire constructor names and checks their child kinds against the same generated slot capabilities.

Unreleased: Typed event callbacks (ADR 0007 Phase 3b)

Element callbacks now receive their payload rather than a raw protocol event. Wire events and their constructor order are unchanged. The handwritten element interface is checked against schema-owned callback contracts; payload decoders and record/variant definitions are generated from those contracts and protocol field types.

Callback family Argument
Press, long/double press, submit, dismiss, appear, load, pointer enter/leave, ordinary change unit
Input, picked string (picked retains the host's encoded batch; use Lui_picked_files.decode)
Toggle, focus-within bool
Slider change, value-changed, split resize float
Press-detail, pointer down/up/move/cancel, context-menu pointer_detail
Toggle-detail { checked : bool; modifiers : int }
Navigate `Previous
Navigation-key { key : string; shift : bool }
Scroll-completed { token : int; outcome : string }
Visible-range `Range of { first : int; last : int }

The records and variants are exported by Lui_elements. Range and edge records have named types range and scroll_edges. Radio's on_toggle press fallback receives true, the checked value of a selected radio.

(* Before *)
text_field ~on_input:(function
  | Lui_protocol.TextChanged (_, value) -> save value
  | _ -> ()) []
(* After *)
text_field ~on_input:save []
button ~text:"Save" ~on_press:(fun () -> save draft) []
checkbox ~on_toggle:(fun checked -> set_checked checked) []
slider ~label:"Volume" ~value:0.5 ~on_change:set_volume []
button ~text:"Inspect"
  ~on_press_detail:(fun detail -> inspect detail.x detail.y detail.modifiers) []
text_field ~on_navigate:(function
  | Previous -> previous ()
  | Next -> next ()
  | Key { key; shift } -> navigate key shift) []

press send action now returns unit -> unit; on_input send wrap returns string -> unit. Existing uses of these helpers need no call-site change. Composite and AI component callbacks use the same payloads, including unit callbacks for attach/send/remove/confirm/cancel and string callbacks for picked. Suggestion-list selection receives the selected item and unit.

Use on_press_detail instead of matching pointer details inside on_press. Where full protocol events, press modifiers, virtual-window/retention metadata, or extension events are needed, Lui_elements.on_event and Lui_ui.on_event remain raw escape hatches:

fun context parent ->
  let node = button ~text:"Inspect" ~on_press:(fun () -> ()) [] context parent in
  Lui_elements.on_event context node Lui_elements.is_press (function
    | Lui_protocol.PressModifiers (_, modifiers) -> inspect_modifiers modifiers
    | _ -> ());
  node

Non-finite numeric values and pointer coordinates are malformed typed payloads: the runtime logs LUI event: malformed ... payload; skipping handler on stderr and skips the typed callback without raising. Unrelated events do not call the handler. Exceptions raised by application callbacks retain existing error-boundary semantics.

Unreleased: Text buttons and accessible icon buttons

button now requires ~text:string. Its button_size is closed to `default | `sm | `lg; other controls retain their existing sizes. ?text_signal remains supported and overrides the initial text. Reactive text keeps the existing authored syntax:

button ~text:"Save" ~on_press:save []
button ~text:(reactive caption) ~on_press:save []

Replace icon-only calls with icon_button ~icon ~label; both arguments are mandatory, and label is the accessible name, not visible text:

(* Before *)
button ~icon:`plus ~label:"Add attachment" ~size:`icon children
(* After: keep the same children list, including menus/custom content. *)
icon_button ~icon:`plus ~label:"Add attachment" ~size:`icon children

icon_button accepts the same styling, variant, disabled state, callbacks, icon signal, tooltip and shortcut options as button, but no text/text signal. Its control_size also includes `icon. Both constructors keep the existing defaults and emit the same Button wire kind; no wrapper or new backend kind is introduced. Composite glass actions choose the appropriate constructor based on whether visible text is present. The transparent file preview hit target now has meaningful transparent text rather than no text.

JSON keeps "kind":"button": with text it uses the text constructor; without text it requires both icon and label and uses icon_button. Host accessible-name validation remains: mandatory OCaml strings can still be empty, and a reactive text signal can become empty. Missing arguments are compile-time errors, but empty accessible names still need runtime validation.

Unreleased: Resilient JSON positioning and sizing conflicts

Conflicting JSON inputs now normalize deterministically and log diagnostics on stderr through the same path as runtime boundary/duplicate-key diagnostics:

  • A valid anchor side wins over x/y point positioning.
  • anchor-target wins over anchor-rect (the losing rectangle is not parsed).
  • Without an anchor side, orphan anchor sources are ignored; a complete point wins, otherwise Cover is used. An incomplete point also falls back to Cover.
  • Split first-width wins over fractional value.

For example, {"kind":"split","value":0.25,"first-width":246} emits only first-pane-width=246 and logs the discarded fraction. Conflicts no longer raise. Invalid winning rectangle data still follows the existing validation.

Unreleased: Closed vocabularies and exclusive modes (ADR 0007 Phase 3a, step 3)

The typed element API replaces the following open strings/integers with closed polymorphic variants. Existing valid wire values are unchanged:

Parameter Type and values
heading level heading_level: `h1 through `h6 (still encoded as integers 1–6)
toolbar placement toolbar_placement: `automatic `bottom `navigation `principal `primary_action `secondary_action `status `confirmation_action `cancellation_action `destructive_action `top_bar_leading `top_bar_trailing
sheet sizing sheet_sizing: `form `fitted `page
font_style `normal `italic `oblique
white_space `normal `nowrap `pre_wrap `pre_line
text_overflow `clip `ellipsis
overflow `visible `hidden `auto

Signal twins use the same types. Underscores still encode as hyphens, e.g. `pre_wrap becomes "pre-wrap". Replace ~level:2 with ~level:`h2, ~sizing:"form" with ~sizing:`form, and ~white_space:"pre-wrap" with ~white_space:`pre_wrap.

The shared element_tag type is replaced by exact per-kind as_ types: phrasing_tag on text (Span, Em, Strong, B, I, U, S, Del, Mark, Small, Code, Kbd, Sub, Sup, Pre); heading_tag on heading (H1–H6); paragraph_tag on paragraph (P, Span, Div, Pre); label_tag on label (Label, Span, Div); list_container_tag on column (Div, Ul, Ol); and row_tag on row (Div, Li). Tag names remain polymorphic variants, so valid literal calls are unchanged. Annotations using element_tag must adopt the appropriate family type.

Popover positioning

Replace at/at_signal, anchor, anchor_target, anchor_rect, anchor_alignment, anchor_offset, and anchor_alignment_offset with one target (or reactive target / low-level target_signal):

popover ~target:(At (10., 20.)) []
popover ~target:(Anchor {
  side = `below; source = Target "filter-trigger";
  align = `start; offset = 8.; align_offset = 0.
}) []
popover ~target:(reactive (fun (x, y) -> At (x, y)) position) []

Cover is the unchanged no-anchor default. Anchor.source is Parent, Target identifier, or Rect {x; y; width; height}. A rectangle keeps the existing space-separated float encoding. Choose the alignment and offsets explicitly in an Anchor record. Mode/source changes remove stale properties, including when switching back to Cover. Native demos previously specified an invalid point-plus-anchor combination; they now use the intended below-parent anchor. dropdown_menu and tooltip positioning APIs are unchanged.

Split sizing and motion

Replace value/value_signal and first_width/first_width_signal with sizing/sizing_signal. Use Fraction value or First_width pixels:

split ~sizing:(First_width 246.) (column []) (column [])
split ~sizing:(reactive (fun value -> Fraction value) fraction)
  ~motion:{duration_ms = 180; easing = `standard; origin = None}
  (column []) (column [])

Omitting sizing now emits Fraction 0.5, including on Apple, which requires exactly one sizing mode. Reactive mode changes remove only the opposite sizing property; publishing an unchanged sizing value emits no patches. motion groups the former resize_duration, resize_easing, and resize_origin. Omitted motion retains instant resizing (duration 0, implicit standard easing, no origin). Positive duration emits the chosen easing and optional origin. Non-positive duration means instant resizing: duration is clamped to zero and easing/origin are omitted to keep the batch valid.

Language-neutral view contracts retain flattened wire fields for positioning, sizing, and motion. The JSON renderer translates its existing flat inputs to the new sum types and normalizes conflicting modes/sources as described above. Newly closed JSON enum inputs reject unknown values.

Unreleased: Mandatory element values (ADR 0007 Phase 3a, step 2)

The following constructor labels are now required:

Constructor Required labels
icon name
slider label, value
progress value
sheet, accordion title (renamed from text)
toolbar, radio_group, tree, bottom_tabs label
stepper active
step text
timeline_item title
bottom_tab title, on_press

Supply a meaningful accessible label/title rather than an empty placeholder. For sheet and accordion, rename text/text_signal to title/title_signal. Their wire property remains text; other constructors' text parameters are unchanged. form_sheet already takes title and needs no caller change.

Existing signal twins remain optional. The required static value initializes the property; a supplied signal wins on mount and subsequent publications. For example:

slider ~label:"Volume" ~value:0.5 []
sheet ~title:"Settings" [text ~value:"Preferences" []]
accordion ~title:"Details" [text ~value:"More information" []]

(* Both required initial value and signal binding are supplied by the PPX. *)
slider ~label:"Volume" ~value:(reactive volume) []
progress ~value:(reactive (fun completed total -> completed /. total)
                   completed total) []

For mandatory reactive labels, lui_ppx evaluates the signal expression once, reads its current value with Signal.sample, and supplies both ~x and ~x_signal. Mapped signals retain their existing mount-owned lifetime. The mandatory labels live in schema/components.json; generated PPX metadata and the interface contract test consume that declaration. Optional reactive labels still lower to the signal argument alone.

The JSON-view renderer also requires these data values (sheet/accordion titles continue to use the wire key text). A bottom-tab JSON node requires an id to route its required press callback. Missing required JSON data now raises Invalid_argument naming the missing constructor parameter instead of mounting an incomplete node. Data-only typed view contracts mark required properties too.

Unreleased: Admission-safe element parameters (ADR 0007 Phase 3a, step 1)

Lui_elements constructors now expose only properties and events admitted by Lui_protocol for their node kind. Unsupported optional parameters are removed, including their _signal twins wherever present. key remains reload metadata; toggle_button/menu_item keep checked (an alias for selected), and radio keeps selected (an alias for checked). Required values, vocabulary types, event payload types, and child types are unchanged in this step.

The following sets abbreviate the removed property parameters:

A = gap, main, cross, columns
P = padding, padding_horizontal, padding_vertical
M = margin, margin_horizontal, margin_vertical,
    margin_top, margin_right, margin_bottom, margin_left
D = width, height, min_width, max_width, min_height, max_height
B = background, foreground, border_color, border_width, corner_radius
F = container_relative_frame, container_relative_frame_inset
U = A + grow + P + M + D + B + F + style_class + data_attrs

+ combines sets; - excludes names. Every listed name also removes its signal twin if the old constructor exposed one.

Constructor family Removed properties
row, column, panel, card, box, button, radio, checkbox, popover columns
stack, overlay, view_that_fits, bubble, text, heading, paragraph, label, toggle_button, toggle, slider, number_stepper, textarea, switch_, spinner, icon, table_cell, resizable, status_bar, file_image A
edge_inset, scroll, select, combobox, dropdown_menu, split main, cross, columns
alert A + text_alignment
radio_group, progress, divider, separator, spacer, image, media_surface, table A + foreground
text_field, secure_field, input, search_field A + submit_on_enter
list, virtual_list, tabs, button_group, toggle_group, breadcrumb, pagination columns, foreground
bottom_tabs A + P + M + B + F
bottom_tab, stepper, step, timeline_item, file_picker U
context_menu U + disabled
menu_item columns, role, tree_level, expanded
list_item, link gap, columns
avatar A + grow + P + M
timeline U - gap - grow
input_group U - grow - width - height - min_width
input_group_actions U - gap
accordion U - height - style_class
table_row main, cross, columns, foreground
tree main, cross, columns, foreground, role, tree_level, expanded
dialog main, cross, grow, columns + F
drawer, sheet A + grow + B + F + min_width, max_width, min_height, max_height
tooltip U - F
toast A + grow + B + D + F
toolbar main, cross, grow, columns, padding_horizontal, padding_vertical + M + foreground, border_color + (D - height) + F
kbd A + M + F

No property parameters were removed from grid, menu_trigger, menu, submenu, list_section, swipe_actions, swipe_action, or file_preview.

Constructor Removed event parameters
toggle_button on_press
select on_input, on_submit
dropdown_menu on_press, on_input, on_submit
menu_item on_input, on_submit, on_dismiss
list_item on_input
tree on_press, on_change, on_toggle, on_press_detail, on_pointer_down, on_pointer_up, on_context_menu

Move layout/styling to a container that admits it, and wire callbacks on the interactive children rather than the owning collection. For example:

(* Before: gap is not a Text property. *)
text ~gap:8 ~value:"Status" []

(* After: keep spacing on an admitted layout container. *)
row ~gap:8 [text ~value:"Status" []]

context_menu keeps its platform menu surface and item styling; it no longer accepts arbitrary surface decorations. The Windows demo drops its rejected background/border/radius/padding arguments, retaining menu items and their foreground colors and using the host's standard menu decoration. Do not put a generic box inside a context menu: its child-kind contract still applies.

apply_universal is now internal, not a public low-level styling escape hatch. Use admitted constructor parameters (or an admitted enclosing container), not Lui_elements.apply_universal. The JSON-view renderer's constructor calls are updated alongside the signatures, so it also stops forwarding unsupported arguments. The schema tooling test parses those signatures, including separator, menu, and submenu, and checks them against generated canonical admission data.

Unreleased: Canonical design-token and typography parity

Web headline text now uses the canonical typography rule's 1.4 line-height instead of inheriting 1.5. Explicit per-node font sizes still take precedence. This slightly tightens the headline and moves following content upward; the Phone BottomTabs Gallery baselines include this intentional change. Applications that need fixed line spacing can supply an explicit line_height metric.

schema/components.json now inventories the cross-backend vocabulary under designTokens. Colors use existing hyphenated wire spellings (the ADR's surface_raised and muted_foreground identifiers correspond to surface-raised and muted-foreground):

Category Canonical names
Colors background, surface, surface-raised, card, foreground, muted-foreground, primary, secondary, accent, muted, destructive, warning, success, info, border, input, ring, glass, bar, transparent
Spacing none, xs, sm, md, lg, xl, page
Radius none, sm, md, lg, xl, full
Text roles display, title, headline, subheadline, body, caption, footnote, code
Text modifiers semibold, single-line

Existing colors, custom colors, theme overrides, and legacy aliases such as title2 and mono remain available. Newly admitted colors reuse existing platform surfaces and accents rather than introducing a new palette. Foreground slots resolve container tokens (excluding the accent ink names primary and accent) through their corresponding ink token: for example ~foreground:"secondary" uses secondary-foreground, not the pale secondary background. Explicit *-foreground theme overrides win. Apple keeps its adaptive secondary style only when the corresponding secondary-foreground or muted-foreground theme override is absent. Background and border slots retain existing values; literal colors are not remapped. Applications intentionally using a container fill as text ink can continue to supply its literal color instead.

Use text ~style_class:"headline semibold single-line" ~value:title [] for semantic type and one-line ellipsis. .caption and the other named roles now work on all four renderers; .code selects the platform monospace family. Explicit typography properties continue to override role defaults. Native class changes invalidate text measurement as well as painting. Apple uses Dynamic Type roles; Android retains Material typography rather than adopting Apple point sizes.

Named metric lookup tables are available in each backend, with Web CSS variables --lui-space-* and --lui-radius-*. These are platform defaults, not new string-valued wire properties: shared constructors still accept numeric geometry. Typed space/radius arguments remain a later ADR phase.

Backend Spacing none/xs/sm/md/lg/xl/page Radius none/sm/md/lg/xl/full
Web 0/4/8/12/16/24/24 px 0/4/6/8/12/9999 px (relative to existing --lui-radius)
Apple 0/4/8/12/16/24/16 pt 0/6/8/12/16/9999 pt
Android 0/4/8/16/24/32/16 dp 0/4/8/12/16/9999 dp
Native 0/4/8/12/16/24/16 logical px 0/4/6/8/12/9999 logical px

tooling/test/design-token-parity.test.mjs parses the actual backend tables, including both Native palettes, foreground-slot counterparts, metric scales, and consumed typography roles. Missing canonical names fail the existing Node tooling test command; platform-specific extra tokens remain valid.

Unreleased: Subtree error boundaries

Lui_elements.error_boundary ~fallback child isolates exceptions raised while mounting a child or running its owned reactive view updates. For example:

error_boundary
  ~fallback:(fun diagnostic -> text ~value:diagnostic.message [])
  (reactive (fun model -> render model) model_s)

The diagnostic contains exception_, message, state_path, and phase (Mount or Update). A stderr diagnostic is logged once. The failed content's runtime writes are undone, its scope is disposed, and its prior children are replaced by the fallback. Runtime mutations use an application-scoped undo journal: each boundary takes a constant-size savepoint on mount and at the first protected callback in a publication wave. Later callbacks share that savepoint. A failure discards all uncommitted runtime writes since it, including opaque writes made through runtime helpers outside the subtree. Runtime state from before the savepoint is preserved.

A successful fallback commits its recovery entries. An outer or interleaved sibling rollback never resurrects that boundary's disposed content or undoes its committed writes. Independent properties, children and handlers retain their own undo history; a committed recovery wins when it writes the same property. Recovery entries belong to their boundary anchor. If an enclosing mount rolls back creation of that anchor, the nested recovery is discarded with it; only the enclosing fallback remains. Replacing an existing ancestor's failed subtree can also unmount a nested fallback normally. A fallback that itself fails does not commit its partial recovery. Runtime identifiers remain monotonic across boundary rollbacks.

If the flush has queued operations when rollback occurs, its entire pending delta is discarded and Phase 1 authoritative resync is scheduled. After recovery settles, the host receives detaches for its previously accepted roots, followed by a complete snapshot of the surviving runtime tree. This preserves earlier pending state and committed sibling recoveries without replaying stale indices, unlinking descendants before subtree removal, or attaching incomplete tweaks. Successful publications remain incremental. Before resync, surviving and restored size properties are normalized even if their original operations were discarded (for example, width 10 with min-width 100 is stored and sent as width 100).

Text, toggle and numeric echo markers have independent undo entries; unrelated recovery styling cannot commit the echo marker of a discarded value.

Savepoints reset before the next mutation round. The shared journal is compacted at flush end, including rejected batches and exceptions, so boundaries retain no full-tree snapshots. External side effects and signal state changes are not transactional.

Fallbacks latch: later publications do not retry the failed child. Remount the boundary (for example through an enclosing reactive switch) to retry with fresh subscriptions. A fallback is outside its own boundary, so a failing fallback reaches the nearest enclosing boundary, or propagates to the caller when none exists. An inner boundary handles errors before its enclosing one.

The construct uses existing boxes with display=contents as a stable outer anchor and a disposable content anchor; no wire kind or host changes are required. As with other transparent anchors, use it where a box is an admissible child, not in restricted slots such as direct menu-item lists. It protects owned reactive subtree switches, collections, conditionals, and PPX-owned property projections. Retained keyed and virtual rows inherit the enclosing boundary's protection, including later row-property projections after a successful reconciliation. Element-owned signal encoders also run inside that protection: publishing an unsupported reactive data_attrs name mounts the fallback instead of raising from signal stabilization. Empty and valid attribute lists behave as before. External signal producers, event/timer callbacks, disposal callbacks, backend rejections, and explicit reentrant flushes are not error-boundary transactions. Outside a boundary, exceptions retain their existing propagation behavior. OCaml eagerly evaluates constructor arguments: exceptions raised before a child's mount closure runs must be deferred with scoped or reactive to be inside the boundary.

Low-level Lui_ui.ui_context records now include an inherited ui_protect callback. Prefer the context constructors; custom record literals must supply ui_protect = (fun action -> action ()) outside a boundary. PPX-generated mount-owned projections use the scope-owning Lui_ui.map/map2 helpers to route update failures to this callback. Runtime property binding helpers accept an optional ~protect callback; existing callers retain exception propagation.

Unreleased: Shared Android admission and native web-only hints

Android main/cross alignment and modal-surface kind sets are now generated from the canonical OCaml admission export by generate_component_schema.mjs. Grid, checkbox, and radio accept main/cross alignment; drawer follows the same modal property restrictions as dialog and sheet.

Android renderer dispatch remains independent of admission: drawers still use the existing navigation-drawer renderer, while dialogs and sheets use their dedicated modal renderer. For example, a shared drawer retains its main content and selected-state-controlled drawer panel after schema admission updates.

The shared component schema now marks shrink and focus-within-enabled (the wire property behind on_focus_within) as web-only. SwiftUIHost and KotlinHost ignore their writes/removals instead of rejecting them, including direct native host batches. For example, a shared row ~shrink:0. view can mount on native hosts without a platform guard; native layout defaults remain unchanged and no focus-within callback is generated there. Web behavior and GenericHost's existing strict admission remain unchanged. There were no other web-only property annotations in the schema; future annotations feed these same generated host filters. No wire names or formats changed.

Unreleased: Numeric clamping and Apple bottom-tabs resilience

The OCaml runtime emit path and Web, Apple, and Android retained stores now clamp negative width, height, min-width, max-width, min-height, max-height, gap, padding (including directional and axis variants), border-width, corner-radius, tooltip-delay, duration, and resize-duration to zero. Margins and signed offsets are unchanged. Values of the wrong wire type and properties unsupported by a node kind still reject.

Pixel size constraints resolve after the batch's property writes: effective_max = max(min_size, max_size) and effective_fixed = clamp(fixed, min_size, effective_max). An absent minimum means zero and an absent maximum remains unbounded; absent dimensions and "auto" stay absent/automatic. For example, width=10, min-width=100, max-width=50 now stores and renders width=100, min-width=100, max-width=100 instead of rejecting. Later writes resolve against these canonical stored values, not a hidden copy of the original conflicting values. Pure protocol validators still validate canonical values; low-level integrations can call Lui_protocol.normalize_property_value and normalize_size_properties before validating. size_properties names the affected pixel-size properties.

Web replays only retained pixel-size properties after normalization. Absent pixel dimensions do not clear viewport-derived CSS: for example, setting min-height=10 preserves an existing width-viewport=0.5 as 50dvw. Explicit pixel-size removals still clear their corresponding CSS dimension.

opacity, hover-opacity, pressed-opacity, disabled-opacity, and label-opacity clamp to [0,1]. Non-finite values for these opacity properties fall back to the neutral opacity default 1 and emit a stderr diagnostic naming the property, reason, and fallback. For example, a reactive computation returning nan for opacity now emits 1.0, not invalid JSON. The low-level wire encoder continues to reject non-finite floats; applications bypassing the runtime must normalize before encoding. Other float properties retain their existing rules.

Apple bottom_tabs no longer rejects a dynamic child count outside 2...5; it logs a diagnostic and renders the supplied destinations using the existing tab renderer. Required accessible labels and valid bottom_tab children remain enforced. For example, publishing a temporary empty destination list is accepted while loading; restoring two or more destinations requires no remount workaround. There are no schema or wire-format changes, and valid existing values behave as before.

Unreleased: OCaml runtime resilience

Children-position reactive now compares physically identical values first, then attempts structural equality. If structural equality raises Invalid_argument (for example on a record containing a closure), the value is treated as changed. Explicit ~equal comparators keep their existing semantics. For example, reactive (fun model -> pane model) model_s can now receive fresh closure-bearing records repeatedly; use reactive ~equal:(fun a b -> a.id = b.id) pane model_s when identity alone should retain the branch. The comparator is also available as Lui_elements.default_subtree_equal for low-level Lui_dynamic.switch integrations; replace an unguarded (=) argument with this function to use the same closure-safe policy.

keyed and virtual_rows business keys now use occurrence order to distinguish duplicates instead of rejecting the publication. The first occurrence retains the original identity; later occurrences retain identity by (key, occurrence) across publications. For example, [a; a; b] reordered to [a; b; a] moves the second a row without remounting it. Unique keys behave as before and remain recommended: inserting a duplicate before another duplicate changes which item owns each occurrence's local state. Diagnostics on stderr identify the polymorphic key by key_hash, the parent node, and the duplicate occurrence (starting at 1). Arbitrary polymorphic keys have no public text printer. Virtual rows' separate semantic scroll_key uniqueness and nonempty shared viewport key requirements remain enforced; use unique semantic keys for shared viewports even if business keys repeat.

After apply_batch returns false, the rejected delta is no longer requeued. The rejection is still reported as Invalid_argument "backend rejected patch batch". On the next flush, even without new pending operations, the runtime sends an authoritative resync_batch snapshot of the latest retained state under the next host generation. Later successful turns resume incremental delivery. For example, catch a rejected flush, restore/reset the host through its existing resync mechanism when using an explicit bridge snapshot. For a synchronous backend returning false, simply flush again: recovery now prefixes the snapshot with DetachSubtree for every root acknowledged by that backend, including roots removed from the runtime in the rejected delta. This clears the old mirror before recreating live nodes without a new host-reset callback. Explicit bridge snapshots remain create/set/insert-only: Apple's applySnapshot and Android's replacement-store path still perform their own reset. The Web backend reports apply errors as exceptions rather than false; this rejection policy does not change its DOM error recovery. Exceptions from apply_batch retain the existing uncertain-commit semantics. There is no wire-format change.

Unreleased: SDL popup presentation

Experimental macOS/Linux SDL hosts may now present menu, popover and tooltip nodes in child windows. Applications keep their existing retained nodes and event handlers; for example, a context menu's normal item handler and Escape dismissal still apply. A host embedding Lui_host can opt in via Lui_host.set_popup_presenter host (Some (present, finish)); return false from present to draw that overlay in the parent as before, or pass None to keep all overlays in-window. SDL lifecycle messages for a child do not resize or close its parent.

SDL adapters that translate child coordinates can use Lui_sdl3.Event.map_pointer (fun x y -> (x +. left, y +. top)) event; keyboard, scroll and lifecycle events are not transformed.

Unreleased: macOS native frame pacing

The experimental Metal host requests frames from the window's display link on macOS 14 and newer. Layout is refreshed while the window is being resized; applications continue to use their existing resize handlers. Older systems or unavailable display links keep the timer-based scheduler. Hosts with their own loop can arm the cadence with Lui_metal.request_frame_tick renderer after Lui_metal.set_frame_rate renderer fps.

Unreleased: SDL3 native host text input

Native SDL host code should replace Lui_sdl3.set_text_input_rect window rect with Lui_sdl3.set_text_input_area window rect ~cursor:0 for the old positioning, or pass the horizontal caret offset in window pixels relative to the area's left edge. start_text_input window still starts ordinary single-line input; use start_text_input ~multiline:true window for a text area or ~secure:true for a password field. No wire changes are required. Native drivers can query a focused field with Lui_window.Assembly.ime_surrounding. For example, pass the returned selection to ime_range_rect to locate it in device pixels, or call ime_replace assembly selection replacement and apply its actions as for Assembly.handle. Ranges use UTF-8 byte offsets in the current committed text, not UTF-16 indices or preedit offsets. Secure fields do not expose committed text to these requests.

For a character position inside an active preedit, use Lui_window.Assembly.ime_marked_caret_rect asm marked byte_offset, not ime_range_rect. Pass the native marked string and an offset in that string; query ime_range_rect only for committed text.

Input preferences are optional: for example, use Lui_sdl3.start_text_input ~autocorrect:false ~capitalization:Lui_sdl3.None_ window for an identifier field. Omitting the options keeps the SDL defaults. Send native-window work from another domain with Lui_sdl3.run_on_main_thread (fun () -> Lui_sdl3.show_window window) after SDL initialization; posted work is asynchronous off the UI thread. Use Lui_sdl3.native_handle window to query the backend instead of using SDL2 WM-info calls; for example, match Some (Lui_sdl3.Wayland_surface ptr) for a Wayland-only integration and leave other drivers unchanged.

The experimental Win32 driver now handles IMM32 reconversion and document feed requests for normal editable fields. A confirmed reconversion replaces the requested committed range, instead of inserting the result at the current caret. Existing text-change handlers, including those for normal IME composition, do not need to change.

Unreleased: Web top-level MenuTrigger activation

On Web, a top-level MenuTrigger that owns a DropdownMenu opens on activation instead of hover or focus. Pointer clicks and native Enter/Space button activation toggle the layer-managed open state; moving the pointer away does not close the root menu. aria-expanded follows opening, click toggles, and close paths. Menu triggers inside menu or picker popup contexts retain their hover/focus submenu and pointer-corridor behavior. Outside click, Escape, menu-action dismissal, and focus restoration remain supported. The runtime toggle does not add a second Press event. For runtime-owned menus, on_dismiss is an optional notification; the runtime closes the menu even when it is omitted or does not update application state. Ordinary button-controlled menus and picker behavior are unchanged. There is no protocol or schema change, and other backends are unchanged.

For example, a convenience menu owns its trigger and dropdown:

menu ~text:"More"
  [ menu_item ~text:"Refresh" ~on_press:(fun _ -> refresh ()) [] ]

Experimental native transparent popup frames

Native retained popup transitions now omit all paint operations at zero animated opacity, including modal backdrops. This prevents a fully painted blank shell from flashing before the first visible fade frame on native renderers.

The existing low-level scene opacity defaults and nonzero transition behavior are preserved. No application migration is required; existing declarations work:

dialog ~transition:"opacity 200ms ease-out, transform 200ms ease-out" [content]

Experimental native hover includes ancestor controls

Native hover styling now remains active on a control while the pointer covers its icon, label or another descendant, matching Web :hover. Entering and leaving invalidate affected ancestor paint; moving between children of the same control preserves the parent's cached background. Pointer enter/leave payloads and event admission do not change.

Keep hover styling on the owning control, for example Lui_ui.string_property context button HoverBackground "accent". Remove child-specific hover workarounds if they were added to preserve the parent background. Web and maintained mobile backends retain their existing behavior.

Experimental native hosts use SDL3

The experimental native host replaces tsdl and tsdl-ttf with the pinned logseq/ocaml-sdl3 fork. Backend selection and maintained mobile/web defaults are unchanged. SDL2 pointers must never be passed to SDL3 functions, including Lui_webview.host_of_sdl_window and Lui_metal.init_window.

  • Link lui.sdl3, and use module Sdl = Lui_sdl3. Lui_blit.create now accepts Lui_sdl3.window; distinct window/renderer/cursor types reject mismatched resource calls during compilation.
  • Use Window.high_pixel_density instead of Window.allow_highdpi. Windows are shown by default; remove Window.shown. Display identifiers are stable nonzero IDs, rather than zero-based indices. Refresh rates retain fractions.
  • Text input and IME rectangles require the owning window: Sdl.start_text_input window, Sdl.stop_text_input window, and Sdl.set_text_input_rect window (Some rect). One window no longer changes another window's text-input state.
  • Events expose typed, owned snapshots. Replace raw union fields with match (Sdl.Event.value event).kind with Key_down key -> ... | .... Mouse coordinates and wheel deltas remain floats; timestamps are timestamp_ns : int64. Compute age using get_ticks_ns, not milliseconds. Drop/text payloads are copied before the next dequeue; remove SDL2 drop payload frees. Pixel-size/scale changes refresh backing density separately from logical resize events.
  • Build test events with Event.make and Event.of_event. Push supported native events through push_key_event, push_quit_event, and push_expose_event; no mutable event-union setters are exposed.
  • Texture upload pitch is always bytes, including Int32 Bigarrays. Replace Sdl.update_texture texture None pixels width with a byte pitch of width * 4 for 32-bit pixels. Renderer creation takes ~software:true or ~vsync:true, instead of SDL2 renderer flags.
  • The SDL gamepad backend enumerates stable SDL3 joystick IDs. Virtual-device, GUID and mapping helpers take those IDs, which must not be reused as list indices. Linux audio uses SDL3 AudioStreams; macOS AVFoundation and Windows XInput retain their platform implementations.
  • The spike demo uses SDL3 debug text and --no-text; it no longer needs SDL_ttf or accepts --no-ttf.
module Sdl = Lui_sdl3

let on_event event =
  match (Sdl.Event.value event).kind with
  | Key_down {scancode; keymod; repeat} -> handle_key scancode keymod repeat
  | Mouse_motion {x; y; _} -> handle_pointer x y
  | Text_input text -> insert_text text
  | _ -> ()

Application packages must include the SDL3 runtime and its non-system shared-library dependencies. The binding searches the application's bundled runtime before system loader paths. Logseq's macOS builder embeds SDL3 in Contents/Frameworks, rejects SDL2 and unbundled absolute dependencies, and signs the resulting bundle. End users do not install SDL3.

Experimental self-drawn OCaml native backend

The self-drawn backend under platform/native is available again as experimental. The restored lui.host, lui.store, lui.layout, lui.paint, lui.scene, window, text, raster and GPU libraries use the current shared LUI protocol. Existing Apple/iOS, Android, Web and WebView desktop defaults do not change. The portable lui.plugin and lui.plugin_fetch implementations stay under platform/services; the restored renderer does not provide duplicate service registries.

Applications opt in by linking the native renderer libraries and constructing their own window driver. No application is migrated automatically. Native development requires SDL3 and the OCaml dependencies declared in dune-project and both opam manifests. The sdl3 binding is pinned to the Logseq fork. Portable services and the direct Win32 host do not require an SDL runtime; macOS and Linux native drivers bundle or install SDL3. Platform-specific runtime qualification must run on the actual target, including when a different target compiles stubs.

let status : [ `Experimental ] = Lui_host.stability

Restored example and scaffold views use reactive and lui.ppx; direct dyn calls are not a supported application form. The native JSON scenario recorder also handles the current FocusWithinChanged and VirtualRetention event constructors instead of leaving those constructors unmatched.

The Darwin test gate recognizes both Unicode and current Apple SF Symbol completion markers. It still requires one nonempty successful terminal summary and independently observed zero exit statuses for SwiftPM and its test helper. Missing, conflicting and unrecognized terminal summaries remain failures.

On-demand Web application icons

The Web renderer constructors (create, create_with_extensions, and their simulator variants) accept optional ~resolve_app_icon:(string -> Lui_web_types.web_app_icon option). It receives a bare app: name when a mounted icon needs an asset. Return Icon_url url or Icon_svg descriptor. The typed descriptor contains svg_view_box, svg_filled and svg_shapes. Shape tags (Svg_path, Svg_rect, Svg_circle, etc.) and attributes (Svg_d, Svg_fill, etc.) use closed constructors, excluding active elements and event/resource attributes. Dynamic paint values reject resource references. Shapes mount directly in the owning document and leave with their node, avoiding both cached SVG image documents and per-icon XML document parsing. Explicit app_icons entries retain precedence; None retains the missing-icon fallback. Omitting the resolver preserves existing behavior. There is no wire change. Resolver results are not retained by the renderer, so scrolling through a catalog does not create an unbounded application registry.

Applications can replace an eagerly expanded SVG registry with:

Lui_web.create ~resolve_app_icon:(fun name ->
  Option.map (fun descriptor -> Lui_web_types.Icon_svg descriptor)
    (catalog_lookup name)) root

Only look up and decode the requested icon inside the callback. Static overrides can remain in ~app_icons; native renderers are unchanged.

Desktop WebAssembly capability

The standalone builder also accepts repeated --ocaml-package <findlib-name> arguments for explicitly installed application dependencies. Existing builds keep the same package set. Invalid package names fail before compilation; this option does not install dependencies.

Desktop build configuration adds optional "web": {"wasm": true}. The default is false. Enabling it adds only 'wasm-unsafe-eval' to the local script CSP so applications can instantiate bundled WebAssembly, including SQLite. JavaScript eval and inline scripts remain disabled. The builder rejects non-boolean values and unknown web options. .wasm assets now use application/wasm so streaming instantiation receives the correct MIME type. Existing configurations need no changes; applications using WASM must opt in and rebuild the host executable. The internal macOS scheme-window FFI tuple now includes the host-generated CSP; custom native probes must append that string argument.

OCaml Web desktop host and optional Melange desktop services

The new opt-in platform/desktop host runs a prebuilt Melange frontend in a system WebView. Existing browser, Apple/macOS/iOS and Android APIs remain compatible. No Dune stanza, shared LUI wire schema or mobile package changes. The native shell and update engine run in OCaml.

lui.web.dom adds Lui_web_desktop.available : unit -> bool and Lui_web_desktop.check_for_updates : unit -> bool Js.Promise.t. Ordinary browsers report false and resolve checks to false. In the desktop host, a check opens/reuses the Web update window and resolves true. Existing applications need no changes; add a settings/menu action as follows:

let check_updates () = ignore (Lui_web_desktop.check_for_updates ())

The shell also handles Command/Ctrl+Shift+U. The update window uses an on-demand OCaml helper process, created only when requested. Repeated requests reuse its live instance. Closing the window or choosing Remind Me Later exits that helper and its WebKit session; reopening starts a fresh helper. The main process closes the updater helper before shutdown or installation, releasing executable locks. On Windows this uses process termination (Sys.sigkill), since native OCaml does not support Sys.sigterm; application command APIs are unchanged. The Windows installation helper also leaves the application's working directory before replacing its tree, avoiding a directory lock inherited from shortcuts. Windows replacement and rollback retry transient file-lock errors for up to ten seconds while WebView2 children release their files. A headless cleanup child waits for the installation helper to exit, then removes only its token-named directory under the application's storage. The internal --lui-cleanup mode does not register application commands or open a WebView; application APIs and configuration are unchanged. Windows Authenticode packaging uses DigiCert's documented HTTP RFC3161 endpoint because SignTool rejects an HTTPS timestamp URL. The timestamp token remains cryptographically verified; update feeds and downloads still require HTTPS. Its native bridge exposes built-in update actions and explicitly registered application commands; it exposes no native reflection. On macOS the host loads packaged assets at lui://localhost, with no HTTP listener. WKURLSchemeHandler serves assets and a main-frame/origin-checked script-message bridge handles desktop commands. The update helper owns its update state and uses the same scheme. Linux/Windows retain their loopback transport until native scheme adapters are qualified. The host reserves __lui/* and __lui-desktop.css, injects the bridge before </head>, serves assets with MIME types and a local-only CSP, and requires same-origin JSON POSTs for update mutations on loopback transports. Frontends must use relative, production-bundled assets and external scripts. The Gallery detects this host, displays a desktop two-column layout with a Check for Updates action, and omits its mobile simulator controls. Its browser mode is unchanged. Desktop scrollbars use the host's thin stylesheet; mobile/browser defaults remain unchanged. Unicode DOM literals must use Melange {js|…|js} strings.

The shell's JSON build config requires stable identifier and slug, a semantic version, and a positive monotonically increasing integer build. Window defaults are 1100×760. The sample config explicitly selects 1180×820 and disables updates by omitting updates. Enabling updates requires an HTTPS feed URL and a 32-byte Ed25519 public key encoded as lowercase hex. These values are embedded in the native binary. Upgrading an existing browser app requires bundling its output and running tooling/desktop.py build as documented in the host guide.

Update contract version 1 signs exact JSON payload bytes prefixed with lui desktop update v1\n. The signed payload binds app ID, platform, build, version, plain-text notes and full/delta artifact descriptors (url, size, sha256). Builds at or below the running build are ignored; wrong app/platform and invalid signatures are errors. Package format 1 uses LUIUPD1\n, a big-endian 32-bit JSON index length, the index, and sequential file payloads. Each file has a relative path, length, SHA-256, mode 0644/0755, and either a payload offset or null to copy the same installed path. Files absent from the new index are removed by whole-tree reconstruction. No application-internal symlink is supported. Limits are 2 GB per artifact and reconstructed tree, 8 MB/100,000 files per index and 1 MB per feed.

Configured builds check after 10 seconds and every 24 hours while the main page remains open. Package-managed installations and builds without a feed never check automatically. Skip persists a build; a manual check bypasses that skip. Remind Me Later closes the window. Download/install and restart require explicit user actions. A delta failure retries the authenticated full package. Installation replaces the complete app after exit, retains user data, and requires the replacement page to acknowledge its expected build within 30 seconds before removing the previous tree; failed startup rolls back. Keep the public key stable; key rotation and binary-level patches are not part of format 1. Generate update files only after final OS signing and notarization, then publish artifacts before the feed. The tooling does not upload or publish anything. Production qualification and cross-platform installed-upgrade checks remain required; see the host guide.

Typed native application commands

Lui_command adds portable ('request, 'response) t descriptors with abstract, validated Name.t and Codec.t constructors. Share a descriptor module between native OCaml and Melange. Name.of_string accepts lowercase dot-separated identifier segments up to 128 characters and reserves lui.*. Built-in codecs cover unit, UTF-8 string, boolean and canonical signed 32-bit decimal integers; Codec.make supports application-specific validated encodings.

(* Shared app_commands.ml *)
let echo =
  let name = Result.get_ok (Lui_command.Name.of_string "app.echo") in
  Lui_command.v ~name ~request:Lui_command.Codec.string
    ~response:Lui_command.Codec.string

(* Native desktop_app.ml *)
let commands () =
  [Lui_desktop_commands.handle App_commands.echo (fun text -> Ok text)]

(* Melange frontend *)
let echo text = Lui_web_desktop.invoke App_commands.echo text

Lui_desktop.run_with_commands ~commands initializes bindings only in the main application. Existing run remains compatible and registers none. The standalone builder adds ordered, repeatable --ocaml-source modules and a --commands module exporting commands : unit -> Lui_desktop_commands.binding list. Duplicate names fail startup. Handler and client types must match the descriptor; wrong response/request types and raw string descriptors are compiler errors.

invoke resolves ('response, Lui_command.error) result Js.Promise.t. Browser calls return Unavailable. Dynamic unknown commands, decode failures, overload, handler failures and malformed responses remain validated at the boundary. Errors carry code and message; codes are unavailable, unknown_command, invalid_arguments, command_failed, internal_error, busy, closed, timed_out and invalid_response. Unexpected native exceptions are redacted.

The command wire envelope carries the registered name and codec-encoded UTF-8 payload string. Replies contain either {"result":"encoded string"} or {"error":{"code":"...","message":"..."}}. Custom encodings and name stability are application contracts; version them when incompatible. Built-in updater actions retain their previous wire behavior. Only the main frame at lui://localhost can invoke on macOS; the loopback transport requires its launch capability. Updater helpers do not initialize application bindings.

Handlers run on bounded OCaml worker threads (default 16 in flight; explicit registry limits must be 1–256), with 1 MiB encoded request/response limits. They must marshal UI work to the native UI thread themselves. The WebKit bridge allows 256 pending requests and a five-minute timeout. Page close/navigation rejects pending calls and discards stale replies; already running handlers are not cancelled. Applications must manage their own cancellation and side effects. No migration is required for applications using only the existing update API.

macOS sparse-list animated scroll convergence

Animated sparse virtual-list scroll requests now share one 250 ms animation deadline across viewport updates and variable-row measurements. Corrections after that deadline apply immediately, so repeated retargeting cannot keep restarting the animation before the destination row is reached. A new scroll token starts a new animation deadline.

The scroll-animated default, wire properties and completion outcomes remain compatible. succeeded still requires stable native row geometry and visible alignment. Applications need no source changes: for example, an existing virtual_list ~scroll_target:"row-99999" ~scroll_token:1 rows now settles even when measured row heights differ from item_extent; keep waiting for its ScrollCompleted event rather than a fixed delay.

Unreleased: macOS sparse rows use independent hosting graphs

macOS sparse virtual rows now retain an independent SwiftUI hosting graph per mounted row. Measured row heights propagate back to the outer layout, including growth and shrinkage after mounting. Existing row identities, retention leases, focus, composition and shared-scroll ownership remain authoritative. iOS keeps its existing row host.

Anchored macOS popovers and hosted dropdowns now present through NSPopover, including anchors inside independent row hosts. Native content-size changes resize the popup; current retained declarations still own admission and dismissal. No wire fields, public signatures or event names change. Applications keep their existing anchor properties and Dismiss handlers. Custom SwiftUI extensions must not depend on preference values crossing an independent hosting-controller boundary; pass required state explicitly through their extension context.

Unreleased: Apple scroll padding moves with the document

Padding on a scroll node now belongs to its scrolling document. The native viewport and scrollbar occupy the whole container, and content fills the native cross-axis proposal without adding the scrollbar width to the container. For example, a 320-point-high scroll with 32-point vertical padding keeps a 320-point viewport and adds 64 points to its document height. Remove any application-level compensating outer padding when adopting this behavior.

On macOS, hover-opacity tracking is now a hit-transparent native tracking view mounted only when hover opacity is declared. Empty layout and overlay containers no longer acquire an interaction surface from unconditional SwiftUI hover handlers. Late tracking activation samples the current stationary pointer; retired trackers cannot deliver pending samples. No application migration is required for ordinary buttons, overlays or hover-opacity properties.

Unreleased: Apple hosted menus keep retained declaration admission

Apple anchored dropdowns presented by the stack/panel/card menu host no longer reopen when an interactively dismissed retained menu receives another revision. On macOS, a declaration first encountered, rebound to a different host, or attached to a new native host while a mouse button is held stays suppressed after release. Already admitted menus keep working during a hold. Native close and hosted Escape consume only the current model/host/attachment/mode lease and emit the existing Dismiss once; programmatic teardown does not emit another. Deferred delivery rechecks the consumed lease before calling the application, so a replacement model that reuses the numeric node ID cannot receive that close. Destructive host/menu removal retires this authority as soon as its patch is accepted, including same-ID recreation while observable commits coalesce. An old close arriving before the quiet-timer flush, or queued across that patch, is discarded; unrelated unguarded events keep their existing delivery behavior.

To reopen, retire the mounted dropdown declaration, commit its removal, then create a fresh declaration from a later independent activation after release. For example, on_dismiss sets the selector's open signal false and lets the conditional dropdown removal commit; the next ordinary activation sets it true. Changing a label/revision, or a false-to-true toggle coalesced before removal is observed, no longer reopens the same declaration. iOS uses the same dismissal lifetime with physical-held=false; popover/dialog migration revokes the old close lease while preserving an admitted declaration.

No public API, wire field, event name, anchor coordinate or selected-value handler changes. This covers the existing anchored menu host only, not all dropdown factories: row/column inline dropdowns, native Menu/submenus, comboboxes and tooltips keep their own presenters. A new declaration first delivered after release has no causal input receipt and is not classified as a stale drag by this guard.

Unreleased: Apple sparse scroll completion observes native placement

Apple sparse lists now keep requested/planning offsets separate from native observations. An accepted scroll write or a mounted, measured target alone no longer emits ScrollCompleted(..., "succeeded"). Completion rechecks the current token, source generation, semantic target/index/row, owner and native connection, offset, clamp and target rect after its asynchronous boundary. Changed evidence discards that queued success and reevaluates a still-current request; unavailable native geometry remains pending until fresh evidence or existing cancellation / missing-target handling. Both shared-owner and standalone sparse lists use this gate. Existing shared-owner writes continue ignoring scroll-animated.

No API signatures, wire fields, event names/outcomes, anchor meanings or token deduplication rules change. Continue matching the current token and application intent: for example, a consumer awaiting token 7 must ignore completion for token 6, and must still perform its own current-intent and exact-control checks after token 7 completes. Scroll success proves the scroll stage only; it does not register an editor, claim focus/IME readiness, acknowledge retention or release an opaque Core receipt. There is no new timeout or wire-version migration.

Unreleased: Apple reactive fragments do not create layout boxes

An unmodified box whose only property is display: contents now forwards its children into an Apple layout container's flow. Empty reactive/keyed fragments occupy no gap or sizing slot, and populated fragments preserve their children's order, grow factors and absolute positioning. The retained wire tree and node IDs do not change, and virtual-list sources retain their semantic row identities. Fragments with surface or input properties keep their existing native container behavior.

For example, a row containing [a; empty_fragment; b] with gap 4 now has one 4-point gap; a fragment containing [b; c] lays out as [a; b; c]. Applications that require a real box must use an ordinary box without display: contents. There are no API signatures or wire-version changes.

Unreleased: Apple anchored popover declaration ownership

Native anchored popover dismissals now remain suppressed for the lifetime of the retained popover model, including commits where its anchor is temporarily unreachable. Geometry-only updates no longer cause a current dismissal callback to be rejected. A stale callback still cannot dismiss a replacement model or anchor identity. Primitive binding feedback remains close-only.

On macOS, a new or rebound anchored candidate encountered while a physical mouse button is held is rejected for that declaration's lifetime. Releasing the button or repainting does not replay it. Retry by removing the rejected popover declaration, committing its retirement, and constructing a fresh declaration from a neutral explicit user action. An already admitted presentation keeps working during a hold, including geometry updates. iOS admission is unchanged.

There are no public Swift/OCaml signatures, wire fields, or schema changes. This does not add a timed outside-close grace or infer a dismissal reason from the unit Dismiss event. Applications own any target-specific re-show delay.

Unreleased: Flat Apple virtual list retention (opt-in v1)

Applications may explicitly select ~virtual_capabilities:[Lui_virtual.Shared_viewport_retention_v1] on Lui_app constructors, Lui_runtime.create / create_with_extensions, or Lui_multi_window.create. The default remains []. Only SwiftUIHost supports shared-viewport-retention-v1; selecting it on an unsupported host or binding an owner/source without selecting it raises Invalid_argument. Standalone virtual_rows remains available without the capability and keeps its default configuration. The existing VirtualWindow ABI is unchanged.

Apple sparse window delivery now checks source/viewport intersection before overscan, including standalone lists. A nonempty source outside the viewport can therefore emit an empty half-open maintenance window (first = last), with independent pins. Inclusive public visible ranges can be (0,-1) or (count,count-1). Preserve these empty intervals instead of fabricating a visible row or inferring missing-target/release completion.

Direct consumers of emitted Melange JavaScript must account for the new optional argument: App.create(undefined, undefined, backend, model, reducer, view) passes the defaults for virtual_rows and virtual_capabilities, respectively. OCaml callers keep named optional arguments.

Lui_virtual adds opaque owner, source, retention, and receipt handles, binding = {node : int; lease : int}, create_owner, dispose_owner, root_source, binding, retain, ticket, receipt, receipt_status, request_release, cancel_retention, and supports. shared_viewport_version is 1. Create handles in application state before mounting. Bind an owner with Lui_elements.scroll ~virtual_owner and a source with Lui_elements.virtual_list ~viewport; direct Lui_dynamic.virtual_rows callers also pass ~viewport:source. Use stable semantic scroll_key values in the source's virtual_rows. Binding/receipt signals are borrowed: do not dispose them from consuming views. Unmount invalidates the binding lease; explicitly dispose the owner when its application state ends.

Each owner has at most one flat root source. Owners cannot nest. Independent scrolling documents may have independent owners. A participating source/owner cannot be nested under another virtual list, and its rows cannot contain virtual lists or owners. Ordinary non-virtual layout/editor children remain supported. Journals and page view use the same flat contract: the application projects the expanded tree into ordered rows carrying depth/section data rather than recursively creating virtual child lists. Supply the complete projected row sequence, including off-window rows, with unique stable semantic keys. Application loading and expansion must put a hidden target in that projection; the SDK does not expand branches or retain semantic ancestors.

let owner = Lui_virtual.create_owner () in
let outline = Lui_virtual.root_source owner ~key:"selected-root" in
let retained = Lui_virtual.retain outline ~key:target_key in
let native_ticket = Lui_virtual.ticket retained in
(* Build one scroll ~virtual_owner:owner and virtual_list ~viewport:outline;
   supply its flat projected rows with stable semantic scroll_key values.
   Pass native_ticket to the native registration/focus integration. *)
ignore native_ticket;
match Signal.sample (Lui_virtual.receipt retained) with
| Some proof when Lui_virtual.receipt_status proof = Lui_virtual.Focused ->
    ignore (Lui_virtual.request_release retained proof)
| _ -> ()

Retaining a flat row keeps its semantic key before cold mount, through viewport feedback, reorder, and row render replacement. A release request retains that key until a matching native Released receipt is validated. request_release returns Error Stale_receipt, Owner_retired, or Unsupported when its proof/lifetime/binding is invalid. Cancellation explicitly abandons the logical obligation. Source generations and owner leases invalidate older receipts; completion of a scroll command alone is never physical proof. Once a bound source publishes its complete projected-key index, a missing target publishes Missing_target through receipt; an unbound or not yet published cold source continues waiting. Known owner/source/row changes publish Stale and clear a pending release. These SDK refusal statuses do not invent a native proof and do not release or cancel the ticket. For example, an application can observe Missing_target and call cancel_retention when it abandons that reveal. Cancelling an offscreen ticket removes its exclusive rows immediately, without waiting for another window event; other tickets and native pins survive. Source-generated receipt changes publish after reconciliation commits. An observer may synchronously cancel a missing or stale target without reverting the source generation; failed candidate mounts publish no intermediate refusal. Existing scroll targets still cancel only with a fresh empty control token; reusing the same token with an empty target does not cancel pending work.

The typed schema appends virtual-viewport-epoch, virtual-owner-node, virtual-owner-epoch, virtual-row-keys, virtual-retentions, and virtual-retention-releases after existing properties. Owner/source leases are positive integers. Row keys are a unique string vector of nonempty semantic keys parallel to mounted children/virtual indices. Retention records are {ticket,key}, releases are {ticket,receipt} with the exact original opaque receipt string. Multiple sources per owner, nested virtual lists/owners on the participating path, cross-owner binding, malformed records, and nonpositive epochs are rejected atomically. These are canonical typed properties, not data attributes.

The flat source reuses its declared owner's existing vertical native scroll view. Local content position is ownerOffset - sourceOrigin; there are no child-source paths, nested virtual windows, or multilevel anchor arbitration. The first version fails closed for intervening scroll containers, scaled/rotated transforms, detached geometry, and stale row placement. Offscreen sources do not create overscan requests for unrelated rows. Ordinary sidebar/Journal/Views roots need no changes unless opted in. The owner anchors its actual native leading visible flat row across layout changes, choosing a crossing row or the next visible row after a gap. Source measurements and generation reconfiguration do not independently scroll the owner. Apply one correction for that row's physical displacement after native layout. Explicit scroll targets and native scrolling establish a new anchor; standalone sources retain their existing local compensation behavior. Reading anchors follow the same semantic key and retained native row model across source generations; physical receipts remain generation-bound. Selection uses the one flat source and checks native clipping/hidden/alpha eligibility. Public setScrollTop and scrollIntoView establish a new anchor even when the accepted intent leaves the native offset unchanged. Shared owner corrections and source scroll targets use that owner's bound native scroller directly; optional host scroll-query probes are not a prerequisite.

Native controls/extensions must call LUIAppleBackend.registerVirtualNativeView(nodeID:view:) for their exact retained node and unregister the returned LUIVirtualNativeRegistration when that view lifetime ends. Registering the same view for the same retained model is idempotent; rebinding it to another model invalidates its previous registration. After layout, call acknowledgeVirtualRetention(ownerNode:ticket:view:requirements:) using LUIVirtualHandoffRequirements (.attached, .visible, .focus). Attachment is always required. The backend verifies the live registration/model identity, current owner/source/row incarnations, actual row anchors, geometry, window, visibility, and requested native focus. A successful call emits a compact opaque v1 receipt with status pinned or focused and exactly one source-row proof. Release rechecks the same physical proof and emits current-generation pin feedback before released; stale proof leaves the cold obligation intact. The latest successfully emitted receipt per live owner epoch/ticket remains recognizable after native unregister, proof-cache eviction, or physical owner detachment. Releasing those exact bytes emits stale once per unchanged request, including when proof becomes invalid during pin feedback. Unknown or altered receipt bytes cannot authorize a release. A fresh acknowledgement is required to retry successfully; re-register a retired view first. .visible additionally requires a presented window and a nontransparent native view hierarchy; an ordered-out or transparent window/control may still satisfy .attached alone. Built-in SwiftUI controls are not implicitly registered by semantic key: downstream native integration owns their exact view lifetime and must not infer it from a midpoint hit test.

LUIEvent.virtualRetention(owner:ticket:receipt:) and OCaml VirtualRetention of int * int * string are appended; OCaml's constructor is after ExtensionEvent so previous runtime tags remain stable. Apple's legacy C callback appends kind 21, node argument 0, and JSON {"owner":integer,"ticket":integer,"receipt":string} preserving full integers. Kind 20 remains unchanged. External legacy callback consumers must decode kind 21; typed hosts forward the receipt unchanged to the ABI below.

The generic native ABI appends:

int32_t lui_ocaml_virtual_retention_utf8(
    int64_t owner, int64_t ticket, const char *receipt, int32_t length);
int32_t lui_ocaml_virtual_viewport_version(void);

The receipt function rejects IDs <= 0 or > Max_long, a NULL receipt even when length is zero, and negative length before acquiring the runtime lock. A non-NULL zero-length payload reaches the strict SDK decoder. Copying uses the exact byte length, including embedded NUL; the callback named lui_<prefix>_virtual_retention_utf8 receives three GC-rooted OCaml arguments (owner, ticket, bytes) with existing batch/exception semantics. VirtualRetention does not replace VirtualWindow feedback. The viewport probe returns 1 on Apple and 0 elsewhere; lui_ocaml_virtual_rows_version is unchanged.

Before downstream enablement, pair the OCaml and Swift SDK revision and verify Lui_virtual.shared_viewport_version, LUIAppleBackend.sharedVirtualViewportVersion, and the C capability probe are all 1. Update OCaml, Swift package, and Swift resolution pins together. Transport-only builds may forward the new event while leaving capability selection empty. SDK policy/unit/compilation checks do not establish physical Logseq scrolling, visibility, focus, or IME acceptance on macOS/iOS.

Migration from the earlier e42a6e6a proposal

The unreleased feature has been narrowed to flat lists. Remove child_source calls and project expanded descendants into the single root source instead. A second distinct root_source key for one owner is rejected; reuse its stable root handle. VirtualSourcePath / virtual-source-path, retention path, ancestor proof chains, and nested anchor/window arbitration have been removed. Applications must not encode the old metadata or create a virtual list/owner inside a participating row. Use the typed SDK DSL/publication APIs.

The exported helpers Lui_virtual.Internal.source_path and Lui_virtual_json.path are also removed. Neither has a flat replacement; downstream code must stop constructing or parsing semantic source paths.

Earlier e42 contract Flat migration
Lui_virtual.child_source and recursive virtual child lists Project journals/page-view descendants into one root row sequence. Depth, section and expansion are application data.
Multiple root keys for one owner Use one stable root key. Repeating that key returns the same source handle; a distinct second key is rejected.
VirtualSourcePath, generated virtualSourcePath cases and virtual-source-path Remove property construction, switch arms and manual wire emission. Do not send an empty path as a substitute; rebuild paired generated consumers.
Retentions {ticket,path,key} Publish {ticket,key} through the typed SDK. Release records remain {ticket,receipt}.
Native receipt rows containing an ancestor-to-target proof chain The paired SDK emits exactly one source-row proof and rejects multiple rows. Forward the opaque receipt unchanged; do not edit or truncate its JSON.
Ancestor cold pins, deepest-descendant anchors, nested windows and parent/child measurement compensation Retain the target flat row and use one owner window/leading-row anchor. The application loads and expands the domain tree before publishing the target row; it must not add a second compensation or ancestor proof chain.

root_source, capability/version names, native registration/acknowledgement, VirtualRetention, the UTF-8 C ABI, B1 callbacks, and release metadata signatures are unchanged. Existing owner/ticket/opaque-byte B3 forwarding needs no new parser or callback adaptation. Capability and receipt versions remain 1 for this unreleased feature; rebuild OCaml and Swift from the same selected SHA. No compatibility alias or fallback for the removed nested API is provided.

Unreleased: Apple CSS variable color references

Apple color props now resolve var(--name, fallback) and hsl(var(--name)) through semantic theme colors and the existing built-in color names. For example, background: hsl(var(--border)) now paints the built-in border color instead of remaining unstyled when no custom border token is registered. A theme's --border entry takes precedence over its border entry, then the built-in border color. Previously registered whole-expression colors retain highest precedence.

Fallbacks resolve recursively, including nested var() and hsl(var()) values. For example, var(--missing, var(--border, #ff0000)) uses the border color before the literal red fallback. var(--lui-border) resolves a registered --lui-border or lui-border theme entry; it does not invent a default for that custom name. Unknown references without a resolvable fallback and malformed expressions still return no color. Literal HSL values remain unsupported; only the variable wrapper is unwrapped. The wire format and public APIs are unchanged. Hosts need no opt-in, but should expect these previously unstyled color props to become visible.

Unreleased: Apple native dialogs during synchronized teardown

Apple native alert and confirmation-dialog bindings now return false while the modal store synchronously clears its active item during synchronization. The binding keeps its observed item dependency, then skips rich-content and presentation-style evaluation during that clear. A retiring rich dialog is therefore not asserted as a native alert by a re-entrant getter in that window.

For example, a Core batch that removes a rich dialog's children and detaches the dialog remains one atomic batch. Hosts need no split batches, forced refreshes or presentation workaround. Outside the synchronous clear, live dialog classification and normal alert presentation remain dynamic. Existing deferred modal replacement, binding setters and semantic event APIs are unchanged; this does not add identity checks for late setters or reused IDs. No public API, wire field, default or downstream opt-in changes.

Unreleased: Apple transparent container presses

Rows, columns and boxes with press-enabled now retain their native semantic tap region at exact opacity: 0, including when no hover-opacity is present. Opacity affects paint; it does not disable the container's press action. For example, changing only opacity from 1 to 0 preserves one semantic press per native click at the same visual-box location without a geometry update.

The container gesture is attached after visual opacity and clipping, before outer margin, on both plain and decorated surfaces. Its region includes the surface padding while outer margin remains outside. Existing native disabled behavior and child controls continue to govern activation. Native controls keep their own actions; a container gesture is not added to other widget kinds.

The event and frame-table APIs are unchanged. Downstream hosts need no raw pointer forwarding, synthetic press, opacity epsilon or cached-rectangle repair.

Unreleased: Apple surface hover opacity

Apple surfaces now render typed hover-opacity while an enabled node is under the native pointer. Hover opacity replaces the explicit opacity value rather than multiplying it; when the pointer leaves, the base opacity returns (default 1). For example, opacity: 0 with hover-opacity: 1 is invisible until hovered. Touch input without hover continues to use base opacity. Existing native disabled emphasis remains a separate factor.

Plain and decorated surfaces both support this behavior. Adding, changing or removing hover-opacity preserves the native content, draft and focus identity; it does not switch the plain/decorated rendering path. The hover tracker uses the laid-out visual box before outer margin, independently of paint opacity. Hover does not synthesize semantic presses or alter the frame-reporting API. Inline attributed Text runs remain part of their containing native text surface.

The wire property and its finite [0, 1] range are unchanged. Downstream hosts need no protocol migration or pointer-event workaround.

Unreleased: Apple overlapping frame producers

Transient SwiftUI view overlap can activate multiple frame reporters for the same retained model. When the most recently registered reporter disappears, the SDK now resumes the newest remaining live, active reporter that still represents that current model. Geometry comes only from that reporter's own matching sample. A reporter without a sample can resume registration and wait for its next geometry callback; released or unrepresented reporters cannot restore historical rectangles. Destructive model removal clears all registrations.

For example, if A publishes a frame, B temporarily supersedes A, and B then disappears while A remains active, the next snapshot can contain A's latest sample without requiring A's unchanged geometry to fire again. If A has been released or the model was dropped, its old frame is not restored. Native inline producers without a SwiftUI reporter retain their single-owner cleanup behavior.

onFramesReport and emitFramesSnapshot() retain their [Int: CGRect] API, batched delivery and reported-geometry semantics. Downstream hosts continue replacing their cached frame table on each report; no wire migration, layout barrier, coordinate adjustment or host-side recovery is required.

Unreleased: Apple frame snapshots retire dropped owners

Destructive detach-subtree and drop-node commits now revoke each removed node's frame before clearing native query registrations, including inline Text runs that have no separate SwiftUI view. Delayed geometry and disappearance callbacks belong to their original model and mounted producer; they cannot restore a dropped frame or overwrite or erase a replacement owner's frame. A replacement model can publish at the same coordinates without waiting for a later rectangle change, including when geometry precedes its mount callback.

onFramesReport and emitFramesSnapshot() keep their [Int: CGRect] API and batched frame-table behavior. For example, after detaching a Text subtree, the next snapshot omits its inline run IDs even before native teardown; if an ID is recreated, its frame comes from the replacement layout. Downstream hosts can continue replacing their cached table with each report. No wire change or host-side coordinate workaround is required. A snapshot remains a table of reported geometry, not a synchronous layout barrier for newly created nodes.

Unreleased: Apple atomic subtree recreation

An accepted batch that destructively detaches a subtree and recreates its IDs now publishes fresh retained models and child links from the final tree. Previously, the accepted nodes could remain absent from the native view model. For example, detach-subtree(2), create-node(2, search-field) and reinserting 2 in one batch produces a new usable search node; old focus requests and drafts do not belong to the replacement. This also applies across coalesced batches. No wire-format change or client-side split into extra generations is needed.

Unreleased: Apple minimum row height preserves tall content

A non-growing Row with default/stretch cross alignment and no explicit height keeps its intrinsic height through the outer minimum-height surface. For example, a min-height: 24 row containing 261pt of stacked content stays 261pt under parent compression instead of collapsing to 24pt around overflowing children. Growing, explicitly sized and absolutely positioned rows keep their existing sizing behavior.

Unreleased: Apple native search focus capability

Hoisted iOS search fields now consume host focus requests once and report keyboard ownership through SwiftUI's public search-focus binding on iOS 18+. A request also refocuses an already active search interface after another input takes focus. Hoisted search fields now honor the existing autofocus property.

iOS 17 search UI remains supported. Host requestFocus returns false for search-field on iOS 17, and search-field ownership is not reported there: search-interface activation alone does not identify keyboard focus. Downstream hosts must check the returned Bool rather than treating acceptance as completed native focus. Other text-input focus capabilities are unchanged.

Unreleased: Apple inline newline boundary geometry

An inline text run ending with a newline keeps the downstream insertion line in lineRanges, expressed as a zero-length range at the run's UTF-16 length. This applies both at the document end and before a following text run. Hit testing that line returns the run's end offset, consistently with caretRect.

Unreleased: Apple grouped controls host anchored popovers

Named popover targets inside a button group now mount the same presentation host and frame reporting as standalone nodes. For example, a Popover with anchor-target: "group-action" can target that button's accessibility identifier inside a button-group; group keyboard navigation keeps its existing behavior.

An anchored submenu child is presentation content, not menu label content. A menu-item with its own text and only a positioned Popover child now keeps its text label. Hidden children likewise do not replace the fallback label.

available-height bounds a native Popover's scrollable viewport. Overflowing controls remain reachable by scrolling; short content keeps its ideal height. The content stays mounted when its height crosses that limit, preserving drafts and native control identity. Adding or removing the property also retains the same native scroll and input controls. For example, updating a cap from 220 to 700, removing it, then restoring 220 does not clear an unbound input draft. Native scrolling still clamps its offset when the viewport grows past the content. Omit the property for an unconstrained ideal size.

Unreleased: Apple sibling paint order and transparent inline wrappers

Row, Column and Box now place flow and absolute children in one sibling paint scope. Their integer z-index values order complete child surfaces; equal values retain wire child order. Absolute children still contribute no intrinsic extent, gap or grow weight. For example, a Text with z-index: 1 paints above an opaque absolute selection layer with an omitted (zero) z-index. No client mutation or selection transparency change is needed. Stack children also honor z-index.

Inside Text, display: contents wrappers now contribute their Text descendants to the same committed TextKit document, recursively inheriting typography and foreground. A label containing text [box ~display:"contents" [text "Nov"]] therefore renders "Nov" instead of an empty label. The wrapper creates no native box or reported frame; leaf Text nodes retain their ranges and geometry. This inline behavior does not flatten wrappers in Row/Column flow layouts.

Unreleased: display: none leaves flow layout on Apple

display: none children are now removed from the parent's flow enumeration entirely — no frame slot, no gap/space-between spacing, no grow absorption, and no main: center|end spacer suppression on row, column, box, stack and the horizontal group kinds. Auxiliary slots (menus, tooltips) and extension children are unchanged. Hidden nodes still report no frames. Clients already treating display: none as "not rendered" only lose the previously stray spacing; no migration required.

Unreleased: Apple macOS native split divider replaces the overlay handle

On macOS, native split columns (NavigationSplitView) now use the system divider: held-pointer drags resize the sidebar natively and emit the existing split value-change event, matching the iOS behavior. The detail-leading overlay divider handle is removed, including its arrow-key and accessibilityAdjustableAction stepping; keyboard and assistive adjustments now go through the system control.

Model-driven fraction changes still resize the column programmatically: the backend applies the requested width once per push through the NSSplitView's public position API and tracks the rendered width locally. Programmatic applies do not emit a value-change event — pushes were never echoed back before. The divider keeps its flexible bounds throughout, so drags are never locked.

Native resize events use the backing NSSplitView arranged pane width, observed through its public resize notification. A child with max-width no longer stops value-change events as the divider moves beyond that child's width. Model-driven width applications remain silent.

Collapse and reopen through window chrome behave as before, including the hairline-fraction value change reported on collapse and the rendered-width report on reopen.

Unreleased: macOS requestFocus accepts button and menu-item

LUIAppleBackend.requestFocus(nodeID:) previously accepted only text inputs. On macOS it now also accepts button and menu-item nodes, using the same contract: latest request wins, the pending request is consumed once by the retained node it was issued for (including nodes still awaiting mount), and focusedNodeID reports whichever control — text input or generic — currently owns focus. Items rendered into real NSMenus (e.g. menu-bar menus) cannot take programmatic focus and never consume a request. iOS behavior is unchanged: requestFocus still accepts text inputs only there.

A focused macOS menu-item view now activates its existing press action on Return, including an item focused through requestFocus(nodeID:). Disabled or replaced retained nodes do not activate. Real NSMenu items keep native handling.

Unreleased: Apple parent-anchored submenus and hidden subtrees

A Popover with anchor but no anchor-target or explicit rectangle now attaches to its retained parent. For example, a menu item's Popover child with anchor: "right" opens beside that item in a native presentation; its child buttons receive their own press events instead of becoming inactive label content inside the parent button. Existing explicit targets and rectangles keep their behavior. Presentation sides select SwiftUI's attachment edge: right uses its trailing edge, and below uses its bottom edge. Popovers without positioning props retain inline rendering.

On macOS, native popup arrows now target the trigger's cross-axis center. AppKit controls body placement and screen-edge collision handling; its public popover API cannot independently align the body and arrow. start/end no longer pre-shift the attachment by the content size, which displaced the arrow from its trigger. For example, anchor: "below", anchor-alignment: "end" keeps its arrow over the trigger; it does not promise a trailing-aligned body for an interior trigger. stretch still sets the minimum trigger width and anchor-alignment-offset still shifts the actual attachment by the requested points. iOS retains its content-extent alignment behavior.

display: "none" now omits a node's native subtree from rendering, layout and frame reporting while keeping its retained identity and properties. Restoring the display property mounts the subtree from those properties. Hidden ancestors also suppress descendant popovers. For example, a hidden drag-instruction Box remains available in the retained tree without painting its text over a table.

Unreleased: Apple semantic color variable fallbacks

Color props now resolve nested var(--name, fallback) references against the inherited luiSemanticColors dictionary. Registering either --ls-primary-text-color or var(--ls-primary-text-color) satisfies the fallback in var(--ls-caret-color, var(--ls-primary-text-color)); hosts do not need to add each complete expression to the dictionary. Exact expression overrides retain precedence, followed by the named variable and then its fallback. Fallbacks may use existing semantic names or supported hex colors. A missing variable without a usable fallback remains unresolved, preserving the property's existing default.

Unreleased: Apple absolute children in flow containers

Box, Row and Column children with position: absolute are now excluded from normal flow sizing, grow detection and gap distribution. Their typed edge insets use the sized parent surface as the containing block, including opposing-inset stretching. Adding or removing an overlay preserves the normal children's control identities. For example, column [text "Draft"; column ~position:`absolute ~inset:0. [caret]] keeps the text's intrinsic height instead of stacking the caret overlay below it. Backgrounds, rounded clipping and committed text rendering remain unchanged.

A Box's positioned resize handle also stays outside normal flow. For example, a 32-point header button and a 32-point absolute handle share the header surface instead of creating a 64-point stack that can clip the header text.

An omitted Row/Column gap now means zero, matching the canonical flow default. Applications relying on SwiftUI's previous implicit spacing should set an explicit value, for example column ~gap:8 children.

Wire opacity applies to the complete node surface, including its background, border and absolute children. An opacity-zero caret keeps its geometry but does not paint its background; applications should continue emitting their normal opacity updates for blinking.

Unreleased: Apple retained popover presentation and menu child content

Apple popovers with anchor-target, anchor-rect, or at now use native popover presentation. For example, ~anchor_target:"pages-more" ~anchor:`below ~anchor_alignment:`end_ attaches to the retained node whose accessibility-identifier is pages-more; it no longer occupies an inline layout slot. Named targets can mount later and can be standard or extension nodes. Explicit rectangles and at use window coordinates. Native attachment edges, alignment offsets and spacing follow the existing anchor properties; on macOS the arrow remains at the trigger center and AppKit determines body placement as described above. The platform performs screen collision handling. Popovers without positioning properties retain their inline behavior.

Native dismissal emits the existing dismiss event for the popover, so applications should handle ~on_dismiss by removing its retained subtree. Updates to a dismissed retained identity do not reopen it. Removing and recreating it presents a new identity, including when the numeric ID is reused; late native callbacks cannot dismiss that replacement. Programmatic removal does not synthesize another dismissal event.

Menu items render their retained child content when supplied (including rows with Text and icons). Items without children use their own text, then their accessible name. Existing menu-item press events keep the menu item's ID.

Unreleased: Apple input focus, native sidebar synchronization and safe resync

Apple hosts can call backend.requestFocus(nodeID:) -> Bool for standard text-field, secure-field, input, search-field and textarea controls. True means the request was accepted, including before the control mounts; false means the node is unknown, disabled or not one of those controls. The latest request wins and is consumed once through the existing SwiftUI focus binding. Requests belong to the retained node identity: dropping and recreating the same numeric ID never transfers an old request. For example:

guard backend.requestFocus(nodeID: inputID) else {
    throw HostError.invalidFocusTarget(inputID)
}
// When routing a later key event, identify the focused standard text input.
let targetID = backend.focusedNodeID

focusedNodeID is read-only and reports the focused standard text input, or nil when none is focused. Extension controls keep their host-owned focus registries. Existing autofocus, draft composition and wire events are unchanged; hosts do not need to rewrite retained properties to repeat a focus request. Replacing a retained input identity remounts its control, so a reused numeric ID cannot carry the previous node's native draft or focus binding. Focus requests materialize pending coalesced model commits before classifying the target; a newly accepted retained input is focusable before its view mounts.

On macOS, a native sidebar nested directly in a manual split now reconciles retained fraction changes with the parent's target pane proposal, including during animation. Closing an outer right pane no longer caches a sidebar width calculated from the previous, narrower parent. Ordinary window-only resizing still preserves the native sidebar's width in points.

applySnapshot(json:) validates the replacement against a fresh retained tree before clearing or publishing anything. A rejected snapshot throws and leaves the existing tree, pending commits, generation and mounted identities intact; the same generation can be retried with a valid authoritative snapshot. Accepted snapshots keep their existing replacement semantics. Incremental apply failure generation handling is unchanged.

Apple menu items now accept a nonempty accessibility-label without an own text property, matching canonical admission. Native menu titles fall back to their accessible content label when own text is absent. Existing text and named-child forms remain supported; unnamed menu items still fail validation. Committed TextKit foreground colors are resolved in the actual SwiftUI environment before conversion to native colors, preserving semantic colors across light and dark appearance.

Unreleased: Apple typography variables, inline text and absolute stack children

Apple hosts can supply their current theme snapshot with the additive View.luiStyleVariables([String: String]) modifier or the matching EnvironmentValues.luiStyleVariables key. For example:

LUISwiftUIRoot(backend: backend, rootID: rootID)
    .luiStyleVariables(["--ls-page-title-size": "36px", "--ls-page-text-size": "16px"])

The existing font-size, font-family and line-height properties now resolve var(...) chains and nested fallbacks against this environment. For example, font-size: var(--ls-page-title-size, 32px) uses the supplied 36-point title size, or 32 points when the variable is missing. Custom property names are case-sensitive. Missing or cyclic references use the referring fallback; otherwise that typography facet leaves the inherited value unchanged. Literal typography keeps its existing parsing and inheritance. Supported length units are unchanged; this does not add CSS calculations or a stylesheet engine. Updating the environment re-resolves references, including in committed TextKit rendering. Raw retained properties stay unchanged, and the variable environment is carried into sheet and custom-dialog presentation.

Nested text children now draw as inline runs in a shared native TextKit layout instead of disappearing when the parent has no own text value. Each run inherits typography and can override it with its own typed properties. Wrapping and insertion positions come from the same layout that draws the whole line. textGeometry(nodeID:) also works for those child runs and zero-width U+200B pads: returned ranges and offsets are local to that child's UTF-16 text, and its frame encloses its laid-out fragments in window-content coordinates. Frame reporting includes these inline descendants. Snapshots still expire on patches, layout changes, scrolling and unmounting; queried leaf text keeps its existing API and presentation. For example, hosts can query each child of text [text "Hello"; text "\u{200B}"] without inventing caret metrics or turning inline runs into separate horizontal stacks.

The inline renderer handles Text descendants, including Text inside transparent display: contents wrappers. Place icons and controls in sibling layout containers; other non-Text inline children remain unsupported.

Apple stack, panel and card children with position: absolute now honor their numeric inset, inset-top, inset-right, inset-bottom and inset-left properties. For example, a 32-by-32 help button with inset-right: 32 and inset-bottom: 45 stays that distance from its containing stack's right and bottom edges as it resizes. Left/right remain physical edges in RTL layouts. Opposing insets stretch an automatic dimension; explicit width/height keep their existing constraints. Positioned children do not contribute to intrinsic stack size; finite parent proposals define the containing block. Stacks without absolute children keep their existing layout. Other positioning modes retain their existing fallback behavior; hosts do not need to rewrite this wire data.

Unreleased: Apple growing layout, collapsed splits and custom dialogs

Growing children in Apple rows now receive remaining width before flexible containers with grow: 0 (including the default when grow is absent). Empty rows, slot boxes and closed columns no longer divide the main content width. For example, row [scroll ~grow:1. content; column [spacer ()]] gives the scroll the available width rather than half of it. Nested growing title content also fills the space beside empty action/tag rows. Intrinsic single-line content keeps its higher priority, growing siblings keep equal priority, and existing explicit sizes and maximum widths still constrain layout. Hosts can keep their typed grow and max-width properties; no extra host widths are needed. Scroll content now takes its cross-axis minimum from the current viewport proposal, so shrinking a window also shrinks a vertical scroll's content width (or a horizontal scroll's content height) instead of retaining the old minimum.

Apple now admits dialog nodes without a text property, matching the canonical OCaml protocol. A dialog may supply its heading and body through its retained children. Previously, Apple rejected these batches with invalidBatch("modal surface requires text") before the custom content could mount. Existing native alert/action-sheet dialogs and titled sheets keep their presentation and dismissal behavior; sheet still requires a nonempty text property under the canonical contract.

For example, dialog [column [heading "Create graph"; input (); button "Create"]] may omit the dialog's own title. Apple presents the existing custom SwiftUI surface for this subtree, preserving its retained root and modal ownership. Hosts do not need to inject a title into the wire batch or replace the modal renderer.

Apple manual splits now omit the divider, focus target and resize interactions when either pane has zero rendered width or resize-handle-width is zero. For example, a right dock using value: 1.0 and gap: 0 no longer leaves a focusable vertical line after the trailing pane closes. Expanded panes keep the existing resize and accessibility behavior; reopening a dock uses the model's existing split width/value update.

Unreleased: desktop backend removal (breaking)

The native Go desktop backend, its Go module, host commands, capabilities, generated contract manifest, exporters, build/test scripts and CI workflow have been removed. There is no compatibility backend or alias.

Downstream hosts must use platform/apple for macOS/iOS SwiftUI, platform/android for Android, or platform/web for Web/Melange. Logseq keeps Electron for Windows/Linux desktop builds; LUI does not provide a native Windows/Linux desktop backend.

The removed OCaml host constructor is no longer part of host_kind in Lui_protocol or Lui_elements. Remove its match arms and select SwiftUIHost, KotlinHost or WebHost for the actual host. Native host code 5 is retired: it resolves to GenericHost and grants no bounded-row capability. Rebuild downstream OCaml code; serialized OCaml values containing the removed constructor are not compatible. Maintained host codes remain 1 (Web), 2/258 (SwiftUI) and 4/260 (Kotlin).

For example, migrate a macOS host profile to:

let backend = {
  Lui_protocol.backend_profile =
    Lui_protocol.profile Lui_protocol.MacOS Lui_protocol.SwiftUIHost;
  apply_batch;
}

Build the Apple backend through the root Swift package:

swift build
# Shared OCaml gallery library for the maintained Apple host:
opam exec --switch=5.5.0 -- dune build examples/components/native/liblui_components.dylib
LUI_COMPONENTS_NATIVE_LINK_INPUTS="$PWD/_build/default/examples/components/native/liblui_components.dylib" \
  swift build --package-path examples/components/ios-swiftui --product LUIComponentsApp

Keep platform/bridge, platform/services, existing reducers and views, and the mobile build tooling. Maintained host wire contracts, schemas and extension fingerprints are unchanged. shrink and on_focus_within remain Web-only; SwiftUI/Kotlin/Generic profiles continue to reject those opt-ins. Run make generate-component-schema to regenerate the remaining shared, Apple and Android schema artifacts; no desktop Go contract is generated.

Unreleased: Apple desktop host resources, committed text and schema admission

LUIAppleBackend adds these main-actor APIs on macOS 14 and iOS 17:

func registerIcon(name: String, svg: Data) throws
func unregisterIcon(name: String)
func naturalImageSize(nodeID: Int) -> CGSize?
func textGeometry(nodeID: Int) -> LUICommittedTextGeometry?
func isCurrent(_ geometry: LUICommittedTextGeometry) -> Bool
func setScrollTop(nodeID: Int, top: CGFloat) -> Bool
func scrollIntoView(nodeID: Int) -> Bool
func scrollMetrics(nodeID: Int) -> (offset: CGFloat, contentSize: CGSize, viewportSize: CGSize)?

Register a complete SVG under a canonical app:slug name, for example try backend.registerIcon(name: "app:graph", svg: Data(contentsOf: iconURL)). Registration replaces the previous icon and invalidates mounted uses; a failed validation leaves the previous registration intact. Unregistering an unknown name is harmless. SVG data must describe a finite positive intrinsic size and fit within 1 MiB. Both Swift packages pin SwiftDraw 0.24.0. Existing initial icon sources and the public LUIAppleIconSource enum are unchanged.

naturalImageSize returns decoded source pixel dimensions before layout scaling, thumbnail downsampling or source cropping, or nil until decoding completes. It supports image, avatar and file-image nodes. Registered images keep precedence over URL images. Changing the source or reusing a node ID cannot return an earlier source's dimensions.

LUICommittedTextGeometry contains nodeID: Int, generation: Int64, incarnation: UInt64, text: String, frame: CGRect, and lineRanges: [NSRange]. The frame uses window-content, top-left-origin logical points. caretRect(atUTF16Offset:), selectionRects(in:) and offset(at:) use text-local logical points and UTF-16 offsets. Display text, headings, paragraphs and labels opt into native TextKit drawing when first queried, then expose that same committed layout. Existing hosts that do not use this API keep their original SwiftUI Text rendering on iPhone, iPad and Mac; editable controls retain their existing native editing behavior. Uncommitted, hidden and unmounted text returns nil. Retained snapshots remain immutable; isCurrent rejects stale generations, source/layout changes, scrolling, unmounting and node reincarnation. Zero-width U+200B empty-block pads commit TextKit's actual line/caret metrics during native layout even when drawing is culled; caretRect(atUTF16Offset: 0) remains available without a synthetic font box.

Enable existing frame reports to retry pending resource/geometry queries:

backend.frameReportingEnabled = true
backend.onFramesReport = { [weak backend] _ in
    guard let backend, let geometry = backend.textGeometry(nodeID: blockID),
          backend.isCurrent(geometry) else { return }
    let caret = geometry.caretRect(atUTF16Offset: utf16Offset)
    // Add geometry.frame.origin to translate caret into window coordinates.
    _ = caret
}

Hosts storing UTF-8 byte offsets must translate them through their source run spans before calling these native UTF-16 APIs. Search-match previews expose the displayed excerpt as geometry.text.

The scroll controls bind to mounted native views without replacing the ScrollView, its delegates or gestures. setScrollTop accepts a retained scroll node and clamps a top-origin logical-point offset to its content range. scrollIntoView reveals any mounted standard node in its nearest enclosing native scroll viewport; it also returns true when already visible. For a scroll node itself, this reveals its viewport in an enclosing scroll. The methods return false for an unavailable target/viewport; missing IDs, non-scroll setScrollTop targets and nonfinite offsets are flagged by false. No exceptions or deferred commands are produced. scrollMetrics returns nil for missing, non-scroll and unmounted nodes. Sizes are logical points; UIKit's adjusted insets are excluded from the viewport and normalized out of offset. Probes mount lazily on the first call, so even an already displayed node may initially return false/nil. Retry using onFramesReport, guard pending requests against node incarnation, and discard requests when their node is replaced.

backend.onFramesReport = { [weak backend] _ in
    guard let backend, let metrics = backend.scrollMetrics(nodeID: scrollID) else { return }
    if hasPendingScroll && backend.setScrollTop(nodeID: scrollID, top: requestedTop) {
        hasPendingScroll = false
    }
    updateScrollHeight(metrics.contentSize.height)
}

Vertical retained ScrollView content now fills at least its viewport width; horizontal content fills at least the viewport height. Content can still exceed that minimum. This fixes centered, growing columns collapsing to intrinsic text width and applies consistently on macOS and iOS without changing scrolling axes.

Apple property admission now uses a matrix evaluated from canonical Lui_protocol.property_supported and checked against the schema, instead of limiting admission to rendered features. Schema-valid but unimplemented visual hints are retained and may be ignored by rendering; they do not reject an otherwise valid batch. Malformed values and graph invariants still fail atomically. This admits, among others, button gap, icon opacity, shrink, focus-within-enabled, zero-width resize handles and viewport anchor rectangles. After changing canonical admission, run python3 tooling/generate_apple_admission.py --export, followed by node tooling/generate_component_schema.mjs; --check detects stale exports.

Split accepts exactly one sizing mode: value is a fraction, while first-pane-width is an absolute logical-point width (including zero). For example, replace a rejected first-pane-width: 246 batch directly without adding a synthetic value; do not send both properties. Absolute width stays fixed as its container resizes, honors pane minimum widths, and emits value-changed in logical points. Fractional mode emits fractions. Resize origin uses the selected mode's units. The macOS fractional path without custom handle properties continues to use NavigationSplitView; custom handles and absolute sizing use the existing manual split path.

Unreleased: native navigation sheet action foregrounds

Apple navigation sheet toolbar actions honor the button's existing foreground property. For example, set button ~style_class:"confirmation-action" ~foreground:"foreground" ~text:"Done" [] to use the current semantic foreground for the title. The native toolbar placement, styling and disabled behavior stay in effect. With no resolvable explicit foreground, the system default remains. No wire-format or handler changes are required.

Unreleased: shared iOS input surface

Standalone iOS text, secure, search, and combo box inputs use a padded field with a semantic fill and a visible focus outline. Grouped text controls, native form rows, multiline editors, and other backends keep their existing rendering. The wire schema, edit events, and focus behavior are unchanged.

The fill resolves input, surface, then muted before the system fallback. The focus outline resolves input-focus, then primary before the system accent. Native SwiftUI extensions can use the same surface without changing their own keyboard or submission configuration:

TextField("Email address", text: $email)
    .keyboardType(.emailAddress)
    .focused($focused)
    .luiInputSurface(isFocused: focused)

Unreleased: one lui-agent protocol on every host

Scripts and coding agents can now drive a running app the same way on Apple, Android and Web. The shared OCaml runtime answers every request, so each host only carries strings.

A request is one flat JSON object with an op. The reply is one JSON object with ok:

{"op":"press","selector":"prop:accessibility-identifier=save"}
{"ok":true,"op":"press","node":42}

The protocol has these parts:

  • Ops. hello, tree, dump, find, prop, press, long-press, double-press, submit, dismiss, appear, change, type, toggle, value, key and ext. hello reports protocol ("lui-agent"), version (1), host, generation and ops.
  • Selectors. They use the Drive scenario grammar: id:N, kind:name, ext:identifier, text:needle, prop:name=value and prop:name=prefix*, joined with &. A bare number is an id and a bare word is a text needle.
  • Gestures. press, long-press and double-press go to the nearest ancestor that handles them. Every other action requires the selected node itself to handle the event.
  • Rejected requests. A malformed request, unknown op, missing node or unsupported event gets {"ok":false,"error":...} and changes nothing.
  • Refused requests. If an application handler raises, the call is refused in phase agent, the same way a refused native event is. Hosts answer {"ok":false,"refused":true,"error":...,"diagnostic":{...}}.
  • Patches. An action's patch batches reach the host's normal patch path before the reply.
  • Clock. An action may arm or cancel application-clock timers, so every native host re-reads the clock's next delay after each agent request, as it does after an event.

The new APIs, by layer:

  • OCaml. Lui_agent.handle, Lui_agent.app_target and Lui_agent.target. Lui_native_bridge.agent bridge request answers through a started bridge, and register adds <prefix>_agent (for example lui_kotlin_agent).

  • C ABI. Two new exports:

    int32_t lui_ocaml_agent_utf8(const char *request, int32_t length,
                                 void (*reply)(const char *json));
    int32_t lui_ocaml_agent(const char *request, void (*reply)(const char *json));

    Both return 1 when answered, including {"ok":false} replies. They return 0 when refused; in that case read lui_ocaml_last_error and resync as after any refused call. The batches go to the patch callback given to lui_ocaml_start, then reply receives the reply object.

  • Android.

    • LuiBridge.agent(request): String blocks until the OCaml thread answers and queues the batches for the sink.
    • The JNI library exports nativeAgent.
    • LuiAgentServer.start(port, answer) serves the same line protocol on loopback. answer defaults to LuiBridge.agent.
    • The Components app starts it only in debug builds launched with --ei lui-agent-port PORT. The debug manifest adds INTERNET. Reach it with adb forward tcp:PORT tcp:PORT.
    val server = LuiAgentServer.start(port = 49380)  // after LuiBridge.start
  • Apple.

    • LUINativeAgent(library:recovery:) (or init(agent:recovery:) with an @_silgen_name closure) answers requests and recovers refusals.
    • LUIAgentServer.startFromEnvironment(answer:) serves loopback TCP on the main queue when LUI_AGENT_LISTEN is set.
    • LUINativeRefusalRecovery.recover(_:) is check(_:) returning the failure.
    • The Todos, Split, Markdown, Components and Navigation hosts start the server in DEBUG builds. On the simulator, pass SIMCTL_CHILD_LUI_AGENT_LISTEN=127.0.0.1:PORT to simctl launch.
    let agent = LUINativeAgent(library: handle, recovery: recovery)
    agentServer = try LUIAgentServer.startFromEnvironment { agent.answer($0) }
  • Web.

    • Lui_web_agent.install target sets window.__luiAgent.
    • When the page URL carries ?lui-agent=ws://127.0.0.1:PORT (or ws://localhost:PORT), it dials that socket and answers each text frame. Other hosts are ignored.
    • A raising handler is answered as a refusal rather than thrown.
    • The Components and Chat pages install it.
    Lui_web_agent.install (Lui_agent.app_target ~host:"web" app)

Refusing to drive a stale build

tooling/lui_agent.mjs is the client for every host. It accepts --tcp HOST:PORT or --ws-listen PORT, and runs Drive-vocabulary script lines (press, type, toggle, expect, wait, expect-prop, dump, …), reporting every failing line.

The build scripts now write <artifact>.lui-build.json. It holds the artifact digest and the sha256 of every input file. The scripts that write it are:

  • the Android and iOS Components builds;
  • the Navigation simulator build;
  • the macOS build-app.sh scripts;
  • build_web_release.mjs.

--artifact PATH refuses to drive a build whose receipt is missing, or whose artifact or inputs changed. It names the command that rebuilds it and exits with code 3. --unchecked skips the check. node tooling/lui_build_receipt.mjs check --artifact PATH runs the check alone.

OPAMSWITCH=5.5.0 bash examples/todos/macos-appkit/build-app.sh
LUI_AGENT_LISTEN=127.0.0.1:49380 examples/todos/macos-appkit/.build/debug/LUITodos.app/Contents/MacOS/LUITodos &
node tooling/lui_agent.mjs --tcp 127.0.0.1:49380 --artifact examples/todos/macos-appkit/.build/debug/LUITodos.app \
  'hello' 'tree'

Compatibility

Every server is opt-in and listens on loopback only, so apps that do not set LUI_AGENT_LISTEN, pass the Android extra or call install behave as before.

The wire format, events and existing exports are unchanged. Hosts that load the library with dlopen resolve lui_ocaml_agent_utf8 optionally; a LUINativeAgent without it answers every request with an error.

Unreleased: wire batches skip unknown nested fields

Lui_wire.decode_batch still rejects malformed tokens, unknown operations, unknown node kinds, and unknown properties. Extra object fields — on the batch or on an operation — are now ignored when their names are not part of the operation schema, including nested objects, arrays, and null. Previously only extra scalars were skipped, so a newer encoder's object field failed the OCaml decoder.

Canonical encoder bytes are unchanged. Required fields stay scalars: "value": {"nested": true} is still rejected. Duplicate keys are unchanged (the first operation field wins; the last generation wins). Hosts should not emit duplicate keys; the shared fixtures use unique keys.

let batch =
  Lui_wire.decode_batch
    {|{"schemaVersion":1,"meta":{"nested":[1]},"generation":1,"ops":[{"op":"drop-node","id":1,"trace":{"ok":true}}]}|}
(* generation = 1, ops = [DropNode 1] *)

Unreleased: controllable application clock

Views schedule time-based work with Lui_ui.after context ms action and Lui_ui.every context ms action. Both return a Lui_clock.timer, run on the application's Lui_clock.t (Lui_app.clock app) and are cancelled when the owning view scope is disposed; Lui_clock.cancel stops one earlier. Actions run on the runtime thread like event handlers, so they may send directly:

let upload_button send : t =
  scoped (fun context ->
    let timer = ref None in
    button ~text:"Simulate upload"
      ~on_press:(fun _ ->
        Option.iter Lui_clock.cancel !timer;
        timer := Some (Lui_ui.every context 300. (fun () ->
          ignore (send Advance))))
      [])

Replace host-side setTimeout/DispatchQueue/Handler loops that only feed actions back into the model with these timers: they become deterministic under Drive and tests. Existing apps need no changes; a clock without timers costs nothing and never wakes a host.

Time is in milliseconds (float). Host time only moves forward; the first Lui_clock.tick anchors the clock without firing anything. Lui_clock.pause makes host ticks no-ops, Lui_clock.advance clock ms moves simulated time and fires due timers even while paused, and Lui_clock.settle fires every pending timer (raising after 10,000 firings to stop runaway every loops). Time cannot move from inside a timer action (Invalid_argument).

Host contract, implemented by every maintained host in this release:

  • Native C ABI: new exports lui_ocaml_clock_tick(double now_ms), lui_ocaml_clock_advance(double ms), lui_ocaml_clock_set_paused(int32_t) and double lui_ocaml_clock_next_delay(void) (negative when nothing is due, paused or not started). After every call into the runtime the host reads next_delay, arms one wakeup and calls clock_tick with monotonic milliseconds when it fires. Bridges built with Lui_native_bridge.register get the OCaml side automatically.

  • Android: LuiBridge reschedules a Handler.postAtTime wakeup on the lui-ocaml thread after every dispatch, ticking with SystemClock.uptimeMillis(). New JNI exports nativeClockTick, nativeClockAdvance, nativeClockSetPaused, nativeClockNextDelay and public LuiBridge.advanceClock(ms) / LuiBridge.setClockPaused(paused). Custom JNI libraries must compile the updated lui_jni_bridge.c.

  • Apple: new LUIRuntimeClock in LUIAppleBackend. Create it with LUIRuntimeClock(library: handle) for dlopen hosts or LUIRuntimeClock(tick:nextDelay:) with @_silgen_name functions, call reschedule() after starting the runtime and after every runtime call (typically defer { clock.reschedule() } at the top of backend.onEvent), and cancel() before lui_ocaml_stop:

    let clock = LUIRuntimeClock(library: handle)
    backend.onEvent = { event in
        defer { clock.reschedule() }
        // existing dispatch
    }
  • Web/Melange: call Lui_web.drive_clock app once after Lui_app.start. It ticks from performance.now() with one armed timeout and flushes after each tick, using the new Lui_clock.set_wakeup hook.

  • A timer action that raises is a refused call with phase clock: every native host routes tick results through its existing refusal recovery (diagnostic plus resync), exactly as for a refused event.

  • In-process apps (tests, custom hosts) call Lui_app.tick_clock app ~now or Lui_app.advance_clock app ms, then Lui_app.flush, or register a Lui_clock.set_wakeup callback.

Drive scenarios gain clock pause, clock resume, clock advance <duration> (250, 250ms, 1.5s) and clock settle. In-process sessions support all four; FFI targets support all but settle and report the missing exports for libraries built before this release; live websocket targets report the command as unsupported.

Unreleased: native bridge reports refused calls

When OCaml raises while a native bridge boots, dispatches an event, resyncs or disposes, the C entry still returns 0 and delivers no batch. The bridge now also records a diagnostic, and the new export returns it:

int32_t lui_ocaml_last_error(void (*receiver)(const char *json));

It hands receiver one JSON object, clears it, and returns 1; it returns 0 when no diagnostic is pending. A later accepted call also clears it.

{"bridge":"Todos","phase":"dispatch","node":42,
 "message":"invalid property value ...","recovery":"resync"}

phase is boot, dispatch, resync or dispose; node is present for a dispatch. Batches recorded before the exception are discarded, so the host mirror is stale: report the message, then call lui_ocaml_resync and apply its snapshot rather than keep rendering what mounted before the throw. The bridge still prints the exception to stderr.

The wire format, existing exports and return codes are unchanged. A host that does not adopt the export keeps its old behavior. Resolve the symbol optionally to stay compatible with older libraries. A 0 without a pending diagnostic is argument validation in C, which records no patches and needs no resync. OCaml callers can read the same record with Lui_native_bridge.last_failure and take_failure. Bridges registered with Lui_native_bridge.register gain <prefix>_last_error automatically, so lui_kotlin_last_error exists for JNI.

Every maintained host now consumes it:

  • Android: LuiBridge logs the failure, requests a snapshot through the existing resync path and notifies the optional LuiBridge.failureListener on the main thread with a LuiRuntimeFailure. A failed start reports its diagnostic the same way. The JNI library exports nativeLastError().

    LuiBridge.failureListener = LuiBridge.FailureListener { failure ->
        showError("${failure.phase} failed: ${failure.message}")
    }
  • Apple: LUIAppleBackend.applySnapshot(json:) replaces the retained tree with a lui_ocaml_resync batch. apply(json:) drops that batch as stale because it reuses the current generation. LUINativeRefusalRecovery wraps the two exports for hosts that load the C ABI themselves, and the Todos, Split, Markdown, Components and Navigation hosts use it. Hosts that resync outside this helper must use applySnapshot as well.

    let recovery = LUINativeRefusalRecovery(library: handle)  // or closures over @_silgen_name exports
    recovery.check(pressFunction(Int64(node)))
    
    func apply(json: String) throws {
        if recovery.isReceivingSnapshot {
            try backend.applySnapshot(json: json)
        } else {
            try backend.apply(json: json)
        }
    }
  • Drive: the FFI driver fails the scenario line with the diagnostic, for example target refused dispatch at node #1: …, and rebuilds its model from a resync snapshot. Drive.Model.clear empties a model before a snapshot.

  • Web/Melange runs OCaml in-process and has no C boundary. Exceptions still surface as uncaught JavaScript errors and no patches are dropped, so nothing changes there.

Unreleased: independent flex shrink on Web

row, column and box accept ?shrink:float. The typed ShrinkValue property uses wire name shrink and accepts only finite, nonnegative floats. Only these three standard kinds admit it. Web maps it to CSS flex-shrink. Generic, SwiftUI and Kotlin profiles reject explicit shrink values; Apple and Android also reject direct standard wire patches rather than ignoring them. Extensions/raw markup do not gain a shrink property or escape hatch.

Omitting or removing shrink preserves/restores the existing default factor 1. Setting or removing it does not change grow or flex basis. Existing callers need no changes. New callers must use a host supporting this property and a LUI version that knows the new wire name; older hosts reject that opt-in.

For a bounded, clipped single-line strip, opt in on each direct pill container:

row ~flex_wrap:`nowrap
  [row ~shrink:0. [text ~value:"First" []];
   row ~shrink:0. [text ~value:"Second" []]]

Use the existing typed overflow property on the strip for clipping. Shrink on the strip itself does not disable shrinking its children. Remove unnecessary child grow props to keep intrinsic sizing; do not substitute grow:0 for shrink:0.

Unreleased: opt-in container focus-within observation (Web)

row, column and box accept ?on_focus_within:(bool -> unit) on Web/Melange. Installing the callback enables the new boolean focus-within-enabled property and receives FocusWithinChanged (node, within). Without the callback/property, observation is off and existing views are unchanged. The callback does not make the container focusable or change keyboard traversal.

After mount/enable settles, the observer publishes one current snapshot, then only distinct transitions. True means focus is on the container or inside its rendered subtree. Moving between descendants does not emit an exit/reentry pair. Web coalesces local focusin/focusout checks at the microtask boundary, also checking after retained child removal. Web does not treat a popup/portal outside the subtree as inside merely because it is attached to a trigger. Window activation is not a second condition on retained focus membership; this is not an application-activation callback.

Web can observe focus within transparent boxes through their retained DOM subtree.

Disabled/inert ancestors normalize membership to false, including a terminal false for a previously focused subtree. Re-enabling observes current membership again. The last value is recorded before dispatch, so reducer patches do not cause repeated feedback. Same-node reconciliation retains the observation; opt-out or node retirement discards it. A new incarnation receives a fresh snapshot. Unmount cancels delayed checks without dispatching to a dead node.

SwiftUI, Kotlin and Generic host profiles explicitly reject this property, including explicit false; Apple and Android raw-wire hosts reject it too. Cross-platform applications must omit the callback on those paths, not expect silent no-event support. No Apple/Android focus framework or focusable group is introduced. Their existing focus behavior and appearance properties are unchanged. Rebuild the shared OCaml application and Web host together for the added event constructor and native lui_ocaml_focus_within_changed bool callback. Older native libraries remain usable without this opt-in; attempting to deliver the new event to a library without its callback fails explicitly.

For example, replace per-control focus handlers with one row-owned signal:

row ~on_focus_within:(fun within -> Signal.set toolbar_focused within)
  [comment_body; reactions; toolbar]

Combine that signal with the existing hover state to drive typed toolbar opacity. No new focus-within opacity property or data migration is needed.

Unreleased: Android editable Combobox menu focus

Android suggestion menus anchored beside a combobox retain keyboard focus in the input while the menu is open, so edits continue to emit text changes and filter the shared model-owned options. The native Material popup no longer takes input focus from an editable anchor, and the anchor stays mounted when its menu appears or disappears. Other dropdown and context menus keep their existing focus and dismissal behavior.

Existing stack [combobox ...; dropdown_menu ...] integrations need no API or wire changes; keep the query and filtered options in the shared model rather than manually refocusing or remounting the input after each edit. Apple and Web behavior is unchanged.

Unreleased: Android growing content and Gallery navigation

Android columns apply grow only when their vertical extent is bounded. Inside a vertical scroll viewport, growing children retain their authored height or intrinsic content height instead of collapsing and overlapping following controls. Bounded columns still distribute remaining height; applications do not need to remove grow from scroll-contained textareas. Android dialogs also render the existing description property above their retained body. Neither correction changes the wire format or event ABI.

The native Android component Gallery now derives a Material navigation drawer from the retained page roots and renders one selected page at a time. Shared OCaml model state remains authoritative across page switches; navigation is host-only and introduces no public LUI component. Its mobile E2E runner uses the checked-in platform/android/gradlew wrapper.

Unreleased: preserve Apple and Android backends

Apple/iOS and Android remain maintained backends alongside macOS SwiftUI and Web/Melange. Their backend sources, packages, example hosts, mobile tooling, Drive probes and CI jobs are restored after their unintended removal.

Downstream applications such as logseq/mobile and logseq/logseq_journal must keep their native backend dependencies:

  • SwiftPM consumers retain the LUIAppleBackend or LUIAppleBackendStatic product from the root package or platform/apple package. For example, Journal can continue using JOURNAL_LUI_PACKAGE_PATH=../lui/platform/apple.
  • Android consumers retain the platform/android/lui Gradle module and its JNI bridge. The optional platform/android/drive instrumentation module remains debug-only.
  • Schema generation emits LUIWireSchema.swift and LuiWireSchema.kt as well as the shared OCaml/PPX artifacts. Regenerate all of them from the current schema, including the modal transition declarations below.
  • Mobile build/test scripts, Maestro flows, Apple/Android CI and make test-apple remain supported. See the component gallery guide for commands.

Restoration does not rename public APIs, change host defaults or event semantics, or change wire batches and capability negotiation. Keep existing SwiftUI/Kotlin host integrations. The separate desktop migration still relocates the shared C bridge to platform/bridge as described below; it does not restore the retired SDL renderer.

Unreleased: modal surface transitions

dialog, drawer, and sheet now accept ~transition:string, like popover. The wire Transition property is admitted on these modal kinds; Root and Tooltip remain excluded, and transition values retain the same validated CSS shorthand grammar.

Pass the transition to the surface constructor rather than a post-mount property bind or a child container:

dialog ~transition:"opacity 200ms ease-out, transform 200ms ease-out"
  [text ~value:"Content" []]

Web applies this declaration to the real retained modal surface, preserving its opening/closing animation, focus restoration, and exit-paint lifecycle. Omitted transitions keep the existing host defaults.

Unreleased: retired SDL renderer and portable host services

The former platform/native OCaml/SDL renderer, its executables, packaging tools, renderer-specific plugins and native test jobs are removed, not deprecated. There are no compatibility aliases or fallback renderer. Web/Melange and the Apple/Android hosts remain supported; mobile backend retirement is not part of this desktop migration.

The shared lui_ocaml_* C ABI moved byte-for-byte to platform/bridge/lui_ocaml_bridge.c and platform/bridge/lui_caml_dispatch.h. Symbols, event dispatch, ownership, capability negotiation and wire batches are unchanged. Update source/header dependencies and include paths in downstream build rules; keep application bridge callbacks and examples/*/native libraries. These directories contain shared OCaml applications, not the removed renderer. The GC runner is now opam exec -- sh platform/bridge/stress/run.sh.

Exactly two former native libraries remain, under platform/services:

Public library Module Dependencies and runtime
lui.plugin Lui_plugin OCaml standard library (Mutex); unchanged registry API
lui.plugin_fetch Lui_plugin_fetch yojson and lui_plugin; runtime libcurl on macOS/Linux and libdl on Linux

Their public names and modules are unchanged; no SDL or renderer dependency is required. Fetch keeps its existing unsupported-platform error outside macOS/Linux; this move does not add Windows HTTP transport.

Every other public library formerly supplied by platform/native is removed:

  • Renderer/layout/resources: lui.backend, lui.blit, lui.d3d11, lui.flex, lui.gl, lui.gpu, lui.host, lui.image, lui.layout, lui.media, lui.metal, lui.paint, lui.retained, lui.raster, lui.resource, lui.resource_loaders, lui.scene, lui.spatial, lui.store, lui.svg, lui.text, lui.text_dwrite, lui.text_pango, lui.theme, lui.vulkan.
  • Input/platform services: lui.a11y, lui.ax, lui.ax_linux, lui.ax_windows, lui.gamepad, lui.ime, lui.input, lui.resilience, lui.shell, lui.shell_linux, lui.shell_windows, lui.updater, lui.webapp, lui.webview, lui.window, lui.window_linux, lui.window_windows.
  • Tools/plugins: lui.cli, lui.e2e, lui.e2e_json, lui.ed25519, lui.pkg, lui.pkg_linux, lui.pkg_webapp, lui.pkg_windows, lui.plugin_gamepad, lui.plugin_glass, lui.plugin_sqlite, lui.plugin_terminal, lui.plugin_updater_ui, lui.plugin_websocket, lui.plugin_webview, and the lui_pkg executable.

The shared lui runtime/element API remains. Keep reducers, signals and views in OCaml and embed the shared application library with platform/apple on macOS/iOS, platform/android on Android, or platform/web for Web output. Replace renderer-specific Dune libraries with lui and only the portable services actually used. Replace custom ../../../platform/native/lui_ocaml_bridge.c and adjacent header dependencies with ../../../platform/bridge/... at the same relative depth.

The old examples/components/webview-shell depended on removed lui.webapp and lui.webview and is deleted; use the Apple Components host or the existing Web build described in the Component gallery guide.

Historical entries below describing the removed renderer record previous releases; they do not promise those APIs remain available. Build and schema checks do not establish visual parity or native interaction acceptance.

Unreleased: Apple minimum scroll viewport reference

Apple hosts may set the optional EnvironmentValues.luiMinimumScrollViewport to a scene-global CGRect measured outside navigation keyboard avoidance and editor safe-area insets. Windowed virtual-list first-section minimum heights use the reference's bottom edge minus the scroll view's top edge, rather than the already-reduced local viewport. Actual scrolling and visible-range tracking are unchanged. With the default nil, existing local viewport measurement is preserved; no wire-format change is required.

For example, measure a NavigationStack background using GeometryReader with .ignoresSafeArea(.all, edges: .bottom), then pass .environment(\.luiMinimumScrollViewport, measuredFrame) to the stack. The background reports proxy.frame(in: .global) without changing keyboard avoidance on the interactive content. Update the frame on geometry changes so rotation and split-view resizing still change the minimum height normally.

Unreleased: Apple virtual-list first-section height retention

The legacy windowed virtual-list keeps data-first-section-count and data-first-section-inset as a minimum viewport height for its first section. The remaining space now belongs to the last real row instead of a synthetic lazy-list slot. Scrolling, pinned editing and scroll requests therefore retain the same logical row positions while row measurements survive recycling. Content taller than the minimum still grows normally; it is never clipped.

No wire or application changes are required. For example, a source with data-first-section-count=2 and data-first-section-inset=136 still reserves at least the unobscured viewport height minus 136 points for its first two rows. data-scroll-index=2 continues to address the third logical row, without an application-supplied padding offset. Sparse virtual-list sources are unchanged.

Unreleased: Native dialog transitions keep a fixed zoom origin

Retained enter/exit motion no longer re-reads a surface's resolved rect each frame while a track is running. The zoom anchor stays where the transition started, so dialogs whose layout is still settling no longer drift or shake during the fade/zoom. No view or wire changes are required.

Unreleased: Android Drive sample safe drawing insets

The optional :drive-sample Activity now explicitly enables edge-to-edge and wraps backend.Content() in Box(Modifier.safeDrawingPadding()). Controls respect current system-bar, display-cutout and IME insets instead of relying on fixed content padding. This changes only the sample's host layout; renderer defaults, native protocol v1, measured-coordinate conversion and strict occlusion checks are unchanged.

Applications that copied the sample should call enableEdgeToEdge() and apply Compose safe-drawing insets at their content boundary, or use their existing screen-specific inset handling. Do not compensate by shifting Drive coordinates or allowing input through SystemUI windows. See platform/android/drive/README.md.

Unreleased: DEBUG iOS read-only Drive probe

DEBUG iOS builds add LUIAppleBackend.debugDriveSnapshot() and LUIDriveSnapshotProbe.startIfEnabled(backend:window:environment:). These APIs are absent in Release and on other platforms. Retain the probe after the single foreground key window is ready, and call stop() during host teardown. Wrap host references in #if DEBUG:

#if DEBUG
driveProbe = try LUIDriveSnapshotProbe.startIfEnabled(
    backend: backend, window: window
)
#endif

No listener opens unless LUI_DRIVE_PROBE=1 is explicitly supplied. The probe temporarily enables frame collection and restores its settings without replacing existing callbacks. It binds only IPv4 loopback (default port 49378) and accepts versioned read-only snapshot requests; it has no Drive action or semantic event endpoint. This is debug access for trusted local processes, not authentication against other local applications.

Native input belongs to the separate Drive XCTest UI-testing target, never the app binary. Selector actions require explicit stable native accessibility identifiers and do not fall back to labels, coordinates or semantic events. Frame coordinates are window-local logical points, not screenshot pixels. Existing production event behavior and transport contracts do not change. See platform/apple/DriveProbe.md for a complete host hookup, protocol and lifecycle example. Apple-SDK compilation and Simulator/device input verification are separate integration gates.

Unreleased: Optional Android native Drive host

Android renderer defaults and existing semantic integrations are unchanged. LuiBackend.inspect() is a new opt-in, UI-thread-only read-only inspection API. Close its LuiInspection handle to remove inspection semantics and layout observers. Snapshots copy retained nodes and carry host-local incarnation guards; native targeting requires attached, visible geometry.

For an API 30+ debuggable test variant, add debugImplementation(project(":drive")), register DriveTarget.attach(activity, backend) after setContent behind an explicit debug intent flag, and close the handle in onDestroy. Declare dev.lui.drive.DriveInstrumentation only in the debug manifest. Keep the optional library, INTERNET permission, runner and test IME out of release artifacts. The sample supplies separate debug/release hooks.

# The debug app must already be installed; this clears its Activity task.
adb forward tcp:49377 tcp:49377
adb shell am instrument -w -e drive true \
  -e activity your.debug.package/.MainActivity \
  your.debug.package/dev.lui.drive.DriveInstrumentation
# In another terminal, with a Drive version supporting loopback TCP:
drive --tcp 127.0.0.1:49377 --input native scenario.drive
# After the run:
adb forward --remove tcp:49377

Native protocol v1 is unchanged: initial hello, full frames, then ops establish readiness; fresh ops and full frames precede each correlated result. Wire coordinates/deltas are content-viewport dp, converted to screen pixels at OS MotionEvent/KeyEvent injection. No action falls back to LUI semantic events.

Text replacement uses a real InputConnection and requires deliberately selecting the test-device IME; type is not advertised otherwise. The host never enables/selects an IME itself. Preserve and restore the original IME, or use the explicit --test-device sample launcher. Missing selection or geometry, stale incarnations, disabled/hidden targets, detectable native occlusion and unsupported input fail explicitly. Offscreen targets need native scrolling; there is no selector auto-scroll.

Settling is bounded model/layout/draw/accessibility quiet, not application or network idle, or proof of every render-thread animation. Accessibility cannot prove the behavior of arbitrary invisible custom touch interceptors; unmeasured modals/extensions and system UI need separate instrumentation. Already running input cannot be rolled back. Compile/protocol/lint checks are not device-input evidence. See platform/android/drive/README.md for complete integration, input and cleanup limits.

Unreleased: Native icon prop paints above state backgrounds

On the retained Native host, an icon prop on menu-item and number-stepper now paints with the node's content — after its background, hover-background, and pressed-background fills — instead of in the default chrome layer underneath them. A hovered or pressed control keeps its glyph visible; previously any declared state background covered the icon. No view or wire changes are required.

Unreleased: Native menu keyboard navigation

The retained Native window host opens a focused menu trigger with Return or Space. Menu keyboard traversal includes enabled submenu triggers. Right, Return, or Space opens the highlighted submenu. Left or Escape closes that submenu and returns focus to its trigger. Menu typeahead clears its prefix after 500 milliseconds of inactivity.

For example, a menu with a regular item followed by submenu ~text:"Type" entries now reaches Type with Down and opens it with Right. Hosts should keep forwarding native keyboard events and advancing the existing window clock. This uses the existing menu constructors and wire events.

Unreleased: Web submenu placement through layout wrappers

Web dropdowns owned by a menu-trigger or menu-item now find their semantic menu container through layout wrappers before choosing a default side. A context-menu, non-picker dropdown-menu, or popover ~role:`menu qualifies. For example, the following opens the submenu at logical inline-end (right in LTR, left in RTL), rather than below its trigger over the following row:

popover ~role:`menu [column [submenu ~text:"Property type" entries]]

Top-level menu and submenu calls without a semantic menu ancestor retain their below-trigger default. Listbox dropdowns and popovers without typed role:`menu stop the lookup; a DOM role data attribute is not a substitute. Applications that use popovers as menu containers should pass the existing typed ~role:`menu only on those containers, not on ordinary dialogs.

Explicit anchor values, viewport collision handling, pointer corridors, hover and keyboard behavior are unchanged. No constructor, wire, schema or native-host changes are required.

Unreleased: Web nested-layer Escape ownership

Web layers now route Escape from their content through the shared topmost-layer dispatcher before application document shortcuts run, even when those shortcuts were registered before the layer opened. With a popover inside a dialog, the first Escape dismisses only the popover; the next dismisses the dialog. This also works when focus remains on the popover trigger inside the dialog. Target-local handlers still run first, and defaultPrevented and composition guards remain unchanged. Consumed Escape does not reach document shortcuts.

Applications should keep dialog ~on_dismiss:close_dialog and popover ~on_dismiss:close_popover as the owners of dismissal rather than closing both in a document Escape shortcut. No constructor, wire, native-host or other keyboard behavior changes are required.

Unreleased: Apple closed drawer visibility

An overlay drawer's retained panel is hidden once closed. On iOS the panel uses a retained hosting controller inside a plain UIKit container. Closing sets the container's accessibilityElementsHidden, then detaches the hosted view from the window when the animation completes. Reopening attaches the same hosted view. The hosting controller and its SwiftUI content remain retained throughout; hidden hosting views can otherwise leave virtual accessibility proxies in the window despite SwiftUI and UIKit visibility flags. The panel remains mounted after its first reveal, preserving scroll position, native state and the inherited SwiftUI environment when reopened. Pinned split-view drawers, wire props and drawer events are unchanged; no application migration is required.

Unreleased: Android button labels in horizontal scrolls

Android icon/label buttons measure their natural content width before allocating space to the label. Both leading and trailing icon groups therefore retain their text in horizontal scroll containers instead of reducing a weighted label to zero width. Explicitly constrained buttons still reserve icon space and ellipsize long labels; no application workaround or new props are required. Other hosts and press events are unchanged.

Unreleased: Android list and menu content padding

Android list-item and menu-item apply authored padding inside their native Material controls, replacing native padding on each specified edge rather than adding a second outer inset. Unspecified edges retain Material defaults. An authored fixed height removes unspecified native vertical padding so compact nested controls do not consume the label's entire height.

Compact selection rows can keep their existing geometry:

list_item ~height:44 ~padding_vertical:0 [
  menu_item ~height:44 ~padding_vertical:0 ~text:"Choice" ~selected:true []
]

Remove explicit padding or height to use the corresponding Material defaults. Native selection, press events, disabled states and other hosts are unchanged; no wire or schema migration is required.

This guide records changes applications must consider when updating LUI. Keep it alongside the implementation: every public constructor, wire contract, default, event or compatibility change must receive an entry before release. Changes below are unreleased work following PR #271.

Unreleased: Android button content alignment

Android buttons center their label or icon/label group using the native Material control. Custom child content now honors child grow; descendant text inherits the button's text-alignment (center by default) unless it declares its own. Icon/label pairs reserve space for either leading or trailing icons and ellipsize long labels within the remaining width. Other hosts and press events are unchanged.

text-alignment no longer implicitly expands a label or its button to the full available width. Adjacent aligned buttons therefore keep their natural widths. Use explicit sizing when expansion is intended:

button ~grow:1.0 ~text_alignment:`center ~text:"Continue" []
button ~grow:1.0 [text ~grow:1.0 ~value:"Continue" []]

An explicit child text_alignment still takes precedence. No wire/schema migration is required.

Unreleased: Compile-time element nesting diagnostics

With lui.ppx enabled, statically resolved illegal element nesting now fails during compilation with a LUI nesting: diagnostic, the parent/child kinds and the offending source location. Admission rules are generated from the existing runtime protocol; valid constructors, node IDs, events and wire batches do not change. Applications without the PPX retain the existing runtime checks.

For example, replace context_menu [button ~text:"Copy" []] with context_menu [menu_item ~text:"Copy" []]. A tree needs row containers, so replace tree [text ~value:"Item" []] with tree [row [text ~value:"Item" []]]. Menu/toolbar restrictions also apply through statically resolved local values, nonrecursive helpers, List.map/concat_map, list concatenation, conditional/match/exception branches and structural wrappers. separator, menu and submenu use their actual underlying node contracts.

Correlated branches over immutable booleans or Lui_ui.host context retain their relationship, including aliases, negation and boolean matches. For example, let child = if android then dropdown_menu [] else context_menu [] in if android then menu_trigger [child] else button [child] remains valid. Separate effectful condition calls are not assumed to return the same value.

Structural reactive, if_ and keyed callbacks mount without an anchor; when one returns another structural primitive, the runtime creates a transparent Box. The checker accounts for that Box rather than treating every dynamic wrapper as transparent. For example, avoid nesting if_ inside reactive under a context_menu: choose the menu_item branch directly instead. virtual_rows requires a direct virtual_list parent and must be its sole child; use virtual_list [virtual_rows ~source ~key ~cmp ~mount ()], not a sibling row or a structural wrapper around virtual_rows.

This is a bounded source-level check, not a replacement for the type checker or runtime validation. Unknown external functions/modules, recursive results, runtime signals and expressions beyond the analysis budget can still require runtime checks. Lexically shadowed constructor/module names are not assumed to be LUI nodes. No type casts or protocol migration are required.

Unreleased: Android text wrapping and overflow

Android text, labels and paragraphs now honor the existing white-space and text-overflow properties. For example, text ~white_space:"nowrap" ~text_overflow:"ellipsis" ~value:"Long title" [] stays on one ellipsized line inside a constrained row. pre disables soft wrapping while preserving explicit line breaks; omitted properties retain wrapping and clipping. Existing line-clamp limits remain supported. No wire/schema migration is required; other hosts are unchanged.

Unreleased: Android sheets expand for text input

Android sheets that support the medium detent now expand when the software keyboard is visible, keeping form fields and actions above the IME. Hiding the keyboard leaves the sheet expanded; dismissal and explicit height constraints are unchanged. Existing sheet ~detents:"medium,large" [...] forms need no application workaround or wire/API migration. Apple and other hosts are unchanged.

Unreleased: Web component defaults and interruptible Accordion motion

Web buttons without size now use the same height and padding as size:default. On the iOS simulator profile, small buttons retain a smaller label while icon buttons have a square 44px target. Separators without orientation now render horizontally; vertical separators stretch across their row and have a one-em minimum height when their parent has no definite height. Explicit typed sizes and spacing remain supported; set ~min_height:0 when intentionally requesting a shorter vertical separator. For example, button ~text:"Save" [] no longer needs ~size:`default, and separator [] no longer needs ~orientation:`horizontal to be visible. Remove padding or separator-height workarounds added only to compensate for the missing defaults.

Web dialogs now separate their title and body, use the theme border color and respect the simulated device width rather than the desktop browser width. Explicit dialog heights remain supported and scroll when content does not fit; omit ~height for content-sized forms, as in dialog ~width:380 ~padding:24 [...]. The gallery's rename form now follows this content-sized pattern. Simulated keyboard space is still reserved while a field has focus, but is labelled as a noninteractive placeholder instead of displaying striped keyboard chrome. Use the host keyboard for text entry; this is not a software keyboard or IME.

Accordion expansion and collapse now transition from the current rendered height, including when reversed mid-animation. Completion callbacks from an older transition cannot hide or resize a newer one. The retained panel and children, controlled selected/on_toggle behavior, linked accessibility semantics and reduced-motion behavior are unchanged. Panel padding now belongs to an internal .lui-accordion-body wrapper, allowing the animated panel to reach zero height without a final padding jump. Applications styling that internal panel's padding should move it to their content or the body wrapper. No OCaml constructor, event payload or wire-schema migration is required.

Unreleased: Apple drawer SDK compatibility

The Apple drawer builds with the existing Xcode 26 / Swift 6.2 toolchain again. Its iOS 27.1 vertical-bar scene reader is compiled only when the SDK supplies SwiftUI 8.1 or later, excluding Mac Catalyst, whose SDK lacks these iOS-only APIs. The existing runtime iOS 27.1 availability check still applies. Older SDK builds and Mac Catalyst retain the standard drawer presentation, even when run on a newer OS; builds using a supported SDK retain the vertical-bar-aware presentation.

No constructor, wire schema, event or application source migration is required. For example, an existing drawer ~selected:is_open main sidebar is unchanged; rebuild its Apple host with the iOS 27.1 SDK or later to enable vertical-bar adaptation on supported devices.

Unreleased: Apple native button styles on OS 26

On iOS/iPadOS 26 and macOS 26, independent button and toggle_button controls use the system's Liquid Glass button styles: absent/default, outline and secondary variants use .glass (secondary keeps its secondary tint), while primary and destructive use .glassProminent (destructive keeps its red tint). Prominent labels retain readable white foreground ink when the application sets an inherited foreground style. Standalone icon-only default buttons also use .glass, rather than the former borderless style. The native styles supply the glass material and interaction; applications should remove custom action backgrounds, corner radii and padding that would cover the system treatment.

Ghost/content buttons remain borderless. Tab triggers keep their tab styling; the default whole-row Form action remains automatic, and default icon-only controls in native List rows remain borderless. Hoisted toolbar children retain the system toolbar style, while cells inside an existing glass capsule remain unadorned instead of drawing a second glass surface. Button actions, disabled/focus state, selection tint and declared hit-target dimensions are unchanged. Earlier Apple OS releases retain their existing bordered/borderless/automatic mapping. This is a host presentation change only: there is no OCaml constructor, wire schema or fingerprint migration. For example, existing button ~variant:`primary ~text:"Save" ~on_press:save [] needs no source change; remove any separately supplied background to see native prominent glass.

Unreleased: Apple wrapping rows

Apple now honors the existing row property flex-wrap: "wrap". Previously it was decoded but rows always used a single HStack. No constructor, wire schema or extension fingerprint changes. Rebuild the Apple host to enable the behavior; existing row ~flex_wrap:`wrap ~gap:16 children needs no source migration. Absent/nowrap retains the existing HStack path. This change is row-only: it does not implement wrapping for box or column.

A finite width proposal (including zero) bounds each line; nil/infinite width uses one natural-width line. Children are measured before breaking lines, and an oversized child is remeasured with the bounded proposal. An explicitly fixed child that cannot shrink occupies its own line and may overflow that line; it does not widen the reported bounded row. Empty rows have zero size. gap is the minimum space between items and between lines; no gap precedes the first item or follows the last line.

main start/center/end/space_between applies independently to each line, with logical horizontal placement mirrored in RTL. cross start/center/end/stretch uses that line's maximum measured height. Positive grow shares remaining line width proportionally after intrinsic bases and gaps; a spacer has a zero basis and grow at least one. Growing children are remeasured at their allocated width before line heights are finalized. Unbounded proposals do not allocate infinite grow space. There is no geometry-to-state feedback or application-specific grid.

Unreleased: Android pointer event capability checks

Android now checks the existing shared node-kind contract before emitting PointerDown or PointerUp. The pointer-enabled property is also set by ordinary input, submit, toggle and hover subscriptions; it does not grant every pointer event to every node kind. Text fields and other unsupported kinds no longer emit a rejected down/up pair before their native interaction. Supported pointer kinds and the existing role="treeitem" opt-in continue to receive down/up events when pointer-enabled is true. Disabled nodes remain inactive.

For example, an existing text_field ~on_input:handle_input [] requires no application change: native editing still emits TextChanged, without synthetic down/up events. Existing row ~on_pointer_down:handle_down ~on_pointer_up:handle_up [] handlers keep their shared event contract. Context menu position observation remains independent of down/up capability, so an attached context menu still observes its long-press location on a text control.

Pointer input restarts when the down/up capability changes. PointerUp is sent only after the observed gesture releases, not from coroutine cancellation during recomposition or removal. The shared receiver's strict unsupported-event checks, wire schema, handler subscriptions and other platforms are unchanged. Rebuild the Android host with this renderer; no source or wire migration is required.

Unreleased: Web scoped theme mode

The Melange DOM backend now consumes the existing theme-mode property instead of rejecting it during DOM application. light and dark select the default Web palette and native control color scheme for the node's subtree; system follows prefers-color-scheme, even inside a forced light or dark ancestor. Nested modes override outer modes, including an explicit light mode under a host .dark class. Removing the property restores the nearest enclosing mode or the existing host appearance when no enclosing mode is present. Unthemed hosts keep their existing default appearance.

For example, keep sending {"op":"set-prop","id":1,"property":"theme-mode","value":"dark"} to switch a mounted root to dark mode, or use "light" / "system" for the other modes. Send {"op":"remove-prop","id":1,"property":"theme-mode"} to stop overriding its inherited mode. No wire, schema or application API migration is required. Rebuild and deploy the Web stylesheet together with the Melange backend; updating only the DOM code does not provide the scoped palette.

Open sheets and other portals follow their retained logical ancestry across mode updates, property removal and reparenting, rather than the portal's physical DOM parent. An explicitly themed portal keeps its own mode, and a detached portal retains its last mode while exiting. Theme mode only selects palette tokens: it does not rewrite explicit foregrounds, author colors, disabled states or responsive styles. Custom token tables (theme) are a separate contract and remain outside this Web receiver change.

Unreleased: Android inherited foreground and scoped appearance

Android now applies a container's foreground to uncolored plain text in its subtree, with the nearest explicit container color winning. An explicit text leaf foreground still wins; an absent, empty, or whitespace-only value inherits rather than resolving to transparent. Use foreground: "transparent" or "#00000000" when transparency is intentional. Node colors resolve after the node's own theme tokens and effective appearance, so a foreground token on the same node uses the newly supplied palette. Removing a container's foreground restores the nearest ancestor's color without remounting.

For example, set {"op":"set-prop","id":2,"property":"foreground","value":"#EAE4DA"} on a Night tools column to color uncolored descendant text, and use {"op":"remove-prop","id":2,"property":"foreground"} to resume inheritance. Applications that relied on uncolored child text ignoring a container's foreground should set a color explicitly on those leaves. This does not apply the inherited color to every TextStyle or override Material buttons' native enabled, disabled, selected, focus, and accessibility behavior.

Android theme-mode: "dark" and "light" now switch the scoped Material 3 color scheme as well as adaptive semantic tokens. "system" restores the host's effective appearance, even under an explicitly dark/light parent; removing theme-mode inherits the nearest parent again. Scoped schemes retain the host's custom LuiTheme(light = ..., darkScheme = ...) palettes rather than replacing them with defaults. For example, set a child node to "system" to use the host palette inside a dark subtree, then remove that property to return to the parent's dark palette. Applications that relied on an explicit system silently inheriting the parent should remove that property instead. Material controls and sheet chrome now follow the effective scoped scheme; their native state colors remain owned by Material. No shared schema, wire format, or event contract changes are required.

Unreleased: Android text line clamps

Android now accepts the existing positive-integer line-clamp property on text, heading, paragraph and label, matching the shared OCaml contract, and passes it to those Compose text nodes as maxLines. Previously the Android validator rejected this property, including in authoritative snapshots, and the renderer had no line-limit consumer. This is not a numeric normalization change.

For example, keep sending {"op":"set-prop","id":2,"property":"line-clamp","value":1} to limit a text node to one line. Sending {"op":"remove-prop","id":2,"property":"line-clamp"} restores its original unlimited-line default. Nodes without the property keep their previous behavior; button labels, text controls and other text consumers are unchanged. No shared schema, wire, event or application rewrite is required.

Unreleased: Android single-line text placeholders

Android placeholders now follow their control's line policy: text-field, secure-field, input, search-field and combobox keep placeholders on one line and ellipsize overflow. textarea placeholders continue to wrap. Previously a narrow or zero-width field could wrap its placeholder character by character, inflating a single-line control and its containing row to hundreds of dp even though the editable text itself was single-line.

The wire format, default control height and grow behavior are unchanged. For example, keep sending {"op":"set-prop","id":2,"property":"placeholder","value":"Search this book…"}; no fixed height or placeholder rewrite is necessary. Applications must still provide usable width or responsive toolbar alternatives: this correction does not make a field usable when other row children consume all available width.

Unreleased: Apple normalizes all floating wire properties

Apple now normalizes integral JSON numbers to its floating retained value for every shared FloatValue property, not just the previously covered subset. JSONDecoder can decode 2.0 or 2e0 as an integer; previously, for example, {"op":"set-prop","id":4,"property":"letter-spacing","value":2.0} rejected the entire batch even though the OCaml producer emitted a valid float.

Existing normalization remains for item-extent, grow, anchor-offset, anchor-alignment-offset, source-x, source-y, source-width, source-height, value, min, max, and step. Newly covered properties are first-pane-width, resize-origin, resize-handle-offset, opacity, label-opacity, letter-spacing, inset, inset-top, inset-right, inset-bottom, inset-left, hover-opacity, pressed-opacity, disabled-opacity, width-viewport, height-viewport, min-width-viewport, max-width-viewport, min-height-viewport, max-height-viewport, popup-x, popup-y, available-height, and collision-padding.

No application migration or JSON rewriting is needed: continue emitting numeric values, including integral floats such as letter-spacing: 2.0 or opacity: 1.0. Fractional numbers keep their existing behavior. Boolean and string values are not converted; integer-only properties are unchanged. Property/kind admission, finite-value checks, numeric bounds, and atomic batch rollback are unchanged. The OCaml protocol and generic native ABI are unchanged.

Unreleased: Android accepts wrapping preserved text

Android's retained text-flow validator now accepts white-space: "pre-wrap", matching the existing shared OCaml and Apple vocabulary for this mode. Previously a valid batch such as {"op":"set-prop","id":2,"property":"white-space","value":"pre-wrap"} was rejected atomically, including authoritative snapshots, even though Compose Text already preserves the supplied text and wraps by default.

No application wire rewrite is required: keep sending pre-wrap for canonical text whose whitespace must be retained. This only corrects validation; it does not add CSS whitespace processing or change rendering of normal/nowrap. Android still rejects pre-line, pre, unknown strings and non-string values.

Unreleased: Linux native clipboard ownership result

Lui_shell_linux.clipboard_write : string -> bool keeps its signature but now returns the synchronous gtk_clipboard_set_with_data ownership result. Previously true only meant a GTK clipboard object existed after calling the void gtk_clipboard_set_text function. It was not an ownership ACK. There is no new checked/compatibility API or wire change. Existing platform-selected Shell.clipboard_write callers keep compiling; callers that ignore the result still do not receive a guarantee.

On Linux, false means missing clipboard support, ownership refusal, allocation failure, or rejected text: invalid UTF-8, embedded NUL, or INT_MAX bytes or more. The maximum accepted length is INT_MAX - 1 bytes. Rejected text is not silently truncated. Empty text is valid. The implementation copies the entire accepted UTF-8 string before acquisition, advertises GTK's text targets, serves requests through that owned copy, and frees it on ownership loss/clear/replacement. Failed acquisition frees the new copy immediately without first clearing the clipboard. The result is not inferred from a readback, change counter, transport enqueue, or SDL return value.

Replace an unchecked destructive continuation:

ignore (Shell.clipboard_write selected_text);
delete_selected_text ()

with an ownership-gated continuation using the existing platform-selected Shell module:

if Shell.clipboard_write selected_text then
  delete_selected_text ()
else
  report_clipboard_write_failure ()

If the application forwards this result asynchronously, its success continuation must additionally revalidate the original editor/selection owner before deleting; an ownership result does not authorize a stale edit. Keep failure handling explicit and never acknowledge an unhandled request.

Call the Linux Shell on the GTK UI thread and continue running Shell.pump there while owning the selection, including when no frame needs repainting. The existing pump iterates GLib's default main context and serves the data and clear callbacks; no extra loop, thread, or event API is introduced. true does not promise external paste success, indefinite ownership, or clipboard-manager persistence after exit. Successful acquisition retains the old gtk_clipboard_set_text helper's gtk_clipboard_set_can_store hint; that void capability hint is not a persistence ACK. No explicit store/manager handoff is added. macOS retains its existing NSPasteboard.setString BOOL result; other backends and their input limits are unchanged and are not newly qualified by this Linux change.

Unreleased: shared component API

Apple drawer swipes can interrupt transitions

Compact Apple drawers now accept a reverse swipe while an opening or closing animation is in progress. Previously, those swipes were discarded until the transition completed. The new drag owns the interaction lock, so completion callbacks and delayed model acknowledgements from the previous transition cannot unlock descendant controls during it. Vertical gestures and outward swipes keep their existing rejection rules.

No wire or application code migration is required. Continue acknowledging each ToggleChanged event through the drawer's controlled selected property. For example, after an opening gesture emits checked=true, publishing selected=true while the user has begun closing acknowledges that opening gesture without restarting its animation or cancelling the closing drag.

Owned pointer gestures on Row and Box

row and box now accept ?pointer_capture:bool, ?on_pointer_down, ?on_pointer_move, ?on_pointer_up and ?on_pointer_cancel. Capture defaults to false. The new wire property is pointer-capture; the new events are PointerMove (node, detail) and PointerCancel (node, detail). Both use the existing pointer_detail payload and client-space coordinates. Its modifier mask is unchanged: Ctrl=1, Shift=2, Meta=4, secondary pointer button=8.

With capture enabled, an admitted primary down owns movement and completion outside the handle. PointerUp means successful release; Escape, host blur, capture loss, pointer cancellation, disablement and removal cancel instead. A captured gesture does not activate Press, PressDetail or a context menu. Handle cancellation by discarding the preview, never by committing it:

box ~pointer_capture:true
  ~on_pointer_down:begin_preview
  ~on_pointer_move:update_preview
  ~on_pointer_up:commit_preview
  ~on_pointer_cancel:discard_preview []

Applications should also discard owned preview state when their view unmounts; a removed node cannot receive subsequent application events. Existing nodes without capture retain their pointer/press behavior and do not subscribe to movement or cancellation. The feature is implemented on Web; adding the shared vocabulary does not qualify other native hosts for captured gestures.

The Web DOM setter now accepts pointer-capture and clears its capability marker on removal. The retained property continues to control gesture ownership; changing or removing it resynchronizes the existing pointer listeners and cancels any active preview. Native DOM capture still begins only on an admitted trusted primary down, not when the property is applied. Existing typed handles, including the example above, require no migration or application fallback.

Row and Box also admit NavigationKey when ?on_navigation_key is provided: arrows, Home/End, PageUp/PageDown, Enter, Space and Escape, preserving Shift. No handler means no navigation subscription. Keyboard focus still belongs to the application's normal typed focus/role configuration.

Row and Box navigation focus ownership

On Web, Row/Box navigation callbacks only receive keys owned by that focused container, never keys from a descendant checkbox or editor. Web stops propagation after an admitted navigation event. Disabled and inert ancestors block navigation. Other controls retain their existing navigation behavior; no handler still means no subscription. Applications can replace a container's raw keydown bridge with row ~on_navigation_key:handle_row_key ... without intercepting keys typed inside child controls. Web containers retain the application's normal focus configuration, such as ~data_attrs:["tabindex", "0"].

Native OCaml makes navigation-enabled Row/Box containers focusable for pointer and Tab focus. Only the actually focused node receives navigation; child checkboxes and editors keep their default keys. Disabled/inert ancestors, hidden containers, modal scope and IME composition block container navigation. Ctrl/Meta/Alt combinations remain outside this navigation subscription; Shift is preserved. Existing button navigation and Enter/Space activation are unchanged.

Checkbox mixed state and modifier-aware proposals

Checkbox gains ?indeterminate:bool and its reactive binding, defaulting to false. The wire property is indeterminate. This is presentation and accessibility state; it never changes accepted checked. Activating a mixed checkbox proposes true. The next model update decides whether to retain or clear the mixed state.

?on_toggle_detail opts in to ToggleChangedDetail (node, checked, modifiers) through toggle-detail-enabled. Its independent physical-key modifier mask is Ctrl=1, Shift=2, Meta=4, Alt=8; it must not be interpreted as the legacy PressModifiers/pointer mask, whose bit 8 denotes a secondary pointer button. The existing ?on_toggle, bool checked, and ToggleChanged event are unchanged. If both handlers are installed each receives one proposal; do not apply the same state transition twice. With no detail handler no detail event is emitted.

The Web DOM setter now accepts toggle-detail-enabled and clears its capability marker on removal. This fixes a render failure for typed ~on_toggle_detail subscriptions; existing consumers require no migration or event fallback.

Mixed rendering and accessibility state are currently implemented only on Web. Web also implements mixed-to-true proposals and ToggleChangedDetail events. Apple and Android recognize the shared property vocabulary and perform typed admission; this does not qualify them for these behaviors.

The Native OCaml window input path now supports mixed-to-true proposals and opt-in ToggleChangedDetail for primary clicks and focused Enter/Space activation, including the physical Ctrl/Shift/Meta/Alt mask above. It does not mutate accepted checked or indeterminate; a model echo decides the state. Disabled/inert ancestors suppress checkbox activation. Legacy bool-event admission is preserved, and without toggle-detail-enabled=true no detail event is emitted. This qualifies only the window pointer/keyboard input contract, not native mixed painting, accessibility state or accessibility-action producers. Native consumers can use the typed ~on_toggle_detail example below without an application-level event fallback; handlers that also subscribe to ~on_toggle must still avoid applying the proposal twice.

checkbox ~checked:all_selected ~indeterminate:some_selected
  ~on_toggle_detail:(function
    | ToggleChangedDetail (_, checked, modifiers) ->
        select_rows ~range:(modifiers land 2 <> 0) checked
    | _ -> ()) []

Pending-aware application model reads

Lui_app.model app now returns the latest reduced model even before a pending signal update is published. This applies to regular, extension-enabled and reloadable application constructors. Reading the model does not flush the scheduler, run view updates or emit patches; view signals keep their existing batched publication semantics.

An async context fence can capture (Lui_app.model app).context_revision before starting a request and read it again before accepting the response. The revision must be incremented by the reducer for every context publication, including an A-to-B-to-A sequence in one flush. A published view signal cannot replace this fresh read because intermediate updates may be coalesced. Existing callers that read after Lui_app.flush require no changes; callers that intentionally need a published view snapshot must read their borrowed model signal instead.

Bounded row generation for virtual lists

virtual_list continues to accept literal children and keyed sources. Those forms retain every LUI row even when the host virtualizes its views. Applications with large collections can opt into virtual_rows as the sole direct child:

(* Before: every item owns a mounted LUI row. *)
virtual_list ~height:400 [
  keyed ~source:rows ~key:(fun row -> row.id) ~cmp:Int.compare ~mount:row_view
]

(* After: the host requests a window of rows. *)
virtual_list ~height:400 ~overscan:5 ~item_extent:32. [
  virtual_rows ~source:rows ~key:(fun row -> row.id) ~cmp:Int.compare
    ~scroll_key:(fun row -> Printf.sprintf "row-%d" row.id)
    ~mount:row_view ()
]

The business data source and its key index remain complete. On Web, SwiftUI and Kotlin hosts that advertise window feedback, only requested rows, overscan and active interaction pins own mounted scopes, signals, handlers and host controls. Overlapping windows preserve row identity; eviction disposes the row and a later visit creates a fresh incarnation. Store persistent editor values, selection and other row state in application data and bind them as controlled values. Late events cannot target a replacement incarnation. Source reorders preserve still-existing mounted keys until the host acknowledges the new source generation.

The source signal is borrowed. A reactive derivation passed as ~source is created and disposed per mount by the PPX, following the same ownership rule as keyed. Rebuild the PPX together with LUI. scroll_key is optional unless a lazy parent uses a nonempty scroll_target; it resolves targets without mounting intermediate rows. Duplicate item keys or scroll keys are errors.

Updated SwiftUI and Kotlin hosts implement the same bounded source contract. Literal children and the older application-managed window conventions retain their existing behavior. An individual row may still own a large descendant subtree, and host geometry caches may scale with source size. Virtual rows require positive logical geometry: a zero-height or empty root keeps a positive estimate or a host minimum of one pixel. This avoids repeatedly expanding the mounted window when blank rows collapse during layout; positive compact rows retain their measured heights.

SwiftUI and Kotlin retain their semantic platform profiles, including native extension selection. Their native startup handshake uses these codes:

Host Legacy code Bounded-row code
SwiftUI 2 258
Kotlin 4 260

The new C export lui_ocaml_virtual_rows_version() returns 1 and is safe to probe before starting the runtime. Updated Swift loaders select code 258 only when this optional export is available. The Android JNI bridge exposes the corresponding optional version probe before selecting code 260. Older libraries and older host clients keep codes 2/4 and receive the complete eager collection. Rebuild the OCaml application, native bridge and updated host together to enable bounded rows. An unrelated or unknown host code does not enable this capability.

Lui_app.create, create_with_extensions, create_reloadable and create_reloadable_with_extensions, and both Lui_runtime.create constructors, accept an optional ~virtual_rows:bool override. The default is true for Web, SwiftUI and Kotlin profiles and false for Generic. The override is fixed before mounting the view and persists through reload without changing the host profile. Custom native initializers must pass the negotiated capability:

let host_profile = Lui_native_bridge.profile platform_code host_code in
Lui_app.create
  ~virtual_rows:(Lui_native_bridge.virtual_rows_supported host_code)
  (Lui_native_bridge.backend bridge host_profile)
  initial_model reducer view

A custom Generic host may explicitly opt in after implementing the complete window protocol. Passing false preserves eager behavior on any semantic host. Code constructing a runtime record directly must account for its new immutable runtime_virtual_rows capability; prefer the runtime constructors.

Custom Swift event switches and Kotlin sealed-event handlers must forward the new virtualWindow / VirtualWindow maintenance event to the native window entry point, independently of application visible-range subscriptions. Apple's legacy C event callback appends kind 20 with legacy node argument 0; its JSON object carries authoritative integer node, generation, first, last and pins fields so IDs are never narrowed to the callback's Int32 node. The typed Swift event and the native OCaml window ABI retain full native integer precision. Existing ordinary callback kinds remain unchanged.

Sparse wire producers set virtual-total-count, virtual-generation and virtual-indices together on the existing virtual-list node. The indices are a canonical JSON integer vector parallel to committed children, strictly increasing and within the logical count. Optional virtual-scroll-index is -1 for a missing target or a valid logical index. Invalid final metadata rejects the entire batch. Internal VirtualWindow feedback uses a half-open interval and direct row node IDs for pins. Public VisibleRange keeps its inclusive range convention. The new event precedes ExtensionEvent; native consumers of raw OCaml variant tags must rebuild for its shifted extension-event tag.

Native host compatibility

Updated Apple hosts accept the existing navigate-enabled flag on buttons and the canonical text-entry kinds. Updated Kotlin hosts accept the existing navigation and navigation-heading list-item roles, with native selected-item and heading accessibility semantics. These properties already come from LUI constructors and the shared Gallery; applications need no source changes. Custom native validators must preserve the canonical finite kind and role sets when accepting sparse virtual-list metadata.

Kotlin ordinary lists use intrinsic column layout when their parent provides unbounded vertical space, preserving the outer scroll owner. Finite viewports retain native lazy-list scrolling and row targets. Applications can keep an ordinary list inside scroll without adding an artificial fixed height. Authored compact list-item heights preserve readable text by removing native vertical content padding while retaining horizontal insets and native input. Sparse Kotlin collections expose the supported native forward/backward scroll actions on their viewport even when interactive rows cover its content.

The Apple C bridge now closes its ARC-owned window safely during reset. The existing reset entry point and application lifecycle API are unchanged.

Large-batch encoder memory

The shared OCaml encoder processes large batches without retaining per-operation JSON copies. Wire bytes, integer precision and application APIs are unchanged. Rebuild application libraries to include the encoder improvement.

Nested toolbar focus ownership

On Web, a toolbar owns one keyboard Tab stop across its nested button and toggle groups. Group refreshes no longer create additional stops after model updates; arrow navigation continues through the complete toolbar sequence. Standalone groups retain their own roving focus behavior. Applications need no source change.

Toast keyboard dismissal

On Web, Escape now dismisses the open toast containing keyboard focus. Escape outside a toast, during IME composition, or after another handler consumes the event leaves notifications open. Applications should handle the existing dismiss event by removing that toast from their model. Independent notifications retain their own lifetimes.

The Gallery now demonstrates one notification per activation and disables its trigger while open. Its four-second duration is demo configuration; component defaults are unchanged.

Virtual-list configuration becomes typed

The OCaml constructor keeps its existing optional arguments:

virtual_list ~overscan:0 ~item_extent:32. rows

Previously these arguments generated data-overscan and data-item-extent attributes inside data-attrs. They now generate the overscan integer and item-extent float properties. overscan must be nonnegative; zero disables extra rows. item-extent must be positive and finite and estimates unmeasured rows; actual row measurements remain authoritative.

Applications using the constructor need no source change. Custom hosts and wire consumers must recognize the two new properties. Legacy semantic attributes remain readable during migration. Explicit typed properties take precedence; removing a typed property restores the legacy attribute or host default. Removing both restores the host default.

Prefer constructor arguments over hand-written semantic attributes:

(* Before *)
virtual_list ~data_attrs:[ "data-overscan", "3" ] rows

(* Preferred *)
virtual_list ~overscan:3 rows

Read-only editing is distinct from disabled editing

text_field, secure_field, input, search_field, textarea and combobox gain ?read_only:bool and reactive ?read_only_signal bindings. The default is false. Read-only controls preserve focus, selection, copying and navigation; they reject user edits and do not emit text-change proposals. Application model updates can still replace their displayed value. disabled continues to block interaction.

Secure fields retain their password-copy restrictions in read-only mode.

text_field ~text:"Reference value" ~read_only:true []
textarea ~text:(reactive Model.notes model)
  ~read_only:(reactive Model.locked model) []

JSON views use "read-only": true; custom hosts must decode the read-only boolean property. Removing it restores editable behavior. Applications that used disabled solely to prevent edits may switch to read_only when users should retain selection and copying.

The experimental self-drawn native backend now enforces the same contract: Lui_text_input.accepts_edits gates insert, delete, paste, cut-deletion, undo and IME commit/composition, while focus, selection, copy and caret navigation remain available. Typed virtual-list overscan and item-extent are read by Lui_layout with precedence over legacy data-overscan / data-item-extent.

Native bridge registrar is a polymorphic record

Lui_native_bridge.register takes ~register_named as { register_named : 'a. string -> 'a -> unit } instead of a bare function. Wrap Callback.register (or a test stub) in that record:

Lui_native_bridge.register
  ~register_named:{ register_named = Callback.register }
  "lui_ocaml" bridge

Tabs, lifecycle and scroll results

Ordinary tabs keep their application-owned content. Arrow keys activate the new focused tab, respecting orientation and disabled items. bottom_tabs renders the selected retained tab's page. Applications must keep selected under model control.

Scroll completion outcomes are succeeded, cancelled and missing-target. Visible ranges use inclusive first/last indices and 0/-1 for an empty viewport. Request tokens and appearance events are scoped to a node incarnation; reusing an ID after removal does not revive old queued callbacks. Scroll request tokens preserve exact OCaml integers, including neighboring values above 2^53; each distinct token starts a new request.

Complete native event payloads

The shared native C ABI includes length-carrying lui_ocaml_*_utf8 pointer exports for target_class without truncation. Existing C-string pointer exports remain available. Custom native bridge loaders using these exports must link the matching rebuilt application library.

PR #271: removed line-break component

The br component, OCaml constructor and standard wire kind were removed. Replace separate-line content with a column, or use a newline inside one text value when it belongs to the same text run. Do not register a custom standard br renderer: it does not restore a removed protocol kind. Raw HTML extensions keep their independent HTML element rules.

Upgrade checks for application maintainers

  1. Update generated wire schemas and custom host decoders together with LUI.
  2. Replace uses of br and invalid retained child shapes.
  3. Prefer typed virtual-list arguments; test any legacy attribute overrides.
  4. Review disabled editors that should allow copying.
  5. Exercise model rejection/normalization, keyboard navigation, resource replacement and stale async callbacks on each host the application ships.

The Web/Melange backend remains available for browser hosts.

Apple virtual-list viewport changes

Apple virtual lists now recompute row visibility when the viewport height changes, even when the row's frame stays unchanged. Initial layout and keyboard/viewport transitions no longer leave visible top rows outside the emitted VisibleRange. The event shape and virtual-window metadata are unchanged; applications need no API migration. Applications with bounded windows should verify initial page load and keyboard transitions without scrolling to repair the visible window.

Apple search input traits

Apple search-field controls disable automatic capitalization and spelling correction so a literal query is not silently changed by the keyboard. Inline controls use the Search return key; navigation/list-hosted native search retains its existing search submission. Ordinary text-field and textarea behavior is unchanged. No schema, event, query normalization or matching semantics change.

Applications should use Lui_elements.search_field ~on_submit:run_search [] for search rather than text_field. Keep on_input bound to the shared query and on_submit to the search action. Do not set submit_on_enter on either single-line kind; that property belongs only to textarea.

Web virtual-list resize measurements

Web virtual lists process TanStack ResizeObserver measurements in an animation frame rather than synchronously inside the observer callback. Rendering a measured row can resize an intrinsically sized list; deferring that render avoids ResizeObserver delivery loops when switching views or changing row dimensions. Initial layout, wire properties and event payloads are unchanged. Resize-driven visible ranges and virtual windows can arrive on the next animation frame.

Applications should continue to use virtual_list ~item_extent:320. rows and respond to on_visible_range rather than expecting the DOM range to change synchronously with a browser resize notification. No API or schema migration is required; other hosts are unchanged.

Primary pointer capture retains non-primary events

Web Row/Box pointer-capture no longer filters out non-primary PointerDown/PointerUp. The LUI handler does not start or end its primary drag state for those buttons.

Applications can keep ~pointer_capture:true for primary dragging and handle PointerUp (_, detail) with detail.button = 1 for middle-click actions. Do not assume that a captured control filters out non-primary releases. No property, event payload or primary drag/cancellation API changes are required.

Apple minimum-height columns retain intrinsic content height

An Apple column with min-height, no positive grow, no fixed or maximum height, and no absolute positioning now retains its content's ideal height. Previously its minimum-height surface could compress under a parent stack while centering taller children outside that surface, including above a scroll document's origin. Fixed, maximum-height, growing and absolute columns retain their existing sizing behavior.

Applications can keep column ~min_height:60 children: the 60-point empty surface remains, and taller content determines the surface height. Use an explicit height or maximum height when a bounded surface is intended. No API, schema, event or imperative-scroll behavior changes are required.

ADR 0008: capability-indexed Slot_style

Slot_style.t is now phantom-capability indexed. Builders are split by admitted property families, and constructors take the matching capability bucket:

Builder Capability Properties
Slot_style.make base overflow, hover/focus/shadow/cursor/opacity/viewport
Slot_style.typography [> \typography]` font_*, line_height, letter_spacing, text_decoration, user_select
Slot_style.text_flow [> \text_flow]` white_space, text_overflow
Slot_style.collision [> \collision]` collision_padding

Combine with Slot_style.merge. Constructor ?style parameters are exact:

  • text / button / menu_item / … → Slot_style.text_caps
  • checkbox / text_field / select / … → Slot_style.typography_caps
  • switch_ / radio_group / button_group / … → Slot_style.base
  • dropdown_menu / popover / menu / submenu → Slot_style.surface_caps

Passing a rejected property is now a compile-time type error (for example button ~style:(Slot_style.collision ~collision_padding:5. ()) []).

(* Before *)
let style = Slot_style.make ~font_size:"14px" ~collision_padding:8. () in
dropdown_menu ~style [dropdown_menu_item ~style []]

(* After *)
let surface =
  Slot_style.merge
    (Slot_style.make ~shadow:"0 4px 6px black" ())
    (Slot_style.merge
       (Slot_style.typography ~font_size:"14px" ())
       (Slot_style.collision ~collision_padding:8. ()))
in
let item =
  Slot_style.merge
    (Slot_style.make ())
    (Slot_style.merge
       (Slot_style.typography ~font_size:"14px" ())
       (Slot_style.text_flow ~white_space:`nowrap ()))
in
dropdown_menu ~style:surface [dropdown_menu_item ~style:item []]

text / heading / paragraph / label apply Slot_style before ~truncate recipes, so ~truncate:true cannot be overridden by ~style:(Slot_style.text_flow ~white_space:\normal ())`.

ADR 0008: polymorphic 'kind el and uniform dynamic combinators

Restricted slot types are now transparent aliases of a covariant phantom 'kind el. Base constructors return polymorphic upper bounds such as [< \general | `toolbar_item ] el. Uniform if_, keyed, scoped, and dyn/reactive` work inside restricted parents without per-slot adapters:

(* Before *)
toolbar ~label:"Actions"
  [ toolbar_button ~text:"A" []
  ; if_toolbar ~test:flag (toolbar_button ~text:"B" [])
  ; keyed_toolbar ~source:items ~key:Fun.id ~cmp:compare
      ~mount:(fun s -> toolbar_button ~text:(reactive s) []) ]

(* After *)
toolbar ~label:"Actions"
  [ button ~text:"A" []
  ; if_ ~test:flag (button ~text:"B" [])
  ; keyed ~source:items ~key:Fun.id ~cmp:compare
      ~mount:(fun s -> button ~text:(reactive s) []) ]

Legacy toolbar_* / dropdown_menu_* / if_* / keyed_* / reactive_* / scoped_* aliases remain available. menu_trigger still rejects if_ / keyed because its single child is mandatory. Use Lui_elements.custom and Lui_elements.mount for host-owned element functions — el is abstract.

ADR 0008: dropdown_menu target grouping

dropdown_menu no longer takes flat ?at / ?anchor / ?anchor_alignment / ?anchor_offset. Use ?target / ?target_signal with dropdown_target:

(* Before *)
dropdown_menu ~at:(48., 96.) entries
dropdown_menu ~anchor:`below ~anchor_alignment:`start entries

(* After *)
dropdown_menu ~target:(Menu_at (48., 96.)) entries
dropdown_menu
  ~target:(Menu_anchor { side = `below; align = `start; offset = 0. })
  entries

popover already used popover_target; both surfaces now emit only the wire properties of the active mode and remove only stale mode properties on transitions. Same-mode updates emit zero RemoveProp.

ADR 0008: Lui.Ui Tier-1 contract

Lui.Ui no longer includes Lui_ui. Raw int-returning builders live under Lui.Raw / Lui_ui. Ui.form_section and Ui.data_list accept list_section_item_el list; wrap general views with Ui.form_row / Ui.data_row (or pass list_item / if_ / keyed / reactive directly):

(* Before *)
Ui.form_section ~title:"Identity"
  [ Ui.form_field ~label:"Name" (text_field [])
  ; toggle ~text:"Enabled" [] ]

(* After *)
Ui.form_section ~title:"Identity"
  [ Ui.form_row (Ui.form_field ~label:"Name" (text_field []))
  ; Ui.form_row (toggle ~text:"Enabled" [])
  ; if_ ~test:flag (Ui.form_row (text_field [])) ]

(* Before *)
Ui.form_sheet ~title:"Edit" ~confirm_disabled:(Signal.value disabled) content

(* After — static bool and signal twins *)
Ui.form_sheet ~title:"Edit" ~confirm_disabled:true content
Ui.form_sheet ~title:"Edit" ~confirm_disabled_signal:(Signal.value disabled) content

Ui.hstack / Ui.vstack / Ui.page / Ui.section accept typed token parameters (?background:color, ?gap:space, ?padding:space, …) and resolve Tokens.space with Tokens.space_value_for (Lui_ui.platform context) (desktop/web denser than iOS/Android touch metrics).

ADR 0008: protocol numeric normalization and JSON enum decoding

Lui_protocol.normalize_property_value clamps CollisionPadding, FirstPaneWidth, AvailableHeight, GrowValue, and ShrinkValue to >= 0 (non-finite floats fall back to 0. with a diagnostic), and clamps TreeLevel to >= 1. Web retained-property tests that previously expected throws for invalid collision-padding must assert clamping to 0. instead.

Lui_json_view enum decoders return None with a structured diagnostic for unknown values; they no longer raise Invalid_argument.

ADR 0008: split sizing_signal default

Mounting split ~sizing_signal no longer emits a spurious default ProgressValue 0.5 before the signal's first value. Mode transitions remove only properties belonging to the previous sizing mode.

Native store: structural patch validation

Lui_store.apply_batch validates a batch against a structural shadow before mutating the live tree. Cyclic InsertChild/MoveChild, RemoveChild that names the wrong parent, and structural ops on missing nodes raise Invalid_argument with op index and a describe_op prefix (patch op N (...): ...). The store is unchanged so Lui_host.apply_batch can return false and the runtime can resync, matching Web and Android. Property ops on missing nodes are still ignored. InsertChild/MoveChild whose parent is not a node (including the gallery sentinel parent=-1) stay a no-op so the child remains a root, matching apply_op. apply_op stays lenient except that inserting a node under itself or an ancestor raises to keep iter_preorder acyclic.

(* Before: InsertChild (2, 1) after InsertChild (1, 2) closed a cycle and
   hung iter_preorder; RemoveChild (2, 3) while parent(3)=1 duplicated 3 in
   the root set. *)
Lui_store.apply_batch store { generation; ops = [ InsertChild (2, 1, 0) ] }

(* After: the batch raises and the tree is unchanged. Hosts treat the
   failure as a rejected batch:
     Lui_host.apply_batch host batch  (* false *)
*)

Native hosts tick the application clock

SDL/native window loops (macOS, Linux, Windows) call Lui_app.tick_clock ~now every iteration and fold Lui_clock.next_delay into the event-wait timeout via Lui_window.fold_wait_ms. Lui_ui.after and Lui_ui.every therefore fire on native windows, matching Apple, Android and Web.

Toast duration is applied by the native UI layer: Ui.store_changed schedules a Dismiss at now + duration and Ui.next_input_deadline wakes the host for it. Demo drivers no longer keep a private toast_since clock.

Native window loops also call Lui_host.tick ~now every iteration (seconds, matching the host animation clock). That starts resize-duration split transitions and advances retained popup motion; Lui_host.wants_repaint already requests frames while those animations run.

Native resource executor and Vulkan frame resize

Lui_resource.create now defaults to a bounded worker pool instead of one Domain.spawn per load. request/reload mark the entry Failed when the executor raises (for example past the domain cap) instead of leaving it stuck Loading. Hosts call drain_all every frame and may install set_completion_wake (SDL hosts use Lui_sdl3.run_on_main_thread) so completions wake an idle wait.

Lui_vulkan.resize recreates only the offscreen frame image and framebuffer. Window swapchain presentation remains a follow-up: Linux still reads the frame back and uploads damaged rows through Lui_blit.

Terminal pump retries short PTY writes; flush_pending is the testable helper. Incoming chunks enqueue in O(1). Terminal_pty.close is idempotent.