@starcried/starlite-core 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, StarCried
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# @starcried/starlite-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+StarLite 的公共播放契约、生命周期和气泡组件。该包不导入 Three.js 或 Inochi2D WASM；宿主先选择后端，再加载对应运行时。
+
+在 Node.js 22.12+ 项目中安装 alpha 版本：
+
+```sh
+npm install @starcried/starlite-core@alpha
+```
+
+通常直接安装所需后端，它会自动安装本包。
+
+## 公共能力
+
+`ModelController` 提供 `pause`、`resume`、`getAnimations`、`playAnimation`、`stopAnimation`、`resetCamera` 和 `destroy`。动作 Promise 的结束结果为 `completed`、`interrupted` 或 `stopped`；循环在中断或停止后结束等待。
+
+`ModelMountSlot` 中止被替换的加载，并销毁迟到的实例。动作载荷、骨骼和参数属于后端，公共层只交换动作名称、时长和播放结果。
+
+`DialogueScheduler` 管理首次入场、偶发小动作和点击回应；`DialogueBubble` 管理纯文本、ARIA 状态提示、边缘位置、过期和清理。两个后端共用该组件与样式。气泡可由宿主独立调用，无需模型或动作；VRM 的声明式场景也可省略 `animation`，仅配置 `lines` 显示句子，不打断待机。
+
+## 语句与动作绑定
+
+```ts
+dialogue: {
+  click: {
+    animation: "Wave",
+    animations: ["Wave", "Nod"],
+    linesByAnimation: {
+      Wave: ["你好！", "很高兴见到你。"],
+      Nod: ["我在这里。", "继续吧。"]
+    }
+  }
+}
+```
+
+每次先选择一个动作，再从该动作的句子中随机选择。动作名称精确匹配且区分大小写；动作池允许 1–20 个不同名称。`linesByAnimation` 必须覆盖整个动作池，且不能包含池外名称；也可用 `lines` 提供共用语句库。
+
+## 进阶
+
+[完整配置](https://github.com/StarCried/starlite/blob/main/docs/configuration.md) · [组件结构](https://github.com/StarCried/starlite/blob/main/docs/architecture.md) · [VRM 后端](https://github.com/StarCried/starlite/blob/main/packages/vrm/README.md) · [Inochi2D 后端](https://github.com/StarCried/starlite/blob/main/packages/inochi2d/README.md)
+
+BSD-2-Clause；不包含模型、角色素材或第三方动作。

package/dist/bubble.css

@@ -0,0 +1,61 @@
+.model-widget__bubble {
+  --model-bubble-shift-x: 0px;
+  position: absolute;
+  left: 50%;
+  bottom: calc(100% + 12px);
+  z-index: 2;
+  box-sizing: border-box;
+  width: max-content;
+  max-width: min(280px, calc(100vw - 24px));
+  padding: 10px 14px;
+  border: 1px solid rgb(255 255 255 / 65%);
+  border-radius: 14px;
+  color: #20242b;
+  background: rgb(255 255 255 / 94%);
+  box-shadow: 0 8px 24px rgb(0 0 0 / 18%);
+  font: 14px/1.55 system-ui, -apple-system, "Segoe UI", sans-serif;
+  overflow-wrap: anywhere;
+  pointer-events: none;
+  transform: translateX(calc(-50% + var(--model-bubble-shift-x)));
+}
+
+.model-widget__bubble[data-model-placement="below"] {
+  top: calc(100% + 12px);
+  bottom: auto;
+}
+
+.model-widget__bubble::after {
+  position: absolute;
+  left: calc(50% - var(--model-bubble-shift-x));
+  bottom: -7px;
+  width: 12px;
+  height: 12px;
+  border-right: 1px solid rgb(255 255 255 / 65%);
+  border-bottom: 1px solid rgb(255 255 255 / 65%);
+  background: rgb(255 255 255 / 94%);
+  content: "";
+  transform: translateX(-50%) rotate(45deg);
+}
+
+.model-widget__bubble[data-model-placement="below"]::after {
+  top: -7px;
+  bottom: auto;
+  transform: translateX(-50%) rotate(225deg);
+}
+
+.model-widget__bubble[hidden] {
+  display: none;
+}
+
+.model-widget__bubble-text {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 6;
+  overflow: hidden;
+  animation: model-bubble-reveal 180ms ease-out;
+}
+
+@keyframes model-bubble-reveal { from { opacity: 0.35; } to { opacity: 1; } }
+@media (prefers-reduced-motion: reduce) {
+  .model-widget__bubble-text { animation: none; }
+}

package/dist/bubble.d.ts

@@ -0,0 +1,12 @@
+import type { DialogueAction } from "./dialogue.js";
+/** Plain-text, accessible dialogue presentation shared by every renderer. */
+export declare class DialogueBubble {
+    #private;
+    readonly element: HTMLDivElement;
+    constructor(host: HTMLElement);
+    show(action: DialogueAction, timestamp: number, withoutFrames?: boolean): void;
+    update(timestamp: number): void;
+    hide(): void;
+    position(): void;
+    destroy(): void;
+}

package/dist/bubble.js

@@ -0,0 +1,56 @@
+/** Plain-text, accessible dialogue presentation shared by every renderer. */
+export class DialogueBubble {
+    element;
+    #host;
+    #until = 0;
+    #timeout;
+    constructor(host) {
+        this.#host = host;
+        this.element = document.createElement("div");
+        this.element.className = "model-widget__bubble";
+        this.element.hidden = true;
+        this.element.setAttribute("role", "status");
+        this.element.setAttribute("aria-live", "polite");
+        this.element.setAttribute("aria-atomic", "true");
+    }
+    show(action, timestamp, withoutFrames = false) {
+        this.hide();
+        const content = document.createElement("span");
+        content.className = "model-widget__bubble-text";
+        content.textContent = action.line;
+        this.element.replaceChildren(content);
+        this.element.dataset.modelScene = action.scene;
+        if (action.animation)
+            this.element.dataset.modelAnimation = action.animation;
+        this.element.hidden = false;
+        this.#until = timestamp + action.durationMs;
+        this.position();
+        if (withoutFrames)
+            this.#timeout = setTimeout(() => this.hide(), action.durationMs);
+    }
+    update(timestamp) {
+        if (!this.element.hidden && timestamp >= this.#until)
+            this.hide();
+    }
+    hide() {
+        if (this.#timeout !== undefined)
+            clearTimeout(this.#timeout);
+        this.#timeout = undefined;
+        this.#until = 0;
+        this.element.hidden = true;
+        this.element.textContent = "";
+        delete this.element.dataset.modelScene;
+        delete this.element.dataset.modelAnimation;
+    }
+    position() {
+        if (this.element.hidden)
+            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 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`);
+    }
+    destroy() { this.hide(); this.element.remove(); }
+}

package/dist/dialogue.d.ts

@@ -0,0 +1,47 @@
+export type DialogueSceneName = 'enter' | 'idle' | 'click';
+export interface DialogueSceneConfig {
+    animation?: string;
+    animations?: readonly string[];
+    /** Shared sentence library used when linesByAnimation is absent. */
+    lines?: readonly string[];
+    /** Complete sentence libraries for the selected animation or animation pool. */
+    linesByAnimation?: Readonly<Record<string, readonly string[]>>;
+    durationMs?: number;
+}
+export interface ResolvedDialogueScene extends DialogueSceneConfig {
+    durationMs: number;
+}
+/** 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 {
+    enter: false | (ResolvedDialogueScene & {
+        delayMs: number;
+    });
+    idle: false | (ResolvedDialogueScene & {
+        intervalMinMs: number;
+        intervalMaxMs: number;
+    });
+    click: false | ResolvedDialogueScene;
+}
+export interface DialogueAction {
+    scene: DialogueSceneName;
+    animation?: string;
+    line: string;
+    durationMs: number;
+}
+/**
+ * Schedules model-authored foreground actions and selects plain-text sentences.
+ *
+ * Clicks are delivered synchronously by the controller. Enter and idle scenes
+ * are polled from the existing render loop, avoiding a second animation loop
+ * or duplicate timers across PJAX navigation.
+ */
+export declare class DialogueScheduler {
+    #private;
+    constructor(config: DialogueSchedule, random: () => number);
+    start(timestampMs: number, immediateEnter?: boolean): void;
+    poll(timestampMs: number, foregroundActive: boolean): DialogueAction | undefined;
+    triggerClick(timestampMs: number): DialogueAction | undefined;
+    /** Postpones natural speech after visibility changes or direct interaction. */
+    deferIdle(timestampMs: number): void;
+}

package/dist/dialogue.js

@@ -0,0 +1,139 @@
+/** Validate and copy plain-text libraries at the backend configuration boundary. */
+export function resolveDialogueSentences(input, animations, field) {
+    const resolve = (value, path) => {
+        if (!Array.isArray(value) || value.length < 1 || value.length > 128) {
+            throw new Error(`${path} must contain 1..=128 sentences`);
+        }
+        return value.map((line, index) => {
+            if (typeof line !== "string")
+                throw new Error(`${path}[${index}] must be a string`);
+            const text = line.trim();
+            const bytes = new TextEncoder().encode(text).byteLength;
+            if (bytes < 1 || bytes > 1024)
+                throw new Error(`${path}[${index}] must contain 1..=1024 UTF-8 bytes`);
+            return text;
+        });
+    };
+    const lines = input.lines === undefined ? undefined : resolve(input.lines, `${field}.lines`);
+    const mapping = input.linesByAnimation;
+    if (mapping === undefined) {
+        if (!lines)
+            throw new Error(`${field}.lines or linesByAnimation is required`);
+        return { lines };
+    }
+    if (!mapping || typeof mapping !== "object" || Array.isArray(mapping)) {
+        throw new Error(`${field}.linesByAnimation must be an animation-to-sentences object`);
+    }
+    if (!animations.length)
+        throw new Error(`${field}.linesByAnimation needs an animation`);
+    const selected = new Set(animations);
+    const keys = Object.keys(mapping);
+    if (keys.length !== selected.size || keys.some(name => !selected.has(name)) || animations.some(name => !Object.hasOwn(mapping, name))) {
+        throw new Error(`${field}.linesByAnimation must cover exactly the selected animations`);
+    }
+    const linesByAnimation = Object.fromEntries(keys.map(name => [name, resolve(mapping[name], `${field}.linesByAnimation[${JSON.stringify(name)}]`)]));
+    return { ...(lines ? { lines } : {}), linesByAnimation };
+}
+/**
+ * Schedules model-authored foreground actions and selects plain-text sentences.
+ *
+ * Clicks are delivered synchronously by the controller. Enter and idle scenes
+ * are polled from the existing render loop, avoiding a second animation loop
+ * or duplicate timers across PJAX navigation.
+ */
+export class DialogueScheduler {
+    #config;
+    #random;
+    #started = false;
+    #enterDueAt;
+    #nextIdleAt;
+    constructor(config, random) {
+        this.#config = config;
+        this.#random = random;
+    }
+    start(timestampMs, immediateEnter = false) {
+        if (this.#started) {
+            return;
+        }
+        this.#started = true;
+        if (this.#config.enter) {
+            this.#enterDueAt =
+                timestampMs + (immediateEnter ? 0 : this.#config.enter.delayMs);
+        }
+        this.#scheduleIdle(timestampMs);
+    }
+    poll(timestampMs, foregroundActive) {
+        if (!this.#started || foregroundActive) {
+            return undefined;
+        }
+        if (this.#config.enter &&
+            this.#enterDueAt !== undefined &&
+            timestampMs >= this.#enterDueAt) {
+            this.#enterDueAt = undefined;
+            const action = this.#action("enter", this.#config.enter);
+            this.#scheduleIdle(timestampMs + action.durationMs);
+            return action;
+        }
+        if (this.#config.idle &&
+            this.#nextIdleAt !== undefined &&
+            timestampMs >= this.#nextIdleAt) {
+            const action = this.#action("idle", this.#config.idle);
+            this.#scheduleIdle(timestampMs + action.durationMs);
+            return action;
+        }
+        return undefined;
+    }
+    triggerClick(timestampMs) {
+        this.deferIdle(timestampMs);
+        if (!this.#config.click) {
+            return undefined;
+        }
+        const action = this.#action("click", this.#config.click);
+        this.#scheduleIdle(timestampMs + action.durationMs);
+        return action;
+    }
+    /** Postpones natural speech after visibility changes or direct interaction. */
+    deferIdle(timestampMs) {
+        if (this.#started) {
+            this.#scheduleIdle(timestampMs);
+        }
+    }
+    #action(scene, config) {
+        // Preserve the historical random draw order for shared sentence libraries.
+        // Bound libraries choose the animation first, then only its own sentences.
+        const chooseAnimation = () => config.animations?.length
+            ? config.animations[Math.floor(this.#unitRandom() * config.animations.length)]
+            : config.animation;
+        const animation = config.linesByAnimation ? chooseAnimation() : undefined;
+        const lines = animation === undefined ? config.lines : config.linesByAnimation[animation];
+        const index = Math.floor(this.#unitRandom() * lines.length);
+        const chosenAnimation = animation ?? chooseAnimation();
+        return {
+            scene,
+            ...(chosenAnimation !== undefined ? { animation: chosenAnimation } : {}),
+            line: lines[index],
+            durationMs: config.durationMs,
+        };
+    }
+    #scheduleIdle(timestampMs) {
+        if (this.#enterDueAt !== undefined) {
+            this.#nextIdleAt = undefined;
+            return;
+        }
+        const idle = this.#config.idle;
+        if (!idle) {
+            this.#nextIdleAt = undefined;
+            return;
+        }
+        const interval = idle.intervalMinMs +
+            (idle.intervalMaxMs - idle.intervalMinMs) * this.#unitRandom();
+        this.#nextIdleAt = timestampMs + interval;
+    }
+    #unitRandom() {
+        const value = this.#random();
+        if (!Number.isFinite(value)) {
+            return 0;
+        }
+        return Math.min(1 - Number.EPSILON, Math.max(0, value));
+    }
+}

package/dist/hit-mask.d.ts

@@ -0,0 +1,22 @@
+/** Model-only alpha coverage. Coordinates are CSS pixels in the host viewport. */
+export interface ModelHitMask {
+    width: number;
+    height: number;
+    left: number;
+    top: number;
+    displayWidth: number;
+    displayHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    bits: Uint8Array;
+}
+export type ModelHitMaskListener = (mask: ModelHitMask | undefined) => void;
+export declare function packAlphaMask(rgba: Uint8ClampedArray): Uint8Array;
+/** Opt-in readback, called immediately after rendering before WebGL clears its buffer. */
+export declare class RenderedHitMask {
+    #private;
+    setListener(listener?: ModelHitMaskListener): void;
+    capture(canvas: HTMLCanvasElement, timestamp: number): void;
+    clear(): void;
+    destroy(): void;
+}

package/dist/hit-mask.js

@@ -0,0 +1,56 @@
+export function packAlphaMask(rgba) {
+    const bits = new Uint8Array(Math.ceil(rgba.length / 4 / 8));
+    for (let pixel = 0; pixel < rgba.length / 4; pixel++) {
+        // Include visible translucent fur and anti-aliased edges, not transparent quads.
+        if (rgba[pixel * 4 + 3] >= 16)
+            bits[pixel >> 3] |= 1 << (pixel & 7);
+    }
+    return bits;
+}
+/** Opt-in readback, called immediately after rendering before WebGL clears its buffer. */
+export class RenderedHitMask {
+    #listener;
+    #surface;
+    #lastTime = -Infinity;
+    setListener(listener) {
+        this.#listener?.(undefined);
+        this.#listener = listener;
+        this.#lastTime = -Infinity;
+        if (!listener)
+            this.#surface = undefined;
+    }
+    capture(canvas, timestamp) {
+        if (!this.#listener || timestamp - this.#lastTime < 50)
+            return;
+        this.#lastTime = timestamp;
+        const rect = canvas.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0 || !canvas.width || !canvas.height)
+            return;
+        // At most 512² bits. Normally one sample per two CSS pixels (240 × 360).
+        const scale = Math.min(.5, 512 / rect.width, 512 / rect.height);
+        const width = Math.max(1, Math.ceil(rect.width * scale));
+        const height = Math.max(1, Math.ceil(rect.height * scale));
+        const surface = this.#surface ??= document.createElement("canvas");
+        if (surface.width !== width)
+            surface.width = width;
+        if (surface.height !== height)
+            surface.height = height;
+        try {
+            const context = surface.getContext("2d", { willReadFrequently: true });
+            if (!context)
+                throw new Error("alpha sampling unavailable");
+            context.clearRect(0, 0, width, height);
+            context.drawImage(canvas, 0, 0, width, height);
+            this.#listener({ width, height, left: rect.left, top: rect.top,
+                displayWidth: rect.width, displayHeight: rect.height,
+                viewportWidth: innerWidth, viewportHeight: innerHeight,
+                bits: packAlphaMask(context.getImageData(0, 0, width, height).data) });
+        }
+        catch {
+            // Unreadable/tainted output must never become a rectangular hit target.
+            this.#listener(undefined);
+        }
+    }
+    clear() { this.#listener?.(undefined); }
+    destroy() { this.setListener(); }
+}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+export type ModelBackend = "inochi2d" | "vrm";
+export type WidgetStatus = "disabled" | "loading" | "running" | "paused" | "fallback" | "destroyed";
+export type AnimationPlaybackResult = "completed" | "interrupted" | "stopped";
+export interface AnimationPlaybackOptions {
+    mode?: "once" | "loop";
+    restart?: boolean;
+}
+export interface ModelAnimationInfo {
+    name: string;
+    durationMs: number;
+}
+import type { ModelHitMaskListener } from "./hit-mask.js";
+export { RenderedHitMask, packAlphaMask, type ModelHitMask, type ModelHitMaskListener } from "./hit-mask.js";
+export interface ModelController {
+    readonly status: WidgetStatus;
+    pause(): void;
+    resume(): void;
+    getAnimations(): readonly ModelAnimationInfo[];
+    playAnimation(name: string, options?: AnimationPlaybackOptions): Promise<AnimationPlaybackResult>;
+    stopAnimation(): void;
+    resetCamera(): void;
+    observeInteractionMask(listener?: ModelHitMaskListener): void;
+    setPointerPosition(clientX: number, clientY: number): void;
+    /** Optional host-movement capability. Coordinates are CSS pixels, local only. */
+    setHostPosition?(x: number, y: number): void;
+    destroy(): void;
+}
+export interface MountOptions {
+    signal?: AbortSignal;
+}
+/** Own one mount, including asynchronous work which outlives a replacement. */
+export declare class ModelMountSlot {
+    #private;
+    mount(factory: (signal: AbortSignal) => Promise<ModelController>): Promise<ModelController | undefined>;
+    destroy(): void;
+}
+/** Only import the selected backend. Runtime URLs are supplied by the host. */
+export declare function mountModelWidget<C extends {
+    backend?: ModelBackend;
+}>(host: HTMLElement, config: C, modules: Record<ModelBackend, () => Promise<{
+    mountModelWidget(host: HTMLElement, config: C, options?: MountOptions): Promise<ModelController>;
+}>>, 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 { observePassThroughClicks } from "./pass-through.js";

package/dist/index.js

@@ -0,0 +1,85 @@
+export { RenderedHitMask, packAlphaMask } from "./hit-mask.js";
+/** Own one mount, including asynchronous work which outlives a replacement. */
+export class ModelMountSlot {
+    #abort;
+    #controller;
+    async mount(factory) {
+        this.destroy();
+        const abort = new AbortController();
+        this.#abort = abort;
+        try {
+            const controller = await factory(abort.signal);
+            if (abort.signal.aborted || this.#abort !== abort) {
+                controller.destroy();
+                return undefined;
+            }
+            this.#controller = controller;
+            return controller;
+        }
+        catch (error) {
+            if (abort.signal.aborted)
+                return undefined;
+            throw error;
+        }
+    }
+    destroy() {
+        this.#abort?.abort();
+        this.#abort = undefined;
+        this.#controller?.destroy();
+        this.#controller = undefined;
+    }
+}
+/** Only import the selected backend. Runtime URLs are supplied by the host. */
+export async function mountModelWidget(host, config, modules, options = {}) {
+    options.signal?.throwIfAborted();
+    const backend = config.backend ?? "inochi2d";
+    const runtime = await modules[backend]();
+    options.signal?.throwIfAborted();
+    return runtime.mountModelWidget(host, config, options);
+}
+/** Streaming limit applies to decoded response bytes, not just Content-Length. */
+export async function fetchBounded(url, maximumBytes, signal) {
+    const response = await fetch(url, { signal, credentials: "same-origin" });
+    if (!response.ok)
+        throw new Error(`asset request failed: HTTP ${response.status}`);
+    if (Number(response.headers.get("content-length")) > maximumBytes) {
+        await response.body?.cancel();
+        throw new Error("asset exceeds the byte limit");
+    }
+    if (!response.body) {
+        const bytes = await response.arrayBuffer();
+        if (bytes.byteLength > maximumBytes)
+            throw new Error("asset exceeds the byte limit");
+        return bytes;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maximumBytes) {
+                await reader.cancel();
+                throw new Error("asset exceeds the byte limit");
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    signal.throwIfAborted();
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes.buffer;
+}
+export { DialogueScheduler, resolveDialogueSentences } from "./dialogue.js";
+export { DialogueBubble } from "./bubble.js";
+export { observePassThroughClicks } from "./pass-through.js";

package/dist/pass-through.d.ts

@@ -0,0 +1,3 @@
+/** Observe the same native click that reaches the page beneath an inert canvas.
+ * Callers opt the host/canvas out of hit testing with pointer-events: none. */
+export declare function observePassThroughClicks(surface: HTMLElement, onClick: () => void): () => void;

package/dist/pass-through.js

@@ -0,0 +1,58 @@
+/** Observe the same native click that reaches the page beneath an inert canvas.
+ * Callers opt the host/canvas out of hit testing with pointer-events: none. */
+export function observePassThroughClicks(surface, onClick) {
+    let down;
+    let ready;
+    const inside = (event) => {
+        const rect = surface.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0
+            && event.clientX >= rect.left && event.clientX < rect.right
+            && event.clientY >= rect.top && event.clientY < rect.bottom;
+    };
+    const clear = () => { down = undefined; ready = undefined; };
+    const move = (event) => {
+        if (down?.id === event.pointerId && Math.hypot(event.clientX - down.x, event.clientY - down.y) > 5)
+            down.moved = true;
+    };
+    const listeners = [
+        ["pointerdown", event => {
+                clear();
+                const pointer = event;
+                if (pointer.button === 0 && pointer.isPrimary !== false && inside(pointer)) {
+                    down = { id: pointer.pointerId, x: pointer.clientX, y: pointer.clientY, moved: false };
+                }
+            }],
+        ["pointermove", event => move(event)],
+        ["pointerup", event => {
+                const pointer = event;
+                if (down?.id !== pointer.pointerId)
+                    return;
+                move(pointer);
+                ready = pointer.button === 0 && !down.moved && inside(pointer) ? down : undefined;
+                down = undefined;
+            }],
+        ["pointercancel", clear],
+        ["scroll", clear],
+        // Capture also sees a page element lose focus during a normal mouse click.
+        // Only leaving this window cancels the in-progress pointer gesture.
+        ["blur", event => { if (event.target === event.currentTarget)
+                clear(); }],
+        ["click", event => {
+                const click = event;
+                const gesture = ready;
+                clear();
+                // Keyboard/programmatic clicks have no matching completed pointer gesture.
+                // Modifier keys intentionally remain available to the page's native click.
+                if (gesture && click.button === 0 && click.detail > 0 && inside(click)
+                    && Math.hypot(click.clientX - gesture.x, click.clientY - gesture.y) <= 5)
+                    onClick();
+            }],
+    ];
+    for (const [type, listener] of listeners)
+        window.addEventListener(type, listener, { capture: true, passive: true });
+    return () => {
+        clear();
+        for (const [type, listener] of listeners)
+            window.removeEventListener(type, listener, true);
+    };
+}

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@starcried/starlite-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "license": "BSD-2-Clause",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./bubble.css": "./dist/bubble.css"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest run"
+  },
+  "description": "Format-neutral lifecycle, animation contracts and dialogue components for StarLite",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/StarCried/starlite.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/StarCried/starlite#readme",
+  "bugs": "https://github.com/StarCried/starlite/issues"
+}