file_manager

Standalone, read-only VFS file manager window. Each open() returns a handle to an independent window so multiple managers can coexist. Listing goes through vfs.list; preview reads files via vfs.read and renders text-like extensions as monospace text. Built on zui.

Exports

• M.open(opts: OpenOpts?) -> Handle — open a new window. Returns the existing handle when called with a live id. path defaults to /zero/.
• M.close(handle: Handle?) — close a window. Safe on nil or already-closed handles.
• M.refresh(handle: Handle?) — force-refresh the current directory listing and re-render now (bypasses the once-per-second rate limit).
• M.__dispatch(callbackId: string, data: any?) — internal; called by the __FileManagerCallbackProxy script-component to route ui.* callbacks into the matching handle.

Types:

• OpenOpts = { id?: string, path?: string }
• Handle = { id, prefix, windowId, screenName, rootPath, alive, state, app?, dispatch? }

Usage

local FileManager = require("@builtin::modules.file_manager")

local handle = FileManager.open()                          -- root at /zero/
local h2     = FileManager.open({ path = "/zero/source/" })
local h3     = FileManager.open({ id = "logs", path = "/zero/runtime/logs/" })

FileManager.refresh(handle)
FileManager.close(handle)

Window

• Nav bar: home (⌂), parent (↑ ..), current path, refresh (↻), close (×).
• Top pane: directory listing — folders (orange) first, then files. Click a folder to descend; click a file to preview.
• Bottom pane: file preview. Text-like extensions (.luau, .lua, .yaml, .yml, .json, .toml, .md, .txt, .wgsl, .glsl, .component, .scene, .module, .controller, .system, .tool, .log, .ini, .csv, .html, .css, .js, .ts, .xml, plus extensionless files) render as monospace text. Anything else shows Binary file: N bytes.

The current directory is auto-refreshed once per second so newly written files appear without manually clicking refresh.

Notes

• Read-only. No create / rename / delete / mkdir — vfs.list doesn't expose mtime/size and the FFI has no delete or mkdir bindings yet.
• Preview cap: 256 KiB. Larger files are truncated with a notice; the rest is not loaded into memory.
• No size column: vfs.list returns only { name, isDirectory }.
• Shared callback proxy: a single __FileManagerCallbackProxy script-component handles every open handle's ui.* events. The proxy runs in its own env but the same VM, so its body requires this module to reach the shared handle registry (per-VM require cache) and routes callbacks through FileManager.__dispatch — no _G state.