Home

WP OpenStation — Developer Documentation

This folder is the contract between WP OpenStation and the plugins that extend it.

If you are building a plugin that interacts with the desktop shell — opens windows, adds dock items, listens to window events, drops icons on the wallpaper — start here.

Index

1. Getting Started — your first hook, in five minutes.
2. Event-Driven Framework — Stable. The mental model: framework as transport, apps own UX policy. Read once before building anything non-trivial.
3. Agents Security Model — Experimental. The trust model for the one part of the framework that acts with capability: why agents can never authenticate, why a run is ceilinged at the invoker's capabilities, why tool output is untrusted input, and why granting an agent a role is granting capability. Read before registering an ability agents can call or adding a trigger intake.
4. Architecture — what renders where, and why.
5. Station Home — the native Dashboard replacement, data contract, responsive design contract, and Imagegen record.
6. Hooks Reference — every PHP action and filter, with signatures, defaults, and minimal examples.
7. JavaScript Reference — CustomEvents on document, the window.wp.os API, and the iframe postMessage bridge.
8. API Index — single-page table of every wp.os.* method, CustomEvent, and postMessage type with its current status. Use this when you need to grep the surface, then jump to the per-API reference for details.
9. Examples — recipes you can copy into a plugin.
10. Bridge Protocol Overview — internals doc. End-to-end wiring of wp.os.connect() / wp.os.iframe.* / the synthesised iframe inside native windows. Read when debugging a stuck handshake or building unusual integrations.
11. Native Windows & Framework Interop — Stable. Public API for openstation_register_window() / openstation_register_window_tab(), Web Components as first-class, and how React / Vue / Svelte plug in without the shell taking a framework dependency. See also examples/native-windows.md and examples/native-window-with-tabs.md.
12. Dock Customization — Stable. Three orthogonal registries — decoration hooks, submenu renderer, dock rail renderer — that let a plugin author go from "tweak a className" to "replace the entire rail with a circular ring." Start here if you want to customize the dock visual.
13. Plugin Compatibility Layer — internals doc. How OpenStation adapts third-party plugins (WooCommerce, Yoast, etc.) whose CSS or menu-registration assumes classic admin chrome. The three-tier mental model — CSS variables → runtime offset scanner → targeted overrides — and the decision tree for adding a new fix. Read before touching chromeless.css or the dock builder for plugin-specific work.
14. Files on the Desktop — Experimental. OpenStation_File base class, openstation_register_file_type(), and wp.os.files.*. The registry, folders, opener associations with per-user overrides, folder sharing, real file storage, and the Trash pin-to-desktop flow are all live.
15. Desktop Themes — Experimental. Whole-OS reskins uploaded as a ZIP of theme.json plus images and fonts: every design token, the typeface, a texture on any of 24 surfaces (chrome, dock, desk, menus, dialogs, tables, buttons) plus a documented way to add your own, and a complete iconset down to the window control glyphs. No author CSS or JS ever executes — PHP validates the manifest and compiles the stylesheet, @font-face rules included. Read before authoring a theme, or before touching the texture and typography tokens in variables.css. See also examples/register-desktop-theme.md.
16. Folder Sharing — Experimental. Per-principal read / write grants on desktop folders with first-sight opt-in, polymorphic target_type schema, If-Match conflict detection, and a <os-modal>-based Share Settings UI.
17. Mio — Experimental. The desk companion: a PixiJS soft-body blob with a chroma neon outline that floats over the wallpaper, feels the gravity of nearby windows and settles onto them, watches your cursor (including across window iframes), and can be dragged anywhere. Covers the simulation, the four soft-body failure modes worth knowing before touching it, the openstation_mio_config filter, and wp.os.mio.
18. Icons: Stable. The thirty-icon set and the one rule behind it: Core owns the verbs, OpenStation owns the nouns. Covers osIcon() / osIconSvg() / osIconDataUri(), the sizing floor below which a Core glyph goes faint, the three groups that stay hand-drawn and why, and how the same eleven reach WordPress's own icon registry as outlines. Read before drawing any glyph.
19. Native Desktop Host — Experimental. The optional Electron layer, shipped as an extension so core never mentions Electron: any window can be set free into a real OS window ("Send to your Mac"). Covers the two generic core capabilities it stands on (wp.os.registerWindowAction() and ?openstation_solo=), the capability-probe detection model, and the deliberately cheap liveness pulse. Read before touching the ⋯ menu or solo mode.
20. Progressive Web App (PWA) — Stable. Web app manifest, service worker (root-scope, narrow fetch handler), install affordance, and wp.os.notify() for local notifications. Phase-4 Web Push wiring lands later without breaking the v1 call surface.
21. Layered layout — the structural refactor that split the historical god-modules: the @core / @api / @protocol / @layout / @ui path aliases, the registry / server-sync / api-client primitives, the public-API facade home, and the PHP slicing of helpers.php / components.php / render.php. Read once before adopting any of the new modules in your plugin.
22. Migration — activity channels move to os/ (1.0.0) — the eleven framework-published activity channels drop the pre-rebrand desktop-mode/ prefix. No alias ships: a subscriber left on an old slug stops firing silently. Read if you subscribe to or filter any built-in channel.
23. Migration — native window tabs move to the chrome — a multi-tab native window no longer renders an <os-tabs> strip into its body; the shell builds one strip in the window chrome from the same metadata. openstation_register_window_tab() is unchanged. Read if you listened for os-tab-change, or styled or queried that strip.
24. Migration — window, wallpaper and widget bundles load on demand — a window's script loads on first open, a canvas wallpaper's when it's applied or previewed, a widget's when it mounts — instead of all of them on every admin page. Nothing to do for a bundle that only publishes its render/mount callback; read if yours also has a boot-time job, extends another plugin's window, or calls an API one publishes.
25. Migration — the navigation model — one model decides where every menu, app and control shows up; itemVisibility / dockOrder become navPlacement / navOrder, native windows take nav_kind, and rails paint three zones. Read if you register a native window with a dock tile, read or write OpenStation Preferences state, or ship a dock rail renderer.
26. Register a widget — polling, storage, canvas charts
27. The Living Tree — algorithm definition — Experimental. The full normative spec for the wp-living-tree canvas wallpaper: WordPress emits hormones, the biology (Space Colonization) decides geometry inside age-bounded morphological constraints. Read before touching any part of the wallpaper.

Conventions used in this docs folder

• Status labels — every hook, event, or API surface carries one of:
  • Stable — shipping today, backwards-compatible inside the current major version.
  • Experimental — shipping but signature may change.
  • Planned — reserved name, not yet fired. Do not rely on it.
• Code examples are complete, drop-in, and use my_plugin_ / my-plugin prefixes as they would in a real plugin.
• PHP examples assume a plugin file with defined( 'ABSPATH' ) || exit; at the top.
• No version tags — these docs describe what the current release does, not when a given surface was added. Breaking changes get a migration-*.md note instead of inline version annotations.

Reporting breakage

If a documented hook behaves differently than what's written here, that is a bug in either the code or the docs. Open an issue or PR. Do not work around it silently — the docs are source of truth for plugin authors.