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 nativeLabel/Textwithout applying the item's typography or hover/focus overrides. - Android Material menu rows keep their native typography and state chrome.
LuiMenuItemderives text style from Material/style classes rather than the item's typography properties, and neither it norluiChromeconsumes 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" ()) []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.
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.
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.
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.
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.
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.
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.
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" []]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:17only 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.
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) []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 contentPage 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.
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.
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
| _ -> ());
nodeNon-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.
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 childrenicon_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.
Conflicting JSON inputs now normalize deterministically and log diagnostics on stderr through the same path as runtime boundary/duplicate-key diagnostics:
- A valid
anchorside wins overx/ypoint positioning. anchor-targetwins overanchor-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-widthwins over fractionalvalue.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 ()) [] ]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]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.
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 usemodule Sdl = Lui_sdl3.Lui_blit.createnow acceptsLui_sdl3.window; distinct window/renderer/cursor types reject mismatched resource calls during compilation. - Use
Window.high_pixel_densityinstead ofWindow.allow_highdpi. Windows are shown by default; removeWindow.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, andSdl.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 aretimestamp_ns : int64. Compute age usingget_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.makeandEvent.of_event. Push supported native events throughpush_key_event,push_quit_event, andpush_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 widthwith a byte pitch ofwidth * 4for 32-bit pixels. Renderer creation takes~software:trueor~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.
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.stabilityRestored 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.
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)) rootOnly look up and decode the requested icon inside the callback. Static
overrides can remain in ~app_icons; native renderers are unchanged.
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.
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.
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 textLui_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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.focusedNodeIDfocusedNodeID 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.
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.
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.
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 LUIComponentsAppKeep 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.
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.
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.
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)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,keyandext.helloreportsprotocol("lui-agent"),version(1),host,generationandops. - Selectors. They use the Drive scenario grammar:
id:N,kind:name,ext:identifier,text:needle,prop:name=valueandprop:name=prefix*, joined with&. A bare number is an id and a bare word is a text needle. - Gestures.
press,long-pressanddouble-pressgo 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_targetandLui_agent.target.Lui_native_bridge.agent bridge requestanswers through a started bridge, andregisteradds<prefix>_agent(for examplelui_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
1when answered, including{"ok":false}replies. They return0when refused; in that case readlui_ocaml_last_errorand resync as after any refused call. The batches go to the patch callback given tolui_ocaml_start, thenreplyreceives the reply object. -
Android.
LuiBridge.agent(request): Stringblocks 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.answerdefaults toLuiBridge.agent.- The Components app starts it only in debug builds launched with
--ei lui-agent-port PORT. The debug manifest addsINTERNET. Reach it withadb forward tcp:PORT tcp:PORT.
val server = LuiAgentServer.start(port = 49380) // after LuiBridge.start
-
Apple.
LUINativeAgent(library:recovery:)(orinit(agent:recovery:)with an@_silgen_nameclosure) answers requests and recovers refusals.LUIAgentServer.startFromEnvironment(answer:)serves loopback TCP on the main queue whenLUI_AGENT_LISTENis set.LUINativeRefusalRecovery.recover(_:)ischeck(_:)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:PORTtosimctl launch.
let agent = LUINativeAgent(library: handle, recovery: recovery) agentServer = try LUIAgentServer.startFromEnvironment { agent.answer($0) }
-
Web.
Lui_web_agent.install targetsetswindow.__luiAgent.- When the page URL carries
?lui-agent=ws://127.0.0.1:PORT(orws://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)
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.shscripts; 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'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.
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] *)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)anddouble lui_ocaml_clock_next_delay(void)(negative when nothing is due, paused or not started). After every call into the runtime the host readsnext_delay, arms one wakeup and callsclock_tickwith monotonic milliseconds when it fires. Bridges built withLui_native_bridge.registerget the OCaml side automatically. -
Android:
LuiBridgereschedules aHandler.postAtTimewakeup on thelui-ocamlthread after every dispatch, ticking withSystemClock.uptimeMillis(). New JNI exportsnativeClockTick,nativeClockAdvance,nativeClockSetPaused,nativeClockNextDelayand publicLuiBridge.advanceClock(ms)/LuiBridge.setClockPaused(paused). Custom JNI libraries must compile the updatedlui_jni_bridge.c. -
Apple: new
LUIRuntimeClockinLUIAppleBackend. Create it withLUIRuntimeClock(library: handle)fordlopenhosts orLUIRuntimeClock(tick:nextDelay:)with@_silgen_namefunctions, callreschedule()after starting the runtime and after every runtime call (typicallydefer { clock.reschedule() }at the top ofbackend.onEvent), andcancel()beforelui_ocaml_stop:let clock = LUIRuntimeClock(library: handle) backend.onEvent = { event in defer { clock.reschedule() } // existing dispatch }
-
Web/Melange: call
Lui_web.drive_clock apponce afterLui_app.start. It ticks fromperformance.now()with one armed timeout and flushes after each tick, using the newLui_clock.set_wakeuphook. -
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 ~noworLui_app.advance_clock app ms, thenLui_app.flush, or register aLui_clock.set_wakeupcallback.
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.
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:
LuiBridgelogs the failure, requests a snapshot through the existing resync path and notifies the optionalLuiBridge.failureListeneron the main thread with aLuiRuntimeFailure. A failedstartreports its diagnostic the same way. The JNI library exportsnativeLastError().LuiBridge.failureListener = LuiBridge.FailureListener { failure -> showError("${failure.phase} failed: ${failure.message}") }
-
Apple:
LUIAppleBackend.applySnapshot(json:)replaces the retained tree with alui_ocaml_resyncbatch.apply(json:)drops that batch as stale because it reuses the current generation.LUINativeRefusalRecoverywraps 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 useapplySnapshotas 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.clearempties 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.
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.
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.
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.
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.
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
LUIAppleBackendorLUIAppleBackendStaticproduct from the root package orplatform/applepackage. For example, Journal can continue usingJOURNAL_LUI_PACKAGE_PATH=../lui/platform/apple. - Android consumers retain the
platform/android/luiGradle module and its JNI bridge. The optionalplatform/android/driveinstrumentation module remains debug-only. - Schema generation emits
LUIWireSchema.swiftandLuiWireSchema.ktas 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-appleremain 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.
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.
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 thelui_pkgexecutable.
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.
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.
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.
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.
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.
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
)
#endifNo 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.
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:49377Native 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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
| _ -> ()) []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.
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 viewA 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.
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.
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.
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.
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.
The OCaml constructor keeps its existing optional arguments:
virtual_list ~overscan:0 ~item_extent:32. rowsPreviously 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 rowstext_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.
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" bridgeOrdinary 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.
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.
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.
- Update generated wire schemas and custom host decoders together with LUI.
- Replace uses of
brand invalid retained child shapes. - Prefer typed virtual-list arguments; test any legacy attribute overrides.
- Review disabled editors that should allow copying.
- 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 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-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 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.
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.
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.
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_capscheckbox/text_field/select/ … →Slot_style.typography_capsswitch_/radio_group/button_group/ … →Slot_style.basedropdown_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 ())`.
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.
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. })
entriespopover 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.
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) contentUi.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).
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.
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.
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 *)
*)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.
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.