Crate day_core

Expand description

day-core: the Piece model, realized tree, mounter, layout engine, and event routing (DESIGN.md §5, §7). Build-once: pieces are constructed exactly once; all dynamism flows through reactive bindings (day-reactive) writing to the thread-local tree.

Re-exports§

pub use element_id::ElementId;
pub use element_id::IntoElementKey;
pub use frame::FrameConsumer;
pub use frame::add_frame_consumer;
pub use frame::frame_consumer_count;
pub use frame::install_frame_requester;
pub use frame::remove_frame_consumer;
pub use image::Bitmap;
pub use image::CanvasExports;
pub use image::RenderBitmap;
pub use image::RenderPdf;
pub use image::canvas_exports;
pub use image::decode as decode_image;
pub use image::decode_async as decode_image_async;
pub use image::image_decode_support;
pub use image::image_encode_formats;
pub use image::image_encode_support;
pub use image::render_bitmap;
pub use image::render_bitmap_async;
pub use image::render_pdf;
pub use image::render_pdf_async;
pub use image::resolve_bitmap_render;
pub use image::resolve_image_decode;
pub use image::resolve_image_encode;
pub use image::resolve_pdf_render;
pub use lifecycle::dispatch_lifecycle;
pub use lifecycle::lifecycle_supported;
pub use lifecycle::on_lifecycle;
pub use list::BuiltRow;
pub use list::ListDeleteDriver;
pub use list::ListDriver;
pub use list::ListReorderDriver;
pub use list::ListSectionsDriver;
pub use list::ListSwipeDriver;
pub use list::install_list;
pub use list::list_reload;
pub use list::list_scroll_to_end;
pub use list::list_scroll_to_row;
pub use list::list_set_editing;
pub use list::list_set_selected;
pub use list::list_splice;
pub use list::list_try_delete;
pub use list::list_try_reorder;
pub use list::list_try_swipe;
pub use list::set_scripted_reorder;
pub use menu::dispatch_menu_action;
pub use menu::has_app_menu;
pub use menu::register_menu_action;
pub use menu::register_scoped_menu_action;
pub use menu::set_app_menu;
pub use menu::set_dock_menu;
pub use shortcuts::set_launcher_shortcuts;
pub use status::KeepRunning;
pub use status::remove_status_item;
pub use status::set_app_progress;
pub use status::set_dock_visible;
pub use status::set_keep_running;
pub use status::set_status_item;
pub use status::status_items;
pub use documents::on_open_files;
pub use documents::request_open_files;
pub use toolbar::Chrome;
pub use toolbar::chrome_changed;
pub use toolbar::current_chrome;
pub use toolbar::current_page_column;
pub use toolbar::current_page_gate;
pub use toolbar::current_page_window;
pub use toolbar::dispatch_toolbar_value;
pub use toolbar::patch_chrome;
pub use toolbar::patch_toolbar;
pub use toolbar::register_contribution;
pub use toolbar::register_contribution_gated;
pub use toolbar::register_toolbar_value;
pub use toolbar::relabel_contribution;
pub use toolbar::toggle_sidebar;
pub use toolbar::unregister_contribution;
pub use toolbar::update_contribution;
pub use toolbar::window_being_built;
pub use toolbar::with_page;
pub use toolbar::with_page_gated;
pub use toolbar::with_page_in;
pub use tree_driver::TreeBuiltRow;
pub use tree_driver::TreeDriver;
pub use tree_driver::TreeMovesDriver;
pub use tree_driver::install_tree;
pub use tree_driver::tree_driver;
pub use tree_driver::tree_reload;
pub use tree_driver::tree_reveal;
pub use tree_driver::tree_set_expanded;
pub use tree_driver::tree_set_selected;
pub use tree_driver::tree_try_move;
pub use tree_driver::tree_visible_rows;
pub use windows::WindowHandle;
pub use windows::about_action_id;
pub use windows::check_for_updates;
pub use windows::check_for_updates_action_id;
pub use windows::current_window;
pub use windows::finish_window_open;
pub use windows::focused_scope;
pub use windows::focused_window;
pub use windows::initial_window;
pub use windows::launch_options;
pub use windows::monitors;
pub use windows::open_about;
pub use windows::open_new_window;
pub use windows::open_new_window_for_group;
pub use windows::open_preferences;
pub use windows::open_window;
pub use windows::quit;
pub use windows::register_about;
pub use windows::register_about_window;
pub use windows::register_check_for_updates;
pub use windows::register_new_window;
pub use windows::register_new_window_for;
pub use windows::register_preferences;
pub use windows::register_preferences_with;
pub use windows::window_by_key;
pub use windows::window_title;
pub use linkme;

Modules§

conformance: Tests that run inside a built Day app (docs/testing.md): a Case is a page plus a drive, or a headless run, declared next to the code it tests with #[day::test] and collected in a registry. The dayscript engine runs them on a real toolkit under day test; the mock harness runs the same functions under cargo test. Nothing here knows how a step is executed: a DriveBackend does, and the engine supplies one.
documents: File activation is data delivery, never route navigation. See docs/documents.md.
element_id: Declared element identities. id! is the only declaration surface; the catalog is collected at link time, including declarations in helpers which have never mounted.
frame: Window-scoped display scheduling (docs/frames.md). Native frame requests are shared by one-shot clients, continuous subscriptions and the legacy frame_clock piece. No timers, no implicit physics clamp, and no native request when there is no demand.
image: Raster images (docs/images.md): decoding encoded bytes into a native image, reading what it is, encoding it back, and releasing it again. Rendering a canvas drawing into a bitmap or a PDF (docs/canvas.md “Exporting”) lives here too: a rendered bitmap is the same Bitmap a decode returns, held in the same toolkit table.
lifecycle: App-lifecycle callbacks (docs/lifecycle.md). An app registers closures for day_spec::Lifecycle phases with on_lifecycle; each backend, at the matching moment in its native app/activity delegate, emits Event::Lifecycle(phase) (or day-core dispatches the launch phases uniformly), and the event pump routes it here to run the closures inside a reactive batch, the same rails as Event::MenuAction, so a lifecycle handler that writes signals updates the UI like any callback.
list: Recycling-list driver (docs/list.md, §10). The native list host owns scrolling + cell reuse; Day owns row content. day-core injects a day_spec::ListSource into the backend; when the native data-source pulls a cell, bind_row builds it once (per physical cell) and thereafter rebinds it (one slot-write) as the cell recycles.
menu: Menu action dispatch (§ menus). The model (day_spec::MenuItem) is toolkit-neutral and carries only ids for its actions; the closures live here, keyed by id. A backend fires Event::MenuAction(id) when a native item is chosen; the event pump routes it to dispatch_menu_action, which runs the app’s closure. Ids are process-unique and monotonic.
shield: The system-gesture / interactive-dismiss / status-bar shield (docs/cover.md): the registries behind the defers_system_gestures, interactive_dismiss_disabled and status_bar_hidden modifiers. Each mounted modifier pushes an entry while its subtree is alive; the union of entries is the app’s current request.
shortcuts: The app’s launcher shortcuts at run time (docs/deep-links.md “Launcher shortcuts”).
status: The app’s presence outside its windows (docs/status-item.md): status items, progress on the Dock or taskbar icon, the macOS Dock icon itself, and whether the app keeps running when its last window closes.
testing: Opt-in presentation policy for functional walkthroughs: fast mode is reduced motion forced on (docs/accessibility.md), nothing more. This is not a virtual clock: timers, network requests, physics and media retain their real timing.
toolbar: Toolbar contributions (docs/toolbars.md). The model (day_spec::ToolbarItem) is toolkit-neutral and carries only ids for its commands; the closures live here, keyed by id, the same shape as crate::menu and the same id space, so one closure can back both a toolbar button and its menu-bar twin.
tree_driver: Recycling-tree driver (docs/tree.md). crate::list’s shape addressed by token instead of row index: the native tree host owns scrolling, disclosure and cell reuse; Day owns row content. day-core injects a day_spec::TreeSource into the backend; when the native data-source pulls a cell, bind_row builds it once (per physical cell) and thereafter rebinds it (one slot-write) as the cell recycles.
tween: Tweening for self-drawn content (docs/tween.md): the pieces a canvas animation needs that native widgets get from their toolkit.
windows: Secondary windows (docs/windows.md): the app-facing open_window API, the per-window registry, and the fallback that presents window content as a fullscreen cover where the toolkit cannot open windows (Cap::MultiWindow = Unsupported).

Macros§

id: Declare an ID at its piece, including a link-time catalog entry.
tls_group: Re-exported so every crate above day-core can reach it without taking a direct day-reactive dependency (see day-reactive for what it does and why Android needs it).

Structs§

AnyPiece: Type-erased piece for heterogeneous branches and dynamic construction.
AspectRatioLayout: The aspect_ratio decorator (§5.2): the largest width / height == ratio box that fits what the parent proposes, with the child given that whole box.
AssetDir: A bundled-asset directory (§18.5): a folder’s path relative to resource/assets/, /-separated, no trailing slash. The generated res::assets::… tree carries one constant per folder, sharing its module’s name: res::assets::web::minisite is the AssetDir and res::assets::web::minisite::index_html a file within it.
AssetName: The bundled-data name that resource resolves by: the file’s path relative to resource/assets/, /-separated (a top-level file is just its file name, extension included).
Blocking: The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. The future spawn_blocking returns: the job’s value once a pool thread has run it.
BuildCx
CellCenter: A recycled tree cell’s anchor layout (docs/tree.md): row content hugs its own height, so center it in the cell’s fixed row height; PassThrough pins it to the top, which reads as a misaligned row whenever the content is shorter than the row (a 16pt label in a 28pt row sat 6pt high). Width still fills; a content taller than the row clamps to it.
CellMetrics: A list cell’s anchor layout (docs/list.md “Row metrics”): the row sits inside the platform’s row margins and the cell is at least the platform’s row height, content centered in it. With zero metrics it is PassThrough.
ComposedSheet: A composed modal sheet (docs/cover.md “Modal sheet”): the cover’s content on a card in the window’s own background color, centered over a dimmed fill that spans the cover. The cover itself is clear and takes every click, so the page shows through but stays out of reach.
CoverLayout: Fullscreen cover (docs/cover.md): the cover node occupies no space where it sits in the tree (its native surface is presented over the window, outside the parent’s bounds), and its content is laid out at the size the backend reported via Event::FrameChanged, the same native-owned-frame contract as NavLayout pages.
EngineCx
FillThrough: Paint/clip wrapper (.background, .corner_radius, the animatable layers): like PassThrough for measurement, but the granted rect flows to the child verbatim at place time. These containers exist to paint or clip the area the parent granted, so a grow stretch above them must reach the painted surface (the grid-cell card case) instead of being re-hugged at every wrapper. Under a parent that places at measured size (every stack, grid rigid cell, and overlay) bounds equal the measure and nothing changes.
Flex: Read-only layout facts a parent may consult about a child (§7.2 ChildRef).
FlowLayout: A wrapping row (docs/size-classes.md “Adaptive pieces”): children keep their natural measure and lay out leading-to-trailing, breaking onto a new line where the next child would overflow the proposed width. Wrapping replaces main-axis negotiation, so flex is inert here: nothing grows, and a spacer() contributes nothing. RTL mirroring comes from place_child, the same as every layout.
FontFamily: The family name of a bundled custom font, feeding Font::custom. Holds a &'static str (so Font stays Copy); generated res::fonts::… constants supply it. The untyped Font::Custom(&'static str, f64) variant remains the escape hatch for a family known another way.
FrameLayout
GridFacts: Per-node grid facts (docs/grid.md), carried on Flex: the shipped form of the §7.2 ChildRef facts surface. Set at build time by grid_row and the .grid_span/.grid_align modifiers; only GridLayout reads them.
GridLayout: SwiftUI-style grid negotiation (docs/grid.md): columns are inferred from grid_row children, a column’s width is the max ideal width of its span-1 cells, a grow_w cell makes its column flexible (leftover width split evenly, the StackLayout share rule), and a non-row child is a full-width cell spanning every column. spacer() is an inert empty cell. The contract: exactly two measure proposals per cell per layout, unconstrained (pass A) and at the final column width (pass B), and place re-runs the same proposals, so it measures from cache.
GrowLayout: The grow/grow_w/grow_h decorators (§5.2): a single-child wrapper carrying grow Flex so the parent stack OFFERS it the space, and a greedy measure/place so the child actually FILLS it. Non-grown axes hug the child (like frame(maxWidth: .infinity) on one axis).
ImageName: The bundled-image name that resource() callers resolve by (the file stem).
InspectorLayout: Inspector split (docs/inspector.md): the two pane frames are native-owned (an NSSplitView’s panes, a dock widget), so Day lays each pane’s content within the size the toolkit last reported via Event::FrameChanged, the same native-owned-frame contract as NavLayout pages. The fallback before the first report splits the host bounds at the pane width when visible, and gives the content everything when hidden.
LeafLayout: Native leaf: measurement delegates to the toolkit.
MaxHeightLayout: The .max_height(h) decorator, MaxWidthLayout’s vertical twin: proposes at most h to the child, so a scroll or anything else that takes the height it is offered stops at h, while shorter content still hugs. Where the parent offers less than h (a phone held sideways), the child gets that, so a capped box still fits a short screen. The horizontal axis passes through untouched.
MaxWidthLayout: The .max_width(w) decorator (docs/layout.md): proposes at most w to the child, so text wraps instead of overflowing, while narrower content still hugs. The vertical axis passes through untouched.
MinWidthLayout: The .min_width(w) decorator: the child measures as it would, but never reports narrower than w, and is placed across whatever width the wrapper is given. A stretching control (a slider) in a row that is being squeezed thereby overflows its row instead of shrinking to nothing, which is what lets a labeled row notice and stack (docs/forms.md). The vertical axis passes through untouched.
NavController: A mounted host’s control surface. Closures run user code (route builders), so the registry Never holds a borrow across a call (§3.3 discipline: clone the Rc out, then call).
NavLayout: Navigation host (docs/navigation.md): page frames are native-owned (splitter panes, nav-controller views), so set_frame on pages is a toolkit no-op; Day lays each page’s content within the size the toolkit last reported via Event::FrameChanged, falling back to a sidebar/detail split (or the full host) of the host bounds.
NavToken: Opaque handle from register_nav; a nested host calls unregister_nav on dispose.
NodeData
NodeProbe: Cached last-applied props for the dayscript element index (§14.2).
OverlayLayout: Z-layering (§overlay): children share the container bounds, stacked back-to-front in child order (first child = bottom of the z-order), each positioned by a single Alignment. size_to_first reports only the first child’s natural size, the badge/annotation sizing of overlay (the annotation does not grow the frame); otherwise the layout reports the union (max) of all children’s natural sizes, the ZStack sizing of zstack. No native work: the container is the same panel as column/row, so backends stack children by attach order.
PaddingLayout
PassThrough: Single-child pass-through (root, wrappers, group fallback): top-leading.
PieceFn: A closure kept as a concrete piece: the deferral primitive (§5.2).
PresentFuture
RNode: Realized-node key. NodeId (the spec-boundary id) is its FFI encoding.
ReserveLayout: Reserve at least the size of a sample child, then lay the content out inside it.
Resource: A handle to a bundled resource’s bytes with efficient random read-only access.
ScrollLayout: Scroll viewport (§7.6): greedy on the proposal; content measured unconstrained on the scroll axis and reported via set_scroll_content. Children are placed in the scroll’s content coordinate space (the scroll node is their native ancestor).
Sleep: Future returned by sleep.
SplitLayout: Native split (docs/split.md): the two pane frames are native-owned (an NSSplitView’s, a GtkPaned’s, a QSplitter’s), so Day lays each pane’s content within the size the toolkit last reported via Event::FrameChanged, the InspectorLayout contract. The fallback before the first report divides the host bounds by the bound fraction along the axis.
StackLayout: Column/row negotiation (§7.2): rigid children first, remaining main-axis space divided among flexible children; spacer() is maximally flexible; group anchors expand inline.
TaskHandle: A handle to a spawned task. Copy and !Send (the executor is thread-local).
TextMetricsCacheStats: What measure_text’s cache has done on this thread: a diagnostic, for an app that wants to see whether its drawing is measuring the same strings over and over (it usually is).
Tree
VectorName: The bundled-vector name that resource() callers resolve by (docs/vectors.md): the stem of a resource/vectors/ SVG (or .symbolset bundle). Vectors and images share one per-backend resolution namespace; staging guarantees every vector name resolves as whatever form that backend loads natively (a VectorDrawable, a catalog entry, a rasterized PNG).

Enums§

Alignment: Two-axis placement of a child within a container’s bounds (SwiftUI’s Alignment). Used by the z-layering primitives (OverlayLayout): zstack, overlay/overlay_aligned.
Axis
BlockingError: The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. Why a Blocking future resolved without its job’s value.
Boundary: Measure-invalidation boundary (§7.4): Yes stops upward needs-measure propagation (scroll viewports, nav pages). Named enum instead of a bare bool at call sites (docs/api-style.md).
CrossAlign
Either: A build-time branch between two piece TYPES, without erasing either (§5.1).
PresentationMode: Whether Day presents native controls or holds requests for an explicit script response. Scripted mode does not synthesize answers or affect OS permissions/external applications.
ScrollTarget: A programmatic scroll destination (§7.6, docs/scroll.md). Edges are axis extremes (Top/Bottom vertical, Leading/Trailing horizontal, i.e. start/end in layout direction); Offset pins the viewport origin to a content-space point (clamped by the platform); Id reveals the element with that dayscript id inside its nearest enclosing scroll.
WindowRootReply: TreeOps::open_window_root’s answer: the tree-level face of day_spec::WindowOpenReply, carrying the adopted (or parked) root node.

Constants§

NAV_LIST_WIDTH: Default preferred width of a navigation host’s content-list pane (props::NavProps::list_width, docs/navigation.md), Mail’s message-list proportion.
NAV_SIDEBAR_WIDTH
SYNTHESIZED_TEXT: The tag of the Event::Custom synthesize_text sends to a piece of a kind day-core does not paint itself, carrying the text, just before the TextChanged that follows it. A piece whose native view owns the characters shows the text on this event and then sees the TextChanged as the echo it already handles.
VERSION: The linked Day runtime version, for diagnostics from independently versioned extensions.

Traits§

Ambient: State an ancestor provides once and any descendant reads back by type: SwiftUI’s @EnvironmentObject, and Day’s answer to “where does app state live?” (docs/state.md).
Layout: Open layout protocol (§7.2). children are the node’s direct children; group nodes (when/each anchors) are layout-transparent: stacks expand them inline.
LayoutOps: The engine surface visible to Layout implementations.
NavStore: A key/value sink a nav surface’s .restore persists its state through, so navigation survives a relaunch or an Android process death (docs/navigation.md). day::launch installs the preferences store (day_part_preferences::install_nav_store) unless the app installed one first; an app marks the surfaces it wants remembered with .restore(key). With no store installed, .restore is a silent no-op, so a surface’s .restore call never fails to build.
Piece: A UI description consumed once (§5.2). Returns the root realized node it created.
PieceSeq: Children of a container (§5.1): a tuple of pieces (the floem ViewTuple pattern), a Vec or array of one piece type, or an Option of a piece. Implemented for exactly those shapes, never via a blanket, to stay coherent. All of them are build-time children: evaluated once when the parent builds, with no keyed identity or reconciliation. A child that must come and go at runtime is a when, a keyed, or an each.
TreeOps

Functions§

announce: Speak text through the screen reader without moving its focus (docs/accessibility.md): the outcome of an action the user cannot otherwise learn about (“Saved”, “3 results”). The sentence waits for whatever is being read to finish; announce_urgent interrupts it. Nothing happens when no screen reader is running, and nothing happens on a toolkit that answers Cap::Announce with Unsupported.
announce_urgent: announce, interrupting what the screen reader is saying: an error, or a change that cannot wait.
app_environment: The app-wide T: created on the reactive root scope the first time it is asked for, and returned unchanged by every later call (docs/state.md).
app_temp_dir: An app-writable scratch directory (docs/files.md), re-exported from day_spec::present so day_core::app_temp_dir() keeps working for the pieces layer’s file-save staging. An app-writable scratch directory: the backend-supplied one, else std::env::temp_dir(). Used by the file-save flow (docs/files.md) to stage bytes before the native save picker.
application_handlers: Query current system associations on the UI thread. macOS AppKit implements all query kinds; other backends return Unsupported. No application is launched by discovery.
backend_name: The compile-time target key of the running backend ("macos-appkit", "ios-uikit", …, the Platform::TARGET string), recorded by launch_with. None before launch.
blocking_inline: The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. Whether spawn_blocking runs jobs inline: always on the web, else per set_blocking_inline.
blocking_limit: The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. How many threads the blocking pool may hold at once: the machine’s parallelism, at least four (a job waiting behind three slow ones still gets a thread), at most thirty-two. Zero on the web, where jobs run inline.
blocking_threads: The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. How many pool threads exist right now, idle ones included: for diagnostics and tests.
capability: Query the active toolkit’s support for a capability (docs). Lets app/piece code adapt its content to the backend, e.g. a page can skip a title the native nav already shows in a header (Cap::NavHeader), or pick a presentation from Cap::NavSplit.
clear_controllers: Drop every controller: a fresh mount / test boot (called from tree install/uninstall).
clear_text_metrics_cache: Drop every cached measurement (the counters keep running).
current_anim: The ambient animation set by the innermost enclosing with_animation, if any.
current_route: The full current route: every mounted surface’s contribution, outermost to innermost, /-joined (docs/navigation.md). None = no surface mounted; Some("") = everything at its root. Round-trips through navigate, so persisting navigation state is save(current_route()) on the way out and navigate(&saved) on the way back in.
dark_mode: Whether the platform is rendering in dark appearance (see Toolkit::dark_mode): the branch apps take when painting custom opaque surfaces so fills track the theme that the default text colors already follow.
debug_title_tag: The development tag every window title carries in a debug build: (<version>/<toolkit>[/<script>]), for example (1.1.0/appkit), or (1.1.0/gtk/walkthrough.yaml) while a dayscript is driving. With several apps, toolkits and scripted runs open at once, the title bar is the only place that says which window is which.
default_browser: The OS-chosen browser for HTTPS links, read afresh rather than cached by Day.
direction_of_locale: The writing direction a locale implies (language subtag match).
edit_action_id: The standing dispatch id behind a MenuRole::Cut/Copy/Paste item on a toolkit whose role items come back as plain menu actions (docs/menus.md): the closure invokes the installed edit bridge. Durable across menu installs, like the undo pair.
encode_route: Assemble a route string from segments and params, the inverse of parse_route. Reserved characters (/, ?, &, =, %) in segments and params are percent-encoded.
enqueue_event: The enqueue-only event sink installed into every backend (§8.3). May be invoked re-entrantly from inside any Toolkit method; dispatch happens at the next safe point.
enqueue_events: Enqueue several events into one drain before dispatching. Backends that observe a focus move at a single point (Qt’s focusChanged(old, new), an AppKit first-responder change) deliver the loss+gain pair through this so the pump can dispatch the gain first and a shared group signal never passes through None (docs/focus.md).
environment: Read the nearest ambient T provided by an enclosing with_environment, or None if none is in scope. Call it while constructing or building a piece within that subtree.
focus_search: Activate the focused window’s searchable navigation surface (for a Find command).
focused_environment: The ambient T of the window that currently has focus (docs/state.md): SwiftUI’s @FocusedValue.
focused_node: The node that currently has the keyboard, as the platform last reported it. Keys follow focus (docs/menus.md), so this is where a synthetic key has to land for a scripted run to exercise the same route a real one does. None when nothing focusable holds it.
font_families: The platform’s font families with their faces (docs/fonts.md), enumerated once per process through Toolkit::font_families and cached: the answer is stable for the process (bundled fonts register before the tree exists, and nothing tracks a system font install under a running app; the OS font panels cache too), enumeration is expensive, and the query is synchronous on the UI thread. Sorted case-insensitively by family, deduplicated, and unioned with the bundled fonts (day_spec::fonts::bundled_fonts) the toolkit’s own database did not report, which is how a res/font/ (Android), ms-appx (XAML) or registerFont (HarmonyOS) family reaches a font menu without each shim parsing sfnt. Empty where the toolkit answers Cap::FontList = Unsupported.
has_launch_deeplink: Whether a launch deep link is pending (DAY_DEEPLINK or a platform hint). A nav surface’s .restore reads this so a deep link wins over restored state (docs/navigation.md).
has_nav_store: Whether a NavStore is installed. day::launch installs the preferences store when the app has not installed one of its own.
has_tree
id_of: Resolve a dispatched NodeId back to the app-authored .id() string that named its node (find_by_id’s inverse, §5.5), or None for an id-less node or one no longer in the tree. The recorder (day::record, §14.6) calls this from inside its event observer to label a tap/input with the id an app would target in a dayscript step. Borrow-safe: returns None rather than panicking if the tree is momentarily borrowed by a re-entrant backend call.
id_to_rnode
init_logging: Install Day’s default logger and level, unless the app already installed its own.
init_presentation_mode: Initialize browser hosts, which have no process environment, before constructing the UI. Further windows must not reset a policy selected by a running script.
inline_search_host: The inline search host the reserved day::search id names when no bar item carries it: the most recently shown one in the focused window.
install_edit_bridge: Wire the app’s standard-edit handlers to the platform (docs/menus.md): state is a tracked read whose value mirrors into the toolkit (Cap::EditBridge: native menu validation enables the stock Cut/Copy/Paste exactly as it does for text widgets), and every invocation a platform route delivers comes back through on_invoke. On a toolkit with no native route, the menu_role(Cut/Copy/Paste) items dispatch here instead (the same standing-id fallback the undo pair uses). Call once, after launch; installing again replaces the wiring. Most apps want day::install_edit_commands, which adds the clipboard transport.
install_undo_bridge: Wire an undo history to the platform (docs/model.md): the four signals mirror into the toolkit’s native front where one exists (Cap::UndoBridge: the stock Edit menu retitles and enables itself, the platform’s gestures land), and every invocation the platform delivers comes back through on_invoke(redo). On a toolkit without a native undo system the state goes nowhere and the app’s own affordances call the stack directly; installing the bridge is still harmless. Call once, after launch; installing again replaces the wiring.
invalidate_size: Tell layout that a node’s intrinsic size may have changed. For tweaks (docs/tweaks.md): after a native call that alters a widget’s preferred size (fonts, tick marks, bezel styles), the measure cache along the node’s path must be invalidated, since Day can’t see native mutations it didn’t make. Relayout runs at the next turn boundary as usual. No-op on a disposed node.
invoke_edit: Invoke the installed edit bridge (the same handler the platform’s Cut/Copy/Paste route reaches, clipboard transport included), returning whether one is installed. An app’s own affordances (a context menu’s Cut/Copy) call this rather than duplicating the clipboard plumbing (docs/menus.md).
invoke_undo: Invoke the installed undo bridge (the same handler a native front reaches: ⌘Z, the Edit menu, a three-finger swipe), returning whether one is installed. The dayscript undo:/redo: steps drive history through this, so a walkthrough needs no app-provided undo button on any target.
is_mounted: Whether a tree is installed on this thread, i.e. whether the app has already launched.
is_rtl: Whether the app is being rendered right-to-left (docs/localization), a convenience over layout_direction. The layout engine already mirrors widget placement under an RTL locale, but a canvas draws in its own coordinate space, so a custom drawing that has a reading direction (a battery that drains one way, an arrow, a progress sweep) can call this to mirror itself. Fixed for the life of the process, like layout_direction.
label_of: A human-readable label for a node, for annotating a recorded script (§14.6): the accessibility label if one is set (.a11y(label = …), the localized string the screen reader speaks), otherwise the control’s own visible text. None when the node carries neither.
launch_with: Launch a Day app on the given platform backend: sets up the reactive scheduler and the cross-thread poster, mounts the root piece into the window’s content container, runs the initial layout, and installs the turn-end layout callback (§3.3). The backend then owns the native main loop.
layout_direction: The app-wide layout direction (docs/localization): mirrors every horizontal placement in the place pass when day_geometry::LayoutDirection::Rtl. Resolved lazily from the DAY_LOCALE launch environment (so toolkits can read it before any UI exists); set_layout_direction (called by install_locales for the resolved locale) overrides. Fixed for the life of the process; switching locale at runtime does not re-mirror.
measure_text: Measure one line of canvas text at size points in font (docs/fonts.md), in the engine that draws DrawOp::Text; a toolkit that cannot measure answers TextMetrics::approximate, so a caller always gets a usable box.
modifiers: The keyboard modifiers held right now, for interactions whose meaning they change (shift-click adds to a selection). Touch backends answer all-false; a dayscript step’s declared modifiers take precedence while it dispatches.
nav_back: Pop one level, day-initiated (the toolkit presents the pop). Native-initiated pops arrive as Event::NavBack and go through the owning host’s pop directly.
nav_store_load: Read a .restore key through the installed NavStore (None if none is installed or the key was never saved).
nav_store_save: Write a .restore key through the installed NavStore (a no-op if none is installed).
navigate: Navigate to a route (docs/navigation.md).
note_appearance_changed: Re-read the toolkit’s appearance into the reactive dark_mode signal. Backends call this when the system appearance changes under a running app (macOS theme switch, GTK style-manager change), and set_appearance calls it after applying an override, so closures reading dark_mode() recolor live instead of going stale until a rebuild.
note_motion_changed: Re-read the toolkit’s reduce-motion setting into reduce_motion. Backends call this when the user flips the setting under a running app; launch_with calls it once the tree stands, which is the launch read. Like note_appearance_changed, it may fire before the tree is installed and then does nothing.
note_navigation: Announce a navigation to route from its source: a nav host (the sidebar nav host) calls this the instant it changes the bound selection, so the observer sees it synchronously instead of waiting for the route to settle into NAV_STACK a frame later (which maybe_notify_route_change reads). Deduped like the pump-boundary path. route is the host’s local key, which replays as a relative navigate (innermost-first), correct for both a top-level sidebar and a nested one.
note_text_size_changed: The system text size changed under a running app (iOS Dynamic Type, a desktop’s text scaling): every text measurement Day holds is stale. Backends call this from the platform’s notification, once the native text has taken the new size. Day re-measures every node and re-lays every bound list row, so a content-sized row (docs/list.md “Row heights”) takes its new height through ListPatch::RowSizeInvalidated. Skipped when the tree is busy or not installed yet: a tree built after the change measures at the new size anyway.
on_open_url: Register on the UI thread. Return true to consume a URL; false retains normal deep-link routing. Delivery never performs a privileged action.
open_url: Open url in the platform’s default handler (system browser for http(s), mail client for mailto:, …). The function behind the link piece; call it directly from a tap handler for a custom affordance. Fire and forget: no result, unopenable URLs are ignored by the backend.
open_url_with_application: Open a URL or file URL in a chosen application. Await on the UI executor. Success means the OS accepted the open request; tab/window presentation belongs to the receiving app.
override_size_class: Force a class the window is not at: dayscript’s size_class: step and tests.
parse_route: Split a route string into its path segments and query params. Segments and param names/values are percent-decoded (%2F → /, …); everything else is taken literally.
pending_presentation: The most recently opened still-pending presentation, for dayscript inspection/response.
piece_fn: A piece from a closure, built when the tree reaches it.
piece_operation: Dispatch to the live node’s kind. Returns false without calling done if the node or operation is absent. A true result means the handler accepted responsibility for completion. The registry and tree are not borrowed while the handler runs, so it may update the tree or register another operation.
prepare_remount: Tear the current mount down so the app can be built again in the same process (docs/settings.md “Appearance on Android”).
present: Present a modal request under the current policy and await its answer (docs/dialogs.md). The pieces layer wraps this in Alert/confirm/prompt; call it directly for a custom PresentSpec.
presentation_mode: The current UI-thread presentation policy. Ordinary app launches default to native.
pump_events: Dispatch queued native events from the backend queue, containing any panic. Native event callbacks reach Day through extern "C" signal trampolines (GTK’s value_changed_trampoline, Qt’s event filters, …) that abort the process on unwind (panic_cannot_unwind). A panic in a Day event handler or its reactive drain (e.g. the reactive-cycle assertion firing during a slider drag) would therefore SIGABRT the whole app instead of surfacing. Catch it at this single backend-agnostic boundary, log it (the message carries the offending effect’s source location), and reset the runtime so the app keeps running (degraded) rather than crashing.
pump_generation: The current pump generation (see PUMP_GEN). Read by the recorder’s nav coalescing.
rc_layout: Helper for constructing shared layout Rcs.
reduce_motion: Whether motion should be reduced (docs/accessibility.md): the user’s system setting (Toolkit::reduce_motion), or a launch that forced it (DAY_REDUCE_MOTION=1, and day launch --fast, whose fast mode is this setting forced on). Day already applies every finite animation at its destination under it and keeps only indeterminate motion; this read is for the motion an app drives itself, such as a day::frame simulation or a decorative loop, which the app opts down. Reactive: a closure reading it re-runs when the setting flips.
reduce_motion_now: reduce_motion untracked and borrow-free, for the animation gates inside the tree.
register_nav: Install a controller (innermost = last). Returns its token. The root nav() registers once and never unregisters; nested hosts (tabs() in a route) unregister when their scope disposes.
register_piece_operation: Register a named operation for one piece kind. Use a namespaced name and document its input and output. Registering the same kind and name replaces only that handler.
register_search_host: Record host as showing an inline search field. Registered by the host’s builder for the life of its scope; see inline_search_host.
request_open_url: Platform intake. Keeps the original URL, including its scheme, query and escaping.
request_route: Ask the app to navigate, from anywhere, at any time.
reset_ambient: Reset every window’s ambient state (tests; pairs with uninstall_tree).
resolve_presentation: Deliver a native answer (the modal already dismissed itself). Called from pump_events on Event::PresentResult.
resource: Open a bundled resource by name for efficient random read-only access.
respond_presentation: Answer a pending modal programmatically (dayscript). Resolves with the given result first (removing the pending request), then dismisses the control only if it was presented natively. Scripted requests never enter the toolkit. The native dismissal’s own completion event finds nothing pending and is a no-op. False = no such pending request.
restore_reported_size_class: Undo an override_size_class: back to the class the window itself last reported.
rnode_to_id
route_param: The value of one query param of the most recent navigate (None = not present).
route_params: The query params carried by the most recent navigate call (?name=value&…). Read them inside a destination builder: route_param("id"). They describe the navigation in flight; a push you perform by writing a path signal directly carries its data in your own state instead (docs/navigation.md).
safe_area: The window’s safe-area insets, in points. Zero on every backend that clamps Day’s root to the safe area natively (the default everywhere); nonzero only where a backend runs the root edge-to-edge, today day-toolkit-material’s opt-in immersive mode (docs/layout.md, the android platform page). Compose it yourself where a background should run under the system bars: paint the background unpadded, pad the content by these insets. The read is tracked, but layout attributes like .padding capture the value at build time, so a mid-run inset change (rotation) does not re-pad already-built pages.
scroll_to: Imperatively scroll a scroll piece (docs/scroll.md): node is the scroll node for edge and offset targets (ScrollTarget::Id ignores it and reveals the named element in its own nearest scroll). Animated on-screen; dayscript uses the unanimated variant for determinism. Call with no tree borrow held.
seed_safe_area: Backend-facing: the first window’s safe-area insets, known before its content builds and before the tree that owns them exists (an overlay title bar’s height, docs/window-chrome.md). The first window’s content reads them at build time; later changes go through set_safe_area.
set_app_badge: Put a badge on the app’s icon: the Dock, launcher, home screen, or taskbar (docs/badge.md).
set_appearance: Override the app’s appearance: Some(true) dark, Some(false) light, None follow the system again. On backends reporting Cap::Appearance the native widgets restyle in place and dark_mode answers the override; app-painted surfaces pick it up on their next rebuild. Other backends ignore the call; probe before offering a theme picker.
set_contained_panic_observer: Register the contained-panic observer. First registration wins; later calls are no-ops (there is one crash reporter per process).
set_event_observer: Install (or clear, with None) an observer that sees every event day-core dispatches, in queue order, at the one point every backend funnels native events through (enqueue_events, §8.3), before the event reaches the app, so it observes exactly what the app receives. This is the recording/telemetry hook behind day::record (§14.6): a higher layer captures user actions into a replayable dayscript without touching any of the backends. Main-thread only; a None observer adds no cost to the event path. The boxed closure is adopted into an Rc internally so enqueue_events can call it with no borrow held.
set_launch_deeplink: Record the host’s launch deep link before launch_with runs (docs/navigation.md). Platform glue only; apps navigate with navigate. DAY_DEEPLINK, where a process environment exists, takes precedence.
set_layout_direction: Override the layout direction (normally from install_locales). Must be called before the first layout pass to take effect everywhere.
set_log_level: Set the maximum level that will be emitted. Separate from init_logging because the web launch path has to supply the level from the page URL rather than the environment, and because an app may want to raise or lower it at runtime.
set_log_sink: Install the line sink. First registration wins (one host per process). Called before launch; day::web::start does it for the browser.
set_modifier_override: Scoped modifier stand-in for the dayscript executor: Some while a step with declared modifiers dispatches, back to None after.
set_nav_observer: Install (or clear, with None) the navigation observer. Resets the dedup baseline so the next change fires regardless of where recording started.
set_nav_store: Install the app’s navigation persistence store (docs/navigation.md). Call once at startup, before the UI mounts, so a .restore surface reads it on first build. A later call replaces the store.
set_presentation_mode: Change policy for subsequent presentations. Answer existing requests first: switching cannot make an already-open system picker disappear.
set_resource_opener: Register the active backend’s resource opener (Android AAssetManager, GTK GResource, Qt QResource, ArkUI rawfile, …). Called once during backend init. A second call is ignored, so a backend that shares the default file opener need not call this at all.
set_safe_area: set_window_safe_area against the primary window, which is what a single-window backend reports.
set_size_class: set_window_size_class against the primary window, which is what a single-window backend reports.
set_window_safe_area: Backend-facing: report a window’s safe-area insets (points). Call from the native inset pass whenever the value changes; apps observe it through safe_area.
set_window_size_class: Backend-facing: report a window’s size class. Call whenever the window’s size changes; the signal only notifies when the bucket changes, so a resize within one class is free.
share_support: Whether the current toolkit can present a native sharing chooser.
share_url: Present a native chooser for a URL. Call directly from user activation (required on web). Returns false if unavailable or presentation failed; cancellation is not an error and no completion is implied. The caller owns any explicitly labeled fallback.
size_class: The current window’s size class, or None on a backend that does not report one yet. Tracked: a piece that lays out from this rebuilds when the window crosses a breakpoint.
sleep: Resolve after (at least) ms milliseconds, on the UI thread: the portable delay for day::task flows (docs/async.md). Rides Platform::post_delayed, so it works on single-threaded hosts (web) where std::thread::sleep + Setter cannot.
spawn_blocking: The blocking pool (docs/async.md): spawn_blocking runs a job on a worker thread and resolves on the awaiting side; std-only, so it lives in day-async and is re-exported here. Run job on a pool thread and resolve to its value on the awaiting side.
synthesize_text: Deliver synthetic typing to a text control (the dayscript input step and the autodrive string commands both route here): paint the widget via the ordinary app-write patch, then enqueue the TextChanged event. Both halves are needed: when a real user types, the text is already in the native field by the time its change event fires, so the two-way binding’s echo guard suppresses the write-back (§4.4); a synthesized event alone would drive the app’s signal while the widget kept showing its old text.
task: Spawn an async flow onto Day’s main-loop executor. This is the opt-in entry point for actions that open modals or pickers: button.action(|| day::task(async move { … .await … })). The future is polled once before this returns; the returned handle can TaskHandle::abort it and is freely discardable. At app termination pending tasks are dropped while reactive state is still available. Tasks submitted after shutdown begins are dropped without being polled.
text_metrics_cache_stats: Read the measure_text cache’s counters (docs/fonts.md).
toolkit_key: The toolkit key of the running backend ("appkit", "gtk", …, the Platform::TOOLKIT string), recorded by launch_with. None before launch.
try_with_tree: Like with_tree, but returns None instead of panicking when the tree can’t be entered: already borrowed, or not installed yet. A snapshot (TreeOps::snapshot) holds the borrow while the backend draws the window synchronously, and that draw can re-enter Day through a native callback, e.g. a lazy list’s viewForRow/connect_bind/cellForRow firing during cacheDisplayInRect. And platform style callbacks can fire before install_tree, e.g. GTK’s StyleManager emits a dark notify while startup applies a forced DAY_THEME scheme, before activate mounts the tree; a panic there unwinds into a C signal trampoline and aborts the process. Such callbacks use this and skip their work; the next real layout (or the signal’s first post-mount read) catches up.
undo_action_id: The standing dispatch id behind a MenuRole::Undo/Redo item on a toolkit with no native undo responder (docs/menus.md): activating the item comes back as a plain menu action, and this id’s closure invokes the installed undo bridge. Registered once and durable across menu installs, like the preferences id. Toolkits with a native undo system (appkit) keep their responder-chain selector instead, so a focused text field’s own undo stays ahead of the app stack there.
uninstall_tree: Reset the thread-local tree + queues (tests).
unregister_nav: Remove a controller whose host was disposed. No-op if already gone.
unregister_search_host: Forget host, once its scope is disposed.
window_safe_area: safe_area against an explicit window root.
window_size_class: size_class against an explicit window root.
window_size_class_untracked: size_class without subscribing, for code that reacts to the change itself.
with_animation: Explicitly animate every state change made in f, Day’s equivalent of SwiftUI’s withAnimation. The mutation runs inside a day_reactive::batch; that batch’s synchronous fixpoint drain (bindings → patch, plus the turn-end layout → set_frame) executes while spec is ambient, so the resulting native updates carry the animation intent and the toolkit animates them on its own compositor. Nesting overrides; the previous ambient restores after.
with_environment: Provide an ambient value T to content and its entire descendant subtree (the SwiftUI @Environment/.environment(_) analog, layered over day-reactive’s scope context). content, and any piece built within it, reads it back with environment. A thin, non-reactive wrapper: T is a snapshot captured here; for a value that must react, provide a Signal<T> (or a Memo<T>) and read it reactively inside the subtree.
with_tree: Access the installed tree. Tree methods never run user code, so nesting cannot occur while a borrow is held; if events were queued during the call, they are pumped after the borrow is released (the “safe point” of §3.3).

Type Aliases§

EventHandler: An event handler registered on a realized node.
EventObserver: The recording/telemetry observer installed via set_event_observer (§14.6): called with every dispatched (NodeId, Event), in queue order, before the app receives it.
NavObserver: A navigation observer (§14.6): called with the new full route each time it changes, from any source: imperative navigate/nav_back, a nav_link or sidebar row (which navigate from an event handler, bypassing the event observer), a stack push, or a native back gesture. "" is the root. Installed by the recorder in day-script; day-core only fires it.
PieceOperationDone: Completes an operation with its textual result or a human-readable error. The operation defines the payload format. Completion may be immediate or asynchronous.
PieceOperationFn: An operation on a live node of the registered kind. Copy the input if retaining it. Accepted requests must complete, including when the native operation fails.
ResourceOpener: A backend’s resource opener: maps a declared name (e.g. "stations.json") to its bytes, or None if there is no such resource.

Crate day_core

Crate day_core Copy item path

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate day_core