Add asset graph foundations

[alexchuber]

Summary

Adds the initial graph-based API.

• adds typed blocks, ports, node assets, execution contexts, and resource lifetimes
• adds glTF/GLB input and output blocks
• adds KTX2 texture compression and Draco geometry compression
• adds unit and integration coverage

Testing

• pnpm test
• pnpm format:check
• pnpm lint
• pnpm build

[Copilot]

🟡 Changes recommended

There are verified correctness/documentation/tooling issues (notably the Draco encoder Node init __dirname handling, inaccurate docs examples/status labels, and config/CI hygiene) that should be addressed before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Introduces the initial graph-based asset pipeline API, centered on typed Blocks connected via ports and executed as a captured NodeAsset with per-execution NodeAssetContext inputs and scoped resource lifetimes. It also adds first-party glTF/GLB IO blocks plus opt-in texture (KTX2) and geometry (Draco) compression, with accompanying docs and test coverage.

Changes:

• Add core graph runtime: block definitions/config, connection point typing, node asset execution, execution contexts, and resource scoping/disposal.
• Add glTF/GLB input/output blocks, KTX2 texture compression transform, and Draco encoder source block for glTF export compression.
• Add unit + integration tests and update tooling/config (deps, Vite externals, TypeDoc output, linting rules, docs).

File summaries

File	Description
vite.config.ts	Externalizes runtime/platform-specific deps (e.g., sharp, encoder) from bundling.
typedoc.json	Moves TypeDoc output under docs/typedocs.
tsconfig.json	Updates TypeScript include list (now includes an examples path).
tests/unit/nodeAsset.test.ts	Unit tests for NodeAsset execution, contexts, and resource lifecycle behavior.
tests/unit/block.test.ts	Unit tests for Block config/defaults and port connection semantics.
tests/integration/gltfOutput.test.ts	Integration coverage for GLB export and texture transform preservation.
tests/integration/gltfInput.test.ts	Integration coverage for glTF/GLB loading and HTTP dependency behavior.
tests/integration/dracoCompression.test.ts	Integration coverage for Draco compression opt-in behavior.
tests/integration/compressTextures.test.ts	Integration coverage for KTX2 texture compression transform.
tests/integration/compressedGlbPipeline.test.ts	End-to-end integration test for combined KTX2 + Draco pipeline via public API.
tests/helpers/numberBlocks.ts	Helper block/type definitions for numeric pipeline tests.
tests/helpers/gltf.ts	Helpers to generate embedded glTF/GLB data URIs for tests.
tests/helpers/glb.ts	Helpers to parse GLB structure and assert embedded KTX2 image bytes.
tests/.gitkeep	Keeps tests/ directory tracked.
src/resources/resourceScope.ts	Implements per-execution resource resolution, caching, and disposal ordering.
src/resources/resource.ts	Defines Resource types and dependency/value typing utilities.
src/resources/nullEngineResource.ts	Provides a NullEngine resource for headless Babylon scene loading.
src/nodeAsset/nodeAssetContext.ts	Adds per-execution input injection with runtime validation.
src/nodeAsset/nodeAsset.ts	Captures graph topology from an output block and executes it with scoped resources.
src/index.ts	Exposes the initial public API surface (blocks + node asset types).
src/blocks/gltfOutputBlock.ts	Implements GLB serialization with optional Draco compression hookup.
src/blocks/gltfInputBlock.ts	Implements glTF/GLB loading (data/http/local) into a Babylon scene.
src/blocks/dracoEncoderBlock.ts	Provides Babylon’s default Draco encoder and registers exporter extension.
src/blocks/compressTexturesBlock.ts	Implements texture re-encoding to KTX2 (BasisU), with Node sharp decode path.
src/block/connectionPointType.ts	Adds connection point typing and built-in types (URL, File, Scene, DracoEncoder).
src/block/blockDefinition.ts	Adds typed block/source definitions, config descriptors, and helpers.
src/block/block.ts	Implements blocks, input/output ports, connection validation, and cycle checks.
README.md	Simplifies README to focus on description + contributing link.
pnpm-lock.yaml	Adds lockfile entries for new deps (encoder, sharp, transitive additions).
package.json	Adds sideEffects: false, adds new deps, and renames TypeDoc script to typedocs.
eslint.config.mjs	Adds custom rule enforcing underscore prefix for @internal APIs.
docs/usage.md	Adds usage documentation for blocks, connections, node assets, and examples.
CONTRIBUTING.md	Minor wording update around pre-PR checks.
AGENTS.md	Expands agent/dev guidelines (including testing guidance).
.prettierignore	Stops ignoring all docs/, only ignores generated docs/typedocs.
.gitignore	Stops ignoring all docs/, only ignores docs/typedocs; updates ignored local dirs.
.github/workflows/ci.yml	Removes the GitHub Actions CI workflow.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (1)

tests/unit/nodeAsset.test.ts:303

• AGENTS.md discourages toHaveBeenCalled/toHaveBeenCalledOnce assertions because they test implementation details. Prefer an assertion on observable behavior (or at least avoid the toHaveBeenCalled matcher family).

• Files reviewed: 33/37 changed files
• Comments generated: 6
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.