tabApp

Layer 5 shell — visibility-driven tabbed app. Wraps Z.app with a per-tab refresh scheduler that gates ALL data fetches on (window_visible AND tab_active AND refresh_due), so the panel costs zero engine work when hidden / closed / minimized and only the active tab's build() is invoked when open. Lifted from system_tools.module (the original consumer) so future live-data tools compose against this surface instead of re-implementing the scheduler.

Exports

• M.create(opts: TabAppOpts) -> TabAppHandle — build and mount a tab app. Required: name, tabs, tabOrder.
• M(opts) — the module table is callable; equivalent to M.create(opts).

Types:

• TabSpec = { label?, refresh?, build?, onMount?, onCallback?, tick? }
• ChromeOpts = { title?, layout?, minimizable?, closable?, minWidth?, minHeight?, maxWidth? }
• ExtraScreenSpec = { build?, refresh?, layer?, tags?, onCallback? }
• AppOpts = { layer?, tags?, ctx? }
• TabAppOpts = { name, tabs, tabOrder, tabAliases?, statusClock?, onStatusTick?, chrome?, extraScreens?, appOpts?, initialState?, callbackPrefix?, windowId?, closedWidth?, closedHeight?, minimizedWidth?, tabGap?, tabPadding? }
• TabAppHandle = { app, state, update, onCallback, destroy, setVisible, screenName }

Usage

local TabApp = require("@builtin::modules.zui.shell.tabApp")

local handle = TabApp {
    name         = "system_tools",
    tabs         = TABS,
    tabOrder     = { "entities", "logs" },
    statusClock  = 0.1,
    onStatusTick = function(state) ... end,
}

-- Per-frame
handle.update(dt)

Notes

• The scheduler keeps a single shared schedClock plus per-timer lastFire timestamps. Stepping lastFire by the refresh interval (rather than to now) keeps timers phase-locked to their mount time forever — timers with matching intervals fire on the same frame.
• extraScreens may use either a function(state) shorthand or a { build, refresh, layer, tags, onCallback } table. The handle's onCallback dispatches into App handlers first, then per-tab onCallback, then extraScreen onCallback.
• The default chrome ships three shells (closed / minimized / open). Pass chrome.layout(state, opts) -> widget to override entirely.
• setVisible flips windowVisible AND calls ui.showScreen / ui.hideScreen for the bound screen name.
• destroy unmounts the App and resets the shared DataSource cache.