App Framework — a window in one PHP file (.osx.php + optional .os.ts), Code Blue & WP Explorer rebuilt on it

[AllTerrainDeveloper]

Proposal

An OpenStation app is a window declared in one PHP file. App::define() covers everything a native window can do today — title, size, icon, title-bar buttons, ⋯-menu rows, tabs, per-window theme/controls/slots, desktop icon, gate — plus a typed state schema, actions, and a view painted from <os-*> components. No JavaScript per app: one shared runtime mounts it, sends os-action triggers to PHP, and morphs the re-rendered body back in.

When an interaction must be instant (a filter over rows the browser already holds), the app adds a client view — a .os.ts beside the .os.php — with local actions and a view( { state, data } ) rendered by the kit's own html tag. Same state model, same dispatch contract, same effects; os-bind writes and local actions never leave the tab.

Full contract: docs/app-framework.md. Recipe: docs/examples/os-app.md.

What's in the box

• Framework core (includes/framework/): App, State, Runtime, Registry, Os, Effects, Html — calls no WordPress function. Six contracts (Auth, Settings, Hooks, Cache, Env, Store) with WordPress and standalone adapters; define( 'OPENSTATION_STANDALONE', true ) runs the same framework and the same app files on bare PHP (Runtime::describe() returns "the whole window" as a value).
• WordPress host (includes/framework/wordpress.php): loads apps/ (+ openstation_apps_directories), registers every allowed app through openstation_register_window() / _tab() / _icon(), one route POST desktop-mode/v1/apps/<id>/dispatch.
• Client runtime (src/app-runtime/, 19 kB minified / 7.1 kB gzipped): keyed DOM morph, the attribute vocabulary (os-action, os-bind, os-arg-*, os-on for every kit event, os-keys, os-debounce, os-confirm*, os-poll, os-key, os-preserve, os-prop-* for property-driven components), effects (toast, title, close, open, open_url, badge, announce, context menu, channel send), tabs, channels, lifecycle actions, wp.os.apps.{dispatch,local,session}.
• @openstation/app for .os.ts files: defineApp(), html, i18n. apps/*/*.os.ts are discovered by Vite and built by npm run build:apps.
• <os-histogram>: the stacked time chart with a toggle legend joins the component kit.
• Code Blue rebuilt as apps/code-blue/ (same window id, gate and openstation_code_blue_* hooks). Removed surface — the /code-blue/* REST routes and the window_args / icon_args / template_html filters — is written up in docs/migration-code-blue-app.md. Filters are instant (client view); reading a log, switching source and clearing are one request each.
• My WordPress rebuilt (My WordPress: WP Explorer rebuilt on the App Framework — 8,169 lines against 32,238, Agents wizard included #727, merged here) as apps/my-wordpress/ — WP Explorer as an App Framework app: the section grids, the dossiers, the Agents wizard and the WooCommerce surfaces, with the legacy desktop-mode-my-wordpress native window, its bundle and its build target deleted whole. The full story is in that PR; migration notes in docs/migration-wp-explorer-app.md.

The ledger

Source lines only, tests and docs excluded. What the framework costs once, what each app costs on top of it, and what the old implementations gave back. (Numbers include the hardening pass below — the framework grew by the services both apps were re-implementing, and both apps shrank while gaining behaviour.)

New code:

	PHP	TypeScript	CSS	Total
App Framework — includes/framework/, src/app-runtime/, runtime CSS	3,952	2,204	65	+6,221
Code Blue app — apps/code-blue/	606	356	269	+1,231
My WordPress app — apps/my-wordpress/	2,730	5,383	1,588	+9,701

Removed:

	PHP	TypeScript	CSS	Total
Old Code Blue — includes/code-blue/, src/code-blue/, its stylesheet	981	1,726	528	−3,235
Old My WordPress (WP Explorer) — the src/my-wordpress/ bundle deleted whole, plus PHP registration trims	274	15,823	18	−16,115

Read together: the two apps' 10,932 lines replace 19,350 removed ones, and the framework's 6,221 are paid once — every further port lands at the apps' ratio, not its own. <os-histogram> and <os-stat> (880 lines) are counted with neither: they joined the general component kit. On the My WordPress side, ~7,100 lines deliberately survive as shared infrastructure (the WooCommerce bundle, the shared explorer stylesheet, the cross-bundle leaf modules) — itemised in #727.

Is it actually easier to write an app now? — an honest comparison

The line counts say a third of the code; here is what that means at the desk, task by task, old implementation against new — including what got harder.

Registering a window. Old Code Blue needed five PHP files: window.php (registration args, the icon, a kses'd template callback, three filters, an init priority matched by convention), rest.php, assets.php, bootstrap.php, plus a per-app Vite build target and the lazy-load sync wiring. Old My WordPress's window.php alone was 359 lines. New: one App::define() chain in one file — the template, the dispatch route, the gate, the stylesheet and the client bundle are all derived by convention (npm run build:apps discovers every apps/*/*.os.ts).

Painting UI. The old bundles were imperative: renderCodeBlue() built every control with document.createElement, attached an addEventListener per control, and choreographed its own paint functions and repaints — 26 imperative DOM calls in old Code Blue's entry, 274 across old My WordPress's. The new view is a function of ( state, data ): new Code Blue contains zero createElement/addEventListener calls — the whole window is a template — and new My WordPress contains 18, of which 15 live in wire.ts, the deliberately imperative edge (drag-out, drop targets, the hover card).

Talking to the server. Old: every operation was its own REST route (register_rest_route + permission_callback + args schema) and its own client function in a hand-rolled REST module (src/code-blue/rest.ts, 118 lines; src/my-wordpress/rest.ts, 1,101 lines) reading window config, joining URLs, carrying nonces, handling errors. New: an operation is one ->action() closure; the wire, the nonce, request serialisation, the local-write-survives-echo race handling, busy states and error toasts are the runtime's. One-off reads go through ctx.fetch. And there is one capability gate per app instead of a permission_callback per route — fewer places to get authorization wrong.

The behaviour every list window needs. Old: each window rebuilt pagination, selection, marquee, stat tiles and formatters for itself — that is a large part of how the old My WordPress bundle reached 15,707 lines. New: createPagedList(), applySelection(), createMarquee(), <os-stat>, formatBytes/formatDate, Os::page()/Os::facts() — an app composes them instead of writing them.

Testing. mockViewContext() mounts an app view in jsdom in one call and local actions are pure reducers; the old bundles needed a DOM rig and fetch stubs per module. The Code Blue suite pins the whole app at under half its old size.

What is honestly harder, or new:

1. There is a model to learn. Server action vs local action vs os-bind — you must decide which side every interaction lives on, and the wrong default is slow: a server-view interaction is a full WordPress request (~235 ms on the local Docker). The framework makes the right choice possible, not automatic.
2. The attribute vocabulary and effects are a DSL. Until os-action/os-arg-*/os-confirm/os-poll are muscle memory, the reference stays open in a tab.
3. State is a schema. Undeclared keys are silently dropped and types are coerced — deliberate and documented, but the first "why doesn't the client remember this?" hour is real.
4. Debugging crosses more layers — trigger → binding → dispatch wire → State coercion → data() → render — than "click handler mutates DOM" ever did.
5. Shadow-DOM components change test idioms. textContent does not see into <os-stat>; assertions read props/attributes (several were converted during the port).
6. Client views are not third-party-consumable yet. @openstation/app is a Vite alias into src/ — outside plugin authors get server views today; the instant path is ours until the package ships.
7. The imperative edge remains. My WordPress's wire.ts is still ~700 lines of drag/drop/hover glue in mounted/updated. The framework shrank that corner; it does not — and should not — pretend it away.

Net: for the shapes admin windows actually take — lists, forms, dashboards, detail panes — an app is about a third of the code, and roughly a working day of registration/REST/paint ceremony per window is simply gone. The price is a learning curve and a wire between the author and the DOM. Code Blue demonstrates the floor (an entire window with zero imperative DOM); My WordPress demonstrates the ceiling (the hardest 15% still needs hands, just fewer of them).

How an app opens — click to painted

Nothing about a Code Blue window is in the tab until you ask for it. The
runtime is registered at boot and never enqueued; the client view, both
stylesheets and the log itself arrive on the first open, in this order:

sequenceDiagram
    autonumber
    actor U as User
    participant SH as Shell · window manager
    participant CV as apps/code-blue.min.js
    participant RT as app-runtime.min.js
    participant API as REST · dispatch route
    participant AP as Runtime + code-blue.os.php
    participant LR as log-reader.php

    Note over SH,LR: PHP already ran. init@10 loaded apps/*/*.os.php into the Registry.<br/>init@20 registered the native window, the desktop icon, the Refresh button and the ⋯ Clear row,<br/>and shipped openStationWindowConfig — osApp true, the endpoint, a nonce, the declared state.<br/>Not one byte of this window's JS or CSS is in the tab.

    Note over U,SH: 1 · The ask
    U->>SH: click the dock tile or the desktop icon
    SH->>SH: manager.open() — window frame in the DOM, loading overlay up
    SH->>SH: cloneTemplate() — the server-rendered mount root paints its os-spinner

    Note over SH,CV: 2 · First open only — companion assets, in contract order
    SH->>SH: inject app-runtime.css and code-blue.css
    SH->>CV: load the built .os.ts bundle
    CV-->>SH: defineApp() publishes window.openStationApps[id]
    SH->>RT: load the one shared runtime
    RT-->>SH: registerApps() publishes openStationNativeWindows[id]<br/>and registers the title-bar and ⋯ chrome

    Note over SH,RT: 3 · Mount
    SH->>RT: invoke the render callback — resolved from the registry after the load
    RT->>RT: build the wp.os host, apply window theme, controls and slots
    RT->>RT: createSession per mount root, wire hide / show / resize / channels
    RT->>API: dispatch mount — state, args, params, viewport, X-WP-Nonce

    Note over API,LR: 4 · One round trip, all of it server-side
    API->>AP: permission — logged in, app exists, App::allows()
    AP->>AP: can_use() — manage_options AND Developer mode, both filterable
    AP->>AP: new State(defaults, incoming) — undeclared keys dropped, types coerced
    AP->>AP: run_mount(), then compute_data()
    AP->>LR: sources() → current_source() → read()
    LR->>LR: tail() the last 1 MB
    LR->>LR: parse() → entries filter → cap
    LR-->>AP: entries, sources, environment, scanned bytes
    AP-->>API: ok, state, html, data, effects<br/>html is empty — Code Blue has no server view
    API-->>RT: 200 JSON

    Note over RT,U: 5 · Paint
    RT->>CV: client.render() — view(state, data) through the kit's html tag
    CV-->>RT: diffed into the live root, nodes kept
    RT->>RT: finishRender() — os-prop-* props, lazy-load missing os-* components, reconcile os-poll timers
    RT->>RT: mounted() fires once, reading a finished DOM — then run effects
    RT-->>SH: the mount promise resolves
    SH->>U: loading overlay drops — the window is open

    Note over U,LR: Steady state. Range, search, sort, legend chips and row expansion are local actions:<br/>runLocal() reduces the state, repaints, finishRender() — every paint, server or local, ends in the same pass.<br/>Only Refresh, switching source and Clear log come back to the dispatch route — each exactly one request.

Loading

Three things the shape is meant to make obvious:

• The window's cost is paid on open, not on boot. Steps 5–9 happen once
  per tab. Every admin page that never opens Code Blue pays nothing for it.
• The client view loads before the runtime. That is the companion-script
  contract in native-windows.ts, and it is load-bearing here: the runtime's
  render callback calls clientAppFor( id ), which can only find what
  defineApp() already published.
• mount is the only request between clicking and reading the log. The
  old window needed the bundle plus /code-blue/sources plus
  /code-blue/entries.

The hardening pass — from experiment to the shipping framework

This started as an experiment; with two apps landed it is the framework we ship, and a full framework-vs-apps audit (every capability inventoried against what each app actually uses, plus a duplication sweep) drove a hardening pass. The rule it enforced: anything both apps re-implement is the framework's job, and an app carries only what makes it that app.

What moved into the framework:

• ViewContext grew the client services apps were hand-rolling: ctx.dispatch( …, { confirm } ) (the shell's confirm dialog on imperative dispatches — fixing a real hole where Move to Trash from the context menu ran unconfirmed while the same action's button confirmed), ctx.ui( factory ) + ctx.repaint() (client-only per-view state with an explicit re-render, replacing a WeakMap bag and a no-op reducer), ctx.fetch() (REST root + nonce + window spinner attribution supplied by the framework), and ctx.host (the typed shell surface).
• createPagedList() — the infinitely scrolled server-paginated list (accumulation, the one-page-per-scroll-gesture sentinel protocol, skeleton sizing, the short-list deadlock guard): ~120 lines every list window needed, now @openstation/app's. applySelection() (click/Ctrl/Shift selection math) beside it.
• refresh joined set as a built-in action — both apps had declared an empty PHP handler just to get "recompute data() and re-render".
• Os::page() (the paged-list envelope, hand-assembled five times) and Os::facts() (the drop-empty-facts idiom, four times) as pure statics — the framework core stays WordPress-free.
• formatBytes / formatDate exported from @openstation/app (five app-side date helpers and a third formatBytes copy deleted; the footprint's month callout no longer shifts a month in negative-UTC timezones).
• <os-stat> joined the kit (three surfaces drew the same stat tile with three stylesheets), and the data-tone → --os-app-tone tone contract moved into app-runtime.css scoped to .os-app — it had been document-scoped in Code Blue's sheet, retinting any data-tone element in the tab.
• mockViewContext() (src/app-runtime/testing.ts) — one blessed test context instead of four drifting stubs.
• Plus the couplings the audit flagged: the Agents pane strip is the kit's <os-tabs> (the hand-rolled tablist had no roving focus), the context-menu clamp is the shell's clampToViewport, the duplicated hover-card CSS is served once by the shared explorer sheet, and os-preserve is documented as the server-view morph's contract (client views guard imperative DOM with stamps, which is what actually protected it).

Still open, deliberately: tabs/channels/server-view surfaces have no consumer app yet — the next port should be chosen to exercise them.

Tests

npm run build, lint, typecheck, test:js (5,338), full PHPUnit (2,722), PHPCS clean. New: tests/phpunit/tests/appFramework.php (including Os::page/Os::facts and the built-in refresh), tests/phpunit/tests/codeBlue.php, tests/vitest/app-runtime-*.test.ts (one scans the component kit and fails if the runtime's event list falls behind; app-runtime-session pins the new context services; app-runtime-paged-list pins the scroll-gesture protocol itself, which the app suites never covered; app-runtime-format pins the formatters), apps/code-blue/code-blue.test.ts, the apps/my-wordpress/** suites, src/ui/components/os-histogram/os-histogram.test.ts, src/ui/components/os-stat/os-stat.test.ts.

Review round 2

@epeicher's four passes are addressed in 4bcc7ed:

• Built app bundles + TypeScript in the zip. assets/js/apps/ is gitignored on its own line (the /assets/js/*.js pattern only matches the top level), the two committed bundles are untracked, apps/**/*.ts is export-ignored, and bin/package.sh now walks apps/*/*.os.ts for the bundles it splices in — so the zip no longer depends on git-archive shipping them, and the unminified dev build stops shipping. Verified against a built zip: apps/code-blue/{code-blue.os.php,code-blue.css,log-reader.php} + assets/js/apps/code-blue.min.js, no .ts, no code-blue.js.
• Doc claims. client( $path ) now says client views are not third-party-usable yet and why (@openstation/app is a Vite alias into src/); the standalone section says the seam is real but has no shipped bootstrap and that Code Blue's __() keeps it on WordPress; the runtime figure above is corrected to 19 kB / 7.1 kB gzip.
• $os->toast( $message, $tone ). The parameter is gone rather than faked — the shell has no toast severity at all (wp.os.showToast() takes none), so implementing it would have meant a new <os-toast> variant, which is its own change.
• The default gate, the unescaped server view, state depth. New "The gate is the only authorization there is" section in docs/app-framework.md, with the state-depth limit pinned by a test. The gate default is left matching openstation_register_window()'s (any logged-in user) rather than changed unilaterally — a per-action capability declaration is the open design question, happy to add it if you'd rather it be structural than documented.
• Smaller items. The morph now morphs children before assigning a <select>'s value, and spends a duplicated os-key on first use; os-range-change joins the default-debounced events; the three dropped Code Blue tests are back; Code Blue's remember() cache is removed (the filters ran inside the callback and parse() bakes localized labels in — a log reader's product is freshness).

CI, both jobs red before: PHPUnit failed because the desktop-icon registry is process-scoped and the icons these tests register leaked into Tests_OpenStation_FilesStore's auto-place counts; Plugin Check failed because it recognises exactly four direct-access guard spellings and the framework's dual ABSPATH/OPENSTATION_STANDALONE guard is not one of them (23 files read as unguarded), and because it runs PHPCS under its own ruleset where phpcs.xml.dist's customEscapingFunctions do not exist.

Also, per @AllTerrainDeveloper: the app file is now <name>.os.php beside <name>.os.ts — one extension family per app.

Manual check

Developer mode on → open Code Blue. Range, search, sort, legend chips and row expansion respond with no request; Refresh / source switch / Clear log show the busy state once. Compare against the previous window: cards, legend row, toolbar are 1:1.

🤖 Generated with Claude Code

[epeicher]

Reviewed against trunk across four passes (security, architecture, backwards compatibility, performance). The bet is sound and the execution is disciplined: no confirmed exploitable vulnerability, boot cost does not regress (the runtime is registered but never eagerly enqueued), and the open path drops from 26.7 kB gzip to 12.9 kB. Registering through openstation_register_window() means live refresh works with no new payload key, which is the right call.

Before merge

1. Built app bundles are committed. git ls-files assets/js/apps/ returns code-blue.js and code-blue.min.js. The .gitignore pattern /assets/js/*.js only matches the top level, so the new subdirectory slipped through (assets/js/app-runtime.js is correctly ignored). This is the "assets/js is dist/" rule, and it will produce minified diffs in every future PR.

2. TypeScript source ships to wp.org. git archive HEAD apps/ includes code-blue.os.ts and code-blue.test.ts. .gitattributes export-ignores /src/ and /tests/ but nothing under apps/.

These two need fixing together: bin/package.sh's fileBase sed only matches single-quoted literals and cannot see the app targets' template-literal path (vite.config.js:704), so the zip currently depends on git-archive shipping the committed bundles. Teach package.sh about the app targets first, then gitignore the output. That also stops the unminified dev bundle shipping.

3. Two doc claims outrun the code. docs/app-framework.md:89 tells third parties to pass App::client( $path ), but @openstation/app is a Vite alias to src/app-runtime/client.ts, which imports ../i18n and ../ui/core/html. No package, no global export, so only server-view apps are third-party-usable today. Same for standalone mode: the seam is genuinely clean (verified zero WP calls in the core), but nothing boots it without WordPress in CI, and Code Blue calls __() nine times so it cannot run there. Also the "10 kB" runtime figure measures 19,319 bytes minified / 7,321 gzip.

4. $os->toast( $message, $tone ) silently drops the tone. src/app-runtime/index.ts:75 forwards only { message } and ToastOptions has no tone field, so every success renders as an error. Implement it or drop the parameter before the surface freezes. The session test asserts against a stub host, which is why this passed CI.

Worth deciding while the surface is still Experimental

• The default gate is any logged-in user. class-app.php:366-379: with no capabilities() or can(), allows() returns true for any authenticated user, and there is no per-action authorization. On a WooCommerce site every customer clears that, so an author who writes ->action( 'delete_all', ... ) without a gate has exposed it to all of them.
• An unescaped server view is more than XSS. The dispatch HTML path is deliberately not kses-filtered, and the runtime wires every os-action / os-poll it finds in returned markup, so a smuggled <span os-poll="250" os-action="destructive"> fires on a timer with no user interaction. Code Blue avoids this by rendering client-side, but the docs recommend server views for forms and settings without the warning.
• State typing stops at the top level. State::accept() coerces scalars only. An array() default accepts any JSON object, any depth, arbitrary keys, so toggle_item() and contains() can be handed a nested map. Worth a doc warning plus a test.

Smaller, non-blocking

• The morph assigns a <select> value before morphing in its options (syncFormValue at morph.ts:114, morphChildList at :115), so selecting a newly added option fails silently. Duplicate os-keys also re-match and re-move the same node with no warning.
• The default 250 ms debounce covers only four text events, and os-range-change is not one, so a slider in a server view queues one request per drag tick with no coalescing.
• Three Code Blue tests were dropped (entries filterable, entry cap keeping newest, level mapping). Those cover public filters the migration note says are unchanged.
• Code Blue's new remember() cache runs the entries / max_bytes / max_entries filters inside the callback, and keys localized labels without a locale, so on Redis or Memcached sites filter changes lag and admins in different locales can see each other's labels for up to 5 minutes.

[epeicher]

This proposal looks good to me @AllTerrainDeveloper. I like the idea of having one file of each type for the apps, instead of needing so many lines of code. I have left the output of a thorough review from my agents from different perspectives, as I wanted to analyze it deeply.

[epeicher]

After the latest commits, I passed the same agents with previous context using Fable and thoser are the comments. This is good to go!

Re-reviewed at a50bf071, verifying each item against the code rather than the commit messages. Everything holds: good to merge.

The four pre-merge fixes

• Bundles: /assets/js/apps/ gitignored; package.sh now walks apps/*/*.os.ts itself and mkdir -ps the archive dir, so the packaging interaction is handled. CI builds the views before PHPUnit.
• Zip: apps/**/*.ts export-ignore confirmed with git archive: only .os.php, log-reader.php and CSS ship, and only the .min.js is spliced in, so the dev bundle no longer ships either.
• Docs: client views marked "inside this repo only, for now"; standalone is now "the shape of the contract rather than a supported install mode"; bundle figure corrected to 19 kB.
• Toast tone: parameter removed from Effects::toast() / Os::toast(), with <os-notice tone> documented as the alternative. Clean.

The three decisions: made and documented rather than dodged. The new "The gate is the only authorization there is" section covers all three findings: the default-allow gate (justified as matching openstation_register_window()'s own default, with the instruction to declare a gate on every app), the os-poll trigger-injection escalation, and top-level-only state typing, now pinned by test_state_typing_is_top_level_only_for_array_keys.

Smaller items: both morph edges got real fixes (children morph before syncFormValue; a matched os-key is spent so duplicates insert fresh nodes), os-range-change joined the default debounce set, all three dropped Code Blue tests are back, and the log cache was removed outright with the freshness/filter/locale reasoning written into the code.

Two things beyond the review, both positive: the .os.php rename is complete with zero leftovers, and unifying the paint paths into one finishRender() fixed a real gap where a local action rendering a not-yet-loaded kit component left it inert. CI is green across PHP 8.3/8.4, Vitest, build, and Plugin Check, which settles the one item the first pass left unverified.