@firetable/project-xiaochun 0.1.15 → 0.1.17

package/dist/react.cjs

@@ -1,4 +1,4 @@
-/*! @firetable/project-xiaochun v0.1.15 | MIT | https://github.com/FireTable/project-xiaochun */
+/*! @firetable/project-xiaochun v0.1.17 | MIT | https://github.com/FireTable/project-xiaochun */
 "use strict";
 "use client";
 var __defProp = Object.defineProperty;
@@ -33,7 +33,7 @@ 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"];
+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) {
@@ -51,6 +51,49 @@ function normalizeXcUiOption(v) {
   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) {
@@ -167,7 +210,20 @@ var GestureGate = class {
 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");
@@ -222,6 +278,16 @@ function createXiaochun(options) {
   }
   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);
@@ -236,11 +302,12 @@ 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";
+  noSelect(ws);
   ws.boxShadow = "var(--xc-shadow, none)";
   const applyWrapperBg = () => {
     ws.background = transparent ? "" : "var(--xc-bg, transparent)";
@@ -275,8 +342,8 @@ 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;
@@ -290,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);
   }
@@ -448,6 +516,11 @@ function createXiaochun(options) {
     if (transparent) u.searchParams.set("transparent", "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 === false) u.searchParams.set("controls", "0");
     if (initialScene && isXcId(initialScene)) u.searchParams.set("scene", initialScene);
@@ -479,6 +552,7 @@ function createXiaochun(options) {
     s.colorScheme = "normal";
     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";
@@ -584,6 +658,9 @@ function createXiaochun(options) {
         ack(data.id);
         break;
       }
+      case "xc.lang-changed":
+        emit("lang-changed", data.payload);
+        break;
       case "xc.prefetched":
         ack(data.id, data.payload);
         break;
@@ -828,6 +905,7 @@ function createXiaochun(options) {
     emit(activeGesture.kind, { phase: "end", ...b });
     activeGesture = null;
     lockSelection(false);
+    saveBox();
   }
   function onGesture(kind, raw) {
     if (destroyed || !caps?.gestures) return;
@@ -856,6 +934,7 @@ function createXiaochun(options) {
     if (p.phase === "end") {
       activeGesture = null;
       lockSelection(false);
+      saveBox();
     }
   }
   function syncGestures() {
@@ -880,11 +959,63 @@ function createXiaochun(options) {
   const onWindowResize = () => {
     if (!userMoved || activeGesture || destroyed) return;
     const cur = readBox();
-    const fit = fitBox(cur, viewport());
+    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,
@@ -941,11 +1072,44 @@ function createXiaochun(options) {
     setConfig: (cfg) => send("xc.setConfig", cfg),
     setSize(width, height) {
       if (destroyed) return;
-      ws.width = css(width, "320px");
-      ws.height = css(height, "480px");
+      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();
@@ -1026,6 +1190,7 @@ var EVENT_MAP = [
   ["hit-region", "onHitRegion"],
   ["outfit-changed", "onOutfitChanged"],
   ["scene-changed", "onSceneChanged"],
+  ["lang-changed", "onLangChanged"],
   ["error", "onError"],
   ["move", "onMove"],
   ["resize", "onResize"],
@@ -1043,7 +1208,7 @@ 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, onOutfitChanged: _j, onSceneChanged: _k, onMove: _q, onResize: _r, paused: _p, mic: _m, allowedOrigins, ...create } = cur;
+    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 = [];
@@ -1076,6 +1241,7 @@ function useXiaochun(options = {}) {
     o.transparent,
     o.position,
     JSON.stringify(o.ui ?? null),
+    o.uiAutoHide,
     o.heavy,
     o.controls,
     o.autoPause,
@@ -1086,10 +1252,12 @@ function useXiaochun(options = {}) {
     o.zIndex,
     o.allowCustomModel,
     o.persist,
+    o.persistBox,
     Array.isArray(o.prefetch) ? o.prefetch.join(",") : o.prefetch
   ]);
   const wantOutfit = o.outfit ?? o.model;
-  const first = (0, import_react.useRef)({ lang: o.lang, outfit: wantOutfit, scene: o.scene, width: o.width, height: o.height });
+  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;
@@ -1103,6 +1271,13 @@ function useXiaochun(options = {}) {
     if (wantOutfit) void (isXcId(wantOutfit) ? client.setOutfit(wantOutfit) : client.setModel(wantOutfit)).catch(() => {
     });
   }, [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;
@@ -1113,7 +1288,7 @@ function useXiaochun(options = {}) {
     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 ?? 320, o.height ?? 480);
+    client.setSize(o.width, o.height);
   }, [client, o.width, o.height]);
   (0, import_react.useEffect)(() => {
     client?.setDraggable(o.draggable === true);
@@ -1167,6 +1342,7 @@ function XiaochunInner(props, ref) {
       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(),
@@ -1187,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"
   };