# filedom

> A React renderer for the macOS desktop. Components render as real Finder icons.

## Docs

- [FileDOM](https://filedom.method.actor/docs): Render React components as real Finder icons.

## Learn

- [Getting Started](https://filedom.method.actor/docs/learn/getting-started): Install FileDOM and run your first game.
- [Choose an API](https://filedom.method.actor/docs/learn/choosing-an-api): Pick the smallest abstraction that fits what you want to put on the desktop.
- [The Rendering Model](https://filedom.method.actor/docs/learn/rendering-model): Why filedom never changes an icon in place: Finder's blanking behavior, the move-only law, and the park + cover protocol.

## Guides

- [Build a text surface](https://filedom.method.actor/docs/guides/text-surfaces): Turn editor or chat state into a bounded viewport of reusable glyph files.
- [Troubleshooting](https://filedom.method.actor/docs/guides/troubleshooting): Fix permissions, missing icons, and input problems.
- [Status](https://filedom.method.actor/docs/guides/status): Releases and current limits.

## Reference

- [filedom](https://filedom.method.actor/docs/reference/react-api): The main entry point: roots, the startSession lifecycle, the asset-authoring toolkit, and shared types.
- [filedom/system](https://filedom.method.actor/docs/reference/system): The native macOS host bridge plus filesystem operations behind the React layer.
- [filedom/sound](https://filedom.method.actor/docs/reference/sound): Sound effects and playback backends.
- [Architecture](https://filedom.method.actor/docs/reference/architecture): How the published package, the internal @filedom/* packages, the reconciler, and the native runtime fit together.
- [Host Runtime](https://filedom.method.actor/docs/reference/host-runtime): The TypeScript bridge that orchestrates processes and talks to the macOS-native Swift binaries.
- [Swift Runtime](https://filedom.method.actor/docs/reference/swift-runtime): The native controllers that move icons, capture input, and play audio on macOS.

### Components

- [Components](https://filedom.method.actor/docs/reference/components): React components for desktop rendering.
- [StageProvider](https://filedom.method.actor/docs/reference/components/stage-provider): Provides the park position, background, and icon size for stages.
- [Stage](https://filedom.method.actor/docs/reference/components/stage): Owns a pool of reusable desktop icons.
- [Sprite](https://filedom.method.actor/docs/reference/components/sprite): Displays one pooled icon at a position.
- [Wallpaper](https://filedom.method.actor/docs/reference/components/wallpaper): Sets the desktop wallpaper.
- [VirtualTreeProvider](https://filedom.method.actor/docs/reference/components/virtual-tree-provider): Provides a filesystem tree and desktop display settings.
- [Score](https://filedom.method.actor/docs/reference/components/score): Displays a changing number using pooled digit icons.
- [Text](https://filedom.method.actor/docs/reference/components/text): Shows or hides a block of laid-out text tiles.
- [GameOverlay](https://filedom.method.actor/docs/reference/components/game-overlay): Renders help and game results from an overlay controller.
- [Layout](https://filedom.method.actor/docs/reference/components/layout): fitIconSize, centerBoard, createGrid, distribute: sizing and point math for boards made of icons.

### Hooks

- [Hooks](https://filedom.method.actor/docs/reference/hooks): React hooks for desktop games.
- [useDesktopGameShell](https://filedom.method.actor/docs/reference/hooks/use-desktop-game-shell): Configures the desktop and derives game geometry.
- [useDesktopMetrics](https://filedom.method.actor/docs/reference/hooks/use-desktop-metrics): Subscribes to desktop metrics in state and a ref.
- [useBounds](https://filedom.method.actor/docs/reference/hooks/use-bounds): Reads current desktop metrics.
- [useViewOptions](https://filedom.method.actor/docs/reference/hooks/use-view-options): Reads and updates desktop view settings.
- [useInitialSetup](https://filedom.method.actor/docs/reference/hooks/use-initial-setup): Keeps startup loading active while game assets are prepared.
- [useGameControls](https://filedom.method.actor/docs/reference/hooks/use-game-controls): Binds keyboard controls and generates matching help text.
- [useGameOverlay](https://filedom.method.actor/docs/reference/hooks/use-game-overlay): Manages help visibility and result configuration.
- [useKeypress](https://filedom.method.actor/docs/reference/hooks/use-keypress): Subscribes to normalized global keydown events.
- [useDesktopPointInput](https://filedom.method.actor/docs/reference/hooks/use-desktop-point-input): Routes desktop pointer events by coordinates.
- [useDesktopClick](https://filedom.method.actor/docs/reference/hooks/use-desktop-click): Calls a handler when a file is clicked.
- [useDesktopRightClick](https://filedom.method.actor/docs/reference/hooks/use-desktop-right-click): Calls a handler when a file is right-clicked.
- [useDesktopDrag](https://filedom.method.actor/docs/reference/hooks/use-desktop-drag): Reports a file position after dragging.
- [useDesktopSelection](https://filedom.method.actor/docs/reference/hooks/use-desktop-selection): Tracks selected Finder paths.
- [useFixedTick](https://filedom.method.actor/docs/reference/hooks/use-fixed-tick): Runs a callback at a fixed interval.
- [useIntentQueue](https://filedom.method.actor/docs/reference/hooks/use-intent-queue): Buffers unique input intents between ticks.
- [useStageSession](https://filedom.method.actor/docs/reference/hooks/use-stage-session): Reads all values from the enclosing StageProvider.
- [useStagePark](https://filedom.method.actor/docs/reference/hooks/use-stage-park): Reads the required park position.
- [useStageParkOrNull](https://filedom.method.actor/docs/reference/hooks/use-stage-park-or-null): Reads the park position when one is available.
- [useStageIconSize](https://filedom.method.actor/docs/reference/hooks/use-stage-icon-size): Reads the icon size supplied by StageProvider.
- [useStageBackgroundColor](https://filedom.method.actor/docs/reference/hooks/use-stage-background-color): Reads the background color for a park cover.
- [useProvideWallpaperColor](https://filedom.method.actor/docs/reference/hooks/use-provide-wallpaper-color): Supplies a wallpaper color to StageProvider.
- [useVirtualTree](https://filedom.method.actor/docs/reference/hooks/use-virtual-tree): Reads the filesystem tree and its mutation actions.
- [useDesktopSettings](https://filedom.method.actor/docs/reference/hooks/use-desktop-settings): Reads inherited desktop display settings.
- [useSound](https://filedom.method.actor/docs/reference/hooks/use-sound): Returns a soundboard for semantic game events.
- [useSoundtrack](https://filedom.method.actor/docs/reference/hooks/use-soundtrack): Loops a system sound while enabled.
- [useEmittedSounds](https://filedom.method.actor/docs/reference/hooks/use-emitted-sounds): Maps emitted domain events to sound effects.
- [useSoundTransitions](https://filedom.method.actor/docs/reference/hooks/use-sound-transitions): Plays sounds when observed state changes match rules.

## Examples

- [Pong](https://filedom.method.actor/docs/examples/pong): Pong played with real Finder icons, in local and networked modes.
- [Chess](https://filedom.method.actor/docs/examples/chess): Drag-to-move chess on the Finder desktop, a denser example of positioning, drag input, and host round-trips.

## Finder Mode

- [Finder Mode](https://filedom.method.actor/docs/finder-mode): Games and tools played with your desktop icons.
- [People & invitations](https://filedom.method.actor/docs/finder-mode/people-and-chat): How Finder Mode connects players and sends game invitations.
- [Guest servers](https://filedom.method.actor/docs/finder-mode/guest-access): Connect directly to a private test or self-hosted FinderMode server without Patreon.

## Agent resources

- [llms-full.txt](https://filedom.method.actor/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://filedom.method.actor/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [JSON API](https://filedom.method.actor/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://filedom.method.actor/openapi.json.
- [Agent skills](https://filedom.method.actor/.well-known/agent-skills/index.json): Agent Skills discovery index of the skills this site publishes.
- [API catalog](https://filedom.method.actor/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [AI catalog](https://filedom.method.actor/.well-known/ai-catalog.json): ARD manifest of the agent-facing resources on this site (MCP server, skills, APIs).
- [agent-readability.json](https://filedom.method.actor/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://filedom.method.actor/sitemap.xml): Every indexable page URL with its last-modified date.