Gridland Framework

The @gridland/container package allows you to run Gridland apps or any CLI tool inside an isolated Docker container. This provides a safe sandbox for executing untrusted terminal code, making it ideal for agent tools, code playgrounds, and review environments where you want to prevent code from accessing your host machine.

Requirements

• Docker must be installed and running.
• Bun version 1.0 or later.

# Run a demo in a sandbox
bunx @gridland/container @gridland/demo -- landing

Gridland is JSX that renders to a cell grid rather than HTML. This allows the same component tree to be targeted at different environments:

1. In a browser: Uses @gridland/web to draw to an HTML5 <canvas>.
2. In a terminal: Uses @gridland/bun to draw to stdout via a native FFI bridge.
3. As plain text (Headless): Renders the component tree to a plain-text string. This is a first-class target designed for AI agents, crawlers, and screen readers to ensure accessibility and searchability without needing a canvas or terminal.

Because all three paths accept the same components and hooks, you can share a single codebase to ship a web TUI, a CLI binary, and an agent-readable document simultaneously.

Wrap your application in PromptInputProvider to lift the input state (text, suggestions, etc.) outside of the PromptInput component. This allows sibling components to interact with the input.

Use usePromptInputController to access and modify the state:

• controller.textInput.value: current text
• controller.textInput.setValue(v): set text
• controller.textInput.clear(): clear text
• controller.suggestions.setSuggestions(s): update suggestions

import { PromptInputProvider, usePromptInputController } from "@/components/ui/prompt-input"

<PromptInputProvider initialInput="">
  <Sidebar />
  <PromptInput focusId="prompt" autoFocus onSubmit={handleSubmit} />
</PromptInputProvider>

Most Gridland components allow you to pass an explicit color prop. Explicit color props always take precedence over the values defined in the current ThemeProvider.

<Spinner text="Default" />           {/* uses theme.accent */}
<Spinner text="Custom" color="#FF6B6B" />  {/* overrides theme */}

Every container managed by @gridland/container runs with hardened security defaults to ensure isolation:

• Capabilities: All Linux capabilities are dropped (--cap-drop=ALL).
• Privileges: Prevents privilege escalation (--security-opt=no-new-privileges).
• Filesystem: The root filesystem is read-only (--read-only).
• Process Limits: Limits the process count to 256 (--pids-limit=256).
• Memory: Defaults to a 512MB cap (--memory=512m).
• User: Runs as an unprivileged runner user (non-root).
• Scratch Space: A writable tmpfs is provided at /tmp, limited to 256MB.

Warning: Network access is enabled by default. Always use the --no-network flag when running untrusted code that should not make outbound connections.

The status prop allows you to transition the spinner from an animated state to a static completion symbol. When a status is provided, the animation stops and a semantic icon is displayed using the appropriate theme color.

Note: The default status is spinning.

<Spinner status="success" text="Dependencies installed" />
<Spinner status="error" text="Build failed" />
<Spinner status="warning" text="Compiled with warnings" />
<Spinner status="info" text="3 tasks queued" />

When you mount the <TUI> component, it installs a BrowserContext for all its descendants. This context acts as the single source of truth for the renderer, the canvas element, and cell dimensions.

Use the useBrowserContext() hook inside any component that is a descendant of <TUI> to access the current BrowserContextValue. This allows browser-only hooks like useFileDrop and usePaste to function correctly.

import { BrowserContext, useBrowserContext } from "@gridland/web"

// Inside a component descendant of <TUI>
const context = useBrowserContext();

The useKeyboard hook is used to register keyboard event handlers. It supports two scoping modes:

1. Global Handlers (Recommended): To register a handler that works regardless of which element has focus, pass { global: true } in the options object.
2. Scoped Handlers (Deprecated): The bare form useKeyboard(handler) is deprecated. It is intended for handlers that should only fire when a specific component's subtree is mounted or focused.

Note: When migrating, be careful not to convert scoped handlers (like those in Modals or Tab Bars) to global handlers, as this will cause them to intercept keys even when they are not the active focus target.

// Global handler (Blessed form)
useKeyboard(handler, { global: true });

// Scoped handler (Deprecated bare form)
useKeyboard(handler);