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.

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.js
index 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.swift
index 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.md
index 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|macos
Authorization: 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 tokens
diff --git a/docs/glance.md b/docs/glance.md
index 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.md
index 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.mjs
index 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.md
index 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 a
The 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.js
index 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');
+ });
});