@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/docs/publishing.md

@@ -1,5 +1,10 @@
 # Publishing to HELIX Instant
 
+`publish_world` / `helix publish` now automatically capture a ready-world cover when no selected custom thumbnail exists. The image is verified and assigned atomically with the Build; capture failure refuses publication before World/Build writes. Register a `hero` shot and call `screenshots.ready` after assets load. Automatic covers refresh per Build; selected custom covers are preserved. Pass `thumbnail` / `--thumbnail` to select a cover without automatic capture. Manual capture/inspect/attach below remains the workflow for selecting custom media and optional preview images.
+
+Native Scene v2, semantic Continuum Releases and Unreal/shared-runtime promotion currently require a selected custom cover. They explicitly fail with `WORLD_THUMBNAIL_CAPTURE_UNSUPPORTED` if no cover exists; automatic capture adapters for those runtimes are not integrated. This is a publication failure, never a successful generic placeholder.
+
+
 ## The pipeline
 
 `publish_world` runs the full creator pipeline against the platform:
@@ -10,6 +15,64 @@
 4. **Finalize** — the platform verifies every declared file landed byte-exact, then atomically activates the build. A draft world auto-publishes on its first successful build.
 5. You get back the **play URL** — shareable, instant, no install.
 
+## Native platform updates
+
+New system-bearing web Worlds publish with platform systems outside the creator
+bundle. Compatible `^`/`~` ranges receive safe native character updates—such as
+emotes, the emote customizer, standard camera behavior, pointing, and avatar
+presentation—on a fresh launch without rebuilding or republishing the World.
+**Engine systems are ranges.** Declare `^`/`~` lines (`"humanoid-character": "^0.3"`,
+`"engine-core": "^0.1"`, `"scene": "^0.3"`, `"visual": "^0.1"`); never an exact `x.y.z`. An
+exact version freezes the World on one immutable build, so `validate_world` and
+`publish_world` **refuse** it (an exact `systems` value, a `helix.runtime.json` system with
+`mode: "pinned"`, or an `@helix/*` import-map entry aimed at an immutable
+`/packages/<id>/<rev>/` URL). If an engine fix is published but not promoted, **promote it**
+(`POST /api/v1/instant-packages/<slug>/versions/<version>/rollout`
+`{"rolloutPercent":100,"reason":"…"}`) — never pin a World to get it. The only override is
+the human running the CLI with `helix publish dist --allow-exact-engine-pin "<reason>"`: the
+reason is required, a loud warning is printed, and the override is logged to
+`~/.helix/engine-pin-overrides.jsonl`. Agents do not use it.
+
+This does not hot-swap arbitrary creator code: the creator SDK, installed
+abilities, game code, and game assets remain in the immutable World build.
+Feature-level refusals also remain available without pinning everything. Every
+native avatar feature — emotes, the radial wheel and its Customize door, x-ray,
+pointing, sitting, the avatar camera, the two camera legs, and universal-avatar
+bodies — is ON in every character World, and a World names the ones it does not
+want in `character.native.disabled` at create time (a blocklist, never an
+allow-list, so features added later still arrive; `universal-avatar` is the
+all-or-nothing top switch). That is runtime config, not manifest, and not a
+publish-time concern — full reference: `read_doc({ name: "character-world" })`
+section 8g, which carries the humanoid-character version this surface needs;
+an older runtime ignores the key silently. Validation and the publish server both reject legacy bundled system
+delivery, unsafe `latest`/`*` ranges, and import-map drift.
+
+Older source-less bundles are never rewritten. Recover the source, run the
+current `helix install --update`, rebuild, validate, and republish.
+
+## Source upload is OPT-IN, and it is the human's decision
+
+A published world ships only its **built bundle**. Nothing else is kept, so the world cannot be
+opened and edited in the website editor later — there is nothing there to edit.
+
+`publish_world({ uploadSource: true })` additionally sends the project's source, on a separate
+**private** channel, which is what makes that later edit possible.
+
+- **Off by default.** Source is never uploaded unless you set it.
+- **ASK THE HUMAN FIRST.** This sends their code to the platform. Some creators deliberately do not
+  want that, and it is not a decision an agent makes on their behalf. Do not set it because it
+  seems helpful.
+- **What is sent**: the project directory, honouring `.gitignore`, always excluding `node_modules`,
+  `.git`, `dist` and `.vite`. Compressed cap 128 MiB, checked before anything is uploaded.
+- **Which directory**: `directory` is the BUILT bundle, so the source defaults to its parent. Pass
+  `sourceDir` only when the project root is somewhere else. `sourceDir` on its own is refused, not
+  silently ignored.
+- **Nothing about the build changes.** The published bundle, its files, its URLs and its behaviour
+  are identical either way. The source never becomes part of the build — build files are public and
+  long-cached; source is not.
+- The publish response says which happened, every time. Relay it: a creator who published without
+  source should know the option exists.
+
 ## Login (human-in-the-loop)
 
 Publishing requires a creator account session. The sign-in itself is human (browser + website), but you drive it: call `start_login` — the human's browser opens to the HELIX sign-in page (relay the returned URL if it doesn't) — then poll `check_login` until it reports success. The minted token is saved locally by the MCP process and never enters the conversation.
@@ -28,6 +91,9 @@ Creator access is currently invite-only (curated launch); the account must have
 - Validation errors list every problem at once — fix all of them, rebuild, re-validate.
 - `409` on world creation: the slug is taken by another creator. Choose a different slug in `helix.json`.
 - "missing upload" / "size mismatch" at finalize: the build directory changed between validate and publish — rebuild and re-publish.
+- A bundle refused for containing `helix-sdk/dev-shell`: world code imported the `helix dev` simulator. It is
+  the CLI's half of local testing, never a world API — remove the import; the world talks to whatever shell
+  embeds it, simulated or real, through the ordinary `Helix.*` surface.
 - `401`/`403`: login expired or the account lacks the creator flag — back to the human.
 
 ## After publishing
@@ -35,41 +101,55 @@ Creator access is currently invite-only (curated launch); the account must have
 - The publish response returns the canonical **play URL** — share that link directly (don't construct portal URLs by hand; they differ per environment).
 - Title, content rating, mobile support, and `requiresAuth` on the world page all come from the manifest — re-publish to update them.
 
+## Achievements are registered separately (and BEFORE the rules that award them)
+
+A world's badges are a per-world registry the bundle cannot express: `helix.json` has no achievements block, and
+publish cannot check that an awarded key exists — so an `awardAchievement` rule naming an unregistered key ships clean
+and silently grants nobody anything. Register with `register_achievement` / `helix achievement register <slug>` (a 2D
+icon file is required), read the registry back with `list_achievements`, and only then publish the world whose rules
+name those keys. Test the unlock BEFORE registering: the same rows (no icon needed) seed `.helix/dev-achievements.json`
+for `helix dev`, where criteria unlock off simulated evidence as you play. Registering on an already-live world takes
+effect immediately — no republish — and runs a backfill crediting players who already qualify. Full model:
+`multiplayer-logic` §19.
+
+## In-world products are registered separately too (and BEFORE the code that buys them)
+
+What a world sells is a per-world registry the bundle cannot express either: `helix.json` has no products block, and
+world code buys a product by the creator-authored key — `Helix.marketplace.purchaseProduct("speed_boost")` buys
+`pkey:speed_boost`, and an unregistered key returns `ProductNotFound` at runtime. Register with
+`register_world_product` / `helix product register <slug>` first, because the key is immutable once registered and the
+price lives server-side only (a world never sends an amount). Author what the purchase hands over as a `grants`
+effect array — pass | currency; several = a bundle, `[]` = a tip jar — which the backend fulfils **durably at
+settle** and the world reads back with `Helix.purchases.getEntitlements` (spend balances via `Helix.purchases.consume`,
+never a client-side counter); the effect list is as immutable as the key. Ordering against publish is practical, not
+enforced: nothing refuses a registration on a draft world — only the all-worlds creator listing (`helix product list`
+with no slug) filters to Published — but a **purchase** needs a live world (Published or Unlisted), so a product
+registered on a draft is simply unbuyable until the world ships. What a registration DOES need is the world ROW, so on
+a brand-new project run `create_world` / `helix world create --slug <slug> --title <title>` first — it mints the Draft
+with no build that both registries hang off, and without it every registration fails with `No world of yours has the
+slug ...`. Read the registry back with `list_world_products`. Test the whole loop first under `helix dev`
+(`.helix/dev-products.json` seeds the catalog; nothing is charged), and note a registration on an already-live world
+takes effect immediately — no republish.
+Full API: `sdk` → `Helix.marketplace` + `Helix.purchases`.
+
+World Products never mint universal items. For a portable Standard item or fixed-supply
+Collectible, publish an item definition, create a Marketplace or World distribution, and have world
+code request that distribution through the shell. Read `read_doc({ name: "items" })`; there is no raw
+`grantItem(itemId)` path.
+
 ## Preview video (YouTube)
 
-A world's detail page shows a carousel: the **thumbnail is always the cover**, and an optional
-**preview video** plays as an extra slide. Set it after the world is published:
+A world's detail page keeps its thumbnail as the cover and can show a YouTube
+video as an additional carousel slide. Set or clear it through the creator CLI:
 
-```
+```bash
 helix preview-video <slug> "https://www.youtube.com/watch?v=VIDEO_ID"
 helix preview-video <slug> --clear
 ```
 
-From an agent, the MCP tool is `set_preview_video({ slug, url })` / `set_preview_video({ slug, clear: true })`.
-From code, the SDK exports `setWorldPreviewVideo(slug, url, creds)` and `clearWorldPreviewVideo(slug, creds)`.
-
-**Video is referenced, never uploaded.** There is deliberately no way to upload an mp4/webm: the
-world's media slots take images only, and YouTube does the transcoding, adaptive streaming,
-moderation and bandwidth. We store an 11-character video id.
-
-Any usual link shape works — extra params like `&t=` and `&list=` are discarded:
-
-| accepted |
-| --- |
-| `https://www.youtube.com/watch?v=ID` |
-| `https://youtu.be/ID` |
-| `https://www.youtube.com/embed/ID` |
-| `https://www.youtube.com/shorts/ID` |
-| `https://www.youtube.com/live/ID` |
-| `ID` (a bare 11-character id) |
-
-The link is normalised and host-checked **server-side**, so a non-YouTube URL is rejected with a
-`400` rather than stored — there is no best-effort fallback. Don't pre-validate or rewrite the URL
-before sending it; pass what the human gave you and let the API be the one authority.
-
-> **Make the video earn its slide.** It sits alongside the thumbnail and screenshots, so a clip that
-> just re-shows the cover image gives players a carousel that says the same thing twice. Show
-> something the stills can't: movement, a mechanic, a moment.
+Video is referenced, never uploaded. Pass the creator's YouTube URL or bare
+video id through unchanged; the backend remains the authority for
+normalization and validation.
 
 ## Keeping the toolchain current
 

package/docs/purchases.md

@@ -0,0 +1,223 @@
+# In-world purchases (IWP) — selling things from a world
+
+How a world sells something and honours it afterwards. Four parties, and a world is only one of them:
+
+| Who | Does what | You reach it with |
+|---|---|---|
+| **The creator** | registers the products the world may sell | `register_world_product` (MCP) / `helix product` (CLI) |
+| **The shell** | raises the confirm popup, charges LIX, settles the sale | nothing — it is not yours to call |
+| **The backend** | fulfils the `grants` durably at settle, into entitlements | nothing — it writes, you read |
+| **Your world** | asks for a purchase, then reads what the player owns | `Helix.marketplace` · `Helix.purchases` · the `purchase` rule |
+
+**Your world never handles money.** It names a product, and reads entitlements back. It cannot mint a product,
+set a price, or write an entitlement — which is exactly why a player can trust it, and why the failure modes
+below are all about *reading* the truth rather than *keeping* it.
+
+Worked end-to-end world: `read_template({ name: "world-shop" })`. Room-side grammar:
+`read_doc({ name: "multiplayer-logic" })` §20. SDK signatures: `read_doc({ name: "sdk" })`.
+
+## 1. Register the product BEFORE writing the code that buys it
+
+`helix.json` has **no products block**, and nothing in world code can mint one. A world can only sell what its
+creator registered **on that world**, so `purchaseProduct` on an unregistered key returns `ProductNotFound` at
+runtime — which looks like a button that silently does nothing.
+
+```
+register_world_product({
+  worldSlug: "my-world",
+  key: "coin-pack",            // IMMUTABLE — world code buys `pkey:coin-pack`
+  title: "Coin Pack",
+  priceLix: 25,                // the ONLY place a price lives
+  grants: [{ kind: "currency", code: "coin", amount: 500, display: "wallet" }],
+})
+```
+
+- `dryRun: true` validates the whole shape locally — no network, works logged out.
+- The **key is immutable** (a rename would break every build naming it) and so is the **`grants` array** (it
+  would re-label every copy already sold). Choose both once.
+- **Registration does not need a published world; buying does.** A product on a draft world exists and lists
+  fine, and refuses to sell until the world is Published or Unlisted.
+- **It does need the world to exist.** On a brand-new project call **`create_world`** first (`helix world
+  create --slug <slug> --title <title>`): it mints the world row as a Draft with no build, which is all a
+  registration needs. Without it you get `No world of yours has the slug ...`.
+- **On a LIVE world, registration takes effect immediately — no republish.** The registry is server-side and
+  worlds read it at runtime, so a new product is buyable the moment it registers; only the world CODE that
+  names the key ships via publish. Same JSON as your `.helix/dev-products.json` seed — test under `helix dev`
+  first, register second.
+- `list_world_products` / `update_world_product` — update changes title, description, price and active state.
+  Never the key, never the grants.
+
+### The grant shapes
+
+| `kind` | Fields | Hands over |
+|---|---|---|
+| `currency` | `code`, `amount`, `display: "wallet" \| "uses"` | adds to a named server-held balance |
+| `pass` | `passKey` (defaults to the product key), `durationSeconds` | a server-held boolean; omit the duration for permanent |
+
+Several effects in one array = a **bundle** in one charge. An empty array = a **tip jar**. `priceLix: 0` = a
+free **Claim** the popup still confirms. Caps: **8 effects** per product, **16 distinct currency codes** per
+world; `code`/`passKey` are lowercase slugs (`^[a-z0-9][a-z0-9_-]{0,63}$`).
+
+**A permanent-pass-only product is capped at `maxPerUser: 1`** and registration refuses a higher value — a
+re-buy would charge again and deliver nothing new. Add a timed pass or a currency effect to make it re-buyable.
+
+World Products never mint universal items. For portable ownership, publish an item definition and create an
+ItemDistribution; read `read_doc({ name: "items" })`. Legacy item-grant rows may still appear during
+migration, but agents must not create new ones.
+
+## 2. Buy
+
+```ts
+const result = await Helix.marketplace.purchaseProduct('coin-pack');   // a bare key becomes pkey:coin-pack
+if (result.completed) refresh();
+```
+
+The shell raises the popup and settles. `PurchaseResult.status` is the canonical outcome:
+
+| Status | Means | `completed` |
+|---|---|---|
+| `Granted` | paid and delivered | ✅ |
+| `Claimed` | free claim delivered | ✅ |
+| `AlreadyOwned` | they already had it — **nothing charged, nothing new** | ✅ |
+| `Pending` | not a final answer — re-read with `getPurchase` | — |
+| `InsufficientFunds` · `MaxPerUserReached` · `ProductInactive` · `ProductNotFound` · `NotInWorld` · `Unauthorized` · `RateLimited` · `Failed` | refused, nothing charged | — |
+| `Cancelled` · `Timeout` · `NotFound` | client-side outcome; the true result may still be resolvable | — |
+| `PriceChanged` | the displayed price went stale; nothing charged, the shell re-prompts | — |
+
+**Branch on `completed`, not on `Granted`** — otherwise every free claim reads as a failure. And treat
+`AlreadyOwned` as "they have it", never as "a sale happened".
+
+Universal items use `purchaseDistributionKey`, `purchaseDistribution`, or `purchaseListing`; raw item ids
+are not purchase references. `getListings(query?)` browses active Marketplace distributions and listings.
+
+## 3. Read and spend what fulfilment granted
+
+```ts
+const ent = await Helix.purchases.getEntitlements();
+// { v: 1, passes: { vip: { since, expiresAt, active } }, balances: { coin: 740 }, owned: { 'starter-pack': 1 } }
+if (ent.passes.vip?.active) unlockLounge();
+
+const spent = await Helix.purchases.consume('potion', 1);   // { applied, balance, reason?: 'insufficient' }
+if (spent.applied) drinkPotion(); else offerShop(spent.balance);
+
+const off = Helix.purchases.onEntitlementsChanged(() => refresh());   // no payload — re-read
+```
+
+- **Server-held, backend-written.** Entitlements are the durable projection of every settled purchase in THIS
+  world for THIS player. A world reads and spends; it can never write.
+- `consume` is **atomic and floor-at-zero**: `applied: false` with `reason: 'insufficient'` left the balance
+  untouched. It is **idempotent per call** — a retry of the same call cannot double-spend, but calling it again
+  is a genuinely new spend.
+- Pass expiry is judged at read time via `active`.
+- **Preview mode (no shell)** resolves empty entitlements and an insufficient consume, so display code never
+  breaks the world loop.
+
+## 4. Surviving a reload mid-purchase
+
+Supply your own `idempotencyKey`, persist it, and re-read on boot. Without this, a tab that reloads during the
+popup leaves a player charged with your world unaware:
+
+```ts
+const key = localStorage.getItem('buy:coin-pack') ?? crypto.randomUUID();
+localStorage.setItem('buy:coin-pack', key);
+await Helix.marketplace.purchaseProduct('coin-pack', { idempotencyKey: key });
+
+// on boot:
+const prior = await Helix.purchases.getPurchase(key, 'coin-pack');   // PASS the ref
+if (prior?.completed) { localStorage.removeItem('buy:coin-pack'); refresh(); }
+```
+
+**Always pass the `ref`.** Without it the answer is bound only to (key, player, world), so a key that settled
+for one product would answer for any other.
+
+## 5. A custom confirm UI
+
+```ts
+const ctx = await Helix.marketplace.getPurchaseContext('vip-pass');
+// product + the player's live balance + eligibility + the grants effect list, in one call
+```
+
+The built-in popup uses this internally. You can render your own pre-confirm screen from it — but the popup
+still settles the sale, because consent to spend is the shell's job, not yours.
+
+## 6. Multiplayer — a sale reaches the room with no world code
+
+The shell settles, then the platform forwards the backend receipt to the room the buyer occupies, firing a
+`{"when":{"on":"purchase"}}` rule with `self` = the buyer.
+
+```jsonc
+{ "when": {"on":"purchase"},
+  "if":   {"op":"==","a":{"var":"purchase.productKey"},"b":"vip_pass"},
+  "then": [ {"do":"set","target":"self.tier","to":"vip"}, {"do":"save","player":"self"} ] }
+```
+
+- Readable only inside that rule: `purchase.productKey` and `purchase.purchaseId`. The event takes **no
+  params** — branch on the key in `if`.
+- **Exactly once per purchase**, platform-enforced. A re-forward, a rejoin, a dead tab and a second instance of
+  the world all collapse to one firing — **so grant durably** (`save`, `increment`, `submitScore`,
+  `awardAchievement`), never into state a disconnect resets.
+- Rules read the same entitlements: `{"op":"hasPass","passKey":"vip","of":"self"}` and
+  `{"op":"balanceOf","code":"coin","of":"self"}` (O(1), refreshed before the purchase rule runs), and spend
+  with `{"do":"consume","code":"coin","amount":10,"player":"self"}`.
+- A **guest seat owns no purchase**, so nothing fires for one.
+
+Full grammar and worked rules: `read_doc({ name: "multiplayer-logic" })` §20.
+
+## 7. Single-player worlds
+
+Everything in §1–§5 works with no multiplayer block at all — registration, buying, entitlements and consume are
+all shell/backend features. Only §6 needs a room. A single-player world applies the effect itself on
+`completed` and reads entitlements for anything durable.
+
+## 8. Footguns — every one of these fails silently
+
+- **Never mirror a pass or balance into client state, a playerVar or a roomVar.** A session copy resets while
+  the entitlement does not, and the two then disagree about money. Read the entitlement where you need it.
+- **Publish does not check the product registry.** A typo in a `passKey` or currency `code` publishes clean and
+  reads empty forever — `hasPass` false, `balanceOf` 0, deny by default.
+- **`of` is REQUIRED** on `hasPass`/`balanceOf`; there is no implicit `self`, and an entity ref is a publish error.
+- **Do not invent a manifest permission.** `Helix.marketplace` and `Helix.purchases` ride the world-scoped
+  session and need none — and the manifest is `additionalProperties: false`, so a guessed permission string is
+  a hard validation error, not a warning.
+- **A consumable bought under legacy `type: "consumable"` grants nothing durable** — your world applies the
+  effect on `Granted`, and a crashed tab loses it. Use a `currency` grant instead.
+- **The price is never sent by the world.** If you find yourself passing an amount, you are building the wrong
+  thing.
+
+## 9. Testing before you ship
+
+Register with `dryRun: true` to check shapes offline. Then actually execute your buy / grant / consume code —
+in preview mode (`vite preview`, no shell) none of it runs: `purchaseProduct` refuses, entitlements read empty,
+and the SDK warns once per method that it did nothing.
+
+**Start with `helix dev` — the simulated shell.** Build the world, then `helix dev` serves the built bundle
+inside a HELIX shell simulated on your machine: no login, no backend, no room, no engine clone, nothing to boot.
+It simulates the whole shell lane — `purchaseProduct`, `getPurchaseContext`, `getPurchase`, entitlements,
+`consume`, wallet, inventory, and the data store with the backend's real key policy — applies a product's
+`grants` to durable local state and fires `entitlements-changed`, so the code you wrote for a real sale is the
+code that runs. It enforces production's caps (30 data-store writes/min per player, 120 consumes/min, 256 KB per
+value), so a world that would be rate-limited live is rate-limited here. Products seed from
+`.helix/dev-products.json`, achievements from `.helix/dev-achievements.json` (criteria-bearing ones UNLOCK
+locally off the simulated evidence — see the sdk doc); the simulated player lives in `.helix/dev-state.json` and survives reloads
+(`--fresh` = a new player, `--reset` = wipe). Every answer is console-logged `[helix dev · SIMULATED]` under a
+permanent banner — the mode is *simulated*, never "test", and it spends nothing real.
+
+It raises the shell's purchase confirm dialog too (Buy / Cancel with real price and balance figures), so the
+player-cancelled path — `Cancelled`, nothing charged, nothing recorded, a retry confirms again — is testable
+locally. Its debug menu is what you cannot get anywhere else: **Purchases Always Fail** (cycling
+`InsufficientFunds` → `PriceChanged` → a throw that leaves the purchase `Pending`), **Force Save Failure**,
+**Exhaust Consume Fence**, grant / remove an entitlement by hand. §8's footguns are all silent failures — this
+is how you make them loud. Full reference: `read_doc({ name: "sdk" })`.
+
+**What the simulator cannot prove.** It never charges, escrows or fulfils anything, and it mints **no receipt** —
+so nothing settles, and §6's `purchase` rule never fires. It cannot tell you a product is genuinely registered
+(only `list_world_products` against the real backend can), and it exercises no room-lane behaviour at all: DSL
+rules, the `consume` / `save` verbs, `awardAchievement`, multiplayer. Treat a green `helix dev` run as "my world
+handles the answers correctly", never as "the sale works".
+
+**Then cross-check on the dev stack — the real pipeline.**
+`node helix-web-engine-new/tools/dev-stack/dev-stack.mjs up iwp-shop` (single-player) or `up iwp-mp` (the room
+harness) boots the backend, the room and the economy service, seeds products and funds a wallet, so a purchase
+settles end to end against real services rather than a mock. Run the same world both ways and compare: when
+`helix dev` and the dev stack answer differently, that is signal, not noise — one of them is wrong, and it is
+worth knowing which.

package/docs/scene-performance.md

@@ -0,0 +1,64 @@
+# Scene performance: measure the first build
+
+Run `analyze_scene_performance` as soon as an imported or generated Scene has its first build. Repeat it after material, lighting, streaming, or geometry changes and on the exact release candidate.
+
+```text
+analyze_scene_performance({
+  directory: "/absolute/path/to/generated",
+  scene: "/absolute/path/to/generated/scene.helix-scene.json",
+  package: "/absolute/path/to/generated/continuum-package-version.json",
+  snapshot: "/absolute/path/to/qa/inspect.json",
+  perf: "/absolute/path/to/qa/perf.json",
+  profile: "web-desktop-balanced"
+})
+```
+
+The terminal equivalent is `helix world performance-report generated --scene <scene> --package <package> --snapshot <snapshot> --perf <receipt>`. Its `estimated-budget-utilization` compares facts to an existing Palette Showcase device profile. This is a useful reference tier, not a universal Scene promise. Unknown residency, GPU allocation, shader, transparency, or pass costs stay unknown and cannot improve the rating. Static counts never predict FPS.
+
+The analyzer runs the canonical Scene v2 and Continuum Package validators before counting. It accepts a structurally valid older Scene's declared capabilities and extensions for analysis; that does not prove the target runtime supports them. Missing or mismatched local bundle resources, paths that escape the Scene directory, invalid contracts, and an FPS claim that contradicts its rendered-frame count and duration fail the report. Vault or other non-bundle resources stay explicitly unresolved, make affected counters and reference checks unknown, and require exact resolved bytes or runtime evidence.
+
+Start from platform-owned defaults when they preserve the scene: use an existing Palette material Package for common material families and the built-in visual runtime for lighting and grade. Consider actual lightmaps for suitable static surfaces only after the importer/runtime/shell path is verified. Keep authored PBR, dynamic lights, or probes where the intended look, movement, or editability requires them. Confirm the renderer consumed each native binding; Package dependencies and provenance are not live-binding proof.
+
+## Read each counter literally
+
+| Counter | Meaning | It does not mean |
+|---|---|---|
+| `meshDefinitionTriangles` | triangle sum across authored render mesh definitions in exact Scene resources | triangles submitted per frame |
+| `visibleSceneTriangles` | visible geometry in one inspection snapshot | worst-case submitted geometry |
+| `submittedTriangles` | renderer submissions measured on the driven route, including repeated placements and passes | unique authored geometry |
+| `uniqueVisualMaterials` | visual definitions after texture refs resolve to external or embedded content hashes; names/provenance extras are ignored and visual extensions remain | file records, slots, or programs |
+| `fileLocalMaterialRecords` | sum of GLB `materials[]` records | visually distinct looks |
+| `materialSlots` | mesh primitive/material slots | shader programs |
+| `sourceBoundSurfaces` | Scene v2 `surfaces[].default.kind: "source"` | Palette bindings |
+| `nativeMaterialBoundSurfaces` | Scene v2 surfaces using native material definitions | live Palette shader use |
+| `packageNativeBindings` | exact Package id/version/manifest CID material bindings | Vault pins or live Palette use |
+| `observedPaletteBindings` | a renderer probe explicitly counted live Palette bindings | material Package provenance |
+| `materialKtx2Resources` | Scene-owned KTX2 resources actually referenced by render-material texture slots | every declared texture resource or GPU residency |
+
+Do not invent Vault pins to close a Package-native gap. A legacy Scene can have Palette dependencies in Package provenance while every surface remains source-bound.
+
+`assetLocalDraws` estimates GLB submissions from placements. Repeated source objects are only review candidates: material-batched modules may already collapse them into fewer draws, while instancing can add draws or create broad bounds that cull poorly. Compare the current material-batch draw count with proposed instance draws and active instance bounds/cell culling on the same route. Runtime instancing also requires repeated top-level Scene nodes that reference the same eligible single-static-mesh/single-primitive resource.
+
+## Delivery and memory are separate
+
+- `declaredOwnedBytes` is the Scene document plus exact resources in its table. Unattached directory files are reported separately.
+- `transitiveClosureBytes` is reachability, not actual transfer.
+- Cold and warm transfer require deliberate separate runs. Cached `transferSize: 0` entries do not prove zero cold cost.
+- Compressed KTX2 bytes are not GPU memory. 1K maps are a strong default, but separate base/normal/ORM maps can raise cold bytes.
+- ReadySets or stream groups shape first-frame residency. Dependency count does not.
+
+## Runtime evidence remains a supplied claim
+
+A JSON file can claim any FPS. The analyzer uses `supplied-unbound` unless exact entry and Scene hashes match and the receipt includes hardware renderer, exact browser build, build revision, Scene identity, viewport, DPR, effective quality profile, and explicit frame cap including `null`. Even then it says `supplied-identity-matched`: hashes bind bytes, not measurement origin. A harness that owns the capture may make a stronger verified-run claim in its own output.
+
+Wait for compilation idle, the declared stream closure, and a recorded GI-asleep quiet interval before sampling. Apply the same ordered preconditioning, then drive a grounded walk through the same midpoint. Report rendered frames and duration alongside FPS and frame percentiles; do not substitute an average of sampled reciprocal FPS or a fly route. Record avatar and vehicle occupancy, the rendered bundle SHA, and a digest of dirty code. Keep the compositor's internal resolution separate from canvas size and DPR. A frame cap explains a plateau; reaching it does not prove spare headroom. Include draw calls, submitted triangles, shader programs, pass multipliers, shadow-casting and punctual lights, GPU texture allocation, and observed Palette count when available.
+
+## Fix costs without trading away the scene
+
+Use the built-in visual runtime. Before planning lightmaps, verify that the active importer preserves lightmap UVs and that the target runtime and shell consume the binding. A probe-field consumer does not establish a shipped shell lightmap path. Where the whole path is verified, lightmaps can remove suitable dynamic light work for truly static surfaces. For probe baking, follow `read_doc({ name: "lighting-world" })` and the canonical `helix bake-lighting` route, freeze the authored sun/time path, and keep movable avatars and vehicles outside immutable architectural transport. Keep gameplay/moving lights and required editability; limit range and decorative shadows. Baked probes avoid live captures but still sample per fragment. They are not lightmaps, and “baked” does not mean fast.
+
+Treat transmission, GI/probe sampling, and shadows as pass multipliers. Huge frosted panes can dominate through transmission/upscale paths with unchanged authored triangles. Change a feature only after a matched ablation identifies it.
+
+## Visual QA closes the optimization
+
+A capped low-resolution screenshot is not fullscreen proof. Compare before and after on the same camera route, exposure, time of day, viewport, DPR, effective quality, and frame cap. Drive while measuring, then inspect close views for stone/wood normal shimmer, frosted-glass errors, contact-shadow loss, and light leaks. An FPS gain that loses those properties is not a successful optimization.

package/docs/screenshots.md

@@ -0,0 +1,140 @@
+# HELIX Instant — World Screenshots & Thumbnails
+
+`publish_world` / `helix publish` now automatically capture a ready-world cover when no selected custom thumbnail exists. The image is verified and assigned atomically with the Build; capture failure refuses publication before World/Build writes. Register a `hero` shot and call `screenshots.ready` after assets load. Automatic covers refresh per Build; selected custom covers are preserved. Pass `thumbnail` / `--thumbnail` to select a cover without automatic capture. Manual capture/inspect/attach below remains the workflow for selecting custom media and optional preview images.
+
+Native Scene v2, semantic Continuum Releases and Unreal/shared-runtime promotion currently require a selected custom cover. They explicitly fail with `WORLD_THUMBNAIL_CAPTURE_UNSUPPORTED` if no cover exists; automatic capture adapters for those runtimes are not integrated. This is a publication failure, never a successful generic placeholder.
+
+
+Every published world starts with a generated placeholder image. This doc covers capturing a real,
+deterministic screenshot of your world and deliberately attaching it as the world's `thumbnail`/`preview`.
+Capturing is local and non-destructive — it never touches the published world; attaching is a separate,
+explicit step.
+
+## 1. Declare a hero shot in world code
+
+Two calls, both cheap no-ops during normal play — they only activate when the page is loaded with
+`?helixScreenshot=1`, which `capture_world_screenshot` (and the `helix screenshot` CLI command) do for you:
+
+```ts
+import { screenshots } from '@helix/engine-core/screenshot';
+screenshots.register('hero', { position: [12, 8, -20], lookAt: [0, 2, 0], fov: 55 });
+// ...after your world's own async setup resolves, right before the render loop starts:
+screenshots.ready({ renderer, scene, camera });
+```
+
+`scaffold_world` wires this in `src/main.ts` with a placeholder pose — adjust `position`/`lookAt`/`fov`
+to frame your scene. (True from helix-cli 0.1.13-helix3.79 onward. Earlier scaffolds emitted the
+`engine-core` pin but none of the wiring, so `capture_world_screenshot` timed out on a brand-new world
+and the error told you to do what the scaffold claimed to have done. On an older project, follow §9.) `renderer`/`scene`/`camera` are required: a capture applies the registered pose to your
+world's own camera for the frame and restores it afterwards — no separate camera is created.
+
+**Keep the placeholder body out of frame.** Headless captures run logged out, so the local player renders as
+the bare default mannequin — usually not what you want standing in your cover shot. `ready()` takes an optional
+`hide` list of scene objects made invisible for the whole screenshot session (a no-op during normal play):
+
+```ts
+screenshots.ready({ renderer, scene, camera, hide: [mp.local.model] });
+```
+
+Needs `engine-core >= 0.1.1`. Omit `hide` (or leave the list empty) if you deliberately want the character in frame.
+
+## 2. Shot naming & warmup
+
+- Name shots by what they show, not by number — `hero`, `overview`, `arena`. Register more than one if it
+  helps; `capture_world_screenshot` captures every declared shot by default, or a single one via `shot`.
+- The default warmup (a handful of rendered frames) is enough for a static scene but not for physics settling
+  (ragdolls, dropped props, water). Pass a per-shot `warmupMs` — `screenshots.register('hero', { position, lookAt, fov, warmupMs: 500 })` — so the world visibly settles before the frame is grabbed.
+
+## 3. The workflow: capture → inspect → iterate → attach
+
+1. Build the world (`npm run build`).
+2. `capture_world_screenshot({ directory: "<dist>" })` — runs headless Chromium in-process (the same code
+   path as `helix screenshot`), writes PNGs to disk, and returns a preview image per capture so you can
+   actually see the framing, not just a file path.
+3. Look at the returned image. Framing off? The fast lane is the pose override — `capture_world_screenshot({
+   directory, camera: [x, y, z], lookAt: [x, y, z], fov })` renders exactly that one pose (written as
+   `custom.png`) with NO rebuild, so you can audition angles rapidly; add `previewImages: 1` to keep each
+   iteration cheap. A single declared shot re-captures via `shot: "name"`. Once you like the frame, bake the
+   winning numbers into `screenshots.register(...)` and rebuild so the shot is stable for everyone.
+4. Once you're satisfied, run `helix thumbnail set <slug> <file>` to attach it. Never skip straight to
+   attaching a capture you haven't looked at.
+
+The same flow is available from the terminal: `helix screenshot <dist>` then `helix thumbnail set <slug> <file>`.
+
+## 4. The two slots
+
+- **`thumbnail`** — the world's cover image everywhere: catalog cards, the detail page's first carousel
+  slide, the loading screen. Target 1280×720.
+- **`preview`** — one extra detail-carousel slide, optional. Target 2560×1440 — capture with `preview: true`
+  to also get the 2560×1440 variant of each shot.
+
+`helix thumbnail set <slug> <file> --kind preview` fills the second slot; omit `--kind` for `thumbnail`.
+
+## 5. The anti-churn policy
+
+- Publishing preserves a selected custom cover. Otherwise `publish_world` assigns supplied/bundled
+  artwork or automatically captures the ready Web Build and assigns its cover during activation.
+  Later publications refresh automatic covers; native/semantic publication requires a selected cover.
+- Filling an **empty** slot is a normal finishing step — do it without asking.
+- Replacing an **occupied** slot requires `overwrite: true`, and you should only pass it when the human
+  explicitly asked for a replacement. Without it, `helix thumbnail set` refuses and returns the current URL
+  so you can relay the situation instead of silently skipping it.
+- When a change materially alters the world's visuals, suggest a retake to the human and stop — never
+  recapture and overwrite on your own judgment.
+
+## 6. The `screenshots/` folder
+
+Captures land on disk — by default a `screenshots/` folder next to the built bundle directory, or wherever
+`out` points. It's there so you and the human can inspect files directly; it's excluded from publish
+bundling, so nothing in it ever ships with the world.
+
+## 7. Blind mode — a labeled last resort
+
+A world published before it integrated the screenshot helper has no `window.__helixScreenshots` to drive.
+`capture_world_screenshot({ directory, blindMs: 800 })` waits `blindMs` milliseconds, then screenshots the
+canvas exactly as it looks — no declared pose, no warmup guarantee. The result is clearly labeled
+non-deterministic; treat it as a stopgap, not a stable thumbnail source. Prefer republishing the world with
+a declared shot instead.
+
+## 8. Capture as eyes while you build (optional)
+
+Attaching thumbnails is the finishing step, but `capture_world_screenshot` is useful earlier too: when you
+have no browser tool, it is the only way to actually SEE the world you are editing. Rebuild, capture, look
+at the returned image — a placed model, a material, lighting, scene layout, all confirmable without leaving
+the loop. The `camera`/`lookAt`/`fov` override inspects any angle without touching world code, and even a
+failed capture reports the page's boot errors, so it doubles as a headless smoke test.
+
+Use it deliberately, not habitually:
+
+- Capture when a change is **visual** and you cannot confirm it any other way. Skip it for logic-only
+  changes — every capture costs a build plus several seconds, and image results are heavy.
+- One well-chosen angle beats a burst of captures. Prefer the declared shots you already framed.
+- If a live browser tool (e.g. a Chrome MCP) is available, prefer it for interactive debugging — console,
+  network, clicking. Headless capture is the no-browser fallback and the framing-exact check, not a
+  replacement for a real browser session.
+
+## 9. Adding the helper to an existing world
+
+A world scaffolded before the helper moved to its own package needs these steps:
+
+1. Add `"engine-core": "^0.1.0"` to `public/helix.json` → `systems` (alongside `humanoid-character`).
+2. Resolve it: `install_world_packages` (or the CLI's `helix install`).
+3. If `vite.config.ts` predates the engine-core aliases, add these three lines to `resolve.alias`
+   BEFORE any `@helix/humanoid-character` entry — subpath aliases must precede the root alias, or
+   rollup's prefix substitution mangles `@helix/engine-core/screenshot` into an ENOENT:
+
+   ```ts
+   '@helix/engine-core/screenshot': fileURLToPath(new URL('./public/helix_modules/engine-core/screenshot/index.js', import.meta.url)),
+   '@helix/engine-core/world-camera': fileURLToPath(new URL('./public/helix_modules/engine-core/world-camera/index.js', import.meta.url)),
+   '@helix/engine-core': fileURLToPath(new URL('./public/helix_modules/engine-core/index.js', import.meta.url)),
+   ```
+
+4. Add the integration lines from §1 to `src/main.ts`:
+
+   ```ts
+   import { screenshots } from '@helix/engine-core/screenshot';
+   screenshots.register('hero', { position: [12, 8, -20], lookAt: [0, 2, 0], fov: 55 });
+   screenshots.ready({ renderer, scene, camera });
+   ```
+
+5. Rebuild (`npm run build`), then capture as usual: `capture_world_screenshot`.