@sidurijs/body 1.0.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 VXNUS Creative Technology Studio
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,56 @@
+# @sidurijs/body
+
+The canonical Body Organ for Siduri-X.
+
+This organ acts as the embodiment state machine and experience adapter for visual avatars, supporting 2D Live2D Cubism (`.model3.json`) and 3D humanoid VRM (`.vrm`) models.
+
+## Architecture & Responsibilities
+
+In Siduri's decoupled organ architecture:
+- **Backend / Organ layer (`@sidurijs/body`)**:
+  - Serves as the state machine tracking avatar state (`idle`, `speaking`, `acting`), current facial expressions (`neutral`, `happy`, `sad`, etc.), format detection (`live2d` / `vrm`), and trigger actions.
+  - Implements the `ExperienceAdapter` contract for approved `avatar` lifecycle events.
+  - Maintains model references (`modelPath`, `modelUrl`, `vrmOptions`) without requiring headless GPU or WebGL bindings on the backend server.
+- **Frontend / Client layer (`apps/web` or custom UI)**:
+  - Consumes avatar state updates and renders either Live2D Cubism models or 3D humanoid VRM avatars via WebGL / Three.js (`AvatarCanvas`, `VRMRenderer`).
+
+## Usage
+
+### Live2D
+
+```typescript
+import { NeutralBodyOrgan, Live2DAdapter } from '@sidurijs/body';
+
+// Instantiate with Live2D model URL or path
+const body = new Live2DAdapter({
+  initialExpression: 'neutral',
+  modelUrl: '/assets/body/companion/model.model3.json',
+});
+
+// Update expression or actions
+body.setExpression('happy');
+body.speak('speech-1', 'Hello world');
+```
+
+### VRM (3D Humanoid / VRoid)
+
+```typescript
+import { VRMAdapter } from '@sidurijs/body';
+
+const body = new VRMAdapter({
+  modelUrl: '/assets/body/companion/avatar.vrm',
+  vrm: {
+    specVersion: '1.0',
+    lookAtMode: 'camera',
+  },
+});
+```
+
+## Third-Party Licensing & Runtime Downloads
+
+### Live2D Cubism Notice
+- **Proprietary Core**: Live2D Cubism Core (`live2dcubismcore.min.js`) is proprietary software of Live2D Inc. and cannot be bundled into public npm packages or git repositories under open-source licenses.
+- **Runtime Downloading**: Clients download the official binary directly at runtime from Live2D's verified CDN. You can also programmatically acquire and verify the binary on the host via `downloadCubismCore({ targetDir: './public/live2d', verifyChecksum: true })`.
+- **Indie vs. Commercial Use**: Royalty-free for indie / small-scale entities with annual revenue < 10,000,000 JPY (~$67,000 USD). Commercial publishers exceeding this threshold require a Publication License Agreement directly with Live2D Inc.
+
+For details across all organs, see [Third-Party Organ Licensing Documentation](../../docs/third-party-organ-licensing.md).

package/dist/cubism-installer.d.ts

@@ -0,0 +1,21 @@
+export interface PinnedCubismAsset {
+    version: string;
+    filename: string;
+    url: string;
+    sha256: string;
+}
+/**
+ * Pinned official Live2D Cubism Core Web release with SHA-256 integrity digest.
+ */
+export declare const DEFAULT_PINNED_CUBISM_CORE: PinnedCubismAsset;
+export declare function computeFileSha256(filePath: string): Promise<string>;
+export interface CubismInstallOptions {
+    targetDir: string;
+    asset?: PinnedCubismAsset;
+    verifyChecksum?: boolean;
+}
+/**
+ * Downloads the official Live2D Cubism Core binary into the specified target directory.
+ * Preserves licensing by downloading directly on the user's host environment.
+ */
+export declare function downloadCubismCore(options: CubismInstallOptions): Promise<string>;

package/dist/cubism-installer.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PINNED_CUBISM_CORE = void 0;
+exports.computeFileSha256 = computeFileSha256;
+exports.downloadCubismCore = downloadCubismCore;
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:stream/promises");
+const node_crypto_1 = require("node:crypto");
+/**
+ * Pinned official Live2D Cubism Core Web release with SHA-256 integrity digest.
+ */
+exports.DEFAULT_PINNED_CUBISM_CORE = {
+    version: '5-r.1',
+    filename: 'live2dcubismcore.min.js',
+    url: 'https://cubism.live2d.com/sdk-web/cubismcore/live2dcubismcore.min.js',
+    sha256: '25ae938cb4fe282ce189b357bcc97e603d1e1f7ec78bf04150d401c23cdc792f',
+};
+async function computeFileSha256(filePath) {
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    const stream = (0, node_fs_1.createReadStream)(filePath);
+    for await (const chunk of stream) {
+        hash.update(chunk);
+    }
+    return hash.digest('hex').toLowerCase();
+}
+/**
+ * Downloads the official Live2D Cubism Core binary into the specified target directory.
+ * Preserves licensing by downloading directly on the user's host environment.
+ */
+async function downloadCubismCore(options) {
+    const asset = options.asset || exports.DEFAULT_PINNED_CUBISM_CORE;
+    const targetDir = options.targetDir;
+    const destPath = (0, node_path_1.join)(targetDir, asset.filename);
+    await node_fs_1.promises.mkdir(targetDir, { recursive: true });
+    if ((0, node_fs_1.existsSync)(destPath)) {
+        if (options.verifyChecksum && asset.sha256) {
+            const hash = await computeFileSha256(destPath);
+            if (hash.toLowerCase() === asset.sha256.toLowerCase()) {
+                return destPath;
+            }
+            // Corrupt or outdated, remove and re-download
+            await node_fs_1.promises.unlink(destPath).catch(() => { });
+        }
+        else {
+            return destPath;
+        }
+    }
+    const tmpPath = `${destPath}.tmp-${Date.now()}`;
+    const res = await fetch(asset.url);
+    if (!res.ok || !res.body) {
+        throw new Error(`Failed to download Live2D Cubism Core from ${asset.url}: HTTP ${res.status}`);
+    }
+    const writeStream = (0, node_fs_1.createWriteStream)(tmpPath);
+    await (0, promises_1.pipeline)(res.body, writeStream);
+    if (options.verifyChecksum && asset.sha256) {
+        const downloadedHash = await computeFileSha256(tmpPath);
+        if (downloadedHash.toLowerCase() !== asset.sha256.toLowerCase()) {
+            await node_fs_1.promises.unlink(tmpPath).catch(() => { });
+            throw new Error(`SHA-256 checksum mismatch for ${asset.filename}. Expected ${asset.sha256}, got ${downloadedHash}`);
+        }
+    }
+    await node_fs_1.promises.rename(tmpPath, destPath);
+    return destPath;
+}

package/dist/cubism-installer.test.d.ts

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

package/dist/cubism-installer.test.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const cubism_installer_1 = require("./cubism-installer");
+describe('Live2D Cubism Core Runtime Installer & Verification', () => {
+    const testDir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `siduri-cubism-test-${Date.now()}`);
+    afterAll(() => {
+        (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true });
+    });
+    test('DEFAULT_PINNED_CUBISM_CORE specifies official release metadata and sha256', () => {
+        expect(cubism_installer_1.DEFAULT_PINNED_CUBISM_CORE.filename).toBe('live2dcubismcore.min.js');
+        expect(cubism_installer_1.DEFAULT_PINNED_CUBISM_CORE.url).toContain('cubism.live2d.com');
+        expect(cubism_installer_1.DEFAULT_PINNED_CUBISM_CORE.sha256).toBe('25ae938cb4fe282ce189b357bcc97e603d1e1f7ec78bf04150d401c23cdc792f');
+    });
+    test('downloadCubismCore downloads and verifies official binary', async () => {
+        const destPath = await (0, cubism_installer_1.downloadCubismCore)({
+            targetDir: testDir,
+            verifyChecksum: true,
+        });
+        expect((0, node_fs_1.existsSync)(destPath)).toBe(true);
+        const hash = await (0, cubism_installer_1.computeFileSha256)(destPath);
+        expect(hash).toBe(cubism_installer_1.DEFAULT_PINNED_CUBISM_CORE.sha256);
+        const content = (0, node_fs_1.readFileSync)(destPath, 'utf-8');
+        expect(content).toContain('Live2D Cubism Core');
+    }, 30000);
+    test('downloadCubismCore re-uses already verified file without re-downloading', async () => {
+        const destPath = await (0, cubism_installer_1.downloadCubismCore)({
+            targetDir: testDir,
+            verifyChecksum: true,
+        });
+        expect((0, node_fs_1.existsSync)(destPath)).toBe(true);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { BodyOrgan, ExperienceAdapter, ExperienceEvent, ExperienceAdapterResult } from '@sidurijs/core';
+export * from './cubism-installer';
+export type BodyState = 'idle' | 'speaking' | 'acting';
+export type AvatarFormat = 'live2d' | 'vrm' | 'auto';
+export interface VRMModelOptions {
+    /** Target VRM standard specification version */
+    specVersion?: '0.x' | '1.0' | 'auto';
+    /** Default camera lookAt target behavior */
+    lookAtMode?: 'camera' | 'cursor' | 'head' | 'none';
+    /** Default resting humanoid pose identifier */
+    defaultPose?: string;
+    /** Custom blendshape preset map overrides */
+    expressionMapping?: Record<string, string>;
+}
+export interface BodySnapshot {
+    state: BodyState;
+    currentExpression: string;
+    format: 'live2d' | 'vrm' | 'unknown';
+    modelPath?: string;
+    modelUrl?: string;
+    lastSpeechId: string | null;
+    lastAction: string | null;
+    lastText?: string;
+    lastLanguage?: string;
+    vrmOptions?: VRMModelOptions;
+    updatedAt: number;
+}
+export interface NeutralBodyOrganConfig {
+    /** Avatar rendering provider */
+    provider?: 'live2d' | 'vrm' | 'none' | string;
+    /** Explicit format override (defaults to auto-detection from modelUrl/modelPath extension) */
+    format?: AvatarFormat;
+    initialExpression?: string;
+    modelPath?: string;
+    modelUrl?: string;
+    /** VRM-specific embodiment options */
+    vrm?: VRMModelOptions;
+    [key: string]: unknown;
+}
+export type Live2DAdapterConfig = NeutralBodyOrganConfig;
+export declare class NeutralBodyOrgan implements BodyOrgan, ExperienceAdapter {
+    readonly kind: "avatar";
+    currentExpression: string;
+    modelPath?: string;
+    modelUrl?: string;
+    format: 'live2d' | 'vrm' | 'unknown';
+    vrmOptions?: VRMModelOptions;
+    lastSpeechId: string | null;
+    lastAction: string | null;
+    lastText?: string;
+    lastLanguage?: string;
+    state: BodyState;
+    lastEvent: ExperienceEvent | null;
+    updatedAt: number;
+    constructor(config?: NeutralBodyOrganConfig);
+    private detectFormat;
+    setExpression(expression: string): void;
+    speak(speechId: string, text?: string, language?: string): void;
+    act(action: string): void;
+    completeAction(): void;
+    getSnapshot(): BodySnapshot;
+    handleEvent(event: ExperienceEvent): Promise<ExperienceAdapterResult>;
+    cleanup(): void;
+}
+export declare const Live2DAdapter: typeof NeutralBodyOrgan;
+/** Specialized alias configured for VRM 3D humanoid models */
+export declare class VRMAdapter extends NeutralBodyOrgan {
+    constructor(config?: NeutralBodyOrganConfig);
+}

package/dist/index.js

@@ -0,0 +1,177 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VRMAdapter = exports.Live2DAdapter = exports.NeutralBodyOrgan = void 0;
+const core_1 = require("@sidurijs/core");
+__exportStar(require("./cubism-installer"), exports);
+class NeutralBodyOrgan {
+    kind = 'avatar';
+    currentExpression = 'neutral';
+    modelPath;
+    modelUrl;
+    format = 'unknown';
+    vrmOptions;
+    lastSpeechId = null;
+    lastAction = null;
+    lastText;
+    lastLanguage;
+    state = 'idle';
+    lastEvent = null;
+    updatedAt = Date.now();
+    constructor(config = {}) {
+        if (config.initialExpression) {
+            this.currentExpression = config.initialExpression;
+        }
+        if (config.modelPath) {
+            this.modelPath = config.modelPath;
+        }
+        if (config.modelUrl) {
+            this.modelUrl = config.modelUrl;
+        }
+        if (config.vrm) {
+            this.vrmOptions = { ...config.vrm };
+        }
+        // Resolve avatar format
+        this.format = this.detectFormat(config);
+    }
+    detectFormat(config) {
+        if (config.format && config.format !== 'auto') {
+            return config.format;
+        }
+        if (config.provider === 'vrm') {
+            return 'vrm';
+        }
+        if (config.provider === 'live2d') {
+            return 'live2d';
+        }
+        const ref = (this.modelPath || this.modelUrl || '').toLowerCase();
+        if (ref.endsWith('.vrm')) {
+            return 'vrm';
+        }
+        if (ref.endsWith('.model3.json') || ref.endsWith('.json')) {
+            return 'live2d';
+        }
+        return 'unknown';
+    }
+    setExpression(expression) {
+        this.currentExpression = expression;
+        this.updatedAt = Date.now();
+    }
+    speak(speechId, text, language) {
+        this.lastSpeechId = speechId;
+        this.lastText = text;
+        this.lastLanguage = language;
+        this.state = 'speaking';
+        this.updatedAt = Date.now();
+    }
+    act(action) {
+        this.lastAction = action;
+        this.state = 'acting';
+        this.updatedAt = Date.now();
+    }
+    completeAction() {
+        this.state = 'idle';
+        this.updatedAt = Date.now();
+    }
+    getSnapshot() {
+        return {
+            state: this.state,
+            currentExpression: this.currentExpression,
+            format: this.format,
+            modelPath: this.modelPath,
+            modelUrl: this.modelUrl,
+            lastSpeechId: this.lastSpeechId,
+            lastAction: this.lastAction,
+            lastText: this.lastText,
+            lastLanguage: this.lastLanguage,
+            vrmOptions: this.vrmOptions,
+            updatedAt: this.updatedAt,
+        };
+    }
+    async handleEvent(event) {
+        const validation = (0, core_1.validateExperienceEvent)(event);
+        if (!validation.valid) {
+            return {
+                accepted: false,
+                eventId: event?.eventId || '',
+                lifecycle: 'FAILED',
+                error: validation.error,
+                reason: 'INVALID_EVENT_ENVELOPE',
+            };
+        }
+        if (event.kind !== 'avatar') {
+            return {
+                accepted: false,
+                eventId: event.eventId,
+                lifecycle: 'FAILED',
+                error: `Body adapter received incompatible event kind: ${event.kind}`,
+                reason: 'INCOMPATIBLE_EVENT_KIND',
+            };
+        }
+        if (event.approval !== 'APPROVED') {
+            return {
+                accepted: false,
+                eventId: event.eventId,
+                lifecycle: 'FAILED',
+                error: 'Event is not APPROVED',
+                reason: 'APPROVAL_REQUIRED',
+            };
+        }
+        this.lastEvent = event;
+        if (event.expression) {
+            this.setExpression(event.expression);
+        }
+        if (event.action) {
+            this.act(event.action);
+        }
+        if (event.text) {
+            this.lastText = event.text;
+            this.lastLanguage = event.language;
+        }
+        return {
+            accepted: true,
+            eventId: event.eventId,
+            lifecycle: 'STARTED',
+            metadata: {
+                expression: this.currentExpression,
+                action: this.lastAction,
+                state: this.state,
+                format: this.format,
+                companionId: event.companionId,
+                correlationId: event.correlationId,
+            },
+        };
+    }
+    cleanup() {
+        this.state = 'idle';
+        this.lastEvent = null;
+        this.updatedAt = Date.now();
+    }
+}
+exports.NeutralBodyOrgan = NeutralBodyOrgan;
+// Backward-compatible alias
+exports.Live2DAdapter = NeutralBodyOrgan;
+/** Specialized alias configured for VRM 3D humanoid models */
+class VRMAdapter extends NeutralBodyOrgan {
+    constructor(config = {}) {
+        super({
+            provider: 'vrm',
+            format: 'vrm',
+            ...config,
+        });
+    }
+}
+exports.VRMAdapter = VRMAdapter;

package/dist/index.test.d.ts

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

package/dist/index.test.js

@@ -0,0 +1,257 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+describe('NeutralBodyOrgan', () => {
+    let organ;
+    beforeEach(() => {
+        organ = new index_1.NeutralBodyOrgan();
+    });
+    afterEach(() => {
+        organ.cleanup();
+    });
+    test('constructs with default or custom initial expression with zero external config', () => {
+        expect(organ.currentExpression).toBe('neutral');
+        expect(organ.state).toBe('idle');
+        expect(organ.lastSpeechId).toBeNull();
+        expect(organ.lastAction).toBeNull();
+        const customOrgan = new index_1.NeutralBodyOrgan({
+            initialExpression: 'happy',
+            modelPath: './assets/body/custom/model.model3.json',
+            modelUrl: '/assets/body/custom/model.model3.json',
+        });
+        expect(customOrgan.currentExpression).toBe('happy');
+        expect(customOrgan.modelPath).toBe('./assets/body/custom/model.model3.json');
+        expect(customOrgan.modelUrl).toBe('/assets/body/custom/model.model3.json');
+        const snapshot = customOrgan.getSnapshot();
+        expect(snapshot.modelPath).toBe('./assets/body/custom/model.model3.json');
+        expect(snapshot.modelUrl).toBe('/assets/body/custom/model.model3.json');
+        customOrgan.cleanup();
+    });
+    test('Live2DAdapter is exported as a compatible alias', () => {
+        const adapter = new index_1.Live2DAdapter();
+        expect(adapter).toBeInstanceOf(index_1.NeutralBodyOrgan);
+        adapter.cleanup();
+    });
+    test('tracks body state machine transitions locally', () => {
+        organ.setExpression('smile');
+        expect(organ.currentExpression).toBe('smile');
+        organ.speak('speech_101', 'Hello world', 'en');
+        expect(organ.lastSpeechId).toBe('speech_101');
+        expect(organ.lastText).toBe('Hello world');
+        expect(organ.lastLanguage).toBe('en');
+        expect(organ.state).toBe('speaking');
+        organ.act('wave_hand');
+        expect(organ.lastAction).toBe('wave_hand');
+        expect(organ.state).toBe('acting');
+        organ.completeAction();
+        expect(organ.state).toBe('idle');
+        const snapshot = organ.getSnapshot();
+        expect(snapshot.state).toBe('idle');
+        expect(snapshot.currentExpression).toBe('smile');
+        expect(snapshot.lastSpeechId).toBe('speech_101');
+        expect(snapshot.lastAction).toBe('wave_hand');
+        expect(snapshot.lastText).toBe('Hello world');
+        expect(snapshot.lastLanguage).toBe('en');
+    });
+    test('handleEvent processes valid approved avatar event', async () => {
+        const res = await organ.handleEvent({
+            eventId: 'evt-avatar-1',
+            companionId: 'companion-test',
+            responseId: 'resp-100',
+            correlationId: 'corr-100',
+            channel: 'public',
+            approval: 'APPROVED',
+            kind: 'avatar',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            expression: 'surprised',
+            action: 'nod',
+            text: 'Affirmative.',
+            language: 'en',
+            createdAt: new Date().toISOString(),
+        });
+        expect(res.accepted).toBe(true);
+        expect(res.lifecycle).toBe('STARTED');
+        expect(res.metadata).toMatchObject({
+            expression: 'surprised',
+            action: 'nod',
+            state: 'acting',
+            companionId: 'companion-test',
+            correlationId: 'corr-100',
+        });
+        expect(organ.currentExpression).toBe('surprised');
+        expect(organ.lastAction).toBe('nod');
+        expect(organ.lastText).toBe('Affirmative.');
+    });
+    test('handleEvent rejects unapproved events or incompatible kinds', async () => {
+        const unapprovedRes = await organ.handleEvent({
+            eventId: 'evt-avatar-2',
+            companionId: 'companion-test',
+            responseId: 'resp-100',
+            correlationId: 'corr-100',
+            channel: 'public',
+            approval: 'STAGED',
+            kind: 'avatar',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            createdAt: new Date().toISOString(),
+        });
+        expect(unapprovedRes.accepted).toBe(false);
+        expect(unapprovedRes.error).toContain('APPROVED');
+        const incompatibleRes = await organ.handleEvent({
+            eventId: 'evt-avatar-3',
+            companionId: 'companion-test',
+            responseId: 'resp-100',
+            correlationId: 'corr-100',
+            channel: 'public',
+            approval: 'APPROVED',
+            kind: 'voice',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            createdAt: new Date().toISOString(),
+        });
+        expect(incompatibleRes.accepted).toBe(false);
+        expect(incompatibleRes.reason).toBe('INCOMPATIBLE_EVENT_KIND');
+    });
+    test('handleEvent rejects invalid envelope', async () => {
+        const invalidRes = await organ.handleEvent({});
+        expect(invalidRes.accepted).toBe(false);
+        expect(invalidRes.reason).toBe('INVALID_EVENT_ENVELOPE');
+    });
+    test('requires no open network sockets or transport listeners', () => {
+        // Verifies the object has no transport handles
+        expect(organ.wss).toBeUndefined();
+        expect(organ.vts).toBeUndefined();
+        expect(organ.clients).toBeUndefined();
+    });
+    test('handles sequential avatar events where latest valid event updates active state', async () => {
+        await organ.handleEvent({
+            eventId: 'evt-avatar-10',
+            companionId: 'companion-test',
+            responseId: 'resp-101',
+            correlationId: 'corr-101',
+            channel: 'public',
+            approval: 'APPROVED',
+            kind: 'avatar',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            expression: 'happy',
+            action: 'wave',
+            createdAt: new Date().toISOString(),
+        });
+        expect(organ.currentExpression).toBe('happy');
+        expect(organ.lastAction).toBe('wave');
+        // Newer event arrives
+        await organ.handleEvent({
+            eventId: 'evt-avatar-11',
+            companionId: 'companion-test',
+            responseId: 'resp-102',
+            correlationId: 'corr-102',
+            channel: 'public',
+            approval: 'APPROVED',
+            kind: 'avatar',
+            lifecycle: 'STARTED',
+            evidenceIds: [],
+            expression: 'surprised',
+            action: 'nod',
+            createdAt: new Date().toISOString(),
+        });
+        expect(organ.currentExpression).toBe('surprised');
+        expect(organ.lastAction).toBe('nod');
+    });
+    test('speech synchronization sets speaking state and reset returns to idle', () => {
+        organ.speak('speech_v1', 'Konnichiwa', 'ja');
+        expect(organ.state).toBe('speaking');
+        expect(organ.lastSpeechId).toBe('speech_v1');
+        organ.completeAction();
+        expect(organ.state).toBe('idle');
+    });
+    test('handles unknown expressions and actions with graceful baseline fallbacks', () => {
+        organ.setExpression('unknown_custom_expression');
+        expect(organ.currentExpression).toBe('unknown_custom_expression');
+        organ.act('unknown_action');
+        expect(organ.lastAction).toBe('unknown_action');
+        expect(organ.state).toBe('acting');
+        organ.completeAction();
+        expect(organ.state).toBe('idle');
+    });
+    describe('VRM / 3D Embodiment Support (RFC)', () => {
+        test('auto-detects live2d format from .model3.json or .json extensions', () => {
+            const live2dOrgan = new index_1.NeutralBodyOrgan({
+                modelPath: './assets/body/avatar/model.model3.json',
+            });
+            expect(live2dOrgan.format).toBe('live2d');
+            expect(live2dOrgan.getSnapshot().format).toBe('live2d');
+            live2dOrgan.cleanup();
+        });
+        test('auto-detects vrm format from .vrm extension', () => {
+            const vrmOrgan = new index_1.NeutralBodyOrgan({
+                modelUrl: 'https://cdn.example.com/avatars/companion.vrm',
+            });
+            expect(vrmOrgan.format).toBe('vrm');
+            expect(vrmOrgan.getSnapshot().format).toBe('vrm');
+            vrmOrgan.cleanup();
+        });
+        test('respects explicit format override and provider setting', () => {
+            const explicitVrm = new index_1.NeutralBodyOrgan({
+                provider: 'vrm',
+                modelUrl: 'https://cdn.example.com/asset-without-extension',
+            });
+            expect(explicitVrm.format).toBe('vrm');
+            expect(explicitVrm.getSnapshot().format).toBe('vrm');
+            explicitVrm.cleanup();
+            const forcedFormat = new index_1.NeutralBodyOrgan({
+                format: 'live2d',
+                modelPath: './model.vrm',
+            });
+            expect(forcedFormat.format).toBe('live2d');
+            forcedFormat.cleanup();
+        });
+        test('VRMAdapter defaults provider and format to vrm and retains vrm options', () => {
+            const vrm = new index_1.VRMAdapter({
+                modelPath: './assets/avatar.vrm',
+                vrm: {
+                    specVersion: '1.0',
+                    lookAtMode: 'cursor',
+                    defaultPose: 'idle_a',
+                    expressionMapping: { joy: 'happy' },
+                },
+            });
+            expect(vrm).toBeInstanceOf(index_1.NeutralBodyOrgan);
+            expect(vrm.format).toBe('vrm');
+            expect(vrm.vrmOptions).toEqual({
+                specVersion: '1.0',
+                lookAtMode: 'cursor',
+                defaultPose: 'idle_a',
+                expressionMapping: { joy: 'happy' },
+            });
+            const snapshot = vrm.getSnapshot();
+            expect(snapshot.format).toBe('vrm');
+            expect(snapshot.vrmOptions?.lookAtMode).toBe('cursor');
+            expect(snapshot.vrmOptions?.specVersion).toBe('1.0');
+            vrm.cleanup();
+        });
+        test('handleEvent includes format in response metadata', async () => {
+            const vrm = new index_1.VRMAdapter({
+                modelPath: './avatar.vrm',
+            });
+            const res = await vrm.handleEvent({
+                eventId: 'evt-avatar-vrm-1',
+                companionId: 'companion-3d',
+                responseId: 'resp-200',
+                correlationId: 'corr-200',
+                channel: 'public',
+                approval: 'APPROVED',
+                kind: 'avatar',
+                lifecycle: 'STARTED',
+                evidenceIds: [],
+                expression: 'happy',
+                createdAt: new Date().toISOString(),
+            });
+            expect(res.accepted).toBe(true);
+            expect(res.metadata?.format).toBe('vrm');
+            expect(res.metadata?.expression).toBe('happy');
+            vrm.cleanup();
+        });
+    });
+});

package/organ-manifest.json

@@ -0,0 +1,81 @@
+{
+  "name": "@sidurijs/body",
+  "organType": "body",
+  "version": "1.0.0",
+  "displayName": "Body (Live2D & VRM Avatar State)",
+  "description": "Renderer-agnostic avatar expression and embodiment event adapter supporting Live2D (.model3.json) and VRM (.vrm)",
+  "entrypoint": "./dist/index.js",
+  "factory": "NeutralBodyOrgan",
+  "configKey": "body",
+  "configSchema": {
+    "type": "object",
+    "required": [
+      "provider"
+    ],
+    "properties": {
+      "provider": {
+        "type": "string",
+        "enum": [
+          "live2d",
+          "vrm",
+          "none"
+        ]
+      },
+      "format": {
+        "type": "string",
+        "enum": [
+          "live2d",
+          "vrm",
+          "auto"
+        ],
+        "default": "auto"
+      },
+      "initialExpression": {
+        "type": "string",
+        "default": "neutral"
+      },
+      "modelPath": {
+        "type": "string",
+        "description": "Path to local Live2D Cubism (.model3.json) or VRM (.vrm) model file"
+      },
+      "modelUrl": {
+        "type": "string",
+        "description": "Relative web or remote HTTP URL to Live2D Cubism (.model3.json) or VRM (.vrm) model file"
+      },
+      "vrm": {
+        "type": "object",
+        "properties": {
+          "specVersion": {
+            "type": "string",
+            "enum": [
+              "0.x",
+              "1.0",
+              "auto"
+            ],
+            "default": "auto"
+          },
+          "lookAtMode": {
+            "type": "string",
+            "enum": [
+              "camera",
+              "cursor",
+              "head",
+              "none"
+            ],
+            "default": "camera"
+          },
+          "defaultPose": {
+            "type": "string"
+          },
+          "expressionMapping": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  },
+  "environment": [],
+  "services": [],
+  "database": null,
+  "healthCheck": null
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sidurijs/body",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "jest --config jest.config.json"
+  },
+  "dependencies": {
+    "@sidurijs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.5.1",
+    "jest": "^30.5.1",
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.9.3"
+  },
+  "description": "Body organ for embodiment, avatar expression state machine, and physical animation",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vxnus-studio/siduri-x",
+    "directory": "packages/organs/body"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "files": [
+    "dist",
+    "organ-manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./organ-manifest.json": "./organ-manifest.json"
+  }
+}