feat(geo3d): add opt-in Giro3D renderer with advanced API and self-hosted assets v3

[p4535992]

Summary

• Add an explicitly opt-in Geo3D renderer entry point powered by Giro3D for LAS/LAZ, COPC, CityJSON, GeoTIFF/COG, 3D Tiles, and 3TZ without adding it silently to existing Full packages.
• Preserve streaming and HTTP byte-range behavior, regular TIFF fallback, relative multi-resource dataset URLs, and bounded/safe 3TZ handling.
• Keep decoder Worker/WASM and runtime assets self-hosted while exposing typed Giro3D lifecycle hooks and retaining File Viewer ownership of cancellation, resources, and disposal.
• Add real-browser, installed-consumer, Worker ownership, lifecycle, cache/memory, fixture, range-request, archive, CRS, and format-routing regression coverage.
• Harden large tiled-TIFF metadata inspection, document/root-relative dataset URL resolution, and exact propagation of AbortSignal.reason.

Related issue

Closes #324

Change classification

• User-visible UI or rendering change
• Non-visual change
• File-format or renderer behavior
• Public API, package, Worker, WASM, or deployment-path change

Verification

Check	Result
pnpm install --frozen-lockfile	Pass
pnpm test:geo3d-entry	Pass — routing/format tests passed and the dedicated Geo3D Node suite reports 110/110 passed, 0 failed, 0 skipped
pnpm --filter @file-viewer/renderer-3d verify:geo3d-browser	Pass — real Giro3D browser validation against workspace output and a physical installed consumer
Geo3D workspace browser cases	Pass — 45/45
Geo3D installed-consumer browser cases	Pass — 45/45
pnpm build	Pass
pnpm type-check	Pass
pnpm test	Pass — full repository regression suite
Core/component integration regressions	Pass
pnpm docs:build	Pass
pnpm verify:github-governance	Pass — 48 passed, 0 failed, 1 existing not-applicable skip
Built demo browser smoke	Pass
Strict Geo3D fixture and HTTP range validation	Pass
Compressed LAZ/COPC fixture regressions	Pass — 19/19 passed
Geo3D focused validation workflow	Pass
Geo3D branch/full-workspace validation workflow	Pass

All recorded full-workspace validation commands completed with exit code 0, including install, Geo3D entry validation, Playwright/browser validation, Rust/WASM prerequisites, build, type-check, root tests, integration tests, documentation, governance, demo browser smoke, fixture installation, strict fixture/range validation, and compressed-fixture tests.

Sample / fixture evidence

• Public Geo3D fixture set: https://github.com/p4535992/file-viewer/tree/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d

• LAS fixture: https://github.com/p4535992/file-viewer/blob/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/sample.las

• COPC fixture: https://github.com/p4535992/file-viewer/blob/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/probe.copc.laz

• GeoTIFF/COG fixture: https://github.com/p4535992/file-viewer/blob/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/sample-cog.tif

• GeoTIFF/non-COG fixture: https://github.com/p4535992/file-viewer/blob/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/geotiff-noncog.tif

• Ordinary TIFF fallback fixture: https://github.com/p4535992/file-viewer/blob/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/regular.tif

• CityJSON fixture: https://github.com/p4535992/file-viewer/blob/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/sample.city.json

• 3D Tiles fixtures: https://github.com/p4535992/file-viewer/tree/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/tiles3d

• 3TZ fixture: https://github.com/p4535992/file-viewer/blob/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/sample.3tz

• COPC browser-rendering evidence: https://github.com/p4535992/file-viewer/blob/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/result-copc.png

• Geo3D COPC rendering: https://raw.githubusercontent.com/p4535992/file-viewer/feature/rendition-giro3d-v3/packages/renderers/3d/test/fixtures/geo3d/result-copc.png

• Strict fixture validation completed successfully with the pinned development dependencies.

• Compressed LAZ/COPC regression suite: 19/19 passed with lazrs==0.8.2.

• LAZ validation decoded all point records and verified sequential reads and random point seeking where applicable.

• COPC validation verified hierarchy pages, octree levels, independently decoded chunks, node bounds, chunk tables, and direct hierarchy byte ranges.

• Streaming COPC HTTP-range validation transferred 2,314 of 18,133 bytes (12.761%) for the tested partial access path, using HTTP 206 responses and no full-file request.

• 3TZ validation verified archive CRC and index structure.

Visual evidence

The screenshot above was produced by the successful real-browser Geo3D validation of revision.

Risk and compatibility

• Affected packages/formats: @file-viewer/renderer-3d/geo3d; LAS/LAZ, COPC, CityJSON, GeoTIFF/COG, 3D Tiles, and 3TZ.
• Compatibility or migration risk: the renderer is explicitly opt-in. Existing consumers are unaffected unless Geo3D is registered. Ordinary TIFF continues to use the existing image renderer unless geographic TIFF metadata is detected.
• Streaming assumptions: remote COPC/COG sources require valid HTTP byte-range semantics and appropriate CORS exposure when cross-origin access is used.
• Deployment: decoder and Worker assets remain self-hosted. Installed-consumer validation passed the asset-copy command and custom deployment-path checks.
• Package compatibility: a physically installed consumer passed with runtime modules resolved from the installed packages rather than the workspace.
• Engine compatibility: owned source adapters intentionally target the reviewed Giro3D 2.0.4 implementation and fail closed when pinned engine internals change.
• Rollback: remove or disable the opt-in geo3d entry point and specialist routing; existing default renderers remain available.

Checklist

• I added or updated focused automated coverage, or explained why it is not needed.
• I updated user-facing documentation or release notes when behavior or API changed, or marked them not applicable.
• I verified offline/private-deployment paths when changing Worker, WASM, fonts, vendor assets, or URLs.
• I did not commit secrets, customer files, private samples, generated caches, or unrelated changes.

[wybaby168]

The contribution was checked against real local inputs and is not ready to land unchanged. Blob input is lost through the File-only normalization path, and nested 3TZ resources need enforceable local-archive boundaries rather than allowing external resources to escape through embedded tile/model loaders. The continuation also closes bounded decoding and cancellation gaps that were exercised in the real browser and packed-consumer checks.

Draft #338 preserves the contributor commit and repairs these runtime boundaries together with the coherent direct sanitizer dependencies. Its final head 9557eb375cfde1b9c38851f73506f5f58111ee6f passed the completed native/browser/cold-consumer checks, 114 Geo3D regressions, 298 Vitest tests with one existing skip, and full Public CI, focused CI, Security, CodeQL and governance. No skip or unexecuted check is counted as passing.

Please review the verified continuation's explicit input, resource and cancellation boundaries before considering a merge. Neither this original PR nor the repair has been merged or published.