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(walk-sdk): give ?avatar= precedence over the stored choice on deep links

nirholas6be91ed66c06
diff --git a/walk-sdk/src/companion.js b/walk-sdk/src/companion.js
index 1e3cc5c35..a1f4a56c7 100644
--- a/walk-sdk/src/companion.js
+++ b/walk-sdk/src/companion.js
@@ -778,6 +778,26 @@ function ensureStyles() {
document.head.appendChild(style);
}
+/**
+ * Resolve the avatar id for a bootstrap path that never mounts the corner
+ * companion (the `?walk=play` deep link and the playground drop-in resume).
+ *
+ * `setAvatar()`/the picker persist the visitor's choice via `config.keys.avatar`,
+ * but the playground launch paths read that key directly and never looked at
+ * the query string, so `?walk=play&avatar=fox` silently loaded the stored (or
+ * default) avatar instead of `fox`. This gives `?avatar=` precedence and
+ * persists it, the same way picking an avatar in the UI would.
+ *
+ * @param {object} config resolved config (for its storage keys)
+ * @param {URLSearchParams} params the current query string
+ * @returns {string|null} the avatar id to launch with, or null for the default
+ */
+export function deepLinkAvatarId(config, params) {
+ const param = params.get('avatar');
+ if (param) lsSet(config.keys.avatar, param);
+ return param || lsGet(config.keys.avatar) || null;
+}
+
// ── Factory + control object ──────────────────────────────────────────────────
/**
* Create a Walk Companion controller. Side-effect free: nothing mounts until
@@ -943,13 +963,13 @@ export function createWalkCompanion(opts = {}) {
}
},
- async _tryDropIn() {
+ async _tryDropIn(avatarId = null) {
try {
const mod = await import('./playground.js');
if (!mod.consumeDropIn(config)) return false;
control._wirePlaygroundReturn();
mod.launchPlayground({
- avatarId: lsGet(config.keys.avatar) || null,
+ avatarId: avatarId || lsGet(config.keys.avatar) || null,
dropIn: true,
config,
});
@@ -969,21 +989,19 @@ export function createWalkCompanion(opts = {}) {
if (walk === '0') {
control.disable();
} else if (walk === 'play') {
+ const avatarId = deepLinkAvatarId(config, params);
lsSet(config.keys.enabled, '1');
import('./playground.js')
.then((mod) => {
control._wirePlaygroundReturn();
- mod.launchPlayground({
- avatarId: lsGet(config.keys.avatar) || null,
- config,
- });
+ mod.launchPlayground({ avatarId, config });
})
.catch((err) => {
log.warn('playground deep-link failed:', err?.message || err);
control.enable();
});
} else if (walk === '1' || isEnabled()) {
- control._tryDropIn().then((dropped) => {
+ control._tryDropIn(deepLinkAvatarId(config, params)).then((dropped) => {
if (!dropped) control.enable();
});
}
diff --git a/walk-sdk/test/companion.test.mjs b/walk-sdk/test/companion.test.mjs
new file mode 100644
index 000000000..c9c48f591
--- /dev/null
+++ b/walk-sdk/test/companion.test.mjs
@@ -0,0 +1,50 @@
+// @three-ws/walk: companion deep-link resolution.
+// ====================================================
+// The playground launch paths (`?walk=play` and the drop-in resume) read the
+// avatar id straight out of storage and never looked at `?avatar=`, so a deep
+// link like `?walk=play&avatar=fox` silently loaded the stored (or default)
+// avatar instead of `fox`. Pure logic; `node --test`.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolveConfig } from '../src/config.js';
+
+// This Node test run has no DOM, so `lsGet`/`lsSet` (src/internal/storage.js)
+// hit a bare `localStorage` global that doesn't exist here. Shim the Web
+// Storage API with a plain Map so deepLinkAvatarId's persistence is actually
+// observable, the same way it would be in a browser.
+const store = new Map();
+globalThis.localStorage = {
+ getItem: (k) => (store.has(k) ? store.get(k) : null),
+ setItem: (k, v) => store.set(k, String(v)),
+ removeItem: (k) => store.delete(k),
+};
+
+const { deepLinkAvatarId } = await import('../src/companion.js');
+
+test('deepLinkAvatarId prefers the ?avatar= query param over the stored choice', () => {
+ const config = resolveConfig({ storagePrefix: `test-${Date.now()}-a` });
+ localStorage.setItem(config.keys.avatar, 'wolf');
+ const params = new URLSearchParams('walk=play&avatar=fox');
+ assert.equal(deepLinkAvatarId(config, params), 'fox');
+});
+
+test('deepLinkAvatarId persists the query param so it survives into the playground', () => {
+ const config = resolveConfig({ storagePrefix: `test-${Date.now()}-b` });
+ const params = new URLSearchParams('walk=play&avatar=fox');
+ deepLinkAvatarId(config, params);
+ assert.equal(localStorage.getItem(config.keys.avatar), 'fox');
+});
+
+test('deepLinkAvatarId falls back to the stored choice when there is no ?avatar=', () => {
+ const config = resolveConfig({ storagePrefix: `test-${Date.now()}-c` });
+ localStorage.setItem(config.keys.avatar, 'wolf');
+ const params = new URLSearchParams('walk=play');
+ assert.equal(deepLinkAvatarId(config, params), 'wolf');
+});
+
+test('deepLinkAvatarId returns null when there is neither a param nor a stored choice', () => {
+ const config = resolveConfig({ storagePrefix: `test-${Date.now()}-d` });
+ const params = new URLSearchParams('walk=play');
+ assert.equal(deepLinkAvatarId(config, params), null);
+});