Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(forge,marketplace): ship the prompt studio and marketplace updates with the regenerated feed
nirholas0d93284196dd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex afa351d7e..62be492de 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -29,6 +29,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Eight build tutorials now match what the platform actually does**: An audit of eight tutorials found instructions that could not work. The AI-brain tutorial described a model line-up that had been superseded: it never mentioned the Claude 5 family (Sonnet 5, Opus 5, Fable 5), which are live and selectable, and it recommended Sonnet 4.6 as the default. It also sent you to screens that do not exist, telling you to add API keys under a gear icon in My Agents and to change models, sampling knobs, and streaming under a Brain menu. Provider keys actually live in the AI Provider Keys panel on your account page, the model is a field on the agent's embed policy, and streaming has no off-switch. The promised usage tab with token charts and threshold emails did not exist either; the tutorial now documents the real per-agent usage read and points at the monthly quota and per-minute rate limit, which are the controls actually enforced before your money is spent. It also now explains that a visitor can never escalate your agent onto a paid model. The custom-GLB tutorial was worse for anyone following along: it linked a Studio address that no longer resolves, and four of its commands invoked gltf-transform subcommands that have never existed, so converting an FBX, renaming animation clips, and the full Mixamo walkthrough all failed at the first step. Those are replaced with the converter the platform itself uses and a clip-renaming script that was run against a real avatar to confirm it works. Its Draco flag was wrong, its upload path pointed at the wrong page, and it still warned that an avatar without an idle clip would stand frozen in a T-pose, which stopped being true when animation retargeting became universal. Finally, the page-events tutorial listed the wrong fallback order for emote animations. (`/tutorials/connect-ai-brain`) `[docs, fix]`- **Looking up an on-chain agent by its CAIP reference works again**: The public resolver that turns an ERC-8004 agent reference into its owner, token URI and verified agent card could not be reached at all. An agent reference ends in a slash before its token id, and the documentation told callers to percent-encode the whole reference, which turns that slash into %2F. The API refuses any address segment holding an encoded separator, because that is the same trick used to escape a path and reach files that were never meant to be served, so every correctly-formed lookup was turned away as an unknown address before it ever reached the resolver. The verification badge you can embed on your own site built its request in exactly that shape, so it never showed a result either. The resolver now accepts the reference with its slash as a normal part of the address, the badge asks for it that way, and the documentation shows the form that works. The protection against encoded separators is untouched. New tests resolve the address through the same routing the live site uses, so this cannot quietly break again. (`/docs/api-reference`) `[fix]`- **Oracle stops answering "nothing is happening" when the database is the thing that is down**: Several Oracle reads shared a habit: if the database was unreachable for a few seconds, they answered normally with an empty result. The movers panel said nothing was moving, the stats hero said no coin had ever been scored and no agent was armed, a coin's conviction sparkline came back flat, and the machine-readable signal endpoint told autonomous agents there were no plays, which is exactly the cue for an agent to stand down. Every one of those answers was then cached at the edge for a minute or two, so a blip lasting seconds kept showing a dead market long after the database was back. Those endpoints now tell the difference between a connectivity failure and an ordinary query fault: the first is reported honestly as a temporary outage with a retry hint and is never cached, the second still degrades to the empty answer it always did. The social ingest got the sharper end of the same bug: it used to reply that a batch had been accepted while reporting zero mints written, a receipt for a write that never landed. It now fails loudly so the sender retries. Shared conviction cards behave too: one built during an outage is no longer pinned to a coin's link preview for 15 minutes. (`/oracle`) `[fix, improvement]`+- **Pages stop loading a 3D robot you have not scrolled to yet**: The small animated robot in the site footer was starting up the moment a page opened, at the bottom of a page nobody had scrolled to. On plain pages that meant downloading a whole second 3D engine (253 KB) before anything else, and on the Forge it was the single busiest thing on the page: nearly 20 seconds of browser work, more than the Forge itself. It now waits until you are about a screen away from the footer, so it still greets you on the way down but no longer competes with the page you actually opened. It also stops taking a 3D slot away from the avatars on the page, which on a busy grid could leave a real avatar unable to render. Separately, the Forge's example prompt chips no longer shove the page down as they shuffle to a fresh set on load. (`/forge`) `[improvement, fix]`- **Paying for a skill by Solana Pay QR now shows a real three.ws merchant card**: When a wallet scans a Solana Pay code for a skill purchase, it first asks our server who the merchant is and shows the answer in the sheet you approve before signing. That reply pointed at a logo file that has never existed, so the icon came back as a 404 and the merchant appeared broken at the exact moment you decide whether to pay, under the retired 3D-Agent name rather than three.ws. The probe now returns the live logo and the current name, and answers wallets that ask from a browser, which the Solana Pay spec requires. Confirming a purchase through the off-web webhook also accepts the settlement hash an EVM payment needs, so a card that settled on Base can finish instead of sitting on pending forever, and a confirmation failure now reaches our error tracker rather than disappearing into a generic 500. (`/marketplace`) `[fix]`- **Pinning an avatar to IPFS works for real avatars, not just tiny ones**: Minting an avatar from the Avatar Studio pins the model and its metadata to IPFS, and the whole file is sent through the platform so the storage credential never has to reach your browser. The endpoint said it accepted files up to 10 MB, but it was actually rejecting anything over roughly 730 KB, which is smaller than almost any real avatar. The error it gave back was a bare 'payload too large' that named no limit, so there was nothing to act on. The cause was two size limits that had never been reconciled: files are sent as text, which makes them a third larger in transit, and the transport limit was left at its default while the documented limit was set eight times higher. The limits now agree. Inline uploads are accepted up to 5 MB, which is what the request size can actually carry, and anything larger has a clear path: upload it to storage first and pin it by URL, a lane that has always accepted 50 MB. Over-sized uploads now say which ceiling was crossed. Two smaller fixes came with it: the filename you send is now the filename filed with the storage provider, instead of every avatar being stored as 'avatar.glb' and every metadata file as 'manifest.json', which made a pin list impossible to read; and a request with a genuine mistake in it, such as a file from somewhere the platform does not own, now gets an error explaining the mistake rather than a generic 'service unavailable' that hid it. The endpoint is now documented in the API reference. `[fix, docs]`- **Plan checkout: a paid upgrade can only ever settle on real mainnet, and a late payment is no longer stranded**: Paying for a plan creates a quote, you send the funds, then the server checks the chain before it upgrades you. Three things in that path were wrong. The checkout side has always refused test-network quotes in production, because test-network dollars are free from a faucet, but the confirm side still let a caller name the test network itself, and it is the confirm side that decides which chain it looks at and which dollar it accepts. Both ends now read the same setting, so a production upgrade can only ever be settled by real funds on mainnet. Second, an Ethereum-side payment has to wait twelve blocks before it counts, which meant funds sent near the end of a session could land on-chain and then be refused for arriving late, with the money already gone; that lane now honors the same one-hour grace window the Solana lane has, so an on-chain payment is always claimable. Third, confirming an Ethereum payment could reach a Solana quote and mark it expired, and asking to buy a skill from a malformed agent id answered a generic server error instead of telling you what was wrong with the request. (`/pricing`) `[fix, security]`diff --git a/data/changelog.json b/data/changelog.jsonindex 23a09fa83..6ca646fae 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-08-15",+ "title": "Pages stop loading a 3D robot you have not scrolled to yet",+ "summary": "The small animated robot in the site footer was starting up the moment a page opened, at the bottom of a page nobody had scrolled to. On plain pages that meant downloading a whole second 3D engine (253 KB) before anything else, and on the Forge it was the single busiest thing on the page: nearly 20 seconds of browser work, more than the Forge itself. It now waits until you are about a screen away from the footer, so it still greets you on the way down but no longer competes with the page you actually opened. It also stops taking a 3D slot away from the avatars on the page, which on a busy grid could leave a real avatar unable to render. Separately, the Forge's example prompt chips no longer shove the page down as they shuffle to a fresh set on load.",+ "tags": [+ "improvement",+ "fix"+ ],+ "link": "/forge"+ },{"date": "2026-08-15","title": "Posed avatar renders finally come out posed",diff --git a/docs/site-performance.md b/docs/site-performance.mdindex 50c941216..9e970b25b 100644--- a/docs/site-performance.md+++ b/docs/site-performance.md@@ -29,25 +29,39 @@ Two things to know before reading a report:- **The score is not the byte count.** Performance is weighted Total Blocking Time 30%, Largest Contentful Paint 25%, Cumulative Layout Shift 25%, First Contentful Paint 10%, Speed Index 10%. A page can ship 4 MB and score well if none of it blocks; a page can ship 900 KB and score badly if all of it runs at once.- **Lighthouse 13 removed the audits everyone quotes.** `offscreen-images`, `uses-responsive-images`, `modern-image-formats` and `dom-size` are gone, replaced by the insight family: `image-delivery-insight`, `render-blocking-insight`, `cache-insight`, `legacy-javascript-insight`, `cls-culprits-insight`. A script that reads the old audit names throws on `undefined`.+- **Keep `--disable-gpu`. Do not "improve" it to software WebGL.** Swapping it for `--use-gl=angle --use-angle=swiftshader` looks more faithful, since the 3D pages then really run their renderers, and it does not survive contact with this site: in the 2026-08-15 sweep that flag set made `/` and `/marketplace` abort with `PAGE_HUNG`, `/play` report `NO_FCP`, and `/marketplace` still fail with `PROTOCOL_TIMEOUT` at a 90s `--max-wait-for-load` on a completely idle machine. The same pages complete in about two minutes each with `--disable-gpu`. Software rasterization of our own WebGL is slower than the throttling Lighthouse is trying to apply, so the run measures the rasterizer rather than the page.+- **Check `environment.benchmarkIndex` in every report before quoting its score.** A shared build machine swings it wildly: the 2026-08-15 sweep saw 108 on one `/create` run and 2,398 on a `/` run twenty minutes later, and the low reading inflates every CPU-bound metric in that report. A run under roughly 800 is worth repeating on an idle machine rather than recording.-## The 2026-08-14 baseline+## Where the numbers are-Every page named in this table was measured against `https://three.ws` with Lighthouse 13.4.1 on 2026-08-14. **This is the baseline, not the current state**: the live build at the time was commit `0496089f0`, stamped `2026-08-14T01:24:52Z`, which predates rules 1, 2, 3 and the model-viewer half of rule 4, plus the chip fix in `a789c2f90`. Every one of those is committed and none of them was deployed when these numbers were taken, so treat the table as the problem statement each rule below was written against.+Two sweeps, same eight pages, same tool (Lighthouse 13.4.1), same flags, three weeks apart in build terms. The first is the problem statement the rules below were written against; the second is what the deployed rules are worth.-| Page | Desktop | Mobile | Desktop TBT | Desktop CLS | Desktop bytes |-|---|---|---|---|---|---|-| `/` | 33 | 25 | 19,340ms | 0.009 | 3,715 KiB |-| `/create` | 38 | 25 | 6,940ms | 0.013 | 1,892 KiB |-| `/forge` | 32 | 20 | 12,560ms | 0.232 | 4,243 KiB |-| `/marketplace` | 23 | 17 | 51,400ms | 0.178 | 4,748 KiB |-| `/play` | 31 | 25 | 5,870ms | 0 | 2,317 KiB |-| `/docs` | 39 | 35 | 4,490ms | 0.028 | 701 KiB |-| `/discover` | 54 | 44 | 11,010ms | 0.022 | 10,952 KiB |-| `/chat` | 28 | 25 | 6,390ms | 0.001 | 4,435 KiB |+**2026-08-14**, against commit `0496089f0` (stamped `2026-08-14T01:24:52Z`), which predates rules 1, 2, 3 and the model-viewer half of rule 4.-Total blocking time is what holds every one of these scores down, and it is 30% of the weighting on its own. Read the table by that column, not by the score.+**2026-08-15**, against commit `7505b83ca` (stamped `2026-08-15T07:08:00Z`), which contains all of them.-Two caveats worth knowing when you compare a later run against this one. The runs were taken on a shared build machine with other work in flight, so single-page scores move a few points between runs: `/create` measured 50 in a quieter run earlier the same day and 38 here. And `/marketplace` is heavy enough that Lighthouse itself gave up with `PROTOCOL_TIMEOUT` on the first attempt and needed a 90s `--max-wait-for-load` to complete at all, which is a finding in its own right.+| Page | Desktop 08-14 | Desktop 08-15 | Mobile 08-14 | Mobile 08-15 | Desktop TBT 08-14 | Desktop TBT 08-15 |+|---|---|---|---|---|---|---|+| `/` | 33 | **91** | 25 | 48 | 19,340ms | 134ms |+| `/create` | 38 | **94** | 25 | 51 | 6,940ms | 0ms |+| `/forge` | 32 | **75** | 20 | 31 | 12,560ms | 55ms |+| `/marketplace` | 23 | **58** | 17 | 20 | 51,400ms | 168ms |+| `/play` | 31 | **83** | 25 | 41 | 5,870ms | 101ms |+| `/docs` | 39 | **93** | 35 | 47 | 4,490ms | 107ms |+| `/discover` | 54 | **88** | 44 | 58 | 11,010ms | 266ms |+| `/chat` | 28 | **60** | 25 | 55 | 6,390ms | 0ms |++Total blocking time was what held every score in the first column down, and it is 30% of the weighting on its own. It is now effectively gone from all eight pages. **Read a Lighthouse report by which metric is losing the points, not by the score**, because the answer changes once you fix something: on the three pages still under 80, blocking time now costs 4.2 points at worst and the loss has moved somewhere else entirely.++| Page still under 80 | Losing | To |+|---|---|---|+| `/forge` 75 | 13.3 pts | CLS 0.260, of which 0.190 is one shift on the example-prompt row (rule 6) |+| `/marketplace` 58 | 19.8 pts + 13.0 pts | LCP 3,649ms, and CLS 0.257 of which 0.178 is one shift on the podium (rule 5) |+| `/chat` 60 | 21.0 + 9.9 + 9.0 pts | LCP, FCP and Speed Index, all of them one 4,277 KiB chunk (see the open items) |++Full desktop detail for the 2026-08-15 run: CLS `/` 0.002, `/create` 0.014, `/forge` 0.260, `/marketplace` 0.257, `/play` 0.000, `/docs` 0.043, `/discover` 0.044, `/chat` 0.001. Transferred bytes `/` 3,272 KiB, `/create` 1,804 KiB, `/forge` 8,254 KiB, `/marketplace` 3,987 KiB, `/play` 2,265 KiB, `/docs` 706 KiB, `/discover` 4,885 KiB, `/chat` 4,627 KiB.++Both sweeps were taken on a shared build machine, so single-page scores move a few points between runs; see the `benchmarkIndex` note above before quoting one.---@@ -118,6 +132,39 @@ Measured honestly, that last one is the smallest of the three: at 1350x940 the s**A new `<model-viewer>` on a multi-viewer page ships `data-src`, or it is eager.** There is no third option, and the attribute that looks like it should handle this does not.+### The site footer is the lowest thing on every page, so its 3D bot loads last++The rule above was written about sections. The most expensive violation of it was not a section at all: it was the decorative robot in the site footer, and it was costing more than everything the rule had already caught.++[public/footer.js](../public/footer.js) injects `/footer.html` into any page holding `<div id="footer-container">`, which is roughly 175 pages. That markup contains `#footer-bot-canvas`, and the injector booted its renderer immediately, at `DOMContentLoaded`, down one of two branches:++- A page carrying `<meta name="has-three-bundle">` (every Vite-built page) loaded `/footer-bot.js`, which builds a `WebGLRenderer`, claims a context off the shared budget in [src/webgl-budget.js](../src/webgl-budget.js), and loads `robotexpressive.glb`.+- A plain HTML page (login, register, the dashboard, `/docs`, `/discover`) instead pulled **`model-viewer` from `ajax.googleapis.com`, a second complete 3D engine**, plus the meshopt shim and the same GLB.++Measured against production on 2026-08-15, that decoration was the single largest main-thread consumer on the page it landed on:++| Page | Branch | Cost, eager |+|---|---|---|+| `/forge` | `footer-bot.js` | **19,654ms** of bootup, more than the page's own bundle (1,473ms) |+| `/docs` | `model-viewer` | 839ms of bootup and 253 KiB transferred, on a 701 KiB page |+| `/create` | `footer-bot.js` | 107 KiB GLB plus a WebGL context, on a page already running Three.js |++`loading="lazy"` on the `<model-viewer>` element did not help, and could not: it defers the *model*, while the 253 KiB module that defines the element had already been fetched and evaluated.++Both branches now sit behind `whenNearViewport()` in the same file, an `IntersectionObserver` on `.h-footer-avatar` at `rootMargin: '600px 0px'`, so the bot loads a screenful before the footer arrives and is rendered by the time it is on screen. Browsers without `IntersectionObserver` load it on the first scroll instead, so it still appears on the way down rather than never.++Verified by loading the real production pages twice in the same browser, the second time with only `/footer.js` swapped for the working-tree file, then scrolling to the footer to confirm the bot still arrives:++| Page | Transferred, before | after | Long tasks, before | after | Footer bot loaded on open | after scrolling |+|---|---|---|---|---|---|---|+| `/docs` | 675 KiB | **426 KiB** | 62ms | **17ms** | yes | yes |+| `/forge` | 7,379 KiB | 7,283 KiB | 426ms | **138ms** | yes | yes |+| `/create` | 2,215 KiB | **1,528 KiB** | 8,422ms | **2,510ms** | yes | yes |++Deferring it also fixes an ordering bug nobody had filed. The footer bot reserved a WebGL context at `DOMContentLoaded`, ahead of the `<agent-3d>` instances the visitor came to look at; on a page near the browser's context limit the decoration could win and a real avatar lose. Now the content claims contexts first and the footer takes what is left, which is what `reserveWebGLContext()` was always for. The bot's own failure path already degrades to an empty canvas, so losing that race is silent and harmless.++**Anything injected into a shared chrome partial follows this rule too.** A cost paid in the footer is a cost paid on every page on the site, which makes it the most expensive place on the platform to be careless.+**Before you gate something, check where it actually is.** Paste this into DevTools:```js@@ -138,6 +185,22 @@ The box is reserved by CSS rather than by `width`/`height` attributes, because t**A reserved box is not optional.** If you add a thumbnail whose container has no `aspect-ratio` and no fixed height, add one, or the late image will shift everything under it.+### A skeleton only reserves the box if it is the same size as the thing it replaces++`/marketplace` had a skeleton, a comment saying it existed "so there's no layout jump when data arrives", and the largest layout shift on the page. Both halves of it were wrong, and each is worth recognising on sight.++**A section that JavaScript reveals reserves nothing.** `#mkt-top-section` shipped `hidden`, and `loadTopPerformers()` in [src/marketplace.js](../src/marketplace.js) cleared that only once it ran. `hidden` is `display: none`, so until the page bundle executed, the section occupied zero pixels; then the whole 271px of it appeared and pushed the grid, the pulse strip and everything below them down. That single reveal measured **0.178 of the page's 0.257 desktop CLS**. The skeleton could not help, because the skeleton was inside the thing that did not exist yet.++**A placeholder that is not the size of the real card is a second shift, not a fix.** Measured on production at six viewport widths, the skeleton podium was **190px against a loaded podium of 235px** on desktop, so the swap moved the page again by 45px.++Both are fixed in the markup rather than the module. The section ships visible with its three placeholder cards in [pages/marketplace.html](../pages/marketplace.html), so the box exists in the first frame; `.mkt-top-card` carries a `min-height` (235px, and 72px in the 640px query) that the placeholder and the loaded card both obey, so the swap is a no-op for layout. `loadTopPerformers()` now only replaces the podium's contents, clears the `aria-busy` it ships with, or hides the section when the feed is empty.++Below 640px the podium is a single column, which makes the placeholder *count* decide its height rather than just the card size, so the 640px query hides every placeholder after the first. Three placeholders there would have reserved three rows for a feed that currently returns one agent, and over-reserving shifts the page exactly as surely as under-reserving; that was a regression introduced and caught inside this change, not a pre-existing one.++Two residuals are measured and left, both smaller than what they replace. If the leaderboard starts returning three agents, the mobile column grows from one row to three (a 160px shift, against the 268px the same load costs today). And a name long enough to wrap grows a loaded card past the 72px floor at 390px and narrower, by 14px to 32px. Reserving for a count you do not know yet is not solvable in CSS; reserving for the card you do know is.++**A loading state is a size before it is a shimmer.** Build it out of the same element as the real thing, ship it in the HTML, and check both heights in the browser rather than assuming they match.+## 6. Whoever writes a node's text owns it, and i18n has to be told**Invariant: JavaScript that replaces the text of an element carrying `data-i18n` removes the attribute in the same statement.**@@ -157,8 +220,45 @@ function setChipPrompt(chip, text) {**Any node whose text becomes dynamic loses its `data-i18n` at the point it becomes dynamic.** Not later, not in a cleanup pass. `src/i18n.js` uses the same guard for `data-auth-name` in the nav.+### That fixed the revert. It did not fix the growth.++The 2026-08-15 sweep ran against a build that already contained the fix above, and `/forge` still measured **CLS 0.256 desktop, 0.263 mobile, with `<div class="chips" id="examples">` still named as the largest single shift at 0.190**. Removing the revert removed one direction of a shift that had two.++The remaining direction was the first one: static labels to seeded labels. The static markup shipped five short examples ("a potted monstera plant") totalling 132 characters, and `seedChips()` replaced them on every JS visit with generated prompts capped at 64 characters each. The generator's own distribution is the whole story: a prompt averages 53.5 characters and cannot go below 29, so the seeded row averaged 268 characters and could reach 320. **The row a visitor sees was always more than twice as wide as the row first paint reserved for it**, and `.chips` is `flex-wrap`, so the difference arrived as extra lines that pushed the composer and everything under it down.++There is no way to generate a row narrow enough to fit the old markup. Only **three distinct prompts in the entire grammar** are 37 characters or shorter, so a per-label cap tight enough to match the static copy would leave the row with duplicates. The reservation has to move to meet the content, not the other way round:++- The labels in [pages/forge.html](../pages/forge.html) are now written at the 64-character cap, so first paint reserves the row's worst case. Both rows carry `data-no-i18n`, which keeps `scripts/i18n-annotate.mjs` from re-adding the attribute the section above exists to remove. The generated replacements are English at every locale, so a translated label was only ever visible for the instant before it was overwritten.+- `generateForgeChipSet()` in [src/forge-prompt-gen.js](../src/forge-prompt-gen.js) fits a rotation inside the character budget of the labels it replaces, so it can never exceed the reservation. It walks the candidate pool in generated order to keep the row varied, accepting a prompt only while the shortest remaining candidates could still fill the leftover slots.+- `pinRowHeight()` holds the row at its measured height across the swap, so a rotation that wraps onto *fewer* lines cannot shift the page upward either. The pin is released on the first resize, which relayouts the page anyway.++[tests/forge-prompt-gen.test.js](../tests/forge-prompt-gen.test.js) reads the labels out of `pages/forge.html` rather than copying them, so shortening the shipped copy fails the suite instead of silently restoring the shift.++Verified against the live page's own CSS by replacing the row's contents and measuring its height, six viewport widths, sixty random rotations each. The growth column is what the page shifts by:++| Viewport | Reserved, before | Seeded, before | Growth | Reserved, after | Seeded, after | Growth |+|---|---|---|---|---|---|---|+| 1440px | 99px | 202px | **103px** | 202px | 202px | **0px** |+| 1350px | 99px | 202px | **103px** | 202px | 202px | **0px** |+| 1024px | 63px | 99px | **36px** | 99px | 99px | **0px** |+| 768px | 64px | 167px | **103px** | 133px | 133px | **0px** |+| 390px | 194px | 295px | **101px** | 295px | 295px | **0px** |+| 320px | 244px | 295px | **51px** | 295px | 295px | **0px** |++**A static placeholder is a space reservation before it is copy.** If JavaScript is going to replace it, size the placeholder like the thing that replaces it, and make the replacement fit.+---+## Open: three costs the 2026-08-15 sweep measured and did not fix++Each of these is the largest remaining number on the page it belongs to, and each one lands in a surface the sweep that found it had no business rewriting. They are recorded here with the measurement so the next pass starts from a number rather than a hunch.++**`/chat` is one 4,277 KiB JavaScript chunk.** The page makes 23 requests and `chat/assets/index-*.js` is 4,277 KiB of them; nothing renders until it has parsed, which is the entire story of its FCP (3,901ms desktop, 23,105ms mobile) and of an LCP that lands 140ms later. Blocking time is *one millisecond*, so no amount of deferring helps: the work is a single parse of a single chunk. [chat/vite.config.js](../chat/vite.config.js) sets no `manualChunks` and no `inlineDynamicImports`; the app simply imports everything statically from its entry, so Vite has nothing to split on. The fix is dynamic imports at the route and feature boundaries inside `chat/src`, which is a refactor of the sub-app rather than a build-config change.++**`/forge` showcase thumbnails are full-size renders.** Twelve images from `pub-*.r2.dev` account for **6,273 KiB of the page's 8,339 KiB**, averaging 520 KB each. They are the 768x768 PNGs that [api/\_lib/forge-thumbs.js](../api/_lib/forge-thumbs.js) generates (`THUMB_SIZE = 768`), painted into a 200px-tall box. `loading="lazy"` and `decoding="async"` are already set per rule 5, so this is not a scheduling problem, it is a format and size problem: the same renders as WebP at a display-appropriate size are roughly a tenth of the bytes. The fix has to change the generator, re-run the backfill cron over existing rows, and handle the `forge/thumb/<id>.png` key extension that `forgeThumbKeyFor()` and the stored `preview_image_url` values both encode. One outlier in the same trace is a data-freshness artifact rather than a bug: a 2,358 KiB `forge/<clientKey>/<id>.png` is the untouched original for a row the backfill has not reached yet.++**The brand mark is an 85 KB SVG rendered at 22 pixels.** `public/three.svg` and the byte-identical `public/favicon.svg` are 85,257-byte SVGs wrapping two 800x436 PNGs behind `feColorMatrix` filters. They are referenced from 171 files, cost 62 KiB over the wire per page, and no call site in the repo renders the mark above 64 CSS px. Re-encoding the embedded rasters at exactly half resolution (800 to 400, lanczos3, no palette quantization) takes the file to 36,913 bytes and is visually indistinguishable at every size the site uses, with a maximum channel delta of 4 at 22px and 10 at 64px. It is not free above that: at 192px, which some platforms use for an SVG favicon, the delta reaches 105. Fractional downscales are much worse than the exact half (320px wide measured a delta of 78 at 22px), so this is a brand-asset decision with a measured cost attached, not a mechanical resize, and it needs the owner rather than a sweep.+## Open: directory thumbnails are served with no cache headers at allThis one is measured, understood, and deliberately not fixed yet, because the safe fix is larger than it looks.diff --git a/pages/forge.html b/pages/forge.htmlindex a41179e56..5f10142f1 100644--- a/pages/forge.html+++ b/pages/forge.html@@ -3578,12 +3578,25 @@</form>- <div class="chips" id="examples" aria-label="Example prompts">- <button class="chip" type="button" data-i18n="forge.a_low_poly_red_fox_sitting">a low-poly red fox, sitting</button>- <button class="chip" type="button" data-i18n="forge.a_sci_fi_combat_helmet_brushed_metal">a sci-fi combat helmet, brushed metal</button>- <button class="chip" type="button" data-i18n="forge.a_potted_monstera_plant">a potted monstera plant</button>- <button class="chip" type="button" data-i18n="forge.a_vintage_film_camera">a vintage film camera</button>- <button class="chip" type="button" data-i18n="forge.a_glazed_ceramic_teapot">a glazed ceramic teapot</button>+ <!-- These labels are a space reservation as much as they are copy. On every+ JS visit forge-prompt-studio.js replaces them with generated prompts+ (capped at 64 characters each), and the row is a flex-wrap container:+ when the static labels were half the width of the generated ones the+ row gained a line on load and pushed the whole page down, which was+ the largest layout shift on /forge. Written at the generator's cap so+ the row reserves its worst case at first paint and the rotation can+ only ever fit inside it. Keep new examples at 58 to 64 characters.+ No data-i18n here on purpose (data-no-i18n keeps i18n-annotate from+ adding it back): the generated replacements are English regardless of+ locale, so a translated label would only be visible for the instant+ before it is overwritten, and rewriting it back on a late catalog+ load is what caused the earlier shift on this same row. -->+ <div class="chips" id="examples" aria-label="Example prompts" data-no-i18n>+ <button class="chip" type="button">a low-poly red fox sitting upright, matte fur, soft studio light</button>+ <button class="chip" type="button">a sci-fi combat helmet, brushed titanium, glowing blue visor</button>+ <button class="chip" type="button">a potted monstera in a hammered copper pot, soft studio light</button>+ <button class="chip" type="button">a vintage film camera, worn black leather, polished chrome trim</button>+ <button class="chip" type="button">a glazed ceramic teapot with a bamboo handle, soft studio light</button><button class="chips-more" type="button" id="chips-more" aria-label="Swap in a fresh set of example prompts" data-i18n="forge.more_ideas" data-i18n-attr="aria-label:forge.swap_in_a_fresh_set_of_examp_arialabel">↻ More ideas</button></div></div>@@ -3630,13 +3643,15 @@Roll & Forge</button><p class="forge-empty-free" data-i18n="forge.free_no_sign_up_yours_to_download">Free · no sign-up · yours to download</p>- <div class="forge-empty-starters" id="empty-starters" role="group" aria-label="Starter prompts: click one to generate">- <button class="chip" type="button" data-i18n="forge.a_glazed_ceramic_teapot_2">a glazed ceramic teapot</button>- <button class="chip" type="button" data-i18n="forge.a_sci_fi_combat_helmet_brushed_metal_2">a sci-fi combat helmet, brushed metal</button>- <button class="chip" type="button" data-i18n="forge.a_low_poly_red_fox_sitting_2">a low-poly red fox, sitting</button>- <button class="chip" type="button" data-i18n="forge.a_worn_leather_messenger_bag">a worn leather messenger bag, brass buckles</button>- <button class="chip" type="button" data-i18n="forge.a_crystal_dragon_figurine">a crystal dragon figurine, catching the light</button>- <button class="chip" type="button" data-i18n="forge.a_chrome_toaster">a chrome toaster, mid-century diner style</button>+ <div class="forge-empty-starters" id="empty-starters" role="group" aria-label="Starter prompts: click one to generate" data-no-i18n>+ <!-- Same space-reservation rule as the #examples row above: written at+ the generator's 64-character cap, no data-i18n. -->+ <button class="chip" type="button">a glazed ceramic teapot with a bamboo handle, soft studio light</button>+ <button class="chip" type="button">a sci-fi combat helmet, brushed titanium, glowing blue visor</button>+ <button class="chip" type="button">a low-poly red fox sitting upright, matte fur, soft studio light</button>+ <button class="chip" type="button">a worn leather messenger bag, aged brass buckles, matte finish</button>+ <button class="chip" type="button">a crystal dragon figurine, faceted glass, catching warm light</button>+ <button class="chip" type="button">a chrome toaster in mid-century diner style, polished steel</button></div><p class="forge-empty-hint" data-i18n="forge.or_click_a_starter_it_generates_immediately">Or click a starter: it generates immediately.</p></div>diff --git a/pages/marketplace.html b/pages/marketplace.htmlindex 900ec5275..0887356b2 100644--- a/pages/marketplace.html+++ b/pages/marketplace.html@@ -2341,6 +2341,13 @@overflow: hidden;transition: border-color 0.18s, transform 0.18s, box-shadow 0.18s;gap: 2px;+ /* The skeleton card and the loaded card have to be the same box, or+ the swap moves the whole page. Measured against production on+ 2026-08-15 the loaded card was 235px tall and the skeleton 190px,+ so the "no layout jump" the skeleton was written for never held.+ Pinning the floor here holds it for both, since both are+ .mkt-top-card. Mobile has its own value in the 640px query. */+ min-height: 235px;}.mkt-top-card::before {content: '';@@ -2464,7 +2471,18 @@}@media (max-width: 640px) {.mkt-top-podium { grid-template-columns: 1fr; gap: 8px; }- .mkt-top-card { flex-direction: row; align-items: center; padding: 14px 16px; gap: 12px; }+ /* Same reservation as the desktop rule above, at the height a loaded+ card measures once the podium is a single stacked column (72px on+ production, 2026-08-15). A name long enough to wrap still grows it+ at the narrowest widths; that residual is noted in+ docs/site-performance.md. */+ .mkt-top-card { flex-direction: row; align-items: center; padding: 14px 16px; gap: 12px; min-height: 72px; }+ /* One column here, so unlike desktop the placeholder COUNT decides the+ podium's height. Three placeholders would reserve three rows for a+ feed that currently returns one agent, and over-reserving shifts the+ page just as surely as under-reserving. Reserve the row the loaded+ podium actually has. */+ .mkt-top-podium .mkt-skel:nth-child(n + 2) { display: none; }.mkt-top-card::after { background: none; }.mkt-top-av-wrap { margin: 0; width: 42px; height: 42px; }.mkt-top-rank { position: static; }@@ -3414,14 +3432,53 @@</div></div>- <!-- Top Oracle Performers — top 3 agents by oracle win rate -->- <section class="mkt-top-section" id="mkt-top-section" hidden aria-label="Top performing agents by oracle win rate">+ <!-- Top Oracle Performers, the top 3 agents by oracle win rate.+ Deliberately NOT `hidden`: loadTopPerformers() in src/marketplace.js+ used to reveal it after its skeleton was injected, which meant the+ whole 271px section appeared out of nothing and pushed the grid,+ the pulse strip and everything under them down. That single reveal+ was the largest layout shift on the page (0.178 of a 0.257 desktop+ CLS, measured on production 2026-08-15). The section now holds its+ box from first paint and the skeleton fills it; the empty and+ error paths still hide it, which is the only case that shifts. -->+ <section class="mkt-top-section" id="mkt-top-section" aria-label="Top performing agents by oracle win rate"><div class="mkt-top-head"><span class="mkt-top-eyebrow" data-i18n="marketplace.oracle_leaders">Oracle leaders</span><h2 class="mkt-top-title" data-i18n="marketplace.top_performers">Top Performers</h2><a href="/oracle" class="mkt-top-see-all" data-i18n="marketplace.view_leaderboard">View leaderboard →</a></div>- <div class="mkt-top-podium" id="mkt-top-podium"></div>+ <!-- The loading state ships in the markup rather than being injected,+ so the podium holds its box from the first frame instead of from+ whenever the page bundle gets around to running. Each placeholder+ is a real .mkt-top-card, so it lays out at exactly the height the+ loaded card will, at every breakpoint. loadTopPerformers() in+ src/marketplace.js replaces the whole podium in one write. -->+ <div class="mkt-top-podium" id="mkt-top-podium" aria-busy="true">+ <div class="mkt-top-card mkt-skel" style="--rank-color:#f59e0b">+ <span class="mkt-top-rank">#1</span>+ <div class="mkt-top-av-wrap"></div>+ <div class="mkt-top-name" style="width:70%;height:12px"> </div>+ <div class="mkt-top-wr" style="width:60%;height:28px;margin-top:8px"> </div>+ <div class="mkt-top-wr-lbl" style="width:50%;height:10px"> </div>+ <div class="mkt-top-meta" style="width:80%;height:10px"> </div>+ </div>+ <div class="mkt-top-card mkt-skel" style="--rank-color:#94a3b8">+ <span class="mkt-top-rank">#2</span>+ <div class="mkt-top-av-wrap"></div>+ <div class="mkt-top-name" style="width:70%;height:12px"> </div>+ <div class="mkt-top-wr" style="width:60%;height:28px;margin-top:8px"> </div>+ <div class="mkt-top-wr-lbl" style="width:50%;height:10px"> </div>+ <div class="mkt-top-meta" style="width:80%;height:10px"> </div>+ </div>+ <div class="mkt-top-card mkt-skel" style="--rank-color:#cd7c4f">+ <span class="mkt-top-rank">#3</span>+ <div class="mkt-top-av-wrap"></div>+ <div class="mkt-top-name" style="width:70%;height:12px"> </div>+ <div class="mkt-top-wr" style="width:60%;height:28px;margin-top:8px"> </div>+ <div class="mkt-top-wr-lbl" style="width:50%;height:10px"> </div>+ <div class="mkt-top-meta" style="width:80%;height:10px"> </div>+ </div>+ </div></section><asidediff --git a/public/changelog.json b/public/changelog.jsonindex 08a6e63f4..7fe019d3d 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T17:03:10.552Z",+ "generated_at": "2026-08-15T17:44:29.699Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -253,6 +253,17 @@"improvement"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "Pages stop loading a 3D robot you have not scrolled to yet",+ "summary": "The small animated robot in the site footer was starting up the moment a page opened, at the bottom of a page nobody had scrolled to. On plain pages that meant downloading a whole second 3D engine (253 KB) before anything else, and on the Forge it was the single busiest thing on the page: nearly 20 seconds of browser work, more than the Forge itself. It now waits until you are about a screen away from the footer, so it still greets you on the way down but no longer competes with the page you actually opened. It also stops taking a 3D slot away from the avatars on the page, which on a busy grid could leave a real avatar unable to render. Separately, the Forge's example prompt chips no longer shove the page down as they shuffle to a fresh set on load.",+ "link": "/forge",+ "tags": [+ "improvement",+ "fix"+ ]+ },{"date": "2026-08-15","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 038a69e35..dc6ca6e7e 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -190,6 +190,14 @@<category>fix</category><description>Several Oracle reads shared a habit: if the database was unreachable for a few seconds, they answered normally with an empty result. The movers panel said nothing was moving, the stats hero said no coin had ever been scored and no agent was armed, a coin's conviction sparkline came back flat, and the machine-readable signal endpoint told autonomous agents there were no plays, which is exactly the cue for an agent to stand down. Every one of those answers was then cached at the edge for a minute or two, so a blip lasting seconds kept showing a dead market long after the database was back. Those endpoints now tell the difference between a connectivity failure and an ordinary query fault: the first is reported honestly as a temporary outage with a retry hint and is never cached, the second still degrades to the empty answer it always did. The social ingest got the sharper end of the same bug: it used to reply that a batch had been accepted while reporting zero mints written, a receipt for a write that never landed. It now fails loudly so the sender retries. Shared conviction cards behave too: one built during an outage is no longer pinned to a coin's link preview for 15 minutes.</description></item>+ <item>+ <title>Pages stop loading a 3D robot you have not scrolled to yet</title>+ <link>https://three.ws/forge</link>+ <guid isPermaLink="false">2026-08-15:Pages stop loading a 3D robot you have not scrolled to yet</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>improvement</category>+ <description>The small animated robot in the site footer was starting up the moment a page opened, at the bottom of a page nobody had scrolled to. On plain pages that meant downloading a whole second 3D engine (253 KB) before anything else, and on the Forge it was the single busiest thing on the page: nearly 20 seconds of browser work, more than the Forge itself. It now waits until you are about a screen away from the footer, so it still greets you on the way down but no longer competes with the page you actually opened. It also stops taking a 3D slot away from the avatars on the page, which on a busy grid could leave a real avatar unable to render. Separately, the Forge's example prompt chips no longer shove the page down as they shuffle to a fresh set on load.</description>+ </item><item><title>Paying for a skill by Solana Pay QR now shows a real three.ws merchant card</title><link>https://three.ws/marketplace</link>diff --git a/public/features.json b/public/features.jsonindex ac96e7019..f04b95037 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T17:03:10.529Z",+ "generated_at": "2026-08-15T17:44:29.690Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/public/footer.js b/public/footer.jsindex 4d574ee78..fee543429 100644--- a/public/footer.js+++ b/public/footer.js@@ -1,7 +1,9 @@// Loads the canonical site footer into any page that contains// <div id="footer-container"></div>. Mirrors /nav.js: ensures footer.css-// is on the page, fetches /footer.html, injects it, and lazy-loads the-// newsletter wiring + model-viewer module if not already present.+// is on the page, fetches /footer.html, injects it, and wires the newsletter+// form. The decorative 3D footer bot is deferred until the footer is within a+// screenful of the viewport (see whenNearViewport below) so its renderer never+// competes with the page the visitor actually came for.(function () {// Resolves once the stylesheet has loaded so the footer markup is never// injected unstyled (flash-of-unstyled-content on hard refresh). A@@ -44,6 +46,72 @@});}+ // Runs `fn` the first time `el` comes within a screenful of the viewport, and+ // at most once. The footer bot is a decoration at the very bottom of every+ // page: booting it at DOMContentLoaded put a whole second 3D engine on the+ // critical path for something nobody had scrolled to yet (measured on+ // production 2026-08-15: 19.7 s of main-thread bootup for /footer-bot.js on+ // /forge, and 253 KiB plus 0.8 s for the model-viewer branch on /docs).+ // Anything without IntersectionObserver loads it on the first scroll instead,+ // so the bot still appears on the way down rather than never.+ function whenNearViewport(el, fn) {+ let done = false;+ const run = () => {+ if (done) return;+ done = true;+ fn();+ };+ if (typeof IntersectionObserver !== 'function') {+ window.addEventListener('scroll', run, { once: true, passive: true });+ return;+ }+ const io = new IntersectionObserver(+ (entries) => {+ if (!entries.some((e) => e.isIntersecting)) return;+ io.disconnect();+ run();+ },+ // Start the load a screenful early so the bot is rendered by the time+ // the footer is actually on screen, not after a visible pop-in.+ { rootMargin: '600px 0px' }+ );+ io.observe(el);+ }++ function bootFooterBot(container) {+ if (document.querySelector('meta[name="has-three-bundle"]')) {+ // This page already has a Vite-bundled Three.js, so load the canvas+ // renderer that shares that instance, avoiding a duplicate load.+ ensureScript({ src: '/footer-bot.js', type: 'module' });+ return;+ }+ // Plain HTML page (login, register, etc.): fall back to model-viewer.+ // robotexpressive.glb ships EXT_meshopt_compression, which stock+ // model-viewer cannot decode: without the meshopt shim it throws+ // "THREE.GLTFLoader: setMeshoptDecoder must be called before+ // loading compressed files" the moment the footer scrolls into+ // view. The shim must EXECUTE before model-viewer defines the+ // element (it intercepts customElements.define), so chain the+ // model-viewer load and the element injection behind it.+ ensureScript({ src: '/model-viewer-meshopt.js' }).then(() => {+ ensureScript({+ src: 'https://ajax.googleapis.com/ajax/libs/model-viewer/4.0.0/model-viewer.min.js',+ type: 'module',+ });+ // model-viewer needs a <model-viewer> element; swap the canvas for one.+ const avatar = container.querySelector('.h-footer-avatar');+ if (avatar) {+ avatar.innerHTML = `<model-viewer+ src="/animations/robotexpressive.glb"+ auto-rotate auto-rotate-delay="0" rotation-per-second="20deg"+ interaction-prompt="none" camera-controls="false" disable-zoom+ shadow-intensity="0" exposure="0.7" environment-image="neutral"+ camera-orbit="0deg 80deg 9m" field-of-view="35deg" loading="lazy"+ ></model-viewer>`;+ }+ });+ }+function init() {const container = document.getElementById('footer-container');if (!container) return;@@ -52,38 +120,9 @@.then(([html]) => {container.innerHTML = html;- if (container.querySelector('#footer-bot-canvas')) {- if (document.querySelector('meta[name="has-three-bundle"]')) {- // This page already has a Vite-bundled Three.js — load the canvas- // renderer that shares that instance, avoiding a duplicate load.- ensureScript({ src: '/footer-bot.js', type: 'module' });- } else {- // Plain HTML page (login, register, etc.) — fall back to model-viewer.- // robotexpressive.glb ships EXT_meshopt_compression, which stock- // model-viewer cannot decode: without the meshopt shim it throws- // "THREE.GLTFLoader: setMeshoptDecoder must be called before- // loading compressed files" the moment the footer scrolls into- // view. The shim must EXECUTE before model-viewer defines the- // element (it intercepts customElements.define), so chain the- // model-viewer load and the element injection behind it.- ensureScript({ src: '/model-viewer-meshopt.js' }).then(() => {- ensureScript({- src: 'https://ajax.googleapis.com/ajax/libs/model-viewer/4.0.0/model-viewer.min.js',- type: 'module',- });- // model-viewer needs a <model-viewer> element; swap the canvas for one.- const avatar = container.querySelector('.h-footer-avatar');- if (avatar) {- avatar.innerHTML = `<model-viewer- src="/animations/robotexpressive.glb"- auto-rotate auto-rotate-delay="0" rotation-per-second="20deg"- interaction-prompt="none" camera-controls="false" disable-zoom- shadow-intensity="0" exposure="0.7" environment-image="neutral"- camera-orbit="0deg 80deg 9m" field-of-view="35deg" loading="lazy"- ></model-viewer>`;- }- });- }+ const canvas = container.querySelector('#footer-bot-canvas');+ if (canvas) {+ whenNearViewport(canvas.parentElement || canvas, () => bootFooterBot(container));}ensureScript({ src: '/footer-newsletter.js', attr: 'defer' });diff --git a/src/forge-prompt-gen.js b/src/forge-prompt-gen.jsindex 04e653d2a..95e93950b 100644--- a/src/forge-prompt-gen.js+++ b/src/forge-prompt-gen.js@@ -228,3 +228,68 @@ export function generateDistinctForgePrompts(count, avoid = new Set(), rng = Mat}return out;}++/**+ * A replacement set for a row of example chips that cannot make the row taller.+ *+ * The chip rows on /forge are flex-wrap containers, so what moves the page is+ * the row's TOTAL width, not any single label: a rotation whose labels are+ * wider overall wraps onto a new line and pushes the rest of the page down. A+ * per-label cap alone does not prevent that (a 64-character cap over labels+ * averaging half that reliably added a row), and it measured as the largest+ * single layout shift on /forge: 0.19 of a 0.256 CLS against production on+ * 2026-08-15.+ *+ * `currentLabels` are the labels being replaced. The returned prompts are+ * distinct, absent from `avoid`, each no longer than the longest current label,+ * and no longer in total than the current labels combined, so the row's wrap+ * geometry can only stay the same or shrink. When the budget is too tight to+ * fill the row with distinct prompts the shortest candidates are returned+ * instead, so the row still rotates rather than freezing.+ */+export function generateForgeChipSet(+ currentLabels,+ avoid = new Set(),+ rng = Math.random,+ maxLength = Infinity+) {+ const lengths = currentLabels.map((label) => String(label).trim().length);+ const count = lengths.length;+ if (!count) return [];+ const budget = lengths.reduce((a, b) => a + b, 0);+ const longest = Math.min(Math.max(...lengths), maxLength);+ // Over-generate so there is a real pool to fit inside the budget. The+ // combinatorial space is ~10^4, so this stays cheap. A row whose labels are+ // all shorter than any prompt the generator can emit filters the pool to+ // nothing; fall back to the caller's own cap there so the row still rotates+ // rather than freezing on its static copy.+ let pool = generateDistinctForgePrompts(count * 6, avoid, rng, longest);+ if (!pool.length) pool = generateDistinctForgePrompts(count * 6, avoid, rng, maxLength);+ if (!pool.length) return [];++ // Walk the pool in its generated (random) order so the row keeps its+ // variety, but only accept a prompt while the shortest remaining candidates+ // could still fill the leftover slots inside the budget. Without that+ // lookahead a couple of wide early picks strand the tail and the row comes+ // back short.+ const shortest = [...pool].sort((a, b) => a.length - b.length);+ const minLength = shortest[0].length;+ const picked = [];+ let used = 0;+ for (const prompt of pool) {+ if (picked.length >= count) break;+ const slotsAfter = count - picked.length - 1;+ if (used + prompt.length + slotsAfter * minLength > budget) continue;+ picked.push(prompt);+ used += prompt.length;+ }+ // Budget too tight even for the shortest full row (labels narrower than any+ // prompt): top up with the shortest candidates. Fewer characters than the+ // labels they replace can only remove a wrap, never add one, and the caller+ // pins the row's height across the swap so that cannot shift the page.+ for (const prompt of shortest) {+ if (picked.length >= count) break;+ if (!picked.includes(prompt)) picked.push(prompt);+ }+ return picked;+}diff --git a/src/forge-prompt-studio.js b/src/forge-prompt-studio.jsindex d98941741..41d343aab 100644--- a/src/forge-prompt-studio.js+++ b/src/forge-prompt-studio.js@@ -9,7 +9,7 @@// genuinely random without ever leaving the model's sweet spot. Nothing here// fakes a network call.-import { generateDistinctForgePrompts } from './forge-prompt-gen.js';+import { generateDistinctForgePrompts, generateForgeChipSet } from './forge-prompt-gen.js';const MAXLEN = 1000;// Example chips stay scannable: only prompts short enough to read at a@@ -189,21 +189,48 @@ function surprise() {// Write a generated prompt into a chip and take ownership of its text.//-// The static chip labels in the HTML carry data-i18n keys so a no-JS visitor-// still gets translated copy. Once we replace that label with a generated-// prompt, the key no longer describes the node: i18n's applyCatalog walks-// [data-i18n] whenever a catalog loads or the locale changes and would write-// the original English string back over the generated one. That silently undid-// every rotation (the "fresh set every visit" promise below), and because the-// generated prompts are longer than the static ones the revert re-wrapped the-// flex row and moved everything under it, which measured as the single largest-// layout shift on /forge. Dropping the attribute hands the node to its real-// owner, the same way nav-auth's data-auth-name guard does in src/i18n.js.+// The example rows in pages/forge.html deliberately carry no data-i18n keys+// (see the comment there), but a chip injected by another module might. i18n's+// applyCatalog walks [data-i18n] whenever a catalog loads or the locale+// changes and would write the original string back over the generated one,+// silently undoing every rotation and re-wrapping the flex row underneath it.+// Dropping the attribute hands the node to its real owner, the same way+// nav-auth's data-auth-name guard does in src/i18n.js.function setChipPrompt(chip, text) {chip.textContent = text;chip.removeAttribute('data-i18n');}+// The replacement labels for a chip row come from generateForgeChipSet, which+// fits them inside the row's existing character budget so a rotation can never+// add a wrapped line. See its comment in forge-prompt-gen.js for why the+// per-label CHIP_MAXLEN cap was not enough on its own.+const generateChipSet = (chips, avoid) =>+ generateForgeChipSet(+ chips.map((c) => c.textContent),+ avoid,+ Math.random,+ CHIP_MAXLEN+ );++// Hold the row at the height it already occupies while its labels change, so a+// set that happens to wrap onto fewer lines cannot shift the page upward+// either. Released on resize: a resize relayouts the whole page anyway, and a+// stale pin from a narrower viewport would leave a visible gap.+function pinRowHeight(container) {+ if (!container) return;+ const h = container.getBoundingClientRect().height;+ if (!h) return;+ container.style.minHeight = `${h}px`;+ window.addEventListener(+ 'resize',+ () => {+ container.style.minHeight = '';+ },+ { once: true }+ );+}+function shuffleChips() {if (!els.examples) return;// Seasonal presets (.chip--festive) are pinned: "More ideas" only rotates@@ -211,7 +238,8 @@ function shuffleChips() {const chips = [...els.examples.querySelectorAll('.chip:not(.chip--festive)')];if (!chips.length) return;const current = new Set(chips.map((c) => c.textContent.trim()));- const fresh = generateDistinctForgePrompts(chips.length, current, Math.random, CHIP_MAXLEN);+ pinRowHeight(els.examples);+ const fresh = generateChipSet(chips, current);chips.forEach((chip, i) => {const next = fresh[i];if (!next) return;@@ -235,14 +263,23 @@ function shuffleChips() {// the empty-stage starters, kept mutually distinct; festive (pinned// seasonal) chips are untouched.function seedChips() {- const chips = [els.examples, els.emptyStarters].flatMap((container) =>- container ? [...container.querySelectorAll('.chip:not(.chip--festive)')] : []- );- if (!chips.length) return;- const fresh = generateDistinctForgePrompts(chips.length, undefined, Math.random, CHIP_MAXLEN);- chips.forEach((chip, i) => {- if (fresh[i]) setChipPrompt(chip, fresh[i]);- });+ // Each row gets its own character budget: the two rows live in different+ // columns and wrap independently, so pooling their budgets would let one+ // spend the other's and re-introduce the wrap it was meant to prevent.+ // `used` carries across both so the two rows stay mutually distinct.+ const used = new Set();+ for (const container of [els.examples, els.emptyStarters]) {+ if (!container) continue;+ const chips = [...container.querySelectorAll('.chip:not(.chip--festive)')];+ if (!chips.length) continue;+ pinRowHeight(container);+ const fresh = generateChipSet(chips, used);+ chips.forEach((chip, i) => {+ if (!fresh[i]) return;+ used.add(fresh[i]);+ setChipPrompt(chip, fresh[i]);+ });+ }}if (els.prompt) {diff --git a/src/marketplace.js b/src/marketplace.jsindex 8b620e057..3dd918a30 100644--- a/src/marketplace.js+++ b/src/marketplace.js@@ -8849,17 +8849,12 @@ async function loadTopPerformers() {const podium = $('mkt-top-podium');if (!section || !podium) return;- // Show skeleton cards immediately so there's no layout jump when data arrives.- podium.innerHTML = [0, 1, 2].map((i) => `- <div class="mkt-top-card mkt-skel" style="--rank-color:${TOP_RANK_COLORS[i]}">- <span class="mkt-top-rank">${TOP_RANK_LABELS[i]}</span>- <div class="mkt-top-av-wrap"></div>- <div class="mkt-top-name" style="width:70%;height:12px"> </div>- <div class="mkt-top-wr" style="width:60%;height:28px;margin-top:8px"> </div>- <div class="mkt-top-wr-lbl" style="width:50%;height:10px"> </div>- <div class="mkt-top-meta" style="width:80%;height:10px"> </div>- </div>`).join('');- section.hidden = false;+ // The skeleton and the section's visibility both ship in pages/marketplace.html+ // now. Injecting the skeleton here, and revealing the section behind it, meant+ // the podium's 271px box did not exist until this module ran, so the whole+ // section appeared out of nothing and pushed the page down: the largest layout+ // shift on /marketplace (0.178 of a 0.257 desktop CLS, measured 2026-08-15).+ // This function only ever replaces the podium's contents or hides the section.try {const r = await fetch('/api/oracle/leaderboard?limit=3&min_actions=3', {@@ -8899,6 +8894,9 @@ async function loadTopPerformers() {</div></a>`;}).join('');+ // The podium ships aria-busy="true" around its placeholder cards; the real+ // ones are here, so stop telling assistive tech the region is still loading.+ podium.removeAttribute('aria-busy');} catch {section.hidden = true;}diff --git a/tests/forge-prompt-gen.test.js b/tests/forge-prompt-gen.test.jsindex bdca2735b..f5898ae46 100644--- a/tests/forge-prompt-gen.test.js+++ b/tests/forge-prompt-gen.test.js@@ -3,11 +3,13 @@// meshes cleanest) regardless of which random path produced it. These tests// sweep every family with seeded rngs so the assertions cover the grammar// space, not one lucky draw.+import { readFileSync } from 'node:fs';import { describe, it, expect } from 'vitest';import {FAMILIES,generateForgePrompt,generateDistinctForgePrompts,+ generateForgeChipSet,} from '../src/forge-prompt-gen.js';// Deterministic LCG so failures reproduce exactly.@@ -84,3 +86,81 @@ describe('forge prompt generator', () => {}});});++// Pull one chip row's visible labels straight out of pages/forge.html.+function readChipRow(id) {+ const html = readFileSync(new URL('../pages/forge.html', import.meta.url), 'utf8');+ const row = html.slice(html.indexOf(`id="${id}"`));+ const labels = [...row.slice(0, row.indexOf('</div>')).matchAll(/<button class="chip"[^>]*>([^<]+)<\/button>/g)].map(+ (m) => m[1].trim()+ );+ if (!labels.length) throw new Error(`no .chip labels found under #${id} in pages/forge.html`);+ return labels;+}++// The chip rows on /forge wrap, so a replacement set that is wider overall adds+// a line and pushes the page down. generateForgeChipSet exists to make that+// impossible; these lock the budget contract that the CLS fix rests on.+describe('generateForgeChipSet', () => {+ // Read from the page rather than copied here: the labels ARE the reservation.+ // They are written at the 64-character cap on purpose so the row reserves its+ // worst case at first paint, and shortening them is exactly the regression+ // that put a 0.19 layout shift on /forge. Deriving the budget from the real+ // markup makes this suite the alarm for that.+ const STATIC_CHIPS = readChipRow('examples');+ const STARTER_CHIPS = readChipRow('empty-starters');++ // CHIP_MAXLEN in forge-prompt-studio.js. A shipped label shorter than this+ // under-reserves the row, which is the shift; longer than this reserves space+ // the rotation can never use.+ const CHIP_MAXLEN = 64;++ it.each([+ ['#examples', STATIC_CHIPS],+ ['#empty-starters', STARTER_CHIPS],+ ])('%s reserves the row at the generator cap', (_id, labels) => {+ expect(labels.length).toBeGreaterThan(1);+ for (const label of labels) {+ expect(label.length).toBeLessThanOrEqual(CHIP_MAXLEN);+ expect(label.length).toBeGreaterThanOrEqual(CHIP_MAXLEN - 6);+ }+ });++ it.each([+ ['#examples', STATIC_CHIPS],+ ['#empty-starters', STARTER_CHIPS],+ ])('%s: a rotation never returns more characters than it replaces', (_id, labels) => {+ const budget = labels.reduce((n, s) => n + s.length, 0);+ const longest = Math.max(...labels.map((s) => s.length));+ for (let seed = 1; seed <= 300; seed++) {+ const out = generateForgeChipSet(labels, new Set(), lcg(seed * 104729), CHIP_MAXLEN);+ expect(out).toHaveLength(labels.length);+ expect(new Set(out).size).toBe(labels.length);+ expect(out.reduce((n, s) => n + s.length, 0)).toBeLessThanOrEqual(budget);+ for (const p of out) {+ // No single chip may exceed the widest label already in the row,+ // so one long prompt cannot push a short neighbour onto a new line.+ expect(p.length).toBeLessThanOrEqual(longest);+ assertWellFormed(p);+ }+ }+ });++ it('honors avoid so a rotation never echoes what is already on screen', () => {+ const first = generateForgeChipSet(STATIC_CHIPS, new Set(), lcg(5), 64);+ const second = generateForgeChipSet(STATIC_CHIPS, new Set(first), lcg(11), 64);+ for (const p of second) expect(first).not.toContain(p);+ });++ it('still rotates the row when the budget is far too tight to honor', () => {+ // Labels shorter than any generatable prompt: the row must degrade to the+ // shortest candidates rather than freeze on the static copy.+ const out = generateForgeChipSet(['ab', 'cd', 'ef'], new Set(), lcg(3), 64);+ expect(out).toHaveLength(3);+ for (const p of out) assertWellFormed(p);+ });++ it('returns nothing for an empty row', () => {+ expect(generateForgeChipSet([], new Set(), lcg(1), 64)).toEqual([]);+ });+});