Project shapeContract

App Anatomy

The files an Airglow app can define, how the platform discovers them, and which runtime each file runs in.

Four Optional Parts

Part	Path	Runtime	Use when
Manifest	`manifest.json`	Server + extension loader	Every app needs identity, metadata, permissions, and entry declarations.
Userscripts	`userscripts/*.ts`	Injected page USER_SCRIPT world	You need DOM access or page-level automation.
Startup	`startup.ts`	Offscreen sandbox iframe	You need to register redirects or platform capabilities once at extension start.
UI	`ui/App.tsx`	Sandbox iframe inside app-shell	You need a React app surface separate from the target website.
Server	`server/*.ts`	Next.js serverless function	You need server secrets, platform keys, OAuth exchange, or paid API protection.

Manifest Fields

Field	Required	Meaning
`id`	Yes	Stable app id. Used for routing, storage namespace, userScript world id, and log labels.
`name`	Yes	Display name in dashboards and app lists.
`version`	Yes	App version shown to the platform. This is separate from SDK contract versioning.
`description`	Yes	Human-readable summary.
`tags`	No	Search/discovery metadata.
`userscripts`	No	Array of `{ file, matches }` entries registered through Chrome userScripts.
`startup`	No	Single startup script path, usually `startup.ts`.
`secrets`	No	Client-visible settings exposed through the extension secrets/settings UI and read by `airglow.storage.get`.
`host_permissions`	No	Chrome match patterns required for `airglow.fetch(..., { includeCookies: true })`.

Manifest examplejson

{
  "id": "hn-tagger",
  "name": "HN Tagger",
  "version": "0.1.0",
  "description": "Tags Hacker News stories from a userscript",
  "userscripts": [
    {
      "file": "userscripts/hn.ts",
      "matches": ["*://news.ycombinator.com/*"]
    }
  ],
  "secrets": {
    "ANTHROPIC_API_KEY": { "label": "Anthropic API Key" }
  }
}

How Apps Load

1Server serves manifestsGET /api/apps/manifests returns known apps from the configured APPS_DIR.
2Extension registers userscriptsThe background loader fetches bundled script code, prepends SDK code, and registers each file in an app-specific USER_SCRIPT world.
3Extension runs startupStartup code runs in a sandbox iframe because MV3 service workers cannot eval app code.
4Extension shows UILocal debug can use the SDK-injected /api/apps/:appId/ui route; production should load remote UI bundles into an extension-owned sandbox.
5SDK calls route through backgroundEvery airglow.* call includes the app id and is validated before touching storage, fetch, identity, platform, or RPC.