@starcried/starlite-core 0.1.0-alpha.3 → 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
 ```
 
 通常直接安装所需后端，它会自动安装本包。

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/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/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";
@@ -11,6 +12,9 @@ export interface ModelAnimationInfo {
 }
 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;
@@ -20,6 +24,8 @@ 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;
@@ -38,6 +44,8 @@ export interface ModelController {
     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 {
@@ -58,7 +66,7 @@ export declare function mountModelWidget<C extends {
 /** 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, resolveDialogueContext, type DialogueContext, type DialogueAction, type DialogueSchedule, type DialogueSceneConfig, type ResolvedDialogueScene } from "./dialogue.js";
-export { DialogueBubble } from "./bubble.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 {

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/quick-settings.d.ts

@@ -1,3 +1,4 @@
+import { type StarLiteLocale } from "./locale.js";
 export type QuickSettingCallback<T> = (value: T) => void | Promise<void>;
 interface QuickSettingBase {
     id: string;
@@ -30,6 +31,7 @@ export type QuickSettingItem = (QuickSettingBase & {
     onAction: () => void | Promise<void>;
 });
 export interface QuickSettingsOptions {
+    locale?: StarLiteLocale;
     title?: string;
     tabs: readonly {
         id: string;

package/dist/quick-settings.js

@@ -1,3 +1,4 @@
+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}
@@ -158,6 +159,7 @@ export class QuickSettingsMenu {
         this.#selects.clear();
     }
     #validate(options) {
+        validateLocale(options.locale);
         const ids = new Set();
         if (!options.tabs.length)
             throw new Error("quick settings requires a tab");
@@ -176,7 +178,7 @@ export class QuickSettingsMenu {
     }
     #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])])]);
+        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;
@@ -196,12 +198,12 @@ export class QuickSettingsMenu {
         close.type = "button";
         close.className = "starlite-menu__close";
         close.textContent = "×";
-        close.setAttribute("aria-label", "关闭菜单");
+        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", "设置分类");
+        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";
@@ -490,7 +492,7 @@ export class QuickSettingsMenu {
         if (this.#destroyed)
             return;
         const status = this.element.querySelector("[role=status]");
-        status.textContent = "未能应用设置，请重试。";
+        status.textContent = resolveLocale(this.#options.locale) === "en" ? "Could not apply this setting. Please try again." : "未能应用设置，请重试。";
         status.hidden = false;
     }
     #position() {

package/package.json

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