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(glance): send an unlinked Apple widget to the Apple hand-off, not the Android one
nirholasd3df5f1bca58
diff --git a/api/glance/mine.js b/api/glance/mine.jsindex 767d2c3ec..16d7886a7 100644--- a/api/glance/mine.js+++ b/api/glance/mine.js@@ -37,9 +37,18 @@ import { isUuid } from '../_lib/validate.js';const SITE = 'https://three.ws';const SIGN_IN_URL = `${SITE}/login?next=%2Fglance`;-const LINK_URL = `${SITE}/glance?link=android`;const CREATE_URL = `${SITE}/create`;+// Where a widget with no working credential sends the person who taps it. The+// page can start the hand-off on its own if it knows which shell is asking, so+// the widget says: `?platform=ios` and `macos` open the Apple flow, anything+// else opens the Android one, which is what the shipped 1.1 APK gets by sending+// nothing at all.+const LINK_FLOWS = { android: 'android', ios: 'apple', macos: 'apple' };+export function linkUrl(platform) {+ return `${SITE}/glance?link=${LINK_FLOWS[platform] || 'android'}`;+}+export const GLANCE_STATES = {signedOut: 'signed-out',unlinked: 'unlinked',@@ -48,13 +57,13 @@ export const GLANCE_STATES = {};/** The notice card for each non-agent state. Exported for the tests. */-export function stateCard(state) {+export function stateCard(state, platform) {if (state === GLANCE_STATES.unlinked) {return noticeCard({name: 'Widget unlinked',headline: 'Tap to link this widget to your account again.',description: 'This widget no longer has access to your agent.',- url: LINK_URL,+ url: linkUrl(platform),});}if (state === GLANCE_STATES.noAgent) {@@ -110,8 +119,14 @@ export default wrap(async (req, res) => {const url = new URL(req.url, 'http://x');const format = url.searchParams.get('format') === 'png' ? 'png' : 'json';+ // Only ever narrows the tap target of a notice card; a card with an agent on+ // it already points at that agent on every platform.+ const platform = url.searchParams.get('platform') || '';+const caller = await resolveCaller(req, res, url);- if (caller.state) return respond(res, format, url, { state: caller.state, card: stateCard(caller.state), agents: [] });+ if (caller.state) {+ return respond(res, format, url, { state: caller.state, card: stateCard(caller.state, platform), agents: [], platform });+ }const owned = await sql`SELECT id, name@@ -130,17 +145,17 @@ export default wrap(async (req, res) => {const target = pinned || owned[0]?.id || null;if (!target) {- return respond(res, format, url, { state: GLANCE_STATES.noAgent, card: stateCard(GLANCE_STATES.noAgent), agents: [] });+ return respond(res, format, url, { state: GLANCE_STATES.noAgent, card: stateCard(GLANCE_STATES.noAgent, platform), agents: [], platform });}const card = await loadGlanceCard(target);if (!card) {- return respond(res, format, url, { state: GLANCE_STATES.noAgent, card: stateCard(GLANCE_STATES.noAgent), agents: owned });+ return respond(res, format, url, { state: GLANCE_STATES.noAgent, card: stateCard(GLANCE_STATES.noAgent, platform), agents: owned, platform });}- return respond(res, format, url, { state: GLANCE_STATES.agent, card, agents: owned, via: caller.via });+ return respond(res, format, url, { state: GLANCE_STATES.agent, card, agents: owned, via: caller.via, platform });});-async function respond(res, format, url, { state, card, agents, via = null }) {+async function respond(res, format, url, { state, card, agents, via = null, platform = '' }) {if (format === 'png') {const opts = pngOptions(url.searchParams);const { png, width, height, etag, cache } = await glancePng(card, opts);@@ -170,7 +185,7 @@ async function respond(res, format, url, { state, card, agents, via = null }) {agents: agents.map((a) => ({ id: a.id, name: a.name })),signInUrl: SIGN_IN_URL,createUrl: CREATE_URL,- linkUrl: LINK_URL,+ linkUrl: linkUrl(platform),});}diff --git a/apple/GlanceKit/GlanceClient.swift b/apple/GlanceKit/GlanceClient.swiftindex 5edd53f5a..3330563c5 100644--- a/apple/GlanceKit/GlanceClient.swift+++ b/apple/GlanceKit/GlanceClient.swift@@ -52,6 +52,10 @@ struct GlanceClient {URLQueryItem(name: "size", value: size.rawValue),URLQueryItem(name: "theme", value: theme.rawValue),URLQueryItem(name: "scale", value: String(size.scale)),+ // Only narrows where an unlinked card's tap goes: it sends this+ // device to the Apple hand-off on /glance rather than the Android+ // one. Everything else about the answer is identical.+ URLQueryItem(name: "platform", value: Self.platform),]guard let url = components?.url else { throw GlanceClientError.badStatus(0) }@@ -81,6 +85,17 @@ struct GlanceClient {)}+ /// The token platform this shell registers as, and the value+ /// `/api/glance/mine?platform=` reads. Matches GLANCE_TOKEN_PLATFORMS in+ /// api/_lib/glance-tokens.js.+ static let platform: String = {+ #if os(macOS)+ return "macos"+ #else+ return "ios"+ #endif+ }()+static let userAgent: String = {let version = Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "unknown"#if os(macOS)diff --git a/docs/api-reference.md b/docs/api-reference.mdindex c6f0e979c..f408f5de3 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -7490,11 +7490,11 @@ No auth. `json` is the card model, `svg` a self-contained image, `png` a bitmap### My card```-GET /api/glance/mine?format=json|png&agent=<uuid>&size=…&theme=dark|light&scale=…+GET /api/glance/mine?format=json|png&agent=<uuid>&size=…&theme=dark|light&scale=…&platform=android|ios|macosAuthorization: Bearer glw_… (widget token) or the session cookie```-Always `200`. JSON: `{ signedIn, state, via, card, notice, agents, signInUrl, createUrl, linkUrl }`, `state` one of `agent`, `signed-out`, `unlinked`, `no-agent`. PNG: the card bitmap for whichever state applies, with `x-glance-state`, `x-glance-url` (tap target), `x-glance-name`, `x-glance-metric`, `x-glance-agent`, `x-glance-updated` headers. `cache-control: private, no-store`.+Always `200`. JSON: `{ signedIn, state, via, card, notice, agents, signInUrl, createUrl, linkUrl }`, `state` one of `agent`, `signed-out`, `unlinked`, `no-agent`. PNG: the card bitmap for whichever state applies, with `x-glance-state`, `x-glance-url` (tap target), `x-glance-name`, `x-glance-metric`, `x-glance-agent`, `x-glance-updated` headers. `platform` narrows nothing but the tap target of a notice card: `ios` and `macos` point an unlinked widget at the Apple hand-off on `/glance`, anything else (including omitting it, which is what the shipped Android app does) points at the Android one. `cache-control: private, no-store`.### Widget tokensdiff --git a/docs/glance.md b/docs/glance.mdindex 1758f50e2..2f45c08ab 100644--- a/docs/glance.md+++ b/docs/glance.md@@ -91,6 +91,8 @@ Every state is a `200` with a designed card, never a `401`: a widget that render`format=png` (with `size`, `theme`, `scale` as above) returns the bitmap for whichever state applies, with `x-glance-state`, `x-glance-url` (the tap target), `x-glance-name`, `x-glance-metric` and `x-glance-agent` in the headers, so a native widget learns everything from the one request that fetched the image.+Add `platform=ios` or `platform=macos` and an unlinked card's tap opens the Apple hand-off on `/glance` instead of the Android one. It changes nothing else, and omitting it keeps the Android behaviour the shipped app relies on.+### `POST | GET | PATCH | DELETE /api/glance/token`The widget tokens. Session and same-site only. `POST { label?, platform?, agent? }` mints one and answers the plaintext exactly once, plus `links.android`, the `intent://` URL that hands it to the Android app, and `links.apple`, the `threews://glance/link` URL the Mac and iPhone apps claim. `GET` lists the caller's live tokens (prefix, label, platform, last seen), `PATCH { id, agent }` repoints one, `DELETE ?id=` revokes one. The revoke list on [/glance](https://three.ws/glance#devices) is this endpoint.diff --git a/docs/native-widgets.md b/docs/native-widgets.mdindex 714b4a6a0..a85a6e12e 100644--- a/docs/native-widgets.md+++ b/docs/native-widgets.md@@ -134,7 +134,7 @@ verifies both projects and the wire contract without a Mac.| Endpoint | Purpose || --- | --- |-| `GET /api/glance/mine?format=png&size=small\|medium\|large&theme=dark\|light&scale=1\|2\|3` | The card bitmap for the caller (widget token as `Authorization: Bearer`, or the session cookie). Always `200`; the state is in `x-glance-state` and the tap target in `x-glance-url`. |+| `GET /api/glance/mine?format=png&size=small\|medium\|large&theme=dark\|light&scale=1\|2\|3&platform=android\|ios\|macos` | The card bitmap for the caller (widget token as `Authorization: Bearer`, or the session cookie). Always `200`; the state is in `x-glance-state` and the tap target in `x-glance-url`. `platform` only decides which hand-off an unlinked card's tap opens. || `GET /api/glance/mine` | The same as JSON: `{ signedIn, state, card, notice, agents, … }`. || `POST /api/glance/token` | Mint a widget token (session, same-site). Returns the plaintext once plus `links.android` and `links.apple`. || `GET /api/glance/token` | List the caller's live tokens. |diff --git a/scripts/check-apple-widget.mjs b/scripts/check-apple-widget.mjsindex e34649cf5..c7a72cb23 100644--- a/scripts/check-apple-widget.mjs+++ b/scripts/check-apple-widget.mjs@@ -167,11 +167,20 @@ const svg = read('api/_lib/glance-svg.js');const token = read('api/glance/token.js');if (!client.includes('api/glance/mine')) fail('the Swift client does not call /api/glance/mine');-for (const param of ['format', 'size', 'theme', 'scale']) {+for (const param of ['format', 'size', 'theme', 'scale', 'platform']) {if (!client.includes(`name: "${param}"`)) fail(`the Swift client never sends ?${param}, which the server reads`);}pass('the Swift client calls the endpoint with the query the server reads');+// The platform hint only exists to point an unlinked card at the right+// hand-off, so the value the client sends has to be one the server routes.+const flows = (mine.match(/LINK_FLOWS = \{([^}]+)\}/) || [, ''])[1];+for (const value of ['macos', 'ios']) {+ if (!flows.includes(`${value}:`)) fail(`api/glance/mine.js does not route ?platform=${value} to a link flow`);+ if (!client.includes(`return "${value}"`)) fail(`the Swift client never reports platform=${value}`);+}+pass('the unlinked card sends an Apple device to the Apple hand-off');+// Header names, as the server sets them.const headers = [...mine.matchAll(/setHeader\('(x-glance-[a-z]+)'/g)].map((m) => m[1]);const usedByClient = headers.filter((h) => client.includes(`"${h}"`));diff --git a/specs/GLANCE_CARD.md b/specs/GLANCE_CARD.mdindex bed8d94a4..eed425e4a 100644--- a/specs/GLANCE_CARD.md+++ b/specs/GLANCE_CARD.md@@ -111,6 +111,8 @@ A response that has no agent to show (signed out, an unlinked widget token, an aThe JSON answer is `{ signedIn, state, via, card, notice, agents, signInUrl, createUrl, linkUrl }` with `state` one of `agent`, `signed-out`, `unlinked`, `no-agent`. When `state` is `agent`, `card` is the document above and `notice` is `null`; otherwise `card` is `null` and `notice` is a notice card.+A caller MAY add `platform=android|ios|macos`. It changes nothing but the `url` of a notice card, sending an unlinked widget to the hand-off its own shell can finish; omitting it is the Android hand-off, which is what a shell that predates the parameter gets.+The PNG answer is always status `200` and carries the same facts in headers, so a host that only downloads a bitmap still learns where a tap goes:| Header | Value |diff --git a/tests/glance-png.test.js b/tests/glance-png.test.jsindex 7889ca636..2c1afb994 100644--- a/tests/glance-png.test.js+++ b/tests/glance-png.test.js@@ -9,7 +9,7 @@ import sharp from 'sharp';import { buildGlanceCard, noticeCard } from '../api/_lib/glance-card.js';import { renderGlanceSvg } from '../api/_lib/glance-svg.js';import { rasterizeGlanceCard, pngOptions, GLANCE_PNG_SCALES } from '../api/_lib/glance-png.js';-import { stateCard, GLANCE_STATES } from '../api/glance/mine.js';+import { stateCard, linkUrl, GLANCE_STATES } from '../api/glance/mine.js';const NOW = new Date('2026-08-28T12:00:00.000Z');@@ -107,4 +107,18 @@ describe('notice cards', () => {expect((await sharp(out.png).metadata()).width).toBe(240);}});++ it('send an unlinked widget to the hand-off its own platform can finish', () => {+ // The shipped 1.1 Android APK sends no platform at all, so the default+ // has to stay exactly where it was pointing before Apple existed here.+ expect(linkUrl('')).toBe('https://three.ws/glance?link=android');+ expect(linkUrl(undefined)).toBe('https://three.ws/glance?link=android');+ expect(linkUrl('android')).toBe('https://three.ws/glance?link=android');+ expect(linkUrl('ios')).toBe('https://three.ws/glance?link=apple');+ expect(linkUrl('macos')).toBe('https://three.ws/glance?link=apple');+ // An unknown value is a caller we do not know, not a reason to 400 a+ // widget that is already in trouble.+ expect(linkUrl('windows')).toBe('https://three.ws/glance?link=android');+ expect(stateCard(GLANCE_STATES.unlinked, 'macos').url).toBe('https://three.ws/glance?link=apple');+ });});