platform

# QORM

> QORM (Query · Observe · Render · Mutate) is an agent-native, cross-platform
> app platform. A QORM app
> is a small, language-neutral JSON bundle (manifest + scenes + actions + an
> optional Go middle-layer) that one pure-Go runtime renders live in a browser,
> snapshots to static HTML, compiles + ed25519-signs into a verifiable bundle,
> delivers over-the-air with rollback, packages as web / iOS / Android /
> desktop, and exposes to AI agents over MCP. No cgo — it cross-compiles
> everywhere.

Dual-consumer by design: every artifact is readable, installable, and writable by
a human developer, and discoverable, derivable, and self-verifiable by an AI
agent. Docs marked "auto-generated" are regenerated from the code and guarded by
tests — trust them over prose. Write apps in the format the runtime accepts
**today**: follow getting-started + the `examples/` + the auto-generated
references below (the runnable sources are the contract).

## Start here

- [README](README.md) — what QORM is; run / build / sign / package at a glance.
- [AGENTS.md](AGENTS.md) — a short orientation for AI agents working in this repo.
- [Getting started](docs/tutorials/getting-started.md) — install, first app, the run loop.
- [First scene](docs/tutorials/first-scene.md) · [First action](docs/tutorials/first-action.md) · [First component](docs/tutorials/first-component.md)
- [Responsive layout](docs/tutorials/responsive-layout.md) — `when`, `viewport.*`, `breakpoint.*`
- [Partial render](docs/runtime/partial-render.md) — server-side patch for scalar state updates

## The format (write apps in this)

- [examples/](examples) — the canonical runnable patterns: text via `text`, bind with `{{state.x}}`, `onPress` names an action in `actions/`, components in `qorm.json` with `{{prop.x}}`.
- [Project structure](docs/project-structure.md) — the app folder: `qorm.json` manifest, `scenes/`, `actions/`, and the optional `qorm.config.json` host-window block (size/title/resizable/chromeless/transparent → shaped windows).
- [Actions & state](api/actions.md) — the step vocabulary, `script` actions in the qscript language (`actions/*.qs` + the shared `actions/lib.qs`), scene `keys`/`swipes`, `computed`.
- [Expressions](docs/expressions.md) — the `{{ … }}` language: operators and every builtin (incl. the v2 array/string methods).
- [Widget catalog](api/widgets.md) — every node `type` the renderer accepts (auto-generated from `internal/render`, guarded by `TestWidgetCatalogInSync`).
- [Node & style props](api/props.md) — node schema + common style keys (~100; canvas filter/mask/snap/FLIP + game motion props).
- [QSS & canvas effects](docs/styles.md) — stylesheets + declarative canvas visual effects.
- [Animation](api/animation.md) — entrance, spring, FLIP, `fx` (burst…), `timeline` (path/cubic/onComplete/yoyo/stagger), transitionYoyo.
- [Capabilities](docs/platforms/capabilities.md) — built-in hardware/OS ops, callbacks, and platforms (auto-generated from `internal/capability`).

## Middle-layer — add your own native ops

- [User middle-layer](docs/platforms/native-middlelayer.md) — one `native/desktop.go`; register ops with `qormext.Register`, reach hardware with `qormext.Native`, push UI events with `qormext.Emit`. Compiles into the desktop binary AND the mobile/web WASM.
- [examples/middleware](examples/middleware) · [examples/native-ext](examples/native-ext)

## Platforms

- [Platform support matrix](docs/platforms/support-matrix.md) — what works where, at a glance.
- [Mobile](docs/platforms/mobile.md) · [Desktop](docs/platforms/desktop.md) · [Web](docs/platforms/web.md) · [Mini-app](docs/platforms/miniapp.md) (static export)

## Examples (runnable — the canonical patterns)

- [counter](examples/counter) · [todo](examples/todo) · [tasks](examples/tasks) — state + actions + lists
- [dashboard](examples/dashboard) — data-viz widgets · [gallery](examples/gallery) — the widget gallery
- [hardware](examples/hardware) · [desktop-hardware](examples/desktop-hardware) — the capability catalog exercised
- [uikit](examples/uikit) — JSON-defined custom components · [i18n](examples/i18n) — ICU messages, plurals, RTL
- [menus](examples/menus) — desktop system-bar / tray / right-click menus · [floating](examples/floating) — chromeless, custom-shape window
- [places](examples/places) — scroll surfaces: a `largetitle` that collapses into a sticky compact bar, a frosted `backdropBlur` panel, and a `sheet` dragged between snap points
- [canvas-fx](examples/canvas-fx) — canvas FX + full game motion: filter/mask/clip (`polygon`)/snap/FLIP, invert/sepia/tint, rotate/scale/flip/skew/`transformOrigin`, `zIndex` stacking, mix-blend extras (`plus-lighter`), pixelated images, `fx` (burst…), `timeline` (path/cubic/onComplete/yoyo), stagger
- [derived](examples/derived) — `computed` cart totals declared once, a `guard` that bounces an unauthenticated checkout to sign-in, and a `forEach` bulk edit
- [tetris](examples/tetris) · [g2048](examples/g2048) · [mario](examples/mario) · [raiden](examples/raiden) — qscript games with canvas `fx` and chiptune `playSound`/`playMusic` (Tetris/2048 keep FX local — flash/banner/outline, not whole-board shake; Mario is NES 1-1 at 2x with `tilemap` + board camera; Raiden shoot/explode)

## Drive it as an AI agent

- [Build with your AI](docs/build-with-ai.md) — the human's side: set up your agent, then have it scaffold/edit/verify QORM apps.
- [Human-AI collaboration](docs/collaboration.md) — a human and an agent on one live app over SSE + MCP, each seeing the other; the "AI edited" toast and `qorm_activity` close the loop.
- [integrations/](integrations) — drop-in MCP config + per-agent setup (Claude Code/Desktop, Cursor, Windsurf) + a QORM **skill**.
- [Agent skill](integrations/skill/SKILL.md) — runnable format, full MCP tool list, canvas FX, `board` camera + `tilemap`, game motion rules, self-verify.
- [MCP tools](docs/agent/mcp-tools.md) — the Model Context Protocol surface to read/edit a live app.
- [Verifying an app](docs/verification.md) — default CLI `qorm shot` / `qorm measure` / static `qorm check` use deterministic headless canvas; live MCP reads the active canvas graph or browser/WebView DOM, and `qorm_capture_canvas` returns the native host's last-presented PNG pixels.
- CLI: `qorm new | run | render | shot | measure | check | build | keygen | sign | verify | mcp | preview | package | docs | audit | updates | update | version` — full reference: [api/cli.md](api/cli.md).

## Trust & security

- [Bundle signing](docs/security/bundle-signing.md) — ed25519 verify-the-bundle delivery.
- [Permission model](docs/security/permission-model.md) · [Security model](docs/security/security-model.md)

## Commercial use

- [ops/TERMS.md](ops/TERMS.md) — the source is MIT; a good-faith Patreon membership covers commercial white-labeling (custom icon / removing the "Made with QORM" note).