3D engine that AI agents drive
Start the home hero's first view with the page and warm the build chunks (#884)
Nguyen Xuan An55e475240cff
diff --git a/changes/884-parallel-start.md b/changes/884-parallel-start.mdnew file mode 100644index 00000000..03a98c8a--- /dev/null+++ b/changes/884-parallel-start.md@@ -0,0 +1,2 @@+- The home hero starts its first view with the page, in parallel with the poster, instead of after the poster loads (#884)+- The home hero asks for the build's two on-demand chunks while the first view downloads (#884)diff --git a/docs/hero-loading.md b/docs/hero-loading.mdindex 49c4e3c1..08c73eec 100644--- a/docs/hero-loading.md+++ b/docs/hero-loading.md@@ -4,8 +4,8 @@ The hero on the home page plays a flight over the Port showcase world. The world## Order of the files-1. The poster image loads. Nothing else competes with it.-2. When the poster has settled (or after 5 s), `index.html` starts the first view: `scene.json`, `scene.first.glb` (about 2 MB) and `sky.preview.hdr` (256 by 128, 131 KB, a block average of the full `sky.hdr` at the same orientation; exposure, tone mapping, sun, fog and sky intensity come from the same `scene.json` for both, so only the sky's detail differs at the swap. Make it with `node scripts/downsample-hdr.mjs <sky.hdr> <sky.preview.hdr> 256 128`; the Fast 4G first frame budget keeps it under 150 KB).+1. The poster image (49 KB, 15 KB on a phone, `fetchpriority="high"`) and the first view start together. The poster is the largest contentful paint and the first view is small enough not to starve it; only the 9.7 MB full world waits for something else (step 3).+2. The inline script of `index.html` starts the first view as the head is parsed, without waiting for the poster: `scene.json`, `scene.first.glb` (about 2 MB) and `sky.preview.hdr` (256 by 128, 131 KB, a block average of the full `sky.hdr` at the same orientation; exposure, tone mapping, sun, fog and sky intensity come from the same `scene.json` for both, so only the sky's detail differs at the swap. Make it with `node scripts/downsample-hdr.mjs <sky.hdr> <sky.preview.hdr> 256 128`; the Fast 4G first frame budget keeps it under 150 KB).3. When those have settled, it starts the full world: `scene.glb`, `scene.rest.glb` and `sky.hdr`.4. `fetchWorld(url, { firstView: true })` in `src/hero-lab/loop/world.js` resolves as soon as the first view is in. It holds a `detail` promise for the full world.5. The world is built from the first view and draws. `completeDetail` (`src/hero-lab/loop/detail.js`) then waits for `detail`, parses it and calls `world.upgrade(detail)`. The upgrade uploads the textures and the sky while the first view keeps drawing. Only the swap itself (the sky prefilter, one `replaceParts` and a prepared draw) holds the draws: about 140 ms on a desktop and a phone viewport (`swapHeldMs` of `scripts/measure-hero-load.mjs`, GPU shared with other jobs). Feeding `replaceParts` in slices was tried and doubled the hold (swap 0.8 s to 1.5 s) without shortening the longest gap between frames (about 110 ms either way).@@ -38,9 +38,10 @@ The chip fab is the one world with an animation clip: engineers walk, hoist vehi```shnpx vite build --outDir <folder>-node scripts/measure-hero-load.mjs --dist <folder> --label <name> --runs 3+node scripts/measure-hero-load.mjs --dist <folder> --label <name> --runs 3 [--cpu 4]+node scripts/measure-hero-load.mjs --origin https://67js.codepawl.com --label live --runs 3node scripts/measure-hero-load.mjs --dist <folder> --stills <directory>node scripts/measure-hero-load.mjs --dist <folder> --video <file.mp4>```-It serves the folder with brotli and throttles through the DevTools protocol (Fast 4G, 1.6 Mbit/s with 150 ms round trip, unthrottled), on a desktop and a phone viewport. Network times do not depend on the GPU load; frame times do. `--stills` scores the first view against the full world at the same pose with PSNR.+It serves the folder with brotli and throttles through the DevTools protocol (Fast 4G, 1.6 Mbit/s with 150 ms round trip, unthrottled), on a desktop and a phone viewport. `--cpu 4` slows the CPU four times through the DevTools protocol (emulated, not a slow phone); the output has the largest contentful paint (`lcpMs`) and the layout shift beside the first frame. `CHROME_PATH` and `HERO_CHROME_ARGUMENTS` set the browser for a container. Network times do not depend on the GPU load; frame times do. `--stills` scores the first view against the full world at the same pose with PSNR.diff --git a/index.html b/index.htmlindex 7f3b704b..f22a209f 100644--- a/index.html+++ b/index.html@@ -17,8 +17,8 @@<meta name="twitter:card" content="summary_large_image" /><link rel="canonical" href="https://67js.codepawl.com/" /><script id="hero-mode">- // Decides how the home hero loads before the page body parses, so a visitor's first world starts downloading the moment the poster- // has arrived, before the scripts are ready, and a visitor on a light connection downloads no 3D at all. hero-loop.js reads window.__heroMode: 'live', 'deferred' (a phone,+ // Decides how the home hero loads before the page body parses, so a visitor's first world starts downloading with the page, in+ // parallel with the poster and before the scripts are ready, and a visitor on a light connection downloads no 3D at all. hero-loop.js reads window.__heroMode: 'live', 'deferred' (a phone,// starts after the poster and an idle moment) or 'poster' (no 3D until the visitor presses Play live 3D).(function () {var connection = navigator.connection || {};@@ -33,17 +33,14 @@// ?scout=1 builds one world on request and never runs the loop, so nothing is prefetched for it.if (mode !== 'live' || query.has('scout')) return;// Plain fetches, not <link rel=preload>: a preload that fetch() should have reused failed now and then, with no error to read.- // They start when the poster has loaded (or after POSTER_WAIT_MS if it has not): on a slow link, 12 MB of world files started- // ahead of the poster delayed the poster by several seconds. hero-lab/loop/world.js waits for window.__heroPrefetchReady, takes- // these promises by URL and falls back to its own request when one is missing or failed.- var POSTER_WAIT_MS = 5000;+ // They start with the page, beside the poster (49 KB, 15 KB on a phone): only the 2 MB first view starts now and the 9.7 MB full+ // world waits for it, so the poster is not starved the way 12 MB of world files started at once once starved it.+ // hero-lab/loop/world.js waits for window.__heroPrefetchReady, takes these promises by URL and falls back to its own request when+ // one is missing or failed.var prefetched = window.__heroPrefetch = {};- var started = false;var releaseReady;window.__heroPrefetchReady = new Promise(function (resolve) { releaseReady = resolve; });function startPrefetch() {- if (started) return;- started = true;// The first view (a small copy of the whole world) goes first and the full world's files start when those have settled, so// the first 3D frame does not wait for the full 9 MB. The promises exist at once; world.js takes them by URL.var firstViewFiles = ['/showcase/port/scene.json', '/showcase/port/scene.first.glb', '/showcase/port/sky.preview.hdr'];@@ -61,9 +58,7 @@firstViewFiles.concat(fullWorldFiles).forEach(function (href) { prefetched[href].catch(function () {}); });releaseReady();}- // The poster <img> calls this from its load and error events.- window.__heroPosterSettled = startPrefetch;- setTimeout(startPrefetch, POSTER_WAIT_MS);+ startPrefetch();})();</script><title>67js · 3D engine that AI agents drive</title>@@ -81,7 +76,7 @@</header><section id="hero" class="hero-loop" data-scene="port" aria-label="67js introduction and live preview"><div class="stage" id="stage" tabindex="-1" role="img" aria-label="A live 3D scene: Container port">- <picture><source media="(max-width: 700px)" srcset="/hero-lab/poster-b-port-mobile.webp" /><img class="poster" id="poster" src="/hero-lab/poster-b-port.webp" alt="" width="1440" height="900" fetchpriority="high" onload="window.__heroPosterSettled&&window.__heroPosterSettled()" onerror="window.__heroPosterSettled&&window.__heroPosterSettled()" /></picture>+ <picture><source media="(max-width: 700px)" srcset="/hero-lab/poster-b-port-mobile.webp" /><img class="poster" id="poster" src="/hero-lab/poster-b-port.webp" alt="" width="1440" height="900" fetchpriority="high" /></picture></div><div class="copy"><h1>3D engine that<br />AI agents drive</h1>diff --git a/scripts/measure-hero-load.mjs b/scripts/measure-hero-load.mjsindex 5e9e15e2..20895f65 100644--- a/scripts/measure-hero-load.mjs+++ b/scripts/measure-hero-load.mjs@@ -2,6 +2,8 @@//// node scripts/measure-hero-load.mjs --dist <built site folder> [--label name] [--runs 3] [--conditions fast4g,slow,none]// [--viewports desktop,phone] [--out directory]+// [--cpu 4] CPU slowdown factor (emulated by the DevTools protocol, not a slow device)+// [--origin <url>] measure a deployed site instead of serving --dist (it then needs no folder)// node scripts/measure-hero-load.mjs --dist <folder> --stills <directory> stills before and after the swap, with PSNR// node scripts/measure-hero-load.mjs --dist <folder> --video <file.mp4> CDP screencast of the first 8 s on Fast 4G//@@ -20,8 +22,9 @@ import { spawnSync } from 'node:child_process';import { chromium } from 'playwright';import sharp from 'sharp';-const CHROME_PATH = 'C:/Program Files/Google/Chrome/Application/chrome.exe';-const GPU_ARGUMENTS = ['--use-angle=d3d11', '--enable-gpu', '--ignore-gpu-blocklist'];+// CHROME_PATH and HERO_CHROME_ARGUMENTS (space separated) override these, for a container with Vulkan instead of Direct3D.+const CHROME_PATH = process.env.CHROME_PATH ?? 'C:/Program Files/Google/Chrome/Application/chrome.exe';+const GPU_ARGUMENTS = process.env.HERO_CHROME_ARGUMENTS ? process.env.HERO_CHROME_ARGUMENTS.split(' ') : ['--use-angle=d3d11', '--enable-gpu', '--ignore-gpu-blocklist'];const FIRST_FRAME_MARKER = 'hero-first-world-draw';const CONDITIONS = {fast4g: { label: 'Fast 4G', downloadBitsPerSecond: 9e6, uploadBitsPerSecond: 1.5e6, latency: 60 },@@ -36,7 +39,7 @@ const CONTENT_TYPES = { '.html': 'text/html', '.js': 'text/javascript', '.css':const TEXT_TYPES = new Set(['.html', '.js', '.css', '.json', '.svg']);function parseArguments(argv) {- const options = { dist: null, label: 'build', runs: 3, conditions: ['fast4g', 'slow', 'none'], viewports: ['desktop', 'phone'], out: null, stills: null, video: null, timeoutSeconds: 120 };+ const options = { dist: null, label: 'build', runs: 3, conditions: ['fast4g', 'slow', 'none'], viewports: ['desktop', 'phone'], out: null, cpu: 1, remoteOrigin: null, stills: null, video: null, timeoutSeconds: 120 };for (let index = 0; index < argv.length; index++) {const flag = argv[index];const value = () => argv[++index];@@ -45,12 +48,15 @@ function parseArguments(argv) {else if (flag === '--runs') options.runs = Number(value());else if (flag === '--conditions') options.conditions = value().split(',');else if (flag === '--viewports') options.viewports = value().split(',');+ else if (flag === '--cpu') options.cpu = Number(value());+ else if (flag === '--origin') options.remoteOrigin = value().replace(/[/]$/, '');else if (flag === '--out') options.out = resolve(value());else if (flag === '--stills') options.stills = resolve(value());else if (flag === '--video') options.video = resolve(value());else if (flag === '--timeout') options.timeoutSeconds = Number(value());else throw new Error(`Unknown argument ${flag}.`);}+ if (!options.dist && options.remoteOrigin) return options;if (!options.dist || !existsSync(join(options.dist, 'index.html'))) throw new Error('Pass --dist <folder with index.html>.');return options;}@@ -88,6 +94,14 @@ async function startServer(root) {// first live 3D frame a visitor sees. The poster fades out only after that.function installFrameTimer(marker) {window.__firstWorldDraw = null;+ window.__largestContentfulPaint = null;+ new PerformanceObserver(list => {+ for (const entry of list.getEntries()) window.__largestContentfulPaint = entry.startTime;+ }).observe({ type: 'largest-contentful-paint', buffered: true });+ window.__layoutShift = 0;+ new PerformanceObserver(list => {+ for (const entry of list.getEntries()) if (!entry.hadRecentInput) window.__layoutShift += entry.value;+ }).observe({ type: 'layout-shift', buffered: true });// Gaps between animation frames over 50 ms: the main thread was blocked. The swap to the full world should leave none that is long.window.__frameGaps = [];let previousFrameAt = performance.now();@@ -105,12 +119,13 @@ function installFrameTimer(marker) {}).observe(document, { subtree: true, childList: true, attributes: true, attributeFilter: ['data-live'] });}-async function openPage(browser, viewport, condition) {+async function openPage(browser, viewport, condition, cpuSlowdown = 1) {const context = await browser.newContext({ viewport: { width: viewport.width, height: viewport.height }, deviceScaleFactor: viewport.deviceScaleFactor, isMobile: viewport.isMobile });const page = await context.newPage();const session = await context.newCDPSession(page);await session.send('Network.enable');await session.send('Network.setCacheDisabled', { cacheDisabled: true });+ if (cpuSlowdown > 1) await session.send('Emulation.setCPUThrottlingRate', { rate: cpuSlowdown });if (condition.downloadBitsPerSecond > 0) {await session.send('Network.emulateNetworkConditions', {offline: false,@@ -144,7 +159,7 @@ function bytesAt(state, milliseconds) {async function measureOnce(browser, options, viewportName, conditionName) {const condition = CONDITIONS[conditionName];- const { context, page, session } = await openPage(browser, VIEWPORTS[viewportName], condition);+ const { context, page, session } = await openPage(browser, VIEWPORTS[viewportName], condition, options.cpu);const bytes = watchBytes(session, page);const errors = [];page.on('pageerror', error => errors.push(error.message));@@ -155,7 +170,7 @@ async function measureOnce(browser, options, viewportName, conditionName) {const failed = events.find(event => event.kind === 'failed');const swapEnd = detailed?.at ?? Infinity;const swapGaps = (window.__frameGaps ?? []).filter(([at, gap]) => at + gap > swapEnd - (detailed?.ms ?? 0) - 100 && at < swapEnd + 100);- return { first: window.__firstWorldDraw, detailed: detailed?.at ?? null, swapMs: detailed?.ms ?? null, swapHeldMs: (window.__phases ?? []).filter(phase => phase[0] === "swap").reduce((total, phase) => total + phase[3] - phase[2], 0), swapLongestGapMs: swapGaps.length ? Math.max(...swapGaps.map(([, gap]) => gap)) : 0, failed: failed?.message ?? null, state: window.__loop?.detail?.() ?? null, mode: window.__heroMode };+ return { lcp: window.__largestContentfulPaint, layoutShift: window.__layoutShift, first: window.__firstWorldDraw, detailed: detailed?.at ?? null, swapMs: detailed?.ms ?? null, swapHeldMs: (window.__phases ?? []).filter(phase => phase[0] === "swap").reduce((total, phase) => total + phase[3] - phase[2], 0), swapLongestGapMs: swapGaps.length ? Math.max(...swapGaps.map(([, gap]) => gap)) : 0, failed: failed?.message ?? null, state: window.__loop?.detail?.() ?? null, mode: window.__heroMode };});const deadline = Date.now() + options.timeoutSeconds * 1000;let status = await finished();@@ -174,6 +189,8 @@ async function measureOnce(browser, options, viewportName, conditionName) {condition: condition.label,mode: status.mode,posterEndMs: poster,+ lcpMs: status.lcp === null ? null : Math.round(status.lcp),+ layoutShift: Number(status.layoutShift.toFixed(4)),firstFrameMs,detailMs,swapMs: status.swapMs,@@ -204,7 +221,10 @@ async function runMatrix(browser, options) {condition: CONDITIONS[conditionName].label,mode: runs[0].mode,runs: runs.length,+ cpuSlowdown: options.cpu,posterEndMs: median(runs.map(run => run.posterEndMs)),+ lcpMs: median(runs.map(run => run.lcpMs)),+ layoutShift: median(runs.map(run => run.layoutShift)),firstFrameMs: median(runs.map(run => run.firstFrameMs)),firstFrameRangeMs: [Math.min(...runs.map(run => run.firstFrameMs ?? Infinity)), Math.max(...runs.map(run => run.firstFrameMs ?? 0))],detailMs: median(runs.map(run => run.detailMs)),@@ -301,7 +321,7 @@ async function recordVideo(browser, options) {}const options = parseArguments(process.argv.slice(2));-const { server, origin } = await startServer(options.dist);+const { server, origin } = options.remoteOrigin ? { server: null, origin: options.remoteOrigin } : await startServer(options.dist);options.origin = origin;const browser = await chromium.launch({ executablePath: CHROME_PATH, headless: true, args: GPU_ARGUMENTS });try {@@ -310,5 +330,5 @@ try {else await runMatrix(browser, options);} finally {await browser.close();- server.close();+ server?.close();}diff --git a/src/hero-lab/loop/world.js b/src/hero-lab/loop/world.jsindex b14e9ffd..52687fd0 100644--- a/src/hero-lab/loop/world.js+++ b/src/hero-lab/loop/world.js@@ -148,7 +148,15 @@ async function fetchFirstViewFiles(description) {}}+// The build needs two chunks that load on demand (the meshopt decoder and replaceParts). Asking for them while the world's files are+// still downloading takes their round trips off the time between the last byte of the first view and its first frame.+function warmBuildChunks() {+ import('../../gltf-meshopt.js').catch(() => {});+ import('../../replace-textured-parts.js').catch(() => {});+}+export async function fetchWorld(descriptionUrl, { firstView = false, measureLink = measureLinkMegabits } = {}) {+ warmBuildChunks();const description = await readDescription(descriptionUrl);if (!firstView || !hasFirstView(description)) return fetchDetail(description);const firstViewFiles = await fetchFirstViewFiles(description);diff --git a/tests/hero-mode.test.js b/tests/hero-mode.test.jsindex f9a1e53c..56941f02 100644--- a/tests/hero-mode.test.js+++ b/tests/hero-mode.test.js@@ -33,44 +33,24 @@ test('index.html carries the hero mode script', () => {assert.ok(heroModeScript, 'index.html needs <script id="hero-mode">');});-test('the poster image reports its load and its error to the script, and keeps its high fetch priority', () => {+test('the poster keeps its high fetch priority and does not gate the world on its load', () => {const poster = indexHtml.match(/<img class="poster"[^>]*>/)[0];assert.match(poster, /fetchpriority="high"/);- assert.ok(poster.includes('onload="window.__heroPosterSettled&&window.__heroPosterSettled()"'));- assert.ok(poster.includes('onerror="window.__heroPosterSettled&&window.__heroPosterSettled()"'));+ assert.ok(!poster.includes('onload'), 'the first world does not wait for the poster');+ assert.ok(!poster.includes('onerror'));});-test('a desktop on a good connection goes live and starts the first world only once the poster has loaded', async () => {- const { mode, attribute, fetched, window } = runHeroMode({ connection: { effectiveType: '4g', saveData: false }, deviceMemory: 8 });+test('a desktop on a good connection goes live and starts the first view with the page, the full world after it', async () => {+ const { mode, attribute, fetched, timers, window } = runHeroMode({ connection: { effectiveType: '4g', saveData: false }, deviceMemory: 8 });assert.equal(mode, 'live');assert.equal(attribute, 'live');- assert.deepEqual(fetched, [], 'nothing competes with the poster');- window.__heroPosterSettled();- assert.ok(fetched.length > 0);- assert.equal(fetched.length, 3, 'only the first view starts at once');+ assert.equal(fetched.length, 3, 'only the 2 MB first view starts at once, beside the poster');+ assert.equal(timers.length, 0, 'no timer holds the world back');await window.__heroPrefetchReady;for (const href of Object.keys(window.__heroPrefetch)) assert.deepEqual(await window.__heroPrefetch[href], { href });assert.equal(fetched.length, 6, 'the full world follows once the first view has settled');});-test('a poster that never settles does not hold the world back for ever', () => {- const { fetched, timers, runTimers } = runHeroMode();- assert.equal(timers.length, 1);- assert.equal(timers[0].delay, 5000);- assert.deepEqual(fetched, []);- runTimers();- assert.ok(fetched.length > 0);-});--test('the prefetch starts once however many times the poster and the timeout report', () => {- const { fetched, window, runTimers } = runHeroMode();- window.__heroPosterSettled();- const count = fetched.length;- window.__heroPosterSettled();- runTimers();- assert.equal(fetched.length, count);-});-test('a scout page goes live but prefetches nothing and sets no timer', () => {const { mode, fetched, timers, window } = runHeroMode({ search: '?scout=1' });assert.equal(mode, 'live');@@ -128,7 +108,7 @@ test('the light path shows the poster and fetches nothing', () => {}});-test('a phone on a good connection waits for the poster and fetches nothing yet', () => {+test('a phone on a good connection is deferred and fetches nothing from the page head', () => {const { mode, fetched } = runHeroMode({ connection: { effectiveType: '4g' }, deviceMemory: 8, phone: true });assert.equal(mode, 'deferred');assert.equal(fetched.length, 0);