Migrating v0.2.2 → v0.2.3

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

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

Optional: adopt the SDK's HERO greeting default

If you currently hand-write the greeting body (title + rows + kbdHint) in your layout code and pass it via bodyHtml, you can delete that code and let the SDK render the default. Keep a title override if your product has its own brand voice.

Before (v0.2.2 host-owned greeting):

// Your layout code — 60+ lines of HTML
const greetingHtml = locale === 'zh-TW'
  ? `<div style="...">嗨！我是 dotdotduck</div>
     <div style="...">👆 點右下角的鴨子 → 打開指令面板</div>
     ...`
  : `...`;

mobile.showHeroGreeting(plainText, { bodyHtml: greetingHtml, autoDismissMs: 20000 });

After (v0.2.3 SDK default + brand-voice title override):

new MobileTrigger({
  heroGreeting: {
    title: {
      en: "Hi! I'm dotdotduck",
      'zh-TW': '嗨！我是 dotdotduck',
    },
    // Everything else — rows, kbdHint, dismiss timing, session-storage
    // gating — falls back to the SDK-shipped defaults.
  },
});
// No manual showHeroGreeting call needed — the SDK auto-fires on first
// visit (session-storage gated) and dismiss on click / auto-timeout.

To disable the auto-fire entirely: heroGreeting: false. Full body override: heroGreeting: { bodyHtml: (locale) => '...' }.

Optional: drop your sprite-URL CSS overrides

If your app.css has entries like this to work around the "sprites don't render on subdirectory hosts" bug:

/* app.css — old workaround */
:root {
  --dddk-swim-cycle-url: url('/duck/swim-cycle.png');
  --dddk-cursor-url:     url('/duck/cursor.png');
  --dddk-brand-mark-url: url('/duck/logo.png');
}

You can delete those declarations — the v0.2.3 runtime resolver handles it. Sprite URLs are computed from the SDK JS's actual location via import.meta.url and set on :root.style inline, so they resolve correctly on any host serving path.

If you want to swap sprites for your brand:

autoInstall({
  sprites: {
    avatar: '/my-brand/mascot.png',
    swim:   '/my-brand/swim.png',
    // brand-mark left as default → keeps the dotdotduck logo on the
    // palette footer's "Powered by" strip.
  },
});

Optional: switch from new MobileTrigger + attachTo to autoInstall(...)

If your v0.2.2 code looks like this:

const dddk = new DotDotDuck({ llm: myProvider });
new MobileTrigger({ fab: { alwaysVisible: true, faces: {...} } }).attachTo(dddk);

You can move the whole thing into autoInstall:

const dddk = autoInstall({
  llm: myProvider,
  mobile: { fab: { faces: {...} } },  // alwaysVisible is now the default
});

Same shape, one fewer imperative call, MobileTrigger's other defaults (heroGreeting on, dwellOnTap off, breakpoints, etc.) all pick up the SDK's v0.2.3 defaults automatically.

Skip this migration if you're happy with the explicit form — both keep working.

Enterprise UI: disable Dwell corner mascots

If your product's brand voice is serious (accounting, ERP, medical, legal), the playful side-view swim duck + sunglasses "chill" duck at the Dwell frame corners might feel out of place. New v0.2.3 config:

new Dwell({
  llm: myLLM,
  showCornerMascots: false,   // frame outline only; no mascots
});

Long-press-to-activate, Escape-to-clear, and the frame outline itself all work identically. Only the two decorative sprites are suppressed.

Removed / deprecated

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

New surface summary