Choose an API
Pick the smallest abstraction that fits what you want to put on the desktop.
Pick an API by what you want to display. The lowest-level Finder command is rarely the right starting point.
| What you’re building | Start here | Why |
|---|---|---|
| A moving game piece or changing visual state | Stage & Sprite | Prepare variants once, then move warm files. |
| A score or counter | Score | Reuse prepared digit artwork. |
| A banner, label, or help panel | Text | Lay lines out once as tiles; show or hide the block. |
| Keyboard help or a pause screen | Overlays | Reuse the existing help display and lifecycle. |
| An editor or conversation transcript | Text surfaces | Separate text state from glyph allocation and placement. |
| Responsive positioning | Layout | Derive positions from the current desktop geometry. |
Own state in your application
FileDOM renders your state. Game rules, note persistence, network connections, and editor commands stay in your code, where you can test them without moving real Desktop files. Hooks connect input and desktop geometry to that model.
Changing artwork works by switching which prepared file is visible, so a Sprite never updates a file’s custom icon frame by frame. Read the rendering model before allocating your first pool.
Choose the lifecycle deliberately
A bare createRoot() owns its rendered tree. Unmounting it removes the files it
rendered and restores any wallpaper or view options it changed, but it does not
hide or reveal the user’s Desktop items or touch the Dock and menu bar. For a
full desktop takeover, use the session API,
which adds those steps. Under Finder Mode, the signed app hides and restores the
Desktop itself and the session skips its own copy of that work.
Reach lower only when you need to
The system API exposes native operations. Calling it directly makes you responsible for ordering, ownership, and cleanup, so prefer the component lifecycle unless you are building a primitive the library lacks.
Next, follow Pong for a small game. To extend FileDOM itself, read architecture and the host runtime.