Skip to content

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.

fix(ibm): let the page IBM hosts read the files it was built to read

nirholascbf83b2a0064
diff --git a/docs/ops/ibm-hosted-page-audit.md b/docs/ops/ibm-hosted-page-audit.md
new file mode 100644
index 000000000..a9073888b
--- /dev/null
+++ b/docs/ops/ibm-hosted-page-audit.md
@@ -0,0 +1,84 @@
+# IBM hosted-page audit: proving the publish-once page works on a foreign origin
+
+`scripts/audit-ibm-hosted-page.mjs` (`npm run audit:ibm-hosted`) loads
+`pages/ibm/hello.html` the way IBM's visitors load it: from a domain that is not
+three.ws.
+
+Every other page audit in this repo loads pages from three.ws itself. That is
+the right test for every page except this one. `hello.html` is a **publish-once**
+file: it is uploaded to a host we do not control (see
+[pages/ibm/HOSTING.md](../../pages/ibm/HOSTING.md)), and from there every asset it
+names and every document it fetches from three.ws is a **cross-origin** request.
+Two classes of break live only on that origin, and both are invisible to
+`npm run audit:console`.
+
+## What it catches
+
+**1. A missing `access-control-allow-origin` on something the page reads.**
+On 2026-09-04 `/x402.js`, `/i18n.js`, `/locales/*.json` and `/ibm/hello.live`
+all answered without one. On three.ws all four were perfect, and the console
+sweep was green. On the hosted copy:
+
+- the live-update fetch failed, so the page was frozen on its baked baseline,
+ which is precisely the thing HOSTING.md promises will not happen;
+- the language switcher never mounted;
+- the paid x402 demo never armed.
+
+The fix is header routes in `vercel.json` granting those paths open CORS, next
+to the same grant `/embed/v1.js` and `/assistant/v1.js` already carry. They are
+public, unauthenticated, cookie-free static files whose whole purpose is to be
+read from other origins.
+
+**2. A root-relative URL that resolves against the publisher's domain.**
+`hello.live.html` is authored to run same-origin on three.ws, so it names its own
+scripts `/x402.js`. `scripts/build-ibm-shell.mjs` rewrites those to absolute URLs
+when it bakes `hello.html`, but the *runtime* live-update path swaps in the
+fetched document as-is, so the same URL came back root-relative and asked IBM's
+server for a file only three.ws has. The boot script now applies the same
+rewrite (`abs()`), and the builder refuses to bake a `href`/`data-src`/`poster`/
+`action`/`srcset` that is root-relative, because those are not rewritten
+anywhere and would break the same way.
+
+Runtime `i18n.js` had the same shape: it fetched `/locales/<code>.json` and
+`/api/locale` root-relative, which resolves against whatever page loaded it.
+`src/i18n.js` now derives its data origin from `import.meta.url`, so the
+catalogs travel with the code. On three.ws itself that resolves to `''` and the
+URLs are byte-identical to what they always were.
+
+## Running it
+
+```bash
+# What IBM's visitors get right now.
+npm run audit:ibm-hosted
+
+# What this working tree would give them. Needs a local server and a built dist/
+# (the page loads the agent-3d bundle from it like any visitor would).
+npm run build && node server/index.mjs &
+THREE_WS_ORIGIN=http://localhost:8080 npm run audit:ibm-hosted
+
+HEADFUL=1 npm run audit:ibm-hosted # watch it run
+```
+
+The audit serves `pages/ibm/` from a throwaway origin of its own and lets the
+page talk to a real three.ws **over the network**. Nothing is stubbed or
+intercepted: a proxy answering for three.ws would satisfy CORS on the browser's
+behalf and blind the audit to the only failure it exists to catch. That is worth
+stating plainly because the first draft of this script did exactly that and
+reported a green run over a page whose live update was dead.
+
+## What it asserts
+
+| Check | Why it is the right signal |
+|---|---|
+| Live update applied | `data-ibm-source="live"` on `<html>`. `"baked"` means the fetch failed and the visitor is reading whatever content was frozen in at publish time. |
+| Language switcher mounted | `customElements.get('lang-switcher')` is defined, which happens only if `i18n.js` loaded, ran, and read a catalog. |
+| x402 widget bound | A payable element carries `data-x402-bound="1"`, which `x402.js` sets on each element it binds. The markup alone is present even when the script was blocked, so the markup alone proves nothing. |
+| No console errors, page errors or failed requests | On this page a console error means a visitor lost a demo. Auth- and payment-gated statuses (401/402/403/429) are expected: a paid demo answering 402 is the demo working. The console filter is `scripts/lib/console-noise.mjs`, shared with `npm run audit:console` so the two audits agree about what a defect is. |
+
+Exit code is 0 only when all four pass.
+
+## Related
+
+- [pages/ibm/HOSTING.md](../../pages/ibm/HOSTING.md) - what IBM publishes and how.
+- [page-audit.md](page-audit.md) - the authed full-site sweep.
+- `npm run audit:console` - the console sweep over every route on three.ws itself.
diff --git a/package.json b/package.json
index 5d9da5905..6601638cf 100644
--- a/package.json
+++ b/package.json
@@ -332,6 +332,7 @@
"load:viewers": "node scripts/viewer-load-test.mjs",
"audit:mobile-touch": "node scripts/mobile-touch-audit.mjs",
"audit:overlays": "node scripts/audit-overlays.mjs",
+ "audit:ibm-hosted": "node scripts/audit-ibm-hosted-page.mjs",
"test:pages": "node scripts/test-pages.mjs",
"verify:ibm": "node scripts/verify-ibm-pages.mjs",
"verify:zauth": "node scripts/verify-zauth-runtime.mjs",
diff --git a/pages/ibm/hello.html b/pages/ibm/hello.html
index c4a854a2a..8feae236a 100644
--- a/pages/ibm/hello.html
+++ b/pages/ibm/hello.html
@@ -2928,8 +2928,17 @@ a:focus-visible{outline-offset:3px}
function descFromInert(n) {
return { src: n.getAttribute('data-ibm-src') || '', type: n.getAttribute('data-ibm-type') || '', code: n.textContent || '' };
}
+ // The live document is authored to run same-origin on three.ws, so its own
+ // scripts are named root-relative ('/x402.js'). Here the page is somebody
+ // else's domain, where that resolves against THEIR origin and 404s, so the
+ // fetched document gets the same rewrite the baked copy got at build time.
+ // On three.ws itself the rewrite is a no-op: the origin it prepends is the
+ // one the page is already served from.
+ function abs(src) {
+ return src.charAt(0) === '/' && src.charAt(1) !== '/' ? "https://three.ws" + src : src;
+ }
function descFromLive(n) {
- return { src: n.getAttribute('src') || '', type: (n.getAttribute('type') || '').toLowerCase(), code: n.textContent || '' };
+ return { src: abs(n.getAttribute('src') || ''), type: (n.getAttribute('type') || '').toLowerCase(), code: n.textContent || '' };
}
// Run a list of script descriptors in order. src scripts are awaited so anything
// that depends on x402.js / agent-3d.js (earlier in the page) sees it loaded.
diff --git a/scripts/audit-ibm-hosted-page.mjs b/scripts/audit-ibm-hosted-page.mjs
new file mode 100644
index 000000000..19c025c18
--- /dev/null
+++ b/scripts/audit-ibm-hosted-page.mjs
@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// Proves the publish-once IBM partnership page still works on somebody else's
+// domain.
+//
+// pages/ibm/hello.html is uploaded once onto a host we do not control (see
+// pages/ibm/HOSTING.md). Everything about it is therefore the opposite of every
+// other page in this repo: it runs on a FOREIGN ORIGIN, so every asset it names
+// and every document it fetches from three.ws is a cross-origin request. Two
+// whole classes of break are invisible to `npm run audit:console`, which loads
+// /ibm/hello from three.ws itself, where all of it is same-origin:
+//
+// 1. A missing `access-control-allow-origin` on something the page reads.
+// On 2026-09-04 /x402.js, /i18n.js, /locales/*.json and /ibm/hello.live all
+// answered without one, so on the hosted copy the live-update fetch failed
+// silently (the page froze on its baked baseline, the exact thing HOSTING.md
+// promises will not happen), the language switcher never mounted, and the
+// paid demo never armed. On three.ws all four were perfect.
+// 2. A root-relative URL in the fetched live document. It resolves against the
+// PUBLISHER'S origin once swapped in, so '/x402.js' asks ibm.com for a file
+// only three.ws has.
+//
+// This audit reproduces the hosted deployment exactly: it serves pages/ibm/ from
+// a throwaway origin of its own and lets the page talk to a real three.ws over
+// the network, so the browser applies its real cross-origin rules. Nothing is
+// stubbed or intercepted; a proxy that answered for three.ws would satisfy CORS
+// on the browser's behalf and blind the audit to the only failure it exists to
+// catch. A console error is a failure, because on that page a console error
+// means a visitor lost a demo.
+//
+// Usage:
+// node scripts/audit-ibm-hosted-page.mjs # against production
+// THREE_WS_ORIGIN=http://localhost:8080 node scripts/audit-ibm-hosted-page.mjs
+// HEADFUL=1 node scripts/audit-ibm-hosted-page.mjs # watch it run
+//
+// Point THREE_WS_ORIGIN at a local `node server/index.mjs` to test THIS working
+// tree; leave it off to test what the partner's visitors get right now. A local
+// server needs a built dist/ (`npm run build`), because the page loads the
+// agent-3d bundle from it like any visitor would.
+
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { join, extname, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright';
+import { isIgnorableConsole } from './lib/console-noise.mjs';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PAGE_DIR = join(ROOT, 'pages/ibm');
+const THREE_WS = (process.env.THREE_WS_ORIGIN || 'https://three.ws').replace(/\/$/, '');
+const SETTLE_MS = Number(process.env.SETTLE_MS) || 12_000;
+
+const TYPES = {
+ '.html': 'text/html; charset=utf-8',
+ '.js': 'text/javascript; charset=utf-8',
+ '.css': 'text/css; charset=utf-8',
+ '.svg': 'image/svg+xml',
+ '.woff2': 'font/woff2',
+ '.json': 'application/json',
+ '.png': 'image/png',
+};
+
+// The publisher's own web server: it holds hello.html and the files that travel
+// with it (fonts/, vendor/, three.svg) and nothing else, which is precisely the
+// deployment HOSTING.md describes.
+function servePublisher() {
+ return new Promise((resolve) => {
+ const srv = createServer(async (req, res) => {
+ const path = decodeURIComponent(req.url.split('?')[0]);
+ const file = path === '/' || path === '/hello' ? 'hello.html' : path.replace(/^\//, '');
+ if (file.includes('..')) {
+ res.statusCode = 400;
+ return res.end('bad path');
+ }
+ try {
+ let bytes = await readFile(join(PAGE_DIR, file));
+ // The published file names three.ws absolutely, which is the point of
+ // baking it. Repoint those literals at the origin under test so a local
+ // server can stand in for three.ws; against production this is a no-op.
+ if (THREE_WS !== 'https://three.ws' && extname(file) === '.html') {
+ bytes = Buffer.from(String(bytes).replaceAll('https://three.ws', THREE_WS));
+ }
+ res.setHeader('content-type', TYPES[extname(file)] || 'application/octet-stream');
+ res.end(bytes);
+ } catch {
+ res.statusCode = 404;
+ res.end('not found');
+ }
+ });
+ srv.listen(0, () => resolve({ srv, port: srv.address().port }));
+ });
+}
+
+const { srv, port } = await servePublisher();
+const publisherOrigin = `http://127.0.0.1:${port}`;
+
+const problems = [];
+
+const browser = await chromium.launch({ headless: !process.env.HEADFUL });
+const page = await browser.newPage();
+
+// A paid demo answering 402 is the demo WORKING: the page asks an x402 endpoint
+// for a price and gets one. The console sweep classifies auth- and
+// payment-gated statuses the same way, and sharing its filter keeps the two
+// audits agreeing about what counts as a defect.
+const EXPECTED_STATUS = new Set([401, 402, 403, 429]);
+
+page.on('console', (m) => {
+ if (m.type() === 'error' && !isIgnorableConsole(m.text())) problems.push(`console: ${m.text()}`);
+});
+page.on('pageerror', (e) => problems.push(`pageerror: ${e.message}`));
+page.on('response', (r) => {
+ if (r.status() >= 400 && !EXPECTED_STATUS.has(r.status())) {
+ problems.push(`http ${r.status()}: ${r.url()}`);
+ }
+});
+page.on('requestfailed', (r) => {
+ problems.push(`request failed: ${r.url()} (${r.failure()?.errorText || 'unknown'})`);
+});
+
+// The page gives its live fetch a 3 s budget, which is right for a visitor on a
+// CDN-warm origin and wrong for the first cold request against a server this
+// audit just started. Warm the document once so the measurement is of the page,
+// not of a cold start this harness introduced.
+await fetch(`${THREE_WS}/ibm/hello.live`, { headers: { origin: publisherOrigin } }).catch(() => {});
+
+await page.goto(`${publisherOrigin}/hello`, { waitUntil: 'domcontentloaded' });
+await page.waitForTimeout(SETTLE_MS);
+
+// The three guarantees the hosted copy makes, each of which failed silently at
+// least once: the live document replaced the baked baseline, the runtime i18n
+// mounted its switcher, and the x402 widget bound its payable element.
+const state = await page.evaluate(() => ({
+ source: document.documentElement.getAttribute('data-ibm-source'),
+ langSwitcher: !!customElements.get('lang-switcher'),
+ // `data-x402Bound` is set by x402.js on each payable element it binds, so
+ // this is proof the script LOADED and ran, not merely that the markup for a
+ // payable button is present (which it is even when the script was blocked).
+ payable: !!document.querySelector('[data-x402-endpoint][data-x402-bound="1"]'),
+}));
+
+await browser.close();
+srv.close();
+
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+
+console.log(`\nIBM hosted-page audit: publisher ${publisherOrigin}, three.ws ${THREE_WS}\n`);
+const checks = [
+ ['live update applied (not frozen on the baked baseline)', state.source === 'live'],
+ ['runtime i18n mounted its language switcher', state.langSwitcher],
+ ['x402 widget bound its payable element', state.payable],
+ ['no console errors, page errors or failed requests', problems.length === 0],
+];
+for (const [label, ok] of checks) console.log(` ${ok ? green('PASS') : red('FAIL')} ${label}`);
+
+if (problems.length) {
+ console.log(`\n${red(`${problems.length} problem(s):`)}`);
+ for (const p of [...new Set(problems)]) console.log(` - ${p}`);
+}
+
+const failed = checks.some(([, ok]) => !ok);
+console.log(failed ? `\n${red('FAILED')}\n` : `\n${green('The hosted copy works on a foreign origin.')}\n`);
+process.exit(failed ? 1 : 0);
diff --git a/scripts/build-ibm-shell.mjs b/scripts/build-ibm-shell.mjs
index 10dabcc4b..8ed1a3404 100644
--- a/scripts/build-ibm-shell.mjs
+++ b/scripts/build-ibm-shell.mjs
@@ -86,8 +86,17 @@ function boot() {
function descFromInert(n) {
return { src: n.getAttribute('data-ibm-src') || '', type: n.getAttribute('data-ibm-type') || '', code: n.textContent || '' };
}
+ // The live document is authored to run same-origin on three.ws, so its own
+ // scripts are named root-relative ('/x402.js'). Here the page is somebody
+ // else's domain, where that resolves against THEIR origin and 404s, so the
+ // fetched document gets the same rewrite the baked copy got at build time.
+ // On three.ws itself the rewrite is a no-op: the origin it prepends is the
+ // one the page is already served from.
+ function abs(src) {
+ return src.charAt(0) === '/' && src.charAt(1) !== '/' ? ${JSON.stringify(SITE_ORIGIN)} + src : src;
+ }
function descFromLive(n) {
- return { src: n.getAttribute('src') || '', type: (n.getAttribute('type') || '').toLowerCase(), code: n.textContent || '' };
+ return { src: abs(n.getAttribute('src') || ''), type: (n.getAttribute('type') || '').toLowerCase(), code: n.textContent || '' };
}
// Run a list of script descriptors in order. src scripts are awaited so anything
// that depends on x402.js / agent-3d.js (earlier in the page) sees it loaded.
@@ -165,7 +174,29 @@ function boot() {
`.trim();
}
+// Only <script src> is rewritten to our origin, at bake time and again in the
+// boot script's live path. Every other asset the live page names is either
+// absolute already or ships alongside the published file ('./fonts/…'). A
+// root-relative value in any other attribute would therefore resolve against
+// the publisher's domain and 404 there while working perfectly on three.ws,
+// which is the kind of break nobody sees until a partner reports it. Refuse to
+// bake one: either make the reference absolute, or teach absolutize() about the
+// attribute in both places.
+const ROOT_RELATIVE_ATTR = /\s(href|data-src|poster|action|srcset)="\/(?!\/)/gi;
+
+function assertNoUnhandledRootRelative(live) {
+ const found = [...live.matchAll(ROOT_RELATIVE_ATTR)].map((m) => m[1].toLowerCase());
+ if (!found.length) return;
+ const attrs = [...new Set(found)].join(', ');
+ throw new Error(
+ `hello.live.html: root-relative ${attrs} would resolve against the publisher's own domain ` +
+ 'on the hosted copy. Use an absolute https://three.ws URL, or extend absolutize() in ' +
+ 'this script and abs() in boot() to cover the attribute.',
+ );
+}
+
function generate(live) {
+ assertNoUnhandledRootRelative(live);
const headEnd = live.indexOf('</head>');
const bodyOpen = live.indexOf('<body');
const bodyClose = live.lastIndexOf('</body>');
diff --git a/src/i18n.js b/src/i18n.js
index 89081d833..2c9cfa833 100644
--- a/src/i18n.js
+++ b/src/i18n.js
@@ -16,7 +16,23 @@
// and run without a DOM.
const STORAGE_KEY = 'twx_lang';
-const LOCALES_BASE = '/locales';
+
+// The catalogs live wherever this module was served from, which is not always
+// the page's own origin: /i18n.js is published onto partner pages (the IBM
+// partnership page hosts a copy on its own domain and loads this script from
+// three.ws), where a root-relative fetch would resolve against THEIR origin and
+// 404. Deriving the base from import.meta.url keeps the data with the code.
+// Same-origin pages, which is every page on three.ws itself, get '' and the
+// exact root-relative URLs they always had.
+const ASSET_ORIGIN = (() => {
+ try {
+ const origin = new URL(import.meta.url).origin;
+ return typeof location !== 'undefined' && origin !== location.origin ? origin : '';
+ } catch {
+ return '';
+ }
+})();
+const LOCALES_BASE = `${ASSET_ORIGIN}/locales`;
const hasDOM = typeof document !== 'undefined';
@@ -255,7 +271,9 @@ function mergeCatalog(target, slice) {
async function fetchSlice(code, names) {
if (!names.length) return {};
try {
- return await fetchJSON(`/api/locale?code=${encodeURIComponent(code)}&ns=${names.join(',')}`);
+ return await fetchJSON(
+ `${ASSET_ORIGIN}/api/locale?code=${encodeURIComponent(code)}&ns=${names.join(',')}`,
+ );
} catch {
try {
return await fetchJSON(`${LOCALES_BASE}/${code}.json`);
diff --git a/vercel.json b/vercel.json
index feff5a727..58efba695 100644
--- a/vercel.json
+++ b/vercel.json
@@ -255,6 +255,14 @@
},
"continue": true
},
+ {
+ "src": "/locales/(.+)\\.json",
+ "headers": {
+ "access-control-allow-origin": "*",
+ "cross-origin-resource-policy": "cross-origin"
+ },
+ "continue": true
+ },
{
"src": "/cdn/(.+)",
"dest": "/api/cdn-object?key=$1"