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(brownout): finish the proofs page and cover the knock SDK
nirholasdefdf9788a4b
diff --git a/data/pages.json b/data/pages.jsonindex 3164604e2..4ba2f6a9a 100644--- a/data/pages.json+++ b/data/pages.json@@ -2351,6 +2351,14 @@"priority": 0.6,"changefreq": "daily","added": "2026-08-12"+ },+ {+ "path": "/preflight",+ "title": "x402 Preflight: can this seller actually settle?",+ "description": "Check whether any x402 seller can complete a payment before you sign one. Fetches the seller's signed payability attestation and verifies the ed25519 signature, the expiry and the subject entirely in your browser. Free, open format, works against any origin.",+ "priority": 0.7,+ "changefreq": "weekly",+ "added": "2026-08-28"}]},diff --git a/extensions/checkout-companion/manifest.json b/extensions/checkout-companion/manifest.jsonindex eb606f9be..74291cdb8 100644--- a/extensions/checkout-companion/manifest.json+++ b/extensions/checkout-companion/manifest.json@@ -4,7 +4,7 @@"short_name": "Checkout Companion","version": "1.0.0","description": "Your agent reads the checkout before you pay: what it really costs, whether it repeats, and what the fine print commits you to.",- "homepage_url": "https://three.ws/checkout-companion",+ "homepage_url": "https://three.ws/companion","icons": {"16": "icons/icon-16.png",diff --git a/extensions/checkout-companion/popup.html b/extensions/checkout-companion/popup.htmlindex 30a90a185..4a051800b 100644--- a/extensions/checkout-companion/popup.html+++ b/extensions/checkout-companion/popup.html@@ -41,7 +41,7 @@<footer><a href="options.html" target="_blank" rel="noopener">Account and privacy</a>- <a href="https://three.ws/checkout-companion" target="_blank" rel="noopener">How it works</a>+ <a href="https://three.ws/companion" target="_blank" rel="noopener">How it works</a></footer><script src="popup.js" type="module"></script></body>diff --git a/packages/knock-sdk/test/knock.test.mjs b/packages/knock-sdk/test/knock.test.mjsnew file mode 100644index 000000000..b30dc1e42--- /dev/null+++ b/packages/knock-sdk/test/knock.test.mjs@@ -0,0 +1,137 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { KnockError, confirmationFor, formatUsdc, knock, quote, receipt } from '../src/index.js';++const FREE_DOOR = {+ handle: 'ada', display_name: 'Ada', free: true, price: '$0.00', price_atomics: '0',+ currency: 'USDC', networks: [], max_chars: 600, headline: null, greeting: null,+ endpoint: 'https://three.ws/api/knock/send', protocol: 'http',+};+const PAID_DOOR = {+ ...FREE_DOOR, free: false, price: '$0.05', price_atomics: '50000',+ networks: ['solana'], endpoint: 'https://three.ws/api/x402/knock?to=ada', protocol: 'x402',+};++function stubFetch(routes) {+ const calls = [];+ const f = async (url, init = {}) => {+ calls.push({ url: String(url), init });+ const key = Object.keys(routes).find((k) => String(url).includes(k));+ if (!key) return new Response('{"error":"not_found"}', { status: 404, headers: { 'content-type': 'application/json' } });+ const { status = 200, body } = routes[key];+ return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });+ };+ f.calls = calls;+ return f;+}++test('formatUsdc renders atomic units the way the API does', () => {+ assert.equal(formatUsdc(0n), '$0.00');+ assert.equal(formatUsdc('50000'), '$0.05');+ assert.equal(formatUsdc('1000'), '$0.001');+ assert.equal(formatUsdc('1000000'), '$1.00');+ assert.equal(formatUsdc('1234500000'), '$1234.50');+});++test('quote normalizes the handle and reads the public door', async () => {+ const f = stubFetch({ '/api/knock/door': { body: { door: PAID_DOOR } } });+ const door = await quote('@ADA', { fetch: f });+ assert.equal(door.price, '$0.05');+ assert.match(f.calls[0].url, /handle=ada/);+});++test('quote refuses a handle that could never be one', async () => {+ await assert.rejects(() => quote('not a handle!', { fetch: stubFetch({}) }), (err) => {+ assert.ok(err instanceof KnockError);+ assert.equal(err.code, 'bad_handle');+ return true;+ });+});++test('a free door sends with nothing but fetch', async () => {+ const f = stubFetch({+ '/api/knock/door': { body: { door: FREE_DOOR } },+ '/api/knock/send': { status: 201, body: { ok: true, knock_id: 'k1', delivered_to: 'Ada', paid: '$0.00', receipt_url: 'https://three.ws/api/knock/reply?id=k1&token=t', duplicate: false } },+ });+ const result = await knock({ to: 'ada', from: 'Bob', message: 'a real message', fetch: f });+ assert.equal(result.knock_id, 'k1');+ const sent = JSON.parse(f.calls[1].init.body);+ assert.equal(sent.to, 'ada');+ assert.equal(sent.sender_kind, 'agent');+});++test('a priced door refuses to guess a wallet', async () => {+ const f = stubFetch({ '/api/knock/door': { body: { door: PAID_DOOR } } });+ await assert.rejects(() => knock({ to: 'ada', from: 'Bob', message: 'a real message', fetch: f }), (err) => {+ assert.equal(err.code, 'payment_required');+ assert.match(err.message, /fetchWithPayment/);+ return true;+ });+});++test('a priced door pays through the caller-supplied x402 fetch', async () => {+ const f = stubFetch({ '/api/knock/door': { body: { door: PAID_DOOR } } });+ let paidUrl = null;+ const fetchWithPayment = async (url, init) => {+ paidUrl = String(url);+ assert.equal(JSON.parse(init.body).subject, 'hello');+ return new Response(JSON.stringify({ ok: true, knock_id: 'k2', delivered_to: 'Ada', paid: '$0.05', receipt_url: 'r', duplicate: false }), {+ status: 200, headers: { 'content-type': 'application/json' },+ });+ };+ const result = await knock({ to: 'ada', from: 'Bob', message: 'a real message', subject: 'hello', fetch: f, fetchWithPayment });+ assert.equal(result.paid, '$0.05');+ assert.equal(paidUrl, PAID_DOOR.endpoint);+});++test('maxPriceAtomics is checked before any payment is attempted', async () => {+ const f = stubFetch({ '/api/knock/door': { body: { door: PAID_DOOR } } });+ let paid = false;+ await assert.rejects(+ () => knock({+ to: 'ada', from: 'Bob', message: 'a real message', maxPriceAtomics: 10000n, fetch: f,+ fetchWithPayment: async () => { paid = true; return new Response('{}'); },+ }),+ (err) => {+ assert.equal(err.code, 'over_budget');+ return true;+ },+ );+ assert.equal(paid, false, 'nothing may be paid once the ceiling is exceeded');+});++test('a message longer than the door allows never reaches the network', async () => {+ const f = stubFetch({ '/api/knock/door': { body: { door: { ...FREE_DOOR, max_chars: 40 } } } });+ await assert.rejects(() => knock({ to: 'ada', from: 'Bob', message: 'x'.repeat(41), fetch: f }), (err) => {+ assert.equal(err.code, 'message_too_long');+ return true;+ });+ assert.equal(f.calls.length, 1, 'only the door read happened');+});++test('server errors surface with their code and status', async () => {+ const f = stubFetch({+ '/api/knock/door': { body: { door: FREE_DOOR } },+ '/api/knock/send': { status: 429, body: { error: 'door_full', error_description: 'full for today' } },+ });+ await assert.rejects(() => knock({ to: 'ada', from: 'Bob', message: 'a real message', fetch: f }), (err) => {+ assert.equal(err.code, 'door_full');+ assert.equal(err.status, 429);+ return true;+ });+});++test('receipt reads the knock state back with no account', async () => {+ const f = stubFetch({ '/api/knock/reply': { body: { knock: { id: 'k1', status: 'replied', reply: 'sure', seen: true, amount: '$0.05' } } } });+ const state = await receipt('https://three.ws/api/knock/reply?id=k1&token=t', { fetch: f });+ assert.equal(state.reply, 'sure');+});++test('confirmationFor names the recipient, amount, token and chain', () => {+ const c = confirmationFor(PAID_DOOR);+ assert.equal(c.recipient, 'Ada (@ada)');+ assert.equal(c.amount, '$0.05');+ assert.equal(c.token, 'USDC');+ assert.deepEqual(c.chains, ['solana']);+ assert.match(c.note, /settles directly/);+});diff --git a/pages/brownout.html b/pages/brownout.htmlindex 6eae096f4..415ee066e 100644--- a/pages/brownout.html+++ b/pages/brownout.html@@ -210,7 +210,7 @@<section class="bo-live-panel" id="bo-live-panel" hidden><div class="bo-live-head">- <h2>This page load</h2>+ <h2>A live call, from your browser, just now</h2><span class="bo-tier" id="bo-live-tier" data-tier="none">unknown</span></div><p class="bo-live-body" id="bo-live-body"></p>diff --git a/src/brownout-page.js b/src/brownout-page.jsindex 87a9fd083..2d648de49 100644--- a/src/brownout-page.js+++ b/src/brownout-page.js@@ -70,24 +70,54 @@ function humanAge(ms) {return `${Math.round(m / 60)}h`;}-function renderLivePanel(prov) {+// A live read of a real data endpoint, made from the visitor's browser, right+// now. The registry endpoint itself is a disk read and touches no upstream, so+// reporting ITS provenance would show an empty trace and prove nothing. This+// asks a market endpoint instead, which fans out across several providers, and+// shows what actually happened. A claim about resilience is cheap; the same+// claim measured on a request the reader just made is not.+const PROBE_ENDPOINT = '/api/coin/global';++async function renderLivePanel() {const panel = document.getElementById('bo-live-panel');const tierEl = document.getElementById('bo-live-tier');const body = document.getElementById('bo-live-body');- if (!panel || !prov) return;+ if (!panel || !tierEl || !body) return;++ let res;+ try {+ res = await fetch(PROBE_ENDPOINT, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(20_000) });+ } catch {+ // The panel is a demonstration, not the page. If the probe cannot run, the+ // page is still worth reading, so it simply does not appear.+ return;+ }+ const prov = parseProvenance(res.headers);+ if (!prov) {+ // Every source answered from cache, so nothing was recorded. That is a real+ // and healthy state, and saying so beats hiding the panel.+ tierEl.dataset.tier = 'cache';+ tierEl.textContent = 'cache';+ body.textContent =+ `A live call to ${PROBE_ENDPOINT} from your browser just now was answered entirely from cache, ` ++ 'so it touched no upstream at all. That is the healthy case: the fastest request is the one that never leaves.';+ panel.hidden = false;+ return;+ }const tier = prov.tier || 'none';tierEl.dataset.tier = tier;tierEl.textContent = tier;- const parts = [];- parts.push(- `The request that loaded this list touched ${prov.ok + prov.failed} source${prov.ok + prov.failed === 1 ? '' : 's'} ` +- `in ${prov.ms}ms, and what you are reading ${TIER_COPY[tier] || 'was served from an unknown tier'}.`,- );+ const touched = prov.ok + prov.failed;+ const parts = [+ `A live call to ${PROBE_ENDPOINT} from your browser just now touched ${touched} source${touched === 1 ? '' : 's'} ` ++ `in ${prov.ms}ms, and the answer ${TIER_COPY[tier] || 'came from an unknown tier'}.`,+ ];if (prov.failed > 0) {parts.push(- `${prov.failed} of them did not answer, and you still got a page: that is the whole point, and it is why the header exists.`,+ `${prov.failed} of them did not answer, and the request succeeded anyway. ` ++ 'That is the whole point, and without the header nobody would ever have known it happened.',);}body.textContent = parts.join(' ');@@ -213,9 +243,9 @@ async function main() {return;}- // Read the provenance of THIS request before anything else: it is the most- // honest demonstration on the page, and it costs nothing.- renderLivePanel(parseProvenance(res.headers));+ // Fire the live probe alongside the registry render rather than before it:+ // it is a demonstration, and it must never delay the page it decorates.+ void renderLivePanel();if (!res.ok) {if (status) status.textContent = 'The registry answered with an error.';