@vitreajs/vitrea 0.1.0

package/dist/index.js

@@ -0,0 +1,1001 @@
+import { MOTION_DRIVER_BY_CHANNEL, INTERACTION_STATES, SHAPE_FAMILIES } from './chunk-ST6GFEQT.js';
+
+// src/accessibility.ts
+var ACCESSIBILITY_FLAGS = [
+  "reducedTransparency",
+  "reducedMotion",
+  "increasedContrast",
+  "forcedColors"
+];
+var OVERRIDABLE_ACCESSIBILITY_FLAGS = [
+  "reducedTransparency",
+  "reducedMotion",
+  "increasedContrast"
+];
+var NOMINAL_ACCESSIBILITY_POLICY = {
+  reducedTransparency: false,
+  reducedMotion: false,
+  increasedContrast: false,
+  forcedColors: false,
+  material: {
+    glass: "material",
+    colorSource: "material",
+    frost: "nominal",
+    refraction: "nominal",
+    occlusion: "nominal",
+    border: "nominal",
+    ambientTint: "nominal",
+    foreground: "adaptive"
+  },
+  motion: {
+    overshoot: "elastic",
+    deformation: "nominal",
+    shimmer: "travel",
+    morph: "elastic",
+    crossfade: "never",
+    positionalContinuity: true
+  }
+};
+var ACCESSIBILITY_BEHAVIOR_TABLE = {
+  reducedTransparency: {
+    material: { frost: "increased", refraction: "reduced", occlusion: "increased" }
+  },
+  increasedContrast: {
+    material: { border: "strong", foreground: "near-monochrome", ambientTint: "reduced" }
+  },
+  reducedMotion: {
+    motion: {
+      overshoot: "none",
+      deformation: "none",
+      shimmer: "none",
+      morph: "non-elastic",
+      crossfade: "large-plane-shifts"
+    }
+  },
+  forcedColors: {
+    // "system colors, borders, no glass" — and with the glass gone, every
+    // optical axis follows it: nothing to frost, lens, or tint, and a flat
+    // system fill that hides the backdrop entirely.
+    material: {
+      glass: "none",
+      colorSource: "system",
+      frost: "none",
+      refraction: "none",
+      occlusion: "opaque",
+      border: "strong",
+      ambientTint: "none",
+      foreground: "near-monochrome"
+    }
+  }
+};
+var ACCESSIBILITY_PRECEDENCE = [
+  "reducedMotion",
+  "reducedTransparency",
+  "increasedContrast",
+  "forcedColors"
+];
+var resolveFlag = (detected, override) => override === void 0 || override === "system" ? detected : override;
+var REDUCED_TRANSPARENCY_UNDETECTABLE = {
+  code: "reduced-transparency-undetectable",
+  severity: "warning",
+  subjects: [],
+  message: 'This platform cannot query `prefers-reduced-transparency`, so leaving `reducedTransparency` on "system" silently resolves it to false and the preference is lost. Set the GlassRoot `reducedTransparency` prop to an explicit boolean (\xA7Accessibility policy).'
+};
+function resolveAccessibilityPolicy(system, overrides = {}, diagnostics) {
+  const active = {
+    reducedTransparency: resolveFlag(system.reducedTransparency, overrides.reducedTransparency),
+    reducedMotion: resolveFlag(system.reducedMotion, overrides.reducedMotion),
+    increasedContrast: resolveFlag(system.increasedContrast, overrides.increasedContrast),
+    // Deliberately not overridable — see OverridableAccessibilityFlag.
+    forcedColors: system.forcedColors
+  };
+  const leftToTheSystem = overrides.reducedTransparency === void 0 || overrides.reducedTransparency === "system";
+  if (leftToTheSystem && !system.reducedTransparencySupported) {
+    diagnostics?.report(REDUCED_TRANSPARENCY_UNDETECTABLE);
+  }
+  let material = NOMINAL_ACCESSIBILITY_POLICY.material;
+  let motion = NOMINAL_ACCESSIBILITY_POLICY.motion;
+  for (const flag of ACCESSIBILITY_PRECEDENCE) {
+    if (!active[flag]) continue;
+    const row = ACCESSIBILITY_BEHAVIOR_TABLE[flag];
+    if (row.material !== void 0) material = { ...material, ...row.material };
+    if (row.motion !== void 0) motion = { ...motion, ...row.motion };
+  }
+  return { ...active, material, motion };
+}
+
+// src/backdrop-hint.ts
+function normalizeChannel(value) {
+  if (value === void 0) return { corrected: false };
+  if (!Number.isFinite(value)) return { corrected: true };
+  if (value < 0) return { value: 0, corrected: true };
+  if (value > 1) return { value: 1, corrected: true };
+  return { value, corrected: false };
+}
+function normalizeHint(hint, groupId, diagnostics) {
+  const luminance = normalizeChannel(hint.luminance);
+  const complexity = normalizeChannel(hint.complexity);
+  if (luminance.corrected || complexity.corrected) {
+    diagnostics?.report({
+      code: "backdrop-hint-out-of-range",
+      severity: "warning",
+      subjects: [groupId],
+      message: `X6: the backdrop hint for group "${groupId}" carried a luminance or complexity outside 0..1. Both are normalised fractions; out-of-range values were clamped and non-finite ones dropped.`
+    });
+  }
+  return {
+    tone: hint.tone,
+    ...luminance.value === void 0 ? {} : { luminance: luminance.value },
+    ...complexity.value === void 0 ? {} : { complexity: complexity.value }
+  };
+}
+function resolveBackdropHint(request) {
+  const { groupId, backdrop, estimator, diagnostics } = request;
+  if (backdrop !== void 0) {
+    if (estimator !== void 0) {
+      diagnostics?.report({
+        code: "backdrop-hint-redundant-estimator",
+        severity: "warning",
+        subjects: [groupId],
+        message: `X6: group "${groupId}" has both an explicit backdrop hint and the estimator "${estimator.id}". The explicit hint wins; remove one so the source of adaptation is unambiguous.`
+      });
+    }
+    return { availability: "author-hint", hint: normalizeHint(backdrop, groupId, diagnostics) };
+  }
+  const estimated = estimator?.estimate(groupId);
+  if (estimated === void 0) return { availability: "none" };
+  return { availability: "estimator", hint: normalizeHint(estimated, groupId, diagnostics) };
+}
+
+// src/capability.ts
+var WEBGPU_AVAILABILITIES = [
+  "not-requested",
+  "pending",
+  "unavailable",
+  "available"
+];
+var GOVERNOR_PRESSURES = ["none", "degrade-in-tier", "demote-tier"];
+var HINT_AVAILABILITIES = ["none", "author-hint", "estimator"];
+var REASON_PRECEDENCE = [
+  "no-webgpu",
+  "device-lost",
+  "no-texture-supplied",
+  "tainted-source",
+  "incompatible-texture",
+  "no-backdrop-filter",
+  "probe-failed",
+  "governor"
+];
+var DEMOTION_RECOVERY = {
+  "no-webgpu": {
+    trigger: "none",
+    explanation: "WebGPU is unavailable in this browser session. Nothing the app can do recovers it; a user enabling support means a new session."
+  },
+  "no-backdrop-filter": {
+    trigger: "probe-repassed",
+    explanation: "The backdrop-filter probe failed. Re-running it after the page's filter context changes can pass."
+  },
+  "tainted-source": {
+    trigger: "source-replaced",
+    explanation: "A CORS-tainted source cannot be read into a GPU texture. Register a same-origin or CORS-permitted source."
+  },
+  "incompatible-texture": {
+    trigger: "source-replaced",
+    explanation: "The supplied texture view does not satisfy the declared usage, format or dimension requirements. Register a conforming source."
+  },
+  "no-texture-supplied": {
+    trigger: "source-replaced",
+    explanation: "The source is declared as a texture and no pixels have been handed over for it yet, so there is nothing to sample. Supply the canvas, image or video behind it \u2014 the group keeps drawing tint, rim and glow until then."
+  },
+  "device-lost": {
+    trigger: "device-restored",
+    explanation: "The GPUDevice was lost. vitrea-owned devices re-request automatically; an app-owned device needs the replacement-device callback and the resource re-registration handshake."
+  },
+  "probe-failed": {
+    trigger: "probe-repassed",
+    explanation: "The backdrop-proxy conformance probe found this engine's proxy sampling non-equivalent. It clears if the probe passes on a later run."
+  },
+  governor: {
+    trigger: "pressure-released",
+    explanation: "The quality governor switched tiers under sustained pressure. It restores after its hysteresis and cooldown elapse."
+  }
+};
+function applicableFaults(inputs) {
+  const { platform, governor, configuredSource } = inputs;
+  const faults = /* @__PURE__ */ new Set();
+  if (platform.webgpu === "unavailable") faults.add("no-webgpu");
+  if (platform.webgpu === "available" && platform.deviceHealth === "lost") {
+    faults.add("device-lost");
+  }
+  if (configuredSource === "texture") {
+    if (inputs.source.supply === "absent") {
+      faults.add("no-texture-supplied");
+    } else {
+      if (inputs.source.taint === "tainted") faults.add("tainted-source");
+      if (inputs.source.textureCompatibility === "incompatible") faults.add("incompatible-texture");
+    }
+  } else {
+    if (!platform.backdropFilter) {
+      faults.add("no-backdrop-filter");
+    } else if (platform.backdropProxyConformance === "fail") {
+      faults.add("probe-failed");
+    }
+  }
+  if (governor === "demote-tier") faults.add("governor");
+  return REASON_PRECEDENCE.filter((reason) => faults.has(reason));
+}
+var RENDERER_FAULTS = [
+  "no-webgpu",
+  "device-lost",
+  "probe-failed",
+  "governor"
+];
+var SAMPLING_FAULTS = [
+  "tainted-source",
+  "incompatible-texture",
+  "no-texture-supplied",
+  "no-backdrop-filter"
+];
+function resolveGlassGroupState(inputs) {
+  const faults = applicableFaults(inputs);
+  const configuredSource = inputs.configuredSource;
+  const rendererDemoted = faults.some((fault) => RENDERER_FAULTS.includes(fault));
+  const samplingDemoted = faults.some((fault) => SAMPLING_FAULTS.includes(fault));
+  const cssWithoutFault = inputs.platform.webgpu === "not-requested" || inputs.platform.webgpu === "pending";
+  const activeRenderer = cssWithoutFault || rendererDemoted ? "css" : "webgpu";
+  const sampling = (() => {
+    if (activeRenderer === "css") {
+      return {
+        samplingBackend: inputs.platform.backdropFilter ? "css-backdrop" : "none",
+        refraction: "none"
+      };
+    }
+    if (samplingDemoted) {
+      return { samplingBackend: "none", refraction: "none" };
+    }
+    return configuredSource === "texture" ? { samplingBackend: "gpu-texture", refraction: "true" } : { samplingBackend: "css-backdrop", refraction: "approximate" };
+  })();
+  const analysis = sampling.samplingBackend === "gpu-texture" ? "exact" : inputs.hint === "none" ? "none" : "hint";
+  const reason = faults[0];
+  return {
+    configuredSource,
+    activeRenderer,
+    ...sampling,
+    analysis,
+    health: reason === void 0 ? "ok" : "demoted",
+    ...reason === void 0 ? {} : { demotionReason: reason }
+  };
+}
+var STATE_KEYS = [
+  "configuredSource",
+  "activeRenderer",
+  "samplingBackend",
+  "refraction",
+  "analysis",
+  "health",
+  "demotionReason"
+];
+var sameState = (a, b) => STATE_KEYS.every((key) => a[key] === b[key]);
+function classifyStateChange(previous, next) {
+  if (previous === void 0) {
+    return {
+      kind: "initial",
+      ...next.demotionReason === void 0 ? {} : { reason: next.demotionReason }
+    };
+  }
+  if (sameState(previous, next)) return { kind: "unchanged" };
+  if (previous.health === "ok" && next.demotionReason !== void 0) {
+    return { kind: "demoted", reason: next.demotionReason };
+  }
+  if (previous.demotionReason !== void 0 && next.health === "ok") {
+    return { kind: "recovered", from: previous.demotionReason };
+  }
+  return {
+    kind: "changed",
+    ...next.demotionReason === void 0 ? {} : { reason: next.demotionReason }
+  };
+}
+
+// src/diagnostics.ts
+var DIAGNOSTIC_CODES = [
+  /** Two glass surfaces overlap inside one plane — the sandwich cannot express it (X1). */
+  "same-plane-overlap",
+  /** `regular` and `clear` nodes share one GlassGroup (§Material variants). */
+  "variant-mixing",
+  /** A group's `mergeDistance` is below its `samplingPadding`, so proxies can double-filter (X1). */
+  "merge-distance-below-padding",
+  /** Two groups' padded proxies cover the same pixels, so the filter applies twice (X1). */
+  "group-proxy-overlap",
+  /** A `clear` node has no dimming policy, so it resolved to `regular` instead. */
+  "clear-variant-needs-dimming",
+  /** A foreground mode the resolved state cannot support; the nearest legal mode was used. */
+  "foreground-mode-illegal",
+  /** A `sampled-async` rate or hysteresis outside the supported range was clamped. */
+  "foreground-rate-clamped",
+  /** A backdrop hint carried a luminance/complexity outside 0..1. */
+  "backdrop-hint-out-of-range",
+  /** Both an explicit hint and an estimator provider are configured; the explicit hint wins (X6). */
+  "backdrop-hint-redundant-estimator",
+  /** `reducedTransparency` is left on "system" where the platform cannot detect it. */
+  "reduced-transparency-undetectable",
+  /** A frame-phase operation was performed in the wrong phase. */
+  "frame-phase-violation"
+];
+var KEY_SEPARATOR = "\u241F";
+var keyOf = (diagnostic) => [diagnostic.code, ...diagnostic.subjects].join(KEY_SEPARATOR);
+function createDiagnosticsChannel(options = {}) {
+  const { sink, dedupe = true } = options;
+  const retained = [];
+  const seen = /* @__PURE__ */ new Set();
+  return {
+    report(diagnostic) {
+      if (dedupe) {
+        const key = keyOf(diagnostic);
+        if (seen.has(key)) return;
+        seen.add(key);
+      }
+      retained.push(diagnostic);
+      sink?.(diagnostic);
+    },
+    get reported() {
+      return retained;
+    },
+    clear() {
+      retained.length = 0;
+      seen.clear();
+    }
+  };
+}
+
+// src/foreground.ts
+var FOREGROUND_MODES = ["sampled-async", "author-hint", "fixed"];
+var SAMPLED_ASYNC_RATE_LIMITS = {
+  minHz: 1,
+  maxHz: 15,
+  minHysteresis: 0.02,
+  maxHysteresis: 0.5
+};
+var SAMPLED_ASYNC_DEFAULTS = { rateHz: 4, hysteresis: 0.06 };
+function legalModes(analysis) {
+  switch (analysis) {
+    case "exact":
+      return FOREGROUND_MODES;
+    case "hint":
+      return ["author-hint", "fixed"];
+    case "none":
+      return ["fixed"];
+  }
+}
+var clamp = (value, min, max) => Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : min;
+function validateSampled(requested, options) {
+  const { minHz, maxHz, minHysteresis, maxHysteresis } = SAMPLED_ASYNC_RATE_LIMITS;
+  const rateHz = clamp(requested.rateHz, minHz, maxHz);
+  const hysteresis = clamp(requested.hysteresis, minHysteresis, maxHysteresis);
+  if (rateHz !== requested.rateHz || hysteresis !== requested.hysteresis) {
+    options.diagnostics?.report({
+      code: "foreground-rate-clamped",
+      severity: "warning",
+      subjects: [options.subject ?? "*"],
+      message: `Foreground sampled-async parameters were clamped to the supported range (rateHz ${minHz}..${maxHz}, hysteresis ${minHysteresis}..${maxHysteresis}). Readback is low-frequency by contract, never per-frame.`
+    });
+  }
+  return { mode: "sampled-async", rateHz, hysteresis };
+}
+function resolveForegroundAdaptation(requested, state, options = {}) {
+  const legal = legalModes(state.analysis);
+  if (legal.includes(requested.mode)) {
+    return {
+      adaptation: requested.mode === "sampled-async" ? validateSampled(requested, options) : requested
+    };
+  }
+  const from = requested.mode;
+  const to = FOREGROUND_MODES.slice(FOREGROUND_MODES.indexOf(from) + 1).find(
+    (mode) => legal.includes(mode)
+  );
+  const target = to ?? "fixed";
+  options.diagnostics?.report({
+    code: "foreground-mode-illegal",
+    severity: "warning",
+    subjects: [options.subject ?? "*"],
+    message: `Foreground mode "${from}" needs a state this group does not have \u2014 sampled-async requires analysis: exact, author-hint requires a backdrop hint or estimator (X6). Resolved analysis is "${state.analysis}", so "${target}" was used instead.`
+  });
+  return {
+    adaptation: target === "sampled-async" ? { ...SAMPLED_ASYNC_DEFAULTS, mode: target } : { mode: target },
+    downgraded: { from, to: target }
+  };
+}
+function defaultForegroundAdaptation(state) {
+  switch (state.analysis) {
+    case "exact":
+      return { mode: "sampled-async", ...SAMPLED_ASYNC_DEFAULTS };
+    case "hint":
+      return { mode: "author-hint" };
+    case "none":
+      return { mode: "fixed" };
+  }
+}
+
+// src/frame.ts
+var FRAME_PHASES = ["collect", "read", "update", "write", "render"];
+
+// src/material.ts
+var MATERIAL_VARIANTS = ["regular", "clear"];
+var DEFAULT_CLEAR_DIMMING = { scrim: 0.28, direction: "darken" };
+function resolveMaterial(request) {
+  const { variant, dimming, nodeId, diagnostics } = request;
+  if (variant === "regular") return { variant: "regular", adaptation: "adaptive" };
+  if (dimming === void 0) {
+    diagnostics?.report({
+      code: "clear-variant-needs-dimming",
+      severity: "error",
+      subjects: [nodeId ?? "*"],
+      message: `The clear variant requires a dimming policy (\xA7Material variants); without one its foreground is not guaranteed legible. This surface rendered as regular instead. Supply one on the group's material profile \u2014 DEFAULT_CLEAR_DIMMING is a usable starting point.`
+    });
+    return { variant: "regular", adaptation: "adaptive" };
+  }
+  return { variant: "clear", adaptation: "constrained", dimming };
+}
+function checkVariantMixing(check) {
+  const { groupId, members, diagnostics } = check;
+  const regular = members.filter((member) => member.variant === "regular");
+  const clear = members.filter((member) => member.variant === "clear");
+  if (regular.length === 0 || clear.length === 0) return false;
+  const name = (list) => list.map((member) => member.nodeId).join(", ");
+  diagnostics?.report({
+    code: "variant-mixing",
+    severity: "warning",
+    subjects: [groupId],
+    message: `Group "${groupId}" mixes material variants, which Apple's guidance advises against: regular on ${name(regular)}, clear on ${name(clear)}. Both render as authored \u2014 split them into separate groups if the mix was not deliberate.`
+  });
+  return true;
+}
+
+// src/planes.ts
+var GLASS_PLANES = ["base", "overlay"];
+var planeIndex = (plane) => GLASS_PLANES.indexOf(plane);
+function compareZSlot(a, b) {
+  const byPlane = planeIndex(a.plane) - planeIndex(b.plane);
+  return byPlane !== 0 ? byPlane : a.order - b.order;
+}
+function unionRect(a, b) {
+  const x = Math.min(a.x, b.x);
+  const y = Math.min(a.y, b.y);
+  return {
+    x,
+    y,
+    width: Math.max(a.x + a.width, b.x + b.width) - x,
+    height: Math.max(a.y + a.height, b.y + b.height) - y
+  };
+}
+function inflateRect(rect, by) {
+  return {
+    x: rect.x - by,
+    y: rect.y - by,
+    width: rect.width + by * 2,
+    height: rect.height + by * 2
+  };
+}
+function rectsOverlap(a, b) {
+  if (a.width <= 0 || a.height <= 0 || b.width <= 0 || b.height <= 0) return false;
+  return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+}
+
+// src/scene.ts
+var GlassSceneError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "GlassSceneError";
+    this.code = code;
+  }
+};
+var DEFAULT_BACKDROP_RESOLUTION = {
+  scale: 1,
+  maxDimension: 2048
+};
+var DEFAULT_GROUP_SAMPLING = {
+  samplingPadding: 24,
+  mergeDistance: 24
+};
+function applyPatch(base, patch) {
+  const next = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === void 0) delete next[key];
+    else next[key] = value;
+  }
+  return next;
+}
+var unknown = (kind, id) => new GlassSceneError("unknown-id", `Unknown ${kind} "${id}".`);
+var duplicate = (kind, id) => new GlassSceneError("duplicate-id", `Duplicate ${kind} id "${id}" \u2014 ids must be unique.`);
+function createGlassScene(options) {
+  const diagnostics = options.diagnostics ?? createDiagnosticsChannel();
+  const devMode = options.devMode ?? true;
+  const sources = /* @__PURE__ */ new Map();
+  const groups = /* @__PURE__ */ new Map();
+  const nodes = /* @__PURE__ */ new Map();
+  let platform = options.platform;
+  let governor = "none";
+  let system = options.accessibility ?? {
+    reducedTransparency: false,
+    reducedMotion: false,
+    increasedContrast: false,
+    forcedColors: false,
+    reducedTransparencySupported: true
+  };
+  let overrides = options.accessibilityOverrides ?? {};
+  let consumedFrameId;
+  let consumedEpochs = [];
+  let framePhase;
+  const FROZEN_PHASES = ["update", "write", "render"];
+  const guardFrozenScene = (subject) => {
+    if (framePhase === void 0 || !FROZEN_PHASES.includes(framePhase)) return;
+    diagnostics.report({
+      code: "frame-phase-violation",
+      severity: "error",
+      subjects: [subject],
+      message: `The scene was changed during the "${framePhase}" phase, after this frame resolved. Register, remove and patch in the "collect" phase or outside a frame \u2014 from "update" onward the resolution and the scene must agree.`
+    });
+  };
+  const requireSource = (id) => {
+    const record = sources.get(id);
+    if (record === void 0) throw unknown("backdrop source", id);
+    return record;
+  };
+  const requireGroup = (id) => {
+    const record = groups.get(id);
+    if (record === void 0) throw unknown("glass group", id);
+    return record;
+  };
+  const requireNode = (id) => {
+    const record = nodes.get(id);
+    if (record === void 0) throw unknown("glass node", id);
+    return record;
+  };
+  const groupsOfSource = (sourceId) => [...groups.values()].filter((group) => group.descriptor.backdropSourceId === sourceId);
+  const nodesOfGroup = (groupId) => [...nodes.values()].filter((node) => node.descriptor.groupId === groupId);
+  const isRebuildable = (record) => record.descriptor.kind === "texture" && record.dirtyEpoch > record.builtEpoch;
+  function capabilityInputs(group, hint) {
+    const source = requireSource(group.descriptor.backdropSourceId);
+    const pressure = group.governor ?? governor;
+    return source.descriptor.kind === "texture" ? {
+      configuredSource: "texture",
+      platform,
+      source: source.descriptor.probe,
+      governor: pressure,
+      hint
+    } : { configuredSource: "dom", platform, governor: pressure, hint };
+  }
+  const paddingOf = (group) => group.descriptor.samplingPadding ?? DEFAULT_GROUP_SAMPLING.samplingPadding;
+  function samplingOf(group) {
+    const samplingPadding = paddingOf(group);
+    const mergeDistance = group.descriptor.mergeDistance ?? samplingPadding;
+    if (devMode && mergeDistance < samplingPadding) {
+      diagnostics.report({
+        code: "merge-distance-below-padding",
+        severity: "warning",
+        subjects: [group.descriptor.id],
+        message: `Group "${group.descriptor.id}" has mergeDistance ${mergeDistance} below samplingPadding ${samplingPadding}, which X1 forbids: two members can then sit close enough for their padded proxies to overlap without having merged, and the backdrop filter applies twice over the overlap \u2014 paint-order dependent, and measured drifting up to 17/255. Raise mergeDistance to at least the padding.`
+      });
+    }
+    return { samplingPadding, mergeDistance };
+  }
+  const hintOf = (group) => resolveBackdropHint({
+    groupId: group.descriptor.id,
+    ...group.descriptor.backdrop === void 0 ? {} : { backdrop: group.descriptor.backdrop },
+    ...group.descriptor.estimator === void 0 ? {} : { estimator: group.descriptor.estimator },
+    diagnostics
+  });
+  return {
+    diagnostics,
+    get framePhase() {
+      return framePhase;
+    },
+    setFramePhase(phase) {
+      framePhase = phase;
+    },
+    registerBackdropSource(descriptor) {
+      if (sources.has(descriptor.id)) throw duplicate("backdrop source", descriptor.id);
+      guardFrozenScene(descriptor.id);
+      sources.set(descriptor.id, { descriptor, dirtyEpoch: 0, builtEpoch: 0 });
+    },
+    updateBackdropSource(id, patch) {
+      const record = requireSource(id);
+      guardFrozenScene(id);
+      if (record.descriptor.kind !== "texture") {
+        throw new GlassSceneError(
+          "wrong-source-kind",
+          `Backdrop source "${id}" is a dom source: the compositor owns its blur, so it has no resolution policy.`
+        );
+      }
+      sources.set(id, {
+        ...record,
+        descriptor: { ...record.descriptor, resolution: patch.resolution }
+      });
+    },
+    removeBackdropSource(id) {
+      requireSource(id);
+      guardFrozenScene(id);
+      const dependents = groupsOfSource(id);
+      if (dependents.length > 0) {
+        throw new GlassSceneError(
+          "in-use",
+          `Backdrop source "${id}" is in use by ${dependents.map((group) => `"${group.descriptor.id}"`).join(", ")}. Remove those groups first.`
+        );
+      }
+      sources.delete(id);
+    },
+    backdropSource(id) {
+      return sources.get(id);
+    },
+    registerGlassGroup(descriptor) {
+      if (groups.has(descriptor.id)) throw duplicate("glass group", descriptor.id);
+      requireSource(descriptor.backdropSourceId);
+      guardFrozenScene(descriptor.id);
+      groups.set(descriptor.id, { descriptor });
+    },
+    updateGlassGroup(id, patch) {
+      const record = requireGroup(id);
+      const descriptor = applyPatch(record.descriptor, patch);
+      requireSource(descriptor.backdropSourceId);
+      guardFrozenScene(id);
+      groups.set(id, { ...record, descriptor });
+    },
+    removeGlassGroup(id) {
+      requireGroup(id);
+      guardFrozenScene(id);
+      const members = nodesOfGroup(id);
+      if (members.length > 0) {
+        throw new GlassSceneError(
+          "in-use",
+          `Glass group "${id}" still holds ${members.map((node) => `"${node.descriptor.id}"`).join(", ")}. Remove those nodes first.`
+        );
+      }
+      groups.delete(id);
+    },
+    glassGroup(id) {
+      return groups.get(id);
+    },
+    groupsOfSource,
+    registerGlassNode(descriptor) {
+      if (nodes.has(descriptor.id)) throw duplicate("glass node", descriptor.id);
+      requireGroup(descriptor.groupId);
+      guardFrozenScene(descriptor.id);
+      nodes.set(descriptor.id, { descriptor });
+    },
+    updateGlassNode(id, patch) {
+      const record = requireNode(id);
+      const descriptor = applyPatch(record.descriptor, patch);
+      requireGroup(descriptor.groupId);
+      guardFrozenScene(id);
+      nodes.set(id, { ...record, descriptor });
+    },
+    removeGlassNode(id) {
+      requireNode(id);
+      guardFrozenScene(id);
+      nodes.delete(id);
+    },
+    glassNode(id) {
+      return nodes.get(id);
+    },
+    nodesOfGroup,
+    setNodeBounds(id, bounds, clip) {
+      const record = requireNode(id);
+      if (framePhase !== void 0 && framePhase !== "read") {
+        diagnostics.report({
+          code: "frame-phase-violation",
+          severity: "warning",
+          subjects: [id],
+          message: `Bounds for "${id}" were set during the "${framePhase}" phase. Batch every layout read into the "read" phase so the steady state performs none.`
+        });
+      }
+      nodes.set(id, { ...record, bounds, ...clip === void 0 ? {} : { clip } });
+    },
+    setPlatformProbe(probe) {
+      platform = probe;
+    },
+    setSourceProbe(sourceId, probe) {
+      const record = requireSource(sourceId);
+      if (record.descriptor.kind !== "texture") {
+        throw new GlassSceneError(
+          "wrong-source-kind",
+          `Backdrop source "${sourceId}" is a dom source; only texture sources carry a source probe.`
+        );
+      }
+      sources.set(sourceId, { ...record, descriptor: { ...record.descriptor, probe } });
+    },
+    setGovernorPressure(pressure, groupId) {
+      if (groupId === void 0) {
+        governor = pressure;
+        return;
+      }
+      const record = requireGroup(groupId);
+      groups.set(groupId, { ...record, governor: pressure });
+    },
+    setSystemAccessibility(preferences) {
+      system = preferences;
+    },
+    setAccessibilityOverrides(next) {
+      overrides = next;
+    },
+    accessibilityPolicy() {
+      return resolveAccessibilityPolicy(system, overrides, diagnostics);
+    },
+    markBackdropSourceDirty(id) {
+      const record = requireSource(id);
+      sources.set(id, { ...record, dirtyEpoch: record.dirtyEpoch + 1 });
+    },
+    dirtyBackdropSources() {
+      return [...sources.values()].filter(isRebuildable);
+    },
+    consumeDirtyBackdropSources(frameId) {
+      if (consumedFrameId === frameId) return [];
+      consumedFrameId = frameId;
+      const requests = [];
+      const built = [];
+      for (const record of sources.values()) {
+        if (!isRebuildable(record)) continue;
+        const consumers = groupsOfSource(record.descriptor.id).map((group) => group.descriptor.id);
+        if (consumers.length === 0) continue;
+        requests.push({
+          sourceId: record.descriptor.id,
+          epoch: record.dirtyEpoch,
+          resolution: record.descriptor.resolution ?? DEFAULT_BACKDROP_RESOLUTION,
+          groupIds: consumers
+        });
+        built.push(record);
+      }
+      consumedEpochs = built.map((record) => ({
+        id: record.descriptor.id,
+        builtEpoch: record.builtEpoch
+      }));
+      for (const record of built) {
+        sources.set(record.descriptor.id, { ...record, builtEpoch: record.dirtyEpoch });
+      }
+      return requests;
+    },
+    rollbackDirtyBackdropSources(frameId) {
+      if (consumedFrameId !== frameId) return [];
+      const restored = [];
+      for (const { id, builtEpoch } of consumedEpochs) {
+        const record = sources.get(id);
+        if (record === void 0) continue;
+        sources.set(id, { ...record, builtEpoch });
+        restored.push(id);
+      }
+      consumedEpochs = [];
+      return restored;
+    },
+    resolve() {
+      const resolvedGroups = [];
+      const resolvedNodes = [];
+      const changes = [];
+      const settled = [];
+      for (const group of groups.values()) {
+        const groupId = group.descriptor.id;
+        const hint = hintOf(group);
+        const state = resolveGlassGroupState(capabilityInputs(group, hint.availability));
+        const requested = group.descriptor.foreground ?? defaultForegroundAdaptation(state);
+        const foreground = resolveForegroundAdaptation(requested, state, { subject: groupId, diagnostics });
+        const previous = group.state;
+        const change = classifyStateChange(previous, state);
+        if (change.kind !== "unchanged") {
+          changes.push({
+            groupId,
+            ...previous === void 0 ? {} : { previous },
+            next: state,
+            change
+          });
+        }
+        settled.push({ ...group, state });
+        resolvedGroups.push({ groupId, state, hint, foreground, sampling: samplingOf(group) });
+        const profile = group.descriptor.material ?? { variant: "regular" };
+        const members = nodesOfGroup(groupId);
+        for (const node of members) {
+          const nodeId = node.descriptor.id;
+          const material = resolveMaterial({
+            variant: node.descriptor.variant ?? profile.variant,
+            ...profile.dimming === void 0 ? {} : { dimming: profile.dimming },
+            nodeId,
+            diagnostics
+          });
+          resolvedNodes.push({
+            nodeId,
+            groupId,
+            material,
+            foreground: resolveForegroundAdaptation(node.descriptor.foreground ?? requested, state, {
+              subject: nodeId,
+              diagnostics
+            })
+          });
+        }
+        if (devMode) {
+          checkVariantMixing({
+            groupId,
+            members: members.map((node) => ({
+              nodeId: node.descriptor.id,
+              variant: node.descriptor.variant ?? profile.variant
+            })),
+            diagnostics
+          });
+        }
+      }
+      for (const group of settled) groups.set(group.descriptor.id, group);
+      return {
+        groups: resolvedGroups,
+        nodes: resolvedNodes,
+        changes,
+        accessibility: resolveAccessibilityPolicy(system, overrides, diagnostics)
+      };
+    },
+    checkSamePlaneOverlap() {
+      if (!devMode) return [];
+      const measured = [...nodes.values()].filter(
+        (node) => node.bounds !== void 0
+      );
+      const overlaps = [];
+      for (let i = 0; i < measured.length; i += 1) {
+        for (let j = i + 1; j < measured.length; j += 1) {
+          const a = measured[i];
+          const b = measured[j];
+          if (a === void 0 || b === void 0) continue;
+          const plane = a.descriptor.zSlot.plane;
+          if (plane !== b.descriptor.zSlot.plane) continue;
+          if (!rectsOverlap(a.bounds, b.bounds)) continue;
+          const nodeIds = [a.descriptor.id, b.descriptor.id];
+          overlaps.push({ plane, nodeIds });
+          diagnostics.report({
+            code: "same-plane-overlap",
+            severity: "error",
+            subjects: [...nodeIds],
+            message: `Glass surfaces "${nodeIds[0]}" and "${nodeIds[1]}" overlap inside the "${plane}" plane (X1). The paint sandwich cannot put one surface's body above the other's DOM label \u2014 put the upper one on the overlay plane instead.`
+          });
+        }
+      }
+      return overlaps;
+    },
+    checkGroupProxyOverlap() {
+      if (!devMode) return [];
+      const boxes = [];
+      for (const group of groups.values()) {
+        const groupId = group.descriptor.id;
+        const padding = paddingOf(group);
+        const byPlane = /* @__PURE__ */ new Map();
+        for (const node of nodesOfGroup(groupId)) {
+          const { bounds } = node;
+          if (bounds === void 0) continue;
+          const plane = node.descriptor.zSlot.plane;
+          const grown = byPlane.get(plane);
+          byPlane.set(plane, grown === void 0 ? bounds : unionRect(grown, bounds));
+        }
+        for (const [plane, union] of byPlane) {
+          boxes.push({ groupId, plane, box: inflateRect(union, padding) });
+        }
+      }
+      const overlaps = [];
+      for (let i = 0; i < boxes.length; i += 1) {
+        for (let j = i + 1; j < boxes.length; j += 1) {
+          const a = boxes[i];
+          const b = boxes[j];
+          if (a === void 0 || b === void 0) continue;
+          if (a.plane !== b.plane || a.groupId === b.groupId) continue;
+          if (!rectsOverlap(a.box, b.box)) continue;
+          const groupIds = [a.groupId, b.groupId];
+          overlaps.push({ plane: a.plane, groupIds });
+          diagnostics.report({
+            code: "group-proxy-overlap",
+            severity: "warning",
+            subjects: [...groupIds],
+            message: `Groups "${groupIds[0]}" and "${groupIds[1]}" sit close enough in the "${a.plane}" plane that their padded backdrop proxies overlap, and X1 says the filter then applies twice over that region \u2014 paint-order dependent, measured drifting up to 17/255. mergeDistance cannot help: it only unions members inside one group. Either put these surfaces in one group so they share a proxy, or separate them by more than the sum of their samplingPadding.`
+          });
+        }
+      }
+      return overlaps;
+    }
+  };
+}
+
+// src/scheduler.ts
+function createFrameScheduler(options) {
+  const { scene } = options;
+  const participants = /* @__PURE__ */ new Map();
+  return {
+    addParticipant(participant) {
+      participants.set(participant.id, participant);
+    },
+    removeParticipant(id) {
+      participants.delete(id);
+    },
+    get participants() {
+      return [...participants.values()];
+    },
+    runFrame(frame) {
+      let resolution;
+      let overlaps = [];
+      let proxyOverlaps = [];
+      const rebuilds = [];
+      const contextFor = (phase) => ({
+        frame,
+        phase,
+        scene,
+        ...resolution === void 0 ? {} : { resolution },
+        consumeDirtyBackdropSources: () => {
+          if (phase !== "write") {
+            scene.diagnostics.report({
+              code: "frame-phase-violation",
+              severity: "error",
+              subjects: [phase],
+              message: `The dirty backdrop set was consumed during the "${phase}" phase. Pyramid rebuilds belong to the "write" phase, after the scene has resolved and before anything draws.`
+            });
+            return [];
+          }
+          const handed = scene.consumeDirtyBackdropSources(frame.id);
+          rebuilds.push(...handed);
+          return handed;
+        }
+      });
+      try {
+        for (const phase of FRAME_PHASES) {
+          scene.setFramePhase(phase);
+          if (phase === "update") resolution = scene.resolve();
+          for (const participant of [...participants.values()]) {
+            participant[phase]?.(contextFor(phase));
+          }
+          if (phase === "read") {
+            overlaps = scene.checkSamePlaneOverlap();
+            proxyOverlaps = scene.checkGroupProxyOverlap();
+          }
+        }
+      } catch (error) {
+        scene.rollbackDirtyBackdropSources(frame.id);
+        throw error;
+      } finally {
+        scene.setFramePhase(void 0);
+      }
+      return {
+        frame,
+        // `update` always runs, so this is always assigned by the time it is read.
+        resolution: resolution ?? scene.resolve(),
+        overlaps,
+        proxyOverlaps,
+        rebuilds,
+        pendingSources: scene.dirtyBackdropSources().map((source) => source.descriptor.id)
+      };
+    }
+  };
+}
+
+// src/state.ts
+var DEMOTION_REASONS = [
+  "no-webgpu",
+  "no-backdrop-filter",
+  "tainted-source",
+  "incompatible-texture",
+  "no-texture-supplied",
+  "device-lost",
+  "probe-failed",
+  "governor"
+];
+function isHealthy(state) {
+  return state.health === "ok" && state.demotionReason === void 0;
+}
+
+// src/renderer-seam.ts
+async function loadWebGPURendererModule() {
+  return import('./dist-FGJI5LQM.js');
+}
+async function loadWebGPURenderer() {
+  const { createWebGPURenderer } = await loadWebGPURendererModule();
+  return createWebGPURenderer();
+}
+
+// src/index.ts
+var VITREA_CONTRACTS = {
+  shapeFamilies: SHAPE_FAMILIES,
+  interactionStates: INTERACTION_STATES,
+  motionDrivers: MOTION_DRIVER_BY_CHANNEL
+};
+var RENDERER_TIERS = ["webgpu", "css"];
+
+export { ACCESSIBILITY_BEHAVIOR_TABLE, ACCESSIBILITY_FLAGS, ACCESSIBILITY_PRECEDENCE, DEFAULT_BACKDROP_RESOLUTION, DEFAULT_CLEAR_DIMMING, DEFAULT_GROUP_SAMPLING, DEMOTION_REASONS, DEMOTION_RECOVERY, DIAGNOSTIC_CODES, FOREGROUND_MODES, FRAME_PHASES, GLASS_PLANES, GOVERNOR_PRESSURES, GlassSceneError, HINT_AVAILABILITIES, MATERIAL_VARIANTS, NOMINAL_ACCESSIBILITY_POLICY, OVERRIDABLE_ACCESSIBILITY_FLAGS, RENDERER_TIERS, SAMPLED_ASYNC_DEFAULTS, SAMPLED_ASYNC_RATE_LIMITS, VITREA_CONTRACTS, WEBGPU_AVAILABILITIES, checkVariantMixing, classifyStateChange, compareZSlot, createDiagnosticsChannel, createFrameScheduler, createGlassScene, defaultForegroundAdaptation, inflateRect, isHealthy, loadWebGPURenderer, loadWebGPURendererModule, rectsOverlap, resolveAccessibilityPolicy, resolveBackdropHint, resolveForegroundAdaptation, resolveGlassGroupState, resolveMaterial, unionRect };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map