example native windows

Native windows

Status: Stable. The native-window registration API has shipped. This page is a redirect — the worked examples live in dedicated docs.

Native windows are windows whose content renders directly in the parent DOM instead of inside a chromeless iframe. Use them for desktop-first UI — small tools, chat widgets, status HUDs — that would be awkward to wedge into a full admin-page iframe.

Where to start

• Register a desktop icon (Jorvy) — the canonical end-to-end example: PHP openstation_register_window() + openstation_register_icon() + a JS render callback. Read this first.
• Native window with tabs — multi-pane windows via openstation_register_window_tab(), including the auto-swap rendering pattern other plugins can extend.
• Native window with bundle-bound config — the recommended way to ship REST URLs / nonces / session-bound data to your bundle so it lands on both eager and lazy load paths.
• Layout primitives — <os-stack> / <os-section> / <os-row> / etc. Compose these inside your template callback.

The render-callback contract in one paragraph

The shell clones the registered <template> into the window body before invoking your render callback, so render is enhancement, not construction: query body.querySelector( … ) for the mount points your template declared, light them up. The callback's return value is captured as a teardown (cleared on window close — interval cleanup, listener removal, the usual). To start from a blank canvas anyway, call body.replaceChildren() first; nothing the shell did is irreversible.

Related

• Dock badges — registering a regular iframe-backed dock item.
• Architecture: two window types — iframe vs native distinction.
• native-windows-proposal.md — historical RFC; the shipped API differs in details, the docs above are authoritative.