@starcried/starlite-core 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -18,6 +18,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/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/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

@@ -10,6 +10,7 @@ export interface ModelAnimationInfo {
     durationMs: number;
 }
 import type { ModelHitMaskListener } from "./hit-mask.js";
+import type { DialogueContext } from "./dialogue.js";
 export { RenderedHitMask, packAlphaMask, type ModelHitMask, type ModelHitMaskListener } from "./hit-mask.js";
 export interface ModelController {
     readonly status: WidgetStatus;
@@ -20,9 +21,23 @@ export interface ModelController {
     stopAnimation(): void;
     resetCamera(): void;
     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;
     destroy(): void;
 }
 export interface MountOptions {
@@ -42,6 +57,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 { DialogueScheduler, resolveDialogueSentences, resolveDialogueContext, type DialogueContext, type DialogueAction, type DialogueSchedule, type DialogueSceneConfig, type ResolvedDialogueScene } from "./dialogue.js";
 export { DialogueBubble } 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

@@ -80,6 +80,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/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,51 @@
+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 {
+    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,508 @@
+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) {
+        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.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", "关闭菜单");
+        close.onclick = () => this.close();
+        header.append(title, close);
+        const tabs = document.createElement("div");
+        tabs.setAttribute("role", "tablist");
+        tabs.setAttribute("aria-label", "设置分类");
+        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 = "未能应用设置，请重试。";
+        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,6 +1,6 @@
 {
   "name": "@starcried/starlite-core",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "type": "module",
   "license": "BSD-2-Clause",
   "files": [