@xpert-ai/chatkit-types 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -36,6 +36,46 @@ export declare interface ApprovalHostReference {
     expiresAt: number;
 }
 
+/** IDs are resource identifiers, not a closed list of bundled presets. */
+export declare type AssistantAppearance = {
+    version: 1;
+    kind: 'image';
+} | {
+    version: 1;
+    kind: 'character';
+    id: string;
+    color: string;
+    config?: AssistantCharacterConfig;
+} | {
+    version: 1;
+    kind: 'pet';
+    id: string;
+    /** Sprite layout version; omitted by legacy v1 avatars. */
+    spriteVersionNumber?: 1 | 2;
+    asset?: {
+        type: 'sprite-atlas' | 'animated-image';
+        url: string;
+    };
+};
+
+export declare type AssistantCharacterConfig = {
+    shape: 'round' | 'pebble' | 'pill' | 'drop' | 'flame' | 'triangle' | 'square' | 'bag' | 'star' | 'heart' | 'cloud' | 'clover';
+    eyes: 'oval' | 'toon' | 'pill' | 'dot' | 'ring' | 'happy' | 'sleepy' | 'wink' | 'plus' | 'slash' | 'squint';
+    mouth: 'none' | 'smile' | 'open' | 'neutral' | 'o';
+    motion: 'float' | 'bounce' | 'sway' | 'none';
+    eyeSize: number;
+    eyeSpacing: number;
+    brows?: 'none' | 'flat' | 'angry' | 'worried' | 'raised';
+    ink?: 'auto' | 'dark' | 'light';
+    tilt?: number;
+    speed?: number;
+    blink?: boolean;
+};
+
+export declare type AssistantCustomizeEffect = {
+    assistantId: string;
+};
+
 /**
  * strategies to host files before attaching them to messages.
  */
@@ -220,6 +260,8 @@ export declare type ChatFileChange = {
     updatedAt?: string;
 };
 
+export declare const CHATKIT_ASSISTANT_CUSTOMIZE_EFFECT = "assistant.customize";
+
 export declare const CHATKIT_TASK_SUMMARY_OPEN_RESOURCE_EFFECT: "task_summary.open_resource";
 
 export declare interface ChatKitApprovalsOptions {
@@ -231,6 +273,18 @@ export declare interface ChatKitApprovalsOptions {
     onAction?: (input: ApprovalActionRequest) => Promise<void> | void;
 }
 
+/** Computer shortcuts in the Assistant details dialog. Remote targets use registered View keys. */
+export declare type ChatKitAssistantComputers = {
+    cloud?: {
+        viewKey: string;
+    };
+    /** Host-reported local Shell state; opening emits assistant.computer.open with kind: local. */
+    local?: {
+        name?: string;
+        status: 'loading' | 'unavailable' | 'disabled' | 'ready' | 'connected' | 'error';
+    };
+};
+
 export declare type ChatKitClientSecretObject = {
     secret: string;
     organizationId?: string;
@@ -581,6 +635,15 @@ export declare type ChatKitOptions = {
      */
     header?: {
         enabled?: boolean;
+        /** Center the published Assistant character in bubble mode. Defaults to true. */
+        character?: {
+            enabled?: boolean;
+            /** Shows customization actions, emitted as the assistant.customize public effect. */
+            customizable?: boolean;
+            computers?: ChatKitAssistantComputers;
+            /** Honor an explicit reduced-animation preference in addition to the OS setting. */
+            reducedMotion?: boolean;
+        };
         /** Enable native Electron dragging/OS double-click behavior on unused chat and Workbench header space. Defaults to false. */
         windowDrag?: boolean;
         /**
@@ -796,6 +859,8 @@ export declare type ChatKitPetBoundsPadding = {
 export declare type ChatKitPetCharacter = {
     type: 'sprite-atlas';
     src: string;
+    /** v1: 8 × 9; v2: 8 × 11, with 16 directional poses in the final two rows. */
+    spriteVersionNumber?: 1 | 2;
     atlas?: ChatKitPetSpriteAtlas;
 };
 
@@ -1434,6 +1499,10 @@ declare type CustomApiConfig = {
     xpertId?: string;
 };
 
+export declare function customCharacterSvg(appearance: Extract<AssistantAppearance, {
+    kind: 'character';
+}>, state?: string, animate?: boolean): string;
+
 export declare type DatePicker = {
     type: 'DatePicker';
     key?: string;
@@ -1465,6 +1534,8 @@ export declare const DEFAULT_PET_SPRITESHEET_URL = "/pets/boba/spritesheet.webp"
 
 export declare const DEFAULT_PET_STORAGE_KEY = "chatkit:pet:position:v1";
 
+export declare const defaultCharacterConfig: AssistantCharacterConfig;
+
 export declare type Divider = {
     type: 'Divider';
     key?: string;
@@ -1975,7 +2046,7 @@ export declare function mergeChatSkillUsages(...groups: ReadonlyArray<readonly C
 /** Collapse observed operations to the net change, retaining immutable first/last review references. */
 export declare function mergeFileChanges(items: ChatFileChange[]): ChatFileChange[];
 
-export declare function mergePetSpriteAtlas(override?: ChatKitPetSpriteAtlas): PetSpriteAtlasDefinition;
+export declare function mergePetSpriteAtlas(override?: ChatKitPetSpriteAtlas, spriteVersionNumber?: 1 | 2): PetSpriteAtlasDefinition;
 
 export declare type MessageContentImageUrl = {
     type: 'image_url';
@@ -2046,6 +2117,8 @@ export declare function normalizeRequestLanguage(locale?: string | null): string
 
 export declare function normalizeThreadReference(value: unknown): ChatKitThreadReference | null;
 
+export declare function parseAssistantAppearance(value: unknown): AssistantAppearance | undefined;
+
 export declare function parseFileActivityContent(value: unknown): TMessageContentFileActivity | null;
 
 export declare function parseFileChangeReport(value: unknown): FileChangeReport | null;
@@ -2063,6 +2136,12 @@ export declare type PetFrameAnimationDefinition = {
     frameDurations: readonly number[];
 };
 
+/** v2's 16 poses are clockwise from up; a central dead zone restores idle. */
+export declare function petLookFrame(dx: number, dy: number, deadZone?: number): {
+    row: number;
+    column: number;
+} | null;
+
 export declare type PetPosition = {
     x: number;
     y: number;

package/dist/index.js

@@ -415,6 +415,170 @@ function normalizeThreadReference(value) {
 function isLocator(value) {
   return typeof value === "string" && value.trim().length > 0 && value.length <= 128;
 }
+const CHATKIT_ASSISTANT_CUSTOMIZE_EFFECT = "assistant.customize";
+function parseAssistantAppearance(value) {
+  if (!value || typeof value !== "object" || !("version" in value) || value.version !== 1 || !("kind" in value))
+    return;
+  if (value.kind === "image") return { version: 1, kind: "image" };
+  if (!("id" in value) || typeof value.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,99}$/.test(value.id))
+    return;
+  if (value.kind === "character" && "color" in value && typeof value.color === "string" && /^#[0-9a-f]{6}$/i.test(value.color)) {
+    if ("config" in value && value.config !== void 0 && !isCharacterConfig(value.config))
+      return;
+    return value;
+  }
+  if (value.kind === "pet") {
+    if ("spriteVersionNumber" in value && value.spriteVersionNumber !== void 0 && value.spriteVersionNumber !== 1 && value.spriteVersionNumber !== 2) return;
+    if ("asset" in value && value.asset !== void 0) {
+      const asset = value.asset;
+      if (!asset || typeof asset !== "object" || !("type" in asset) || !["sprite-atlas", "animated-image"].includes(String(asset.type)) || !("url" in asset) || typeof asset.url !== "string" || asset.url.length > 4096 || !/^(https?:\/\/|\/(?!\/))/.test(asset.url))
+        return;
+    }
+    return value;
+  }
+}
+function isCharacterConfig(value) {
+  return !!value && typeof value === "object" && "shape" in value && [
+    "round",
+    "pebble",
+    "pill",
+    "drop",
+    "flame",
+    "triangle",
+    "square",
+    "bag",
+    "star",
+    "heart",
+    "cloud",
+    "clover"
+  ].includes(String(value.shape)) && "eyes" in value && [
+    "oval",
+    "toon",
+    "pill",
+    "dot",
+    "ring",
+    "happy",
+    "sleepy",
+    "wink",
+    "plus",
+    "slash",
+    "squint"
+  ].includes(String(value.eyes)) && "mouth" in value && ["none", "smile", "open", "neutral", "o"].includes(String(value.mouth)) && "motion" in value && ["float", "bounce", "sway", "none"].includes(String(value.motion)) && "eyeSize" in value && typeof value.eyeSize === "number" && Number.isFinite(value.eyeSize) && value.eyeSize >= 0.6 && value.eyeSize <= 1.5 && "eyeSpacing" in value && typeof value.eyeSpacing === "number" && Number.isFinite(value.eyeSpacing) && value.eyeSpacing >= 0.55 && value.eyeSpacing <= 1.6 && (!("brows" in value) || value.brows === void 0 || ["none", "flat", "angry", "worried", "raised"].includes(
+    String(value.brows)
+  )) && (!("ink" in value) || value.ink === void 0 || ["auto", "dark", "light"].includes(String(value.ink))) && (!("tilt" in value) || value.tilt === void 0 || typeof value.tilt === "number" && Number.isFinite(value.tilt) && value.tilt >= -15 && value.tilt <= 15) && (!("speed" in value) || value.speed === void 0 || typeof value.speed === "number" && Number.isFinite(value.speed) && value.speed >= 0.5 && value.speed <= 2) && (!("blink" in value) || value.blink === void 0 || typeof value.blink === "boolean");
+}
+const defaultCharacterConfig = {
+  shape: "round",
+  eyes: "oval",
+  mouth: "smile",
+  motion: "float",
+  eyeSize: 1,
+  eyeSpacing: 1,
+  brows: "none",
+  ink: "auto",
+  tilt: 0,
+  speed: 1,
+  blink: true
+};
+const shapes = {
+  round: '<circle cx="100" cy="100" r="65"/>',
+  pebble: '<path d="M34 96 C37 49 77 28 114 38 C161 42 177 84 163 128 C155 164 109 176 68 157 C43 149 30 121 34 96Z"/>',
+  pill: '<rect x="26" y="51" width="148" height="99" rx="49"/>',
+  drop: '<path d="M100 24 C87 46 39 72 39 111 C39 174 161 174 161 111 C161 72 113 46 100 24Z"/>',
+  flame: '<path d="M114 22 C108 59 159 57 164 109 C174 179 35 187 35 118 C34 94 45 79 62 64 C59 89 71 92 74 75 C76 48 96 30 114 22Z"/>',
+  triangle: '<path d="M86 35 Q100 13 114 35 L177 142 Q188 165 161 167 L39 167 Q12 165 24 142Z"/>',
+  square: '<rect x="37" y="37" width="126" height="126" rx="34"/>',
+  bag: '<path d="M78 56 V37 Q78 30 86 30 H114 Q122 30 122 37 V56" fill="none" stroke="currentColor" stroke-width="8"/><rect x="29" y="52" width="142" height="111" rx="22"/>',
+  star: '<path d="M92 30 Q100 14 108 30 L126 64 L166 70 Q185 72 171 87 L143 113 L149 152 Q153 172 135 164 L100 144 L65 164 Q47 172 51 152 L57 113 L29 87 Q15 72 34 70 L74 64Z"/>',
+  heart: '<path d="M100 60 C58 2 6 49 32 101 C45 129 71 151 100 171 C129 151 155 129 168 101 C194 49 142 2 100 60Z"/>',
+  cloud: '<path d="M48 153 C3 152 15 92 45 87 C42 40 93 30 114 58 C150 27 182 68 168 99 C199 139 163 165 133 152 C108 174 75 168 65 152Z"/>',
+  clover: '<path d="M100 49 C143 -1 200 63 151 100 C201 141 140 200 100 151 C60 200 -1 141 49 100 C0 60 60 0 100 49Z"/>'
+};
+const finite = (value, fallback, min, max) => typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+function customCharacterSvg(appearance, state = "idle", animate = false) {
+  const config = { ...defaultCharacterConfig, ...appearance.config };
+  const color = /^#[0-9a-f]{6}$/i.test(appearance.color) ? appearance.color : "#7c6ee6";
+  const luminance = [1, 3, 5].map((start) => {
+    const channel = parseInt(color.slice(start, start + 2), 16) / 255;
+    return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+  });
+  const darkBackground = luminance[0] * 0.2126 + luminance[1] * 0.7152 + luminance[2] * 0.0722 < 0.18;
+  const ink = config.ink === "light" ? "#ffffff" : config.ink === "dark" ? "#20212c" : darkBackground ? "#ffffff" : "#20212c";
+  const speed = finite(config.speed, 1, 0.5, 2);
+  const tilt = finite(config.tilt, 0, -15, 15);
+  const eyeSize = finite(config.eyeSize, 1, 0.6, 1.5);
+  const gap = finite(config.eyeSpacing, 1, 0.55, 1.6) * 18;
+  const moving = animate && config.motion !== "none";
+  const thinking = state === "review";
+  const working = state === "running" || state === "running-right" || state === "running-left";
+  const success = state === "waving" || state === "jumping";
+  const sleeping = state === "sleeping";
+  const alarm = state === "waiting";
+  const faceScale = [
+    "drop",
+    "flame",
+    "triangle",
+    "star",
+    "heart",
+    "clover"
+  ].includes(config.shape) ? 0.78 : 1;
+  const faceY = ["drop", "triangle", "flame"].includes(config.shape) ? 10 : 0;
+  const eyes = sleeping ? "sleepy" : success ? "happy" : config.eyes;
+  const brows = alarm || state === "failed" ? "worried" : config.brows;
+  const blink = moving && config.blink !== false && !sleeping ? `<animateTransform attributeName="transform" type="scale" values="1 1;1 1;1 .1;1 1;1 1" keyTimes="0;.83;.87;.91;1" dur="${4.5 / speed}s" repeatCount="indefinite"/>` : "";
+  const eye = (x, right) => {
+    let drawing;
+    switch (eyes) {
+      case "happy":
+        drawing = '<path d="M-7 1 Q0 -11 7 1"/>';
+        break;
+      case "sleepy":
+        drawing = '<path d="M-7 0 Q0 4 7 0"/>';
+        break;
+      case "plus":
+        drawing = '<path d="M-7 0 H7 M0 -7 V7"/>';
+        break;
+      case "slash":
+        drawing = '<path d="M-5 7 L5 -7"/>';
+        break;
+      case "squint":
+        drawing = `<path d="${right ? "M5 -7 L-3 0 L5 7" : "M-5 -7 L3 0 L-5 7"}"/>`;
+        break;
+      case "ring":
+        drawing = '<ellipse rx="6" ry="8" stroke-width="3"/>';
+        break;
+      case "dot":
+        drawing = `<circle r="4.5" fill="${ink}" stroke="none"/>`;
+        break;
+      case "pill":
+        drawing = `<rect x="-3" y="-9" width="6" height="18" rx="3" fill="${ink}" stroke="none"/>`;
+        break;
+      case "wink":
+        if (right) {
+          drawing = '<path d="M-6 -5 L3 0 L-6 5"/>';
+          break;
+        }
+      case "toon":
+        drawing = `<ellipse rx="9" ry="11" fill="#ffffff" stroke="#20212c" stroke-width="1"/><ellipse cx="${thinking ? 2 : 0}" cy="${thinking ? -3 : working ? 3 : 1}" rx="4" ry="6" fill="#20212c" stroke="none"/>`;
+        break;
+      default:
+        drawing = `<ellipse rx="5" ry="8" fill="${ink}" stroke="none"/>`;
+    }
+    return `<g transform="translate(${x} 97)"><g>${["oval", "toon", "dot", "ring", "pill", "wink"].includes(eyes) ? blink : ""}${drawing}</g></g>`;
+  };
+  const brow = (x, right) => {
+    const lift = right ? -1 : 1;
+    const path = brows === "flat" ? "M-8 -17 H8" : brows === "angry" ? `M-8 ${-21 - 4 * lift} L8 ${-21 + 4 * lift}` : brows === "worried" ? `M-8 ${-21 + 4 * lift} L8 ${-21 - 4 * lift}` : brows === "raised" ? right ? "M-8 -21 Q0 -30 8 -21" : "M-8 -18 H8" : "";
+    return path ? `<path transform="translate(${x} 97)" d="${path}" stroke-width="3"/>` : "";
+  };
+  const mouth = state === "failed" ? '<path d="M88 130 Q100 116 112 130"/>' : alarm || thinking ? '<ellipse cx="100" cy="127" rx="4" ry="5"/>' : success || config.mouth === "open" ? `<path d="M87 123 Q100 128 113 123 Q111 144 100 144 Q89 144 87 123Z" fill="${ink}"/>` : config.mouth === "none" ? "" : config.mouth === "neutral" || sleeping ? '<path d="M91 127 H109"/>' : config.mouth === "o" ? '<ellipse cx="100" cy="127" rx="5" ry="7"/>' : '<path d="M87 125 Q100 138 113 125"/>';
+  const animation = !moving ? "" : state === "failed" ? `<animateTransform attributeName="transform" type="translate" values="0 0;-3 0;3 0;0 0" dur="${0.4 / speed}s" repeatCount="2"/>` : config.motion === "sway" ? `<animateTransform attributeName="transform" type="rotate" values="-5 100 130;5 100 130;-5 100 130" dur="${2.4 / speed}s" repeatCount="indefinite"/>` : `<animateTransform attributeName="transform" type="translate" values="0 0;0 ${success || config.motion === "bounce" ? -12 : sleeping ? -2 : -5};0 0" dur="${(success || config.motion === "bounce" ? 1.1 : sleeping ? 4 : 3) / speed}s" repeatCount="indefinite"/>`;
+  const pulse = moving ? `<animate attributeName="opacity" values=".35;1;.35" dur="${1.5 / speed}s" repeatCount="indefinite"/>` : "";
+  const activity = thinking ? `<g fill="${ink}" opacity=".6"><circle cx="153" cy="49" r="3"/><circle cx="161" cy="39" r="5"/><circle cx="174" cy="26" r="7"/>${pulse}</g>` : working ? `<g fill="none" stroke="${ink}" stroke-width="3" stroke-linecap="round"><path d="M158 142 H175 M158 150 H183 M158 158 H171"/>${pulse}</g>` : alarm ? `<g fill="${ink}"><circle cx="161" cy="46" r="10"/><path d="M161 40 V47 M161 51 V52" stroke="${color}" stroke-width="2.5"/>${pulse}</g>` : sleeping ? `<path d="M150 60 H163 L151 72 H164 M169 35 H184 L170 48 H185" fill="none" stroke="${ink}" opacity=".5" stroke-width="3"/>` : state === "listening" ? `<g fill="none" stroke="${ink}" stroke-width="3" stroke-linecap="round"><path d="M167 84 V108 M175 91 V101"/>${pulse}</g>` : "";
+  const shift = thinking ? "3 -3" : working ? "1 3" : "0 0";
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200" viewBox="0 0 200 200"><ellipse cx="100" cy="186" rx="42" ry="5" fill="${color}" opacity=".12"/><g>${animation}<g transform="rotate(${tilt} 100 100)"><g fill="${color}" color="${color}">${shapes[config.shape] ?? shapes.round}</g><g transform="translate(100 ${100 + faceY}) scale(${faceScale}) translate(-100 -100)"><g transform="translate(${shift})" fill="none" stroke="${ink}" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"><g transform="translate(100 97) scale(${eyeSize}) translate(-100 -97)">${eye(100 - gap, false)}${eye(100 + gap, true)}${brow(100 - gap, false)}${brow(100 + gap, true)}</g>${mouth}</g></g></g></g>${activity}</svg>`;
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
 const PET_ANIMATION_NAMES = [
   "idle",
   "running-right",
@@ -483,6 +647,11 @@ const DEFAULT_PET_SIZE = {
   width: petSpriteAtlas.cellWidth,
   height: petSpriteAtlas.cellHeight
 };
+function petLookFrame(dx, dy, deadZone = 12) {
+  if (!Number.isFinite(dx) || !Number.isFinite(dy) || Math.hypot(dx, dy) <= deadZone) return null;
+  const index = (Math.round(Math.atan2(dx, -dy) / (Math.PI / 8)) + 16) % 16;
+  return { row: 9 + Math.floor(index / 8), column: index % 8 };
+}
 const DEFAULT_PET_BOUNDS_PADDING = {
   top: 0,
   right: 0,
@@ -509,7 +678,7 @@ function mergeFrameAnimation(base, override) {
     frameDurations: (override == null ? void 0 : override.frameDurations) && override.frameDurations.length > 0 ? override.frameDurations : base.frameDurations
   };
 }
-function mergePetSpriteAtlas(override) {
+function mergePetSpriteAtlas(override, spriteVersionNumber = 1) {
   var _a;
   const animations = {};
   for (const name of PET_ANIMATION_NAMES) {
@@ -520,7 +689,7 @@ function mergePetSpriteAtlas(override) {
   }
   return {
     columns: (override == null ? void 0 : override.columns) ?? petSpriteAtlas.columns,
-    rows: (override == null ? void 0 : override.rows) ?? petSpriteAtlas.rows,
+    rows: (override == null ? void 0 : override.rows) ?? (spriteVersionNumber === 2 ? 11 : petSpriteAtlas.rows),
     cellWidth: (override == null ? void 0 : override.cellWidth) ?? petSpriteAtlas.cellWidth,
     cellHeight: (override == null ? void 0 : override.cellHeight) ?? petSpriteAtlas.cellHeight,
     animations
@@ -569,7 +738,7 @@ function resolvePetCharacter(character) {
   return {
     kind: "atlas",
     src: character.src,
-    atlas: mergePetSpriteAtlas(character.atlas)
+    atlas: mergePetSpriteAtlas(character.atlas, character.spriteVersionNumber)
   };
 }
 function normalizeBoundsPadding(value) {
@@ -942,6 +1111,7 @@ function countFileChangeLines(report) {
   return { status: "ready", added: m - previous[m], removed: n - previous[m] };
 }
 export {
+  CHATKIT_ASSISTANT_CUSTOMIZE_EFFECT,
   CHATKIT_TASK_SUMMARY_OPEN_RESOURCE_EFFECT,
   CHAT_EVENT_TYPE_FOLLOW_UP_CONSUMED,
   ChatMessageEventTypeEnum,
@@ -964,6 +1134,8 @@ export {
   clampPetPosition,
   countFileChangeLines,
   createResourceCardContent,
+  customCharacterSvg,
+  defaultCharacterConfig,
   fileChangeRangeKey,
   getFileActivityContribution,
   getLegacyFileActivityContribution,
@@ -1001,10 +1173,12 @@ export {
   normalizePetOptions,
   normalizeRequestLanguage,
   normalizeThreadReference,
+  parseAssistantAppearance,
   parseFileActivityContent,
   parseFileChangeReport,
   parseResourceCard,
   parseResourceCardContent,
+  petLookFrame,
   petSpriteAtlas,
   projectMessageFileActivity,
   resolveLocalizedText,