Crate day 

Day — the umbrella crate apps depend on. One backend feature per binary (§3.2).

Modules

lifecycle

App-lifecycle support for the backend compiled into THIS binary (docs/lifecycle.md).

prefs

Persistent settings (docs/prefs.md): a small key/value string store backed by each platform’s native facility — NSUserDefaults on Apple, SharedPreferences on Android, a file store elsewhere. day::prefs::{get, set, remove, contains}, plus bind to persist a Signal and install_nav_store to make .restore(key) navigation survive a relaunch (docs/navigation.md).

prelude

reactive

The reactive core, whole (docs/async.md): day::reactive::{Resource, Load} for async data loading — namespaced because the prelude’s Resource is the ASSET handle above, a different type that predates the async one.

record

dayscript recording (docs/dayscript.md “Recording”, DESIGN §14.6): install a recorder that captures the user’s taps, edits, selections, and navigation into a replayable dayscript. day::record::{start, start_into, start_to_file, stop, is_recording, recording_signal, script, steps, save, clear, exclude_prefix}. A recorder also arms headlessly from day launch --record <file> (the DAY_RECORD env, honored inside day_script::init). What it records is an ordinary dayscript, so it replays cross-toolkit through play_script or day launch -p <target> --script <file>.

Macros

android_main

Expands to the three JNI exports dev.daybrite.day.bridge.DayBridge’s natives resolve against in the app cdylib (nativeStart/nativeOnEvent/nativeRunPosted), wired to the given root piece.

arkui_main

Expands to the day_arkui_start C export the HarmonyOS ArkUI shim’s start(...) NAPI wrapper calls (from ArkTS: import native from 'libday_arkui.so'; native.start(nodeContent, w, h, density)). It mounts the app’s root piece into the ArkTS NodeContent and runs the loop.

ios_main

Expands to the day_main C export the iOS Runner’s main.swift calls (@_silgen_name("day_main")). The optional title is currently unused on iOS (the window fills the screen bounds); accepted for future window-scene use.

require_lifecycle

Compile-time assert that the backend in this binary delivers $phase, else a build error. Use it to make a hard dependency on a platform-specific phase explicit: day::require_lifecycle!(day::Lifecycle::DidEnterBackground); fails to compile on desktop. For soft handling, guard with lifecycle::supported / lifecycle_supported instead.

routes

Define a plain routes enum and its Route impl in one shot:

web_main

Expands to the day_dom_main C export the web host’s shim.js calls once the wasm module is instantiated (wasm.day_dom_main() at the end of start() in crates/day-cli/resources/web/shim.js).

Structs

AnyPiece

Type-erased piece for heterogeneous branches and dynamic construction.

AssetName

The bundled-data name that resource resolves by (the full file name, extension included).

BuildCx

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.

ImageName

The bundled-image name that image callers resolve by (the file stem).

LocalizedText

A localized text source: label(tr("greeting").arg("name", name)) (§12.2).

NativeRef

A liveness-checked reference to a mounted piece’s realized node — the retained half of the tweaks API (docs/tweaks.md). Capture one with Decorate::native_ref, then reach the native widget later (from event handlers, timers) through a toolkit ext accessor. node/with yield None before mount and after the node’s subtree is disposed, so async races are safe no-ops.

RNode

Realized-node key. NodeId (the spec-boundary id) is its FFI encoding.

Resource

A handle to a bundled resource’s bytes with efficient random read-only access.

TaskHandle

A handle to a spawned task. Copy and !Send (the executor is thread-local).

VectorName

The bundled-vector name that vector 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).

WindowHandle

A live secondary window (docs/windows.md). Cheap to clone; inert after close.

WindowOptions

Enums

Lifecycle

An app-lifecycle phase (docs/lifecycle.md). Each backend maps these onto its OS’s native app / activity delegate. Some phases only exist on some platforms — a mobile app truly enters the background and can be low on memory, a desktop app essentially cannot — so Lifecycle::is_universal marks the ones every backend delivers, and Toolkit::supports_lifecycle reports per-backend truth.

WindowKind

What a secondary window IS, so backends can apply platform conventions (docs/windows.md).

Traits

IntoFArg

Disjoint-marker conversion for .arg values (the same E0119 dodge as IntoText).

IntoNumberFArg

Marker for IntoFArg values that carry a number — required for a Fluent variable used as a plural / select selector, where CLDR plural rules select on a number (so a string can’t be passed there by mistake). Implemented for the numeric IntoFArg types only (i64, f64, and their Signals); the generated res::str::<key>(…) functions (§18.5) type such parameters as impl IntoNumberFArg instead of impl IntoFArg.

Piece

A UI description consumed once (§5.2). Returns the root realized node it created.

PieceSeq

Children of a container: a tuple of pieces (the floem ViewTuple pattern — implemented ONLY for tuples, (), and PieceVec, never via a blanket, to stay coherent).

Functions

app_temp_dir

An app-writable scratch directory. The OS temp dir is NOT app-writable on every target (Android reports getCacheDir()), so a backend records the right location at startup and this is how an app asks for it. For derived files an app can rebuild: rendered documents, thumbnails, export 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.

compare

Compare two strings in the CURRENT locale’s collation order. Reads the locale signal (tracked), so a sort inside a reactive closure re-runs when the locale switches.

compare_in

Compare two strings in locale’s collation order (untracked; accepts -u-co- extensions, e.g. "zh-u-co-stroke"). Falls back to code-point order if the locale has no collation data.

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.

env

An app-environment value, portably: the process environment on native targets, the page URL’s query string on web-dom (where a browser sandbox has no process environment — day launch --env K=V forwards each pair as a query parameter, docs/web.md). Prefer this over std::env::var for anything a --env flag should be able to set on every target.

focused_window

The most recently focused open secondary window, if any. None ⇒ the primary window is key (or no secondary window exists).

install_locales

Register the app’s locales (see day_l10n::install) and fix the layout direction from the locale that actually resolved (docs/localization): an RTL locale (Arabic, Hebrew, …) mirrors every horizontal placement and flips the native toolkit’s direction. Direction is resolved once, before the first layout — runtime set_locale switches strings but not direction.

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

launch

launch_external

Launch through an EXTERNAL toolkit’s backend (docs/extending.md “External toolkits”) — the cfg-free counterpart of the feature-gated launch entries below, for platform-toolkit pairs registered via [package.metadata.day.toolkit]. Feature-independent on purpose: day build -p <external> compiles the app with only the external toolkit’s own feature, so none of the launchers below exist in that build. Starts the dayscript engine exactly as they do — which is what keeps day launch --script, day drive, and the session registry working on a backend this repository has never heard of.

lifecycle_supported

Does the running backend deliver phase? Use this to guard registration at runtime: if day::lifecycle_supported(Lifecycle::DidEnterBackground) { on_lifecycle(...) }.

locale

The current locale (a tracked read inside bindings).

matches_search

matches_search_in against the CURRENT locale. Reads the locale signal (tracked), so a filtered list inside a reactive closure re-filters when the language changes — the same contract crate::compare has.

matches_search_in

Does text match query under locale’s rules? (untracked — pass the locale explicitly).

on_lifecycle

Register f to run whenever the app reaches phase. Handlers run in registration order, in a reactive batch (signal writes coalesce into one UI update). Register early — before launch, or at the top of the root builder — so WillLaunch/DidLaunch handlers are in place when they fire.

open_preferences

Open-or-focus the preferences surface (docs/windows.md): a WindowKind::Preferences singleton window on desktop, the cover fallback elsewhere — one call for menu items and toolbar gears alike. false = no preferences piece is registered (logged).

open_window

Open a secondary window (docs/windows.md). key names the LOGICAL window: when a window with this key is already open it is focused and returned instead of duplicated (the preferences pattern); None always opens a new one. Where the toolkit cannot open windows (Cap::MultiWindow = Unsupported — probe it to adapt chrome) the content presents as a fullscreen cover in the primary window instead, closable the same way.

play_script

Replay a dayscript against the running app, in-process (docs/dayscript.md “Recording”): parse yaml and run each step through the embedded engine, on the main thread between flushes — the same executor day launch --script drives. Returns an error while a recording is live (a replay must not record itself) and on web (no background thread — drive the page over the WebSocket transport there). See record.

register_new_window

Register the builder behind File ▸ New Window and the macOS tab-bar “+” (docs/windows.md): each call opens another WindowKind::Normal window. A menu_role(MenuRole::NewWindow) item lowers to this action; without a registration it lowers disabled.

register_preferences

Declare the app’s preferences piece (docs/windows.md) — once, in root(), ideally before app_menu. Enables the desktop Preferences window (singleton, primary+,), the auto Settings…/Preferences menu item, and open_preferences everywhere (cover fallback where the toolkit cannot open windows). The window titles itself with options.title; use register_preferences_with to localize it or change the size.

register_preferences_with

register_preferences with explicit window options (localized title, size).

resource

Open a bundled resource by name for efficient random read-only access.

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-android’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 — a mid-run inset change (rotation) does not re-pad already-built pages.

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.

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.

sort_localized

Sort a slice in place in the CURRENT locale’s collation order (tracked, like compare).

task

Spawn an async flow onto Day’s main-loop executor. This is the opt-in seam 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.

toolkit_name

The display name of the toolkit compiled into THIS binary — "AppKit", "GTK", "Qt", "UIKit", "Android", "XAML", "ArkUI", "DOM" (or "Mock"). Handy for a window title that names its backend.

tr

window_by_key

The open window registered under key, if any (the dayscript screenshot step’s window: target resolves here).