# Building a WidgetStore app — guide for coding agents

You are helping someone build an app for the WidgetStore app platform (https://widgetstore.net/apps).
Read this whole file before writing code. Human tutorial: https://widgetstore.net/docs/ai/first-app

## What an app is

- A **static web app**: HTML / JS / CSS / images / fonts / wasm. No server code (phase 1).
- Packaged as a zip (≤ 10 MB, ≤ 300 files, each file ≤ 5 MB) with `widgetstore.app.json` and the entry HTML at the root (or inside one top folder).
- Hosted by WidgetStore on a separate origin, inside a sandbox **without** same-origin: no cookies, no `localStorage` / `IndexedDB` that persists, no access to WidgetStore's pages. Everything platform-related goes through the SDK.
- Allowed file types: html, htm, js, mjs, css, json, map, txt, md, svg, png, jpg, jpeg, gif, webp, avif, ico, woff, woff2, ttf, otf, mp3, ogg, wav, m4a, mp4, webm, wasm, csv, xml, webmanifest.

## Manifest: `widgetstore.app.json`

```json
{
  "name": "My App",
  "version": "1.0.0",
  "entry": "index.html",
  "icon": "icon.svg",
  "description": "One or two sentences.",
  "permissions": ["login", "sparks", "ai", "storage", "share"],
  "network": ["api.example.com"],
  "screenshots": ["shots/1.png"]
}
```

- `version`: semver (`1.2.3`). Bump it on every publish.
- `permissions`: only what you use. `sparks` and `ai` calls fail with `permission_not_declared` if missing.
- `network`: external https hosts your code calls with `fetch` / loads images or scripts from (max 5). Everything else is blocked by CSP. Not allowed: widgetstore.net, workers.dev, IP addresses.
- `icon`: png / svg / webp / jpg, square, ≤ 512 KB. `id` is added by the CLI after the first publish — keep it.

## SDK

```html
<script src="https://widgetstore.net/apps/sdk/v1.js"></script>
```

Types: https://widgetstore.net/apps/sdk/v1.d.ts. Global `ws`:

```js
const ctx = await ws.ready();          // { app, lang: 'zh-CN'|'zh-TW'|'en'|'ja'|'ko', theme: 'light'|'dark', platform, preview }
ws.on('theme', (t) => …);              // the SDK also sets <html data-ws-theme="dark|light">
const { user, idToken } = await ws.login();   // user = { sub, name, avatar }; sub is per-app (pairwise)
await ws.getUser();                    // null if not signed in (no prompt)
await ws.sparks.balance();
await ws.sparks.charge({ amount: 30, reason: 'Unlock all colors' });   // integer 1–5000; user confirms
const r = await ws.ai.run({ prompt, system, history, json, maxTokens }); // r.text, r.credits (charged to the user)
await ws.storage.set('key', value); await ws.storage.get('key'); await ws.storage.remove('key'); await ws.storage.keys();
await ws.share({ title, text, url }); await ws.openUrl('https://…'); await ws.toast('Saved');
```

Errors are `Error` objects with `code`: `not_in_host`, `cancelled` (user said no — not an error to show loudly), `login_required`, `insufficient_sparks`, `daily_limit`, `ai_daily_limit`, `permission_not_declared`, `storage_full`, `value_too_large`, `invalid_key`, `version_outdated` (ask the user to reload), `timeout`.

Limits: storage keys `^[A-Za-z0-9._:-]{1,100}$`, values JSON ≤ 16 KB, ≤ 200 keys and 512 KB per user per app. AI ≤ 100 calls per user per app per day. Charges ≤ 20,000 Sparks per user per app per day.

## Rules (checked automatically and by human review)

1. Support the user's language from `ctx.lang` when you can (zh-CN, zh-TW, en, ja, ko). If you ship one language, say so in the description.
2. Follow `ctx.theme` (light / dark) — the platform UI around your app follows it.
3. **Never** ask for passwords, card numbers, verification codes or WidgetStore credentials. Don't imitate WidgetStore's or another brand's UI. Password fields get extra review.
4. Before calling `ws.sparks.charge`, show clearly what the user gets. Never charge in a loop or on page load.
5. No crypto mining, no tracking scripts, no redirects to other sites without `ws.openUrl`.
6. If you store user data with `ws.storage` or send it to a `network` host, the app needs a privacy policy URL (set in the developer center).
7. Don't fake data: no made-up reviews, users or statistics. Sample content must be labelled as sample.

## Develop

```bash
widgetstore app init my-app --template blank|sparks|ai
cd my-app && widgetstore app dev          # http://127.0.0.1:5178/ — simulated user, Sparks and AI, same sandbox
```

No desktop app? Serve the folder with any static server and open it inside an iframe that implements the protocol in `v1.js` (messages `{ ws: "wsapp/1", id, method, params }`), or just publish and use the private preview link.

## Publish

```bash
widgetstore app publish --slug my-app      # first time (creates the app; slug = URL name, 3–32 chars, a-z 0-9 -)
widgetstore app publish --notes "What changed"
```

Without the CLI, use the WidgetStore MCP server (https://widgetstore.net/mcp, scope `write:apps`):
`apps_create` → `apps_publish` (text files up to 48 KB) or `apps_upload_url` (then `curl -X PUT --data-binary @app.zip -H "Content-Type: application/zip" <url>`) → `apps_status` → `apps_release` (canary `pct` 1–99, roll back by releasing an older approved version).

Every upload is an immutable version. Automatic scan → human review for the first listing, new permissions / network hosts or password fields → live. Users always get the live version automatically.

## Money

The developer gets 50% of the Sparks users pay in the app (the part paid with purchased Sparks is withdrawable after a 30-day hold; payouts are reviewed and paid manually from 500,000 Sparks ≈ $50). AI calls are charged to the user at cost-based prices and are not shared.
