files

Files tab — VFS browser embedded in the System Tools panel. Single recursive folder/file tree on top, file preview below. Lazy: vfs.list runs only when a folder is first expanded; results cache on state.files.dirCache[path] and are refreshed when the visibility-gated scheduler ticks (1 s while the tab is active and the panel is visible — cost zero when hidden).

Built from the Z.fs.* composites so the same building blocks back the standalone FileManager window. Clicking "Open in standalone window" mounts the legacy FileManager at the current path for users who want a dedicated viewport.

Exports

• M.label: string — "Files".
• M.refresh: number — 1.0 (1 Hz).
• M.onMount(state) — seed state.files (currentPath, expanded map, dirCache, preview slots).
• M.refresh_data(state) — refresh hook; invalidates dirCache for the visible subtree.
• M.build(state) -> any — build the Files widget tree.
• M.onCallback(callbackId: string, data: any, state) -> boolean — handle tree toggle, file select, breadcrumb nav, manual refresh, copy path, open-standalone.

Types:

• FilesState = any — shell-owned tab state; carries files = { currentPath, expanded, dirCache, selectedPath, previewText, previewNote }.

Usage

-- Registered by system_tools/init.luau:
local Files = require("@builtin::modules.engine.editor.system_tools.tabs.files")
TABS.files = Files

Notes

• Preview is byte-limited (PREVIEW_BYTE_LIMIT = 256 * 1024) and refuses binary payloads — anything with a non-text extension or a NUL byte renders as "Binary file: <size> bytes".
• The directory cache key is the absolute VFS path, so invalidateCache(state, "/zero/source/") drops every entry at or below /zero/source/ in O(n) over cached paths.
• "Open in standalone window" calls into @builtin::modules.engine.ui.file_manager; the pcall lets the tab survive when that module isn't present (legacy builds without the FileManager window).