summer-engine 3.6.0 → 3.8.0

package/library/skills/summer-apps/minimal-app.md

@@ -0,0 +1,183 @@
+# A complete minimal Summer App
+
+A working code app: shared notes for a playtest. Copy it, rename things, then grow it.
+It shows every piece an app needs: the manifest, loading the SDK and kit, waiting for
+the host, shared data (list, put, live changes), who changed a row (person or agent),
+an edit flow (dialog + form with setValues), status badges, an error with Try again, the
+page declaration, an agent event, an agent tool and frame-move state.
+
+Publish it with `summer_app_publish {appId, dir, manifest, note}` where `dir` holds
+`index.html` and `app.js`, or pass the same two as `files`. The page, sections, inputs,
+table, notice and empty text are kit components (`summer_app_guide` section `kit`, or
+`/summer-ui/v1/catalog.json` on the app host); no app CSS is needed.
+
+## The manifest (send it as `manifest`)
+
+```json
+{
+  "name": "Playtest notes",
+  "purpose": "Tester notes per level. Notes live in this app's shared data.",
+  "permissions": ["data"],
+  "collections": {
+    "notes": {
+      "description": "One remark from a playtest",
+      "fields": {
+        "text": { "type": "string", "required": true, "description": "What the tester said" },
+        "level": { "type": "string", "description": "Level name, e.g. bridge" },
+        "status": { "type": "string", "description": "open or fixed" },
+        "author": { "type": "string", "description": "Who added it" }
+      }
+    }
+  },
+  "agentEvents": ["note.added"],
+  "agentTools": [
+    {
+      "name": "add_note",
+      "description": "Add a playtest note",
+      "input": {
+        "type": "object",
+        "properties": { "text": { "type": "string" }, "level": { "type": "string" } },
+        "required": ["text"]
+      }
+    }
+  ]
+}
+```
+
+## index.html
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Playtest notes</title>
+<!-- Both are ES modules on the app's own host (apps.summerengine.app). Root paths, type="module". -->
+<script type="module" src="/summer-sdk/v1.js"></script>
+<script type="module" src="/summer-ui/v1/ui.js"></script>
+</head>
+<body>
+<summer-page heading="Playtest notes" purpose="Tester notes per level, shared with your team and your agent.">
+  <summer-button slot="actions" id="add" variant="primary" icon="plus">Add note</summer-button>
+  <summer-section heading="Notes">
+    <summer-notice id="error" tone="error" action="Try again" action-icon="refresh-cw" hidden></summer-notice>
+    <summer-table id="table" row-key="id" sortable clickable loading
+      empty-text="No notes yet. Add the first one, or ask your agent to add the testers' notes."></summer-table>
+  </summer-section>
+  <summer-dialog id="dialog" heading="Note" description="Shared with your team and your agent.">
+    <summer-form id="form" submit-label="Save note">
+      <summer-text-input label="Note" name="text" multiline required></summer-text-input>
+      <summer-grid columns="2">
+        <summer-text-input label="Level" name="level" placeholder="bridge"></summer-text-input>
+        <summer-select label="Status" name="status" options='[{"value":"open","label":"Open"},{"value":"fixed","label":"Fixed"}]'></summer-select>
+      </summer-grid>
+    </summer-form>
+  </summer-dialog>
+</summer-page>
+<!-- app.js runs after the SDK module (module scripts run in order). -->
+<script type="module" src="app.js"></script>
+</body>
+</html>
+```
+
+## app.js
+
+```js
+const notes = summer.data.collection("notes");
+const info = await summer.ready;   // { viewer: { userId, name }, params, restored, ... }
+const $ = (id) => document.getElementById(id);
+const table = $("table"), dialog = $("dialog"), form = $("form"), error = $("error");
+let editing = null;                 // the note id being edited, or null for a new one
+
+table.columns = [
+  { key: "text", label: "Note", priority: "primary" },
+  { key: "level", label: "Level" },
+  { key: "status", label: "Status", badges: { open: "warn", fixed: "ok" } },   // one badge tone per value
+  { key: "by", label: "By", type: "muted" },
+];
+
+async function load() {
+  table.setAttribute("loading", "");
+  try {
+    const page = await notes.list({ limit: 500 });   // removed notes are never listed
+    table.rows = page.records.map((r) => ({
+      id: r.recordId,
+      ...r.data,
+      // createdBy: who made the row ({ userId, kind: "person" | "agent" | "seed", agent?, via? });
+      // later edits do not change it (actor is the last writer). Seed rows have no author.
+      by: r.createdBy?.kind === "agent" ? `${r.createdBy.agent ?? "Agent"} (agent)` : r.data.author ?? "",
+    }));
+    error.hidden = true;
+  } catch (e) {
+    error.setAttribute("text", `Could not load notes: ${e.message}`);
+    error.hidden = false;
+  } finally {
+    table.removeAttribute("loading");
+  }
+}
+error.addEventListener("action", load);   // the notice's "Try again" button
+
+function openEditor(row) {
+  editing = row?.id ?? null;
+  form.setValues(row ?? { text: "", level: "", status: "open" });
+  dialog.show();
+}
+$("add").addEventListener("click", () => openEditor(null));
+table.addEventListener("summer-row", (event) => openEditor(event.detail.row));   // click a row to edit
+
+form.addEventListener("submit", async (event) => {
+  const { text, level, status } = event.detail.values;   // numbers come as numbers, empty as null
+  form.setAttribute("busy", "");
+  try {
+    const id = editing ?? crypto.randomUUID();
+    await notes.put(id, { text, level: level ?? "", status: status ?? "open", author: info.viewer.name ?? "someone" });
+    if (!editing) await summer.agent.send("note.added", { id, text, level });   // name is in manifest.agentEvents
+    dialog.close();
+    summerUI.toast("Note saved");
+  } catch (e) {
+    form.setAttribute("error", e.message);
+  } finally {
+    form.removeAttribute("busy");
+  }
+});
+
+// Live: every change by a teammate or an agent arrives as { revision, actor, ops } (or { reset: true }).
+notes.subscribe(() => load());
+
+// Agent tool: summer_app_call { tool: "add_note", input: { text, level } } runs this while the app is open.
+// Its writes are recorded as the calling agent's (actor.kind "agent", via "agent-tool").
+summer.agent.tool("add_note", async ({ text, level }, { agent }) => {
+  const id = crypto.randomUUID();
+  await notes.put(id, { text, level: level ?? "", status: "open", author: agent });
+  return { id };
+});
+
+// What agents can read and use with summer_app_page.
+summer.page.declare({ actions: [{ id: "add", label: "Add note", run: () => openEditor(null) }] });
+
+// Frame moves: Studio moves an idle app to a fresh frame every few minutes. Shared data survives on
+// its own; keep only UI state, such as an open editor.
+summer.app.onSnapshot(() => (dialog.hasAttribute("open") ? { editing, values: form.values } : null));
+if (info.restored?.values) {
+  editing = info.restored.editing;
+  form.setValues(info.restored.values);
+  dialog.show();
+}
+
+load();
+```
+
+Playing sound with Web Audio instead of `<audio>`? Wrap it so the frame is not moved
+mid-sound: `summer.app.busy(true)` when it starts, `summer.app.busy(false)` in the
+source's `onended`.
+
+## The agent side of the same app
+
+```json
+{ "appId": "<id>", "ops": [{ "op": "put", "collection": "notes", "recordId": "n-1", "data": { "text": "Boss fight too long", "level": "boss", "status": "open", "author": "agent" } }] }
+```
+
+That is a `summer_app_data` write: it works with the app closed, and the open app shows it
+through `notes.subscribe`. `summer_app_tools` and `summer_app_data` reads return the
+`collections` above, so an agent knows the record shape.

package/library/skills/summer-apps/resource.yaml

@@ -0,0 +1,36 @@
+id: skill/summer-apps
+kind: skill
+version: 0.1.0
+summary: "Build a Summer App, a team tool inside Summer Studio (balance table, quest editor, tracker, pick grid): build loop, Layout vs code, data as API, agent tools."
+use_when:
+  - the person asks for a tool for their team ("build us a loot balance tool", "a board to track creatures")
+  - the person needs a UI to decide, rate or edit something they will come back to
+  - reading or changing the data of an existing Summer App
+  - calling an app's agent tools or waiting for what an app sends
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+    - agent-workflow
+  modalities:
+    - ui
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps-design
+  tools:
+    - tool/app-guide
+    - tool/app-create
+    - tool/app-publish
+    - tool/app-events
+    - tool/app-data
+    - tool/app-call
+    - tool/app-dock
+source: official
+license: MIT
+status: preview
+recommended: true

package/library/skills/summer-apps/sdk-reference.md

@@ -0,0 +1,135 @@
+# Summer Apps SDK quick reference
+
+`window.summer`, loaded with `<script type="module" src="/summer-sdk/v1.js">` (the app's own
+host, apps.summerengine.app). The UI kit is `<script type="module" src="/summer-ui/v1/ui.js">`
+(stylesheet alone: `/summer-ui/v1/ui.css`). Use `type="module"` (a classic script still works but warns); other paths do not work. Calling `summer.data.list(name)` and the like rejects with `invalid` and says to use `summer.data.collection(name)`.
+
+The app runs in a sandboxed frame on that host:
+`sandbox="allow-scripts allow-forms allow-popups allow-modals allow-downloads"`, never
+`allow-same-origin`. So it is an opaque origin (no cookies, no `localStorage`), with no network
+unless the workspace allows a domain; the kit and SDK are served with CORS so the module
+scripts load. It only works inside Summer Studio. To preview, publish to a Scratch app and open
+it there (`/studio/apps/<appId>`). There is no offline or local host; do not build one or mock
+the SDK. Opening `index.html` on its own never connects, so `summer.ready` waits forever.
+
+Every call returns a promise and runs as the person using the app. Failures reject with
+`SummerError { code, message }`. Methods need the manifest permission in brackets.
+
+## Start
+
+| Call | Returns |
+|---|---|
+| `await summer.ready` | `{ app: { id, name, version, surface, format }, viewer: { userId, name }, permissions: string[], params: { [k]: string }, theme: "light"\|"dark", restored?: any }` |
+| `summer.app.viewer()` | `{ userId, name, image, role: "owner"\|"admin"\|"member", canManage, spentTodayMicro, dailyCapMicro }` |
+| `summer.app.info({ params })` | `{ app, version, manifest, params }` |
+| `summer.app.setTitle(title)`, `summer.app.notify(text)`, `summer.app.needsYou(count)`, `summer.app.open("/studio/...")` | `void` |
+| `summer.app.theme()` / `summer.app.onTheme(fn)` | `"light"\|"dark"` / stop function |
+| `summer.app.onSnapshot(() => state)` | stop function. `state` (JSON, up to 256 KB) comes back as `(await summer.ready).restored` after Studio moves the app to a fresh frame. |
+| `summer.app.busy(on)` | `void`. Wrap Web Audio playback in `busy(true)` / `busy(false)`; `<audio>` and `<video>` count on their own. |
+
+Use `(await summer.ready).viewer` for who is using the app; `summer.app.viewer()` is the same
+person plus role and spend. The kit applies Studio's light or dark theme by itself
+(`html.dark`): apps never toggle it. `theme()` / `onTheme` are only for your own drawing (canvas).
+
+## Shared data [data]
+
+There is no `summer.data.list(name)`. Always go through `summer.data.collection(name)`.
+
+```js
+const notes = summer.data.collection("notes");   // name: lowercase a-z 0-9 _ . - (max 48)
+```
+
+| Call | Returns |
+|---|---|
+| `notes.list({ limit = 200, after })` | `{ revision, records: Record[], next: string\|null, collections: [{ name, count }] }`. Removed records are never listed. Pass `next` as `after` for the next page (max 500 per page). |
+| `notes.get(id)` | `Record`, or `null` (also for a removed record) |
+| `notes.put(id, data, { ifRevision })` | `Write` (creates or replaces) |
+| `notes.patch(id, partial, { ifRevision })` | `Write` (shallow merge; `null` removes a key; creates if missing) |
+| `notes.remove(id, { ifRevision })` | `Write` |
+| `notes.subscribe((change) => …)` | stop function |
+| `summer.data.subscribe((change) => …)` | every collection |
+| `summer.data.commands({ requestId, baseRevision, ops })` | `Write`: up to 100 ops in one revision |
+
+```ts
+Record = { collection, recordId, data, revision, actor, createdBy, createdAt, updatedAt, deleted }
+Write  = { revision, operation: { revision, requestId, actor, ops, createdAt }, records: Record[], replayed }
+change = { revision, actor, ops: Op[] } | { revision, reset: true }      // on reset, list again
+actor  = { userId, kind: "person" | "agent" | "seed", agent?: "claude-code" | ..., via?: "agent-tool" }
+Op     = { op: "put", collection, recordId, data, ifRevision? }
+       | { op: "patch", collection, recordId, patch, ifRevision? }
+       | { op: "remove", collection, recordId, ifRevision? }
+```
+
+`ifRevision: n` applies only if the record is still at revision `n` (`0`: only if it does not
+exist); otherwise the call rejects with `conflict`. Record ids: letters, digits, `_ . : -`
+(max 128). Records are JSON up to 64 KB, 10,000 per collection, 50 collections.
+
+### Who changed it
+
+`actor.userId` is the account the write ran as, the same id as `ready.viewer.userId` and
+`app.viewer().userId`. `kind: "agent"` marks writes an agent made with `summer_app_data`, and
+writes your own code made while running an agent tool for `summer_app_call` (those also have
+`via: "agent-tool"`). Show agent-made rows (a small "by agent" label) so people know.
+
+`actor` is the last writer. `createdBy` (same shape) is who created the record and does not
+change on later edits, so take the "by agent" label from `createdBy.kind === "agent"`: it
+survives a person's edit. `kind: "seed"` is starter data an agent wrote for the team
+(`summer_app_data` with `as: "seed"`): show no author for it.
+
+## Agents
+
+| Call | Returns |
+|---|---|
+| `summer.agent.send(name, payload)` | `{ seq }`. `name` must be in `manifest.agentEvents`. Agents read it with `summer_app_events`. |
+| `summer.agent.tool(name, async (input, { agent }) => result)` | stop function. `name` must be in `manifest.agentTools`; `agent` is the calling agent's name. Data writes the handler makes are recorded as that agent's (`via: "agent-tool"`). `summer_app_call` runs it; return JSON (under 100 KB); a throw becomes `tool_failed`. |
+| `summer.agent.onMessage((message) => …)` | stop function |
+| `summer.page.declare({ fields, actions })` | promise. `fields: [{ id, label, kind: "text"\|"long-text"\|"number"\|"toggle"\|"choice", value, options?: [{ value, label }] (for choice), max?, hint?, set(value) }]`, `actions: [{ id, label, description?, critical?, run() }]`. Call it again when values change. Critical actions are pressed only by the person. |
+
+## Assets, generation, AI
+
+| Call | Permission | Returns |
+|---|---|---|
+| `summer.assets.search(q, { filters, limit })` | assets:read | matching assets |
+| `summer.assets.get(id)` | assets:read | one asset (`fileUrl`/`url`, `kind`, `title`, ...) |
+| `summer.assets.upload({ name, contentType, base64 })` | assets:write | the new asset |
+| `summer.assets.saveToLibrary(id, { name })` | assets:write | the saved asset |
+| `summer.generate.image({ prompt })`, `.sfx({ prompt, durationSeconds })`, `.sfxChoices({ prompt })`, `.music({ prompt, durationSeconds })`, `.voice({ text, voiceId })` | generate | the result with its asset |
+| `summer.generate.model3d({ prompt })`, `.video({ prompt })`, then `summer.generate.job(jobId)` | generate | a job, then its status |
+| `summer.ai.complete({ prompt, system, json })` | ai | the model's answer |
+
+Paid calls spend the viewer's credits; `spend_cap_reached` when the app's daily cap is hit.
+
+## Team, projects, analytics
+
+| Call | Permission |
+|---|---|
+| `summer.team.members()` → `{ members: [{ userId, role, name, image }] }` (never emails) | team:read |
+| `summer.team.presence()` → `{ presence: [{ userId, name, image, surface, seenAt }] }` | none |
+| `summer.projects.list()`, `summer.projects.get(id)` | projects:read |
+| `summer.grow.portfolio({ range: 7\|28\|90 })` (totals and per-game rows each carry `previous`: the same-length window before, or null), `summer.grow.game(id)`, `summer.grow.earnings()` | grow:read |
+
+## Engine [engine:read / engine:write]
+
+| Call | Notes |
+|---|---|
+| `summer.engine.status()` | Is an engine connected for this person |
+| `summer.engine.readFile(path)` / `writeFile(path, content)` | Only `manifest.engineFiles` paths (and `res://addons/<plugin>/`) |
+| `summer.engine.ops([{ op: "AddNode", ... }])` | App op allowlist only; values are Godot strings (`"Vector3(0, 10, 0)"`) |
+| `summer.engine.play(scene)`, `stop()`, `screenshot("viewport"\|"game")`, `state(kind)` | |
+| `summer.engine.onEvent(fn)`, `summer.engine.plugin.send(msg)`, `summer.engine.plugin.onMessage(fn)` | |
+
+`engine_offline`: no Summer Engine connected; show an "Open in Summer Engine" hint.
+
+## Kit values
+
+`<summer-form>` gives its fields' values by `name` (fields anywhere inside it count, also
+inside `summer-grid`); `form.values = {...}` or `form.setValues({...})` loads a record into it
+for editing. `<summer-text-input type="number">` and `<summer-slider>` give numbers in form
+values and change events (an empty number field gives `null`); the input's `.value` property
+stays text. A `<summer-toggle>` is a boolean.
+
+## Errors
+
+`permission_missing` (add it to the manifest), `invalid` (arguments; the message says which),
+`unknown_method`, `conflict`, `rate_limited` (600 calls a minute, 60 paid), `spend_cap_reached`,
+`engine_offline`, `not_implemented`, `unavailable`.

package/library/skills/summer-apps-design/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: summer-apps-design
+description: "How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: tools
+user-invocable: false
+---
+
+# Summer Apps design
+
+A Summer App is a tool a game team uses every day inside Summer Studio. It should
+feel like a calm, precise studio instrument around colourful game content. The
+chrome is ink on paper; colour comes from the game (art, renders, waveforms) and
+from data that means something. You have freedom inside the app. Use it for the
+task, not for decoration.
+
+## The catalog is the API
+
+The kit ships `summer-ui/v1/catalog.json` next to `ui.js` on the kit origin (the
+summer-apps skill says how to load the kit). It lists every component's
+attributes with value shapes, events with their `detail`, slots, methods, a working
+example, the icon names and the tokens. **Read the entry before you use a
+component** and copy its example. Never guess an attribute.
+
+- JSON attributes take a JSON string, or set the same-named property:
+  `table.rows = rows`. Prefer properties for data.
+- Events bubble out of the components; read `event.detail`.
+- Icons: only names in `icons.names` (lucide: `plus`, `check`, `pencil`,
+  `trash-2`, `search`, `sparkles`, `download`, `ellipsis`, ...). Never draw SVG.
+- Colours: only the tokens in `tokens` (`var(--se-text)`, ...). No hex.
+
+## Do this
+
+1. Write one line: what the person came to do, and the one action that finishes
+   it. That action is the primary button.
+2. Build the page from the recipe below. Every part is a kit component; write your
+   own CSS only for layout glue (a grid, a gap), from tokens, under 30 lines.
+3. Read real data through the SDK. No lorem ipsum, no invented numbers.
+4. Wire `loading`, empty and error for every data component.
+5. Run the checklist. Look at light and dark, 390px and 1440px.
+
+## Page recipe
+
+```html
+<summer-page heading="Playtest results" purpose="How each level played in the latest playtest. Notes are shared with your team and your agent.">
+  <summer-avatar-stack slot="actions" people='[{"name":"Mia"},{"name":"Tom"}]'></summer-avatar-stack>
+  <span slot="actions" class="summer-meta">Playtest 12 Oct</span>
+  <summer-button slot="actions" variant="primary" icon="plus">Add note</summer-button>
+
+  <summer-stats loading>…3-5 summer-stat…</summer-stats>
+  <summer-chart heading="Where players stop" loading …></summer-chart>
+  <summer-section heading="Levels">
+    <summer-select slot="aside" label="Sort" options='…'></summer-select>
+    <summer-table loading …></summer-table>
+  </summer-section>
+</summer-page>
+```
+
+- `summer-page` gives the canvas, width (1280px; forms 640px), padding and spacing,
+  and the header. The purpose line says what the tool does and where data goes.
+  Header actions, in order: avatars, one meta (`.summer-meta` or
+  `summer-progress`), secondary buttons, the primary.
+- One `summer-section` per part, with a short noun heading. Extras for the title row
+  (a select, a count) go in `slot="aside"`; a select there turns compact by itself.
+- A chart gets its own `heading` (its legend then sits in the title row). A chart
+  without a heading as the first thing in a section moves its legend into the
+  section's title row.
+- A page with one part needs no section heading and no card around it.
+- Tables and lists are always framed; charts never. Do not set `frame="false"` on
+  a page.
+
+## Pick the component
+
+| Job | Use (exact names; shapes in the catalog) |
+| --- | --- |
+| Key numbers | `summer-stats` > 3-5 `summer-stat label value delta hint tone`. Delta is text like "+12 this week"; the kit colours the number |
+| A comparison or trend | `summer-chart kind x y heading highlight reference`. `y` is a JSON array of keys; `highlight` `{key, above, below, equals, tone, label, otherLabel}` (`key` tests another field, e.g. colour `lines` bars where `redo` is above 3; `equals` takes a value or a list); counts get whole-number gridlines by themselves; `reference` `{value, label, tone}`. One question per chart |
+| Records you scan, sort, edit | `summer-table columns rows row-key`. Column `{key, label, format, digits, type: bar/badge/muted, over, tone, badges, priority: "secondary", thumb, editable, badge, badgeTone, width, minWidth, wrap}`. Text columns wrap to 2 lines by themselves; `width` takes pixels, a CSS length, "narrow" or "wide" (e.g. `"wide"` for a notes column). `badges` maps each value to a tone or `{tone, label}` for a status column (`{"draft": "quiet", "review": {"tone": "info", "label": "In review"}, "done": "ok"}`; unlabelled values show in sentence case); `badge` names a row key shown as a small badge inside a cell (e.g. "+3:01" over target). Under 640px badge columns fold under the name, and rows stack only if the columns still do not fit. `clickable` gives `summer-row`; `selectable="single"` or `"multi"` gives `summer-select-rows` |
+| Unsaved table edits | `summer-save-bar count save-label` (`save` and `discard` events; then `table.commit()` or `table.discard()`) |
+| Notes, tasks, comments | `summer-list items checkable action menu`. Item `{id, title, meta, checked, badge: {text, tone}, action}`; `action` `{id, label, icon}` is the one quiet button per row; `menu` items `{id, label, icon, tone: "danger"}`; events `summer-check`, `summer-action`, `summer-item` |
+| Pipeline stages | `summer-board` > `summer-lane heading lane-id add-label` > `summer-board-card heading card-id art meta person comments done`; `summer-move` event |
+| Pick between versions | `summer-choice-grid items` (`layout="row" heading meta` for one row per need). Item `{id, label, src, kind}` |
+| Filters above a list | `summer-toolbar` > `summer-search`, `summer-segmented options value` (`{value, label, count}`; scrolls inside its own track when it does not fit), `summer-select` in `slot="end"` (compact by itself) |
+| Add or edit something | `summer-dialog heading description` > `summer-form submit-label` > named inputs |
+| Inputs | `summer-text-input name label hint required multiline`, `summer-select name label options`, `summer-slider`, `summer-toggle`. Every field sends `input` and `change` with `event.detail.value` |
+| Media | `summer-audio`, `summer-video`, `summer-image aspect`, `summer-model-viewer`. Never `<audio controls>` or `<video controls>` |
+| A repeated object | `summer-card variant="object" media selected` |
+| Status in words | `summer-badge tone` (ok, warn, bad, info, quiet, count) |
+| Buttons | `summer-button variant icon size`, `summer-icon-button icon label` |
+| Messages | `summer-notice tone text action` in place (`action="Try again"` adds a button; listen for `action`); `summerUI.toast(text)` after an action |
+| Nothing yet | `summer-empty-state heading body` with one button inside |
+
+If you play Web Audio yourself, call `summer.app.busy(true)` while it plays and
+`busy(false)` after.
+
+## Patterns
+
+**Dashboard (numbers, chart, table).** Stats, then one chart answering the main
+question with the problem bars highlighted and a reference line for the target,
+then the table with a bar column for the value that matters. Columns a phone can do
+without get `priority: "secondary"`.
+
+**Badges in tables.** Two kinds, one rule each:
+- A workflow status column (draft, in review, done, needs art) shows every value as
+  a badge with `badges`. Neutral steps are `quiet`, work in progress `info`, done
+  `ok`; only values that need someone to act get `warn` or `bad`.
+- A health column (balance, over target, errors) shows a badge only on the rows
+  that need attention and stays empty on the rest. Never "OK" on every row.
+
+**Edit flow.** A row click (`summer-row`) or the header's primary opens a
+`summer-dialog` holding a `summer-form`. For an edit, call
+`form.setValues(record)` before `dialog.show()`; for a new item, show it empty.
+Listen for `submit` (`detail.values`; number fields give numbers, empty gives
+null); set `busy` while saving and `error` if it fails; close the dialog on success and toast the result ("Note saved"). The rule is one
+primary per region: the page header, an open dialog, a form that is the whole page,
+and the save bar are separate regions. A page whose job is the form puts Save in the
+form and no primary in the header.
+
+**Empty page and the header.** One primary on screen. When the whole page is empty,
+the empty state holds the primary ("Add note" or "Ask your agent") and the header
+shows no primary until there is data. When only one section is empty, its
+empty-state button is `secondary` and the header keeps its primary.
+
+**List with row actions.** `summer-list` with `checkable` for done or fixed, one
+`action` for the most common step (`{id: "fix", label: "Mark fixed", icon:
+"check"}`: a quiet button that shows on hover and on touch), and `menu` for the rest
+(Edit, Copy, Delete with `tone: "danger"`). Never a bordered button on every row.
+Delete asks first in a `summer-dialog` with `summer-form destructive`.
+
+**Data your agent fills in.** When the app waits on an agent (an import, an
+analysis), the empty state says what is missing and offers the request:
+`summer-empty-state heading="No playtest data yet" body="Your agent can import
+last night's playtest."` with a `summer-button icon="sparkles"` "Ask your agent"
+(primary or secondary per the empty-page rule above). On click call `summer.agent.send("playtest.import", {})`, swap the button
+for `summer-notice tone="info"` "Your agent was asked. This fills in when it
+answers.", and subscribe so rows appear live:
+`summer.data.collection("levels").subscribe(render)` (there is no
+`summer.data.list(name)`).
+
+**Who added it, who changed it.** People and agents edit the same data. Every
+record carries `createdBy` (set once, when it was added) and `actor` (the last
+writer), both `{userId, kind: "person" | "agent" | "seed", agent, via}` or null on
+old records. A "By"
+column or list meta shows `createdBy`: the person's name, or the agent's name
+("Claude Code") with an "Agent" badge when `createdBy.kind` is "agent". Show
+nothing for "seed" (starter data) or null. Add "Last changed by" from `actor` only when it
+helps the task. Say "You" when the `userId` is `info.viewer.userId`. Flash a row or
+card that someone else just changed. Changes from `subscribe` carry `actor` but not
+`createdBy`: read the record again (`get(id)`) to show who added it.
+
+**Board.** Lanes per stage, art on cards from the asset, owner initial and comment
+count. Move cards with `summer-move`; write the new stage to data at once.
+
+**Pick grid.** One `summer-choice-grid layout="row"` per need; the header shows
+`summer-progress` and the primary sends the picks ("Send 7 to game").
+
+## States
+
+- Loading: set `loading` on stats, chart, table, list and select until the data
+  arrives. Never show "No data yet" or "-" while loading.
+- Empty: `empty-text`, or `empty-heading` + `empty-body`, on the component, or
+  `summer-empty-state` for a whole page. Say what to do next.
+- Error: `summer-notice tone="error" text="The notes could not load." action="Try again"`
+  in place of the part that failed; retry on its `action` event. The rest keeps
+  working.
+- Saving: `busy` on the form or save bar, `loading` on a button.
+
+## Type, colour, copy
+
+- The kit sets type. In your own glue use 14px body, 12px muted meta, weights 400,
+  500, 600, `tabular-nums` for numbers. Never 700, never all caps.
+- Colour means something: quiet by default, ink or a status tone for what needs
+  attention, always with words.
+- Plain words, sentence case, no full stop on labels. Name actions by result ("Save
+  note", "Write to game"). Errors do not apologise. Never "AI-generated".
+
+## Never
+
+Grey boxes around numbers. Cards around every section, cards inside cards. Native
+audio, video, select or range controls. Two primaries in one region. A labelled
+button on every row. A health badge on every row that only says all is well. Hand-drawn icons, emoji. Hex
+colours, gradients, glows, shadows on cards. Mono font for numbers. "No data yet"
+while loading.
+
+## Checklist
+
+- [ ] The purpose line says what the tool does; one primary per region finishes it.
+- [ ] Every component and attribute matches its catalog entry.
+- [ ] Numbers line up; long text wraps; on a phone nothing scrolls off.
+- [ ] Loading, empty (including "waiting for your agent") and error states exist
+      and keep the layout in place.
+- [ ] Subtract: remove each badge, icon, helper line and frame; keep it only if the
+      task gets worse without it.
+- [ ] Works by keyboard; icon buttons have labels.
+- [ ] Looked at light and dark, 390px and 1440px; nothing scrolls sideways except a
+      board or a wide table inside its frame.

package/library/skills/summer-apps-design/resource.yaml

@@ -0,0 +1,23 @@
+id: skill/summer-apps-design
+kind: skill
+version: 0.1.0
+summary: How a Summer App should look - page layout, Summer UI kit components, tables, charts, media, boards, states and a pre-ship checklist.
+use_when:
+  - building or changing the UI of a Summer App (agent-built team tool inside Summer Studio)
+  - an app looks generic, cluttered or off-brand
+  - choosing layout for a table, chart, board, pick grid or settings tool
+facets:
+  lifecycle:
+    - build
+  domains:
+    - ui
+    - tools
+  modalities:
+    - docs
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+recommended: true

package/library/skills/using-summer/SKILL.md

@@ -112,6 +112,7 @@ When multiple Summer skills could apply, run them in this order:
 3. **Build skills third** — `fps-controller`, `design-mechanic`, `design-level`, `multiplayer`. These produce the artifacts.
 
 > "I want to make a game" → `brainstorm-game` first, then build skills.
+> "Make me a sword clash sound" with no game in sight → the asset skill (`sound-effect`) directly. Asset requests need no brainstorm, no project and no running engine.
 > "Fix this crash" → `debug` first, then domain skills.
 > "Add an FPS controller" → check `scene-composition` first, then `fps-controller`.
 

package/library/tools/app-call/resource.yaml

@@ -0,0 +1,59 @@
+id: tool/app-call
+kind: tool
+version: 1.0.0
+summary: Run one of a Summer App's agent tools inside the person's open app.
+use_when:
+  - '"nerf the bow using the balance formula in our app"'
+  - using logic that lives in an app (a balance formula, an export) while the app is open
+do_not_use_when:
+  - "plain reads and edits of app data: summer_app_data"
+facets:
+  lifecycle:
+    - build
+  domains:
+    - tools
+    - ui
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/summer-apps
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_app_call
+implementation:
+  module: src/mcp/tools/app-tools.ts
+  export: registerAppTools
+surfaces:
+  mcp:
+    tool_name: summer_app_call
+    remote: true
+input_schema:
+  type: object
+  properties:
+    appId:
+      type: string
+      format: uuid
+      description: The app id from summer_app_create or summer_app_list
+    tool:
+      type: string
+      minLength: 1
+      maxLength: 64
+      description: The agent tool name from summer_app_tools
+    input:
+      type: object
+      additionalProperties: {}
+      default: {}
+      description: Input matching the tool's input schema
+  required:
+    - appId
+    - tool
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: true
+  credentials: false
+  publish: false