@pibbl/core 0.0.1

package/dist/lib/surface/resolve-surface.js

@@ -0,0 +1,184 @@
+const FITS = /* @__PURE__ */ new Set([
+  "contain",
+  "cover",
+  "fill",
+  "none",
+  "scale-down"
+]);
+function validateSurfaceConfig(canvas, config) {
+  const pixelRatio = config?.pixelRatio ?? "device";
+  validatePixelRatio(pixelRatio);
+  if (config?.viewport === "responsive") {
+    if ("fit" in config) {
+      throw new Error("Pibbl responsive viewport does not support fit.");
+    }
+    return { mode: "responsive", pixelRatio };
+  }
+  const width = config?.viewport?.width ?? canvas.width;
+  const height = config?.viewport?.height ?? canvas.height;
+  validatePositiveFinite(width, "viewport width");
+  validatePositiveFinite(height, "viewport height");
+  const fit = config?.fit ?? "contain";
+  if (!FITS.has(fit)) {
+    throw new Error(`Invalid Pibbl fit: ${String(fit)}.`);
+  }
+  return { mode: "fixed", width, height, fit, pixelRatio };
+}
+function resolveSurface(config, display, pixelRatio) {
+  validatePositiveFinite(pixelRatio, "pixelRatio");
+  if (!(display.width > 0) || !(display.height > 0)) {
+    return void 0;
+  }
+  const backingWidth = Math.max(1, Math.round(display.width * pixelRatio));
+  const backingHeight = Math.max(1, Math.round(display.height * pixelRatio));
+  const backingPixelsPerCssPixelX = backingWidth / display.width;
+  const backingPixelsPerCssPixelY = backingHeight / display.height;
+  if (config.mode === "responsive") {
+    return createSnapshot({
+      mode: "responsive",
+      fit: "fill",
+      logicalWidth: display.width,
+      logicalHeight: display.height,
+      display,
+      backingWidth,
+      backingHeight,
+      backingPixelsPerCssPixelX,
+      backingPixelsPerCssPixelY,
+      scaleX: 1,
+      scaleY: 1,
+      offsetX: 0,
+      offsetY: 0
+    });
+  }
+  const projection = resolveProjection(
+    config.fit,
+    config.width,
+    config.height,
+    display.width,
+    display.height
+  );
+  return createSnapshot({
+    mode: "fixed",
+    fit: config.fit,
+    logicalWidth: config.width,
+    logicalHeight: config.height,
+    display,
+    backingWidth,
+    backingHeight,
+    backingPixelsPerCssPixelX,
+    backingPixelsPerCssPixelY,
+    ...projection
+  });
+}
+function createLayerSurface(width, height, densityX, densityY) {
+  validatePositiveFinite(width, "layer width");
+  validatePositiveFinite(height, "layer height");
+  validatePositiveFinite(densityX, "layer densityX");
+  validatePositiveFinite(densityY, "layer densityY");
+  const backingWidth = Math.max(1, Math.round(width * densityX));
+  const backingHeight = Math.max(1, Math.round(height * densityY));
+  const effectiveX = backingWidth / width;
+  const effectiveY = backingHeight / height;
+  return createSnapshot({
+    mode: "layer",
+    fit: "fill",
+    logicalWidth: width,
+    logicalHeight: height,
+    display: { width, height },
+    backingWidth,
+    backingHeight,
+    backingPixelsPerCssPixelX: effectiveX,
+    backingPixelsPerCssPixelY: effectiveY,
+    scaleX: 1,
+    scaleY: 1,
+    offsetX: 0,
+    offsetY: 0
+  });
+}
+function resolveProjection(fit, logicalWidth, logicalHeight, displayWidth, displayHeight) {
+  const widthScale = displayWidth / logicalWidth;
+  const heightScale = displayHeight / logicalHeight;
+  let scaleX;
+  let scaleY;
+  switch (fit) {
+    case "contain":
+      scaleX = scaleY = Math.min(widthScale, heightScale);
+      break;
+    case "cover":
+      scaleX = scaleY = Math.max(widthScale, heightScale);
+      break;
+    case "fill":
+      scaleX = widthScale;
+      scaleY = heightScale;
+      break;
+    case "none":
+      scaleX = scaleY = 1;
+      break;
+    case "scale-down":
+      scaleX = scaleY = Math.min(1, widthScale, heightScale);
+      break;
+  }
+  return {
+    scaleX,
+    scaleY,
+    offsetX: (displayWidth - logicalWidth * scaleX) / 2,
+    offsetY: (displayHeight - logicalHeight * scaleY) / 2
+  };
+}
+function createSnapshot({
+  mode,
+  fit,
+  logicalWidth,
+  logicalHeight,
+  display,
+  backingWidth,
+  backingHeight,
+  backingPixelsPerCssPixelX,
+  backingPixelsPerCssPixelY,
+  scaleX,
+  scaleY,
+  offsetX,
+  offsetY
+}) {
+  const renderTransform = new DOMMatrix().scale(backingPixelsPerCssPixelX, backingPixelsPerCssPixelY).translate(offsetX, offsetY).scale(scaleX, scaleY);
+  const inverseRenderTransform = new DOMMatrix([
+    1 / (backingPixelsPerCssPixelX * scaleX),
+    0,
+    0,
+    1 / (backingPixelsPerCssPixelY * scaleY),
+    -offsetX / scaleX,
+    -offsetY / scaleY
+  ]);
+  return Object.freeze({
+    mode,
+    fit,
+    logicalWidth,
+    logicalHeight,
+    displayWidth: display.width,
+    displayHeight: display.height,
+    backingWidth,
+    backingHeight,
+    backingPixelsPerCssPixelX,
+    backingPixelsPerCssPixelY,
+    backingPixelsPerLogicalUnitX: backingPixelsPerCssPixelX * scaleX,
+    backingPixelsPerLogicalUnitY: backingPixelsPerCssPixelY * scaleY,
+    renderTransform,
+    inverseRenderTransform
+  });
+}
+function validatePixelRatio(pixelRatio) {
+  if (pixelRatio !== "device") {
+    validatePositiveFinite(pixelRatio, "pixelRatio");
+  }
+}
+function validatePositiveFinite(value, name) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`Pibbl ${name} must be a finite number greater than zero.`);
+  }
+}
+export {
+  createLayerSurface,
+  resolveSurface,
+  validateSurfaceConfig
+};
+//# sourceMappingURL=resolve-surface.js.map

package/dist/lib/surface/resolve-surface.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/surface/resolve-surface.ts"],
+  "sourcesContent": ["import type {\n  PibblConfig,\n  PibblFit,\n  PibblSurfaceSnapshot,\n  ResolvedSurfaceConfig,\n  SurfaceDisplaySize,\n} from './types.js';\n\nconst FITS = new Set<PibblFit>([\n  'contain',\n  'cover',\n  'fill',\n  'none',\n  'scale-down',\n]);\n\nexport function validateSurfaceConfig(\n  canvas: HTMLCanvasElement,\n  config?: PibblConfig,\n): ResolvedSurfaceConfig {\n  const pixelRatio = config?.pixelRatio ?? 'device';\n  validatePixelRatio(pixelRatio);\n\n  if (config?.viewport === 'responsive') {\n    if ('fit' in config) {\n      throw new Error('Pibbl responsive viewport does not support fit.');\n    }\n    return { mode: 'responsive', pixelRatio };\n  }\n\n  const width = config?.viewport?.width ?? canvas.width;\n  const height = config?.viewport?.height ?? canvas.height;\n  validatePositiveFinite(width, 'viewport width');\n  validatePositiveFinite(height, 'viewport height');\n  const fit = config?.fit ?? 'contain';\n  if (!FITS.has(fit)) {\n    throw new Error(`Invalid Pibbl fit: ${String(fit)}.`);\n  }\n  return { mode: 'fixed', width, height, fit, pixelRatio };\n}\n\nexport function resolveSurface(\n  config: ResolvedSurfaceConfig,\n  display: SurfaceDisplaySize,\n  pixelRatio: number,\n): PibblSurfaceSnapshot | undefined {\n  validatePositiveFinite(pixelRatio, 'pixelRatio');\n  if (!(display.width > 0) || !(display.height > 0)) {\n    return undefined;\n  }\n\n  const backingWidth = Math.max(1, Math.round(display.width * pixelRatio));\n  const backingHeight = Math.max(1, Math.round(display.height * pixelRatio));\n  const backingPixelsPerCssPixelX = backingWidth / display.width;\n  const backingPixelsPerCssPixelY = backingHeight / display.height;\n\n  if (config.mode === 'responsive') {\n    return createSnapshot({\n      mode: 'responsive',\n      fit: 'fill',\n      logicalWidth: display.width,\n      logicalHeight: display.height,\n      display,\n      backingWidth,\n      backingHeight,\n      backingPixelsPerCssPixelX,\n      backingPixelsPerCssPixelY,\n      scaleX: 1,\n      scaleY: 1,\n      offsetX: 0,\n      offsetY: 0,\n    });\n  }\n\n  const projection = resolveProjection(\n    config.fit,\n    config.width,\n    config.height,\n    display.width,\n    display.height,\n  );\n  return createSnapshot({\n    mode: 'fixed',\n    fit: config.fit,\n    logicalWidth: config.width,\n    logicalHeight: config.height,\n    display,\n    backingWidth,\n    backingHeight,\n    backingPixelsPerCssPixelX,\n    backingPixelsPerCssPixelY,\n    ...projection,\n  });\n}\n\nexport function createLayerSurface(\n  width: number,\n  height: number,\n  densityX: number,\n  densityY: number,\n): PibblSurfaceSnapshot {\n  validatePositiveFinite(width, 'layer width');\n  validatePositiveFinite(height, 'layer height');\n  validatePositiveFinite(densityX, 'layer densityX');\n  validatePositiveFinite(densityY, 'layer densityY');\n  const backingWidth = Math.max(1, Math.round(width * densityX));\n  const backingHeight = Math.max(1, Math.round(height * densityY));\n  const effectiveX = backingWidth / width;\n  const effectiveY = backingHeight / height;\n  return createSnapshot({\n    mode: 'layer',\n    fit: 'fill',\n    logicalWidth: width,\n    logicalHeight: height,\n    display: { width, height },\n    backingWidth,\n    backingHeight,\n    backingPixelsPerCssPixelX: effectiveX,\n    backingPixelsPerCssPixelY: effectiveY,\n    scaleX: 1,\n    scaleY: 1,\n    offsetX: 0,\n    offsetY: 0,\n  });\n}\n\nfunction resolveProjection(\n  fit: PibblFit,\n  logicalWidth: number,\n  logicalHeight: number,\n  displayWidth: number,\n  displayHeight: number,\n) {\n  const widthScale = displayWidth / logicalWidth;\n  const heightScale = displayHeight / logicalHeight;\n  let scaleX: number;\n  let scaleY: number;\n  switch (fit) {\n    case 'contain':\n      scaleX = scaleY = Math.min(widthScale, heightScale);\n      break;\n    case 'cover':\n      scaleX = scaleY = Math.max(widthScale, heightScale);\n      break;\n    case 'fill':\n      scaleX = widthScale;\n      scaleY = heightScale;\n      break;\n    case 'none':\n      scaleX = scaleY = 1;\n      break;\n    case 'scale-down':\n      scaleX = scaleY = Math.min(1, widthScale, heightScale);\n      break;\n  }\n  return {\n    scaleX,\n    scaleY,\n    offsetX: (displayWidth - logicalWidth * scaleX) / 2,\n    offsetY: (displayHeight - logicalHeight * scaleY) / 2,\n  };\n}\n\nfunction createSnapshot({\n  mode,\n  fit,\n  logicalWidth,\n  logicalHeight,\n  display,\n  backingWidth,\n  backingHeight,\n  backingPixelsPerCssPixelX,\n  backingPixelsPerCssPixelY,\n  scaleX,\n  scaleY,\n  offsetX,\n  offsetY,\n}: {\n  mode: PibblSurfaceSnapshot['mode'];\n  fit: PibblFit;\n  logicalWidth: number;\n  logicalHeight: number;\n  display: SurfaceDisplaySize;\n  backingWidth: number;\n  backingHeight: number;\n  backingPixelsPerCssPixelX: number;\n  backingPixelsPerCssPixelY: number;\n  scaleX: number;\n  scaleY: number;\n  offsetX: number;\n  offsetY: number;\n}): PibblSurfaceSnapshot {\n  const renderTransform = new DOMMatrix()\n    .scale(backingPixelsPerCssPixelX, backingPixelsPerCssPixelY)\n    .translate(offsetX, offsetY)\n    .scale(scaleX, scaleY);\n  const inverseRenderTransform = new DOMMatrix([\n    1 / (backingPixelsPerCssPixelX * scaleX),\n    0,\n    0,\n    1 / (backingPixelsPerCssPixelY * scaleY),\n    -offsetX / scaleX,\n    -offsetY / scaleY,\n  ]);\n  return Object.freeze({\n    mode,\n    fit,\n    logicalWidth,\n    logicalHeight,\n    displayWidth: display.width,\n    displayHeight: display.height,\n    backingWidth,\n    backingHeight,\n    backingPixelsPerCssPixelX,\n    backingPixelsPerCssPixelY,\n    backingPixelsPerLogicalUnitX: backingPixelsPerCssPixelX * scaleX,\n    backingPixelsPerLogicalUnitY: backingPixelsPerCssPixelY * scaleY,\n    renderTransform,\n    inverseRenderTransform,\n  });\n}\n\nfunction validatePixelRatio(pixelRatio: 'device' | number): void {\n  if (pixelRatio !== 'device') {\n    validatePositiveFinite(pixelRatio, 'pixelRatio');\n  }\n}\n\nfunction validatePositiveFinite(value: number, name: string): void {\n  if (!Number.isFinite(value) || value <= 0) {\n    throw new Error(`Pibbl ${name} must be a finite number greater than zero.`);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/surface/root-surface.d.ts

@@ -0,0 +1,7 @@
+import type { PibblInstance } from '../types.js';
+import type { PibblConfig, PibblSurfaceSnapshot, LayerSurfaceState, RootSurfaceState, SurfaceDisplaySize } from './types.js';
+export declare function createRootSurfaceState(canvas: HTMLCanvasElement, config?: PibblConfig): RootSurfaceState;
+export declare function createLegacyLayerSurfaceState(width: number, height: number): LayerSurfaceState;
+export declare function mountRootSurface(instance: PibblInstance, canvas: HTMLCanvasElement): void;
+export declare function prepareSurface(instance: PibblInstance): PibblSurfaceSnapshot | undefined;
+export declare function readCanvasContentBox(canvas: HTMLCanvasElement): SurfaceDisplaySize;

package/dist/lib/surface/root-surface.js

@@ -0,0 +1,171 @@
+import { update } from "../update.js";
+import { createLayerSurface, resolveSurface } from "./resolve-surface.js";
+import { validateSurfaceConfig } from "./resolve-surface.js";
+function createRootSurfaceState(canvas, config) {
+  const resolved = validateSurfaceConfig(canvas, config);
+  return {
+    kind: "root",
+    config: resolved,
+    display: readCanvasContentBox(canvas),
+    pixelRatio: readRequestedPixelRatio(resolved.pixelRatio),
+    snapshot: void 0,
+    ownedWidth: void 0,
+    ownedHeight: void 0
+  };
+}
+function createLegacyLayerSurfaceState(width, height) {
+  return {
+    kind: "layer",
+    managed: false,
+    snapshot: createLayerSurface(width, height, 1, 1)
+  };
+}
+function mountRootSurface(instance, canvas) {
+  const state = instance.surface;
+  if (state.kind !== "root") return;
+  if (typeof ResizeObserver !== "function") {
+    throw new Error("Pibbl requires ResizeObserver for Canvas surface sizing.");
+  }
+  const resizeObserver = new ResizeObserver(() => {
+    const display = readCanvasContentBox(canvas);
+    if (setDisplaySize(state, display)) {
+      update(canvas);
+    }
+  });
+  resizeObserver.observe(canvas);
+  instance.mainTeardowns.add(() => resizeObserver.disconnect());
+  instance.mainTeardowns.add(() => {
+    restoreOwnedSize(canvas, "width", state.ownedWidth);
+    restoreOwnedSize(canvas, "height", state.ownedHeight);
+  });
+  if (state.config.pixelRatio === "device") {
+    mountDensityObservers(instance, canvas, state);
+  }
+}
+function prepareSurface(instance) {
+  const state = instance.surface;
+  if (state.kind === "layer") {
+    if (!state.managed) {
+      state.snapshot = createLayerSurface(
+        instance.canvas.width,
+        instance.canvas.height,
+        1,
+        1
+      );
+    }
+    return state.snapshot;
+  }
+  const canvas = instance.canvas;
+  state.display = readCanvasContentBox(canvas);
+  if (state.config.pixelRatio === "device") {
+    state.pixelRatio = readRequestedPixelRatio("device");
+  }
+  let snapshot = resolveSurface(state.config, state.display, state.pixelRatio);
+  state.snapshot = snapshot;
+  if (!snapshot) return void 0;
+  const before = state.display;
+  const dimensionsChanged = canvas.width !== snapshot.backingWidth || canvas.height !== snapshot.backingHeight;
+  if (dimensionsChanged) {
+    canvas.width = snapshot.backingWidth;
+    canvas.height = snapshot.backingHeight;
+    const after = readCanvasContentBox(canvas);
+    if (!nearlyEqual(after.width, before.width)) {
+      state.ownedWidth = ownInlineSize(
+        canvas,
+        "width",
+        before.width,
+        state.ownedWidth
+      );
+    }
+    if (!nearlyEqual(after.height, before.height)) {
+      state.ownedHeight = ownInlineSize(
+        canvas,
+        "height",
+        before.height,
+        state.ownedHeight
+      );
+    }
+    const stabilized = readCanvasContentBox(canvas);
+    if (setDisplaySize(state, stabilized)) {
+      snapshot = resolveSurface(state.config, stabilized, state.pixelRatio);
+      state.snapshot = snapshot;
+      if (!snapshot) return void 0;
+      if (canvas.width !== snapshot.backingWidth || canvas.height !== snapshot.backingHeight) {
+        canvas.width = snapshot.backingWidth;
+        canvas.height = snapshot.backingHeight;
+      }
+    }
+  }
+  return snapshot;
+}
+function readCanvasContentBox(canvas) {
+  const rect = canvas.getBoundingClientRect();
+  const style = getComputedStyle(canvas);
+  return {
+    width: Math.max(0, rect.width - boxInsets(style, "width")),
+    height: Math.max(0, rect.height - boxInsets(style, "height"))
+  };
+}
+function mountDensityObservers(instance, canvas, state) {
+  let mediaQuery;
+  let closed = false;
+  const onDensityChange = () => {
+    if (closed) return;
+    const next = readRequestedPixelRatio("device");
+    bindMediaQuery(next);
+    if (next !== state.pixelRatio) {
+      state.pixelRatio = next;
+      update(canvas);
+    }
+  };
+  const bindMediaQuery = (ratio) => {
+    mediaQuery?.removeEventListener("change", onDensityChange);
+    mediaQuery = matchMedia(`(resolution: ${ratio}dppx)`);
+    mediaQuery.addEventListener("change", onDensityChange);
+  };
+  bindMediaQuery(state.pixelRatio);
+  window.addEventListener("resize", onDensityChange);
+  instance.mainTeardowns.add(() => {
+    closed = true;
+    mediaQuery?.removeEventListener("change", onDensityChange);
+    window.removeEventListener("resize", onDensityChange);
+  });
+}
+function readRequestedPixelRatio(requested) {
+  if (requested !== "device") return requested;
+  const ratio = window.devicePixelRatio;
+  return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+}
+function setDisplaySize(state, display) {
+  if (nearlyEqual(state.display.width, display.width) && nearlyEqual(state.display.height, display.height)) {
+    return false;
+  }
+  state.display = display;
+  return true;
+}
+function ownInlineSize(canvas, property, value, current) {
+  const owned = `${value}px`;
+  const previous = current?.previous ?? canvas.style[property];
+  canvas.style[property] = owned;
+  return { previous, owned };
+}
+function restoreOwnedSize(canvas, property, record) {
+  if (record && canvas.style[property] === record.owned) {
+    canvas.style[property] = record.previous;
+  }
+}
+function boxInsets(style, axis) {
+  const values = axis === "width" ? [style.borderLeftWidth, style.borderRightWidth, style.paddingLeft, style.paddingRight] : [style.borderTopWidth, style.borderBottomWidth, style.paddingTop, style.paddingBottom];
+  return values.reduce((total, value) => total + (Number.parseFloat(value) || 0), 0);
+}
+function nearlyEqual(left, right) {
+  return Math.abs(left - right) < 0.01;
+}
+export {
+  createLegacyLayerSurfaceState,
+  createRootSurfaceState,
+  mountRootSurface,
+  prepareSurface,
+  readCanvasContentBox
+};
+//# sourceMappingURL=root-surface.js.map

package/dist/lib/surface/root-surface.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/surface/root-surface.ts"],
+  "sourcesContent": ["import type { PibblInstance } from '../types.js';\nimport { update } from '../update.js';\nimport { createLayerSurface, resolveSurface } from './resolve-surface.js';\nimport type {\n  PibblConfig,\n  PibblSurfaceSnapshot,\n  LayerSurfaceState,\n  RootSurfaceState,\n  SurfaceDisplaySize,\n} from './types.js';\nimport { validateSurfaceConfig } from './resolve-surface.js';\n\nexport function createRootSurfaceState(\n  canvas: HTMLCanvasElement,\n  config?: PibblConfig,\n): RootSurfaceState {\n  const resolved = validateSurfaceConfig(canvas, config);\n  return {\n    kind: 'root',\n    config: resolved,\n    display: readCanvasContentBox(canvas),\n    pixelRatio: readRequestedPixelRatio(resolved.pixelRatio),\n    snapshot: undefined,\n    ownedWidth: undefined,\n    ownedHeight: undefined,\n  };\n}\n\nexport function createLegacyLayerSurfaceState(\n  width: number,\n  height: number,\n): LayerSurfaceState {\n  return {\n    kind: 'layer',\n    managed: false,\n    snapshot: createLayerSurface(width, height, 1, 1),\n  };\n}\n\nexport function mountRootSurface(\n  instance: PibblInstance,\n  canvas: HTMLCanvasElement,\n): void {\n  const state = instance.surface;\n  if (state.kind !== 'root') return;\n\n  if (typeof ResizeObserver !== 'function') {\n    throw new Error('Pibbl requires ResizeObserver for Canvas surface sizing.');\n  }\n\n  const resizeObserver = new ResizeObserver(() => {\n    const display = readCanvasContentBox(canvas);\n    if (setDisplaySize(state, display)) {\n      update(canvas);\n    }\n  });\n  resizeObserver.observe(canvas);\n  instance.mainTeardowns.add(() => resizeObserver.disconnect());\n\n  instance.mainTeardowns.add(() => {\n    restoreOwnedSize(canvas, 'width', state.ownedWidth);\n    restoreOwnedSize(canvas, 'height', state.ownedHeight);\n  });\n\n  if (state.config.pixelRatio === 'device') {\n    mountDensityObservers(instance, canvas, state);\n  }\n}\n\nexport function prepareSurface(\n  instance: PibblInstance,\n): PibblSurfaceSnapshot | undefined {\n  const state = instance.surface;\n  if (state.kind === 'layer') {\n    if (!state.managed) {\n      state.snapshot = createLayerSurface(\n        instance.canvas.width,\n        instance.canvas.height,\n        1,\n        1,\n      );\n    }\n    return state.snapshot;\n  }\n\n  const canvas = instance.canvas as HTMLCanvasElement;\n  state.display = readCanvasContentBox(canvas);\n  if (state.config.pixelRatio === 'device') {\n    state.pixelRatio = readRequestedPixelRatio('device');\n  }\n  let snapshot = resolveSurface(state.config, state.display, state.pixelRatio);\n  state.snapshot = snapshot;\n  if (!snapshot) return undefined;\n\n  const before = state.display;\n  const dimensionsChanged = canvas.width !== snapshot.backingWidth ||\n    canvas.height !== snapshot.backingHeight;\n  if (dimensionsChanged) {\n    canvas.width = snapshot.backingWidth;\n    canvas.height = snapshot.backingHeight;\n    const after = readCanvasContentBox(canvas);\n    if (!nearlyEqual(after.width, before.width)) {\n      state.ownedWidth = ownInlineSize(\n        canvas,\n        'width',\n        before.width,\n        state.ownedWidth,\n      );\n    }\n    if (!nearlyEqual(after.height, before.height)) {\n      state.ownedHeight = ownInlineSize(\n        canvas,\n        'height',\n        before.height,\n        state.ownedHeight,\n      );\n    }\n    const stabilized = readCanvasContentBox(canvas);\n    if (setDisplaySize(state, stabilized)) {\n      snapshot = resolveSurface(state.config, stabilized, state.pixelRatio);\n      state.snapshot = snapshot;\n      if (!snapshot) return undefined;\n      if (\n        canvas.width !== snapshot.backingWidth ||\n        canvas.height !== snapshot.backingHeight\n      ) {\n        canvas.width = snapshot.backingWidth;\n        canvas.height = snapshot.backingHeight;\n      }\n    }\n  }\n  return snapshot;\n}\n\nexport function readCanvasContentBox(\n  canvas: HTMLCanvasElement,\n): SurfaceDisplaySize {\n  const rect = canvas.getBoundingClientRect();\n  const style = getComputedStyle(canvas);\n  return {\n    width: Math.max(0, rect.width - boxInsets(style, 'width')),\n    height: Math.max(0, rect.height - boxInsets(style, 'height')),\n  };\n}\n\nfunction mountDensityObservers(\n  instance: PibblInstance,\n  canvas: HTMLCanvasElement,\n  state: RootSurfaceState,\n): void {\n  let mediaQuery: MediaQueryList | undefined;\n  let closed = false;\n  const onDensityChange = () => {\n    if (closed) return;\n    const next = readRequestedPixelRatio('device');\n    bindMediaQuery(next);\n    if (next !== state.pixelRatio) {\n      state.pixelRatio = next;\n      update(canvas);\n    }\n  };\n  const bindMediaQuery = (ratio: number) => {\n    mediaQuery?.removeEventListener('change', onDensityChange);\n    mediaQuery = matchMedia(`(resolution: ${ratio}dppx)`);\n    mediaQuery.addEventListener('change', onDensityChange);\n  };\n\n  bindMediaQuery(state.pixelRatio);\n  window.addEventListener('resize', onDensityChange);\n  instance.mainTeardowns.add(() => {\n    closed = true;\n    mediaQuery?.removeEventListener('change', onDensityChange);\n    window.removeEventListener('resize', onDensityChange);\n  });\n}\n\nfunction readRequestedPixelRatio(requested: 'device' | number): number {\n  if (requested !== 'device') return requested;\n  const ratio = window.devicePixelRatio;\n  return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;\n}\n\nfunction setDisplaySize(\n  state: RootSurfaceState,\n  display: SurfaceDisplaySize,\n): boolean {\n  if (\n    nearlyEqual(state.display.width, display.width) &&\n    nearlyEqual(state.display.height, display.height)\n  ) {\n    return false;\n  }\n  state.display = display;\n  return true;\n}\n\nfunction ownInlineSize(\n  canvas: HTMLCanvasElement,\n  property: 'width' | 'height',\n  value: number,\n  current: RootSurfaceState['ownedWidth'],\n) {\n  const owned = `${value}px`;\n  const previous = current?.previous ?? canvas.style[property];\n  canvas.style[property] = owned;\n  return { previous, owned };\n}\n\nfunction restoreOwnedSize(\n  canvas: HTMLCanvasElement,\n  property: 'width' | 'height',\n  record: RootSurfaceState['ownedWidth'],\n): void {\n  if (record && canvas.style[property] === record.owned) {\n    canvas.style[property] = record.previous;\n  }\n}\n\nfunction boxInsets(\n  style: CSSStyleDeclaration,\n  axis: 'width' | 'height',\n): number {\n  const values = axis === 'width' ?\n    [style.borderLeftWidth, style.borderRightWidth, style.paddingLeft, style.paddingRight] :\n    [style.borderTopWidth, style.borderBottomWidth, style.paddingTop, style.paddingBottom];\n  return values.reduce((total, value) => total + (Number.parseFloat(value) || 0), 0);\n}\n\nfunction nearlyEqual(left: number, right: number): boolean {\n  return Math.abs(left - right) < 0.01;\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/lib/surface/transform.d.ts

@@ -0,0 +1,4 @@
+import type { PibblInstance } from '../types.js';
+import type { PibblSurfaceSnapshot } from './types.js';
+export declare function toLogicalTransform(surface: PibblSurfaceSnapshot, current: DOMMatrix): DOMMatrix;
+export declare function getSurfaceSnapshot(instance: PibblInstance): PibblSurfaceSnapshot;

package/dist/lib/surface/transform.js

@@ -0,0 +1,16 @@
+import { rootRenderTarget } from "../render-target.js";
+function toLogicalTransform(surface, current) {
+  return rootRenderTarget(surface).inverseRenderTransform.multiply(current);
+}
+function getSurfaceSnapshot(instance) {
+  const snapshot = instance.surface.snapshot;
+  if (!snapshot) {
+    throw new Error("No visible Pibbl surface is available.");
+  }
+  return snapshot;
+}
+export {
+  getSurfaceSnapshot,
+  toLogicalTransform
+};
+//# sourceMappingURL=transform.js.map

package/dist/lib/surface/transform.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/lib/surface/transform.ts"],
+  "sourcesContent": ["import type { PibblInstance } from '../types.js';\nimport { rootRenderTarget } from '../render-target.js';\nimport type { PibblSurfaceSnapshot } from './types.js';\n\nexport function toLogicalTransform(\n  surface: PibblSurfaceSnapshot,\n  current: DOMMatrix,\n): DOMMatrix {\n  return rootRenderTarget(surface).inverseRenderTransform.multiply(current);\n}\n\nexport function getSurfaceSnapshot(\n  instance: PibblInstance,\n): PibblSurfaceSnapshot {\n  const snapshot = instance.surface.snapshot;\n  if (!snapshot) {\n    throw new Error('No visible Pibbl surface is available.');\n  }\n  return snapshot;\n}\n"],
+  "mappings": "AACA,SAAS,wBAAwB;AAG1B,SAAS,mBACd,SACA,SACW;AACX,SAAO,iBAAiB,OAAO,EAAE,uBAAuB,SAAS,OAAO;AAC1E;AAEO,SAAS,mBACd,UACsB;AACtB,QAAM,WAAW,SAAS,QAAQ;AAClC,MAAI,CAAC,UAAU;AACb,UAAM,IAAI,MAAM,wCAAwC;AAAA,EAC1D;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/lib/surface/types.d.ts

@@ -0,0 +1,132 @@
+import type { pibbl } from "../pibbl.js";
+/**
+ * How a fixed logical viewport fits inside its displayed canvas surface.
+ *
+ * @see {@link PibblFixedViewportConfig}
+ */
+export type PibblFit = 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+/**
+ * Requested backing-store density, either explicit or derived from the device.
+ *
+ * @see {@link PibblFixedViewportConfig}
+ * @see {@link PibblResponsiveViewportConfig}
+ */
+export type PibblPixelRatio = 'device' | number;
+/**
+ * Fixed logical viewport dimensions and fitting policy for a canvas mount.
+ *
+ * @see {@link PibblFit}
+ * @see {@link PibblPixelRatio}
+ * @see {@link PibblConfig}
+ */
+export interface PibblFixedViewportConfig {
+    /**
+     * Opt-in host for application-owned HTML regions associated with this canvas. See
+     * {@link PibblFixedViewportConfig}.
+     */
+    htmlOverlay?: HTMLElement;
+    /**
+     * Abort signal governing the lifetime of this operation or mount. See
+     * {@link PibblFixedViewportConfig}.
+     */
+    signal?: AbortSignal;
+    /** Logical viewport dimensions and fitting configuration. See {@link PibblFixedViewportConfig}. */
+    viewport?: Readonly<{
+        /**
+         * Horizontal extent in the units of the containing geometry or surface. See
+         * {@link PibblFixedViewportConfig}.
+         */
+        width: number;
+        /**
+         * Vertical extent in the units of the containing geometry or surface. See
+         * {@link PibblFixedViewportConfig}.
+         */
+        height: number;
+    }>;
+    /** Policy for fitting content within its available box. See {@link PibblFit}. */
+    fit?: PibblFit;
+    /** Requested backing-store pixel density. See {@link PibblPixelRatio}. */
+    pixelRatio?: PibblPixelRatio;
+}
+/**
+ * A viewport that follows the displayed canvas dimensions.
+ *
+ * @see {@link PibblPixelRatio}
+ * @see {@link PibblConfig}
+ */
+export interface PibblResponsiveViewportConfig {
+    /**
+     * Opt-in host for application-owned HTML regions associated with this canvas. See
+     * {@link PibblResponsiveViewportConfig}.
+     */
+    htmlOverlay?: HTMLElement;
+    /**
+     * Abort signal governing the lifetime of this operation or mount. See
+     * {@link PibblResponsiveViewportConfig}.
+     */
+    signal?: AbortSignal;
+    /**
+     * Logical viewport dimensions and fitting configuration. See {@link PibblResponsiveViewportConfig}
+     * .
+     */
+    viewport: 'responsive';
+    /** Requested backing-store pixel density. See {@link PibblPixelRatio}. */
+    pixelRatio?: PibblPixelRatio;
+}
+/**
+ * Canvas surface sizing, pixel density, and viewport configuration for a Pibbl mount.
+ *
+ * @see {@link PibblFixedViewportConfig}
+ * @see {@link PibblResponsiveViewportConfig}
+ * @see {@link pibbl}
+ */
+export type PibblConfig = PibblFixedViewportConfig | PibblResponsiveViewportConfig;
+export type ResolvedSurfaceConfig = {
+    mode: 'fixed';
+    width: number;
+    height: number;
+    fit: PibblFit;
+    pixelRatio: PibblPixelRatio;
+} | {
+    mode: 'responsive';
+    pixelRatio: PibblPixelRatio;
+};
+export interface SurfaceDisplaySize {
+    width: number;
+    height: number;
+}
+export interface PibblSurfaceSnapshot {
+    mode: 'fixed' | 'responsive' | 'layer';
+    fit: PibblFit;
+    logicalWidth: number;
+    logicalHeight: number;
+    displayWidth: number;
+    displayHeight: number;
+    backingWidth: number;
+    backingHeight: number;
+    backingPixelsPerCssPixelX: number;
+    backingPixelsPerCssPixelY: number;
+    backingPixelsPerLogicalUnitX: number;
+    backingPixelsPerLogicalUnitY: number;
+    renderTransform: DOMMatrix;
+    inverseRenderTransform: DOMMatrix;
+}
+export interface RootSurfaceState {
+    kind: 'root';
+    config: ResolvedSurfaceConfig;
+    display: SurfaceDisplaySize;
+    pixelRatio: number;
+    snapshot: PibblSurfaceSnapshot | undefined;
+    ownedWidth: OwnedInlineSize | undefined;
+    ownedHeight: OwnedInlineSize | undefined;
+}
+export interface LayerSurfaceState {
+    kind: 'layer';
+    managed: boolean;
+    snapshot: PibblSurfaceSnapshot;
+}
+export type PibblSurfaceState = RootSurfaceState | LayerSurfaceState;
+export interface OwnedInlineSize {
+    previous: string;
+    owned: string;
+}

package/dist/lib/teardowns.d.ts

@@ -0,0 +1,14 @@
+/**
+ * AbortSignal is SLOW AS A DEAD TURTLE to deal with because of
+ * addEventListener and removeEventListener. Strong avoid.
+ */
+export declare class Teardowns {
+    private readonly _teardowns;
+    private _closed;
+    get closed(): boolean;
+    follow(parentTeardown: Teardowns): void;
+    add(teardown: () => void): void;
+    remove(teardown: () => void): void;
+    execute(): void;
+}
+export declare function runTeardown(teardown: () => void): void;

package/dist/lib/teardowns.js

@@ -0,0 +1,50 @@
+class Teardowns {
+  _teardowns = /* @__PURE__ */ new Set();
+  _closed = false;
+  get closed() {
+    return this._closed;
+  }
+  follow(parentTeardown) {
+    const handler = () => {
+      this.execute();
+    };
+    parentTeardown.add(handler);
+    this.add(() => parentTeardown.remove(handler));
+  }
+  add(teardown) {
+    if (this._closed) {
+      runTeardown(teardown);
+    } else {
+      this._teardowns.add(teardown);
+    }
+  }
+  remove(teardown) {
+    this._teardowns.delete(teardown);
+  }
+  execute() {
+    if (this._closed) {
+      return;
+    }
+    this._closed = true;
+    const teardowns = Array.from(this._teardowns);
+    this._teardowns.clear();
+    for (const teardown of teardowns) {
+      runTeardown(teardown);
+    }
+  }
+}
+function runTeardown(teardown) {
+  try {
+    teardown();
+  } catch (error) {
+    try {
+      reportError(error);
+    } catch {
+    }
+  }
+}
+export {
+  Teardowns,
+  runTeardown
+};
+//# sourceMappingURL=teardowns.js.map

package/dist/lib/teardowns.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/lib/teardowns.ts"],
+  "sourcesContent": ["/**\n * AbortSignal is SLOW AS A DEAD TURTLE to deal with because of\n * addEventListener and removeEventListener. Strong avoid.\n */\nexport class Teardowns {\n  private readonly _teardowns = new Set<() => void>();\n  private _closed = false;\n\n  get closed(): boolean {\n    return this._closed;\n  }\n\n  follow(parentTeardown: Teardowns): void {\n    const handler = () => {\n      this.execute();\n    };\n    parentTeardown.add(handler);\n    this.add(() => parentTeardown.remove(handler));\n  }\n\n  add(teardown: () => void): void {\n    if (this._closed) {\n      runTeardown(teardown);\n    } else {\n      this._teardowns.add(teardown);\n    }\n  }\n\n  remove(teardown: () => void): void {\n    this._teardowns.delete(teardown);\n  }\n\n  execute(): void {\n    if (this._closed) {\n      return;\n    }\n\n    this._closed = true;\n    const teardowns = Array.from(this._teardowns);\n    this._teardowns.clear();\n    for (const teardown of teardowns) {\n      runTeardown(teardown);\n    }\n  }\n}\n\nexport function runTeardown(teardown: () => void): void {\n  try {\n    teardown();\n  } catch (error) {\n    try {\n      reportError(error);\n    } catch {\n      // Error reporting must not prevent the remaining resources from releasing.\n    }\n  }\n}\n"],
+  "mappings": "AAIO,MAAM,UAAU;AAAA,EACJ,aAAa,oBAAI,IAAgB;AAAA,EAC1C,UAAU;AAAA,EAElB,IAAI,SAAkB;AACpB,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,OAAO,gBAAiC;AACtC,UAAM,UAAU,MAAM;AACpB,WAAK,QAAQ;AAAA,IACf;AACA,mBAAe,IAAI,OAAO;AAC1B,SAAK,IAAI,MAAM,eAAe,OAAO,OAAO,CAAC;AAAA,EAC/C;AAAA,EAEA,IAAI,UAA4B;AAC9B,QAAI,KAAK,SAAS;AAChB,kBAAY,QAAQ;AAAA,IACtB,OAAO;AACL,WAAK,WAAW,IAAI,QAAQ;AAAA,IAC9B;AAAA,EACF;AAAA,EAEA,OAAO,UAA4B;AACjC,SAAK,WAAW,OAAO,QAAQ;AAAA,EACjC;AAAA,EAEA,UAAgB;AACd,QAAI,KAAK,SAAS;AAChB;AAAA,IACF;AAEA,SAAK,UAAU;AACf,UAAM,YAAY,MAAM,KAAK,KAAK,UAAU;AAC5C,SAAK,WAAW,MAAM;AACtB,eAAW,YAAY,WAAW;AAChC,kBAAY,QAAQ;AAAA,IACtB;AAAA,EACF;AACF;AAEO,SAAS,YAAY,UAA4B;AACtD,MAAI;AACF,aAAS;AAAA,EACX,SAAS,OAAO;AACd,QAAI;AACF,kBAAY,KAAK;AAAA,IACnB,QAAQ;AAAA,IAER;AAAA,EACF;AACF;",
+  "names": []
+}