Migrating v0.2.1 → v0.2.2

Purely additive. Existing callsites keep working — no imports to move, no config fields to rename, no CSS variables to rebind. The three sections below are optional adoptions that let you take advantage of what v0.2.2 shipped.

If you're upgrading from an earlier version, chain via v0.2.1 migrating first — the notes below assume you already run v0.2.1.

Optional: adopt dddk.prompts to centralise LLM prompts

If you currently pass webAgent.systemPrompt, InlineAgentConfig.systemPrompt, VoiceConfig.cleanupPrompt, or DwellConfig.systemPrompt to replace the SDK defaults, you can leave those in place — they still win over the registry (as before). But if you want to override PER-LOCALE (English + Japanese + Traditional Chinese versions of the same prompt), the config fields only accept one string; the registry does.

Before (single locale, per-subsystem):

new DotDotDuck({
  webAgent: { systemPrompt: MY_JAPANESE_NARRATOR },
  llm: ...,
});

After (per-locale, single API):

const dddk = new DotDotDuck({ llm: ... });

dddk.prompts.override('webagent-narrator.system', 'ja', () => MY_JAPANESE_NARRATOR);
dddk.prompts.override('webagent-narrator.system', 'zh-TW', () => MY_TRADITIONAL_CHINESE_NARRATOR);
// English keeps the SDK default.

Live locale switch works too — the registry is process-wide and read at message-assembly time, so the next agent turn picks up the current locale's prompt without a re-mount.

Full guide: prompts.md.

Optional: swap new DotDotDuck({...}) for autoInstall(...)

If your existing app already wires every config field explicitly, don't bother — you'll just be moving code around. autoInstall() is aimed at:

• New apps wanting to see the SDK working before choosing what to configure.
• Landing pages / marketing sites where the palette + Dwell + mascot are enough without an LLM.
• <script src> embeds on static sites where full config is overkill.

Before:

const dddk = new DotDotDuck({
  llm: myProvider,
  locale: navigator.language.startsWith('zh') ? 'zh-TW' : 'en',
  // ... 20 more fields explicitly ...
});

After (skip the boilerplate, override only what matters):

const dddk = autoInstall({
  llm: myProvider,
  paletteCommands: myCommands,
});
// Locale, duck sprites, and 20 other fields default to sensible values.

If you want the OLD behaviour (silent no-op when llm is absent, matching raw new DotDotDuck({})), set demoLLM: false:

const dddk = autoInstall({ demoLLM: false });

Full guide: auto-install.md.

Optional: drop your duck sprite files

Before v0.2.2 the SDK expected the host to serve mascot sprite PNGs at whatever paths --dddk-*-url pointed to (plus a hard-coded /duck/swim-cycle.png for the Dwell overlay). v0.2.2 ships seven sprites as build-time-bundled assets inside dist/duck/, referenced by tokens.css defaults — including the new WebAgent cursor.png (a duck riding a paper airplane) that replaces the SVG pointer glyph.

Before:

/* your app.css */
:root {
  --dddk-avatar-url: url('/duck/neutral.png');
  --dddk-swim-url: url('/duck/swim-side.png');
  --dddk-hero-url: url('/duck/hero-greet.png');
  --dddk-chill-url: url('/duck/chill-shades.png');
}

static/duck/
  neutral.png
  swim-side.png
  hero-greet.png
  chill-shades.png

After (SDK ships them, remove your copies):

/* your app.css — nothing here for sprites unless you want to swap them */

Sub-path caveat — if your app is served from a subdirectory like /tools/, keep the :root overrides pointing at root-absolute paths. See the "Sub-path caveat" section in the v0.2.2 release notes for why.

Removed / deprecated

Nothing. Every field, function, and CSS variable that existed in v0.2.1 still works in v0.2.2 unchanged.

New surface summary