@aethervtt/shard-render 0.0.1 → 0.1.0

package/dist/screen-effects.js

@@ -0,0 +1,192 @@
+import {
+  defineResource,
+  defineSystem,
+  ShardError
+} from "@aethervtt/shard-core";
+import { FrameDemand, LogResource, Time } from "@aethervtt/shard-runtime";
+const MAX_SCREEN_EFFECTS = 8;
+const MAX_SCREEN_EFFECT_PARAMS = 8;
+const ScreenEffects = defineResource("render/ScreenEffects", {
+  hostWritable: true,
+  description: "Typed effects published at a screen point (at most 8): kind, center and radius in CSS pixels, ms to live, source entity, params. The app whose view they are in draws them through handlers registered with onScreenEffect.",
+  init: () => ({ effects: [] })
+});
+const ScreenEffectHandlers = defineResource("render/ScreenEffectHandlers", {
+  description: "Handlers by kind (onScreenEffect) and the screen effects they are drawing.",
+  init: () => ({ kinds: /* @__PURE__ */ new Map(), live: [], reported: /* @__PURE__ */ new Set() })
+});
+function invalid(message, path) {
+  return new ShardError("render/invalid-screen-effect", message, {
+    path,
+    hint: "A screen effect has a kind, a radius of at least 0, and at most 8 params."
+  });
+}
+function publishScreenEffect(world, effect) {
+  if (!effect.kind) throw invalid("A screen effect needs a kind", "kind");
+  if (!(effect.radius >= 0)) throw invalid(`Radius ${effect.radius} is below 0`, "radius");
+  const keys = Object.keys(effect.params);
+  if (keys.length > MAX_SCREEN_EFFECT_PARAMS) {
+    throw invalid(`${keys.length} params; at most ${MAX_SCREEN_EFFECT_PARAMS}`, "params");
+  }
+  const effects = world.initResource(ScreenEffects).effects;
+  let i = 0;
+  while (i < effects.length && (effects[i].source !== effect.source || effects[i].kind !== effect.kind))
+    i++;
+  if (i === MAX_SCREEN_EFFECTS) return false;
+  const e = effects[i];
+  if (e) {
+    e.screen[0] = effect.screen[0];
+    e.screen[1] = effect.screen[1];
+    e.radius = effect.radius;
+    e.ttlMs = effect.ttlMs;
+    e.params = effect.params;
+  } else effects.push({ ...effect, screen: [effect.screen[0], effect.screen[1]] });
+  world.touchResource(ScreenEffects);
+  return true;
+}
+function clearScreenEffects(world, source) {
+  const value = world.tryResource(ScreenEffects);
+  if (!value || value.effects.length === 0) return;
+  if (source === void 0) value.effects.length = 0;
+  else value.effects = value.effects.filter((e) => e.source !== source);
+  world.touchResource(ScreenEffects);
+}
+const NO_OFFSET = [0, 0];
+function forwardScreenEffects(from, to, offset = NO_OFFSET) {
+  const source = from.tryResource(ScreenEffects)?.effects ?? [];
+  const out = to.initResource(ScreenEffects).effects;
+  const n = Math.min(source.length, MAX_SCREEN_EFFECTS);
+  for (let i = 0; i < n; i++) {
+    const s = source[i];
+    const d = out[i];
+    if (d) {
+      d.kind = s.kind;
+      d.radius = s.radius;
+      d.ttlMs = s.ttlMs;
+      d.source = s.source;
+      d.params = s.params;
+    } else out.push({ ...s, screen: [0, 0] });
+    const e = out[i];
+    e.screen[0] = s.screen[0] - offset[0];
+    e.screen[1] = s.screen[1] - offset[1];
+  }
+  if (out.length === 0 && n === 0) return;
+  out.length = n;
+  to.touchResource(ScreenEffects);
+}
+function onScreenEffect(world, kind, handler) {
+  world.initResource(ScreenEffectHandlers).kinds.set(kind, handler);
+}
+const SCREEN_EFFECTS_DEMAND = "render/screen-effects";
+const expireScreenEffects = defineSystem({
+  name: "render/expire-screen-effects",
+  description: "Counts ScreenEffects down by the frame time and drops expired ones; holds frames while any live.",
+  run: (_, world) => {
+    const effects = world.tryResource(ScreenEffects)?.effects;
+    let n = 0;
+    if (effects && effects.length > 0) {
+      const ms = world.resource(Time).delta * 1e3;
+      for (let i = 0; i < effects.length; i++) {
+        const e = effects[i];
+        e.ttlMs -= ms;
+        if (e.ttlMs > 0 && n < MAX_SCREEN_EFFECTS) effects[n++] = e;
+      }
+      effects.length = n;
+    }
+    const live = world.tryResource(ScreenEffectHandlers)?.live.length ?? 0;
+    world.tryResource(FrameDemand)?.set(SCREEN_EFFECTS_DEMAND, n > 0 || live > 0);
+  }
+});
+function despawnAll(world, entities) {
+  for (const e of entities) if (world.isAlive(e)) world.despawn(e);
+}
+const runScreenEffects = defineSystem({
+  name: "render/screen-effects",
+  description: "Runs the handlers registered with onScreenEffect for live ScreenEffects.",
+  run: (_, world) => {
+    const handlers = world.tryResource(ScreenEffectHandlers);
+    const effects = world.tryResource(ScreenEffects)?.effects;
+    if (!handlers || handlers.live.length === 0 && (!effects || effects.length === 0)) return;
+    const live = handlers.live;
+    for (let i = 0; i < live.length; i++) live[i].seen = false;
+    const dt = world.resource(Time).delta;
+    if (effects) {
+      for (let i = 0; i < effects.length; i++) {
+        const e = effects[i];
+        let found;
+        for (let j = 0; j < live.length; j++) {
+          const l = live[j];
+          if (l.source === e.source && l.kind === e.kind) {
+            found = l;
+            break;
+          }
+        }
+        if (found) {
+          found.seen = true;
+          found.last = e;
+          found.handler.update?.(world, e, found.entities, dt);
+          continue;
+        }
+        const handler = handlers.kinds.get(e.kind);
+        if (!handler) {
+          if (!handlers.reported.has(e.kind)) {
+            handlers.reported.add(e.kind);
+            world.tryResource(LogResource)?.log("warn", `No handler draws "${e.kind}" effects`, {
+              code: "render/unhandled-screen-effect",
+              hint: "Register one in this app with onScreenEffect(world, kind, handler)."
+            });
+          }
+          continue;
+        }
+        live.push({
+          source: e.source,
+          kind: e.kind,
+          handler,
+          entities: handler.start(world, e) ?? [],
+          last: e,
+          seen: true
+        });
+      }
+    }
+    let kept = 0;
+    for (let i = 0; i < live.length; i++) {
+      const l = live[i];
+      if (l.seen) {
+        live[kept++] = l;
+        continue;
+      }
+      if (l.handler.end) l.handler.end(world, l.last, l.entities);
+      else despawnAll(world, l.entities);
+    }
+    live.length = kept;
+  }
+});
+function describeScreenEffects(world) {
+  const handlers = world.tryResource(ScreenEffectHandlers);
+  return {
+    effects: (world.tryResource(ScreenEffects)?.effects ?? []).map((e) => ({
+      ...e,
+      screen: [...e.screen]
+    })),
+    kinds: handlers ? [...handlers.kinds.keys()].sort() : [],
+    drawing: (handlers?.live ?? []).map((l) => ({
+      kind: l.kind,
+      source: l.source,
+      entities: l.entities.length
+    }))
+  };
+}
+export {
+  MAX_SCREEN_EFFECTS,
+  MAX_SCREEN_EFFECT_PARAMS,
+  SCREEN_EFFECTS_DEMAND,
+  ScreenEffectHandlers,
+  ScreenEffects,
+  clearScreenEffects,
+  describeScreenEffects,
+  expireScreenEffects,
+  forwardScreenEffects,
+  onScreenEffect,
+  publishScreenEffect,
+  runScreenEffects
+};

package/dist/shaders.d.ts

@@ -25,6 +25,12 @@ export declare const ViewUniform: import("@aethervtt/shard-core").ComponentDef<{
      * that sun, applied to its light (spec 0044). All ones without an atmosphere.
      */
     readonly sunTransmittance: import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]> | undefined) => import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32">);
+    /**
+     * Screen scale (0057): render pixels per CSS pixel (x); world units per render pixel at one
+     * unit of view depth, or everywhere when orthographic (y); 1 when orthographic (z). A CSS-pixel
+     * width w at view depth d is w · x · y · d world units (w · x · y orthographic).
+     */
+    readonly pixelScale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<import("@aethervtt/shard-core").Vec4> | undefined) => import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">);
 }>;
 export declare const viewLayout: import("@aethervtt/shard-shader").WgslLayout<{
     readonly viewProj: import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]> | undefined) => import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32">);
@@ -51,6 +57,12 @@ export declare const viewLayout: import("@aethervtt/shard-shader").WgslLayout<{
      * that sun, applied to its light (spec 0044). All ones without an atmosphere.
      */
     readonly sunTransmittance: import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]> | undefined) => import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32">);
+    /**
+     * Screen scale (0057): render pixels per CSS pixel (x); world units per render pixel at one
+     * unit of view depth, or everywhere when orthographic (y); 1 when orthographic (z). A CSS-pixel
+     * width w at view depth d is w · x · y · d world units (w · x · y orthographic).
+     */
+    readonly pixelScale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<import("@aethervtt/shard-core").Vec4> | undefined) => import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">);
 }>;
 export declare const materialLayout: import("@aethervtt/shard-shader").WgslLayout<{
     baseColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
@@ -59,6 +71,7 @@ export declare const materialLayout: import("@aethervtt/shard-shader").WgslLayou
     emissive: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
     emissiveLuminance: import("@aethervtt/shard-core").FieldType<number, "f32">;
     doubleSided: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    deferUntilReady: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
     alphaMode: import("@aethervtt/shard-core").FieldType<"additive" | "alpha" | "mask" | "opaque" | "premultiplied", "u8">;
     alphaCutoff: import("@aethervtt/shard-core").FieldType<number, "f32">;
     normalScale: import("@aethervtt/shard-core").FieldType<number, "f32">;

package/dist/shaders.js

@@ -26,7 +26,13 @@ const ViewUniform = defineComponent("render/ViewUniform", {
    * Per directional light (column i): the atmosphere's transmittance (rgb) between the camera and
    * that sun, applied to its light (spec 0044). All ones without an atmosphere.
    */
-  sunTransmittance: t.mat4
+  sunTransmittance: t.mat4,
+  /**
+   * Screen scale (0057): render pixels per CSS pixel (x); world units per render pixel at one
+   * unit of view depth, or everywhere when orthographic (y); 1 when orthographic (z). A CSS-pixel
+   * width w at view depth d is w · x · y · d world units (w · x · y orthographic).
+   */
+  pixelScale: t.vec4
 });
 const viewLayout = wgslLayout(ViewUniform);
 const materialLayout = wgslLayout(StandardMaterial);
@@ -77,9 +83,9 @@ const FLAG_VISIBLE: u32 = 1u;
 const FLAG_CASTER: u32 = 2u;
 const FLAG_RECEIVER: u32 = 4u;
 
-@group(2) @binding(0) var<storage, read> instances: array<Instance>;
+@data @group(2) @binding(0) var<storage, read> instances: array<Instance>;
 /** The view's culled slots; a draw's instance_index indexes this. */
-@group(2) @binding(1) var<storage, read> visible: array<u32>;
+@data @group(2) @binding(1) var<storage, read> visible: array<u32>;
 
 /** Visible-list entries: slot in the low 28 bits, LOD level in the top 4. */
 const SLOT_MASK: u32 = 0x0fffffffu;
@@ -98,7 +104,7 @@ fn instance_world(inst: Instance, position: vec3f) -> vec3f {
 }
 
 /** Last frame's transform of each slot (three affine rows), for motion vectors. */
-@group(2) @binding(2) var<storage, read> previous: array<vec4f>;
+@data @group(2) @binding(2) var<storage, read> previous: array<vec4f>;
 
 /** Where an object-space position was last frame, in world space. */
 fn previous_world(instance_index: u32, position: vec3f) -> vec3f {
@@ -171,9 +177,9 @@ struct Deform {
 const FLAG_SKINNED: u32 = 32u;
 const FLAG_MORPH: u32 = 64u;
 
-@group(2) @binding(3) var<storage, read> deforms: array<Deform>;
-@group(2) @binding(4) var<storage, read> poses: array<vec4f>;
-@group(2) @binding(5) var<storage, read> deform_data: array<u32>;
+@data @group(2) @binding(3) var<storage, read> deforms: array<Deform>;
+@data @group(2) @binding(4) var<storage, read> poses: array<vec4f>;
+@data @group(2) @binding(5) var<storage, read> deform_data: array<u32>;
 
 struct Deformed {
   position: vec3f,
@@ -360,6 +366,7 @@ import shard::view::view;
 import shard::pbr::types::VertexOutput;
 import shard::mesh::mesh_vertex_at;
 import shard::unlit::shading::shade;
+@if(CUTAWAY) import shard::cutaway::cutaway_clip;
 
 @vertex fn vs(
   @builtin(instance_index) instance_index: u32,
@@ -376,9 +383,11 @@ import shard::unlit::shading::shade;
 }
 
 @fragment fn fs(in: VertexOutput) -> @location(0) vec4f {
+  @if(CUTAWAY) cutaway_clip(in.world_position, in.clip.xy, in.flags);
   let c = shade(in);
   @if(MASK) if (c.a < 0.5) { discard; }
-  return vec4f(c.rgb * view.exposure, c.a);
+  @if(OPAQUE) return vec4f(c.rgb * view.exposure, 1.0);
+  @if(!OPAQUE) return vec4f(c.rgb * view.exposure, c.a);
 }`,
   "shard::pbr::brdf": `
 const PI: f32 = 3.14159265359;
@@ -416,8 +425,24 @@ struct Light {
   shadow_bias: f32,
   shadow_normal_bias: f32,
   shadow_softness: f32,
-  _pad0: f32,
-  _pad1: f32,
+  /** 0: physical; 1: tabletop (0057). */
+  falloff: f32,
+  /** Tabletop: full intensity inside this radius. */
+  bright: f32,
+}
+
+/**
+ * Distance attenuation of a point or spot light: physical inverse square windowed to zero at
+ * range, or tabletop (0057): full intensity inside bright, linear to zero at range.
+ */
+fn light_falloff(light: Light, d: f32, d2: f32) -> f32 {
+  if (light.falloff > 0.5) {
+    return clamp((light.range - d) / max(light.range - light.bright, 1e-4), 0.0, 1.0);
+  }
+  let ratio = d / light.range;
+  let r4 = ratio * ratio * ratio * ratio;
+  let window = clamp(1.0 - r4, 0.0, 1.0);
+  return window * window / d2;
 }
 
 struct DirectionalLight {
@@ -446,10 +471,29 @@ const CLUSTER_Z: u32 = 24u;
 const CLUSTER_COUNT: u32 = 3456u;
 const MAX_PER_CLUSTER: u32 = 128u;
 
-@group(0) @binding(1) var<storage, read> lights: array<Light>;
+@data(uniform, 128) @group(0) @binding(1) var<storage, read> lights: array<Light>;
 /** counts[CLUSTER_COUNT], then MAX_PER_CLUSTER light indices per cluster. */
-@group(0) @binding(2) var<storage, read> clusters: array<u32>;
-@group(0) @binding(3) var<storage, read> directional: DirectionalLights;`,
+@if(!BASELINE) @group(0) @binding(2) var<storage, read> clusters: array<u32>;
+/** Baseline (0064): a bit per packed light, 128 per cluster. */
+@if(BASELINE) @data @group(0) @binding(2) var<storage, read> cluster_bits: array<vec4u>;
+@data(uniform) @group(0) @binding(3) var<storage, read> directional: DirectionalLights;
+
+/**
+ * Baseline (0064): takes the lowest light left in \`mask\` (a cluster's bits) into \`index\`;
+ * false once none are left.
+ */
+@if(BASELINE) fn next_light(mask: ptr<function, vec4u>, index: ptr<function, u32>) -> bool {
+  for (var w = 0u; w < 4u; w++) {
+    let word = (*mask)[w];
+    if (word != 0u) {
+      let lowest = word & (~word + 1u);
+      (*mask)[w] = word ^ lowest;
+      *index = w * 32u + u32(round(log2(f32(lowest))));
+      return true;
+    }
+  }
+  return false;
+}`,
   "shard::pbr::shadows": `
 import shard::color::ign;
 
@@ -473,7 +517,7 @@ struct ShadowData {
   spot_params: array<vec4f, 8>,
 }
 
-@group(0) @binding(4) var<storage, read> shadows: ShadowData;
+@data(uniform) @group(0) @binding(4) var<storage, read> shadows: ShadowData;
 @group(0) @binding(5) var cascade_maps: texture_depth_2d_array;
 @group(0) @binding(6) var spot_maps: texture_depth_2d_array;
 @group(0) @binding(7) var point_maps: texture_depth_2d_array;
@@ -576,9 +620,11 @@ fn point_shadow(index: u32, world: vec3f, n: vec3f, bias: f32, normal_bias: f32,
 import shard::view::view;
 import shard::pbr::types::PbrInput;
 import shard::pbr::brdf::{ PI, d_ggx, v_smith_ggx_correlated, f_schlick };
-import shard::pbr::lights::{ lights, clusters, directional, LIGHT_SPOT, NO_SHADOW, CLUSTER_X, CLUSTER_Y, CLUSTER_Z, CLUSTER_COUNT, MAX_PER_CLUSTER };
+import shard::pbr::lights::{ lights, clusters, cluster_bits, next_light, directional, light_falloff, LIGHT_SPOT, NO_SHADOW, CLUSTER_X, CLUSTER_Y, CLUSTER_Z, CLUSTER_COUNT, MAX_PER_CLUSTER };
 import shard::pbr::shadows::{ directional_shadow, spot_shadow, point_shadow, cascade_index };
 import shard::pbr::environment::environment_light;
+@if(SKY_VISIBILITY) import shard::interior::interior_ambient;
+@if(BLOCKED_LIGHTS) import shard::interior::{ wall_visibility, interior_receiver };
 
 const FLAG_RECEIVER: u32 = 4u;
 
@@ -642,7 +688,39 @@ fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags:
   // Point and spot lights from this fragment's cluster: intensity (cd) / d\xB2 \xD7 window.
   let cluster = cluster_of(frag_coord, view_depth);
   var count = 0u;
-  if (cluster >= 0) {
+  @if(BLOCKED_LIGHTS) let receiver = interior_receiver(world_position, n);
+  @if(BASELINE) if (cluster >= 0) {
+    // The cluster's lights, lowest first; keep the body in step with the loop below.
+    var mask = cluster_bits[cluster];
+    var index = 0u;
+    while (next_light(&mask, &index)) {
+      count++;
+      let light = lights[index];
+      let to_light = light.position - world_position;
+      let d2 = max(dot(to_light, to_light), 1e-4);
+      let d = sqrt(d2);
+      let l = to_light / d;
+      var attenuation = light_falloff(light, d, d2);
+      if (light.kind == LIGHT_SPOT) {
+        let cd = dot(-l, light.direction);
+        let spot = clamp(cd * light.spot_scale + light.spot_offset, 0.0, 1.0);
+        attenuation *= spot * spot;
+      }
+      if (attenuation <= 0.0) { continue; }
+      @if(BLOCKED_LIGHTS) attenuation *= wall_visibility(light, receiver);
+      if (receives && light.shadow != NO_SHADOW) {
+        if (light.kind == LIGHT_SPOT) {
+          attenuation *= spot_shadow(light.shadow, world_position, n, light.position, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, frag_coord.xy);
+        } else {
+          attenuation *= point_shadow(light.shadow, world_position, n, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, frag_coord.xy);
+        }
+      }
+      let a_light = clamp(a + light.radius / (2.0 * d), 0.0, 1.0);
+      let norm = (a / a_light) * (a / a_light);
+      color += brdf(n, v, l, a_light, diffuse_color, f0, norm) * light.color * attenuation;
+    }
+  }
+  @if(!BASELINE) if (cluster >= 0) {
     count = clusters[cluster];
     let base = CLUSTER_COUNT + u32(cluster) * MAX_PER_CLUSTER;
     for (var k = 0u; k < count; k++) {
@@ -651,16 +729,14 @@ fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags:
       let d2 = max(dot(to_light, to_light), 1e-4);
       let d = sqrt(d2);
       let l = to_light / d;
-      let ratio = d / light.range;
-      let r4 = ratio * ratio * ratio * ratio;
-      let window = clamp(1.0 - r4, 0.0, 1.0);
-      var attenuation = window * window / d2;
+      var attenuation = light_falloff(light, d, d2);
       if (light.kind == LIGHT_SPOT) {
         let cd = dot(-l, light.direction);
         let spot = clamp(cd * light.spot_scale + light.spot_offset, 0.0, 1.0);
         attenuation *= spot * spot;
       }
       if (attenuation <= 0.0) { continue; }
+      @if(BLOCKED_LIGHTS) attenuation *= wall_visibility(light, receiver);
       if (receives && light.shadow != NO_SHADOW) {
         if (light.kind == LIGHT_SPOT) {
           attenuation *= spot_shadow(light.shadow, world_position, n, light.position, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, frag_coord.xy);
@@ -683,9 +759,11 @@ fn apply_lighting(p: PbrInput, world_position: vec3f, frag_coord: vec4f, flags:
     surface.occlusion *= textureLoad(ao_texture, min(vec2i(frag_coord.xy), dims - 1), 0).r;
   }
   if (view.envParams.w > 0.5) {
-    color += environment_light(surface, n, v);
+    @if(!SKY_VISIBILITY) color += environment_light(surface, n, v);
+    @if(SKY_VISIBILITY) color += interior_ambient(environment_light(surface, n, v), diffuse_color * surface.occlusion, world_position, n);
   } else {
-    color += diffuse_color * view.ambient * surface.occlusion;
+    @if(!SKY_VISIBILITY) color += diffuse_color * view.ambient * surface.occlusion;
+    @if(SKY_VISIBILITY) color += interior_ambient(diffuse_color * view.ambient * surface.occlusion, diffuse_color * surface.occlusion, world_position, n);
   }
 
   let debug = u32(view.clusterParams.w);
@@ -912,6 +990,7 @@ import shard::mesh::mesh_vertex_at;
 import shard::pbr::material::{ pbr_input, fragment_output };
 import shard::pbr::standard::material;
 import shard::pbr::lighting::apply_lighting;
+@if(CUTAWAY) import shard::cutaway::cutaway_clip;
 
 @vertex fn vs(
   @builtin(instance_index) instance_index: u32,
@@ -928,12 +1007,15 @@ import shard::pbr::lighting::apply_lighting;
 }
 
 @fragment fn fs(in: VertexOutput) -> @location(0) vec4f {
+  @if(CUTAWAY) cutaway_clip(in.world_position, in.clip.xy, in.flags);
   let p = pbr_input(in);
   if (material.alphaMode == 1u && p.alpha < material.alphaCutoff) { discard; }
   let color = (apply_lighting(p, in.world_position, in.clip, in.flags) + p.emissive) * view.exposure;
   // Premultiplied blending expects color \xD7 alpha; additive and alpha blend multiply in hardware.
   @if(PREMULTIPLY) return fragment_output(vec4f(color * p.alpha, p.alpha));
-  @if(!PREMULTIPLY) return fragment_output(vec4f(color, p.alpha));
+  // Opaque and masked surfaces cover their pixel, whatever their base color's alpha (0052).
+  @if(OPAQUE) return vec4f(fragment_output(vec4f(color, p.alpha)).rgb, 1.0);
+  @if(!PREMULTIPLY && !OPAQUE) return fragment_output(vec4f(color, p.alpha));
 }`,
   "shard::post::depth_resolve": `
 @group(0) @binding(0) var depth_ms: texture_depth_multisampled_2d;
@@ -950,7 +1032,7 @@ import shard::pbr::types::PbrInput;
 @group(0) @binding(10) var env_lut: texture_2d<f32>;
 @group(0) @binding(11) var env_sampler: sampler;
 /** SH9, convolved with the cosine lobe and divided by \u03C0: dot with the basis = irradiance / \u03C0. */
-@group(0) @binding(12) var<storage, read> env_sh: array<vec4f, 9>;
+@data(uniform) @group(0) @binding(12) var<storage, read> env_sh: array<vec4f, 9>;
 @group(0) @binding(13) var env_source: texture_cube<f32>;
 
 const ENV_SPECULAR_MIPS: f32 = 5.0;
@@ -1065,6 +1147,13 @@ fn apply_lut(c: vec3f) -> vec3f {
 @fragment fn fs(@builtin(position) p: vec4f) -> @location(0) vec4f {
   let texel = textureLoad(hdr, vec2i(p.xy), 0);
   var hdr_color = max(texel.rgb, vec3f(0.0));
+  @if(TRANSPARENT) var alpha = 1.0;
+  @if(TRANSPARENT) {
+    // Premultiplied (0052): light over less coverage raises alpha, so a glow shows over the page;
+    // then the color is un-premultiplied for grading and the curve, and premultiplied again below.
+    alpha = clamp(max(texel.a, max(hdr_color.r, max(hdr_color.g, hdr_color.b))), 0.0, 1.0);
+    hdr_color = hdr_color / max(alpha, 1e-6);
+  }
   let flags = params.mode.z;
   if ((flags & 1u) != 0u) { hdr_color = grade(hdr_color); }
   if ((flags & 2u) != 0u) {
@@ -1080,9 +1169,12 @@ fn apply_lut(c: vec3f) -> vec3f {
     let n = ign(p.xy) + ign(p.xy + vec2f(71.0, 13.0)) - 1.0;
     c = c + vec3f(n / 255.0);
   }
+  // The page composites in display space, so premultiply there; it keeps rgb <= alpha.
+  @if(TRANSPARENT) c = clamp(c, vec3f(0.0), vec3f(1.0)) * alpha;
   // sRGB targets encode in hardware: hand them linear values.
   @if(SRGB_TARGET) c = srgb_to_linear(clamp(c, vec3f(0.0), vec3f(1.0)));
-  return vec4f(c, 1.0);
+  @if(TRANSPARENT) return vec4f(c, max(alpha, max(c.r, max(c.g, c.b))));
+  @if(!TRANSPARENT) return vec4f(c, 1.0);
 }`,
   "shard::post::upscale": `
 struct Upscale {
@@ -1094,8 +1186,18 @@ struct Upscale {
 @group(0) @binding(1) var input_sampler: sampler;
 @group(0) @binding(2) var<uniform> upscale: Upscale;
 
-fn at(uv: vec2f) -> vec3f {
-  return textureSampleLevel(input, input_sampler, uv, 0.0).rgb;
+@if(!TRANSPARENT) alias Texel = vec3f;
+@if(TRANSPARENT) alias Texel = vec4f;
+
+fn at(uv: vec2f) -> Texel {
+  @if(!TRANSPARENT) return textureSampleLevel(input, input_sampler, uv, 0.0).rgb;
+  @if(TRANSPARENT) return textureSampleLevel(input, input_sampler, uv, 0.0);
+}
+
+/** Opaque views write alpha 1; premultiplied ones keep rgb <= alpha after sharpening (0052). */
+fn out(c: Texel) -> vec4f {
+  @if(!TRANSPARENT) return vec4f(c, 1.0);
+  @if(TRANSPARENT) return vec4f(c.rgb, max(c.a, max(c.r, max(c.g, c.b))));
 }
 
 /**
@@ -1106,7 +1208,7 @@ fn at(uv: vec2f) -> vec3f {
   let uv = frag.xy * upscale.params.xy;
   let c = at(uv);
   let k = upscale.params.z;
-  if (k <= 0.0) { return vec4f(c, 1.0); }
+  if (k <= 0.0) { return out(c); }
   let texel = 1.0 / vec2f(textureDimensions(input));
   let n = at(uv + vec2f(0.0, -texel.y));
   let s = at(uv + vec2f(0.0, texel.y));
@@ -1115,7 +1217,7 @@ fn at(uv: vec2f) -> vec3f {
   let lo = min(c, min(min(n, s), min(e, w)));
   let hi = max(c, max(max(n, s), max(e, w)));
   let sharp = c + (4.0 * c - (n + s + e + w)) * (0.25 * k);
-  return vec4f(clamp(sharp, lo, hi), 1.0);
+  return out(clamp(sharp, lo, hi));
 }`,
   "shard::post::common": `
 import shard::view::view;

package/dist/shadow-catcher.d.ts

@@ -0,0 +1,9 @@
+export declare const SHADOW_CATCHER_SHADERS: Record<string, string>;
+/**
+ * Invisible except for the shadows it receives (0052): color 0, alpha `opacity × (1 − visibility)`
+ * over every shadow-casting light. Premultiplied, so it darkens what's behind it by that alpha.
+ * Needs `shadowCatcherPlugin` (in `forwardPlugin`).
+ */
+export declare const ShadowCatcher: import("./materials.js").MaterialType;
+/** The ShadowCatcher material's shader. */
+export declare const shadowCatcherPlugin: import("@aethervtt/shard-runtime").Plugin;