Skip to content

README.md

Latest commit

 

History

History
43 lines (35 loc) · 6.96 KB

README.md

File metadata and controls

43 lines (35 loc) · 6.96 KB
Raw

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. Hooks Reference — every PHP action and filter, with signatures, defaults, and minimal examples.
  6. JavaScript Reference — CustomEvents on document, the window.wp.os API, and the iframe postMessage bridge.
  7. 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.
  8. Examples — recipes you can copy into a plugin.
  9. 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.
  10. 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.
  11. 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.
  12. 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.
  13. Files on the Desktop — Experimental. OpenStation_File base class, openstation_register_file_type(), and wp.os.files.*. Phase-0 registry only today; folders, opener associations, sharing, and drag-from-Recycle-Bin land in subsequent phases.
  14. 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 22 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.
  15. 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.
  16. Mio — Experimental. Mio's two companion forms: the calm persistent openstation/mio widget and the PixiJS soft-body mascot that floats over the wallpaper. Covers the widget's one-time pin, local state and lifecycle, plus the floating simulation, openstation_mio_config filter, and wp.os.mio.
  17. 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.
  18. Migration 0.7 → 0.8.1 — what landed in the architecture-0.8.1 refactor: 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.
  19. Migration — AI comment-only + native search (0.11.0) — the AI Copilot is scoped to comment spam scoring; post/term auto-analysis and its hooks are removed, the assistant now finds content with native keyword search, and the bulk /ai/reindex endpoint is gone. Read if you depended on any openstation_ai_*post* / *term* hook or the reindex route.
  20. Register a widget — polling, storage, canvas charts
  21. 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.