@agent-native/core-corpus 0.214.0 → 0.217.0

package/corpus/templates/slides-2/.agents/skills/external-agents/references/mcp-apps-embedding.md

@@ -0,0 +1,169 @@
+# MCP Apps Embedding Internals
+
+Deep-dive reference for the optional MCP Apps UI surface — the `mcpApp` action
+field, `embedApp()`, the host bridges (Claude / ChatGPT), embed start tickets,
+extension-page rendering inside chat embeds, and host sizing. For the common
+case (adding a `link` builder, connecting hosts, ingest actions, the
+`/_agent-native/open` route), see `../SKILL.md`. This file is the expansion of
+that skill's "Optional MCP Apps UI" section.
+
+## Optional MCP Apps UI
+
+For hosts that support the MCP Apps extension, an action can also advertise an
+inline UI resource with `mcpApp`. This is a progressive enhancement for flows
+where the external agent should hand the user an interactive surface instead of
+only text — for example reviewing an email draft, editing a calendar invite, or
+choosing between generated dashboard variants.
+
+Use the real React app with `embedApp()` whenever the user needs UI. The mental
+model is simple: the action's `link` target is also the MCP App embed target.
+Expose the operation as a normal action/tool, return a focused deep link with
+`link`, and add `mcpApp.resource = embedApp(...)` so capable hosts load that
+same route inline instead of opening a new tab.
+
+`embedApp()` supports both host bridges. Standard MCP Apps hosts use the
+`ui/*` bridge; ChatGPT uses the `window.openai` compatibility bridge, reading
+`toolInput` / `toolOutput` / `toolResponseMetadata` and calling
+`create_embed_session` through `window.openai.callTool(...)`. Do not build a
+ChatGPT-only HTML surface. Keep the action result and `link` target focused so
+both bridges land on the same real app route.
+
+That means full-app embeds can do anything the route can do once opened:
+review or edit an email draft, show a filtered inbox/search, open a calendar
+event or event draft, load an extension page, inspect a full analytics
+dashboard or saved analysis, continue a deck in the Slides editor, or open a
+Design project/editor. Prefer URL/deep-link params and the existing
+`/_agent-native/open` navigation/app-state bridge over inventing a second
+state protocol for MCP Apps.
+
+On rare occasions the right target is a focused app route that renders one
+shared React component instead of the whole app shell. Analytics' `/chart`
+route is the model: it takes a compact `SqlPanel` payload in the URL and
+renders the same chart component the dashboard uses. This is still an app
+embed, not a plain HTML MCP App. Expose or call it through a normal action /
+`open_app({ path, embed: true })`, keep the URL deterministic, and let
+`embedApp()` render that route inline.
+
+Do not hand-write one-off plain HTML MCP Apps for product UI; if the action
+needs a custom surface, add or reuse a real app route/component first and embed
+that route.
+
+```ts
+import { embedApp } from "@agent-native/core";
+
+export default defineAction({
+  // ...schema, run, link...
+  mcpApp: {
+    resource: embedApp({
+      title: "Review draft",
+      description: "Open the generated draft in the real Mail compose UI.",
+      iframeTitle: "Agent-Native Mail",
+      openLabel: "Open in Mail",
+    }),
+  },
+});
+```
+
+The MCP server advertises extension `io.modelcontextprotocol/ui`, adds
+`_meta.ui.resourceUri` plus the legacy-compatible `_meta["ui/resourceUri"]` to
+`tools/list`, and also emits ChatGPT Apps SDK compatibility metadata
+(`openai/outputTemplate`, widget CSP/description/accessibility). It exposes the
+HTML through `resources/list`, `resources/templates/list`, and `resources/read`
+using MIME `text/html;profile=mcp-app`. The stdio proxy forwards those resource
+handlers from the live app, so local desktop/CLI clients see the same resources
+as HTTP clients.
+
+Keep the existing `link` builder even when adding `mcpApp`. CLI-only clients,
+older hosts, and any host that does not render MCP Apps will ignore the UI
+metadata and still need the "Open in … →" link. `embedApp()` uses that link as
+its launch target. Same-app `open_app({ embed: true })` mints the
+`/_agent-native/embed/start` ticket during the original tool call so production
+hosts do not need the iframe to make a second app-only helper call; custom
+actions can return `embedStartUrl` for the same fast path. The MCP layer keeps
+that ticket-bearing URL in hidden metadata and strips it from model-visible
+structured content and normal open-link metadata. Otherwise the resource falls
+back to the app-only `create_embed_session` helper. The embed start route
+exchanges a one-time SQL ticket, then launches the real app route with a
+short-lived browser session. Standard hosts navigate the MCP App frame
+directly. Claude web uses a single-frame transplant path that fetches the
+signed app HTML and hydrates it inside Claude's MCP App iframe because Claude
+does not reliably allow app-owned child iframes or external frame navigation.
+ChatGPT web uses a controlled route iframe for stable `window.openai` host APIs
+and bounded height control. You can force the
+single-frame transplant path in other hosts with `embedMode: "transplant"` or
+`frame: "transplant"` when debugging host module loading, or force the nested
+diagnostic iframe with `embedMode: "iframe"` /
+`renderMode: "iframe"` / `nested: true` when debugging host behavior. Pass
+additional `frameDomains` only for a custom MCP App that truly embeds a
+third-party frame. `open_app({ app, path, embed: true })` is the generic
+escape hatch for routes like full dashboards, filtered inboxes, calendar
+drafts, analyses, or extension pages, and should be used liberally when the
+full app is the clearest review/edit surface.
+
+Do not set standard `_meta.ui.domain` to an app URL. That field is
+host-specific: Claude validates hash subdomains such as
+`{hash}.claudemcpcontent.com`, while ChatGPT has its own widget-domain
+metadata. Let hosts choose their default sandbox origin unless you are emitting
+a host-specific value on purpose. `embedApp()` may still emit
+`openai/widgetDomain` for ChatGPT compatibility.
+
+Extension pages are a special case inside MCP chat embeds. The normal app uses
+`/_agent-native/extensions/:id/render` as a sandboxed child iframe, but MCP
+chat hosts add another ancestor frame and can block that route via
+`frame-ancestors` / `X-Frame-Options`. In MCP chat bridge mode the framework
+renders the extension document as sandboxed `srcDoc` inside the existing app
+route iframe instead; keep `sandbox="allow-scripts allow-forms"` and do not add
+`allow-same-origin`.
+
+For Dispatch, keep the single connector path first-class: the `open_app`
+resource CSP should include the exact origins of apps granted through Dispatch,
+not broad sources like `https:`. This lets Claude's transplant path fetch the
+signed target app HTML while keeping the connector's resource surface narrow.
+
+Host sizing rule: the MCP resource shell owns a bounded inline height and the
+embedded route should scroll internally. `embedApp({ height })` defaults to a
+`560px` shell, clamps to `320-900px`, and subtracts `44px` for the wrapper bar
+before sizing the route viewport. Do not re-enable host SDK auto-resize for
+full-app route embeds; Claude and ChatGPT can otherwise measure the whole
+document and create a huge chat iframe. After changing the shell or `ui://`
+resource version, verify with a fresh tool call because old conversation frames
+keep the behavior they were rendered with.
+
+Inside embedded routes, `sendToAgentChat({ submit: true })` posts
+`agentNative.submitChat`; MCP App hosts receive that as model context plus a
+visible `ui/message` turn, so an inline preview can intentionally continue the
+Claude/ChatGPT conversation. Hidden context stays in model context; do not put
+internal app-state file instructions into the visible prompt. `submit: false`
+stays local as a prefill/review path.
+
+In the ChatGPT MCP App host, foreground text-and-context handoffs explicitly
+marked `chatTarget: "local"` also use the active `window.openai` / `ui/message`
+bridge, so review and edit actions continue in the ChatGPT conversation. Keep
+prefill-only, background, approval, URL-backed attachments, and app-scoped
+requests local. Inline images represented as data URLs and text attachments can
+use the host. A `newTab` prompt continues in ChatGPT's active conversation;
+thread-fork controls remain app-local because the host bridge has no fork
+method. Other MCP hosts retain their explicit local-chat behavior.
+
+When testing Claude through ngrok, use a production build (`pnpm exec agent-native build`
+then `pnpm exec agent-native start`) or a deployed preview/production URL. Claude's
+transplant path works with production asset chunks; raw Vite dev modules such
+as `/app/root.tsx` can be app-auth protected and fail dynamic imports from the
+Claude resource origin. A production build refuses local PGlite and a generated
+auth secret, so set `DATABASE_URL` to a Postgres database (a local Postgres or a
+Neon branch) and `BETTER_AUTH_SECRET` (from `openssl rand -hex 32`) before
+`agent-native start`.
+
+For known first-party handoffs, prefer a direct action with `mcpApp` over
+letting the model hunt through screens. Examples: Mail `manage-draft` for email
+drafts, Analytics `open-traffic-dashboard` for the first-party traffic
+dashboard, Calendar `manage-event-draft` for invite drafts, and create/search
+actions for Forms, Content, Clips, Slides, and Design. The action should return
+concise structured content plus the link; it should not dump large catalogs or
+HTML.
+
+Compatibility target: build to the standard once, not per-client shims. MCP
+Apps-capable hosts should include Claude/Claude Desktop/Claude Code, ChatGPT
+custom MCP apps, VS Code GitHub Copilot, Goose, Postman, MCPJam, Cursor, and
+any future host that follows the extension negotiation. Host support varies by
+plan, release channel, and client version, so keep the deep link fallback.

package/corpus/templates/slides-2/.agents/skills/frontend-design/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: frontend-design
+description: >-
+  Product-specific interface design for an Agent-Native app. Use when creating
+  or changing any user-facing UI, including screenshot feedback, copy or
+  density cleanup, settings, controls, or a visual redesign.
+scope: both
+---
+
+# Frontend Design
+
+Design around the user's task and the app's existing visual language. A
+distinctive interface comes from a clear product point of view, not extra
+decoration. Keep implementation accessible and responsive.
+
+## Choose a direction
+
+Before a substantial new surface or redesign, decide who is using it, what
+they came to do, and what they should see or do next. Pick a visual direction
+that fits the product's brand and domain. For routine changes, inspect and
+follow the existing components, type, color tokens, and spacing.
+
+If a screen has two unrelated primary jobs, split the workflows or states.
+Do not solve an unclear structure by adding more cards, tabs, controls, or
+explanatory copy.
+
+## Keep the starting view focused
+
+The first view should show where the user is, the current work or state, and
+the input or decision needed now. Make one action clear. Defer rare, advanced,
+diagnostic, destructive, and historical controls to a relevant menu or
+disclosure.
+
+Every visible element should orient the user, show useful content or state,
+collect required input, or enable the next action. If it has no job, remove it
+or disclose it. Density should come from useful data, not extra chrome.
+
+Do not add a page title that repeats the selected navigation item, a subtitle
+or eyebrow under a title, a count strip over visible content, an About section
+in settings, or helper copy that repeats a label unless the user asks for it.
+A card, panel, tab, or settings group gets a title or a description, not both.
+Use tooltips or progressive disclosure for explanations that are not needed to
+make the current decision. User-authored descriptions are content: render them
+when present and render nothing when empty.
+
+For sequential setup, show one decision at a time with clear progress and
+sensible defaults. Use the smallest surface that fits the task: an inline row
+or dialog for a small edit, a focused flow for multi-step work.
+
+## Use the app's design system
+
+Preserve the existing brand and theme. Prefer semantic color tokens and the
+app's type system over raw palette colors or a newly invented visual system.
+Choose an accent and type treatment for a reason; avoid generic gradients,
+glass effects, decorative blobs, and hero sections without a product purpose.
+
+Use the app's local UI adapter for standard controls. In an Agent-Native app,
+check the configured design system and toolkit provider before changing how
+shared controls look. Read `shadcn-ui` when implementing or composing a
+standard control; keep product-specific layout and visual decisions here.
+
+Use real or generated imagery when it helps the user understand the subject.
+Do not add decorative assets solely to fill empty space.
+
+## Coordinate the UI with the agent
+
+Keep repeatable, direct manipulation in the domain UI and use the agent for
+work that benefits from judgment, exploration, or conversation. If the app has
+a contextual agent sidebar, reuse it for in-context help and keep the user on
+the current work surface. Do not add a second freeform prompt box. A control
+that promises agent help should hand off the relevant context; label local,
+deterministic behavior plainly.
+
+## Interaction Responsiveness
+
+Show feedback as soon as the user acts, aiming for 100 ms. When work cannot
+finish immediately, acknowledge it before a network round-trip and show a
+focused pending state within 400 ms. Use optimistic updates when safe, then
+confirm or roll back on failure. Keep long work visibly progressing and offer
+a way to stop when the operation supports cancellation.
+
+## Make interactions clear and accessible
+
+Support keyboard use, visible focus, accessible names, readable contrast, and
+clear validation and recovery. Dialog and menu controls should use the app's
+existing accessible primitives rather than hand-built click-outside behavior.
+Never use browser `alert`, `confirm`, or `prompt` dialogs.
+
+Use motion to clarify a state change. Prefer short transitions on opacity or
+transform, respect reduced-motion preferences, and avoid delaying content with
+decorative entrances or long animations.
+
+Fit the content to narrow screens as well as desktop. Text and controls should
+not overflow their containers; fixed-format editors, boards, and toolbars
+should keep stable dimensions.
+
+## Review the result
+
+Check that the main job and next action are obvious. Look at the default,
+loading, empty, error, and success states that apply, and check a narrow
+viewport. Remove anything that competes with the task without helping the user
+act or understand state.

package/corpus/templates/slides-2/.agents/skills/frontend-design/references/visual-direction.md

@@ -0,0 +1,102 @@
+# Visual Direction Reference
+
+Use this reference when a new app or workspace needs a visual point of view and
+does not already have an established brand system. It adapts the useful parts
+of Impeccable's workflow: understand the product, name the surface mode, deal
+several coherent directions, commit to one, and audit the result for defaults
+that became the design by accident.
+
+## The direction contract
+
+Before writing UI, capture these decisions in the app's `DESIGN.md`:
+
+| Decision             | What to record                                                    |
+| -------------------- | ----------------------------------------------------------------- |
+| Product mode         | `operate`, `read`, `persuade`, or `experience`                    |
+| Audience and cadence | Who uses it, how often, and under what conditions                 |
+| Visual world         | A short name and the feeling it creates                           |
+| Palette family       | The semantic accent family and neutral undertone                  |
+| Type treatment       | Sans-first, editorial contrast, or display-led emphasis           |
+| Composition          | Focused workbench, list/detail, document, canvas, or guided steps |
+| Shape language       | Quiet corners, crisp geometry, or soft utility surfaces           |
+| Anti-references      | Defaults this app must not drift toward                           |
+
+`DESIGN.md` is a portable design contract, not a license to bypass the app's
+tokens or component system. If the app already has a brand system, document it
+and preserve it. If it does not, choose a direction before styling.
+
+## Palette families
+
+Use one family as an accent and keep the rest of the system semantic and quiet.
+These are starting points, not a fixed theme library:
+
+| Family           | Good fit                                    | Typical character                 |
+| ---------------- | ------------------------------------------- | --------------------------------- |
+| Ink / graphite   | Admin, security, sensitive review           | Serious, low-noise, high contrast |
+| Cobalt / sky     | Planning, collaboration, scheduling         | Clear, trustworthy, alert         |
+| Pine / teal      | Automation, systems, finance, data          | Calm, capable, grounded           |
+| Indigo / violet  | Slides, creative tools, research            | Exploratory, focused, expressive  |
+| Plum / berry     | Publishing, knowledge, editorial work       | Distinctive, thoughtful, human    |
+| Coral / rose     | Communication, people, customer workflows   | Warm, direct, social              |
+| Ochre / citron   | Lightweight planning or energetic utilities | Optimistic, sparing, directional  |
+| Paper / charcoal | Long-form reading, exports, approvals       | Tactile, restrained, legible      |
+
+Do not make warm beige plus terracotta the universal fallback. Do not rotate
+through saturated colors mechanically. Choose the family that supports the
+workflow, then verify contrast, dark mode, focus states, destructive states,
+and the sidebar boundary.
+
+## Variation without chaos
+
+Vary at least two independent axes when sibling apps share a workspace:
+
+- accent family or neutral undertone;
+- information density and page composition;
+- type contrast and display treatment;
+- radius and border language;
+- navigation emphasis and use of whitespace.
+
+Keep shared behavior, semantic token names, accessibility, and AgentSidebar
+placement consistent. The goal is a family of products, not five unrelated
+themes and not five copies of the same starter.
+
+For a batch of apps, keep a small direction ledger in the workspace
+`DESIGN.md` or the handoff. Record each app's mode, direction, and palette
+family, then choose a new family or a clearly different composition for the
+next app unless an existing brand requires reuse. Never copy a sibling's
+`global.css` palette block or treat the last app's accent as the generator
+default.
+
+## Review vocabulary
+
+Make one named intervention at a time so the agent can reason about the
+change:
+
+- `distill` - remove copy, controls, cards, and chrome that do not serve the
+  next decision;
+- `typeset` - repair hierarchy, measure, line length, and emphasis;
+- `colorize` - establish a restrained semantic palette and contrast states;
+- `layout` - repair grouping, density, alignment, and responsive composition;
+- `polish` - resolve the small visual inconsistencies after the structure is
+  right;
+- `audit` - check slop, accessibility, responsive behavior, and visual drift.
+
+Do not average several directions into a generic compromise. Deal two or three
+coherent options only when a new or explicitly redesigned surface has a real
+visual decision to make; for routine operate work, select one fitting direction
+and encode only the useful decision in tokens and `DESIGN.md`.
+
+## Anti-slop audit
+
+Before handoff, inspect the first viewport and ask:
+
+- Did the app inherit the neighboring app's palette or hero layout without a
+  product reason?
+- Does the first viewport show one job and one next action, rather than a
+  capability catalog?
+- Are there equal-weight cards, status chips, helper paragraphs, or controls
+  that should be removed or disclosed?
+- Does the typography fit the product mode instead of decorating the shell?
+- Is the AgentSidebar distinct but quiet, with the domain page still primary?
+- Are focus, loading, empty, error, dark, and narrow-width states part of the
+  same design direction?

package/corpus/templates/slides-2/.agents/skills/image-generation-via-a2a/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: image-generation-via-a2a
+description: When a slides deck needs images, delegate to the Assets app over A2A so generations are grounded in the user's brand library — never call an image-generation API directly from slides.
+---
+
+# Image generation via A2A
+
+Slides never calls an image-generation API itself when Assets is reachable.
+Assets owns brand libraries, presets, provenance, and the generation audit log,
+so every improvement there has to reach decks for free.
+
+Both entry points share one delegation helper,
+`server/lib/assets-image-delegation.ts`:
+
+1. **`generate-image-api`** — the action the agent and the editor's image panel
+   use. It delegates to Assets, then returns `source: "assets-a2a"` with the
+   Assets reply verbatim (plus `url` when a `previewUrl`/`downloadUrl` was
+   parseable).
+2. **`pnpm action generate-image`** — the CLI script, for local runs that want
+   files on disk. Same delegation, prints the reply verbatim.
+
+The helper resolves Assets through agent discovery (target `assets`, which also
+matches `images`), so a workspace with both apps mounted needs no endpoint
+configuration. Standalone deployments may provide `IMAGES_A2A_KEY` as a static
+transport credential; user and organization credentials still take precedence.
+
+## Outcomes
+
+The helper distinguishes four outcomes, because "Assets did not return an
+image" has very different right answers:
+
+| Outcome | Meaning | What happens |
+| --- | --- | --- |
+| `delegated` | Task completed | Use the reply's `previewUrl` |
+| `rejected` | Task ended `failed`/`canceled`/`input-required` | Surface the reason; do NOT silently generate locally |
+| `pending` | Caller-side timeout; the Assets run is still going and owns a `taskId` | Tell the user to check Assets; generating again would duplicate the run |
+| `unavailable` | Assets could not be resolved or reached at all | Local fallback |
+
+A `delegated` reply can still say the generation is a draft pending approval.
+That means the user may draft in that brand kit but not save into it: the image
+is real and usable in the deck, and only the copy kept in Assets is waiting on a
+kit editor. Use the image, pass that along, and do not retry or fall back
+locally.
+
+Only `unavailable` falls through to the local Gemini/OpenAI providers under
+`server/handlers/image-providers/`, so a slides-only deploy still works. They
+try the organization's Image generation provider first (the
+`manage-service-providers` action), then Gemini, then OpenAI. That
+output is **not** brand-grounded and the action says so: it returns
+`source: "slides-fallback"` with a `fallbackReason`. Report that honestly
+rather than presenting a fallback image as a library generation.
+
+There is no direct Builder.io image-generation path in slides. If a user wants
+Builder-managed generation, that belongs in Assets, behind the same delegation.
+
+## Calling explicitly from the agent
+
+Call the action with the destination so Assets can ground the generation:
+
+```
+generate-image-api { prompt, deckId, slideId, slideContent }
+```
+
+For direct insertion, add `insertIntoSlide: true`. This requires both IDs. The
+action registers the image in the deck asset collection, then saves
+source-backed slides through `update-slide-source` using the current revision
+and source hash. Legacy HTML slides use `update-slide` with the registered asset
+URL. It only returns `inserted: true` after reading the saved source or HTML back
+and verifying the image.
+Never say the image was added based on `url`, `previewUrl`, or a completed
+Assets reply alone. For preview-only variations, leave `insertIntoSlide` false;
+after the user chooses one, call `generate-image-api` with `generatedImageUrl`
+set to the chosen preview URL, `insertIntoSlide: true`, the target IDs, and the
+original prompt. Do not write the remote preview URL into source or derived
+HTML directly.
+
+Do **not** reach for the generic `call-agent` tool to ask Assets for an image.
+It talks to the same app, so it looks equivalent, but it skips the slide
+grounding, the completed-vs-failed task handling, and the ready-to-render
+preview markdown this action returns — which is how image results end up in
+chat as bare links instead of visible images.
+
+Slides owns the semantic job of the image: its slide role, audience, crop, and
+must-preserve content. Assets owns library and preset selection, style anchors,
+generation settings, and provenance. Include the active design system's
+image-style guidance in the prompt context, but do not ask Assets to invent a
+competing brand direction.
+
+Use the returned `previewUrl` for previews. Do not drop it into slide HTML
+without the verified insertion workflow above.
+
+## Showing the result in chat
+
+Always show a generated image as an inline markdown image:
+
+```md
+![Monstera deliciosa](https://…/preview.png)
+```
+
+The chat renders `![]()` as a real image but `[]()` as a bare link, so a
+plain link (or a "View the photo" / "Open preview" link) leaves the user with
+nothing to look at. Use the action's `url` field, or the `previewUrl` from the
+Assets reply when the action could not parse one. This applies whether the
+request came from the editor's image panel or from a plain chat message like
+"generate a photo of a monstera".
+
+The delegation message already instructs Assets to mark generations with
+`source: "a2a"` and `callerAppId: "slides"` when it calls `generate-image-batch`
+or `refine-image`. That keeps the Assets audit log useful for design review.
+
+## Multi-slide image generation
+
+Do not fire parallel `add-slide` calls into the same deck. Keep deck writes
+sequential: add one slide, wait for the result, then add the next slide. If a
+single slide needs several image variants, the image-generation action may
+request multiple variants internally, but the deck write itself should remain a
+single action call. Use `generate-image-api` for image insertion; it routes
+source-backed slides through revision-checked `update-slide-source` and legacy
+HTML slides through `update-slide`.
+
+## Iteration
+
+When the user gives feedback ("make slide 3's hero darker, more navy"), ask Assets to run `refine-image` with the previous `assetId` (extracted from the `previewUrl` returned earlier) plus the new feedback. Import the refined preview through `generate-image-api` with `generatedImageUrl` and `insertIntoSlide: true` so it becomes a registered asset and source-backed slides use revision-checked edits. Do **not** delete the prior asset — it stays in the library so the user can pick which version to keep.
+
+## Cross-app reply parsing
+
+The Assets reply comes back as plain text. Assets (per its `a2a-assets` skill)
+includes `assetId`, `runId`, `previewUrl`, `downloadUrl`, and `embedPath` exactly
+as returned by its actions. `extractAssetUrl` pulls the first `previewUrl` /
+`downloadUrl` out of that reply; when it finds none, the action returns the reply
+without a `url`.
+
+If parsing the reply fails, surface "I couldn't parse the Assets agent's
+response" to the user rather than guessing at URLs.

package/corpus/templates/slides-2/.agents/skills/performance/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: performance
+description: >-
+  Keep app loads and interactions responsive as data grows. Use when a page
+  feels slow, jumps, or lags, or when changing a data read, list, polling path,
+  startup path, or performance-sensitive UI.
+scope: dev
+---
+
+# Performance
+
+Find the cost that users actually wait on, then reduce it without weakening
+the result. A slow screen may be waiting on the server, moving too much data,
+serial reads, repeated computation, or browser rendering; measure before adding
+caches or extra complexity.
+
+## Load only what the current view needs
+
+- Shape list reads around the fields the list displays. Keep large document
+  bodies, histories, rendered output, and other rarely viewed data on a detail
+  or on-demand path. Return a small preview when the list needs one.
+- Paginate or window unbounded histories and activity feeds. Start with the
+  recent or visible range and load more as the user asks for it.
+- Batch related reads instead of issuing one query per row. Compute counts and
+  other aggregates in the database when the result can be much smaller than
+  the source rows.
+- Start independent reads together. Do not make the first useful content wait
+  for unrelated settings, below-the-fold panels, or secondary details.
+- Index fields used by frequent filters, joins, and sorts when the data and
+  observed query cost justify it. Keep indexes aligned with real query shapes.
+
+For action-backed screens, shape the action response for the screen's current
+need and keep the UI on the app's existing action and query hooks. Do not add a
+second fetch path that duplicates the same read.
+
+## Keep repeated work cheap
+
+- Keep list and frequently refreshed reads inexpensive. Avoid parsing,
+  reformatting, or rebuilding large values on every read when the result can be
+  prepared once or computed only for the view that needs it.
+- Use the app's existing live-update path when fresh data must reach an open
+  screen. Poll only when needed, and keep polled reads bounded and cheap.
+- Keep large file contents and long records out of list responses. Load them
+  when the user opens the relevant item rather than sending them on every list
+  refresh.
+- Defer nonessential data and expensive child views until after the main
+  content is usable. Window a rendered list when rendering all rows makes
+  scrolling or updates slow.
+
+## Protect startup and the first paint
+
+- Keep migrations, backfills, data scans, aggregations, provider handshakes,
+  and cache warming out of module evaluation and application startup. Hosted
+  serverless instances can restart, so startup work can repeat on user
+  requests. Use the app's deliberate migration, job, or on-demand path.
+- Keep optional heavy runtimes out of modules loaded by ordinary page requests.
+  Load a browser, media processor, or other large dependency only in the
+  feature or job that needs it, and inspect the deployed bundle when adding
+  one.
+- Keep the server-rendered shell public and independent of a visitor's session.
+  Resolve user-specific state after the shell loads through the app's
+  authenticated client data path. Reads that must reflect a recent mutation
+  should not depend on cached server-rendered loader data.
+- Give loading placeholders the final content's basic geometry. Reserve space
+  for content whose size is known; avoid showing a temporary layout that shifts
+  the user's reading position when data arrives.
+
+## Keep interactions responsive
+
+Show that an interaction registered as soon as it happens, aiming for 100 ms.
+If the work needs the network or takes longer, acknowledge it before waiting
+and show a focused pending state within 400 ms. Use an optimistic update when
+it is safe, then confirm or roll back on failure.
+
+When investigating a slow experience, separate server response time, data
+transfer, serial waits, rendering, layout movement, and long interaction work.
+Use representative data and the production build when development tooling
+changes the cost. Verify that the user-visible action completed before
+comparing timings or memory.