Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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
```sh
npx 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 3
node 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.html
index 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.mjs
index 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.js
index 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.js
index 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);