@virtualdisplay.io/client 3.6.0 → 4.0.0-alpha.1

package/package.json

@@ -1,57 +1,11 @@
 {
   "name": "@virtualdisplay.io/client",
   "description": "TypeScript-first 3D model integration library with iframe-based architecture",
-  "version": "3.6.0",
+  "version": "4.0.0-alpha.1",
   "author": "Virtualdisplay <support@virtualdisplay.io>",
-  "browserslist": [
-    "last 2 Chrome versions",
-    "last 2 Firefox versions",
-    "last 2 Safari versions",
-    "last 2 Edge versions"
-  ],
-  "bugs": {
-    "url": "https://github.com/virtualdisplay-io/client/issues"
-  },
-  "bundledDependencies": [
-    "@virtualdisplay-io/logger"
-  ],
-  "dependencies": {
-    "@virtualdisplay-io/logger": "1.2.0",
-    "ajv": "8.17.1"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.31.0",
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/commit-analyzer": "^13.0.1",
-    "@semantic-release/exec": "7.1.0",
-    "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^11.0.3",
-    "@semantic-release/npm": "^12.0.2",
-    "@semantic-release/release-notes-generator": "^14.0.3",
-    "@types/node": "^24.0.14",
-    "@typescript-eslint/eslint-plugin": "^8.37.0",
-    "@typescript-eslint/parser": "^8.37.0",
-    "@virtualdisplay-io/shared-config": "^1.4.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "conventional-changelog-conventionalcommits": "9.0.0",
-    "eslint": "^9.31.0",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-jsx-a11y": "^6.10.2",
-    "eslint-plugin-prettier": "^5.5.1",
-    "eslint-plugin-unicorn": "^59.0.1",
-    "globals": "^16.3.0",
-    "jsdom": "^26.1.0",
-    "markdownlint-cli2": "^0.15.0",
-    "markdownlint-cli2-formatter-pretty": "^0.0.8",
-    "prettier": "^3.6.2",
-    "semantic-release": "^24.2.7",
-    "terser": "^5.43.1",
-    "typescript": "^5.8.3",
-    "vite": "^6.3.5",
-    "vite-bundle-visualizer": "^1.2.1",
-    "vite-plugin-dts": "^4.5.4",
-    "vitest": "^3.2.4"
-  },
+  "homepage": "https://virtualdisplay.io",
+  "license": "MIT",
+  "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -59,14 +13,17 @@
       "require": "./dist/virtualdisplay.client.cjs.js"
     }
   },
+  "main": "dist/virtualdisplay.client.cjs.js",
+  "module": "dist/virtualdisplay.client.es.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "schemas",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
+    "CHANGELOG.md"
   ],
-  "homepage": "https://github.com/virtualdisplay-io/client#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
   "keywords": [
     "3d",
     "iframe",
@@ -74,46 +31,5 @@
     "typescript",
     "visualization",
     "webgl"
-  ],
-  "license": "MIT",
-  "main": "dist/virtualdisplay.client.cjs.js",
-  "module": "dist/virtualdisplay.client.es.js",
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/virtualdisplay-io/client.git"
-  },
-  "scripts": {
-    "analyze": "vite-bundle-visualizer --template treemap --output stats.html --open false",
-    "build": "tsc -p tsconfig.build.json && vite build",
-    "coverage": "vitest run --coverage --reporter=verbose",
-    "coverage:feature": "vitest run test/feature --coverage --reporter=verbose",
-    "coverage:integration": "vitest run test/integration --coverage --reporter=verbose",
-    "coverage:unit": "vitest run test/unit --coverage --reporter=verbose",
-    "dev": "vite build --watch",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "pnpm run lint:eslint && pnpm run lint:md && pnpm run lint:types && pnpm run lint:format",
-    "lint:eslint": "eslint .",
-    "lint:eslint:fix": "eslint . --fix",
-    "lint:fix": "pnpm run lint:eslint:fix && pnpm run lint:md:fix && pnpm run lint:format:fix && npx fixpack",
-    "lint:format": "prettier --check .",
-    "lint:format:fix": "prettier --write .",
-    "lint:md": "markdownlint-cli2 '**/*.md' --config .markdownlint-cli2.jsonc",
-    "lint:md:fix": "markdownlint-cli2 '**/*.md' --config .markdownlint-cli2.jsonc --fix",
-    "lint:types": "tsc --noEmit",
-    "prepare": "node -e \"if (!process.env.CI) require('child_process').execSync('pnpm build', {stdio: 'inherit'})\"",
-    "release": "semantic-release",
-    "test": "vitest run",
-    "test:feature": "vitest run test/feature",
-    "test:integration": "vitest run test/integration",
-    "test:unit": "vitest run test/unit",
-    "test:watch": "vitest",
-    "type-check": "tsc --noEmit"
-  },
-  "type": "module",
-  "types": "dist/index.d.ts"
-}
+  ]
+}

package/README.npm.md

@@ -1,483 +0,0 @@
-# Virtualdisplay client
-
-TypeScript library for embedding interactive 3D product models in web
-applications.
-
-**Key features:**
-
-- Simple attribute-based API for product configurators
-- Fire-and-forget messaging with automatic state synchronization
-- Zero external dependencies (all bundled)
-- Works with any frontend framework or vanilla JavaScript
-
-## Installation
-
-```bash
-npm install @virtualdisplay.io/client
-# or
-pnpm add @virtualdisplay.io/client
-# or
-yarn add @virtualdisplay.io/client
-```
-
-## What's new in v3.1
-
-- Simplified message handling with unified event system
-- JSON Schema validation using AJV
-- Cleaner, more maintainable codebase
-- Improved TypeScript types
-- Better error messages with specific error codes
-
-## Quick start
-
-### Simple product (no options)
-
-```typescript
-import { VirtualdisplayClient } from '@virtualdisplay.io/client';
-
-// That's it! Your 3D model is now displayed
-const client = new VirtualdisplayClient({
-  parent: '#product-container',
-  license: 'your-license-key',
-  model: 'statue-model',
-});
-```
-
-### Configurable product (with options)
-
-```typescript
-import { VirtualdisplayClient } from '@virtualdisplay.io/client';
-
-// Create client instance
-const client = new VirtualdisplayClient({
-  parent: '#product-container',
-  license: 'your-license-key',
-  model: 'sneaker',
-});
-
-// Map product options to 3D parts
-client.setMapping({
-  attributes: [
-    {
-      name: 'Color',
-      values: [
-        { value: 'Red', nodeIds: ['laces_red', 'sole_red'], isSelected: true },
-        { value: 'Blue', nodeIds: ['laces_blue', 'sole_blue'] },
-      ],
-    },
-  ],
-});
-
-// Control via product options
-client.getAttribute('Color')?.select('Red');
-
-// Or store the attribute for multiple operations
-const sizeAttribute = client.getAttribute('Size');
-if (sizeAttribute) {
-  sizeAttribute.select('Large');
-}
-```
-
-## How it works
-
-The 3D server hosts the viewer in an iframe, keeping WebGL complexity isolated
-from your application. The client library handles all communication via
-postMessage and manages state locally using an attribute mapping system.
-
-**Key principles:**
-
-- **Iframe architecture**: 3D server loads the viewer independently
-- **Fire-and-forget**: Send messages without waiting for confirmation
-- **Attribute mapping**: Connect your product options to 3D model parts
-- **State synchronization**: Client and 3D server stay in sync automatically
-- **Domain-driven design**: Clean separation of concerns with simplified
-  architecture
-- **Event-driven**: Loosely coupled components communicate via events
-
-## Product options
-
-### When do you need mapping
-
-Before diving in, it's important to understand when you need attribute mapping:
-
-**No mapping needed:**
-
-- Static 3D models that always look the same
-- Product showcases without options
-- Architectural visualizations
-- Art pieces or sculptures
-- Single-configuration products
-
-**Mapping required:**
-
-- Products where users can change colors (different textures/materials per option)
-- Products with size options (different 3D meshes per size)
-- Modular products (parts that can be added/removed)
-- Any product where different options show different 3D elements
-
-### Attribute mapping
-
-The mapping system bridges your business logic with the 3D visualization. It
-serves multiple purposes:
-
-**Why mapping is essential:**
-
-- The 3D server is generic - it doesn't know your specific product options
-- Your business rules (stock, pricing, combinations) change independently from
-  the 3D model
-- You control exactly which parts of the model are shown for each option
-- You can group multiple 3D nodes (meshes, materials) into logical product
-  choices
-
-**How it works:** The mapping connects your product options to specific parts of
-the 3D model:
-
-```typescript
-client.setMapping({
-  attributes: [
-    {
-      name: 'Color',
-      values: [
-        {
-          value: 'Red',
-          nodeIds: ['mat_red_sole', 'mat_red_laces', 'mat_red_logo'],
-          isSelected: true,
-        },
-        {
-          value: 'Blue',
-          nodeIds: ['mat_blue_sole', 'mat_blue_laces', 'mat_blue_logo'],
-        },
-      ],
-    },
-    {
-      name: 'Material',
-      values: [
-        { value: 'Leather', nodeIds: ['material_leather_upper'] },
-        {
-          value: 'Canvas',
-          nodeIds: ['material_canvas_upper'],
-          isSelected: true,
-        },
-      ],
-    },
-  ],
-});
-```
-
-**Structure explained:**
-
-- `attribute` - A product feature like Color, Size, or Material
-- `value` - A specific option like Red, Blue, Small, or Large
-- `nodeIds` - The 3D model parts that represent this option
-- `isSelected` - Whether this option is selected by default
-
-**Example benefits:**
-
-```typescript
-// Group related 3D parts into one logical choice
-{
-  value: 'Red',
-  nodeIds: [
-    'mesh_sole_red',      // Red sole mesh
-    'material_laces_red', // Red laces material
-    'texture_logo_red',   // Red logo texture
-    'mesh_stitching_red'  // Red stitching details
-  ]
-}
-
-// The server automatically handles showing Red parts
-// and hiding Blue/Green parts when Red is selected
-```
-
-**Key advantages:**
-
-- Full control over what's visible without modifying the 3D model
-- Business logic stays in your application, not in the 3D server
-- Easy to update when products or availability changes
-- Group complex 3D structures into simple user choices
-
-**Need help with mapping?**
-
-- We help you connect your product catalog to your 3D models
-- Visual mapping tool coming soon to simplify this process
-- Contact <support@virtualdisplay.io> for mapping assistance
-
-### Complete flow
-
-Here's how the client, mapping system, and 3D server work together:
-
-**Phase by phase breakdown:**
-
-#### Phase 0: Initialization (always happens)
-
-- Client creates iframe and loads 3D server
-- Server initializes the 3D model with all nodes visible
-- Server sends complete node state to client
-- Client now knows about all available nodes in the model
-
-**Note:** For simple models without options, this is all you need!
-
-#### Phase 1: Configuration (only for configurable products)
-
-- You call `setMapping()` with your product structure
-- Client stores the attribute mapping locally
-- Client sends mutations for all `isSelected: true` values
-- Server applies these changes and hides non-selected options
-- Server sends back confirmed state
-- Local state updates based on server response
-- onChange callbacks fire for initial UI synchronization
-
-#### Phase 2: User interaction (only for configurable products)
-
-- User selects a different option in your UI
-- You call `getAttribute('Color').select('Blue')`
-- Client sends mutation request to server
-- Your code continues immediately (doesn't wait for server response)
-- Server updates the 3D model
-- Server sends back the confirmed state
-- Local state updates based on server response
-- onChange callbacks fire with the actual state
-- UI stays perfectly synchronized with 3D model
-
-**Important:** The pattern is identical for both initial mapping and user
-interactions. In both cases:
-
-1. Client sends mutations to server
-2. Server applies changes to 3D model
-3. Server sends back confirmed state
-4. Client updates local state based on server response
-5. onChange callbacks fire with the actual state
-
-This ensures the server remains the single source of truth for all state
-changes.
-
-## Advanced usage
-
-### Live state synchronization
-
-Keep your UI in sync with the 3D server state using onChange callbacks:
-
-```typescript
-const colorAttribute = client.getAttribute('Color');
-
-colorAttribute?.getValues().forEach((value) => {
-  value.onChange = () => {
-    // Update UI when state changes
-    updateButton(value.value, value.isSelected);
-  };
-});
-```
-
-### Mapping validation
-
-Validate your mapping configuration during development:
-
-```typescript
-import { mappingSchema } from '@virtualdisplay.io/client';
-import Ajv from 'ajv';
-
-const validate = new Ajv().compile(mappingSchema);
-if (!validate(myMapping)) {
-  console.error('Invalid mapping:', validate.errors);
-}
-```
-
-## Real-world integration examples
-
-### CMS integration
-
-The Virtualdisplay client is CMS-agnostic. Store the mapping configuration in
-your CMS alongside your product data:
-
-```typescript
-// Fetch product with 3D mapping from your CMS
-const product = await fetch('/api/products/sneaker-pro').then((r) => r.json());
-
-// Use the stored mapping directly
-client.setMapping(product.server3dMapping);
-```
-
-**Best practices:**
-
-- Store the complete mapping configuration with each product
-- Update mappings when product options or availability changes
-- Let your CMS handle filtering of unavailable combinations
-- Version your mappings when 3D models are updated
-
-## Example
-
-See the [color configurator example](./examples/color-configurator/) for a
-complete working implementation that demonstrates:
-
-- Setting up the client
-- Defining attribute mappings
-- Binding UI controls to attributes
-- Real-time state synchronization
-
-## API reference
-
-### ClientOptions
-
-```typescript
-interface ClientOptions {
-  parent: string | HTMLElement; // Container element or selector
-  license: string; // Your license key
-  model: string; // Model ID to load
-  debug?: boolean; // Enable debug logging (default: false)
-  language?: string; // Language for UI inside the iframe (default: 'nl', supported: 'nl', 'en', 'de')
-}
-```
-
-### Methods
-
-#### `setMapping(configuration: MappingConfiguration): void`
-
-Configure attribute-to-node mapping for product variants. This is the primary
-method for setting up your product configurator. Call this once with your
-complete configuration - the client efficiently handles all updates.
-
-```typescript
-client.setMapping({
-  attributes: [
-    {
-      name: 'Color',
-      values: [
-        { value: 'Red', nodeIds: ['node1', 'node2'], isSelected: true },
-        { value: 'Blue', nodeIds: ['node3', 'node4'] },
-      ],
-    },
-  ],
-});
-```
-
-#### `getAttribute(name: string): AttributeSelector | undefined`
-
-Get an attribute selector for changing values. Returns undefined if the
-attribute doesn't exist.
-
-```typescript
-const colorAttr = client.getAttribute('Color');
-if (colorAttr) {
-  colorAttr.select('Blue');
-}
-```
-
-#### `destroy(): void`
-
-Clean up and remove the client connection. Always call this when unmounting your
-component.
-
-```typescript
-// React example
-useEffect(() => {
-  const client = new VirtualdisplayClient({ ... });
-  return () => client.destroy();
-}, []);
-```
-
-### Types
-
-```typescript
-interface MappingConfiguration {
-  attributes: AttributeConfig[];
-}
-
-interface AttributeConfig {
-  name: string; // Attribute name (e.g., 'Color')
-  values: AttributeValueConfig[]; // Possible values
-}
-
-interface AttributeValueConfig {
-  value: string; // Value name (e.g., 'Red')
-  nodeIds: string[]; // 3D node IDs for this value
-  isSelected?: boolean; // Default selection state
-}
-
-class AttributeSelector {
-  // Properties
-  name: string; // Attribute name (getter)
-  currentValue: string | undefined; // Current selected value (getter)
-  availableValues: string[]; // All possible values (getter)
-
-  // Methods
-  select(value: string): AttributeSelector; // Select a value (chainable)
-  onChange(callback: () => void): AttributeSelector; // Register change callback (chainable)
-  getValues(): AttributeValue[]; // Get all AttributeValue objects
-  getValue(value: string): AttributeValue | undefined; // Get specific AttributeValue
-}
-
-class AttributeValue {
-  // Properties
-  value: string; // The value name (e.g., 'Red') - getter
-  nodeList: string[]; // Associated 3D node IDs - getter
-  isSelected: boolean; // Current selection state - getter
-  onChange?: () => void; // Callback when selection changes - property
-}
-```
-
-#### NodeSelector
-
-The client exports `NodeSelector` for direct node manipulation. This is intended
-for specialized tools like mapping editors and inspectors, not for typical
-product configurators. For product configurators, use the attribute-based API.
-
-### Error handling
-
-The client throws `VirtualdisplayError` for known error conditions:
-
-```typescript
-import {
-  VirtualdisplayClient,
-  VirtualdisplayError,
-  ERROR_CODES,
-} from '@virtualdisplay.io/client';
-
-try {
-  client.getAttribute('NonExistent').select('Value');
-} catch (error) {
-  if (error instanceof VirtualdisplayError) {
-    switch (error.code) {
-      case ERROR_CODES.ATTRIBUTE_NOT_FOUND:
-        console.error('Attribute does not exist');
-        break;
-      case ERROR_CODES.NO_MAPPING:
-        console.error('Call setMapping() first');
-        break;
-      // Handle other error codes
-    }
-  }
-}
-```
-
-**Error codes:**
-
-- `NO_MAPPING` - No mapping configuration set
-- `ATTRIBUTE_NOT_FOUND` - Requested attribute doesn't exist
-- `VALUE_NOT_FOUND` - Requested value doesn't exist for attribute
-- `INVALID_MAPPING` - Mapping configuration is invalid
-- `PARENT_NOT_FOUND` - Parent element for iframe not found
-
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
-
-## Troubleshooting
-
-### Common issues
-
-**Iframe not loading:**
-
-- Check that the parent element exists in the DOM
-- Verify your license key is valid
-- Ensure the model ID matches your license
-
-**Attributes not working:**
-
-- Make sure you call `setMapping()` before using `getAttribute()`
-- Verify attribute names match exactly (case-sensitive)
-- Check that node IDs in your mapping exist in the 3D model
-
-## Changelog
-
-See the [GitHub releases](https://github.com/virtualdisplay-io/client/releases)
-for release notes and version history.

package/node_modules/@virtualdisplay-io/logger/CHANGELOG.md

@@ -1,82 +0,0 @@
-# [1.2.0](https://github.com/virtualdisplay-io/logger/compare/v1.1.2...v1.2.0) (2025-06-13)
-
-
-### Features
-
-* simplify logger API by removing environment detection ([#11](https://github.com/virtualdisplay-io/logger/issues/11)) ([8580f93](https://github.com/virtualdisplay-io/logger/commit/8580f93eb2b9eb7dd6fc6b4ae90b5512ac9b55bc))
-
-## [1.1.2](https://github.com/virtualdisplay-io/logger/compare/v1.1.1...v1.1.2) (2025-06-08)
-
-
-### Bug Fixes
-
-* resolve linting issues in console-transport ([#8](https://github.com/virtualdisplay-io/logger/issues/8)) ([10b8f1a](https://github.com/virtualdisplay-io/logger/commit/10b8f1adaf3ed04efb6c46ace9194f39c8d60b00))
-
-## [1.1.1](https://github.com/virtualdisplay-io/logger/compare/v1.1.0...v1.1.1) (2025-06-08)
-
-
-### Bug Fixes
-
-* remove hardcoded VirtualDisplay prefix from console transport ([f3734d5](https://github.com/virtualdisplay-io/logger/commit/f3734d5f3b66c9a1e190a13e7c91f9021543324c))
-
-# [1.1.0](https://github.com/virtualdisplay-io/logger/compare/v1.0.1...v1.1.0) (2025-06-08)
-
-
-### Features
-
-* update semantic-release config to match client library ([ec76794](https://github.com/virtualdisplay-io/logger/commit/ec7679460926ec5423fad52a9859ef34d547a9ef))
-
-## [1.0.1](https://github.com/virtualdisplay-io/logger/compare/v1.0.0...v1.0.1) (2025-06-08)
-
-
-### Bug Fixes
-
-* ensure production build is created before release ([#7](https://github.com/virtualdisplay-io/logger/issues/7)) ([459af10](https://github.com/virtualdisplay-io/logger/commit/459af105c3e6e123b75f4cb96bbaa5c89722fdb8))
-
-# 1.0.0 (2025-06-08)
-
-
-### Features
-
-* initial Virtual Display Logger implementation ([dcbda81](https://github.com/virtualdisplay-io/logger/commit/dcbda81cf31a097eed8df61a6d5294a8b0d9f1c4))
-
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-### Added
-- Initial release of @virtualdisplay-io/logger
-- Core logging functionality with debug, info, warn, error levels
-- Singleton pattern with Logger.getInstance()
-- Child logger support with context inheritance
-- Multiple transport system (Console, Memory)
-- Formatter system (Context, JSON)
-- Environment-aware logging
-- Test environment auto-detection
-- TypeScript support with full type definitions
-- Comprehensive test suite with 100% coverage
-- Zero dependencies
-- Browser and Node.js compatibility
-- Memory transport with querying and export capabilities
-- Global muting functionality
-- Configurable log levels and filtering
-
-### Features
-- **ConsoleTransport**: Console output with colors and timestamps
-- **MemoryTransport**: In-memory log storage with search and export
-- **ContextFormatter**: Appends context data to messages
-- **JSONFormatter**: Full JSON serialization of log entries
-- **Child Loggers**: Hierarchical logging with context merging
-- **Smart Environment Detection**: Automatic test environment detection
-- **Performance Optimized**: Zero runtime dependencies, efficient memory usage
-- **Developer Experience**: Comprehensive TypeScript types, clear API
-
-## [1.0.0] - 2025-01-XX
-
-### Added
-- Initial stable release