@firetable/project-xiaochun 0.1.14 → 0.1.16

package/dist/react.cjs

@@ -1,4 +1,4 @@
-/*! @firetable/project-xiaochun v0.1.14 | MIT | https://github.com/FireTable/project-xiaochun */
+/*! @firetable/project-xiaochun v0.1.16 | MIT | https://github.com/FireTable/project-xiaochun */
 "use strict";
 "use client";
 var __defProp = Object.defineProperty;
@@ -32,6 +32,70 @@ var import_react = require("react");
 var XC_PROTOCOL_VERSION = 1;
 var XC_DEFAULT_ORIGIN = "https://xiaochun.firetable.tech";
 var XC_DEFAULT_SRC = `${XC_DEFAULT_ORIGIN}/embed`;
+var XC_WINDOW_CORNER_RADIUS = 20;
+var XC_UI_PARTS = ["chat", "bubble", "outfit", "scene", "lang", "github"];
+var XC_UI_PART_SET = new Set(XC_UI_PARTS);
+var XC_UI_LEGACY_PARTS = ["chat", "bubble"];
+function parseXcUiList(items) {
+  const seen = /* @__PURE__ */ new Set();
+  const unknown = [];
+  for (const it of items) {
+    const name = typeof it === "string" ? it.trim().toLowerCase() : "";
+    if (XC_UI_PART_SET.has(name)) seen.add(name);
+    else unknown.push(typeof it === "string" ? it.slice(0, 40) : String(typeof it));
+  }
+  return { parts: XC_UI_PARTS.filter((p) => seen.has(p)), unknown, legacy: false };
+}
+function normalizeXcUiOption(v) {
+  if (v === true) return { parts: [...XC_UI_LEGACY_PARTS], unknown: [], legacy: true };
+  if (Array.isArray(v)) return parseXcUiList(v);
+  return { parts: [], unknown: [], legacy: false };
+}
+function parseXcUiAutoHide(raw) {
+  if (raw === true || raw === false || raw === "transparent") return raw;
+  if (typeof raw !== "string") return void 0;
+  const v = raw.trim().toLowerCase();
+  if (v === "1" || v === "true") return true;
+  if (v === "0" || v === "false") return false;
+  if (v === "transparent") return "transparent";
+  return void 0;
+}
+var XC_CAMERA_RANGES = {
+  fov: [15, 60],
+  distance: [1, 15],
+  height: [-1, 1]
+};
+var XC_CAMERA_NUM_KEYS = ["fov", "distance", "height"];
+var XC_CAMERA_KEYS = ["fov", "distance", "height", "intro"];
+function normalizeXcCamera(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return { ok: false, error: "camera must be an object" };
+  const src = raw;
+  for (const k of Object.keys(src)) {
+    if (!XC_CAMERA_KEYS.includes(k)) return { ok: false, error: `unknown camera key: ${k} (expected ${XC_CAMERA_KEYS.join(" | ")})` };
+  }
+  const out = {};
+  const clamped = [];
+  for (const k of XC_CAMERA_NUM_KEYS) {
+    const v = src[k];
+    if (v === void 0) continue;
+    if (v === null) {
+      out[k] = null;
+      continue;
+    }
+    if (typeof v !== "number" || !Number.isFinite(v)) return { ok: false, error: `camera.${k} must be a finite number or null` };
+    const [lo, hi] = XC_CAMERA_RANGES[k];
+    const c = Math.min(hi, Math.max(lo, v));
+    if (c !== v) clamped.push(k);
+    out[k] = c;
+  }
+  if (src.intro !== void 0) {
+    if (src.intro !== null && typeof src.intro !== "boolean") return { ok: false, error: "camera.intro must be a boolean or null" };
+    out.intro = src.intro;
+  }
+  return { ok: true, camera: out, clamped };
+}
+var XC_ID_RE = /^[a-z][a-z0-9_]{0,63}$/;
+var isXcId = (v) => typeof v === "string" && XC_ID_RE.test(v);
 function xcMessage(type, payload, id) {
   const m = { type, v: XC_PROTOCOL_VERSION, payload };
   if (id !== void 0) m.id = id;
@@ -53,11 +117,113 @@ function normalizeOrigin(input) {
   }
 }
 
+// src/gesture-box.ts
+var DEFAULT_RESIZE_LIMITS = Object.freeze({
+  minWidth: 120,
+  minHeight: 180,
+  maxWidth: Infinity,
+  maxHeight: Infinity
+});
+var finitePositive = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
+function normalizeResizable(v) {
+  if (!v) return null;
+  const o = v === true ? {} : v;
+  const minWidth = finitePositive(o.minWidth) ? o.minWidth : DEFAULT_RESIZE_LIMITS.minWidth;
+  const minHeight = finitePositive(o.minHeight) ? o.minHeight : DEFAULT_RESIZE_LIMITS.minHeight;
+  const maxWidth = finitePositive(o.maxWidth) ? Math.max(o.maxWidth, minWidth) : Infinity;
+  const maxHeight = finitePositive(o.maxHeight) ? Math.max(o.maxHeight, minHeight) : Infinity;
+  return { minWidth, minHeight, maxWidth, maxHeight };
+}
+var clamp = (v, lo, hi) => Math.min(Math.max(v, lo), Math.max(lo, hi));
+function moveBox(start, totalDx, totalDy, vp) {
+  return {
+    left: clamp(start.left + totalDx, 0, vp.width - start.width),
+    top: clamp(start.top + totalDy, 0, vp.height - start.height),
+    width: start.width,
+    height: start.height
+  };
+}
+function resizeBox(start, corner, totalDx, totalDy, limits, vp) {
+  const west = corner === "NW" || corner === "SW";
+  const north = corner === "NW" || corner === "NE";
+  const right = start.left + start.width, bottom = start.top + start.height;
+  const wantW = west ? start.width - totalDx : start.width + totalDx;
+  const wantH = north ? start.height - totalDy : start.height + totalDy;
+  const roomW = west ? right : vp.width - start.left;
+  const roomH = north ? bottom : vp.height - start.top;
+  const width = clamp(wantW, limits.minWidth, Math.min(limits.maxWidth, roomW));
+  const height = clamp(wantH, limits.minHeight, Math.min(limits.maxHeight, roomH));
+  return { left: west ? right - width : start.left, top: north ? bottom - height : start.top, width, height };
+}
+function fitBox(b, vp) {
+  const width = Math.min(b.width, Math.max(1, vp.width)), height = Math.min(b.height, Math.max(1, vp.height));
+  return { left: clamp(b.left, 0, vp.width - width), top: clamp(b.top, 0, vp.height - height), width, height };
+}
+var CORNERS = /* @__PURE__ */ new Set(["NW", "NE", "SW", "SE"]);
+var PHASES = /* @__PURE__ */ new Set(["start", "move", "end"]);
+var REASONS = /* @__PURE__ */ new Set(["up", "cancel", "blur"]);
+var MAX_GESTURE_DELTA = 2e4;
+var delta = (v) => typeof v === "number" && Number.isFinite(v) && Math.abs(v) <= MAX_GESTURE_DELTA;
+var counter = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+function parseGesturePayload(kind, raw) {
+  if (raw === null || typeof raw !== "object") return null;
+  const p = raw;
+  if (!counter(p.gesture) || !counter(p.seq) || typeof p.phase !== "string" || !PHASES.has(p.phase)) return null;
+  if (!delta(p.dx) || !delta(p.dy) || !delta(p.totalDx) || !delta(p.totalDy)) return null;
+  if (p.reason !== void 0 && (typeof p.reason !== "string" || !REASONS.has(p.reason))) return null;
+  const out = { gesture: p.gesture, seq: p.seq, phase: p.phase, totalDx: p.totalDx, totalDy: p.totalDy };
+  if (kind === "resize") {
+    if (typeof p.corner !== "string" || !CORNERS.has(p.corner)) return null;
+    out.corner = p.corner;
+  }
+  return out;
+}
+var GestureGate = class {
+  constructor() {
+    this.lastGesture = 0;
+    this.lastSeq = -1;
+    this.open = false;
+  }
+  get active() {
+    return this.open;
+  }
+  accept(p) {
+    if (p.phase === "start") {
+      if (p.gesture <= this.lastGesture || p.seq !== 0) return false;
+      this.lastGesture = p.gesture;
+      this.lastSeq = 0;
+      this.open = true;
+      return true;
+    }
+    if (!this.open || p.gesture !== this.lastGesture || p.seq <= this.lastSeq) return false;
+    this.lastSeq = p.seq;
+    if (p.phase === "end") this.open = false;
+    return true;
+  }
+  /** 宿主主动结束 (关闭手势 / 销毁): 之后同一手势的迟到消息被拒绝。 */
+  close() {
+    this.open = false;
+  }
+};
+
 // src/client.ts
 var FALLBACK_PLACEHOLDER = "data:image/svg+xml;utf8," + encodeURIComponent(
   '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 180"><defs><linearGradient id="g" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#f6b8ae"/><stop offset="1" stop-color="#ea8377"/></linearGradient></defs><ellipse cx="60" cy="170" rx="34" ry="6" fill="#000" opacity=".12"/><circle cx="60" cy="48" r="26" fill="url(#g)" opacity=".75"/><path d="M26 160c2-40 18-62 34-62s32 22 34 62z" fill="url(#g)" opacity=".6"/></svg>'
 );
+var noSelect = (st) => {
+  st.setProperty("user-select", "none");
+  st.setProperty("-webkit-user-select", "none");
+  st.setProperty("-webkit-touch-callout", "none");
+  st.setProperty("-webkit-tap-highlight-color", "transparent");
+};
 var css = (v, d) => v === void 0 ? d : typeof v === "number" ? `${v}px` : v;
+var XC_DEFAULT_WIDTH = 600;
+var XC_DEFAULT_HEIGHT = 1080;
+var defaultWidthCss = (floating = false) => floating ? `min(${XC_DEFAULT_WIDTH}px, calc(100vw - 2 * var(--xc-offset-x, 16px)))` : `min(${XC_DEFAULT_WIDTH}px, 100vw)`;
+var defaultHeightCss = (floating = false) => {
+  const unit = typeof CSS !== "undefined" && typeof CSS.supports === "function" && CSS.supports("height", "1svh") ? "svh" : "vh";
+  return floating ? `min(${XC_DEFAULT_HEIGHT}px, calc(100${unit} - 2 * var(--xc-offset-y, 16px)))` : `min(${XC_DEFAULT_HEIGHT}px, 100${unit})`;
+};
 function createXiaochun(options) {
   if (typeof window === "undefined" || typeof document === "undefined") {
     throw new Error("[project-xiaochun] createXiaochun must run in a browser");
@@ -79,8 +245,56 @@ function createXiaochun(options) {
     if (!n) throw new Error(`[project-xiaochun] invalid allowedOrigins entry: ${o} (wildcards are not allowed)`);
     trusted.add(n);
   }
-  const transparent = options.transparent ?? false;
-  const passthrough = options.passthrough ?? transparent;
+  const prefsKey = options.persist === "host" ? "xiaochun:prefs" : typeof options.persist === "string" && options.persist ? options.persist : null;
+  const readPrefs = () => {
+    if (!prefsKey) return {};
+    try {
+      const raw = JSON.parse(window.localStorage.getItem(prefsKey) ?? "null");
+      const out = {};
+      if (raw && typeof raw === "object") {
+        if (isXcId(raw.outfit)) out.outfit = raw.outfit;
+        if (isXcId(raw.scene)) out.scene = raw.scene;
+      }
+      return out;
+    } catch {
+      return {};
+    }
+  };
+  const writePrefs = (patch) => {
+    if (!prefsKey) return;
+    try {
+      const next = { ...readPrefs() };
+      for (const [k, v] of Object.entries(patch)) {
+        if (v) next[k] = v;
+        else delete next[k];
+      }
+      window.localStorage.setItem(prefsKey, JSON.stringify(next));
+    } catch {
+    }
+  };
+  const prefs = readPrefs();
+  if (options.model !== void 0 && options.outfit === void 0) {
+    console.warn('[project-xiaochun] option "model" is deprecated, use "outfit" (built-in outfit id).');
+  }
+  const uiParse = normalizeXcUiOption(options.ui);
+  const uiParts = uiParse.parts;
+  const uiAutoHide = parseXcUiAutoHide(options.uiAutoHide);
+  if (options.uiAutoHide !== void 0 && uiAutoHide === void 0) console.warn(`[project-xiaochun] ignoring invalid uiAutoHide: ${String(options.uiAutoHide)} (use true | false | 'transparent')`);
+  let camera = {};
+  if (options.camera !== void 0) {
+    const r = normalizeXcCamera(options.camera);
+    if (r.ok) {
+      camera = r.camera;
+      if (r.clamped.length) console.warn(`[project-xiaochun] camera.${r.clamped.join(", camera.")} out of range, clamped (fov ${XC_CAMERA_RANGES.fov.join("\u2013")}, distance ${XC_CAMERA_RANGES.distance.join("\u2013")}, height ${XC_CAMERA_RANGES.height.join("\u2013")})`);
+    } else console.warn(`[project-xiaochun] ignoring invalid camera option: ${r.error}`);
+  }
+  if (uiParse.legacy) console.warn(`[project-xiaochun] option "ui: true" is deprecated, use an array of parts, e.g. ui: ['chat', 'bubble', 'outfit', 'scene'].`);
+  if (uiParse.unknown.length) console.warn(`[project-xiaochun] ignoring unknown ui part(s): ${uiParse.unknown.join(", ")} (known: ${XC_UI_PARTS.join(", ")})`);
+  const outfitOpt = options.outfit ?? (isXcId(options.model) ? options.model : void 0);
+  const initialOutfit = outfitOpt ?? prefs.outfit;
+  const initialScene = options.scene ?? prefs.scene ?? (options.transparent ? "transparent" : void 0);
+  let transparent = initialScene === "transparent" || initialScene !== "light" && initialScene !== "dark" && (options.transparent ?? false);
+  let passthrough = options.passthrough ?? transparent;
   const lazy = options.lazy ?? true;
   const position = options.position ?? "inline";
   const handshakeTimeout = options.handshakeTimeout ?? 2e4;
@@ -88,14 +302,26 @@ function createXiaochun(options) {
   wrapper.setAttribute("data-xiaochun", "");
   const ws = wrapper.style;
   ws.position = position === "inline" ? "relative" : "fixed";
-  ws.width = css(options.width, "320px");
-  ws.height = css(options.height, "480px");
+  ws.width = css(options.width, defaultWidthCss(position !== "inline"));
+  ws.height = css(options.height, defaultHeightCss(position !== "inline"));
   ws.maxWidth = "100%";
   ws.overflow = "visible";
   ws.contain = "layout style";
-  ws.borderRadius = "var(--xc-radius, 0)";
+  noSelect(ws);
   ws.boxShadow = "var(--xc-shadow, none)";
-  if (!transparent) ws.background = "var(--xc-bg, transparent)";
+  const applyWrapperBg = () => {
+    ws.background = transparent ? "" : "var(--xc-bg, transparent)";
+  };
+  applyWrapperBg();
+  let radiusOpt = options.borderRadius;
+  const radiusValue = () => radiusOpt !== void 0 ? css(radiusOpt, "0px") : transparent ? "0px" : `${XC_WINDOW_CORNER_RADIUS}px`;
+  const applyRadius = () => {
+    const v = `var(--xc-radius, ${radiusValue()})`;
+    ws.borderRadius = v;
+    if (placeholderEl) placeholderEl.style.borderRadius = v;
+    if (iframe) iframe.style.borderRadius = v;
+  };
+  ws.borderRadius = `var(--xc-radius, ${radiusValue()})`;
   if (position === "bottom-right") {
     ws.right = "var(--xc-offset-x, 16px)";
     ws.bottom = "var(--xc-offset-y, 16px)";
@@ -116,13 +342,13 @@ function createXiaochun(options) {
       img.src = options.placeholder || FALLBACK_PLACEHOLDER;
       img.alt = "Project XiaoChun";
       img.decoding = "async";
-      img.width = 320;
-      img.height = 480;
+      img.width = XC_DEFAULT_WIDTH;
+      img.height = XC_DEFAULT_HEIGHT;
       placeholderEl = img;
     }
     const ps = placeholderEl.style;
     placeholderEl.setAttribute("part", "placeholder");
-    ps.borderRadius = "var(--xc-radius, 0)";
+    ps.borderRadius = `var(--xc-radius, ${radiusValue()})`;
     ps.position = "absolute";
     ps.inset = "0";
     ps.width = "100%";
@@ -131,6 +357,7 @@ function createXiaochun(options) {
     ps.transition = "opacity .25s ease";
     ps.pointerEvents = "auto";
     ps.cursor = lazy === false ? "default" : "pointer";
+    noSelect(ps);
     placeholderEl.addEventListener("click", () => activate());
     wrapper.appendChild(placeholderEl);
   }
@@ -159,25 +386,45 @@ function createXiaochun(options) {
   let autoPaused = false;
   let loaded = false;
   let lastHit = false;
+  let caps = null;
+  let currentOutfit = null;
+  let currentScene = null;
   const queue = [];
   const pending = /* @__PURE__ */ new Map();
   let idSeq = 0;
   let handshakeTimer = null;
   let io = null;
   let idleHandle = null;
-  const postToFrame = (type, payload, id, transfer) => {
+  let resolveHandshake;
+  const handshaked = new Promise((res) => {
+    resolveHandshake = res;
+  });
+  const failLocal = (type, id, code, message) => {
+    emit("error", { code, message, command: type });
+    const p = id ? pending.get(id) : void 0;
+    if (p && id) {
+      pending.delete(id);
+      p.reject(new Error(`[${code}] ${message}`));
+    }
+  };
+  const unsupportedByFrame = (type, id) => failLocal(type, id, "unsupported", `${type} is not supported by this /embed deployment (older version; its xc.ready has no capabilities for it)`);
+  const postToFrame = (type, payload, id, transfer, requires) => {
     if (!port) {
-      queue.push({ type, payload, id, transfer });
+      queue.push({ type, payload, id, transfer, requires });
+      return;
+    }
+    if (requires && !caps?.[requires]) {
+      unsupportedByFrame(type, id);
       return;
     }
     port.postMessage(xcMessage(type, payload, id), transfer ?? []);
   };
-  const send = (type, payload, wait = false, transfer, fixedId) => {
+  const send = (type, payload, wait = false, transfer, fixedId, requires) => {
     if (destroyed) return Promise.reject(new Error("[project-xiaochun] instance destroyed"));
     if (!iframe) activate();
     const id = fixedId ?? `c${++idSeq}`;
     const p = wait ? new Promise((resolve, reject) => pending.set(id, { resolve, reject, sawEnd: false })) : Promise.resolve();
-    postToFrame(type, payload, id, transfer);
+    postToFrame(type, payload, id, transfer, requires);
     return p;
   };
   const toBuffer = (d) => d instanceof ArrayBuffer ? d : d.buffer.slice(d.byteOffset, d.byteOffset + d.byteLength);
@@ -227,7 +474,7 @@ function createXiaochun(options) {
     let ended = false;
     let fmt = rest.format === "pcm16" || rest.format === "float32" ? rest.format : null;
     let done = Promise.resolve();
-    const handle2 = {
+    const handle = {
       write(data) {
         if (ended) throw new Error("[project-xiaochun] audio stream already ended");
         if (destroyed) throw new Error("[project-xiaochun] instance destroyed");
@@ -261,17 +508,23 @@ function createXiaochun(options) {
         return done;
       }
     };
-    return handle2;
+    return handle;
   };
   function buildUrl() {
     const u = new URL(srcUrl.href);
     u.searchParams.set("host", window.location.origin);
     if (transparent) u.searchParams.set("transparent", "1");
-    if (options.ui) u.searchParams.set("ui", "1");
+    if (uiParts.length) u.searchParams.set("ui", uiParts.join(","));
     if (options.lang) u.searchParams.set("lang", options.lang);
+    if (uiAutoHide !== void 0) u.searchParams.set("uiAutoHide", String(uiAutoHide));
+    if (typeof camera.fov === "number") u.searchParams.set("cameraFov", String(camera.fov));
+    if (typeof camera.distance === "number") u.searchParams.set("cameraDistance", String(camera.distance));
+    if (typeof camera.height === "number") u.searchParams.set("cameraHeight", String(camera.height));
+    if (typeof camera.intro === "boolean") u.searchParams.set("cameraIntro", camera.intro ? "1" : "0");
     if (options.heavy) u.searchParams.set("heavy", options.heavy);
-    if (options.controls) u.searchParams.set("controls", "1");
-    if (options.model) u.searchParams.set("outfit", options.model);
+    if (options.controls === false) u.searchParams.set("controls", "0");
+    if (initialScene && isXcId(initialScene)) u.searchParams.set("scene", initialScene);
+    if (initialOutfit) u.searchParams.set("outfit", initialOutfit);
     return u.href;
   }
   function activate() {
@@ -297,8 +550,9 @@ function createXiaochun(options) {
     s.border = "0";
     s.background = "transparent";
     s.colorScheme = "normal";
-    s.borderRadius = "var(--xc-radius, 0)";
+    s.borderRadius = `var(--xc-radius, ${radiusValue()})`;
     f.setAttribute("part", "iframe");
+    noSelect(s);
     s.opacity = "0";
     s.transition = "opacity .25s ease";
     s.pointerEvents = passthrough ? "none" : "auto";
@@ -310,7 +564,7 @@ function createXiaochun(options) {
       if (!port) emit("error", { code: "timeout", message: `no xc.ready from ${frameOrigin} within ${handshakeTimeout}ms` });
     }, handshakeTimeout);
     setupAutoPause();
-    setupPassthrough();
+    if (passthrough) enablePassthrough();
   }
   const onWindowMessage = (ev) => {
     if (destroyed || !iframe || ev.source !== iframe.contentWindow) return;
@@ -323,20 +577,39 @@ function createXiaochun(options) {
     const ch = new MessageChannel();
     port = ch.port1;
     port.onmessage = onPortMessage;
+    caps = data.payload?.capabilities ?? null;
+    const gWant = wantGestures();
+    sentGestures = gWant;
+    const initConfig = {
+      ...options.allowCustomModel ? { allowCustomModel: true } : {},
+      ...gWant.move || gWant.resize ? { gestures: gWant } : {}
+    };
     iframe.contentWindow.postMessage(
-      xcMessage("xc.init", { hostOrigin: window.location.origin }),
+      xcMessage("xc.init", { hostOrigin: window.location.origin, ...Object.keys(initConfig).length ? { config: initConfig } : {} }),
       ev.origin,
       [ch.port2]
     );
+    warnGestureUnsupported();
     if (handshakeTimer) {
       clearTimeout(handshakeTimer);
       handshakeTimer = null;
     }
     emit("handshake", data.payload);
-    for (const m of queue.splice(0)) port.postMessage(xcMessage(m.type, m.payload, m.id), m.transfer ?? []);
+    resolveHandshake();
+    for (const m of queue.splice(0)) {
+      if (m.requires && !caps?.[m.requires]) unsupportedByFrame(m.type, m.id);
+      else port.postMessage(xcMessage(m.type, m.payload, m.id), m.transfer ?? []);
+    }
     syncPause();
   };
   window.addEventListener("message", onWindowMessage);
+  function ack(id, value) {
+    const p = id ? pending.get(id) : void 0;
+    if (p && id) {
+      pending.delete(id);
+      p.resolve(value);
+    }
+  }
   function onPortMessage(ev) {
     const data = ev.data;
     if (!isXcEnvelope(data)) return;
@@ -347,6 +620,11 @@ function createXiaochun(options) {
       case "xc.loaded":
         if (!loaded) {
           loaded = true;
+          if (options.prefetch && options.heavy === "eager" && caps?.prefetch) {
+            const ids = Array.isArray(options.prefetch) ? options.prefetch : void 0;
+            void api.prefetch(ids).catch(() => {
+            });
+          }
           if (iframe) iframe.style.opacity = "1";
           if (placeholderEl) {
             const el = placeholderEl;
@@ -359,6 +637,33 @@ function createXiaochun(options) {
         }
         emit("ready", data.payload);
         break;
+      case "xc.outfit-changed": {
+        const pl = data.payload;
+        if (!pl.noop) {
+          currentOutfit = pl.id;
+          emit("outfit-changed", pl);
+          if (!pl.initial && pl.id) writePrefs({ outfit: pl.id });
+        }
+        ack(data.id);
+        break;
+      }
+      case "xc.scene-changed": {
+        const pl = data.payload;
+        currentScene = pl.id;
+        if (pl.transparent !== transparent) applyTransparency(pl.transparent);
+        if (!pl.noop) {
+          emit("scene-changed", pl);
+          if (!pl.initial) writePrefs({ scene: pl.id });
+        }
+        ack(data.id);
+        break;
+      }
+      case "xc.lang-changed":
+        emit("lang-changed", data.payload);
+        break;
+      case "xc.prefetched":
+        ack(data.id, data.payload);
+        break;
       case "xc.state":
         emit("state", data.payload);
         break;
@@ -383,9 +688,16 @@ function createXiaochun(options) {
         }
         break;
       }
+      case "xc.gesture-move":
+        onGesture("move", data.payload);
+        break;
+      case "xc.gesture-resize":
+        onGesture("resize", data.payload);
+        break;
       case "xc.error": {
         const { code, message, command } = data.payload;
         emit("error", { code, message, command });
+        if (code === "unknown_id" && (command === "outfit" || command === "scene")) writePrefs({ [command]: null });
         const p = data.id ? pending.get(data.id) : void 0;
         if (p && data.id) {
           pending.delete(data.id);
@@ -442,16 +754,46 @@ function createXiaochun(options) {
       port.postMessage(xcMessage("xc.pointer", { x, y }));
     });
   };
-  function setupPassthrough() {
-    if (!passthrough) return;
+  let passthroughActive = false;
+  function enablePassthrough() {
+    if (passthroughActive || !iframe) return;
+    passthroughActive = true;
     window.addEventListener("pointermove", onHostPointer, { passive: true });
+    window.addEventListener("pointerdown", onHostPointer, { passive: true });
     window.addEventListener("scroll", invalidateRect, { passive: true, capture: true });
     window.addEventListener("resize", invalidateRect, { passive: true });
-    if (typeof ResizeObserver !== "undefined" && iframe) {
+    if (typeof ResizeObserver !== "undefined") {
       rectRo = new ResizeObserver(invalidateRect);
       rectRo.observe(iframe);
     }
   }
+  function disablePassthrough() {
+    if (!passthroughActive) return;
+    passthroughActive = false;
+    window.removeEventListener("pointermove", onHostPointer);
+    window.removeEventListener("pointerdown", onHostPointer);
+    window.removeEventListener("scroll", invalidateRect, true);
+    window.removeEventListener("resize", invalidateRect);
+    rectRo?.disconnect();
+    rectRo = null;
+    if (pointerRaf) {
+      cancelAnimationFrame(pointerRaf);
+      pointerRaf = 0;
+    }
+    lastPtr = null;
+  }
+  function applyTransparency(next) {
+    transparent = next;
+    applyWrapperBg();
+    applyRadius();
+    passthrough = next ? options.passthrough ?? true : false;
+    lastHit = false;
+    lastPosted = null;
+    rectCache = null;
+    if (passthrough) enablePassthrough();
+    else disablePassthrough();
+    if (iframe) iframe.style.pointerEvents = passthrough ? "none" : "auto";
+  }
   let pauseIo = null;
   function setupAutoPause() {
     if (options.autoPause === false || typeof IntersectionObserver === "undefined") return;
@@ -503,50 +845,177 @@ function createXiaochun(options) {
     }, { rootMargin: `${options.lazyMargin ?? 200}px` });
     io.observe(wrapper);
   }
-  let handle = null;
-  if (options.draggable && position !== "inline") {
-    handle = document.createElement("div");
-    handle.setAttribute("aria-label", "drag");
-    Object.assign(handle.style, {
-      position: "absolute",
-      left: "0",
-      top: "0",
-      width: "28px",
-      height: "28px",
-      cursor: "grab",
-      pointerEvents: "auto",
-      borderRadius: "8px",
-      background: "rgba(0,0,0,.25)",
-      color: "#fff",
-      font: "14px/28px system-ui",
-      textAlign: "center",
-      userSelect: "none",
-      touchAction: "none",
-      zIndex: "2",
-      opacity: "0.5"
-    });
-    handle.textContent = "\u283F";
-    let drag = null;
-    handle.addEventListener("pointerdown", (e) => {
-      const r = wrapper.getBoundingClientRect();
-      drag = { dx: e.clientX - r.left, dy: e.clientY - r.top };
-      handle.setPointerCapture(e.pointerId);
-    });
-    handle.addEventListener("pointermove", (e) => {
-      if (!drag) return;
-      ws.left = `${Math.min(Math.max(0, e.clientX - drag.dx), window.innerWidth - 40)}px`;
-      ws.top = `${Math.min(Math.max(0, e.clientY - drag.dy), window.innerHeight - 40)}px`;
+  let draggableOn = options.draggable === true;
+  let resizeLimits = normalizeResizable(options.resizable);
+  const gates = { move: new GestureGate(), resize: new GestureGate() };
+  let activeGesture = null;
+  let inlineShift = { x: 0, y: 0 };
+  let userMoved = false;
+  let sentGestures = null;
+  let warnedGesture = false;
+  const viewport = () => ({
+    width: document.documentElement.clientWidth || window.innerWidth,
+    height: document.documentElement.clientHeight || window.innerHeight
+  });
+  const readBox = () => {
+    const r = wrapper.getBoundingClientRect();
+    return { left: r.left, top: r.top, width: r.width, height: r.height };
+  };
+  const wantGestures = () => ({ move: draggableOn && caps?.gestures?.move === true, resize: resizeLimits !== null && caps?.gestures?.resize === true });
+  function applyBox(b, inlineBase, withSize) {
+    if (withSize) {
+      ws.width = `${b.width}px`;
+      ws.height = `${b.height}px`;
+      ws.maxWidth = "none";
+    }
+    if (position === "inline") {
+      const base = inlineBase ?? { left: b.left - inlineShift.x, top: b.top - inlineShift.y };
+      inlineShift = { x: b.left - base.left, y: b.top - base.top };
+      ws.setProperty("translate", `${inlineShift.x}px ${inlineShift.y}px`);
+    } else {
+      ws.left = `${b.left}px`;
+      ws.top = `${b.top}px`;
       ws.right = "auto";
       ws.bottom = "auto";
-      invalidateRect();
-    });
-    const end = () => {
-      drag = null;
-    };
-    handle.addEventListener("pointerup", end);
-    handle.addEventListener("pointercancel", end);
-    wrapper.appendChild(handle);
+    }
+    userMoved = true;
+    invalidateRect();
+  }
+  let selectionLock = null;
+  function lockSelection(on) {
+    const de = document.documentElement;
+    if (on && !selectionLock) {
+      selectionLock = { us: de.style.getPropertyValue("user-select"), wus: de.style.getPropertyValue("-webkit-user-select") };
+      de.style.setProperty("user-select", "none");
+      de.style.setProperty("-webkit-user-select", "none");
+      try {
+        window.getSelection()?.removeAllRanges();
+      } catch {
+      }
+    } else if (!on && selectionLock) {
+      de.style.setProperty("user-select", selectionLock.us);
+      de.style.setProperty("-webkit-user-select", selectionLock.wus);
+      selectionLock = null;
+    }
+  }
+  function endActiveGesture(kind) {
+    if (!activeGesture || kind && activeGesture.kind !== kind) return;
+    gates[activeGesture.kind].close();
+    const b = readBox();
+    emit(activeGesture.kind, { phase: "end", ...b });
+    activeGesture = null;
+    lockSelection(false);
+    saveBox();
+  }
+  function onGesture(kind, raw) {
+    if (destroyed || !caps?.gestures) return;
+    if (kind === "move" ? !draggableOn : resizeLimits === null) return;
+    const p = parseGesturePayload(kind, raw);
+    if (!p) return;
+    if (p.phase === "start" ? activeGesture !== null : activeGesture?.kind !== kind) return;
+    if (!gates[kind].accept(p)) return;
+    if (p.phase === "start") {
+      const start = readBox();
+      activeGesture = {
+        kind,
+        start,
+        corner: p.corner,
+        inlineBase: position === "inline" ? { left: start.left - inlineShift.x, top: start.top - inlineShift.y } : null
+      };
+      lockSelection(true);
+      emit(kind, { phase: "start", ...start });
+      return;
+    }
+    const a = activeGesture;
+    const vp = viewport();
+    const next = kind === "move" ? moveBox(a.start, p.totalDx, p.totalDy, vp) : resizeBox(a.start, a.corner, p.totalDx, p.totalDy, resizeLimits, vp);
+    applyBox(next, a.inlineBase, kind === "resize");
+    emit(kind, { phase: p.phase, ...next });
+    if (p.phase === "end") {
+      activeGesture = null;
+      lockSelection(false);
+      saveBox();
+    }
+  }
+  function syncGestures() {
+    if (destroyed) return;
+    const want = wantGestures();
+    if (!want.move) endActiveGesture("move");
+    if (!want.resize) endActiveGesture("resize");
+    if (!port || !caps) return;
+    warnGestureUnsupported();
+    if (sentGestures && sentGestures.move === want.move && sentGestures.resize === want.resize) return;
+    sentGestures = want;
+    if (caps.gestures) port.postMessage(xcMessage("xc.setConfig", { gestures: want }));
+  }
+  function warnGestureUnsupported() {
+    if (warnedGesture || !caps || caps.gestures) return;
+    const needMove = draggableOn;
+    if (!needMove && resizeLimits === null) return;
+    warnedGesture = true;
+    const what = [needMove ? "draggable" : "", resizeLimits !== null ? "resizable" : ""].filter(Boolean).join(" / ");
+    emit("error", { code: "unsupported", message: `${what} needs gesture support (capabilities.gestures), which this /embed deployment does not advertise (older version)`, command: "gestures" });
+  }
+  const onWindowResize = () => {
+    if (!userMoved || activeGesture || destroyed) return;
+    const cur = readBox();
+    const vp = viewport();
+    const fit = position === "inline" ? { ...fitBox({ ...cur, top: 0 }, { width: vp.width, height: Number.MAX_SAFE_INTEGER }), top: Math.max(cur.top, -window.scrollY) } : fitBox(cur, vp);
+    if (fit.left === cur.left && fit.top === cur.top && fit.width === cur.width && fit.height === cur.height) return;
+    applyBox(fit, position === "inline" ? { left: cur.left - inlineShift.x, top: cur.top - inlineShift.y } : null, fit.width !== cur.width || fit.height !== cur.height);
+  };
+  window.addEventListener("resize", onWindowResize, { passive: true });
+  const boxKey = options.persistBox === true ? "xiaochun:box" : typeof options.persistBox === "string" && options.persistBox ? `xiaochun:box:${options.persistBox}` : null;
+  const saveBox = () => {
+    if (!boxKey) return;
+    try {
+      const b = readBox();
+      const at = position === "inline" ? inlineShift : { x: b.left, y: b.top };
+      window.localStorage.setItem(boxKey, JSON.stringify({ v: 1, mode: position, x: Math.round(at.x), y: Math.round(at.y), width: Math.round(b.width), height: Math.round(b.height) }));
+    } catch {
+    }
+  };
+  const loadBox = () => {
+    if (!boxKey) return null;
+    try {
+      const raw = window.localStorage.getItem(boxKey);
+      if (raw === null) return null;
+      let o = null;
+      try {
+        o = JSON.parse(raw);
+      } catch {
+      }
+      const ok = (v, lo, hi) => typeof v === "number" && Number.isFinite(v) && v >= lo && v <= hi;
+      if (o && o.v === 1 && o.mode === position && ok(o.x, -1e5, 1e5) && ok(o.y, -1e5, 1e5) && ok(o.width, 1, 1e5) && ok(o.height, 1, 1e5)) {
+        return { x: o.x, y: o.y, width: o.width, height: o.height };
+      }
+      window.localStorage.removeItem(boxKey);
+    } catch {
+    }
+    return null;
+  };
+  function restoreBox() {
+    if (!boxKey || !draggableOn && resizeLimits === null) return;
+    const st = loadBox();
+    if (!st) return;
+    const vp = viewport();
+    const lim = resizeLimits ?? DEFAULT_RESIZE_LIMITS;
+    const cur = readBox();
+    const useW = resizeLimits !== null && options.width === void 0;
+    const useH = resizeLimits !== null && options.height === void 0;
+    const clampN = (v, lo, hi) => Math.min(Math.max(v, lo), Math.max(lo, hi));
+    const width = useW ? clampN(st.width, lim.minWidth, Math.min(lim.maxWidth, vp.width)) : cur.width;
+    const height = useH ? clampN(st.height, lim.minHeight, Math.min(lim.maxHeight, vp.height)) : cur.height;
+    if (position === "inline") {
+      const base = { left: cur.left - inlineShift.x, top: cur.top - inlineShift.y };
+      const left = clampN(base.left + st.x, 0, vp.width - width);
+      const top = Math.max(base.top + st.y, -window.scrollY);
+      applyBox({ left, top, width, height }, base, useW || useH);
+    } else {
+      applyBox(fitBox({ left: st.x, top: st.y, width, height }, vp), null, useW || useH);
+    }
   }
+  restoreBox();
   scheduleLazy();
   const api = {
     element: wrapper,
@@ -561,8 +1030,98 @@ function createXiaochun(options) {
     motion: (m) => send("xc.motion", typeof m === "string" ? m.startsWith("http") || m.startsWith("/") ? { url: m } : { name: m } : m),
     expression: (name) => send("xc.expression", { name }),
     lookAt: (x, y) => send("xc.lookAt", { x, y }),
-    setModel: (m) => send("xc.setModel", typeof m === "string" ? /^(https?:)?\/|\.vrm/i.test(m) ? { url: m } : { outfit: m } : m),
+    setOutfit: (id) => {
+      if (!isXcId(id)) return Promise.reject(new Error("[bad_request] invalid outfit id"));
+      return send("xc.setOutfit", { id }, true, void 0, void 0, "outfits");
+    },
+    setScene: (id) => {
+      if (!isXcId(id)) return Promise.reject(new Error("[bad_request] invalid scene id"));
+      return send("xc.setScene", { id }, true, void 0, void 0, "scenes");
+    },
+    prefetch: (ids) => {
+      if (ids !== void 0 && (!Array.isArray(ids) || ids.some((x) => !isXcId(x)))) {
+        return Promise.reject(new Error("[bad_request] prefetch ids must be an array of outfit ids"));
+      }
+      return send("xc.prefetch", ids ? { ids } : {}, true, void 0, void 0, "prefetch");
+    },
+    getOutfits: async () => {
+      if (!iframe) activate();
+      await handshaked;
+      return caps?.outfits ? caps.outfits.slice() : [];
+    },
+    getScenes: async () => {
+      if (!iframe) activate();
+      await handshaked;
+      return caps?.scenes ? caps.scenes.slice() : [];
+    },
+    get outfit() {
+      return currentOutfit;
+    },
+    get scene() {
+      return currentScene;
+    },
+    setModel: (m) => {
+      const msg = typeof m === "string" ? /^(https?:)?\/|\.vrm/i.test(m) ? { url: m } : { outfit: m } : m;
+      if (msg.url !== void 0 && msg.outfit === void 0 && !options.allowCustomModel) {
+        const message = "custom model URLs are disabled; pass allowCustomModel: true to createXiaochun() (only for URLs you trust) or use setOutfit() with a built-in id";
+        emit("error", { code: "unsupported", message, command: "xc.setModel" });
+        return Promise.reject(new Error(`[unsupported] ${message}`));
+      }
+      return send("xc.setModel", msg);
+    },
     setConfig: (cfg) => send("xc.setConfig", cfg),
+    setSize(width, height) {
+      if (destroyed) return;
+      ws.width = css(width, defaultWidthCss(position !== "inline"));
+      ws.height = css(height, defaultHeightCss(position !== "inline"));
+      if (ws.maxWidth === "none") ws.maxWidth = "100%";
+      invalidateRect();
+    },
+    getBox: () => readBox(),
+    clearPersistedBox(opts) {
+      if (boxKey) {
+        try {
+          window.localStorage.removeItem(boxKey);
+        } catch {
+        }
+      }
+      if (destroyed || opts?.reset !== true) return;
+      endActiveGesture();
+      ws.width = css(options.width, defaultWidthCss(position !== "inline"));
+      ws.height = css(options.height, defaultHeightCss(position !== "inline"));
+      ws.maxWidth = "100%";
+      if (position === "inline") {
+        inlineShift = { x: 0, y: 0 };
+        ws.removeProperty("translate");
+      } else {
+        ws.left = "";
+        ws.top = "";
+        ws.right = "";
+        ws.bottom = "";
+        if (position === "bottom-right") {
+          ws.right = "var(--xc-offset-x, 16px)";
+          ws.bottom = "var(--xc-offset-y, 16px)";
+        }
+        if (position === "bottom-left") {
+          ws.left = "var(--xc-offset-x, 16px)";
+          ws.bottom = "var(--xc-offset-y, 16px)";
+        }
+      }
+      userMoved = false;
+      invalidateRect();
+    },
+    setBorderRadius(radius) {
+      radiusOpt = radius;
+      applyRadius();
+    },
+    setDraggable(on) {
+      draggableOn = on === true;
+      syncGestures();
+    },
+    setResizable(on) {
+      resizeLimits = normalizeResizable(on);
+      syncGestures();
+    },
     startListening: () => send("xc.mic", { enabled: true }),
     stopListening: () => send("xc.mic", { enabled: false }),
     mic: (enabled) => send("xc.mic", { enabled }),
@@ -587,10 +1146,10 @@ function createXiaochun(options) {
       if (handshakeTimer) clearTimeout(handshakeTimer);
       if (pointerRaf) cancelAnimationFrame(pointerRaf);
       window.removeEventListener("message", onWindowMessage);
-      window.removeEventListener("pointermove", onHostPointer);
-      window.removeEventListener("scroll", invalidateRect, true);
-      window.removeEventListener("resize", invalidateRect);
-      rectRo?.disconnect();
+      window.removeEventListener("resize", onWindowResize);
+      lockSelection(false);
+      disablePassthrough();
+      resolveHandshake();
       try {
         port?.close();
       } catch {
@@ -629,7 +1188,12 @@ var EVENT_MAP = [
   ["stt", "onStt"],
   ["utterance", "onUtterance"],
   ["hit-region", "onHitRegion"],
+  ["outfit-changed", "onOutfitChanged"],
+  ["scene-changed", "onSceneChanged"],
+  ["lang-changed", "onLangChanged"],
   ["error", "onError"],
+  ["move", "onMove"],
+  ["resize", "onResize"],
   ["destroy", "onDestroy"]
 ];
 function useXiaochun(options = {}) {
@@ -644,8 +1208,8 @@ function useXiaochun(options = {}) {
   (0, import_react.useEffect)(() => {
     if (!el) return;
     const cur = live.current;
-    const { onHandshake: _a, onReady: _b, onProgress: _c, onState: _d, onStt: _e, onUtterance: _f, onHitRegion: _g, onError: _h, onDestroy: _i, paused: _p, mic: _m, allowedOrigins, ...create } = cur;
-    void [_a, _b, _c, _d, _e, _f, _g, _h, _i, _p, _m];
+    const { onHandshake: _a, onReady: _b, onProgress: _c, onState: _d, onStt: _e, onUtterance: _f, onHitRegion: _g, onError: _h, onDestroy: _i, onOutfitChanged: _j, onSceneChanged: _k, onLangChanged: _l, onMove: _q, onResize: _r, paused: _p, mic: _m, allowedOrigins, ...create } = cur;
+    void [_a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _p, _m, _q, _r];
     const inst = createXiaochun({ ...create, allowedOrigins: allowedOrigins?.slice(), container: el });
     const offs = [];
     for (const [ev, cbName] of EVENT_MAP) {
@@ -675,11 +1239,9 @@ function useXiaochun(options = {}) {
     o.lazyMargin,
     o.placeholder,
     o.transparent,
-    o.width,
-    o.height,
     o.position,
-    o.draggable,
-    o.ui,
+    JSON.stringify(o.ui ?? null),
+    o.uiAutoHide,
     o.heavy,
     o.controls,
     o.autoPause,
@@ -687,9 +1249,16 @@ function useXiaochun(options = {}) {
     o.sandbox,
     o.handshakeTimeout,
     o.crossOriginIsolated,
-    o.zIndex
+    o.zIndex,
+    o.allowCustomModel,
+    o.persist,
+    o.persistBox,
+    Array.isArray(o.prefetch) ? o.prefetch.join(",") : o.prefetch
   ]);
-  const first = (0, import_react.useRef)({ lang: o.lang, model: o.model });
+  const wantOutfit = o.outfit ?? o.model;
+  const cameraKey = JSON.stringify(o.camera ?? null);
+  const first = (0, import_react.useRef)({ lang: o.lang, outfit: wantOutfit, scene: o.scene, width: o.width, height: o.height, camera: cameraKey });
+  const resizableKey = JSON.stringify(o.resizable ?? false);
   (0, import_react.useEffect)(() => {
     if (!client || first.current.lang === o.lang) return;
     first.current.lang = o.lang;
@@ -697,11 +1266,39 @@ function useXiaochun(options = {}) {
     });
   }, [client, o.lang]);
   (0, import_react.useEffect)(() => {
-    if (!client || first.current.model === o.model) return;
-    first.current.model = o.model;
-    if (o.model) void client.setModel(o.model).catch(() => {
+    if (!client || first.current.outfit === wantOutfit) return;
+    first.current.outfit = wantOutfit;
+    if (wantOutfit) void (isXcId(wantOutfit) ? client.setOutfit(wantOutfit) : client.setModel(wantOutfit)).catch(() => {
     });
-  }, [client, o.model]);
+  }, [client, wantOutfit]);
+  (0, import_react.useEffect)(() => {
+    if (!client || first.current.camera === cameraKey) return;
+    first.current.camera = cameraKey;
+    const c = o.camera;
+    void client.setConfig({ camera: { fov: c?.fov ?? null, distance: c?.distance ?? null, height: c?.height ?? null, intro: c?.intro ?? null } }).catch(() => {
+    });
+  }, [client, cameraKey]);
+  (0, import_react.useEffect)(() => {
+    if (!client || first.current.scene === o.scene) return;
+    first.current.scene = o.scene;
+    if (o.scene) void client.setScene(o.scene).catch(() => {
+    });
+  }, [client, o.scene]);
+  (0, import_react.useEffect)(() => {
+    if (!client || first.current.width === o.width && first.current.height === o.height) return;
+    first.current.width = o.width;
+    first.current.height = o.height;
+    client.setSize(o.width, o.height);
+  }, [client, o.width, o.height]);
+  (0, import_react.useEffect)(() => {
+    client?.setDraggable(o.draggable === true);
+  }, [client, o.draggable]);
+  (0, import_react.useEffect)(() => {
+    client?.setBorderRadius(o.borderRadius);
+  }, [client, o.borderRadius]);
+  (0, import_react.useEffect)(() => {
+    client?.setResizable(o.resizable ?? false);
+  }, [client, resizableKey]);
   (0, import_react.useEffect)(() => {
     if (!client || o.paused === void 0) return;
     if (o.paused) client.pause();
@@ -741,6 +1338,12 @@ function XiaochunInner(props, ref) {
       motion: (m) => c()?.motion(m) ?? reject(),
       expression: (n) => c()?.expression(n) ?? reject(),
       lookAt: (x, y) => c()?.lookAt(x, y) ?? reject(),
+      setOutfit: (id) => c()?.setOutfit(id) ?? reject(),
+      setScene: (id) => c()?.setScene(id) ?? reject(),
+      getOutfits: () => c()?.getOutfits() ?? reject(),
+      getScenes: () => c()?.getScenes() ?? reject(),
+      clearPersistedBox: (opts) => c()?.clearPersistedBox(opts),
+      prefetch: (ids) => c()?.prefetch(ids) ?? reject(),
       setModel: (m) => c()?.setModel(m) ?? reject(),
       setConfig: (cfg) => c()?.setConfig(cfg) ?? reject(),
       startListening: () => c()?.startListening() ?? reject(),
@@ -760,8 +1363,8 @@ function XiaochunInner(props, ref) {
   }, []);
   const box = {
     ...style,
-    width: css2(props.width, "320px"),
-    height: css2(props.height, "480px"),
+    width: css2(props.width, defaultWidthCss()),
+    height: css2(props.height, defaultHeightCss()),
     maxWidth: "100%",
     position: style?.position ?? "relative"
   };