@starcried/starlite-vrm 0.0.0-stage → 0.1.0-alpha.2

package/dist/prepare.js

@@ -0,0 +1,134 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { inspectVrm, inspectVrma, MAX_MODEL_BYTES, MAX_ANIMATION_BYTES } from "./inspect.js";
+import { validateCharacterProfile } from "./config.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const arrayBuffer = (bytes) => Uint8Array.from(bytes).buffer;
+async function bounded(path, maximum) {
+    const info = await lstat(path);
+    if (!info.isFile() || info.size > maximum)
+        throw new Error("invalid asset size or file type");
+    const bytes = await readFile(path);
+    if (bytes.byteLength > maximum)
+        throw new Error("asset exceeds byte limit");
+    return bytes;
+}
+function animationNames(animations) {
+    if (!Array.isArray(animations) || animations.length > 64)
+        throw new Error("invalid animation collection");
+    const names = new Set();
+    for (const a of animations) {
+        if (!a || typeof a.name !== "string" || !a.name.trim() || a.name.length > 128 || names.has(a.name))
+            throw new Error("duplicate or invalid animation name");
+        names.add(a.name);
+    }
+}
+function profileNames(profile, animations) {
+    if (profile.neutralAnimation && !animations.some(a => a.name === profile.neutralAnimation))
+        throw new Error("profile neutral animation is missing");
+}
+/** Validate every source before creating output. Never overwrite an existing bundle. */
+export async function prepareModel(request) {
+    const bytes = await bounded(request.model, MAX_MODEL_BYTES);
+    const inspected = inspectVrm(arrayBuffer(bytes));
+    const animations = request.animations ?? [];
+    animationNames(animations);
+    const files = new Map([["model.vrm", bytes]]);
+    const record = (file, data) => ({ file, sha256: hash(data), bytes: data.byteLength });
+    const manifest = { schemaVersion: 1, tool: "vrm-companion-assets", backend: "vrm", model: { ...record("model.vrm", bytes), sourceSha256: hash(bytes) }, animations: [], publication: { allowRedistribution: request.allowRedistribution === true } };
+    let total = 0;
+    for (const [i, source] of animations.entries()) {
+        const data = await bounded(source.path, MAX_ANIMATION_BYTES);
+        total += data.byteLength;
+        if (total > 64 * 1024 * 1024)
+            throw new Error("animation collection exceeds 64 MiB");
+        const { durationMs } = inspectVrma(arrayBuffer(data));
+        const file = `motions/${i}.vrma`;
+        files.set(file, data);
+        manifest.animations.push({ ...record(file, data), name: source.name, durationMs });
+    }
+    if (request.profile) {
+        const data = await bounded(request.profile, 1024 * 1024);
+        const profile = JSON.parse(data.toString("utf8"));
+        validateCharacterProfile(profile);
+        profileNames(profile, [...animations, ...inspected.animations, { name: "StarLiteIdle" }]);
+        files.set("profile.json", data);
+        manifest.profile = record("profile.json", data);
+    }
+    const output = resolve(request.output);
+    await mkdir(dirname(output), { recursive: true });
+    try {
+        await lstat(output);
+        throw new Error("output already exists");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const stage = await mkdtemp(join(dirname(output), ".vrm-stage-"));
+    try {
+        for (const [file, data] of files) {
+            const path = join(stage, file);
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, data, { flag: "wx" });
+        }
+        await writeFile(join(stage, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n", { flag: "wx" });
+        await rename(stage, output);
+        return manifest;
+    }
+    catch (error) {
+        await rm(stage, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Read only declared, hashed files contained in the prepared bundle. */
+export async function readPreparedBundle(directory) { return readPreparedBundleSync(directory); }
+function boundedSync(path, maximum) {
+    const info = lstatSync(path);
+    if (!info.isFile() || info.size > maximum)
+        throw new Error("invalid asset size or file type");
+    const bytes = readFileSync(path);
+    if (bytes.byteLength > maximum)
+        throw new Error("asset exceeds byte limit");
+    return bytes;
+}
+export function readPreparedBundleSync(directory) {
+    const root = realpathSync(directory), raw = boundedSync(join(root, "manifest.json"), 1024 * 1024);
+    const manifest = JSON.parse(raw.toString("utf8"));
+    if (manifest.schemaVersion !== 1 || manifest.tool !== "vrm-companion-assets" || manifest.backend !== "vrm" || typeof manifest.publication?.allowRedistribution !== "boolean" || !/^[a-f0-9]{64}$/.test(manifest.model?.sourceSha256))
+        throw new Error("invalid VRM manifest");
+    animationNames(manifest.animations);
+    const files = new Map();
+    const load = (item, maximum) => {
+        if (!item || typeof item.file !== "string" || !item.file || isAbsolute(item.file) || /[\\:?%#]/.test(item.file) || item.file.split("/").some(p => !p || p === "." || p === "..") || files.has(item.file) || !/^[a-f0-9]{64}$/.test(item.sha256) || !Number.isSafeInteger(item.bytes) || item.bytes < 1 || item.bytes > maximum)
+            throw new Error("invalid manifest asset");
+        const path = realpathSync(join(root, item.file)), part = relative(root, path);
+        if (isAbsolute(part) || part === ".." || part.startsWith("../") || part.startsWith("..\\"))
+            throw new Error("manifest asset leaves bundle");
+        const bytes = boundedSync(path, maximum);
+        if (bytes.byteLength !== item.bytes || hash(bytes) !== item.sha256)
+            throw new Error("manifest asset hash mismatch");
+        files.set(item.file, bytes);
+        return bytes;
+    };
+    const inspected = inspectVrm(arrayBuffer(load(manifest.model, MAX_MODEL_BYTES)));
+    let total = 0;
+    for (const item of manifest.animations) {
+        const bytes = load(item, MAX_ANIMATION_BYTES);
+        total += bytes.byteLength;
+        if (total > 64 * 1024 * 1024)
+            throw new Error("animation collection exceeds 64 MiB");
+        const inspected = inspectVrma(arrayBuffer(bytes));
+        if (!Number.isFinite(item.durationMs) || Math.abs(inspected.durationMs - item.durationMs) > 1)
+            throw new Error("manifest animation duration mismatch");
+    }
+    if (manifest.profile) {
+        const bytes = load(manifest.profile, 1024 * 1024);
+        const profile = JSON.parse(bytes.toString("utf8"));
+        validateCharacterProfile(profile);
+        profileNames(profile, [...manifest.animations, ...inspected.animations, { name: "StarLiteIdle" }]);
+    }
+    return { manifest, files };
+}

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+import type { DialogueSceneConfig, ModelController } from "@starcried/starlite-core";
+export type { ModelController, AnimationPlaybackResult, AnimationPlaybackOptions } from "@starcried/starlite-core";
+export interface VrmAnimationSource {
+    name: string;
+    url: string;
+    durationMs?: number;
+}
+export interface BonePose {
+    rotation: [number, number, number, number];
+    position?: [number, number, number];
+}
+/** Data only: imported profiles cannot execute scripts. All rotations use glTF coordinates. */
+export interface CharacterProfile {
+    schemaVersion: 1;
+    type: "weiguang";
+    neutralPose: Record<string, BonePose>;
+    neutralAnimation?: string;
+    expressions: Record<string, {
+        expression: string;
+        blink?: string;
+    }>;
+    earPoses: Record<string, Record<string, BonePose>>;
+    earBones: string[];
+    accessories: {
+        collar: string;
+        cone: string;
+        collarVisible: boolean;
+        coneVisible: boolean;
+    };
+    blink: {
+        period: number;
+        curve: [number, number][];
+    };
+}
+export interface VrmWidgetConfig {
+    backend?: "vrm";
+    model: string;
+    fallback: string;
+    animations?: readonly VrmAnimationSource[];
+    /** Names returned by inspectVrm for animations embedded in the model. */
+    embeddedAnimations?: readonly string[];
+    /** Initial sample used as the relaxed pose when playback is stopped. */
+    neutralAnimation?: string;
+    profile?: CharacterProfile | string;
+    display?: {
+        width?: number;
+        height?: number;
+    };
+    render?: {
+        fps?: number | "display";
+        maxDevicePixelRatio?: number;
+        initialScale?: number;
+        autoFit?: boolean;
+        fitPadding?: number;
+        /** Fixed CSS pixel margins; when supplied, animation never resizes the canvas. */
+        viewportPadding?: {
+            left: number;
+            top: number;
+            right: number;
+            bottom: number;
+        };
+    };
+    camera?: {
+        yawDegrees?: number;
+        pitchDegrees?: number;
+        fovDegrees?: number;
+        targetHeight?: number;
+    };
+    gaze?: {
+        maxYawDegrees?: number;
+        maxPitchDegrees?: number;
+        smoothingMs?: number;
+    };
+    mobile?: {
+        show?: boolean;
+        breakpoint?: number;
+    };
+    network?: {
+        requestTimeoutMs?: number;
+        modelMaxBytes?: number;
+    };
+    interactions?: {
+        pointer?: boolean;
+        click?: false | {
+            animation?: string;
+            animations?: readonly string[];
+        };
+        drag?: boolean;
+        /** Observe native page clicks without intercepting them; incompatible with drag. */
+        passThrough?: boolean;
+    };
+    ambient?: {
+        animations?: readonly string[];
+    };
+    dialogue?: {
+        enter?: false | (DialogueSceneConfig & {
+            delayMs?: number;
+        });
+        idle?: false | (DialogueSceneConfig & {
+            intervalMinMs?: number;
+            intervalMaxMs?: number;
+        });
+        click?: false | DialogueSceneConfig;
+    };
+}
+export interface ModelViewport {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    baseWidth: number;
+    baseHeight: number;
+}
+export interface VrmDiagnostics {
+    renderedFrames: number;
+    frameTimesMs: number[];
+    renderCostsMs: number[];
+    calls: number;
+    triangles: number;
+    geometries: number;
+    textures: number;
+    renderer: string;
+    loadMs: number;
+    activeAnimation?: string | null;
+    gaze?: {
+        yawDegrees: number;
+        pitchDegrees: number;
+        headYawDegrees: number;
+        headPitchDegrees: number;
+    };
+    framing?: {
+        distance: number;
+        maxAbsX: number;
+        maxAbsY: number;
+        viewport: ModelViewport;
+    };
+    springPose?: readonly {
+        name: string;
+        rotation: [number, number, number, number];
+    }[];
+}
+export interface VrmController extends ModelController {
+    diagnostics(): VrmDiagnostics;
+    captureFrame(): string;
+    getExpressions(): readonly string[];
+    setExpression(name: string, weight: number): void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/widget.css

@@ -0,0 +1,69 @@
+.model-vrm-widget { position:relative; width:320px; height:480px; background:transparent; touch-action:none; }
+.model-vrm-widget canvas { position:absolute; display:block; left:0; top:0; background:transparent; }
+.model-vrm-widget[data-model-pass-through],
+.model-vrm-widget[data-model-pass-through] > canvas,
+.model-vrm-widget[data-model-pass-through] > img { pointer-events:none; touch-action:auto; }
+.model-vrm-widget > img { display:block; width:100%; height:100%; object-fit:contain; }
+.model-vrm-widget > img[hidden], .model-vrm-widget > canvas[hidden] { display:none; }
+
+.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/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@starcried/starlite-vrm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.2",
+  "type": "module",
+  "license": "BSD-2-Clause",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "DEFAULT_IDLE.md",
+    "THIRD_PARTY_NOTICES.md",
+    "THIRD_PARTY_LICENSES.txt"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "require": "./dist/config.cjs"
+    },
+    "./inspect": {
+      "types": "./dist/inspect.d.ts",
+      "import": "./dist/inspect.js",
+      "require": "./dist/inspect.cjs"
+    },
+    "./widget.css": "./dist/widget.css",
+    "./prepare": {
+      "types": "./dist/prepare.d.ts",
+      "default": "./dist/prepare.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@pixiv/three-vrm": "3.5.5",
+    "@pixiv/three-vrm-animation": "3.5.5",
+    "@starcried/starlite-core": "0.1.0-alpha.2",
+    "three": "0.186.0"
+  },
+  "devDependencies": {
+    "@types/three": "0.183.1",
+    "esbuild": "0.28.2"
+  },
+  "description": "WebGL2 VRM and VRMA backend for lightweight StarLite companions",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/StarCried/starlite.git",
+    "directory": "packages/vrm"
+  },
+  "homepage": "https://github.com/StarCried/starlite#readme",
+  "bugs": "https://github.com/StarCried/starlite/issues"
+}