@tableslayer/ui 0.0.1

package/dist/components/Stage/components/MeasurementLayer/utils/distanceCalculations.js

@@ -0,0 +1,130 @@
+import * as THREE from 'three';
+import { hexDistance, pixelToHex } from '../../../helpers/grid';
+import { GridType } from '../../GridLayer/types';
+/**
+ * Calculate hex grid distance between two points
+ * @param startPoint Start point in pixel coordinates
+ * @param endPoint End point in pixel coordinates
+ * @param gridSpacing Grid spacing in inches
+ * @param displaySize Display size in inches
+ * @param displayResolution Display resolution in pixels
+ * @param worldGridSize The real-world size of one hex
+ * @param returnHexCount If true, returns hex count instead of world units
+ * @returns Distance in world grid units or hex count
+ */
+export function calculateHexGridDistance(startPoint, endPoint, gridSpacing, displaySize, displayResolution, worldGridSize = 5, returnHexCount = false) {
+    // Convert pixel coordinates to world coordinates (inches)
+    const pixelsPerInchX = displayResolution.x / displaySize.x;
+    // Calculate hex size in pixels
+    // The grid spacing represents the distance between hex centers
+    // For pointy-top hexagons, this is the width of the hex
+    const hexSizePixels = gridSpacing * pixelsPerInchX;
+    // Convert points to hex coordinates
+    const startHex = pixelToHex(startPoint, hexSizePixels);
+    const endHex = pixelToHex(endPoint, hexSizePixels);
+    // Calculate distance in hex units
+    const hexes = hexDistance(startHex, endHex);
+    // Return either hex count or world units
+    return returnHexCount ? hexes : hexes * worldGridSize;
+}
+/**
+ * Calculate grid-based distance between two points
+ * @param startPoint Start point in pixel coordinates
+ * @param endPoint End point in pixel coordinates
+ * @param gridSpacing Grid spacing in inches
+ * @param displaySize Display size in inches
+ * @param displayResolution Display resolution in pixels
+ * @param gridType Type of grid (square or hex)
+ * @param snapToGrid Whether snapping is enabled
+ * @param enableDMG252 Whether to use DMG 252 diagonal rules
+ * @param worldGridSize The real-world size of one grid square
+ * @param worldGridUnits The units for the world grid size
+ * @returns Distance in world grid units
+ */
+export function calculateLineDistance(startPoint, endPoint, gridSpacing, displaySize, displayResolution, gridType = GridType.Square, snapToGrid = false, enableDMG252 = false, worldGridSize = 5, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+_worldGridUnits = 'FT') {
+    // For hex grids with snapping enabled, use hex pathfinding
+    if (gridType === GridType.Hex && snapToGrid) {
+        return calculateHexGridDistance(startPoint, endPoint, gridSpacing, displaySize, displayResolution, worldGridSize);
+    }
+    // Convert pixel coordinates to world coordinates (inches)
+    const pixelsPerInchX = displayResolution.x / displaySize.x;
+    const pixelsPerInchY = displayResolution.y / displaySize.y;
+    // Convert to inches
+    const startInches = new THREE.Vector2(startPoint.x / pixelsPerInchX, startPoint.y / pixelsPerInchY);
+    const endInches = new THREE.Vector2(endPoint.x / pixelsPerInchX, endPoint.y / pixelsPerInchY);
+    // If DMG 252 rules are enabled and we're snapping to a square grid
+    if (enableDMG252 && snapToGrid && gridType === GridType.Square) {
+        // Convert to grid coordinates (number of grid squares)
+        const startGrid = new THREE.Vector2(startInches.x / gridSpacing, startInches.y / gridSpacing);
+        const endGrid = new THREE.Vector2(endInches.x / gridSpacing, endInches.y / gridSpacing);
+        // Calculate grid distance using DMG 252 rules, then convert to world units
+        const gridDistance = calculateDMG252Distance(startGrid, endGrid);
+        return gridDistance * worldGridSize;
+    }
+    // Standard distance calculation - convert to world grid units
+    const distanceInches = startInches.distanceTo(endInches);
+    const gridDistance = distanceInches / gridSpacing;
+    return gridDistance * worldGridSize;
+}
+/**
+ * Calculate D&D diagonal movement distance
+ * In D&D, diagonal movement costs 1.5 times normal movement
+ * This is implemented as: max(dx, dy) + min(dx, dy) * 0.5
+ */
+export function calculateDnDDiagonalDistance(startPoint, endPoint) {
+    const dx = Math.abs(endPoint.x - startPoint.x);
+    const dy = Math.abs(endPoint.y - startPoint.y);
+    return Math.max(dx, dy) + Math.min(dx, dy) * 0.5;
+}
+/**
+ * Calculate distance using DMG 252 diagonal movement rules
+ * First diagonal = 1 grid unit, second = 2 grid units, alternating
+ * Only applies when snapping to square grid
+ */
+export function calculateDMG252Distance(startPoint, endPoint) {
+    const dx = Math.abs(endPoint.x - startPoint.x);
+    const dy = Math.abs(endPoint.y - startPoint.y);
+    // Get the number of diagonal and straight moves
+    const diagonalMoves = Math.min(dx, dy);
+    const straightMoves = Math.max(dx, dy) - diagonalMoves;
+    // Calculate diagonal cost using DMG 252 rules
+    // Every other diagonal costs 2 units instead of 1
+    const fullDiagonalPairs = Math.floor(diagonalMoves / 2);
+    const remainingDiagonals = diagonalMoves % 2;
+    const diagonalCost = fullDiagonalPairs * 3 + remainingDiagonals * 1; // 3 = 1 + 2 for each pair
+    const straightCost = straightMoves;
+    return diagonalCost + straightCost;
+}
+/**
+ * Calculate radius from center point to edge point
+ */
+export function calculateRadius(centerPoint, edgePoint) {
+    return centerPoint.distanceTo(edgePoint);
+}
+/**
+ * Calculate area of a circle
+ */
+export function calculateCircleArea(radius) {
+    return Math.PI * radius * radius;
+}
+/**
+ * Calculate area of a square
+ */
+export function calculateSquareArea(sideLength) {
+    return sideLength * sideLength;
+}
+/**
+ * Convert pixels to game units (assuming 1 inch = 1 unit)
+ * This is a placeholder - actual conversion depends on grid scale
+ */
+export function pixelsToUnits(pixels, pixelsPerUnit = 1) {
+    return pixels / pixelsPerUnit;
+}
+/**
+ * Convert game units to pixels
+ */
+export function unitsToPixels(units, pixelsPerUnit = 1) {
+    return units * pixelsPerUnit;
+}

package/dist/components/Stage/components/ParticleSystem/ParticleSystem.svelte

@@ -0,0 +1,220 @@
+<script lang="ts">
+  import * as THREE from 'three';
+  import { T, useTask, useLoader } from '@threlte/core';
+  import { ParticleData } from './types';
+  import type { ParticleSystemProps } from './types';
+  import { RNG } from './rng';
+
+  import fragmentShader from '../../shaders/Particles.frag?raw';
+  import vertexShader from '../../shaders/Particles.vert?raw';
+  import { DEG2RAD } from 'three/src/math/MathUtils';
+  import { onDestroy, untrack } from 'svelte';
+
+  interface Props {
+    props: ParticleSystemProps;
+    opacity?: number;
+    intensity?: number;
+  }
+
+  const { props, opacity, intensity }: Props = $props();
+
+  let mesh: THREE.Mesh | undefined = $state(undefined);
+  let geometry: THREE.BufferGeometry | undefined = $state(undefined);
+
+  $effect.pre(() => {
+    const rng = new RNG(0);
+    const count = Math.round(props.maxParticleCount * (intensity ?? 1));
+
+    // Initialize particle attributes - 4 vertices per quad
+    const positions = new Float32Array(count * 12); // 4 vertices * 3 coords
+    const centers = new Float32Array(count * 8); // 1 center * 2 coords
+    const uvs = new Float32Array(count * 8); // 4 vertices * 2 coords
+    const indices = new Uint32Array(count * 6); // 2 triangles * 3 vertices
+    const ageOffsets = new Float32Array(count * 4); // 4 vertices
+
+    const particle = ParticleData[props.type];
+
+    // Initialize particles
+    for (let i = 0; i < count; i++) {
+      const radius = rng.random() * (props.spawnArea.maxRadius - props.spawnArea.minRadius) + props.spawnArea.minRadius;
+      const angle = rng.random() * 2 * Math.PI;
+      const x = radius * Math.cos(angle);
+      const y = radius * Math.sin(angle);
+      const z = -1.001;
+
+      // Quad vertex positions (same for all 4 corners initially)
+      const baseIdx = i * 12;
+
+      // Generate random size for this particle
+      let size = rng.random() * (props.size.max - props.size.min) + props.size.min;
+      let width = size * props.scale.x;
+      let height = size * props.scale.y;
+
+      const rotation = new THREE.Euler(0, 0, props.rotation.offset * DEG2RAD);
+      rotation.z += props.rotation.alignRadially ? angle : 0;
+      rotation.z += props.rotation.randomize ? rng.random() * 360 : 0;
+
+      const v1 = new THREE.Vector3(-width / 2, -height / 2, 0);
+      const v2 = new THREE.Vector3(width / 2, -height / 2, 0);
+      const v3 = new THREE.Vector3(-width / 2, height / 2, 0);
+      const v4 = new THREE.Vector3(width / 2, height / 2, 0);
+
+      v1.applyEuler(rotation);
+      v2.applyEuler(rotation);
+      v3.applyEuler(rotation);
+      v4.applyEuler(rotation);
+
+      v1.add(new THREE.Vector3(x, y, z));
+      v2.add(new THREE.Vector3(x, y, z));
+      v3.add(new THREE.Vector3(x, y, z));
+      v4.add(new THREE.Vector3(x, y, z));
+
+      // Set quad corners with size offset
+      positions[baseIdx] = v1.x; // Bottom left x
+      positions[baseIdx + 1] = v1.y; // Bottom left y
+      positions[baseIdx + 2] = v1.z; // Bottom left z
+
+      positions[baseIdx + 3] = v2.x; // Bottom right x
+      positions[baseIdx + 4] = v2.y; // Bottom right y
+      positions[baseIdx + 5] = v2.z; // Bottom right z
+
+      positions[baseIdx + 6] = v3.x; // Top left x
+      positions[baseIdx + 7] = v3.y; // Top left y
+      positions[baseIdx + 8] = v3.z; // Top left z
+
+      positions[baseIdx + 9] = v4.x; // Top right x
+      positions[baseIdx + 10] = v4.y; // Top right y
+      positions[baseIdx + 11] = v4.z; // Top right z
+
+      // Set center position
+      const centerIdx = i * 8;
+      centers[centerIdx] = x;
+      centers[centerIdx + 1] = y;
+      centers[centerIdx + 2] = x;
+      centers[centerIdx + 3] = y;
+      centers[centerIdx + 4] = x;
+      centers[centerIdx + 5] = y;
+      centers[centerIdx + 6] = x;
+      centers[centerIdx + 7] = y;
+
+      // Calculate random frame from texture atlas
+      const frame = Math.floor(rng.random() * (particle.columns * particle.rows));
+      const col = frame % particle.columns;
+      const row = Math.floor(frame / particle.columns);
+
+      // Calculate UV coordinates for this frame
+      const uv0 = new THREE.Vector2(col / particle.columns, row / particle.rows);
+      const uv1 = new THREE.Vector2((col + 1) / particle.columns, (row + 1) / particle.rows);
+
+      // UV coordinates for quad
+      const uvBaseIdx = i * 8;
+      uvs[uvBaseIdx] = uv0.x; // bottom left
+      uvs[uvBaseIdx + 1] = uv0.y;
+      uvs[uvBaseIdx + 2] = uv1.x; // bottom right
+      uvs[uvBaseIdx + 3] = uv0.y;
+      uvs[uvBaseIdx + 4] = uv0.x; // top left
+      uvs[uvBaseIdx + 5] = uv1.y;
+      uvs[uvBaseIdx + 6] = uv1.x; // top right
+      uvs[uvBaseIdx + 7] = uv1.y;
+
+      // Indices for two triangles
+      const indexBaseIdx = i * 6;
+      const vertexBaseIdx = i * 4;
+      indices[indexBaseIdx] = vertexBaseIdx;
+      indices[indexBaseIdx + 1] = vertexBaseIdx + 1;
+      indices[indexBaseIdx + 2] = vertexBaseIdx + 2;
+      indices[indexBaseIdx + 3] = vertexBaseIdx + 1;
+      indices[indexBaseIdx + 4] = vertexBaseIdx + 3;
+      indices[indexBaseIdx + 5] = vertexBaseIdx + 2;
+
+      // Random attributes (same for all vertices of quad)
+      const ageOffset = rng.random() * props.lifetime;
+
+      for (let v = 0; v < 4; v++) {
+        ageOffsets[i * 4 + v] = ageOffset;
+      }
+    }
+
+    untrack(() => {
+      geometry = new THREE.BufferGeometry();
+      geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+      geometry.setAttribute('center', new THREE.BufferAttribute(centers, 2));
+      geometry.setAttribute('uv', new THREE.BufferAttribute(uvs, 2));
+      geometry.setAttribute('ageOffset', new THREE.BufferAttribute(ageOffsets, 1));
+      geometry.setIndex(new THREE.BufferAttribute(indices, 1));
+    });
+
+    return () => {
+      geometry?.dispose();
+    };
+  });
+
+  const material = new THREE.ShaderMaterial();
+  const loader = useLoader(THREE.TextureLoader);
+
+  // Track current texture for disposal
+  let currentTexture: THREE.Texture | null = $state(null);
+
+  // Add cleanup on component destruction
+  onDestroy(() => {
+    geometry?.dispose();
+    if (currentTexture) {
+      currentTexture.dispose();
+      currentTexture = null;
+    }
+  });
+
+  // Create a derived value for uniforms that updates when props change
+  const uniforms = $derived({
+    uTime: { value: 0 },
+    uTexture: { value: currentTexture },
+    uOpacity: { value: opacity },
+    uColor: { value: new THREE.Color(props.color) },
+
+    uLifetime: { value: props.lifetime },
+    uAngularVelocity: { value: props.rotation.velocity },
+    uInitialVelocity: { value: props.initialVelocity },
+    uLinearForceAmplitude: { value: props.force.linear },
+    uExponentialForceAmplitude: { value: props.force.exponential },
+    uSinusoidalForceAmplitude: { value: props.force.sinusoidal.amplitude },
+    uSinusoidalForceFrequency: { value: props.force.sinusoidal.frequency },
+    uFadeInTime: { value: props.fadeInTime },
+    uFadeOutTime: { value: props.fadeOutTime },
+    uScale: { value: props.scale }
+  });
+
+  $effect(() => {
+    loader.load(ParticleData[props.type].url).then((newTexture) => {
+      untrack(() => {
+        currentTexture?.dispose();
+        currentTexture = newTexture;
+
+        if (material.uniforms.uTexture) {
+          material.uniforms.uTexture.value = newTexture;
+        }
+      });
+    });
+  });
+
+  // Update material uniforms whenever they change
+  $effect(() => {
+    Object.assign(material.uniforms, uniforms);
+  });
+
+  useTask((dt) => {
+    material.uniforms.uTime.value += dt;
+  });
+</script>
+
+<T.Mesh bind:ref={mesh} {geometry}>
+  <T.ShaderMaterial
+    is={material}
+    {vertexShader}
+    {fragmentShader}
+    transparent={true}
+    depthWrite={false}
+    depthTest={false}
+    blending={THREE.NormalBlending}
+    side={THREE.DoubleSide}
+  />
+</T.Mesh>

package/dist/components/Stage/components/ParticleSystem/ParticleSystem.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { ParticleSystemProps } from './types';
+interface Props {
+    props: ParticleSystemProps;
+    opacity?: number;
+    intensity?: number;
+}
+declare const ParticleSystem: import("svelte").Component<Props, {}, "">;
+type ParticleSystem = ReturnType<typeof ParticleSystem>;
+export default ParticleSystem;

package/dist/components/Stage/components/ParticleSystem/rng.d.ts

@@ -0,0 +1,7 @@
+export class RNG {
+    constructor(seed: any);
+    m_w: number;
+    m_z: number;
+    mask: number;
+    random(): number;
+}

package/dist/components/Stage/components/ParticleSystem/rng.js

@@ -0,0 +1,20 @@
+export class RNG {
+  m_w = 123456789;
+  m_z = 987654321;
+  mask = 0xffffffff;
+
+  constructor(seed) {
+    this.m_w = (123456789 + seed) & this.mask;
+    this.m_z = (987654321 - seed) & this.mask;
+  }
+
+  // Returns number between 0 (inclusive) and 1.0 (exclusive),
+  // just like Math.random().
+  random() {
+    this.m_z = (36969 * (this.m_z & 65535) + (this.m_z >> 16)) & this.mask;
+    this.m_w = (18000 * (this.m_w & 65535) + (this.m_w >> 16)) & this.mask;
+    let result = ((this.m_z << 16) + (this.m_w & 65535)) >>> 0;
+    result /= 4294967296;
+    return result;
+  }
+}

package/dist/components/Stage/components/ParticleSystem/types.d.ts

@@ -0,0 +1,88 @@
+export declare enum ParticleType {
+    Snow = 1,
+    Rain = 2,
+    Leaves = 3,
+    Ash = 4
+}
+export declare const ParticleData: {
+    readonly 1: {
+        readonly url: string;
+        readonly size: 768;
+        readonly columns: 3;
+        readonly rows: 3;
+    };
+    readonly 2: {
+        readonly url: string;
+        readonly size: 768;
+        readonly columns: 3;
+        readonly rows: 3;
+    };
+    readonly 3: {
+        readonly url: string;
+        readonly size: 768;
+        readonly columns: 3;
+        readonly rows: 3;
+    };
+    readonly 4: {
+        readonly url: string;
+        readonly size: 768;
+        readonly columns: 3;
+        readonly rows: 3;
+    };
+};
+export interface ParticleSystemProps {
+    maxParticleCount: number;
+    type: ParticleType;
+    lifetime: number;
+    color: string;
+    opacity: number;
+    fadeInTime: number;
+    fadeOutTime: number;
+    initialVelocity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    force: {
+        linear: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        exponential: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        sinusoidal: {
+            amplitude: {
+                x: number;
+                y: number;
+                z: number;
+            };
+            frequency: {
+                x: number;
+                y: number;
+                z: number;
+            };
+        };
+    };
+    rotation: {
+        alignRadially: boolean;
+        offset: number;
+        velocity: number;
+        randomize: boolean;
+    };
+    scale: {
+        x: number;
+        y: number;
+    };
+    size: {
+        min: number;
+        max: number;
+    };
+    spawnArea: {
+        minRadius: number;
+        maxRadius: number;
+    };
+}

package/dist/components/Stage/components/ParticleSystem/types.js

@@ -0,0 +1,37 @@
+import ash from './particles/atlases/ash.png';
+import leaves from './particles/atlases/leaves.png';
+import rain from './particles/atlases/rain.png';
+import snow from './particles/atlases/snow.png';
+export var ParticleType;
+(function (ParticleType) {
+    ParticleType[ParticleType["Snow"] = 1] = "Snow";
+    ParticleType[ParticleType["Rain"] = 2] = "Rain";
+    ParticleType[ParticleType["Leaves"] = 3] = "Leaves";
+    ParticleType[ParticleType["Ash"] = 4] = "Ash";
+})(ParticleType || (ParticleType = {}));
+export const ParticleData = {
+    [ParticleType.Snow]: {
+        url: snow,
+        size: 768,
+        columns: 3,
+        rows: 3
+    },
+    [ParticleType.Rain]: {
+        url: rain,
+        size: 768,
+        columns: 3,
+        rows: 3
+    },
+    [ParticleType.Leaves]: {
+        url: leaves,
+        size: 768,
+        columns: 3,
+        rows: 3
+    },
+    [ParticleType.Ash]: {
+        url: ash,
+        size: 768,
+        columns: 3,
+        rows: 3
+    }
+};

package/dist/components/Stage/components/PerformanceDebugger/PerformanceDebugger.svelte

@@ -0,0 +1,144 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import PerformanceOverlay from '../PerformanceOverlay/PerformanceOverlay.svelte';
+  import { resetMetrics } from '../../helpers/performanceMetrics.svelte';
+  import { debugState, setDebugEnabled } from '../../helpers/debugState.svelte';
+
+  interface Props {
+    /** Key combination to toggle (default: F9) */
+    shortcut?: string;
+    /** Callback when debug state changes (optional, for external notification) */
+    onToggle?: (enabled: boolean) => void;
+    /** Disabled layers for A/B testing */
+    disabledLayers?: string[];
+  }
+
+  const { shortcut = 'F9', onToggle, disabledLayers = [] }: Props = $props();
+
+  let showHelp = $state(false);
+
+  // Use the global debug state
+  const enabled = $derived(debugState.enableMetrics);
+
+  const parseShortcut = (shortcut: string) => {
+    const parts = shortcut.split('+').map((p) => p.trim());
+    const modifiers = ['shift', 'ctrl', 'control', 'alt', 'meta', 'cmd'];
+    const keyPart = parts.find((p) => !modifiers.includes(p.toLowerCase())) || '';
+
+    return {
+      shift: parts.some((p) => p.toLowerCase() === 'shift'),
+      ctrl: parts.some((p) => p.toLowerCase() === 'ctrl' || p.toLowerCase() === 'control'),
+      alt: parts.some((p) => p.toLowerCase() === 'alt'),
+      meta: parts.some((p) => p.toLowerCase() === 'meta' || p.toLowerCase() === 'cmd'),
+      // Preserve case for function keys (F9, F10, etc.)
+      key: keyPart.match(/^[fF]\d+$/) ? keyPart.toUpperCase() : keyPart.toLowerCase()
+    };
+  };
+
+  const shortcutConfig = parseShortcut(shortcut);
+
+  const formatShortcut = () => {
+    const parts = [];
+    if (shortcutConfig.shift) parts.push('Shift');
+    if (shortcutConfig.ctrl) parts.push('Ctrl');
+    if (shortcutConfig.alt) parts.push('Alt');
+    if (shortcutConfig.meta) parts.push('Cmd');
+    // Function keys display as-is (F9), others uppercase
+    parts.push(shortcutConfig.key.match(/^F\d+$/) ? shortcutConfig.key : shortcutConfig.key.toUpperCase());
+    return parts.join(' + ');
+  };
+
+  const isFormElement = (element: Element | null): boolean => {
+    if (!element) return false;
+    const tagName = element.tagName;
+    return (
+      tagName === 'INPUT' ||
+      tagName === 'TEXTAREA' ||
+      tagName === 'SELECT' ||
+      (element as HTMLElement).isContentEditable
+    );
+  };
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    // Don't trigger while typing in form elements
+    if (isFormElement(document.activeElement)) return;
+
+    // Function keys (F1-F12) are case-sensitive in e.key, others we compare lowercase
+    const isFunctionKey = shortcutConfig.key.match(/^F\d+$/);
+    const keyMatches = isFunctionKey ? e.key === shortcutConfig.key : e.key.toLowerCase() === shortcutConfig.key;
+
+    const matchesShortcut =
+      e.shiftKey === shortcutConfig.shift &&
+      e.ctrlKey === shortcutConfig.ctrl &&
+      e.altKey === shortcutConfig.alt &&
+      e.metaKey === shortcutConfig.meta &&
+      keyMatches;
+
+    if (matchesShortcut) {
+      e.preventDefault();
+      const newEnabled = !debugState.enableMetrics;
+      setDebugEnabled(newEnabled);
+      onToggle?.(newEnabled);
+
+      if (newEnabled) {
+        resetMetrics();
+        showHelp = true;
+        setTimeout(() => (showHelp = false), 2000);
+      }
+    }
+  };
+
+  onMount(() => {
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  });
+
+  /** Get debug props to spread into Stage props */
+  export const getDebugProps = () => ({
+    enableStats: debugState.enableMetrics,
+    loggingRate: 1000,
+    enableMetrics: debugState.enableMetrics,
+    logMetricsToConsole: debugState.logMetricsToConsole,
+    disabledLayers
+  });
+</script>
+
+{#if enabled}
+  <PerformanceOverlay visible={true} {disabledLayers} />
+{/if}
+
+{#if showHelp}
+  <div class="performanceDebugger__help">
+    Performance metrics enabled. Press {formatShortcut()} to disable.
+  </div>
+{/if}
+
+<style>
+  .performanceDebugger__help {
+    position: absolute;
+    bottom: 1rem;
+    left: 50%;
+    transform: translateX(-50%);
+    background: var(--fg);
+    color: var(--bg);
+    font-family: var(--font-sans);
+    font-size: 0.75rem;
+    padding: 0.5rem 1rem;
+    border-radius: var(--radius-2);
+    box-shadow: var(--shadow-2);
+    z-index: 1000;
+    pointer-events: none;
+    animation: performanceDebuggerFadeIn 0.2s var(--ease-out-3);
+  }
+
+  @keyframes performanceDebuggerFadeIn {
+    from {
+      opacity: 0;
+      transform: translateX(-50%) translateY(0.5rem);
+    }
+    to {
+      opacity: 1;
+      transform: translateX(-50%) translateY(0);
+    }
+  }
+</style>

package/dist/components/Stage/components/PerformanceDebugger/PerformanceDebugger.svelte.d.ts

@@ -0,0 +1,19 @@
+interface Props {
+    /** Key combination to toggle (default: F9) */
+    shortcut?: string;
+    /** Callback when debug state changes (optional, for external notification) */
+    onToggle?: (enabled: boolean) => void;
+    /** Disabled layers for A/B testing */
+    disabledLayers?: string[];
+}
+declare const PerformanceDebugger: import("svelte").Component<Props, {
+    /** Get debug props to spread into Stage props */ getDebugProps: () => {
+        enableStats: boolean;
+        loggingRate: number;
+        enableMetrics: boolean;
+        logMetricsToConsole: boolean;
+        disabledLayers: string[];
+    };
+}, "">;
+type PerformanceDebugger = ReturnType<typeof PerformanceDebugger>;
+export default PerformanceDebugger;