@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/dist/index.mjs

@@ -0,0 +1,169 @@
+import { Camera, DirectionalLight, Instances, Layer, MeshFilter, MeshRenderer, PointLight, PointLightShadow, Points, Lines, PostProcessParams, SceneInstance, SkyboxBackground, Skylight, SortKey, SpotLight, Visibility } from './chunk-YEJIUW7D.mjs';
+export { ANTIALIAS_FXAA, ANTIALIAS_MSAA, ANTIALIAS_NONE, BLOOM_DISABLED, BLOOM_ENABLED, CAMERA_PROJECTION_ORTHOGRAPHIC, CAMERA_PROJECTION_PERSPECTIVE, Camera, DEFAULT_STANDARD_PROFILE, DirectionalLight, Instances, Layer, Lines, MeshFilter, MeshRenderer, PointLight, PointLightShadow, PointShapeValue, Points, PostProcessParams, RENDER_PHASE_CATALOG, SKYBOX_MODE_CUBEMAP, SceneInstance, SkyboxBackground, Skylight, SortKey, SpotLight, TONEMAP_ACES_FILMIC, TONEMAP_AGX, TONEMAP_CINEON, TONEMAP_LINEAR, TONEMAP_NEUTRAL, TONEMAP_NONE, TONEMAP_REINHARD, TONEMAP_REINHARD_EXTENDED, Visibility, VisibilityStateValue, admitPointsLines, cameraProjectionFromF32, orthographic, perspective, pointShapeFromU32, resolveVisibility, visibilityStateFromU32 } from './chunk-YEJIUW7D.mjs';
+import { SpriteAnimation, SpriteInstances, SpriteRegionOverride, TileLayer, Tilemap } from './chunk-CQXZC5XI.mjs';
+export { Materials } from './chunk-CQXZC5XI.mjs';
+import { validateCookedMaterialRecord } from '@forgeax/engine-pack';
+import { ok, err, MATERIAL_TEXTURE_SLOTS } from '@forgeax/engine-types';
+
+function invalid(guid, expected, reason) {
+  return err({
+    code: "asset-package-invalid",
+    expected,
+    hint: "recook the render asset and publish its complete cooked payload",
+    detail: { guid, reason }
+  });
+}
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validMaterial(value) {
+  if (!record(value) || value.kind !== "material") return false;
+  if (value.cooked !== void 0 && !validateCookedMaterialRecord(value.cooked).ok) {
+    return false;
+  }
+  if (value.passes !== void 0 && !Array.isArray(value.passes)) return false;
+  if (value.parameters !== void 0 && !Array.isArray(value.parameters)) return false;
+  return value.values === void 0 || record(value.values);
+}
+function resolveMaterialWireRef(value, refs, field, guid) {
+  if (typeof value !== "number") return ok(value);
+  if (!Number.isSafeInteger(value) || value < 0 || refs[value] === void 0) {
+    return err({
+      code: "asset-package-invalid",
+      expected: `${field} to reference a GUID through the material Pack refs[] table`,
+      hint: "recook the material so every texture or sampler ref has a matching refs[] entry",
+      detail: { guid, reason: `${field} refs[${value}] is out of bounds` }
+    });
+  }
+  return ok(refs[value]);
+}
+function resolveMaterialWireRefs(value, refs, guid) {
+  if (refs.length === 0) return ok(value);
+  let changed = false;
+  let parent = value.parent;
+  if (typeof parent === "number") {
+    const resolved = resolveMaterialWireRef(parent, refs, "parent", guid);
+    if (!resolved.ok) return resolved;
+    parent = resolved.value;
+    changed = true;
+  }
+  if (value.values === void 0) {
+    return changed ? ok({ ...value, ...parent === void 0 ? {} : { parent } }) : ok(value);
+  }
+  const textureFields = new Set(
+    value.parameters === void 0 ? MATERIAL_TEXTURE_SLOTS : value.parameters.filter((parameter) => parameter.type === "texture").map((parameter) => parameter.name)
+  );
+  const values = { ...value.values };
+  for (const [field, raw] of Object.entries(values)) {
+    if (typeof raw === "number" && textureFields.has(field)) {
+      const resolved = resolveMaterialWireRef(raw, refs, field, guid);
+      if (!resolved.ok) return resolved;
+      values[field] = resolved.value;
+      changed = true;
+      continue;
+    }
+    if (!record(raw)) continue;
+    const rawRecord = raw;
+    let rewritten;
+    for (const key of ["texture", "sampler"]) {
+      if (!(key in rawRecord)) continue;
+      const resolved = resolveMaterialWireRef(rawRecord[key], refs, `${field}.${key}`, guid);
+      if (!resolved.ok) return resolved;
+      if (resolved.value !== rawRecord[key]) {
+        rewritten ??= { ...rawRecord };
+        rewritten[key] = resolved.value;
+        changed = true;
+      }
+    }
+    if (rewritten !== void 0) {
+      values[field] = rewritten;
+    }
+  }
+  return ok(changed ? { ...value, ...parent === void 0 ? {} : { parent }, values } : value);
+}
+var materialContribution = {
+  kind: { kind: "material" },
+  consumer: "Render MaterialScene",
+  decoder: {
+    async decode({ envelope }) {
+      if (!validMaterial(envelope.payload)) {
+        return invalid(
+          envelope.guid,
+          "a material payload with cooked passes, parameters, and values",
+          "material owner validation failed"
+        );
+      }
+      return resolveMaterialWireRefs(envelope.payload, envelope.refs, envelope.guid);
+    }
+  }
+};
+var samplerContribution = {
+  kind: { kind: "sampler" },
+  consumer: "Render DeviceScope",
+  decoder: {
+    async decode({ envelope }) {
+      return envelope.payload.kind === "sampler" ? ok(envelope.payload) : invalid(envelope.guid, "a sampler payload", "sampler owner validation failed");
+    }
+  }
+};
+var renderPipelineContribution = {
+  kind: { kind: "render-pipeline" },
+  consumer: "Render Pipeline",
+  decoder: {
+    async decode({ envelope }) {
+      const payload = envelope.payload;
+      return payload.kind === "render-pipeline" && payload.pipelineId.trim().length > 0 ? ok(payload) : invalid(
+        envelope.guid,
+        "a render-pipeline payload with a pipelineId",
+        "render-pipeline owner validation failed"
+      );
+    }
+  }
+};
+
+// src/plugin.ts
+var RENDER_COMPONENTS = [
+  Camera,
+  DirectionalLight,
+  Instances,
+  Layer,
+  MeshFilter,
+  MeshRenderer,
+  PointLight,
+  PointLightShadow,
+  Points,
+  Lines,
+  PostProcessParams,
+  SceneInstance,
+  SkyboxBackground,
+  Skylight,
+  SortKey,
+  SpotLight,
+  SpriteAnimation,
+  SpriteInstances,
+  SpriteRegionOverride,
+  TileLayer,
+  Tilemap,
+  Visibility
+];
+function registerRenderComponents(world) {
+  const leases = RENDER_COMPONENTS.map(
+    (component) => world.components.register(component).unwrap()
+  );
+  return () => {
+    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();
+  };
+}
+function renderComponentsPlugin() {
+  return {
+    name: "render-components",
+    inject: ["world"],
+    apply(ctx) {
+      ctx.effect(() => registerRenderComponents(ctx.world), "render/components");
+    }
+  };
+}
+
+export { materialContribution, renderComponentsPlugin, renderPipelineContribution, samplerContribution };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/assets/asset-decoders.ts","../src/plugin.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import { validateCookedMaterialRecord } from '@forgeax/engine-pack';\nimport {\n  type AssetDecoderContribution,\n  type AssetKind,\n  type AssetLoadError,\n  err,\n  MATERIAL_TEXTURE_SLOTS,\n  type MaterialAsset,\n  ok,\n  type RenderPipelineAsset,\n  type SamplerAsset,\n} from '@forgeax/engine-types';\n\nfunction invalid(guid: string, expected: string, reason: string) {\n  return err({\n    code: 'asset-package-invalid' as const,\n    expected,\n    hint: 'recook the render asset and publish its complete cooked payload',\n    detail: { guid, reason },\n  });\n}\n\nfunction record(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n\nfunction validMaterial(value: unknown): value is MaterialAsset {\n  if (!record(value) || value.kind !== 'material') return false;\n  if (value.cooked !== undefined && !validateCookedMaterialRecord(value.cooked).ok) {\n    return false;\n  }\n  if (value.passes !== undefined && !Array.isArray(value.passes)) return false;\n  if (value.parameters !== undefined && !Array.isArray(value.parameters)) return false;\n  return value.values === undefined || record(value.values);\n}\n\nfunction resolveMaterialWireRef(\n  value: unknown,\n  refs: readonly string[],\n  field: string,\n  guid: string,\n): ReturnType<typeof ok<string | number>> | ReturnType<typeof err<AssetLoadError>> {\n  if (typeof value !== 'number') return ok(value as string | number);\n  if (!Number.isSafeInteger(value) || value < 0 || refs[value] === undefined) {\n    return err<AssetLoadError>({\n      code: 'asset-package-invalid',\n      expected: `${field} to reference a GUID through the material Pack refs[] table`,\n      hint: 'recook the material so every texture or sampler ref has a matching refs[] entry',\n      detail: { guid, reason: `${field} refs[${value}] is out of bounds` },\n    });\n  }\n  return ok(refs[value] as string);\n}\n\nfunction resolveMaterialWireRefs(\n  value: MaterialAsset,\n  refs: readonly string[],\n  guid: string,\n): ReturnType<typeof ok<MaterialAsset>> | ReturnType<typeof err<AssetLoadError>> {\n  if (refs.length === 0) return ok(value);\n\n  let changed = false;\n  let parent = value.parent;\n  if (typeof parent === 'number') {\n    const resolved = resolveMaterialWireRef(parent, refs, 'parent', guid);\n    if (!resolved.ok) return resolved;\n    parent = resolved.value as unknown as MaterialAsset['parent'];\n    changed = true;\n  }\n\n  if (value.values === undefined) {\n    return changed ? ok({ ...value, ...(parent === undefined ? {} : { parent }) }) : ok(value);\n  }\n\n  const textureFields = new Set(\n    value.parameters === undefined\n      ? MATERIAL_TEXTURE_SLOTS\n      : value.parameters\n          .filter((parameter) => parameter.type === 'texture')\n          .map((parameter) => parameter.name),\n  );\n  const values = { ...value.values };\n  for (const [field, raw] of Object.entries(values)) {\n    if (typeof raw === 'number' && textureFields.has(field)) {\n      const resolved = resolveMaterialWireRef(raw, refs, field, guid);\n      if (!resolved.ok) return resolved;\n      values[field] = resolved.value as NonNullable<MaterialAsset['values']>[string];\n      changed = true;\n      continue;\n    }\n    if (!record(raw)) continue;\n    const rawRecord = raw as unknown as Record<string, unknown>;\n    let rewritten: Record<string, unknown> | undefined;\n    for (const key of ['texture', 'sampler'] as const) {\n      if (!(key in rawRecord)) continue;\n      const resolved = resolveMaterialWireRef(rawRecord[key], refs, `${field}.${key}`, guid);\n      if (!resolved.ok) return resolved;\n      if (resolved.value !== rawRecord[key]) {\n        rewritten ??= { ...rawRecord };\n        rewritten[key] = resolved.value;\n        changed = true;\n      }\n    }\n    if (rewritten !== undefined) {\n      values[field] = rewritten as unknown as NonNullable<MaterialAsset['values']>[string];\n    }\n  }\n  return ok(changed ? { ...value, ...(parent === undefined ? {} : { parent }), values } : value);\n}\n\nexport const materialContribution: AssetDecoderContribution<MaterialAsset, 'material'> = {\n  kind: { kind: 'material' } as AssetKind<MaterialAsset, 'material'>,\n  consumer: 'Render MaterialScene',\n  decoder: {\n    async decode({ envelope }) {\n      if (!validMaterial(envelope.payload)) {\n        return invalid(\n          envelope.guid,\n          'a material payload with cooked passes, parameters, and values',\n          'material owner validation failed',\n        );\n      }\n      return resolveMaterialWireRefs(envelope.payload, envelope.refs, envelope.guid);\n    },\n  },\n};\n\nexport const samplerContribution: AssetDecoderContribution<SamplerAsset, 'sampler'> = {\n  kind: { kind: 'sampler' } as AssetKind<SamplerAsset, 'sampler'>,\n  consumer: 'Render DeviceScope',\n  decoder: {\n    async decode({ envelope }) {\n      return envelope.payload.kind === 'sampler'\n        ? ok(envelope.payload)\n        : invalid(envelope.guid, 'a sampler payload', 'sampler owner validation failed');\n    },\n  },\n};\n\nexport const renderPipelineContribution: AssetDecoderContribution<\n  RenderPipelineAsset,\n  'render-pipeline'\n> = {\n  kind: { kind: 'render-pipeline' } as AssetKind<RenderPipelineAsset, 'render-pipeline'>,\n  consumer: 'Render Pipeline',\n  decoder: {\n    async decode({ envelope }) {\n      const payload = envelope.payload;\n      return payload.kind === 'render-pipeline' && payload.pipelineId.trim().length > 0\n        ? ok(payload)\n        : invalid(\n            envelope.guid,\n            'a render-pipeline payload with a pipelineId',\n            'render-pipeline owner validation failed',\n          );\n    },\n  },\n};\n","import type { Component, World } from '@forgeax/engine-ecs';\nimport type { Plugin } from '@forgeax/engine-plugin';\nimport { Camera } from './components/camera';\nimport { DirectionalLight } from './components/directional-light';\nimport { Instances } from './components/instances';\nimport { Layer } from './components/layer';\nimport { Lines } from './components/lines';\nimport { MeshFilter } from './components/mesh-filter';\nimport { MeshRenderer } from './components/mesh-renderer';\nimport { PointLight } from './components/point-light';\nimport { PointLightShadow } from './components/point-light-shadow';\nimport { Points } from './components/points';\nimport { PostProcessParams } from './components/post-process-params';\nimport { SceneInstance } from './components/scene-instance';\nimport { SkyboxBackground } from './components/skybox-background';\nimport { Skylight } from './components/skylight';\nimport { SortKey } from './components/sort-key';\nimport { SpotLight } from './components/spot-light';\nimport { SpriteAnimation } from './components/sprite-animation';\nimport { SpriteInstances } from './components/sprite-instances';\nimport { SpriteRegionOverride } from './components/sprite-region-override';\nimport { TileLayer } from './components/tile-layer';\nimport { Tilemap } from './components/tilemap';\nimport { Visibility } from './components/visibility';\n\nconst RENDER_COMPONENTS: readonly Component[] = [\n  Camera,\n  DirectionalLight,\n  Instances,\n  Layer,\n  MeshFilter,\n  MeshRenderer,\n  PointLight,\n  PointLightShadow,\n  Points,\n  Lines,\n  PostProcessParams,\n  SceneInstance,\n  SkyboxBackground,\n  Skylight,\n  SortKey,\n  SpotLight,\n  SpriteAnimation,\n  SpriteInstances,\n  SpriteRegionOverride,\n  TileLayer,\n  Tilemap,\n  Visibility,\n];\n\nfunction registerRenderComponents(world: World): () => void {\n  const leases = RENDER_COMPONENTS.map((component) =>\n    world.components.register(component).unwrap(),\n  );\n  return () => {\n    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();\n  };\n}\n\n/** Install the built-in render ECS vocabulary in one World. */\nexport function renderComponentsPlugin(): Plugin {\n  return {\n    name: 'render-components',\n    inject: ['world'],\n    apply(ctx) {\n      ctx.effect(() => registerRenderComponents(ctx.world), 'render/components');\n    },\n  };\n}\n"]}

package/dist/inspection-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Renderer-owned inspection PODs. Keeping these projections free of renderer
+ * implementation imports prevents the observation contract from reopening the
+ * extract/record dependency graph.
+ */
+import type { PointsLinesInspection } from './points-lines/inspection';
+export interface BatchTopologyInspection {
+    readonly revision: number;
+    readonly batchCount: number;
+    readonly candidateCount: number;
+    readonly rebuilds: number;
+    readonly patches: number;
+    readonly ineligible: number;
+}
+export interface GpuSceneTableInspection {
+    readonly capacity: number;
+    readonly bytes: number;
+}
+type GpuSceneTableName = 'primitive' | 'instance' | 'transform' | 'drawTemplate' | 'material';
+export interface GpuSceneInspection {
+    readonly capacity: number;
+    readonly tables: Readonly<Record<GpuSceneTableName, GpuSceneTableInspection>>;
+    readonly uploadRanges: number;
+    readonly uploadBytes: number;
+    readonly capacityGrows: number;
+    readonly fullRebuilds: number;
+    readonly clearedSlots: number;
+    readonly noChangeFrames: number;
+}
+export interface GpuDrivenProductionInspection {
+    readonly gpuOwnedSnapshotsMaterialized: number;
+    readonly filteredPlanBuilds: number;
+    readonly gpuOwnedEntityCount: number;
+    readonly candidateUploadBytes: number;
+    readonly batchUploadBytes: number;
+    readonly viewConstantsUploadBytes: number;
+    readonly batchBindGroupCreates: number;
+    readonly viewBindGroupCreates: number;
+    readonly topologyRevision: number | undefined;
+    readonly validatedGpuOwnedRows: number;
+    readonly cpuFallbackDrawItems: number;
+}
+export type RenderSceneResyncReason = 'attach' | 'asset-catalog-changed' | 'shared-ref-changed' | 'journal-overflow' | 'unsupported-change' | 'non-rigid-lane' | 'explicit-invalidate';
+export interface PersistentRenderSceneInspection {
+    readonly worldEntitiesScanned: number;
+    readonly fullRebuilds: number;
+    readonly noChangeFrames: number;
+    readonly deltaFrames: number;
+    readonly transformUpdates: number;
+    readonly lastResyncReason: RenderSceneResyncReason | undefined;
+    readonly projectionRecords: number;
+    readonly topology: BatchTopologyInspection;
+    readonly gpu: {
+        readonly status: 'inactive';
+    } | {
+        readonly status: 'unsupported';
+        readonly reason: 'storage-buffer-unavailable';
+    } | ({
+        readonly status: 'resident';
+    } & GpuSceneInspection) | {
+        readonly status: 'rebuild-pending';
+    } | {
+        readonly status: 'error';
+    };
+    /** Bounded retained authoring observations; no graph or backend handles. */
+    readonly pointsLines: readonly PointsLinesInspection[];
+}
+export type RenderSceneInspection = PersistentRenderSceneInspection & {
+    readonly gpuDriven: GpuDrivenProductionInspection;
+};
+export {};
+//# sourceMappingURL=inspection-types.d.ts.map

package/dist/inspection-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-types.d.ts","sourceRoot":"","sources":["../src/inspection-types.ts"],"names":[],"mappings":"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"}

package/dist/instance-buffer-cache.d.ts

@@ -0,0 +1,56 @@
+import type { GpuBuffer } from './gpu-resource';
+/**
+ * One entry of the per-RenderSystem instance-transform GPU storage cache.
+ *
+ * The `buffer` field is a `GpuBuffer` wrapper (feat-20260612 M-2/M-3): it
+ * holds the raw RHI handle, owns the lifecycle (`destroy()` + `isDestroyed`)
+ * and routes dispose through the RHI shim's destroy bookkeeping SSOT. The
+ * two `uploaded*` fields are the cache invalidation fingerprint -- when the
+ * archetype version bumps or the byte length changes, the record stage
+ * allocates a fresh GpuBuffer and replaces the entry.
+ */
+export interface InstanceBufferCacheEntry {
+    readonly buffer: GpuBuffer;
+    readonly uploadedByteLength: number;
+    readonly uploadedArchVersion: number;
+}
+/**
+ * Minimal error-registry surface accepted by disposeInstanceBuffers —
+ * only needs `fire`, matching RhiErrorListenerRegistry (feat-20260619 D-6).
+ */
+export interface InstanceBufferCacheErrorSink {
+    fire(e: {
+        code: string;
+    }): void;
+}
+/**
+ * Walk an instance-buffer cache Map, destroy every entry's GpuBuffer, then
+ * clear the Map. Called from `Renderer.dispose()` (M-5) as the per-frame
+ * instance-buffer release step in the dispose chain
+ * (plan-strategy D-2: gpuStore.destroyAll -> graph.drain ->
+ * frameState.instanceBuffers cleanup -> ...).
+ *
+ * Idempotent (architecture-principles §6): a second call after the Map was
+ * cleared is a no-op. Each `.destroy()` routes through the RHI shim's
+ * per-handle bookkeeping; a stray second-destroy on a handle that the
+ * runtime did not flip surfaces as the structured 'destroy-after-destroy'
+ * RhiError from the shim. That error is *not* re-thrown -- this helper
+ * is a sweep that tolerates per-handle failures so the dispose chain can
+ * make progress (mirrors `GpuResidencyCache.destroyAll`'s policy;
+ * plan-strategy D-3 / D-8).
+ *
+ * feat-20260619 M4 (D-6): the optional `errorRegistry` parameter unifies
+ * the dispose path with the per-frame path — destroy failures fire
+ * errorRegistry + sweep continues. Callers that lack an error registry
+ * (unit tests of the helper itself) omit the parameter safely.
+ *
+ * Per-frame Map.delete cleanup at the record stage keeps its existing
+ * 'just delete the key' semantics (plan-strategy D-7 + OOS-11): the
+ * per-frame path bumps fingerprints when the archetype version changes,
+ * letting the next record stage replace the entry; only the dispose
+ * exit path walks-then-destroys.
+ */
+export declare function disposeInstanceBuffers(map: Map<number, InstanceBufferCacheEntry>, errorRegistry?: InstanceBufferCacheErrorSink): void;
+/** Destroy transient uniform-fallback chunks allocated for the previous frame. */
+export declare function disposeTransientInstanceBuffers(entries: InstanceBufferCacheEntry[], errorRegistry?: InstanceBufferCacheErrorSink): void;
+//# sourceMappingURL=instance-buffer-cache.d.ts.map

package/dist/instance-buffer-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance-buffer-cache.d.ts","sourceRoot":"","sources":["../src/instance-buffer-cache.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAaD;;;GAGG;AACH,MAAM,WAAW,4BAA4B;IAC3C,IAAI,CAAC,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAC1C,aAAa,CAAC,EAAE,4BAA4B,GAC3C,IAAI,CAGN;AAED,kFAAkF;AAClF,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,wBAAwB,EAAE,EACnC,aAAa,CAAC,EAAE,4BAA4B,GAC3C,IAAI,CAGN"}

package/dist/internal.d.ts

@@ -0,0 +1,2 @@
+export { type ResolvedTilesetRuntime, resolveTilesetRuntime, type TilesetAtlasLookup, type TilesetRuntimeError, type TilesetRuntimeErrorCode, } from '@forgeax/engine-assets-runtime';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,sBAAsB,EAC3B,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,gCAAgC,CAAC"}

package/dist/internal.mjs

@@ -0,0 +1,3 @@
+export { resolveTilesetRuntime } from '@forgeax/engine-assets-runtime';
+//# sourceMappingURL=internal.mjs.map
+//# sourceMappingURL=internal.mjs.map

package/dist/internal.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"internal.mjs","sourcesContent":[]}

package/dist/lifecycle.d.ts

@@ -0,0 +1,62 @@
+import type { AssetRuntimeError } from '@forgeax/engine-assets-runtime';
+import type { RenderGraphError } from '@forgeax/engine-render-graph';
+import type { RhiError } from '@forgeax/engine-rhi';
+import type { SkinError } from '@forgeax/engine-skinning';
+import type { ImageError } from '@forgeax/engine-types';
+import type { RenderError } from './errors/render';
+import type { PostProcessError } from './post-process-errors';
+export interface RendererLostInfo {
+    readonly reason: string;
+    readonly message: string;
+}
+export type RendererLostListener = (info: RendererLostInfo) => void;
+export type RendererError = RhiError | RenderGraphError | ImageError | RenderError | AssetRuntimeError | SkinError | PostProcessError;
+export type RendererErrorListener = (error: RendererError) => void;
+export type HealthReason = 'alive' | 'device-lost' | 'internal-fault';
+export interface HealthDetailDeviceLost {
+    readonly lostReason: 'unknown' | 'destroyed';
+    readonly message: string;
+}
+export interface HealthDetailInternalFault {
+    readonly message: string;
+}
+export type HealthSnapshot = {
+    readonly reason: 'alive';
+    readonly recoverable: boolean;
+} | {
+    readonly reason: 'device-lost';
+    readonly detail: HealthDetailDeviceLost;
+    readonly recoverable: boolean;
+} | {
+    readonly reason: 'internal-fault';
+    readonly detail: HealthDetailInternalFault;
+    readonly recoverable: boolean;
+};
+export type HealthChangeListener = (snapshot: HealthSnapshot) => void;
+export { DEVICE_RESOURCE_KINDS, type DeviceResourceKind, DeviceResourceRef, DeviceScope, type DeviceScopeReceipt, type DeviceScopeState, type LifecycleFailure, type LifecycleResourceSpec, type LifecycleResult, LifecycleTransaction, type ResourceRef, } from './device/device-scope';
+export declare class LostListenerRegistry {
+    private readonly listeners;
+    private fired;
+    private lastInfo;
+    add(listener: RendererLostListener): () => void;
+    fire(info: RendererLostInfo): void;
+    clear(): void;
+}
+export declare class RhiErrorListenerRegistry {
+    private readonly listeners;
+    private fired;
+    private lastError;
+    add(listener: RendererErrorListener): () => void;
+    fire(error: RendererError): void;
+    clear(): void;
+}
+export declare class HealthListenerRegistry {
+    private readonly listeners;
+    private fired;
+    private lastSnapshot;
+    add(listener: HealthChangeListener): () => void;
+    fire(snapshot: HealthSnapshot): void;
+    clear(): void;
+    getLastSnapshot(): HealthSnapshot;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/light-buffer-layout.d.ts

@@ -0,0 +1,164 @@
+import { type Result, RhiError } from '@forgeax/engine-rhi';
+import type { PointLightSnapshot, SpotLightSnapshot } from './render-system-extract';
+/** Byte size of one HDRP LightSlot in std430 (16 x f32). AC-11 absolute-value lock. */
+export declare const BYTES_PER_LIGHT_SLOT = 64;
+/**
+ * LightSlot kind discriminant — closed enum matching WGSL `KIND_POINT` / `KIND_SPOT`.
+ * Values are u32 bit-tags (not sequential); AC-12 exhaustive switch.
+ */
+export declare const LightSlotKind: {
+    readonly POINT: 0;
+    readonly SPOT: 1;
+};
+export type LightSlotKind = (typeof LightSlotKind)[keyof typeof LightSlotKind];
+/**
+ * Byte-offset layout of one LightSlot in std430 (16 f32 = 64 B).
+ *
+ * Mirrors the WGSL `LightSlot` struct field order byte-for-byte.
+ * All offsets verified by w14 lightslot-layout.test.ts.
+ *
+ * feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-4 (plan-strategy §D-8):
+ * the prior u32x3 pad lanes at byte 52..64 carry shadow-side data on the HDRP
+ * path. `kind_and_pad.x = kind` (u32), `.y = shadow identity` (i32, sentinel
+ * -1 = no shadow), `.z = near` (f32 via bitcast), `.w = far`
+ * (f32 via bitcast). The shader reads near/far through `bitcast<f32>(...)`
+ * to keep the WGSL struct as `vec4<u32>` (alignment + naga_oil unchanged).
+ */
+export declare const LIGHTSLOT_LAYOUT: {
+    readonly byteSize: 64;
+    readonly positionOffset: 0;
+    readonly invRangeSquaredOffset: 12;
+    readonly colorOffset: 16;
+    readonly cosInnerOffset: 28;
+    readonly directionOffset: 32;
+    readonly cosOuterOffset: 44;
+    readonly kindOffset: 48;
+    readonly shadowPayloadOffset: 52;
+    readonly shadowAtlasLayerOffset: 52;
+    readonly shadowAtlasTileOffset: 52;
+    readonly shadowNearOffset: 56;
+    readonly shadowFarOffset: 60;
+    readonly floatCount: 16;
+    readonly vec4Count: 4;
+};
+/**
+ * Minimum storage-buffer count needed by the M3 record stage.
+ *
+ *   1. Mesh SSBO (entity_world + normalMatrix; per-renderable dynamic
+ *      offset, 256 B stride).
+ *   2. PointLight std430 array (this feat).
+ *   3. SpotLight std430 array (this feat).
+ *
+ * Plan R-4 + plan-strategy section 4 risk table: assert >= 4 to keep the
+ * head-room margin for todo-125 (cluster expansion lifts to 4-5 entries).
+ */
+export declare const STORAGE_BUFFER_MIN_REQUIRED = 4;
+/** Byte size of one PointLight std430 slot (vec4 * 2). */
+export declare const POINT_LIGHT_STD430_BYTES = 32;
+/**
+ * Byte size of one SpotLight std430 slot (vec4 * 4).
+ *
+ * feat-20260625-spot-light-shadow-mapping M2 / w8 (D-4): grew 48 -> 64 to make
+ * room for the `shadowAtlasTile: i32` clip-signal lane (slot 15). Slots 0..11
+ * keep the prior layout; slots 12..14 are vec4-alignment padding.
+ */
+export declare const SPOT_LIGHT_STD430_BYTES = 64;
+/** Sentinel value for SpotLight slot[15] meaning "no shadow / clipped". */
+export declare const SPOT_LIGHT_SHADOW_TILE_SENTINEL = -1;
+/** Byte size of the array header (count u32 + 12 B pad to 16 B stride). */
+export declare const LIGHT_ARRAY_HEADER_BYTES = 16;
+/** Maximum number of slots packed in the first-slice cap layout (D-S3). */
+export declare const LIGHT_ARRAY_MAX_SLOTS = 4;
+/** Sentinel value for PointLight slot[7] / LightSlot pad meaning "no shadow". */
+export declare const POINT_LIGHT_SHADOW_LAYER_SENTINEL = -1;
+/**
+ * Pack one PointLightSnapshot into 8 floats / 32 B byte-for-byte std430.
+ *
+ * Returns a fresh `Float32Array` per call; `Float32Array.byteLength === 32`
+ * by construction (Float32Array(8).buffer.byteLength === 32). Slot 7
+ * (byte 28..32) carries `shadowAtlasLayer: i32` (sentinel -1 = no shadow,
+ * 0..3 = cube_array atlas layer index for shadow casters). The lane is
+ * written through an Int32Array view of the same backing ArrayBuffer so the
+ * shader's `i32` read at byte 28..32 of `struct PointLight` (common.wgsl)
+ * sees the correct two's-complement bits (-1 = 0xFFFFFFFF).
+ */
+export declare function packPointLight(snap: PointLightSnapshot): Float32Array;
+/**
+ * Pack one SpotLightSnapshot into 16 floats (64 B byte-for-byte std430).
+ *
+ * cosInner / cosOuter ride the otherwise-padding `.w` lanes of the
+ * `color` and `direction` vec4 columns (AC-04 c + plan D-S2 16 B alignment
+ * via packing rather than padding rows). Slot 15 carries `shadowAtlasTile: i32`
+ * (sentinel -1 = unassigned/clipped, 0..3 = atlas tile) written through an
+ * Int32Array view so the shader's `i32` read at byte 60..64 of struct SpotLight
+ * (common.wgsl) sees the correct two's-complement bits (-1 = 0xFFFFFFFF).
+ * Slots 12..14 stay zero (vec4-alignment padding). feat-20260625 M2 / w8 (D-4).
+ */
+export declare function packSpotLight(snap: SpotLightSnapshot): Float32Array;
+/**
+ * Pack the 16-byte std430 array header (count u32 + 12 B pad) for the
+ * point/spot light storage buffers.
+ *
+ * Returns a fresh `ArrayBuffer` so callers can either re-view it as
+ * `Uint8Array` for `queue.writeBuffer` or as `Uint32Array` for in-place
+ * inspection.
+ */
+export declare function packLightArrayHeader(count: number): ArrayBuffer;
+/**
+ * Cap gate at createRenderer time: check whether the device has enough
+ * storage-buffer slots for the PBR pipeline (M3 requires
+ * `STORAGE_BUFFER_MIN_REQUIRED = 4`). Returns a three-way signal:
+ *
+ *  - `Result.ok(true)`  — storage buffer capable (cap >= 4);
+ *  - `Result.ok(false)` — no storage buffer capability at all (cap === 0);
+ *    consumer walks the uniform-fallback path;
+ *  - `Result.err(RhiError)` — cap in (0, 4); not enough storage slots to run
+ *    but also not a clean zero-cap uniform-fallback case (e.g. downlevel
+ *    adapter with 1-3 slots). The error carries `'limit-exceeded'` with
+ *    `LimitExceededDetail` shape.
+ *
+ * Uniform-fallback path decision (plan D-5): `cap === 0` is the wgpu
+ * WebGL2 backend signal (`downlevel_webgl2_defaults().limits.
+ * maxStorageBuffersPerShaderStage = 0`). Uniform fallback covers pointLight
+ * + spotLight + meshes + instances + skin palette — every storage-buffer
+ * entry in the PBR pipeline switches to `uniform`.
+ */
+/**
+ * Optional shadow info attached to a HDRP LightSlot for point lights with a
+ * companion `PointLightShadow` component. Sentinel `layer = -1` (the default
+ * when the snapshot has no shadow) makes the shader skip cube_array sampling
+ * and stay on the unshadowed `evalPoint` path.
+ *
+ * `near` / `far` ride the otherwise-pad lanes (`kind_and_pad.zw` in the WGSL
+ * struct, byte 56..64) and feed the depth-ref reconstruction in
+ * `evalPointShadowed`. Spot lights (and shadow-less point lights) leave these
+ * lanes zero per std430 init.
+ */
+export interface PointShadowSlotInfo {
+    readonly shadowAtlasLayer: number;
+    readonly near: number;
+    readonly far: number;
+}
+/**
+ * Pack one PointLightSnapshot or SpotLightSnapshot into a 64-byte LightSlot
+ * (16 floats, std430). Point lights fill `cosInner=1.0`, `direction=vec3(0)`,
+ * `cosOuter=0.0`, `kind=POINT(0)`. Spot lights fill all fields verbatim;
+ * `direction` is already normalized by extract and this owner never repeats
+ * that operation.
+ *
+ * feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-4 (plan-strategy §D-8):
+ * the optional point `shadow` info threads through to bytes 52..64 as
+ * `(shadowAtlasLayer i32, near f32, far f32)`. Spot snapshots write their
+ * `shadowAtlasTile` directly into the same identity lane and keep near/far 0.
+ * The shader reads `near`/`far`
+ * through `bitcast<f32>(kind_and_pad.zw)` so the WGSL struct stays
+ * `kind_and_pad: vec4<u32>` (alignment + naga_oil compose unchanged). When
+ * `shadow` is undefined (no PointLightShadow) the lanes default to
+ * `(layer = -1, 0, 0)` -- shader gates on `layer >= 0` so unshadowed lights
+ * stay on the `evaluate_point_light` path. Spot lights write their tile or -1.
+ *
+ * Returns a fresh `Float32Array(16)` per call.
+ */
+export declare function packLightSlot(snap: PointLightSnapshot | SpotLightSnapshot, shadow?: PointShadowSlotInfo): Float32Array;
+export declare function assertStorageBufferCap(cap: number): Result<boolean, RhiError>;
+//# sourceMappingURL=light-buffer-layout.d.ts.map

package/dist/light-buffer-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"light-buffer-layout.d.ts","sourceRoot":"","sources":["../src/light-buffer-layout.ts"],"names":[],"mappings":"AAqDA,OAAO,EAAW,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAyBrF,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,aAAa;;;CAGhB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;CAgBnB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,0DAA0D;AAC1D,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,2EAA2E;AAC3E,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAClD,2EAA2E;AAC3E,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,iFAAiF;AACjF,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,YAAY,CAarE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,YAAY,CAmBnE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAM/D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,EAC5C,MAAM,CAAC,EAAE,mBAAmB,GAC3B,YAAY,CAmCd;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAkB7E"}

package/dist/materials.d.ts

@@ -0,0 +1,47 @@
+import type { MaterialAsset, MaterialColorSpace, MaterialRenderState, MaterialValue } from '@forgeax/engine-types';
+export declare const SPRITE_PREMULTIPLIED_ALPHA_BLEND: GPUBlendState;
+declare const SPRITE_MODULE = "forgeax_material::sprite";
+interface UnlitOpts {
+    /** Asset-side authored color space. Defaults to sRGB. */
+    readonly colorSpace?: MaterialColorSpace;
+    readonly castShadow?: boolean;
+    readonly baseColorTexture?: MaterialValue;
+    readonly alphaCutoff?: number;
+    readonly renderState?: MaterialRenderState;
+    readonly queue?: number;
+}
+declare function unlit(rgba: readonly [number, number, number, number], opts?: UnlitOpts): MaterialAsset;
+interface StandardOpts {
+    /** Asset-side authored color space for baseColor/emissive/specularTint. Defaults to sRGB. */
+    readonly colorSpace?: MaterialColorSpace;
+    readonly baseColor: readonly [number, number, number, number];
+    readonly metallic?: number;
+    readonly roughness?: number;
+    /** Texture channel used for the metallic factor; glTF defaults to B (2). */
+    readonly metallicChannel?: number;
+    /** Texture channel used for the roughness factor; glTF defaults to G (1). */
+    readonly roughnessChannel?: number;
+    readonly clearcoat?: number;
+    readonly clearcoatRoughness?: number;
+    readonly specularTint?: readonly [number, number, number];
+    readonly specularTintTexture?: MaterialValue;
+    readonly emissive?: readonly [number, number, number];
+    readonly emissiveIntensity?: number;
+    readonly emissiveTexture?: MaterialValue;
+    readonly baseColorTexture?: MaterialValue;
+    readonly metallicRoughnessTexture?: MaterialValue;
+    readonly normalTexture?: MaterialValue;
+    readonly occlusionTexture?: MaterialValue;
+    readonly occlusionStrength?: number;
+    readonly alphaCutoff?: number;
+    readonly renderState?: MaterialRenderState;
+    readonly castShadow?: boolean;
+    readonly queue?: number;
+}
+declare function standard(opts: StandardOpts): MaterialAsset;
+export declare const Materials: {
+    readonly unlit: typeof unlit;
+    readonly standard: typeof standard;
+};
+export { SPRITE_MODULE };
+//# sourceMappingURL=materials.d.ts.map

package/dist/materials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materials.d.ts","sourceRoot":"","sources":["../src/materials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAGlB,mBAAmB,EACnB,aAAa,EACd,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,gCAAgC,EAAE,aAG9C,CAAC;AAIF,QAAA,MAAM,aAAa,6BAA6B,CAAC;AA0EjD,UAAU,SAAS;IACjB,yDAAyD;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iBAAS,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,EAAE,SAAS,GAAG,aAAa,CAoB/F;AAED,UAAU,YAAY;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,aAAa,CAAC;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACtD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,aAAa,CAAC;IACzC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC;IAC1C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,aAAa,CAAC;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,aAAa,CAAC;IAC1C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAWD,iBAAS,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,aAAa,CAkDnD;AAED,eAAO,MAAM,SAAS;;;CAA+B,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,CAAC"}