Refactor Packable Format with AssetStore, Caching & Checksum Improvements

[afshawnlotfi]

Summary

This PR introduces a major refactor of the meshly serialization format, replacing the legacy packed array format with a cleaner, content-addressable asset-based approach. It also adds the AssetStore for file-based asset management with deduplication, enhances caching mechanisms, and improves the overall developer experience.

Key Changes

🏗️ New Serialization Format

• New zip structure: metadata/data.json + metadata/schema.json + assets/{checksum}.bin
• Array references: Arrays now use $ref objects with embedded metadata (shape, dtype, itemsize)
• JSON Schema integration: Schema file provides encoding hints (vertex_buffer, index_sequence, array)
• Removes old packed array format (metadata length prefix + JSON metadata + encoded bytes)

📦 AssetStore Implementation

• New AssetStore class for file-based asset management with content-addressable storage
• Deduplication: Assets are stored by checksum, avoiding duplicate storage
• save/load methods: Added save() and load() convenience methods to Packable
• Ensures asset directory creation before writing
• Enhanced __repr__ for better debugging

⚡ Caching & Performance

• New AssetCache class with IndexedDB-backed LRU caching for browser environments
• Memory cache layer for hot assets with configurable limits
• createCachedProvider() helper for wrapping fetch functions with caching
• Automatic eviction based on item count and total size limits

🔧 API Improvements

• TypeScript: Added ExportConstants, JsonSchema, JsonSchemaUtils for format handling
• TypeScript: ArrayUtils.decodeFromRefInfo() for decoding from new $ref format
• TypeScript: Removed DataHandler, CachedAssetLoader in favor of simpler AssetProvider
• Python: Simplified Packable.extract() and Packable.reconstruct() APIs
• Renamed marker fields: markerIndices → markers, markerOffsets → markerSizes, markerTypes → markerCellTypes

🧪 Test Improvements

• Refactored tests to use Array type consistently
• Improved Resource handling in tests
• Added new test_asset_store.py for AssetStore coverage
• Added Python integration test fixtures for TypeScript cross-platform testing
• Removed deprecated tests (test_extract_assets.py, test_load_array.py)

Breaking Changes

• TypeScript: DataHandler and CachedAssetLoader removed—use AssetCache and AssetProvider instead
• TypeScript: MeshMetadata and MeshSize removed—metadata is now embedded in $ref objects
• TypeScript: Marker field renames (markerIndices → markers, etc.)
• Python: New zip format is not backward-compatible with legacy format

Migration Guide

Python:

# Before - manual extract/reconstruct
data, assets = packable.extract()

# After - simplified with AssetStore
store = AssetStore("/path/to/assets")
packable.save(store, "output.zip")
loaded = Packable.load(store, "output.zip")