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(widgets): check the Windows 11 glance widget against its real contract
nirholas5ccfd01ba40c
diff --git a/docs/native-widgets.md b/docs/native-widgets.mdindex a85a6e12e..fe0522c1b 100644--- a/docs/native-widgets.md+++ b/docs/native-widgets.md@@ -86,6 +86,25 @@ Installs with the PWA, no store submission: open three.ws in Edge, install it, oboard (`Win + W`), **Add widgets**, pick **Agent glance**. It authenticates with your session andrefreshes every 15 minutes. Details in [glance.md](glance.md#on-the-windows-11-widgets-board).+### For developers++The board holds three moving parts: the `widgets` member of the PWA manifest (generated from+`vite.config.js`), the Adaptive Card template at `/api/glance/template`, and+[public/glance-sw.js](../public/glance-sw.js), which is the only thing that ever calls+`widgets.updateByTag`. `npm run check:windows-widget` verifies all three against each other+without Windows, and it is in `npm run gate`.++Two traps are worth knowing before you touch the card, because both draw an empty slot rather+than an error, and neither is visible outside a real board:++- **`msAcTemplate` is the URL of the card, not the card.** The host fetches nothing for you. A+ worker that hands `updateByTag` that string leaves every pinned slot blank.+- **The template is Adaptive Expression Language, not JavaScript.** An array is indexed with+ brackets (`${stats[0].label}`); a dot before a digit is a syntax error, and the engine throws+ on the whole card rather than skipping the one binding, so a single dotted index empties the+ entire widget. `api/_lib/glance-adaptive.js` writes paths the JavaScript way and converts them+ on the way out, and the guard expands the result in the board's own engine to prove it.+## macOS and iOSOne WidgetKit extension serves both, in small, medium and large. It fetches the samediff --git a/scripts/check-windows-widget.mjs b/scripts/check-windows-widget.mjsnew file mode 100644index 000000000..e8a186bda--- /dev/null+++ b/scripts/check-windows-widget.mjs@@ -0,0 +1,302 @@+#!/usr/bin/env node+/**+ * Verifies the Windows 11 "Agent glance" widget against the contract the+ * widgets board actually enforces.+ *+ * node scripts/check-windows-widget.mjs+ *+ * Why this exists. The board is the one surface no machine in this repo can+ * open: it needs Windows 11, Edge, and the PWA installed. Everything it does+ * is therefore invisible here until somebody pins the widget by hand, and a+ * broken slot renders as nothing at all rather than as an error. Four defects+ * have already reached that state, each of them green in every local check:+ * the worker passing the host a template URL where the card belonged, no+ * periodic sync ever registered, a slot pinned before the worker activated+ * staying empty, and a template written with JavaScript array paths that the+ * board's expression engine refuses to parse.+ *+ * The last one is the reason this runs the real engine rather than reading the+ * template with our own idea of a path. `${stats.0.label}` resolves fine in+ * JavaScript and is a syntax error in Adaptive Expression Language, and the+ * engine throws on the whole card rather than skipping the one binding, so one+ * dotted index empties the entire widget.+ *+ * A green run means the manifest, the worker, the endpoints and the card agree+ * with each other and with the board's documented contract. It does not mean+ * anyone has seen the widget on a board; that is still a human step, and it is+ * the last open line of prompts/finish/916-roadmap-native-widgets.md.+ */++import { readFileSync, existsSync } from 'node:fs';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+import { runInNewContext } from 'node:vm';+import { Template } from 'adaptivecards-templating';+import { adaptiveTemplate } from '../api/_lib/glance-adaptive.js';++const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const read = (rel) => readFileSync(join(REPO, rel), 'utf8');++const problems = [];+const fail = (msg) => problems.push(msg);+let checks = 0;+const pass = (msg) => {+ checks++;+ console.log(`[windows-widget] ok ${msg}`);+};++// https://learn.microsoft.com/en-us/microsoft-edge/progressive-web-apps/how-to/widgets+// `ms_ac_template` and `data` are what make the widget renderable at all; the+// board silently drops a definition that is missing either.+const REQUIRED_FIELDS = [+ 'name',+ 'description',+ 'tag',+ 'ms_ac_template',+ 'data',+ 'type',+ 'icons',+ 'screenshots',+];++// Every lifecycle event the board fires at the worker. A widget that handles+// only some of them works until the user does the one thing that fires the+// rest, which is exactly how an empty slot survives a casual test.+const REQUIRED_EVENTS = [+ 'activate',+ 'widgetinstall',+ 'widgetresume',+ 'widgetclick',+ 'widgetuninstall',+ 'periodicsync',+];++const pngSize = (rel) => {+ const buf = readFileSync(join(REPO, rel));+ return `${buf.readUInt32BE(16)}x${buf.readUInt32BE(20)}`;+};++// ---------------------------------------------------------------- manifest ---++/** Pull the `widgets:` array literal out of the PWA manifest by brace matching. */+function readWidgetsMember(source) {+ const start = source.search(/\n\t+widgets: \[/);+ if (start < 0) return null;+ const open = source.indexOf('[', start);+ let depth = 0;+ for (let i = open; i < source.length; i++) {+ if (source[i] === '[') depth++;+ else if (source[i] === ']' && --depth === 0) {+ return runInNewContext(`(${source.slice(open, i + 1)})`);+ }+ }+ return null;+}++const viteConfig = read('vite.config.js');+const widgets = readWidgetsMember(viteConfig);+if (!Array.isArray(widgets) || widgets.length !== 1) {+ console.error('[windows-widget] FAIL vite.config.js declares no single widgets member');+ process.exit(1);+}+const widget = widgets[0];+pass(`vite.config.js declares the ${widget.tag} widget`);++for (const field of REQUIRED_FIELDS) {+ if (widget[field] === undefined || widget[field] === null || widget[field] === '') {+ fail(`the widgets member is missing "${field}", which the board requires`);+ }+}+if (widget.type !== 'application/json') {+ fail(`the widgets member declares type "${widget.type}", but the data endpoint serves JSON`);+}+pass(`the widgets member carries all ${REQUIRED_FIELDS.length} required fields`);++// The board shows the screenshot in its widget picker, and it is the only+// picture of the widget a user sees before pinning it.+for (const shot of widget.screenshots || []) {+ if (!shot.label) fail(`the screenshot ${shot.src} has no label, which the picker reads out`);+ const rel = join('public', shot.src);+ if (!existsSync(join(REPO, rel))) {+ fail(`the screenshot ${shot.src} is declared but public/${shot.src} does not exist`);+ continue;+ }+ const real = pngSize(rel);+ if (shot.sizes && real !== shot.sizes) {+ fail(`the screenshot ${shot.src} is ${real} but the manifest declares ${shot.sizes}`);+ }+}+for (const icon of widget.icons || []) {+ const rel = join('public', icon.src);+ if (!existsSync(join(REPO, rel))) {+ fail(`the widget icon ${icon.src} is declared but public/${icon.src} does not exist`);+ continue;+ }+ const real = pngSize(rel);+ if (icon.sizes && real !== icon.sizes) {+ fail(`the widget icon ${icon.src} is ${real} but the manifest declares ${icon.sizes}`);+ }+}+pass(+ `${(widget.screenshots || []).length} screenshot and ${(widget.icons || []).length} icon exist at their declared sizes`,+);++// --------------------------------------------------------------- endpoints ---++const HANDLERS = {+ ms_ac_template: 'api/glance/template.js',+ data: 'api/glance/mine.js',+};+for (const [field, handler] of Object.entries(HANDLERS)) {+ const url = widget[field];+ if (!url || !url.startsWith('/api/glance/')) {+ fail(`the widgets member points ${field} at "${url}", which is not a glance endpoint`);+ continue;+ }+ if (!existsSync(join(REPO, handler))) {+ fail(`${field} is ${url} but ${handler} does not exist to serve it`);+ }+ const expected = `/${handler.replace(/^api\//, 'api/').replace(/\.js$/, '')}`;+ if (url !== expected) fail(`${field} is ${url} but the handler on disk answers ${expected}`);+}+pass('the template and data endpoints resolve to handlers in this repo');++// ------------------------------------------------------------------ worker ---++const sw = read('public/glance-sw.js');++if (!viteConfig.includes("'/glance-sw.js'")) {+ fail('public/glance-sw.js is never imported by the generated service worker, so nothing handles the widget');+}+pass('the generated service worker imports glance-sw.js');++const missingEvents = REQUIRED_EVENTS.filter(+ (name) => !sw.includes(`self.addEventListener('${name}'`),+);+if (missingEvents.length) {+ fail(`the worker never handles ${missingEvents.join(', ')}, so the board's slot goes stale`);+}+pass(`the worker handles all ${REQUIRED_EVENTS.length} board lifecycle events`);++const swTag = (sw.match(/const GLANCE_TAG = '([^']+)'/) || [, ''])[1];+if (swTag !== widget.tag) {+ fail(`the worker updates tag "${swTag}" but the manifest pins the widget to "${widget.tag}"`);+}+const swData = (sw.match(/const GLANCE_DATA_URL = '([^']+)'/) || [, ''])[1];+const swTemplate = (sw.match(/const GLANCE_TEMPLATE_URL = '([^']+)'/) || [, ''])[1];+if (swData !== widget.data) fail(`the worker fetches ${swData} but the manifest declares ${widget.data}`);+if (swTemplate !== widget.ms_ac_template) {+ fail(`the worker falls back to ${swTemplate} but the manifest declares ${widget.ms_ac_template}`);+}+pass('the worker, the manifest and the endpoints agree on the tag and both URLs');++// `msAcTemplate` is the URL of the card. The board fetches nothing on the+// worker's behalf, so a worker that hands `updateByTag` that string draws an+// empty slot. This is the 2026-09-04 defect; keep it fixed.+if (!/fetch\(url,/.test(sw) || !/definition\.msAcTemplate\)/.test(sw)) {+ fail('the worker no longer fetches msAcTemplate as a URL, which leaves every pinned slot empty');+}+if (!/updateByTag\(tag, \{ template, data:/.test(sw)) {+ fail('the worker no longer hands updateByTag the fetched card text');+}+pass('the worker fetches the Adaptive Card rather than passing the host its URL');++// `update` in the manifest is a request; nothing schedules it unless the worker+// registers a periodic sync under the widget's own tag.+if (typeof widget.update !== 'number') {+ fail('the widgets member advertises no update interval');+} else if (!/minInterval: Number\(definition\.update\) \* 1000/.test(sw)) {+ fail(`the manifest advertises a ${widget.update}s refresh that the worker never registers`);+}+if (!/periodicSync/.test(sw)) fail('the worker never touches the Periodic Background Sync API');+pass(`the worker registers the ${widget.update}s refresh the manifest advertises`);++// ------------------------------------------------------------------- card ---++/** The worker's own payload builder, which is what the board binds. */+function loadPayloadBuilder() {+ const self = { addEventListener() {}, registration: {} };+ runInNewContext(sw, {+ self,+ caches: undefined,+ fetch: undefined,+ AbortSignal: { timeout: () => undefined },+ Response: class {},+ Request: class {},+ console,+ });+ return self.__threewsGlancePayload;+}++const glancePayload = loadPayloadBuilder();+if (typeof glancePayload !== 'function') {+ fail('the worker no longer exposes its payload builder, so the card cannot be checked against it');+} else {+ const STATES = [+ ['signed out', { signedIn: false, signInUrl: 'https://three.ws/login' }],+ ['no agent yet', { signedIn: true, card: null, createUrl: 'https://three.ws/create' }],+ [+ 'a live agent',+ {+ signedIn: true,+ card: {+ name: 'Atlas Scout',+ headline: 'Working.',+ url: 'https://three.ws/agents/abc',+ metric: { label: 'Moves today', value: 17 },+ stats: [+ { label: 'This week', value: 96 },+ { label: 'All time', value: 400 },+ { label: 'Days live', value: 12 },+ ],+ },+ },+ ],+ ];+ const template = adaptiveTemplate();+ for (const [label, body] of STATES) {+ let card;+ try {+ card = new Template(structuredClone(template)).expand({ $root: glancePayload(body) });+ } catch (err) {+ fail(`the card does not expand in the board's engine for "${label}": ${err.message}`);+ continue;+ }+ const text = JSON.stringify(card);+ if (text.includes('${')) {+ fail(`the card still holds unbound expressions for "${label}", which draw as empty rows`);+ }+ for (const action of card.actions || []) {+ if (!/^https:\/\//.test(action.url || '')) {+ fail(`the "${action.title}" button goes to "${action.url}" for "${label}", not a real route`);+ }+ }+ }+ pass(`the card expands in the board's own engine for all ${STATES.length} states`);+}++// The two buttons are the widget's only click targets, and a fallback that+// 404s is worse than no button. Both live URLs are checked against the routes+// this site actually publishes.+const pages = JSON.parse(read('data/pages.json'));+const routes = new Set(pages.sections.flatMap((section) => section.pages).map((page) => page.path));+const fallbacks = [...new Set(JSON.stringify(adaptiveTemplate()).match(/https:\/\/three\.ws[^'"\s)]*/g) || [])];+for (const url of fallbacks) {+ const path = new URL(url).pathname;+ if (path.endsWith('.png')) {+ if (!existsSync(join(REPO, 'public', path))) fail(`the card's fallback image ${path} does not exist`);+ continue;+ }+ if (!routes.has(path)) fail(`the card's fallback button points at ${path}, which is not a published route`);+}+pass(`${fallbacks.length} fallback targets in the card resolve to real routes and assets`);++// ---------------------------------------------------------------- verdict ---++if (problems.length) {+ console.error('');+ for (const problem of problems) console.error(`[windows-widget] FAIL ${problem}`);+ console.error(`\n[windows-widget] ${problems.length} problem(s). See docs/native-widgets.md.`);+ process.exit(1);+}+console.log(`[windows-widget] ${checks} checks passed`);