@starcried/starlite-core 0.1.0-alpha.2 → 0.1.0

package/README.en.md

@@ -0,0 +1,45 @@
+# @starcried/starlite-core
+
+[简体中文](README.md) · English
+
+Format-neutral playback, lifecycle, dialogue, and host controls for StarLite. This package imports neither Three.js nor Inochi2D WASM. Usually install a backend; it installs core automatically.
+
+```sh
+npm install @starcried/starlite-core
+```
+
+## Shared contracts
+
+`ModelController` provides `pause`, `resume`, `getAnimations`, `playAnimation`, `stopAnimation`, `resetCamera`, and `destroy`. Playback resolves as `completed`, `interrupted`, or `stopped`; loops resolve when interrupted or stopped. `ModelMountSlot` cancels replaced loads and destroys late instances. Backend-specific bones, tracks, and parameters stay in their backend.
+
+`DialogueScheduler` handles entrance, occasional interaction, and clicks. `DialogueBubble` provides plain text, ARIA announcements, placement, expiry, and cleanup. Both backends share these components and styling. A host can use bubbles without a model or motion; VRM dialogue can omit `animation` and specify only `lines`.
+
+Optional controller methods include `setDisplaySize`, `setFrameRate`, `setPointerEnabled`, `setBubblesVisible`, and `setPerformanceVisible`. These do not remount the model; hiding bubbles does not stop scheduled motions.
+
+`setDialogueContext(context | null)` temporarily replaces or merges a host library. Context contains `id`, `lines`, optional `animation`, `triggers`, `mode`, and `order`. Sequential click and occasional events share progress. Restoring `null` returns to the original library without remounting or entrance replay. Identical context updates preserve progress.
+
+## Shared settings menu
+
+`QuickSettingsMenu` receives `locale: "en" | "zh-CN"`, tabs, toggles, ranges, selects, and action callbacks. The host owns model hit testing and persistence. `open(x,y)` uses viewport coordinates; `update(options)` preserves selected tab and stable menu position; `close()` and `destroy()` clean up. Observe `starlite-menu-change` through `element` to synchronize a native input region.
+
+`resolveLocale(hostLanguage)` maps Chinese tags to `zh-CN`, other nonempty tags to `en`, and absent input to `zh-CN`. Locale affects built-in menu labels and errors only; caller-provided labels and dialogue remain untouched.
+
+## Motion-bound dialogue
+
+```js
+dialogue: {
+  click: {
+    animations: ["Wave", "Nod"],
+    linesByAnimation: {
+      Wave: ["Hello!", "Nice to see you."],
+      Nod: ["I'm here.", "Go ahead."]
+    }
+  }
+}
+```
+
+Each event chooses a motion, then a matching sentence. Names match exactly and are case-sensitive. Pools accept 1–20 unique names; `linesByAnimation` must cover the full pool and contain no unrelated names. Use `lines` for a shared sentence library.
+
+[Configuration](https://github.com/StarCried/starlite/blob/main/docs/configuration.en.md) · [VRM backend](https://github.com/StarCried/starlite/blob/main/packages/vrm/README.en.md)
+
+BSD-2-Clause. No model artwork is included.

package/README.md

@@ -1,11 +1,13 @@
 # @starcried/starlite-core
 
+简体中文 · [English](README.en.md)
+
 StarLite 的公共播放契约、生命周期和气泡组件。该包不导入 Three.js 或 Inochi2D WASM；宿主先选择后端，再加载对应运行时。
 
 在 Node.js 22.12+ 项目中安装 alpha 版本：
 
 ```sh
-npm install @starcried/starlite-core@alpha
+npm install @starcried/starlite-core
 ```
 
 通常直接安装所需后端，它会自动安装本包。
@@ -18,6 +20,12 @@ npm install @starcried/starlite-core@alpha
 
 `DialogueScheduler` 管理首次入场、偶发小动作和点击回应；`DialogueBubble` 管理纯文本、ARIA 状态提示、边缘位置、过期和清理。两个后端共用该组件与样式。气泡可由宿主独立调用，无需模型或动作；VRM 的声明式场景也可省略 `animation`，仅配置 `lines` 显示句子，不打断待机。
 
+支持热更新的后端还可提供 `setDisplaySize(width, height)`、`setFrameRate(30 | 60 | "display")`、`setPointerEnabled(boolean)`、`setBubblesVisible(boolean)` 与 `setPerformanceVisible(boolean)`。这些操作不替换模型或重播动作；隐藏气泡只影响文字显示。
+
+`setDialogueContext(context | null)` 可临时切换宿主句库；`null` 恢复原句库，不重载模型或重播首次入场。`DialogueContext` 包含 `id`、`lines`、可选 `animation`、`triggers: ["click", "idle"]`、`mode: "replace" | "merge"` 和 `order: "sequential" | "random"`。顺序模式下点击与偶发共用进度，每次触发下一条；相同内容与标识的刷新不重置进度。合并模式先加入上下文句子，再保留全局句子原有的动作绑定。动作名称必须已在模型中加载；省略动作可只显示文字。切换时只清理旧文字，当前动作自然结束；暂停、隐藏及访客的气泡开关保持不变。
+
+`QuickSettingsMenu` 是宿主共用的轻量 DOM 设置卡片。宿主提供标签页、开关、范围、选项与动作回调，并负责实际模型命中检测和偏好持久化；`open(x, y)` 使用视口坐标，`update(options)` 保留当前标签页与控件，`close()` / `destroy()` 清理可见和交互状态。通过 `element` 与 `starlite-menu-change` 事件可同步原生窗口交互区域。
+
 ## 语句与动作绑定
 
 ```ts

package/dist/bubble.d.ts

@@ -1,9 +1,14 @@
 import type { DialogueAction } from "./dialogue.js";
+/** Stable model top in host-local CSS pixels, independent of canvas padding/DPR. */
+export interface ModelBubbleAnchor {
+    x: number;
+    y: number;
+}
 /** Plain-text, accessible dialogue presentation shared by every renderer. */
 export declare class DialogueBubble {
     #private;
     readonly element: HTMLDivElement;
-    constructor(host: HTMLElement);
+    constructor(host: HTMLElement, anchor?: () => ModelBubbleAnchor | undefined);
     show(action: DialogueAction, timestamp: number, withoutFrames?: boolean): void;
     update(timestamp: number): void;
     hide(): void;

package/dist/bubble.js

@@ -2,10 +2,12 @@
 export class DialogueBubble {
     element;
     #host;
+    #anchor;
     #until = 0;
     #timeout;
-    constructor(host) {
+    constructor(host, anchor) {
         this.#host = host;
+        this.#anchor = anchor;
         this.element = document.createElement("div");
         this.element.className = "model-widget__bubble";
         this.element.hidden = true;
@@ -47,8 +49,21 @@ export class DialogueBubble {
             return;
         const host = this.#host.getBoundingClientRect(), bubble = this.element.getBoundingClientRect();
         const width = Math.max(1, document.documentElement.clientWidth || window.innerWidth);
-        const margin = 12, centered = host.left + host.width / 2 - bubble.width / 2;
-        this.element.dataset.modelPlacement = host.top >= bubble.height + margin * 2 ? "above" : "below";
+        const candidate = this.#anchor?.();
+        const anchor = candidate && Number.isFinite(candidate.x) && Number.isFinite(candidate.y) ? candidate : undefined;
+        const margin = 12, centered = host.left + (anchor?.x ?? host.width / 2) - bubble.width / 2;
+        const above = host.top + (anchor?.y ?? 0) >= bubble.height + margin * 2;
+        this.element.dataset.modelPlacement = above ? "above" : "below";
+        if (anchor) {
+            const height = Math.max(1, document.documentElement.clientHeight || window.innerHeight);
+            const preferredTop = above ? host.top + anchor.y - margin - bubble.height : host.top + host.height + margin;
+            const top = Math.max(margin, Math.min(Math.max(margin, height - bubble.height - margin), preferredTop));
+            Object.assign(this.element.style, { left: `${anchor.x}px`, top: `${top - host.top}px`, bottom: "auto" });
+        }
+        else {
+            for (const property of ["left", "top", "bottom"])
+                this.element.style.removeProperty(property);
+        }
         const left = Math.max(margin, Math.min(Math.max(margin, width - bubble.width - margin), centered));
         this.element.style.setProperty("--model-bubble-shift-x", `${Math.round(left - centered)}px`);
     }

package/dist/dialogue.d.ts

@@ -11,6 +11,16 @@ export interface DialogueSceneConfig {
 export interface ResolvedDialogueScene extends DialogueSceneConfig {
     durationMs: number;
 }
+export interface DialogueContext {
+    id: string;
+    lines: readonly string[];
+    animation?: string;
+    triggers: readonly ("click" | "idle")[];
+    mode: "replace" | "merge";
+    order: "sequential" | "random";
+}
+/** Copy bounded data before a host replaces an active dialogue context. */
+export declare function resolveDialogueContext(input: unknown): DialogueContext;
 /** Validate and copy plain-text libraries at the backend configuration boundary. */
 export declare function resolveDialogueSentences(input: Pick<DialogueSceneConfig, "lines" | "linesByAnimation">, animations: readonly string[], field: string): Pick<DialogueSceneConfig, "lines" | "linesByAnimation">;
 export interface DialogueSchedule {
@@ -40,6 +50,8 @@ export declare class DialogueScheduler {
     #private;
     constructor(config: DialogueSchedule, random: () => number);
     start(timestampMs: number, immediateEnter?: boolean): void;
+    /** Preserve the model and first entrance while replacing host-owned text. */
+    setContext(input: DialogueContext | null, timestampMs: number): boolean;
     poll(timestampMs: number, foregroundActive: boolean): DialogueAction | undefined;
     triggerClick(timestampMs: number): DialogueAction | undefined;
     /** Postpones natural speech after visibility changes or direct interaction. */

package/dist/dialogue.js

@@ -1,3 +1,26 @@
+/** Copy bounded data before a host replaces an active dialogue context. */
+export function resolveDialogueContext(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("dialogue context must be an object");
+    const value = input;
+    if (Object.keys(value).some(key => !["id", "lines", "animation", "triggers", "mode", "order"].includes(key)))
+        throw new Error("dialogue context has an unknown field");
+    const text = (item, maximum, field) => {
+        if (typeof item !== "string" || !item.trim() || new TextEncoder().encode(item.trim()).byteLength > maximum)
+            throw new Error(`dialogue context ${field} is invalid`);
+        return item.trim();
+    };
+    const id = text(value.id, 2048, "id");
+    const lines = resolveDialogueSentences({ lines: value.lines }, [], "dialogue context").lines;
+    if (!Array.isArray(value.triggers) || !value.triggers.length || value.triggers.length > 2 || new Set(value.triggers).size !== value.triggers.length || value.triggers.some(trigger => trigger !== "click" && trigger !== "idle"))
+        throw new Error("dialogue context triggers are invalid");
+    if (value.mode !== "replace" && value.mode !== "merge")
+        throw new Error("dialogue context mode is invalid");
+    if (value.order !== "sequential" && value.order !== "random")
+        throw new Error("dialogue context order is invalid");
+    return { id, lines, ...(value.animation !== undefined ? { animation: text(value.animation, 1024, "animation") } : {}),
+        triggers: ["click", "idle"].filter(trigger => value.triggers.includes(trigger)), mode: value.mode, order: value.order };
+}
 /** Validate and copy plain-text libraries at the backend configuration boundary. */
 export function resolveDialogueSentences(input, animations, field) {
     const resolve = (value, path) => {
@@ -47,6 +70,10 @@ export class DialogueScheduler {
     #started = false;
     #enterDueAt;
     #nextIdleAt;
+    #context = null;
+    #contextSignature = "null";
+    #contextEntries = [];
+    #contextCursor = 0;
     constructor(config, random) {
         this.#config = config;
         this.#random = random;
@@ -62,6 +89,25 @@ export class DialogueScheduler {
         }
         this.#scheduleIdle(timestampMs);
     }
+    /** Preserve the model and first entrance while replacing host-owned text. */
+    setContext(input, timestampMs) {
+        if (!Number.isFinite(timestampMs))
+            throw new Error("dialogue context timestamp is invalid");
+        const context = input === null ? null : resolveDialogueContext(input);
+        const signature = JSON.stringify(context);
+        if (signature === this.#contextSignature)
+            return false;
+        this.#context = context;
+        this.#contextSignature = signature;
+        this.#contextCursor = 0;
+        this.#contextEntries = context ? [
+            ...context.lines.map(line => ({ line, ...(context.animation !== undefined ? { animation: context.animation } : {}), triggers: context.triggers })),
+            ...(context.mode === "merge" ? context.triggers.flatMap(scene => this.#entries(scene)) : []),
+        ] : [];
+        if (this.#started)
+            this.#scheduleIdle(timestampMs);
+        return true;
+    }
     poll(timestampMs, foregroundActive) {
         if (!this.#started || foregroundActive) {
             return undefined;
@@ -74,10 +120,10 @@ export class DialogueScheduler {
             this.#scheduleIdle(timestampMs + action.durationMs);
             return action;
         }
-        if (this.#config.idle &&
+        if ((this.#config.idle || this.#context?.triggers.includes("idle")) &&
             this.#nextIdleAt !== undefined &&
             timestampMs >= this.#nextIdleAt) {
-            const action = this.#action("idle", this.#config.idle);
+            const action = this.#contextAction("idle") ?? this.#action("idle", this.#config.idle);
             this.#scheduleIdle(timestampMs + action.durationMs);
             return action;
         }
@@ -85,10 +131,10 @@ export class DialogueScheduler {
     }
     triggerClick(timestampMs) {
         this.deferIdle(timestampMs);
-        if (!this.#config.click) {
+        if (!this.#config.click && !this.#context?.triggers.includes("click")) {
             return undefined;
         }
-        const action = this.#action("click", this.#config.click);
+        const action = this.#contextAction("click") ?? this.#action("click", this.#config.click);
         this.#scheduleIdle(timestampMs + action.durationMs);
         return action;
     }
@@ -98,6 +144,40 @@ export class DialogueScheduler {
             this.#scheduleIdle(timestampMs);
         }
     }
+    #entries(scene) {
+        const config = this.#config[scene];
+        if (!config)
+            return [];
+        const animations = config.animations?.length ? config.animations : config.animation ? [config.animation] : [];
+        if (config.linesByAnimation)
+            return animations.flatMap(animation => (config.linesByAnimation[animation] ?? []).map(line => ({ line, animation, durationMs: config.durationMs, triggers: [scene] })));
+        return (animations.length ? animations : [undefined]).flatMap(animation => (config.lines ?? []).map(line => ({ line, ...(animation !== undefined ? { animation } : {}), durationMs: config.durationMs, triggers: [scene] })));
+    }
+    #contextAction(scene) {
+        const context = this.#context;
+        if (!context?.triggers.includes(scene))
+            return undefined;
+        let entry;
+        if (context.order === "random") {
+            const eligible = this.#contextEntries.filter(item => item.triggers.includes(scene));
+            entry = eligible[Math.floor(this.#unitRandom() * eligible.length)];
+        }
+        else {
+            for (let offset = 0; offset < this.#contextEntries.length; offset++) {
+                const index = (this.#contextCursor + offset) % this.#contextEntries.length;
+                const item = this.#contextEntries[index];
+                if (!item.triggers.includes(scene))
+                    continue;
+                entry = item;
+                this.#contextCursor = (index + 1) % this.#contextEntries.length;
+                break;
+            }
+        }
+        if (!entry)
+            return undefined;
+        const config = this.#config[scene];
+        return { scene, line: entry.line, ...(entry.animation !== undefined ? { animation: entry.animation } : {}), durationMs: entry.durationMs ?? (config ? config.durationMs : 4000) };
+    }
     #action(scene, config) {
         // Preserve the historical random draw order for shared sentence libraries.
         // Bound libraries choose the animation first, then only its own sentences.
@@ -121,12 +201,12 @@ export class DialogueScheduler {
             return;
         }
         const idle = this.#config.idle;
-        if (!idle) {
+        if (!idle && !this.#context?.triggers.includes("idle")) {
             this.#nextIdleAt = undefined;
             return;
         }
-        const interval = idle.intervalMinMs +
-            (idle.intervalMaxMs - idle.intervalMinMs) * this.#unitRandom();
+        const interval = (idle ? idle.intervalMinMs : 30000) +
+            ((idle ? idle.intervalMaxMs : 60000) - (idle ? idle.intervalMinMs : 30000)) * this.#unitRandom();
         this.#nextIdleAt = timestampMs + interval;
     }
     #unitRandom() {

package/dist/environment-lighting.d.ts

@@ -0,0 +1,9 @@
+/** A local RGB lighting hint. Hosts own colour acquisition and permission. */
+export interface EnvironmentLighting {
+    color: string;
+    /** 0 restores the original lighting; 1 is the default, 2 exaggerates the effect. */
+    strength?: number;
+    /** Overall light-energy target .8–1.1, blended/amplified by strength. Omit to infer from RGB. */
+    brightness?: number;
+}
+export declare function validateEnvironmentLighting(input: unknown): asserts input is EnvironmentLighting;

package/dist/environment-lighting.js

@@ -0,0 +1,11 @@
+export function validateEnvironmentLighting(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("environmentLighting must be an object");
+    const value = input;
+    if (Object.keys(value).some(key => key !== "color" && key !== "strength" && key !== "brightness") || typeof value.color !== "string" || !/^#[0-9a-f]{6}$/iu.test(value.color))
+        throw new Error("environmentLighting.color must be #RRGGBB");
+    if (value.strength !== undefined && (typeof value.strength !== "number" || !Number.isFinite(value.strength) || value.strength < 0 || value.strength > 2))
+        throw new Error("environmentLighting.strength must be between 0 and 2");
+    if (value.brightness !== undefined && (typeof value.brightness !== "number" || !Number.isFinite(value.brightness) || value.brightness < .8 || value.brightness > 1.1))
+        throw new Error("environmentLighting.brightness must be between 0.8 and 1.1");
+}

package/dist/hit-mask.d.ts

@@ -16,7 +16,7 @@ export declare function packAlphaMask(rgba: Uint8ClampedArray): Uint8Array;
 export declare class RenderedHitMask {
     #private;
     setListener(listener?: ModelHitMaskListener): void;
-    capture(canvas: HTMLCanvasElement, timestamp: number): void;
+    capture(canvas: HTMLCanvasElement, timestamp: number, force?: boolean): void;
     clear(): void;
     destroy(): void;
 }

package/dist/hit-mask.js

@@ -19,8 +19,8 @@ export class RenderedHitMask {
         if (!listener)
             this.#surface = undefined;
     }
-    capture(canvas, timestamp) {
-        if (!this.#listener || timestamp - this.#lastTime < 50)
+    capture(canvas, timestamp, force = false) {
+        if (!this.#listener || (!force && timestamp - this.#lastTime < 50))
             return;
         this.#lastTime = timestamp;
         const rect = canvas.getBoundingClientRect();

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { resolveLocale, validateLocale, type StarLiteLocale } from "./locale.js";
 export type ModelBackend = "inochi2d" | "vrm";
 export type WidgetStatus = "disabled" | "loading" | "running" | "paused" | "fallback" | "destroyed";
 export type AnimationPlaybackResult = "completed" | "interrupted" | "stopped";
@@ -10,6 +11,10 @@ export interface ModelAnimationInfo {
     durationMs: number;
 }
 import type { ModelHitMaskListener } from "./hit-mask.js";
+import type { DialogueContext } from "./dialogue.js";
+import type { EnvironmentLighting } from "./environment-lighting.js";
+export { validateEnvironmentLighting, type EnvironmentLighting } from "./environment-lighting.js";
+import type { ModelBubbleAnchor } from "./bubble.js";
 export { RenderedHitMask, packAlphaMask, type ModelHitMask, type ModelHitMaskListener } from "./hit-mask.js";
 export interface ModelController {
     readonly status: WidgetStatus;
@@ -19,10 +24,28 @@ export interface ModelController {
     playAnimation(name: string, options?: AnimationPlaybackOptions): Promise<AnimationPlaybackResult>;
     stopAnimation(): void;
     resetCamera(): void;
+    /** Stable reference-pose top, in host-local CSS pixels; no canvas padding/DPR. */
+    getBubbleAnchor?(): ModelBubbleAnchor | undefined;
     observeInteractionMask(listener?: ModelHitMaskListener): void;
+    /** Refresh current alpha coverage after a host resize, including while paused. */
+    refreshInteractionMask?(): void;
     setPointerPosition(clientX: number, clientY: number): void;
     /** Optional host-movement capability. Coordinates are CSS pixels, local only. */
     setHostPosition?(x: number, y: number): void;
+    /** Toggle local model metrics without remounting; disabled by default. */
+    setPerformanceVisible?(visible: boolean): void;
+    /** Resize the logical portrait in CSS pixels without resetting playback. */
+    setDisplaySize?(width: number, height: number): void;
+    /** Change the rendering cap without remounting or advancing hidden time. */
+    setFrameRate?(fps: number | "display"): void;
+    /** Toggle pointer tracking; disabling eases the gaze back to neutral. */
+    setPointerEnabled?(enabled: boolean): void;
+    /** Hide dialogue text independently of its scheduled animations. */
+    setBubblesVisible?(visible: boolean): void;
+    /** Replace bounded host dialogue without remounting or replaying entrance. */
+    setDialogueContext?(context: DialogueContext | null): void;
+    /** Optional ambient-light hint. Null restores the original lighting. */
+    setEnvironmentLighting?(lighting: EnvironmentLighting | null): void;
     destroy(): void;
 }
 export interface MountOptions {
@@ -42,6 +65,8 @@ export declare function mountModelWidget<C extends {
 }>>, options?: MountOptions): Promise<ModelController>;
 /** Streaming limit applies to decoded response bytes, not just Content-Length. */
 export declare function fetchBounded(url: string, maximumBytes: number, signal: AbortSignal): Promise<ArrayBuffer>;
-export { DialogueScheduler, resolveDialogueSentences, type DialogueAction, type DialogueSchedule, type DialogueSceneConfig, type ResolvedDialogueScene } from "./dialogue.js";
-export { DialogueBubble } from "./bubble.js";
+export { DialogueScheduler, resolveDialogueSentences, resolveDialogueContext, type DialogueContext, type DialogueAction, type DialogueSchedule, type DialogueSceneConfig, type ResolvedDialogueScene } from "./dialogue.js";
+export { DialogueBubble, type ModelBubbleAnchor } from "./bubble.js";
 export { observePassThroughClicks } from "./pass-through.js";
+export { PerformanceOverlay, FrameSamples, validatePerformanceConfig, type PerformanceConfig, type PerformanceFrameDetails } from "./performance.js";
+export { QuickSettingsMenu, type QuickSettingsOptions, type QuickSettingItem, type QuickSettingCallback } from "./quick-settings.js";

package/dist/index.js

@@ -1,3 +1,5 @@
+export { resolveLocale, validateLocale } from "./locale.js";
+export { validateEnvironmentLighting } from "./environment-lighting.js";
 export { RenderedHitMask, packAlphaMask } from "./hit-mask.js";
 /** Own one mount, including asynchronous work which outlives a replacement. */
 export class ModelMountSlot {
@@ -80,6 +82,8 @@ export async function fetchBounded(url, maximumBytes, signal) {
     }
     return bytes.buffer;
 }
-export { DialogueScheduler, resolveDialogueSentences } from "./dialogue.js";
+export { DialogueScheduler, resolveDialogueSentences, resolveDialogueContext } from "./dialogue.js";
 export { DialogueBubble } from "./bubble.js";
 export { observePassThroughClicks } from "./pass-through.js";
+export { PerformanceOverlay, FrameSamples, validatePerformanceConfig } from "./performance.js";
+export { QuickSettingsMenu } from "./quick-settings.js";

package/dist/locale.d.ts

@@ -0,0 +1,5 @@
+/** Supported interface languages; user content is never translated. */
+export type StarLiteLocale = "zh-CN" | "en";
+/** Accept host language tags (en-US, zh-TW, ...); unsupported languages use English. */
+export declare function resolveLocale(language?: unknown): StarLiteLocale;
+export declare function validateLocale(value: unknown): void;

package/dist/locale.js

@@ -0,0 +1,12 @@
+/** Accept host language tags (en-US, zh-TW, ...); unsupported languages use English. */
+export function resolveLocale(language) {
+    const value = Array.isArray(language) ? language[0] : language;
+    if (typeof value !== "string" || !value.trim())
+        return "zh-CN";
+    return /^zh(?:[-_]|$)/i.test(value.trim()) ? "zh-CN" : "en";
+}
+export function validateLocale(value) {
+    if (value !== undefined && value !== "zh-CN" && value !== "en") {
+        throw new Error("locale must be zh-CN or en");
+    }
+}

package/dist/pass-through.js

@@ -4,6 +4,9 @@ export function observePassThroughClicks(surface, onClick) {
     let down;
     let ready;
     const inside = (event) => {
+        // Local companion controls are not clicks on the model beneath them.
+        if (event.composedPath().some(target => target instanceof Element && target.matches("[data-starlite-quick-settings],[data-starlite-widget-restore]")))
+            return false;
         const rect = surface.getBoundingClientRect();
         return rect.width > 0 && rect.height > 0
             && event.clientX >= rect.left && event.clientX < rect.right

package/dist/performance.d.ts

@@ -0,0 +1,32 @@
+/** The overlay is opt-in; mounting a model with the default config creates none. */
+export interface PerformanceConfig {
+    show?: boolean;
+}
+export type PerformanceStatus = "loading" | "running" | "paused" | "fallback" | "disabled" | "destroyed";
+export interface PerformanceFrameDetails {
+    calls?: number;
+    triangles?: number;
+}
+export declare function validatePerformanceConfig(value: unknown): void;
+/** Bounded numeric history; recording does not shift an array every frame. */
+export declare class FrameSamples {
+    #private;
+    constructor(capacity?: number);
+    add(value: number): void;
+    reset(): void;
+    values(): number[];
+}
+/**
+ * Local-only, non-interactive overlay. The host calls recordFrame after an
+ * actual scheduled render; RAF callbacks skipped by an FPS cap do not count.
+ * CPU cost is model update + WebGL submission, not GPU execution or page cost.
+ * No polling, timers, memory probes or WebGL readbacks are introduced here.
+ */
+export declare class PerformanceOverlay {
+    #private;
+    readonly element: HTMLOutputElement;
+    constructor(host: HTMLElement);
+    setStatus(status: PerformanceStatus): void;
+    recordFrame(timestampMs: number, cpuMs: number, details?: PerformanceFrameDetails): void;
+    destroy(): void;
+}

package/dist/performance.js

@@ -0,0 +1,103 @@
+export function validatePerformanceConfig(value) {
+    if (value === undefined)
+        return;
+    if (!value || typeof value !== "object" || Array.isArray(value)
+        || Object.keys(value).some(key => key !== "show")
+        || ("show" in value && value.show !== undefined && typeof value.show !== "boolean")) {
+        throw new Error("performance must be an object with an optional boolean show");
+    }
+}
+/** Bounded numeric history; recording does not shift an array every frame. */
+export class FrameSamples {
+    #values;
+    #next = 0;
+    #size = 0;
+    constructor(capacity = 240) {
+        if (!Number.isSafeInteger(capacity) || capacity < 1)
+            throw new Error("invalid sample capacity");
+        this.#values = new Float64Array(capacity);
+    }
+    add(value) {
+        if (!Number.isFinite(value) || value < 0)
+            return;
+        this.#values[this.#next] = value;
+        this.#next = (this.#next + 1) % this.#values.length;
+        this.#size = Math.min(this.#size + 1, this.#values.length);
+    }
+    reset() { this.#next = 0; this.#size = 0; }
+    values() {
+        return Array.from({ length: this.#size }, (_, i) => this.#values[(this.#next - this.#size + i + this.#values.length) % this.#values.length]);
+    }
+}
+/**
+ * Local-only, non-interactive overlay. The host calls recordFrame after an
+ * actual scheduled render; RAF callbacks skipped by an FPS cap do not count.
+ * CPU cost is model update + WebGL submission, not GPU execution or page cost.
+ * No polling, timers, memory probes or WebGL readbacks are introduced here.
+ */
+export class PerformanceOverlay {
+    element;
+    #intervals = new FrameSamples();
+    #cpu = new FrameSamples();
+    #previous;
+    #lastPaint;
+    #status = "loading";
+    #destroyed = false;
+    constructor(host) {
+        this.element = document.createElement("output");
+        this.element.className = "model-widget__performance";
+        this.element.setAttribute("data-model-performance", "");
+        this.element.setAttribute("aria-label", "StarLite model performance");
+        this.element.setAttribute("aria-live", "off");
+        this.element.title = "Rendered FPS and frame-interval p95; CPU p95 is the wall time of model update and WebGL submission, including any driver waits, not measured GPU execution or CPU utilization. The latest 240 frames are sampled. Pausing resets measurements.";
+        // Use the logical host, not the expanded canvas: its negative offsets must
+        // not move the panel offscreen or alter the alpha-based interaction mask.
+        Object.assign(this.element.style, {
+            position: "absolute", left: "8px", bottom: "8px", zIndex: "2",
+            maxWidth: "calc(100% - 16px)", boxSizing: "border-box", padding: "6px 8px",
+            borderRadius: "6px", background: "rgba(15, 23, 42, .86)", color: "#f1f5f9",
+            font: "11px/1.5 ui-monospace, SFMono-Regular, Consolas, monospace",
+            whiteSpace: "pre-line", overflowWrap: "anywhere", pointerEvents: "none",
+            userSelect: "none", textAlign: "left",
+        });
+        host.append(this.element);
+        this.#paintStatus();
+    }
+    setStatus(status) {
+        if (this.#destroyed || status === this.#status)
+            return;
+        this.#status = status;
+        this.#intervals.reset();
+        this.#cpu.reset();
+        this.#previous = undefined;
+        this.#lastPaint = undefined;
+        this.#paintStatus();
+    }
+    recordFrame(timestampMs, cpuMs, details = {}) {
+        if (this.#destroyed || this.#status !== "running" || !Number.isFinite(timestampMs))
+            return;
+        if (this.#previous !== undefined && timestampMs > this.#previous)
+            this.#intervals.add(timestampMs - this.#previous);
+        this.#previous = timestampMs;
+        this.#cpu.add(cpuMs);
+        if (this.#lastPaint !== undefined && timestampMs - this.#lastPaint < 500)
+            return;
+        this.#lastPaint = timestampMs;
+        const intervals = this.#intervals.values(), cpu = this.#cpu.values();
+        const sum = intervals.reduce((total, value) => total + value, 0);
+        const fps = sum > 0 ? `${(1000 * intervals.length / sum).toFixed(1)} FPS` : "FPS warming up";
+        const p95 = (values) => values.length ? values.sort((a, b) => a - b)[Math.ceil(values.length * .95) - 1].toFixed(1) : "—";
+        const lines = [fps, `Frame p95 ${p95(intervals)} ms`, `CPU p95 ${p95(cpu)} ms`];
+        if (Number.isFinite(details.calls) && Number.isFinite(details.triangles)) {
+            lines.push(`${details.calls} calls · ${details.triangles.toLocaleString("en-US")} tris`);
+        }
+        this.element.textContent = lines.join("\n");
+        this.element.dataset.modelPerformanceStatus = this.#status;
+    }
+    destroy() { if (this.#destroyed)
+        return; this.#destroyed = true; this.element.remove(); }
+    #paintStatus() {
+        this.element.textContent = `StarLite · ${this.#status}`;
+        this.element.dataset.modelPerformanceStatus = this.#status;
+    }
+}

package/dist/quick-settings.d.ts

@@ -0,0 +1,53 @@
+import { type StarLiteLocale } from "./locale.js";
+export type QuickSettingCallback<T> = (value: T) => void | Promise<void>;
+interface QuickSettingBase {
+    id: string;
+    label: string;
+    description?: string;
+    disabled?: boolean;
+}
+export type QuickSettingItem = (QuickSettingBase & {
+    kind: "toggle";
+    value: boolean;
+    onChange: QuickSettingCallback<boolean>;
+}) | (QuickSettingBase & {
+    kind: "range";
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    formatValue?: (value: number) => string;
+    onChange: QuickSettingCallback<number>;
+}) | (QuickSettingBase & {
+    kind: "select";
+    value: string;
+    options: readonly {
+        value: string;
+        label: string;
+    }[];
+    onChange: QuickSettingCallback<string>;
+}) | (QuickSettingBase & {
+    kind: "action";
+    onAction: () => void | Promise<void>;
+});
+export interface QuickSettingsOptions {
+    locale?: StarLiteLocale;
+    title?: string;
+    tabs: readonly {
+        id: string;
+        label: string;
+        items: readonly QuickSettingItem[];
+    }[];
+}
+/** Shared host controls only; no renderer, model, or application dependencies. */
+export declare class QuickSettingsMenu {
+    #private;
+    readonly element: HTMLElement;
+    constructor(options: QuickSettingsOptions);
+    get isOpen(): boolean;
+    open(clientX: number, clientY: number): void;
+    close(): void;
+    update(options: QuickSettingsOptions): void;
+    destroy(): void;
+}
+export {};

package/dist/quick-settings.js

@@ -0,0 +1,510 @@
+import { resolveLocale, validateLocale } from "./locale.js";
+const STYLE = `
+[data-starlite-menu]{position:fixed;box-sizing:border-box;width:300px;max-width:calc(100vw - 16px);max-height:calc(100vh - 16px);overflow:auto;padding:14px;border:1px solid #9ba9c740;border-radius:16px;background:#1c2130f5;color:#f0f3ff;box-shadow:0 14px 48px #0005;font:14px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif;z-index:2147483647;pointer-events:auto;user-select:none;backdrop-filter:blur(16px);color-scheme:dark;overscroll-behavior:contain}
+[data-starlite-menu][hidden]{display:none!important}
+[data-starlite-menu] *{box-sizing:border-box}
+[data-starlite-menu] button,[data-starlite-menu] input{font:inherit;accent-color:#9faeff}
+[data-starlite-menu] button{color:inherit;background:#ffffff09;border:1px solid #b4bfd528;border-radius:8px;padding:7px 9px}
+[data-starlite-menu] button{cursor:pointer}
+[data-starlite-menu] button:hover{background:#a7b3ff24}
+[data-starlite-menu] :focus-visible{outline:2px solid #b3bfff;outline-offset:2px}
+[data-starlite-menu] :disabled{opacity:.45;cursor:default}
+[data-starlite-menu] .starlite-menu__header{display:flex;align-items:center;justify-content:space-between;margin-bottom:10px;font-weight:650;letter-spacing:.02em}
+[data-starlite-menu] .starlite-menu__close{border:0;background:transparent;padding:2px 7px;font-size:20px;line-height:1.25}
+[data-starlite-menu] [role=tablist]{display:flex;gap:4px;background:#0002;border-radius:9px;padding:3px;margin-bottom:8px}
+[data-starlite-menu] [role=tab]{flex:1;border:0;background:transparent;padding:5px}
+[data-starlite-menu] [role=tab][aria-selected=true]{background:#a7b3ff25;color:#dbe1ff}
+[data-starlite-menu] .starlite-menu__row{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:10px 2px;border-bottom:1px solid #b4bfd514;min-height:44px}
+[data-starlite-menu] .starlite-menu__row:last-child{border-bottom:0}
+[data-starlite-menu] .starlite-menu__text{flex:1;min-width:0}
+[data-starlite-menu] .starlite-menu__description{display:block;font-size:12px;color:#b1bbd2;margin-top:2px;font-weight:400}
+[data-starlite-menu] .starlite-menu__toggle{appearance:none;flex:none;width:34px;height:20px;border-radius:12px;background:#69738a;cursor:pointer;position:relative;margin:0}
+[data-starlite-menu] .starlite-menu__toggle:before{content:"";position:absolute;left:3px;top:3px;width:14px;height:14px;border-radius:50%;background:#fff;transition:transform .12s}
+[data-starlite-menu] .starlite-menu__toggle:checked{background:#899cf6}
+[data-starlite-menu] .starlite-menu__toggle:checked:before{transform:translateX(14px)}
+[data-starlite-menu] .starlite-menu__range-row{display:block}
+[data-starlite-menu] .starlite-menu__range-label{display:flex;justify-content:space-between;gap:12px;margin-bottom:8px}
+[data-starlite-menu] input[type=range]{display:block;width:100%;margin:0;cursor:pointer}
+[data-starlite-menu] output{font-variant-numeric:tabular-nums;color:#c8d2ff}
+[data-starlite-menu] .starlite-menu__select-row{display:grid;grid-template-columns:minmax(0,1fr) minmax(90px,150px)}
+[data-starlite-menu] .starlite-menu__select{display:flex;align-items:center;justify-content:space-between;gap:10px;min-width:0;text-align:left;background:#30384f;color:#f0f3ff;border-color:#7d8baa70}
+[data-starlite-menu] .starlite-menu__select:after{content:"⌄";flex:none;color:#c8d2ff;font-size:15px;line-height:1}
+[data-starlite-menu] .starlite-menu__select[aria-expanded=true]{background:#39445f;border-color:#a7b3ff}
+[data-starlite-menu] .starlite-menu__select-value{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+[data-starlite-menu] .starlite-menu__options{grid-column:1/-1;display:flex;flex-direction:column;gap:3px;margin-top:-4px;padding:5px;border:1px solid #7d8baa70;border-radius:10px;background:#20283b;box-shadow:0 5px 15px #0003}
+[data-starlite-menu] .starlite-menu__options[hidden]{display:none!important}
+[data-starlite-menu] .starlite-menu__option{display:flex;justify-content:space-between;gap:12px;width:100%;border:0;border-radius:6px;background:#20283b;color:#f0f3ff;text-align:left;padding:8px 10px}
+[data-starlite-menu] .starlite-menu__option:after{content:"";width:12px;flex:none}
+[data-starlite-menu] .starlite-menu__option[aria-selected=true]{background:#3a476a;color:#fff}
+[data-starlite-menu] .starlite-menu__option[aria-selected=true]:after{content:"✓";color:#c8d2ff}
+[data-starlite-menu] .starlite-menu__option:hover,[data-starlite-menu] .starlite-menu__option[data-active=true]{background:#4a587e;color:#fff}
+[data-starlite-menu] .starlite-menu__action{display:block;width:100%;text-align:left;border:0;background:transparent;padding:8px 2px}
+[data-starlite-menu] .starlite-menu__status{margin:8px 0 0;color:#ffc7c7;font-size:12px}
+@media(prefers-reduced-motion:reduce){[data-starlite-menu] *{transition:none!important}}
+`;
+let instanceId = 0;
+/** Shared host controls only; no renderer, model, or application dependencies. */
+export class QuickSettingsMenu {
+    element = document.createElement("section");
+    #options;
+    #activeTab;
+    #structure = "";
+    #controls = new Map();
+    #selects = new Map();
+    #openSelect;
+    #draggingRanges = new Map();
+    #outputs = new Map();
+    #pending = new Map();
+    #generation = 0;
+    #destroyed = false;
+    #x = 0;
+    #y = 0;
+    #previousFocus;
+    #id = `starlite-menu-${++instanceId}`;
+    #outside = (event) => {
+        if (!this.isOpen)
+            return;
+        const path = event.composedPath();
+        if (!path.includes(this.element))
+            this.close();
+        else if (this.#openSelect) {
+            const select = this.#selects.get(this.#openSelect);
+            if (!path.includes(select.trigger) && !path.includes(select.listbox))
+                this.#closeSelect();
+        }
+    };
+    #key = (event) => { if (this.isOpen && event.key === "Escape") {
+        event.preventDefault();
+        this.close();
+    } };
+    #rangeEnd = (event) => {
+        for (const [id, pointerId] of this.#draggingRanges) {
+            if (pointerId !== event.pointerId)
+                continue;
+            this.#draggingRanges.delete(id);
+            if (!this.#pending.has(id))
+                this.#sync();
+        }
+    };
+    constructor(options) {
+        this.#validate(options);
+        this.#options = options;
+        this.#activeTab = options.tabs[0].id;
+        if (!document.querySelector("style[data-starlite-menu-style]")) {
+            const style = document.createElement("style");
+            style.dataset.starliteMenuStyle = "";
+            style.textContent = STYLE;
+            document.head.append(style);
+        }
+        this.element.dataset.starliteMenu = "";
+        this.element.dataset.starliteQuickSettings = "";
+        this.element.hidden = true;
+        this.element.setAttribute("role", "dialog");
+        this.element.setAttribute("aria-label", options.title ?? "StarLite");
+        this.element.addEventListener("contextmenu", event => event.preventDefault());
+        document.body.append(this.element);
+        document.addEventListener("pointerdown", this.#outside, true);
+        document.addEventListener("keydown", this.#key);
+        document.addEventListener("pointerup", this.#rangeEnd, true);
+        document.addEventListener("pointercancel", this.#rangeEnd, true);
+        this.#render();
+    }
+    get isOpen() { return !this.#destroyed && !this.element.hidden; }
+    open(clientX, clientY) {
+        if (this.#destroyed || !Number.isFinite(clientX) || !Number.isFinite(clientY))
+            return;
+        if (!this.isOpen)
+            this.#previousFocus = document.activeElement instanceof HTMLElement ? document.activeElement : undefined;
+        this.#closeSelect();
+        this.#x = clientX;
+        this.#y = clientY;
+        this.element.hidden = false;
+        this.#position();
+        this.element.querySelector("[role=tab][aria-selected=true]")?.focus({ preventScroll: true });
+        this.element.dispatchEvent(new Event("starlite-menu-change"));
+    }
+    close() {
+        if (!this.isOpen)
+            return;
+        const containedFocus = this.element.contains(document.activeElement);
+        this.#closeSelect();
+        this.#draggingRanges.clear();
+        this.element.hidden = true;
+        if (containedFocus && this.#previousFocus?.isConnected)
+            this.#previousFocus.focus({ preventScroll: true });
+        this.element.dispatchEvent(new Event("starlite-menu-change"));
+    }
+    update(options) {
+        if (this.#destroyed)
+            return;
+        this.#validate(options);
+        this.#options = options;
+        if (!options.tabs.some(tab => tab.id === this.#activeTab))
+            this.#activeTab = options.tabs[0].id;
+        this.#render();
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.close();
+        this.#destroyed = true;
+        this.#generation++;
+        document.removeEventListener("pointerdown", this.#outside, true);
+        document.removeEventListener("keydown", this.#key);
+        document.removeEventListener("pointerup", this.#rangeEnd, true);
+        document.removeEventListener("pointercancel", this.#rangeEnd, true);
+        this.element.remove();
+        this.#controls.clear();
+        this.#outputs.clear();
+        this.#selects.clear();
+    }
+    #validate(options) {
+        validateLocale(options.locale);
+        const ids = new Set();
+        if (!options.tabs.length)
+            throw new Error("quick settings requires a tab");
+        for (const tab of options.tabs) {
+            if (!tab.id || ids.has(`tab:${tab.id}`))
+                throw new Error("quick settings tab IDs must be unique");
+            ids.add(`tab:${tab.id}`);
+            for (const item of tab.items) {
+                if (!item.id || ids.has(item.id))
+                    throw new Error("quick settings item IDs must be unique");
+                ids.add(item.id);
+                if (item.kind === "range" && (![item.value, item.min, item.max, item.step ?? 1].every(Number.isFinite) || item.max <= item.min || (item.step ?? 1) <= 0))
+                    throw new Error("invalid quick settings range");
+            }
+        }
+    }
+    #item(id) { return this.#options.tabs.flatMap(tab => tab.items).find(item => item.id === id); }
+    #render() {
+        const structure = JSON.stringify([this.#activeTab, this.#options.title, this.#options.locale, this.#options.tabs.map(tab => [tab.id, tab.label, tab.items.map(item => [item.id, item.kind, item.label, item.description, item.kind === "select" ? item.options : item.kind === "range" ? [item.min, item.max, item.step] : null])])]);
+        if (structure === this.#structure) {
+            this.#sync();
+            return;
+        }
+        this.#closeSelect();
+        this.#structure = structure;
+        this.#controls.clear();
+        this.#outputs.clear();
+        this.#selects.clear();
+        this.#draggingRanges.clear();
+        this.element.replaceChildren();
+        const header = document.createElement("div");
+        header.className = "starlite-menu__header";
+        const title = document.createElement("span");
+        title.textContent = this.#options.title ?? "StarLite";
+        const close = document.createElement("button");
+        close.type = "button";
+        close.className = "starlite-menu__close";
+        close.textContent = "×";
+        close.setAttribute("aria-label", resolveLocale(this.#options.locale) === "en" ? "Close menu" : "关闭菜单");
+        close.onclick = () => this.close();
+        header.append(title, close);
+        const tabs = document.createElement("div");
+        tabs.setAttribute("role", "tablist");
+        tabs.setAttribute("aria-label", resolveLocale(this.#options.locale) === "en" ? "Settings categories" : "设置分类");
+        for (const [index, tab] of this.#options.tabs.entries()) {
+            const button = document.createElement("button");
+            button.type = "button";
+            button.textContent = tab.label;
+            button.id = `${this.#id}-tab-${index}`;
+            button.setAttribute("role", "tab");
+            button.setAttribute("aria-selected", String(tab.id === this.#activeTab));
+            button.tabIndex = tab.id === this.#activeTab ? 0 : -1;
+            button.setAttribute("aria-controls", `${this.#id}-panel`);
+            button.onclick = () => { this.#activeTab = tab.id; this.#render(); this.element.querySelector("[role=tab][aria-selected=true]")?.focus({ preventScroll: true }); };
+            button.onkeydown = event => {
+                if (!["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key))
+                    return;
+                event.preventDefault();
+                const count = this.#options.tabs.length;
+                const next = event.key === "Home" ? 0 : event.key === "End" ? count - 1 : (index + (event.key === "ArrowRight" ? 1 : -1) + count) % count;
+                this.#activeTab = this.#options.tabs[next].id;
+                this.#render();
+                this.element.querySelector("[role=tab][aria-selected=true]")?.focus({ preventScroll: true });
+            };
+            tabs.append(button);
+        }
+        const panel = document.createElement("div");
+        panel.id = `${this.#id}-panel`;
+        panel.setAttribute("role", "tabpanel");
+        panel.setAttribute("aria-labelledby", `${this.#id}-tab-${this.#options.tabs.findIndex(tab => tab.id === this.#activeTab)}`);
+        for (const item of this.#options.tabs.find(tab => tab.id === this.#activeTab).items)
+            panel.append(this.#row(item));
+        const status = document.createElement("p");
+        status.className = "starlite-menu__status";
+        status.setAttribute("role", "status");
+        status.hidden = true;
+        this.element.append(header, tabs, panel, status);
+        this.element.setAttribute("aria-label", this.#options.title ?? "StarLite");
+        this.#sync();
+    }
+    #text(item) {
+        const text = document.createElement("span");
+        text.className = "starlite-menu__text";
+        text.textContent = item.label;
+        if (item.description) {
+            const description = document.createElement("span");
+            description.className = "starlite-menu__description";
+            description.textContent = item.description;
+            text.append(description);
+        }
+        return text;
+    }
+    #row(item) {
+        if (item.kind === "action") {
+            const row = document.createElement("div");
+            row.className = "starlite-menu__row";
+            const button = document.createElement("button");
+            button.type = "button";
+            button.className = "starlite-menu__action";
+            button.append(this.#text(item));
+            button.dataset.settingId = item.id;
+            button.onclick = () => { const current = this.#item(item.id); if (current?.kind === "action")
+                this.#invoke(current.id, current.onAction); };
+            this.#controls.set(item.id, button);
+            row.append(button);
+            return row;
+        }
+        const row = document.createElement(item.kind === "select" ? "div" : "label");
+        row.className = "starlite-menu__row";
+        const text = this.#text(item);
+        if (item.kind === "select") {
+            row.classList.add("starlite-menu__select-row");
+            const trigger = document.createElement("button");
+            trigger.type = "button";
+            trigger.dataset.settingId = item.id;
+            trigger.className = "starlite-menu__select";
+            const index = this.#selects.size;
+            text.id = `${this.#id}-select-label-${index}`;
+            trigger.setAttribute("role", "combobox");
+            trigger.setAttribute("aria-haspopup", "listbox");
+            trigger.setAttribute("aria-expanded", "false");
+            trigger.setAttribute("aria-labelledby", text.id);
+            const label = document.createElement("span");
+            label.className = "starlite-menu__select-value";
+            trigger.append(label);
+            const listbox = document.createElement("div");
+            listbox.id = `${this.#id}-select-options-${index}`;
+            listbox.className = "starlite-menu__options";
+            listbox.hidden = true;
+            listbox.setAttribute("role", "listbox");
+            listbox.setAttribute("aria-labelledby", text.id);
+            trigger.setAttribute("aria-controls", listbox.id);
+            const options = item.options.map((option, optionIndex) => {
+                const node = document.createElement("button");
+                node.type = "button";
+                node.tabIndex = -1;
+                node.className = "starlite-menu__option";
+                node.dataset.value = option.value;
+                node.id = `${listbox.id}-${optionIndex}`;
+                node.textContent = option.label;
+                node.setAttribute("role", "option");
+                node.onpointerdown = event => event.preventDefault();
+                node.onclick = () => this.#chooseSelect(item.id, optionIndex);
+                listbox.append(node);
+                return node;
+            });
+            trigger.onclick = () => this.#openSelect === item.id ? this.#closeSelect() : this.#showSelect(item.id);
+            trigger.onkeydown = event => this.#selectKey(item.id, event);
+            trigger.onblur = () => { if (this.#openSelect === item.id)
+                this.#closeSelect(); };
+            this.#selects.set(item.id, { trigger, label, listbox, options, activeIndex: -1 });
+            this.#controls.set(item.id, trigger);
+            row.append(text, trigger, listbox);
+            return row;
+        }
+        const input = document.createElement("input");
+        input.dataset.settingId = item.id;
+        if (item.kind === "toggle") {
+            input.type = "checkbox";
+            input.className = "starlite-menu__toggle";
+            input.onchange = () => { const current = this.#item(item.id); if (current?.kind === "toggle")
+                this.#invoke(current.id, () => current.onChange(input.checked)); };
+            row.append(text, input);
+        }
+        else {
+            input.type = "range";
+            input.min = String(item.min);
+            input.max = String(item.max);
+            input.step = String(item.step ?? 1);
+            input.onpointerdown = event => { if (event.button === 0 && !input.disabled)
+                this.#draggingRanges.set(item.id, event.pointerId); };
+            row.classList.add("starlite-menu__range-row");
+            const label = document.createElement("span");
+            label.className = "starlite-menu__range-label";
+            const output = document.createElement("output");
+            this.#outputs.set(item.id, output);
+            label.append(text, output);
+            input.oninput = () => { const current = this.#item(item.id); if (current?.kind === "range") {
+                const value = Number(input.value);
+                output.textContent = current.formatValue?.(value) ?? String(value);
+                this.#invoke(current.id, () => current.onChange(value));
+            } };
+            row.append(label, input);
+        }
+        this.#controls.set(item.id, input);
+        return row;
+    }
+    #sync() {
+        for (const [id, control] of this.#controls) {
+            const item = this.#item(id);
+            if (!item)
+                continue;
+            // Sliders remain usable while host persistence is pending.
+            control.disabled = item.disabled === true || (item.kind !== "range" && this.#pending.has(id));
+            if (item.kind === "toggle")
+                control.checked = item.value;
+            else if (item.kind !== "action") {
+                // Persisted values may arrive behind an ongoing drag. Keep its thumb
+                // under the pointer; the next authoritative update will settle it.
+                if (item.kind === "range" && this.#draggingRanges.has(id))
+                    continue;
+                control.value = String(item.value);
+                if (item.kind === "range")
+                    this.#outputs.get(id).textContent = item.formatValue?.(item.value) ?? String(item.value);
+                else
+                    this.#syncSelect(id, item.value);
+            }
+        }
+    }
+    #syncSelect(id, value) {
+        const select = this.#selects.get(id);
+        if (!select)
+            return;
+        const option = select.options.find(node => node.dataset.value === value);
+        select.label.textContent = option?.textContent ?? "—";
+        for (const node of select.options)
+            node.setAttribute("aria-selected", String(node === option));
+        if (select.trigger.disabled && this.#openSelect === id)
+            this.#closeSelect();
+    }
+    #showSelect(id, index) {
+        const select = this.#selects.get(id);
+        if (!select || select.trigger.disabled || !select.options.length)
+            return;
+        this.#closeSelect();
+        this.#openSelect = id;
+        select.listbox.hidden = false;
+        select.trigger.setAttribute("aria-expanded", "true");
+        this.#activateOption(id, index ?? Math.max(0, select.options.findIndex(node => node.dataset.value === select.trigger.value)));
+        this.element.dispatchEvent(new Event("starlite-menu-change"));
+    }
+    #activateOption(id, index) {
+        const select = this.#selects.get(id);
+        if (!select)
+            return;
+        select.activeIndex = Math.max(0, Math.min(index, select.options.length - 1));
+        for (const [optionIndex, node] of select.options.entries())
+            node.dataset.active = String(optionIndex === select.activeIndex);
+        const active = select.options[select.activeIndex];
+        if (active) {
+            select.trigger.setAttribute("aria-activedescendant", active.id);
+            active.scrollIntoView({ block: "nearest" });
+        }
+    }
+    #closeSelect() {
+        if (!this.#openSelect)
+            return;
+        const select = this.#selects.get(this.#openSelect);
+        this.#openSelect = undefined;
+        if (select) {
+            select.listbox.hidden = true;
+            select.trigger.setAttribute("aria-expanded", "false");
+            select.trigger.removeAttribute("aria-activedescendant");
+            for (const node of select.options)
+                delete node.dataset.active;
+        }
+        this.element.dispatchEvent(new Event("starlite-menu-change"));
+    }
+    #chooseSelect(id, index) {
+        const select = this.#selects.get(id), current = this.#item(id), option = select?.options[index];
+        if (!select || !option || select.trigger.disabled || current?.kind !== "select")
+            return;
+        const value = option.dataset.value;
+        select.trigger.value = value;
+        this.#syncSelect(id, value);
+        this.#closeSelect();
+        select.trigger.focus({ preventScroll: true });
+        this.#invoke(id, () => current.onChange(value));
+    }
+    #selectKey(id, event) {
+        const select = this.#selects.get(id);
+        if (!select)
+            return;
+        if (event.key === "Escape" && this.#openSelect === id) {
+            event.preventDefault();
+            event.stopPropagation();
+            this.#closeSelect();
+            return;
+        }
+        if (event.key === "Tab") {
+            this.#closeSelect();
+            return;
+        }
+        if (!["ArrowDown", "ArrowUp", "Home", "End", "Enter", " "].includes(event.key))
+            return;
+        event.preventDefault();
+        if (event.key === "Home" || event.key === "End") {
+            const index = event.key === "Home" ? 0 : select.options.length - 1;
+            if (this.#openSelect !== id)
+                this.#showSelect(id, index);
+            else
+                this.#activateOption(id, index);
+        }
+        else if (this.#openSelect !== id)
+            this.#showSelect(id);
+        else if (event.key === "Enter" || event.key === " ")
+            this.#chooseSelect(id, select.activeIndex);
+        else
+            this.#activateOption(id, (select.activeIndex + (event.key === "ArrowDown" ? 1 : -1) + select.options.length) % select.options.length);
+    }
+    #invoke(id, callback) {
+        const token = ++this.#generation;
+        this.#pending.set(id, token);
+        const status = this.element.querySelector("[role=status]");
+        status.hidden = true;
+        try {
+            const result = callback();
+            if (result && typeof result.then === "function") {
+                // Do not reset a just-edited input before the host returns its new state.
+                result.catch(() => { this.#reportError(); this.#sync(); }).finally(() => this.#finish(id, token));
+            }
+            else
+                this.#finish(id, token);
+        }
+        catch {
+            this.#pending.delete(id);
+            this.#reportError();
+            this.#sync();
+        }
+    }
+    #finish(id, token) {
+        if (this.#pending.get(id) !== token)
+            return;
+        this.#pending.delete(id);
+        const control = this.#controls.get(id);
+        if (control)
+            control.disabled = this.#item(id)?.disabled === true;
+    }
+    #reportError() {
+        if (this.#destroyed)
+            return;
+        const status = this.element.querySelector("[role=status]");
+        status.textContent = resolveLocale(this.#options.locale) === "en" ? "Could not apply this setting. Please try again." : "未能应用设置，请重试。";
+        status.hidden = false;
+    }
+    #position() {
+        // Position once per explicit open. Host/model resizes and expanded controls
+        // must never move a slider out from under an active pointer.
+        this.element.style.maxWidth = "";
+        this.element.style.maxHeight = "";
+        const rect = this.element.getBoundingClientRect();
+        const width = rect.width || Math.min(300, innerWidth - 16), height = rect.height || this.element.offsetHeight;
+        this.element.style.left = `${Math.max(8, Math.min(this.#x, innerWidth - width - 8))}px`;
+        const top = Math.max(8, Math.min(this.#y, innerHeight - height - 8));
+        this.element.style.top = `${top}px`;
+        this.element.style.maxHeight = `calc(100vh - ${top + 8}px)`;
+    }
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@starcried/starlite-core",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0",
   "type": "module",
   "license": "BSD-2-Clause",
   "files": [
-    "dist"
+    "dist",
+    "README.en.md"
   ],
   "exports": {
     ".": {