@firetable/project-xiaochun 0.1.14 → 0.1.15

package/dist/index.cjs

@@ -1,4 +1,4 @@
-/*! @firetable/project-xiaochun v0.1.14 | MIT | https://github.com/FireTable/project-xiaochun */
+/*! @firetable/project-xiaochun v0.1.15 | MIT | https://github.com/FireTable/project-xiaochun */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -25,18 +25,27 @@ __export(src_exports, {
   XC_DEFAULT_SRC: () => XC_DEFAULT_SRC,
   XC_FRAME_TO_HOST: () => XC_FRAME_TO_HOST,
   XC_HOST_TO_FRAME: () => XC_HOST_TO_FRAME,
+  XC_ID_RE: () => XC_ID_RE,
   XC_IMPLEMENTED_COMMANDS: () => XC_IMPLEMENTED_COMMANDS,
   XC_PROTOCOL_MAPPING: () => XC_PROTOCOL_MAPPING,
   XC_PROTOCOL_VERSION: () => XC_PROTOCOL_VERSION,
+  XC_UI_LEGACY_PARTS: () => XC_UI_LEGACY_PARTS,
+  XC_UI_PARTS: () => XC_UI_PARTS,
   XC_UNSUPPORTED_COMMANDS: () => XC_UNSUPPORTED_COMMANDS,
+  XC_WINDOW_CORNER_RADIUS: () => XC_WINDOW_CORNER_RADIUS,
   XIAOCHUN_ELEMENT_TAG: () => XIAOCHUN_ELEMENT_TAG,
   XIAOCHUN_PROTOCOL_SCHEME: () => XIAOCHUN_PROTOCOL_SCHEME,
   createXiaochun: () => createXiaochun,
   defineXiaochunElement: () => defineXiaochunElement,
   isXcEnvelope: () => isXcEnvelope,
+  isXcId: () => isXcId,
   normalizeOrigin: () => normalizeOrigin,
+  normalizeXcUiOption: () => normalizeXcUiOption,
   parseProtocolUrl: () => parseProtocolUrl,
+  parseXcUiList: () => parseXcUiList,
+  parseXcUiParam: () => parseXcUiParam,
   toProtocolUrl: () => toProtocolUrl,
+  xcHasOwn: () => xcHasOwn,
   xcMessage: () => xcMessage
 });
 module.exports = __toCommonJS(src_exports);
@@ -56,6 +65,9 @@ var XC_HOST_TO_FRAME = [
   "xc.lookAt",
   "xc.pointer",
   "xc.setModel",
+  "xc.setOutfit",
+  "xc.setScene",
+  "xc.prefetch",
   "xc.setConfig",
   "xc.mic",
   "xc.pause",
@@ -66,10 +78,15 @@ var XC_FRAME_TO_HOST = [
   "xc.ready",
   "xc.load.progress",
   "xc.loaded",
+  "xc.outfit-changed",
+  "xc.scene-changed",
+  "xc.prefetched",
   "xc.state",
   "xc.stt",
   "xc.utterance",
   "xc.hit-region",
+  "xc.gesture-move",
+  "xc.gesture-resize",
   "xc.error"
 ];
 var XC_IMPLEMENTED_COMMANDS = [
@@ -81,6 +98,9 @@ var XC_IMPLEMENTED_COMMANDS = [
   "xc.expression",
   "xc.pointer",
   "xc.setModel",
+  "xc.setOutfit",
+  "xc.setScene",
+  "xc.prefetch",
   "xc.setConfig",
   "xc.mic",
   "xc.pause",
@@ -95,6 +115,34 @@ var XC_PROTOCOL_MAPPING = [
   { xc: "xc.audio", note: "source \u4E3A ArrayBuffer / Blob", action: "audio", url: null },
   { xc: "xc.audio.chunk / xc.audio.end", note: "\u6D41\u5F0F PCM", action: "audio", url: null }
 ];
+var XC_WINDOW_CORNER_RADIUS = 20;
+var XC_UI_PARTS = ["chat", "bubble", "outfit", "scene"];
+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 parseXcUiParam(raw) {
+  const v = (raw ?? "").trim().toLowerCase();
+  if (v === "" || v === "0" || v === "false") return { parts: [], unknown: [], legacy: false };
+  if (v === "1" || v === "true") return { parts: [...XC_UI_LEGACY_PARTS], unknown: [], legacy: true };
+  return parseXcUiList(v.split(",").filter((x) => x.trim() !== ""));
+}
+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 };
+}
+var XC_ID_RE = /^[a-z][a-z0-9_]{0,63}$/;
+var isXcId = (v) => typeof v === "string" && XC_ID_RE.test(v);
+var xcHasOwn = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
 function xcMessage(type, payload, id) {
   const m = { type, v: XC_PROTOCOL_VERSION, payload };
   if (id !== void 0) m.id = id;
@@ -116,6 +164,95 @@ 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>'
@@ -142,8 +279,46 @@ 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;
+  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;
@@ -156,9 +331,20 @@ function createXiaochun(options) {
   ws.maxWidth = "100%";
   ws.overflow = "visible";
   ws.contain = "layout style";
-  ws.borderRadius = "var(--xc-radius, 0)";
   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)";
@@ -185,7 +371,7 @@ function createXiaochun(options) {
     }
     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%";
@@ -222,25 +408,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);
@@ -290,7 +496,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");
@@ -324,17 +530,18 @@ 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 (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() {
@@ -360,7 +567,7 @@ 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");
     s.opacity = "0";
     s.transition = "opacity .25s ease";
@@ -373,7 +580,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;
@@ -386,20 +593,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;
@@ -410,6 +636,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;
@@ -422,6 +653,30 @@ 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.prefetched":
+        ack(data.id, data.payload);
+        break;
       case "xc.state":
         emit("state", data.payload);
         break;
@@ -446,9 +701,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);
@@ -505,16 +767,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;
@@ -566,50 +858,123 @@ 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);
   }
+  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);
+    }
+  }
+  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 fit = fitBox(cur, viewport());
+    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 });
   scheduleLazy();
   const api = {
     element: wrapper,
@@ -624,8 +989,65 @@ 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, "320px");
+      ws.height = css(height, "480px");
+      invalidateRect();
+    },
+    getBox: () => readBox(),
+    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 }),
@@ -650,10 +1072,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 {
@@ -686,11 +1108,17 @@ function createXiaochun(options) {
 // src/avatar-element.ts
 var OBSERVED = [
   "src",
+  "outfit",
+  "scene",
   "model",
   "lang",
   "mic",
   "transparent",
   "draggable",
+  "resizable",
+  "min-size",
+  "max-size",
+  "border-radius",
   "position",
   "size",
   "lazy",
@@ -700,14 +1128,36 @@ var OBSERVED = [
   "ui",
   "controls",
   "allowed-origins",
-  "cross-origin-isolated"
+  "cross-origin-isolated",
+  "persist",
+  "allow-custom-model",
+  "prefetch"
 ];
-var REBUILD = /* @__PURE__ */ new Set(["src", "draggable", "position", "size", "lazy", "placeholder", "heavy", "ui", "controls", "allowed-origins", "transparent", "cross-origin-isolated"]);
+var REBUILD = /* @__PURE__ */ new Set(["src", "position", "lazy", "placeholder", "heavy", "ui", "controls", "allowed-origins", "transparent", "cross-origin-isolated", "persist", "allow-custom-model", "prefetch"]);
+function radiusAttr(v) {
+  if (v === null || v.trim() === "") return void 0;
+  const t = v.trim();
+  return /^\d+(\.\d+)?$/.test(t) ? Number(t) : t;
+}
 function boolAttr(el, name, dflt) {
   const v = el.getAttribute(name);
   if (v === null) return dflt;
   return v !== "false";
 }
+function prefetchAttr(v) {
+  if (v === null || v === "false") return false;
+  if (v === "" || v === "true") return true;
+  return v.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function uiAttr(v) {
+  if (v === null || v === "false" || v === "0") return void 0;
+  if (v === "" || v === "true" || v === "1") return true;
+  return v.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function parsePx(v) {
+  const m = v?.trim().match(/^(\d+(?:\.\d+)?)\s*x\s*(\d+(?:\.\d+)?)$/i);
+  return m ? { w: Number(m[1]), h: Number(m[2]) } : void 0;
+}
 function parseSize(v) {
   if (!v) return { width: "320px", height: "480px" };
   const m = v.trim().split(/x/i);
@@ -755,10 +1205,20 @@ function createElementClass() {
         return;
       }
       const c = this.client;
-      if (name === "model" && newV) void c.setModel(newV).catch(() => {
+      if ((name === "outfit" || name === "model") && newV) {
+        const want = name === "model" && this.hasAttribute("outfit") ? null : newV;
+        if (want) void (isXcId(want) ? c.setOutfit(want) : c.setModel(want)).catch(() => {
+        });
+      } else if (name === "scene" && newV) void c.setScene(newV).catch(() => {
       });
       else if (name === "lang" && newV) void c.setConfig({ lang: newV }).catch(() => {
       });
+      else if (name === "size") {
+        const { width, height } = parseSize(newV);
+        c.setSize(width, height);
+      } else if (name === "border-radius") c.setBorderRadius(radiusAttr(newV));
+      else if (name === "draggable") c.setDraggable(boolAttr(this, "draggable", false));
+      else if (name === "resizable" || name === "min-size" || name === "max-size") c.setResizable(this.resizableOption());
       else if (name === "mic") void c.mic(boolAttr(this, "mic", false)).catch(() => {
       });
       else if (name === "paused") {
@@ -785,11 +1245,17 @@ function createElementClass() {
         height,
         position: this.getAttribute("position") ?? "inline",
         draggable: boolAttr(this, "draggable", false),
+        resizable: this.resizableOption(),
+        borderRadius: radiusAttr(this.getAttribute("border-radius")),
         lang: this.getAttribute("lang") ?? void 0,
-        model: this.getAttribute("model") ?? void 0,
+        outfit: this.getAttribute("outfit") ?? this.getAttribute("model") ?? void 0,
+        scene: this.getAttribute("scene") ?? void 0,
+        persist: this.getAttribute("persist") || void 0,
+        allowCustomModel: boolAttr(this, "allow-custom-model", false),
+        prefetch: prefetchAttr(this.getAttribute("prefetch")),
         heavy: this.getAttribute("heavy") ?? void 0,
-        ui: boolAttr(this, "ui", false),
-        controls: boolAttr(this, "controls", false),
+        ui: uiAttr(this.getAttribute("ui")),
+        controls: boolAttr(this, "controls", true),
         crossOriginIsolated: boolAttr(this, "cross-origin-isolated", false)
       });
       this.client = c;
@@ -800,10 +1266,20 @@ function createElementClass() {
       fwd("stt", "xc-stt");
       fwd("utterance", "xc-utterance");
       fwd("error", "xc-error");
+      fwd("outfit-changed", "xc-outfit-changed");
+      fwd("scene-changed", "xc-scene-changed");
+      fwd("move", "xc-move");
+      fwd("resize", "xc-resize");
       if (boolAttr(this, "paused", false)) c.pause();
       if (boolAttr(this, "mic", false)) void c.ready.then(() => c.mic(true)).catch(() => {
       });
     }
+    /** resizable / min-size / max-size 属性 → SDK 的 resizable 选项 (缺省 / "false" = 关)。 */
+    resizableOption() {
+      if (!boolAttr(this, "resizable", false)) return false;
+      const min = parsePx(this.getAttribute("min-size")), max = parsePx(this.getAttribute("max-size"));
+      return { minWidth: min?.w, minHeight: min?.h, maxWidth: max?.w, maxHeight: max?.h };
+    }
     say(text, opts) {
       return this.requireClient().say(text, opts);
     }
@@ -819,6 +1295,21 @@ function createElementClass() {
     expression(name) {
       return this.requireClient().expression(name);
     }
+    setOutfit(id) {
+      return this.requireClient().setOutfit(id);
+    }
+    setScene(id) {
+      return this.requireClient().setScene(id);
+    }
+    getOutfits() {
+      return this.requireClient().getOutfits();
+    }
+    getScenes() {
+      return this.requireClient().getScenes();
+    }
+    prefetch(ids) {
+      return this.requireClient().prefetch(ids);
+    }
     destroy() {
       this.client?.destroy();
       this.client = null;