Photo/Image Editor (e.g. Canva, Photoshop Web)

/editor                    → New blank document
/editor/:projectId         → Load existing project
/editor/:projectId/export  → Export dialog (modal route)
/templates                 → Template gallery
/templates/:templateId     → Apply template to new project
/assets                    → Asset library browser

<EditorShell>
├── <Toolbar />                    — Tool selection, undo/redo buttons
├── <PanelLayout>
│   ├── <LeftPanel>
│   │   ├── <LayersPanel />        — Layer list with drag reorder
│   │   └── <AssetsPanel />        — Stock images, shapes, templates
│   ├── <CanvasViewport>
│   │   ├── <WebGLCanvas />        — Main rendering surface
│   │   ├── <OverlayCanvas />      — Selection outlines, guides, handles
│   │   └── <InteractionLayer />   — Mouse/touch event capture
│   └── <RightPanel>
│       ├── <PropertiesPanel />    — Position, size, rotation, opacity
│       ├── <FilterPanel />        — Non-destructive filter stack
│       └── <TextPanel />          — Font, size, alignment, effects
├── <Timeline />                   — Animation keyframes (future)
└── <StatusBar />                  — Zoom level, cursor position, memory usage

// Core document structure
interface EditorDocument {
  id: string;
  name: string;
  width: number; // Canvas width in pixels
  height: number; // Canvas height in pixels
  dpi: number; // Resolution for print export (72, 150, 300)
  colorSpace: "sRGB" | "Display-P3" | "Adobe-RGB";
  background: BackgroundConfig;
  layers: Layer[]; // Ordered bottom-to-top
  guides: Guide[]; // Ruler guides for alignment
  metadata: DocumentMetadata;
  version: number; // Optimistic concurrency for collab
}

interface DocumentMetadata {
  createdAt: number;
  updatedAt: number;
  createdBy: string;
  templateId: string | null;
  tags: string[];
  exportHistory: ExportRecord[];
}

// Layer hierarchy
type Layer =
  | RasterLayer
  | VectorLayer
  | TextLayer
  | GroupLayer
  | AdjustmentLayer
  | SmartObjectLayer;

interface BaseLayer {
  id: string;
  name: string;
  visible: boolean;
  locked: boolean;
  opacity: number; // 0–1
  blendMode: BlendMode;
  position: { x: number; y: number };
  size: { width: number; height: number };
  rotation: number; // Degrees
  transform: Matrix3x3; // Affine transform matrix
  mask: LayerMask | null;
  clippingMask: boolean; // Clip to layer below
  filters: FilterNode[]; // Non-destructive filter stack
  lockedBy: string | null; // User ID for collab locking
}

interface RasterLayer extends BaseLayer {
  type: "raster";
  sourceImageId: string; // Reference to decoded image buffer
  crop: { x: number; y: number; width: number; height: number } | null;
  tileMap: TileReference[]; // For large images: references to 2048×2048 tiles
}

interface VectorLayer extends BaseLayer {
  type: "vector";
  paths: VectorPath[];
  fill: FillStyle;
  stroke: StrokeStyle;
}

interface TextLayer extends BaseLayer {
  type: "text";
  content: TextContent;
  boundingBox: "auto" | { width: number; height: number };
  overflow: "visible" | "clip" | "ellipsis";
}

interface GroupLayer extends BaseLayer {
  type: "group";
  children: Layer[];
  passThrough: boolean; // Pass-through vs isolated blending
}

interface AdjustmentLayer extends BaseLayer {
  type: "adjustment";
  adjustment: AdjustmentType; // Applies to all layers below
}

interface SmartObjectLayer extends BaseLayer {
  type: "smart-object";
  sourceDocumentId: string; // Reference to embedded document
  lastRasterized: number; // Timestamp of last rasterization
}

// Filter system (DAG-based)
interface FilterNode {
  id: string;
  type: FilterType;
  enabled: boolean;
  parameters: Record<string, number | string | boolean>;
  inputConnections: string[]; // IDs of upstream filter nodes
  gpuProgram: string | null; // Compiled shader reference
}

type FilterType =
  | "blur-gaussian"
  | "blur-motion"
  | "blur-radial"
  | "sharpen-unsharp-mask"
  | "brightness-contrast"
  | "hue-saturation"
  | "color-balance"
  | "curves"
  | "levels"
  | "vibrance"
  | "noise-reduction"
  | "chromatic-aberration"
  | "vignette"
  | "grain"
  | "color-lookup";

// Blend modes (Photoshop-compatible)
type BlendMode =
  | "normal"
  | "dissolve"
  | "darken"
  | "multiply"
  | "color-burn"
  | "linear-burn"
  | "lighten"
  | "screen"
  | "color-dodge"
  | "linear-dodge"
  | "overlay"
  | "soft-light"
  | "hard-light"
  | "vivid-light"
  | "difference"
  | "exclusion"
  | "hue"
  | "saturation"
  | "color"
  | "luminosity";

// Text content model
interface TextContent {
  paragraphs: TextParagraph[];
}

interface TextParagraph {
  alignment: "left" | "center" | "right" | "justify";
  lineHeight: number; // Multiplier (1.2 = 120%)
  spacing: { before: number; after: number };
  runs: TextRun[];
}

interface TextRun {
  text: string;
  style: TextStyle;
}

interface TextStyle {
  fontFamily: string;
  fontSize: number; // In points
  fontWeight: number; // 100–900
  fontStyle: "normal" | "italic";
  color: ColorValue;
  letterSpacing: number; // In em units
  textDecoration: "none" | "underline" | "strikethrough";
  textTransform: "none" | "uppercase" | "lowercase" | "capitalize";
  effects: TextEffect[];
}

interface TextEffect {
  type: "shadow" | "stroke" | "glow" | "warp";
  parameters: Record<string, number | string>;
}

// Color system
type ColorValue =
  | { type: "solid"; r: number; g: number; b: number; a: number }
  | {
      type: "gradient";
      stops: GradientStop[];
      angle: number;
      gradientType: "linear" | "radial";
    }
  | { type: "pattern"; imageId: string; scale: number; rotation: number };

// Undo/redo command model
interface Command {
  id: string;
  type: CommandType;
  timestamp: number;
  userId: string;
  delta: StateDelta; // Minimal diff for undo
  inverseDelta: StateDelta; // Pre-computed for redo
  affectedLayers: string[]; // For collaboration conflict detection
  snapshotRef: string | null; // Reference to full snapshot (every N commands)
}

type CommandType =
  | "layer.create"
  | "layer.delete"
  | "layer.reorder"
  | "layer.transform"
  | "layer.style"
  | "filter.add"
  | "filter.remove"
  | "filter.update"
  | "text.edit"
  | "text.style"
  | "selection.modify"
  | "paint.stroke"
  | "document.resize"
  | "document.crop";

// Template system
interface Template {
  id: string;
  name: string;
  category: string;
  dimensions: { width: number; height: number };
  thumbnail: string;
  slots: TemplateSlot[];
  constraints: LayoutConstraint[];
  document: EditorDocument; // Base document with placeholder content
}

interface TemplateSlot {
  id: string;
  layerId: string; // Maps to a layer in the template document
  type: "image" | "text" | "shape";
  label: string; // "Hero Image", "Headline", "Logo"
  constraints: {
    minWidth?: number;
    maxWidth?: number;
    aspectRatio?: number;
    allowedFonts?: string[];
  };
}

// Tile system for large images
interface TileReference {
  tileX: number; // Tile grid coordinate
  tileY: number;
  level: number; // Mipmap level (0 = full res)
  textureId: string; // WebGL texture handle
  loaded: boolean;
  lastAccessed: number; // For LRU eviction
}

// Collaboration
interface CollaborationState {
  documentId: string;
  activeUsers: CollabUser[];
  layerLocks: Map<string, string>; // layerId → userId
  pendingOperations: CRDTOperation[];
  vectorClock: Record<string, number>;
}

interface CRDTOperation {
  id: string;
  userId: string;
  timestamp: number;
  vectorClock: Record<string, number>;
  type: "insert" | "delete" | "update" | "move";
  target: { layerId: string; property?: string };
  value: unknown;
}

// POST /api/documents
interface CreateDocumentRequest {
  name: string;
  width: number;
  height: number;
  templateId?: string;
  dpi?: number;
}

interface CreateDocumentResponse {
  id: string;
  document: EditorDocument;
  collaborationToken: string; // JWT for WebSocket auth
}

// GET /api/documents/:id
interface GetDocumentResponse {
  document: EditorDocument;
  permissions: DocumentPermissions;
  activeCollaborators: CollabUser[];
}

// PUT /api/documents/:id
interface SaveDocumentRequest {
  document: EditorDocument;
  version: number; // Optimistic concurrency check
  thumbnail: string; // Base64 preview image
}

// POST /api/images/upload
// Content-Type: multipart/form-data
interface UploadImageResponse {
  imageId: string;
  width: number;
  height: number;
  format: string;
  size: number;
  url: string; // CDN URL for the original
  thumbnailUrl: string; // 256px thumbnail
  tilesUrl?: string; // Base URL for tile pyramid (large images only)
}

// POST /api/images/:id/process (server-side fallback for heavy operations)
interface ProcessImageRequest {
  operations: ServerOperation[];
}

type ServerOperation =
  | {
      type: "resize";
      width: number;
      height: number;
      algorithm: "lanczos" | "bicubic";
    }
  | {
      type: "convert";
      format: "webp" | "avif" | "png" | "jpeg";
      quality?: number;
    }
  | { type: "remove-background" } // AI-powered, requires GPU server
  | { type: "upscale"; factor: 2 | 4 };

// POST /api/export
interface ExportRequest {
  documentId: string;
  format: "png" | "jpeg" | "webp" | "avif" | "pdf" | "svg";
  quality?: number; // 0–100 for lossy formats
  scale?: number; // 0.5×, 1×, 2×, 3×
  colorProfile?: "sRGB" | "Display-P3" | "CMYK";
  pages?: number[]; // For multi-page PDF
  layers?: string[]; // Export specific layers only
}

interface ExportResponse {
  downloadUrl: string;
  expiresAt: number;
  size: number;
  dimensions: { width: number; height: number };
}

// Client → Server
type ClientMessage =
  | { type: "join"; documentId: string; token: string }
  | { type: "operation"; op: CRDTOperation }
  | { type: "lock-layer"; layerId: string }
  | { type: "unlock-layer"; layerId: string }
  | { type: "cursor-move"; position: { x: number; y: number }; viewport: Rect }
  | { type: "presence-update"; tool: string; color: string };

// Server → Client
type ServerMessage =
  | { type: "user-joined"; user: CollabUser }
  | { type: "user-left"; userId: string }
  | { type: "operation"; op: CRDTOperation; userId: string }
  | { type: "lock-granted"; layerId: string }
  | { type: "lock-denied"; layerId: string; lockedBy: string }
  | {
      type: "cursor-update";
      userId: string;
      position: { x: number; y: number };
    }
  | {
      type: "conflict";
      operations: CRDTOperation[];
      resolution: "merge" | "reject";
    };

// GET /api/templates?category=social&dimensions=1080x1080
interface TemplateListResponse {
  templates: TemplateSummary[];
  pagination: { cursor: string; hasMore: boolean };
}

// POST /api/templates/:id/instantiate
interface InstantiateTemplateRequest {
  slotValues: Record<
    string,
    | {
        type: "image";
        imageId: string;
      }
    | {
        type: "text";
        content: string;
      }
  >;
}

┌──────────────────────────────────────────────────────┐
│ L1: GPU Texture Cache (WebGL)                        │
│ • Compiled filter results per layer                   │
│ • Composite framebuffers                              │
│ • Eviction: LRU by last-render timestamp              │
│ • Budget: 512MB GPU memory                            │
├──────────────────────────────────────────────────────┤
│ L2: Memory Cache (ArrayBuffer)                        │
│ • Decoded image pixel data                            │
│ • Tile pyramid levels                                 │
│ • Undo snapshot diffs                                 │
│ • Eviction: LRU with priority (visible layers first)  │
│ • Budget: 1GB system memory                           │
├──────────────────────────────────────────────────────┤
│ L3: IndexedDB (Persistent)                            │
│ • Full document state (autosave every 30s)            │
│ • Image source files (compressed)                     │
│ • Undo history (serialized commands)                  │
│ • Font files (subset WOFF2)                           │
│ • Budget: 2GB per document                            │
├──────────────────────────────────────────────────────┤
│ L4: Service Worker Cache                              │
│ • Application shell (HTML, JS, CSS)                   │
│ • WASM codec modules                                  │
│ • Shared assets (icons, default fonts)                │
│ • Stale-while-revalidate for app updates              │
├──────────────────────────────────────────────────────┤
│ L5: CDN (CloudFront)                                  │
│ • User-uploaded images                                │
│ • Template assets                                     │
│ • Stock photo library                                 │
│ • TTL: 1 year (content-addressed URLs)                │
└──────────────────────────────────────────────────────┘

interface FilterCacheEntry {
  filterId: string;
  inputHash: string; // Hash of input texture + parameters
  outputTextureId: string; // Cached GPU texture
  lastUsed: number;
  sizeBytes: number;
}

// When a filter parameter changes:
// 1. Mark that filter's cache as dirty
// 2. Propagate dirty flag to all downstream filters in the DAG
// 3. On next render, recompute only dirty filters
// 4. Upstream cached results remain valid

Frame Request (requestAnimationFrame)
        │
        ▼
┌───────────────────┐
│ 1. Dirty Check    │ ← Skip if no state changed since last frame
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│ 2. Layer Sort     │ ← Topological sort of layer tree (groups expand)
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│ 3. Visibility     │ ← Frustum cull: skip layers outside viewport
│    Culling        │
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│ 4. Filter Chain   │ ← Execute dirty filters (GPU shaders)
│    Evaluation     │    Cache results as framebuffer textures
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│ 5. Compositing    │ ← Blend layers bottom-to-top using blend mode shaders
│    (WebGL)        │    Apply opacity, masks, clipping
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│ 6. Overlay Pass   │ ← Canvas 2D: selection outlines, guides, handles
│    (Canvas 2D)    │    Cursor position, ruler ticks
└────────┬──────────┘
         │
         ▼
┌───────────────────┐
│ 7. Present        │ ← Swap framebuffer to screen
└───────────────────┘

// Multiply blend mode shader
precision highp float;

uniform sampler2D u_baseLayer;
uniform sampler2D u_blendLayer;
uniform float u_opacity;

varying vec2 v_texCoord;

void main() {
  vec4 base = texture2D(u_baseLayer, v_texCoord);
  vec4 blend = texture2D(u_blendLayer, v_texCoord);

  vec3 result = base.rgb * blend.rgb;

  // Apply opacity and alpha compositing
  float alpha = blend.a * u_opacity;
  gl_FragColor = vec4(mix(base.rgb, result, alpha), base.a + alpha * (1.0 - base.a));
}

// Horizontal pass (vertical pass is identical with swapped direction)
precision highp float;

uniform sampler2D u_texture;
uniform vec2 u_resolution;
uniform float u_radius;

varying vec2 v_texCoord;

void main() {
  vec4 sum = vec4(0.0);
  float weightSum = 0.0;

  for (float i = -32.0; i <= 32.0; i += 1.0) {
    if (abs(i) > u_radius) continue;

    float weight = exp(-(i * i) / (2.0 * u_radius * u_radius));
    vec2 offset = vec2(i / u_resolution.x, 0.0);
    sum += texture2D(u_texture, v_texCoord + offset) * weight;
    weightSum += weight;
  }

  gl_FragColor = sum / weightSum;
}

class FilterGraph {
  private nodes: Map<string, FilterNode> = new Map();
  private cache: Map<string, WebGLTexture> = new Map();
  private dirty: Set<string> = new Set();

  markDirty(nodeId: string): void {
    this.dirty.add(nodeId);
    // Propagate to all downstream nodes
    for (const [id, node] of this.nodes) {
      if (node.inputConnections.includes(nodeId)) {
        this.markDirty(id);
      }
    }
  }

  evaluate(outputNodeId: string, gl: WebGL2RenderingContext): WebGLTexture {
    if (!this.dirty.has(outputNodeId) && this.cache.has(outputNodeId)) {
      return this.cache.get(outputNodeId)!;
    }

    const node = this.nodes.get(outputNodeId)!;

    // Recursively evaluate inputs
    const inputTextures = node.inputConnections.map((id) =>
      this.evaluate(id, gl),
    );

    // Execute GPU shader program
    const result = this.executeShader(gl, node, inputTextures);
    this.cache.set(outputNodeId, result);
    this.dirty.delete(outputNodeId);

    return result;
  }

  private executeShader(
    gl: WebGL2RenderingContext,
    node: FilterNode,
    inputs: WebGLTexture[],
  ): WebGLTexture {
    const program = this.getProgram(gl, node.type);
    gl.useProgram(program);

    // Bind input textures
    inputs.forEach((tex, i) => {
      gl.activeTexture(gl.TEXTURE0 + i);
      gl.bindTexture(gl.TEXTURE_2D, tex);
      gl.uniform1i(gl.getUniformLocation(program, `u_input${i}`), i);
    });

    // Set filter parameters as uniforms
    for (const [key, value] of Object.entries(node.parameters)) {
      const loc = gl.getUniformLocation(program, `u_${key}`);
      if (typeof value === "number") gl.uniform1f(loc, value);
    }

    // Render to framebuffer
    const outputTexture = this.allocateTexture(gl);
    const fb = gl.createFramebuffer();
    gl.bindFramebuffer(gl.FRAMEBUFFER, fb);
    gl.framebufferTexture2D(
      gl.FRAMEBUFFER,
      gl.COLOR_ATTACHMENT0,
      gl.TEXTURE_2D,
      outputTexture,
      0,
    );
    gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
    gl.deleteFramebuffer(fb);

    return outputTexture;
  }
}

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'wasm-unsafe-eval';
  style-src 'self' 'unsafe-inline';
  img-src 'self' blob: data: https://cdn.devpro-editor.com;
  connect-src 'self' wss://collab.devpro-editor.com https://api.devpro-editor.com;
  worker-src 'self' blob:;
  child-src 'self' https://plugins.devpro-editor.com;
  frame-ancestors 'none';
  base-uri 'self';
  form-action 'self';

// Server-side image validation pipeline
async function validateUpload(
  file: Buffer,
  mimeType: string,
): Promise<ValidationResult> {
  // 1. Check magic bytes match claimed MIME type
  const detected = detectFileType(file.slice(0, 12));
  if (detected.mime !== mimeType) {
    return { valid: false, reason: "MIME type mismatch" };
  }

  // 2. Enforce size limits
  if (file.length > 50 * 1024 * 1024) {
    // 50MB max
    return { valid: false, reason: "File too large" };
  }

  // 3. Attempt decode to verify it's a valid image (not a polyglot)
  const metadata = await sharp(file).metadata();
  if (!metadata.width || !metadata.height) {
    return { valid: false, reason: "Invalid image data" };
  }

  // 4. Check dimensions
  if (metadata.width * metadata.height > 100_000_000) {
    // 100MP limit
    return { valid: false, reason: "Image dimensions exceed limit" };
  }

  // 5. Strip all metadata (EXIF, XMP, IPTC) — prevents data leakage
  const clean = await sharp(file)
    .rotate() // Apply EXIF orientation before stripping
    .withMetadata({ orientation: undefined })
    .toBuffer();

  // 6. Re-encode to eliminate any embedded payloads
  const reencoded = await sharp(clean).png({ compressionLevel: 6 }).toBuffer();

  return { valid: true, cleanBuffer: reencoded, metadata };
}

// Plugin host (main thread)
class PluginSandbox {
  private iframe: HTMLIFrameElement;
  private messagePort: MessagePort;

  constructor(pluginUrl: string) {
    this.iframe = document.createElement("iframe");
    this.iframe.sandbox.add("allow-scripts"); // No forms, no popups, no navigation
    this.iframe.src = `https://plugins.devpro-editor.com/sandbox.html`;
    this.iframe.style.display = "none";
    document.body.appendChild(this.iframe);

    // Establish MessageChannel for structured communication
    const channel = new MessageChannel();
    this.messagePort = channel.port1;
    this.iframe.contentWindow!.postMessage(
      { type: "init", pluginUrl },
      "https://plugins.devpro-editor.com",
      [channel.port2],
    );
  }

  async executeFilter(
    imageData: ImageData,
    params: Record<string, number>,
  ): Promise<ImageData> {
    // Transfer pixel data to sandbox (zero-copy via transferable)
    const buffer = imageData.data.buffer;
    this.messagePort.postMessage(
      {
        type: "filter",
        buffer,
        width: imageData.width,
        height: imageData.height,
        params,
      },
      [buffer],
    );

    // Wait for result with timeout
    return new Promise((resolve, reject) => {
      const timeout = setTimeout(
        () => reject(new Error("Plugin timeout")),
        5000,
      );
      this.messagePort.onmessage = (e) => {
        clearTimeout(timeout);
        const result = new ImageData(
          new Uint8ClampedArray(e.data.buffer),
          e.data.width,
          e.data.height,
        );
        resolve(result);
      };
    });
  }

  destroy(): void {
    this.messagePort.close();
    this.iframe.remove();
  }
}

class TileManager {
  private readonly TILE_SIZE = 2048;
  private tiles: Map<string, TileState> = new Map();
  private loadQueue: PriorityQueue<TileRequest>;
  private maxLoadedTiles: number; // Based on available GPU memory

  getTileKey(x: number, y: number, level: number): string {
    return `${level}:${x}:${y}`;
  }

  updateViewport(viewport: Rect, zoom: number): void {
    // Determine which mipmap level to use based on zoom
    const level = Math.max(0, Math.floor(-Math.log2(zoom)));

    // Calculate visible tile range
    const tileScale = Math.pow(2, level);
    const startX = Math.floor(viewport.x / (this.TILE_SIZE * tileScale));
    const startY = Math.floor(viewport.y / (this.TILE_SIZE * tileScale));
    const endX = Math.ceil(
      (viewport.x + viewport.width) / (this.TILE_SIZE * tileScale),
    );
    const endY = Math.ceil(
      (viewport.y + viewport.height) / (this.TILE_SIZE * tileScale),
    );

    // Queue visible tiles for loading (highest priority)
    for (let y = startY; y <= endY; y++) {
      for (let x = startX; x <= endX; x++) {
        const key = this.getTileKey(x, y, level);
        if (!this.tiles.has(key) || !this.tiles.get(key)!.loaded) {
          this.loadQueue.enqueue({ x, y, level, priority: 0 });
        }
      }
    }

    // Queue adjacent tiles for prefetch (lower priority)
    this.prefetchAdjacentTiles(startX, startY, endX, endY, level);

    // Evict distant tiles if over memory budget
    this.evictDistantTiles(viewport, level);
  }
}

// Service Worker strategy for editor assets
const CACHE_STRATEGIES = {
  // App shell: cache-first, update in background
  shell: new CacheFirst({
    cacheName: "editor-shell-v3",
    plugins: [
      new ExpirationPlugin({ maxEntries: 50, maxAgeSeconds: 7 * 24 * 3600 }),
    ],
  }),

  // WASM modules: cache-first (immutable, versioned URLs)
  wasm: new CacheFirst({
    cacheName: "editor-wasm-v1",
    plugins: [new CacheableResponsePlugin({ statuses: [200] })],
  }),

  // User assets: network-first with cache fallback
  assets: new NetworkFirst({
    cacheName: "user-assets",
    networkTimeoutSeconds: 5,
    plugins: [
      new ExpirationPlugin({ maxEntries: 200, maxAgeSeconds: 30 * 24 * 3600 }),
    ],
  }),

  // API calls: network-only (stale data is dangerous for collab)
  api: new NetworkOnly(),
};

// Layer panel with ARIA tree role
function LayersPanel({ layers }: { layers: Layer[] }) {
  return (
    <div role="tree" aria-label="Document layers" aria-orientation="vertical">
      {layers.map((layer, index) => (
        <div
          key={layer.id}
          role="treeitem"
          aria-level={1}
          aria-setsize={layers.length}
          aria-posinset={index + 1}
          aria-selected={layer.id === selectedLayerId}
          aria-expanded={
            layer.type === "group" ? isExpanded(layer.id) : undefined
          }
          aria-label={`${layer.name}, ${layer.type} layer, ${layer.visible ? "visible" : "hidden"}, opacity ${Math.round(layer.opacity * 100)}%`}
          tabIndex={layer.id === focusedLayerId ? 0 : -1}
        >
          <span aria-hidden="true">{getLayerIcon(layer.type)}</span>
          <span>{layer.name}</span>
          <button
            aria-label={`Toggle visibility of ${layer.name}`}
            aria-pressed={layer.visible}
          />
          <button
            aria-label={`Lock ${layer.name}`}
            aria-pressed={layer.locked}
          />
        </div>
      ))}
    </div>
  );
}

<div className="relative">
  {/* Visual rendering — hidden from AT */}
  <canvas aria-hidden="true" ref={canvasRef} />

  {/* Accessible description of canvas state */}
  <div role="img" aria-label={canvasDescription} className="sr-only">
    <p>
      Canvas dimensions: {doc.width} by {doc.height} pixels
    </p>
    <p>
      {layers.length} layers. Selected: {selectedLayer?.name ?? "none"}
    </p>
    <ul aria-label="Layer descriptions">
      {layers.map((l) => (
        <li key={l.id}>
          {l.name}: {l.type} layer at position {l.position.x}, {l.position.y}
        </li>
      ))}
    </ul>
  </div>

  {/* Live region for operation announcements */}
  <div role="status" aria-live="polite" aria-atomic="true" className="sr-only">
    {lastAction}
  </div>
</div>

// Structured error reporting for rendering failures
interface RenderingError {
  type:
    | "webgl_context_lost"
    | "shader_compile_error"
    | "texture_allocation_failed"
    | "worker_crash";
  timestamp: number;
  documentId: string;
  layerCount: number;
  gpuMemoryEstimate: number;
  filterChainLength: number;
  browserInfo: {
    gpu: string;
    maxTextureSize: number;
    extensions: string[];
  };
  stack?: string;
  userAction: string; // What triggered the error
}

function reportRenderError(error: RenderingError): void {
  // Batch errors — don't spam on repeated context losses
  if (
    recentErrors.has(error.type) &&
    Date.now() - recentErrors.get(error.type)! < 5000
  ) {
    return;
  }
  recentErrors.set(error.type, Date.now());

  navigator.sendBeacon("/api/telemetry/error", JSON.stringify(error));
}

class PerformanceBudget {
  private frameTimings: number[] = [];
  private readonly BUDGET_FRAME_MS = 16; // 60fps target
  private readonly DEGRADATION_THRESHOLD = 0.2; // 20% of frames over budget

  recordFrame(durationMs: number): void {
    this.frameTimings.push(durationMs);
    if (this.frameTimings.length > 60) this.frameTimings.shift();

    const overBudget = this.frameTimings.filter(
      (t) => t > this.BUDGET_FRAME_MS,
    ).length;
    const ratio = overBudget / this.frameTimings.length;

    if (ratio > this.DEGRADATION_THRESHOLD) {
      this.applyDegradation();
    }
  }

  private applyDegradation(): void {
    // Progressive quality reduction
    // 1. Reduce filter preview resolution (2× downscale)
    // 2. Disable real-time blend mode preview
    // 3. Show checker pattern for hidden layers instead of rendering them
    // 4. Reduce undo snapshot frequency
    emitEvent("performance:degraded", { level: this.degradationLevel++ });
  }
}