@selvajs/visualization 1.3.0 → 1.4.0

package/dist/gpu-dispose-DrN-ryj5.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"gpu-dispose-DrN-ryj5.cjs","names":["THREE","THREE"],"sources":["../src/shared/errors.ts","../src/shared/logger.ts","../src/shared/geometry.ts","../src/shared/gpu-ownership.ts","../src/shared/gpu-capabilities.ts","../src/shared/gpu-dispose.ts"],"sourcesContent":["/**\n * Errors for the visualization package. Replaces `@selvajs/compute`'s `RhinoComputeError`, which\n * mis-named failures on paths (e.g. the plugin WebSocket) that never touch Rhino.Compute. `code`\n * values match compute's so existing catch-sites keep working.\n */\n\nexport const ErrorCodes = {\n\t/** Structural check failed: bad magic bytes, out-of-window index, malformed metadata. */\n\tVALIDATION_ERROR: 'VALIDATION_ERROR',\n\tINVALID_STATE: 'INVALID_STATE',\n\t/** No `DecompressionStream`, no WebGL context, etc. */\n\tENVIRONMENT_ERROR: 'ENVIRONMENT_ERROR',\n\tINVALID_CONFIG: 'INVALID_CONFIG',\n\t/** Base64 input could not be decoded. */\n\tENCODING_ERROR: 'ENCODING_ERROR',\n\tUNKNOWN_ERROR: 'UNKNOWN_ERROR'\n} as const;\n\nexport type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];\n\nexport class VisualizationError extends Error {\n\tpublic readonly code: ErrorCode;\n\tpublic readonly context?: Record<string, unknown>;\n\tpublic readonly originalError?: Error;\n\n\tconstructor(\n\t\tmessage: string,\n\t\tcode: ErrorCode = ErrorCodes.UNKNOWN_ERROR,\n\t\toptions?: { context?: Record<string, unknown>; originalError?: Error }\n\t) {\n\t\tsuper(message);\n\t\tthis.name = 'VisualizationError';\n\t\tthis.code = code;\n\t\tthis.context = options?.context;\n\t\tthis.originalError = options?.originalError;\n\t\tif (options?.originalError) {\n\t\t\t(this as { cause?: unknown }).cause = options.originalError;\n\t\t}\n\t}\n}\n","/**\n * Logging facility for the visualization package. Deliberately local rather than imported from\n * `@selvajs/compute` (logging isn't a compute concern). Mirrors compute's logger shape so a host\n * wanting one sink for both can call `setLogger(computeLogger.getLogger())`.\n */\n\nimport { VisualizationError, ErrorCodes } from './errors.js';\n\nexport interface Logger {\n\tdebug(message: string, ...args: unknown[]): void;\n\tinfo(message: string, ...args: unknown[]): void;\n\twarn(message: string, ...args: unknown[]): void;\n\terror(message: string, ...args: unknown[]): void;\n}\n\nclass NoOpLogger implements Logger {\n\tdebug(): void {}\n\tinfo(): void {}\n\twarn(): void {}\n\terror(): void {}\n}\n\nclass ConsoleLogger implements Logger {\n\tdebug(message: string, ...args: unknown[]): void {\n\t\t// eslint-disable-next-line no-console -- this class exists to be the console sink\n\t\tconsole.debug(message, ...args);\n\t}\n\n\tinfo(message: string, ...args: unknown[]): void {\n\t\tconsole.info(message, ...args);\n\t}\n\n\twarn(message: string, ...args: unknown[]): void {\n\t\tconsole.warn(message, ...args);\n\t}\n\n\terror(message: string, ...args: unknown[]): void {\n\t\tconsole.error(message, ...args);\n\t}\n}\n\n// Defaults to no-op: a library that writes to the console uninvited is a nuisance in a host with\n// its own logging. Opt in with setLogger or enableDebugLogging.\nlet internalLogger: Logger = new NoOpLogger();\n\n// Call per-use rather than caching — the sink is settable at any time.\nexport function getLogger(): Logger {\n\treturn internalLogger;\n}\n\n// Validates logger shape up front: failing here beats a confusing \"getLogger().debug is not a\n// function\" at some later, unrelated call site.\nexport function setLogger(logger: Logger | Console | null): void {\n\tif (logger === null) {\n\t\tinternalLogger = new NoOpLogger();\n\t\treturn;\n\t}\n\n\tconst missing = (['debug', 'info', 'warn', 'error'] as const).filter(\n\t\t(method) => typeof (logger as unknown as Record<string, unknown>)[method] !== 'function'\n\t);\n\tif (missing.length > 0) {\n\t\tthrow new VisualizationError(\n\t\t\t`Logger is missing required method(s): ${missing.join(', ')}. A logger must implement debug, info, warn and error.`,\n\t\t\tErrorCodes.INVALID_CONFIG,\n\t\t\t{ context: { missingMethods: missing } }\n\t\t);\n\t}\n\n\tinternalLogger = logger as Logger;\n}\n\nexport function enableDebugLogging(): void {\n\tsetLogger(new ConsoleLogger());\n}\n","import * as THREE from 'three';\n\nimport { getLogger } from './logger.js';\n\n// parse/ needs these and must never import upward from render/, so they live in shared/ instead\n// of render's three-helpers.\n\nexport function parseColor(colorString: string): THREE.Color {\n\tif (!colorString || typeof colorString !== 'string') {\n\t\tgetLogger().warn(`Invalid color input: ${colorString}, using white`);\n\t\treturn new THREE.Color(0xffffff);\n\t}\n\n\tconst trimmed = colorString.trim();\n\n\tif (/^#?[0-9A-Fa-f]{6}$/.test(trimmed)) {\n\t\ttry {\n\t\t\tconst hex = trimmed.startsWith('#') ? trimmed : `#${trimmed}`;\n\t\t\treturn new THREE.Color(hex);\n\t\t} catch {\n\t\t\tgetLogger().warn(`Invalid hex color: ${colorString}, using white`);\n\t\t\treturn new THREE.Color(0xffffff);\n\t\t}\n\t}\n\n\tif (trimmed.includes(',')) {\n\t\tconst rgb = trimmed.split(',').map((c) => parseInt(c.trim(), 10));\n\t\tif (rgb.length === 3 && rgb.every((n) => !isNaN(n) && n >= 0 && n <= 255)) {\n\t\t\treturn new THREE.Color(rgb[0] / 255, rgb[1] / 255, rgb[2] / 255);\n\t\t}\n\t}\n\n\t// `new THREE.Color(name)` never throws on unknown names (it logs its own warning and leaves the\n\t// color white), so validate against three's CSS name table instead.\n\tconst named = trimmed.toLowerCase();\n\tif (named in THREE.Color.NAMES) {\n\t\treturn new THREE.Color(THREE.Color.NAMES[named as keyof typeof THREE.Color.NAMES]);\n\t}\n\n\tgetLogger().warn(`Invalid color string: ${colorString}, using white`);\n\treturn new THREE.Color(0xffffff);\n}\n\n/** Defaults to `z` (Rhino's up axis); pass an explicit axis when the scene uses a different `sceneUp`. */\nexport function applyOffset(\n\tmeshes: THREE.Object3D[],\n\toffset: number,\n\taxis: 'x' | 'y' | 'z' = 'z'\n): void {\n\tmeshes.forEach((mesh) => {\n\t\tmesh.position[axis] -= offset;\n\t});\n}\n\nexport function computeCombinedBoundingBox(meshes: THREE.Object3D[]): THREE.Box3 {\n\tconst combinedBoundingBox = new THREE.Box3();\n\tif (meshes.length === 0) return combinedBoundingBox;\n\tmeshes.forEach((mesh) => {\n\t\tmesh.updateMatrixWorld(true);\n\t\tconst bbox = new THREE.Box3().setFromObject(mesh);\n\t\tcombinedBoundingBox.union(bbox);\n\t});\n\treturn combinedBoundingBox;\n}\n","import type * as THREE from 'three';\n\n// ============================================================================\n// GPU resource ownership — the single rule every disposal path obeys\n// ============================================================================\n\n/**\n * A GPU resource has exactly one owner: a **module singleton** (nobody ever frees it) or the\n * **scene** (freed on teardown). Every disposal path asks {@link canDisposeMaterial} and disposes\n * only if true. Geometries and textures are always scene-owned, so they have no claim to check.\n */\n\n// Module-scope singletons from `render/three-materials.ts`, shared across meshes and solves —\n// disposing one would free textures still in use and force a recompile. Held here (not imported\n// there) to avoid an import cycle.\nconst protectedMaterials = new Set<THREE.Material>();\n\n/** Register materials as never-disposable. Called once by `render/three-materials.ts`. */\nexport function protectMaterials(materials: Iterable<THREE.Material>): void {\n\tfor (const material of materials) protectedMaterials.add(material);\n}\n\n/** True when `material` is scene-owned (not one of the protected singletons). */\nexport function canDisposeMaterial(material: THREE.Material | undefined): boolean {\n\tif (!material) return false;\n\treturn !protectedMaterials.has(material);\n}\n","// ============================================================================\n// GPU capabilities — published by the renderer, read by whoever needs them\n// ============================================================================\n\n// Lets a renderer publish GPU capabilities (max anisotropy) without `render/` and `parse/` importing\n// each other: the renderer publishes on init, interested parties subscribe.\n\ntype AnisotropyObserver = (value: number) => void;\n\nconst observers = new Set<AnisotropyObserver>();\n\n// Module load order between layers isn't guaranteed, so a subscriber arriving after init still\n// needs the current value rather than waiting for a second renderer to publish.\nlet maxAnisotropy = 1;\n\nexport function publishMaxAnisotropy(value: number): void {\n\tconst next = Math.max(1, value);\n\tif (next === maxAnisotropy) return;\n\tmaxAnisotropy = next;\n\tfor (const observe of observers) observe(next);\n}\n\n/** Fires immediately with the current value (1 until a renderer has reported), then on every change. */\nexport function observeMaxAnisotropy(observe: AnisotropyObserver): () => void {\n\tobservers.add(observe);\n\tobserve(maxAnisotropy);\n\treturn () => observers.delete(observe);\n}\n","import * as THREE from 'three';\n\nimport { canDisposeMaterial } from './gpu-ownership.js';\n\n// ============================================================================\n// The disposal walkers — every teardown path in the package goes through these\n// ============================================================================\n\n/** Frees a material and its textures, respecting ownership (`./gpu-ownership.ts`). */\nexport function disposeMaterial(material: THREE.Material): void {\n\tif (!canDisposeMaterial(material)) return;\n\n\tfor (const value of Object.values(material)) {\n\t\tif (value instanceof THREE.Texture) {\n\t\t\tvalue.dispose();\n\t\t}\n\t}\n\tmaterial.dispose();\n}\n\nfunction disposeMaterials(material: THREE.Material | THREE.Material[] | undefined): void {\n\tif (!material) return;\n\tif (Array.isArray(material)) material.forEach(disposeMaterial);\n\telse disposeMaterial(material);\n}\n\nexport interface DisposeOptions {\n\t/** Free materials and their textures too. Default true; the solve memo passes false. */\n\tmaterials?: boolean;\n\t/** Called for each geometry before disposal, so a subsystem can free derived resources keyed on it (e.g. edge caches). */\n\tonGeometry?: (geometry: THREE.BufferGeometry) => void;\n}\n\n/**\n * Frees the GPU resources of an object subtree, respecting ownership. **The only traversal that\n * should dispose scene content** — a second disposing `traverse` risks missing an ownership guard.\n */\nexport function disposeObjectTree(root: THREE.Object3D, options: DisposeOptions = {}): void {\n\tconst { materials = true } = options;\n\n\troot.traverse((object) => {\n\t\tconst renderable = object as Partial<THREE.Mesh> & THREE.Object3D;\n\t\tif (!renderable.geometry && !renderable.material) return;\n\n\t\tif (renderable.geometry) {\n\t\t\trenderable.geometry?.dispose();\n\t\t}\n\n\t\tif (materials) disposeMaterials(renderable.material);\n\t});\n}\n"],"mappings":"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"}