@fieldnotes/core 0.65.0 → 0.66.0

package/dist/index.cjs

@@ -31,6 +31,12 @@ __export(index_exports, {
   ElementStore: () => ElementStore,
   EraserTool: () => EraserTool,
   FOCUS_PRESENCE_KIND: () => FOCUS_PRESENCE_KIND,
+  FOG_MAX_TILES: () => FOG_MAX_TILES,
+  FOG_STATE_VERSION: () => FOG_STATE_VERSION,
+  FOG_TILE_CELLS: () => FOG_TILE_CELLS,
+  FogManager: () => FogManager,
+  FogRenderer: () => FogRenderer,
+  FogTool: () => FogTool,
   HandTool: () => HandTool,
   HistoryStack: () => HistoryStack,
   HtmlPainterMissingError: () => HtmlPainterMissingError,
@@ -74,6 +80,7 @@ __export(index_exports, {
   attachAwareness: () => attachAwareness,
   boundsIntersect: () => boundsIntersect,
   cameraOriginForView: () => cameraOriginForView,
+  canonicalizeFogTile: () => canonicalizeFogTile,
   captureCameraView: () => captureCameraView,
   computeElementRects: () => computeElementRects,
   createArrow: () => createArrow,
@@ -91,6 +98,8 @@ __export(index_exports, {
   exportImage: () => exportImage,
   exportSvg: () => exportSvg,
   fitZoomForView: () => fitZoomForView,
+  fogDecodeBase64: () => decodeBase64,
+  fogEncodeBase64: () => encodeBase64,
   footprintFromSize: () => footprintFromSize,
   getActiveFormats: () => getActiveFormats,
   getArrowBounds: () => getArrowBounds,
@@ -116,6 +125,7 @@ __export(index_exports, {
   isPathPresence: () => isPathPresence,
   isPingPresence: () => isPingPresence,
   pathDistanceCells: () => pathDistanceCells,
+  recommendedFogCellSize: () => recommendedFogCellSize,
   resolveHtmlRouting: () => resolveHtmlRouting,
   setFontSize: () => setFontSize,
   smartSnap: () => smartSnap,
@@ -132,7 +142,10 @@ __export(index_exports, {
   toggleBold: () => toggleBold,
   toggleItalic: () => toggleItalic,
   toggleStrikethrough: () => toggleStrikethrough,
-  toggleUnderline: () => toggleUnderline
+  toggleUnderline: () => toggleUnderline,
+  validateFogDefinition: () => validateFogDefinition,
+  validateFogState: () => validateFogState,
+  validateFogTile: () => validateFogTile
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -592,8 +605,464 @@ function sanitizeAttributes(el, tag) {
   }
 }
 
+// src/fog/types.ts
+var FOG_STATE_VERSION = 1;
+var FOG_TILE_CELLS = 128;
+var FOG_MAX_TILES = 256;
+
+// src/fog/tile-codec.ts
+var TILE_BYTES = FOG_TILE_CELLS * FOG_TILE_CELLS / 8;
+var CANONICAL_B64_LENGTH = Math.ceil(TILE_BYTES / 3) * 4;
+var B64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+var B64_LOOKUP = new Uint8Array(128);
+for (let i = 0; i < B64_CHARS.length; i++) B64_LOOKUP[B64_CHARS.charCodeAt(i)] = i;
+function encodeBase64(bytes) {
+  let result = "";
+  const len = bytes.length;
+  for (let i = 0; i < len; i += 3) {
+    const a = bytes[i];
+    const b = i + 1 < len ? bytes[i + 1] : 0;
+    const c = i + 2 < len ? bytes[i + 2] : 0;
+    result += B64_CHARS[a >> 2 & 63];
+    result += B64_CHARS[(a << 4 | b >> 4) & 63];
+    result += i + 1 < len ? B64_CHARS[(b << 2 | c >> 6) & 63] : "=";
+    result += i + 2 < len ? B64_CHARS[c & 63] : "=";
+  }
+  return result;
+}
+function decodeBase64(str) {
+  if (str.length % 4 !== 0) throw new Error("Invalid base64 length");
+  let padCount = 0;
+  if (str.length >= 2 && str[str.length - 1] === "=") {
+    padCount++;
+    if (str[str.length - 2] === "=") padCount++;
+  }
+  const byteLen = str.length / 4 * 3 - padCount;
+  const bytes = new Uint8Array(byteLen);
+  let j = 0;
+  for (let i = 0; i < str.length; i += 4) {
+    const a = B64_LOOKUP[str.charCodeAt(i)];
+    const b = B64_LOOKUP[str.charCodeAt(i + 1)];
+    const c = str[i + 2] === "=" ? 0 : B64_LOOKUP[str.charCodeAt(i + 2)];
+    const d = str[i + 3] === "=" ? 0 : B64_LOOKUP[str.charCodeAt(i + 3)];
+    bytes[j++] = a << 2 | b >> 4;
+    if (j < byteLen) bytes[j++] = (b << 4 | c >> 2) & 255;
+    if (j < byteLen) bytes[j++] = (c << 6 | d) & 255;
+  }
+  return bytes;
+}
+function createTileBytes(fill) {
+  const bytes = new Uint8Array(TILE_BYTES);
+  if (fill) bytes.fill(255);
+  return bytes;
+}
+function setBit(bytes, col, row, value) {
+  const index = row * FOG_TILE_CELLS + col;
+  const byteIndex = index >> 3;
+  const bitIndex = 7 - (index & 7);
+  if (value) {
+    bytes[byteIndex] = bytes[byteIndex] | 1 << bitIndex;
+  } else {
+    bytes[byteIndex] = bytes[byteIndex] & ~(1 << bitIndex);
+  }
+}
+function isTileAllValue(bytes, value) {
+  const expected = value ? 255 : 0;
+  for (let i = 0; i < TILE_BYTES; i++) {
+    if (bytes[i] !== expected) return false;
+  }
+  return true;
+}
+function isBaseValue(base) {
+  return base === "revealed";
+}
+function isTileBase(bytes, base) {
+  return isTileAllValue(bytes, isBaseValue(base));
+}
+function canonicalizeEdgePadding(bytes, def, tileX, tileY) {
+  const baseVal = isBaseValue(def.base);
+  const worldX = tileX * FOG_TILE_CELLS * def.cellSize;
+  const worldY = tileY * FOG_TILE_CELLS * def.cellSize;
+  const boundsRight = def.bounds.x + def.bounds.w;
+  const boundsBottom = def.bounds.y + def.bounds.h;
+  for (let row = 0; row < FOG_TILE_CELLS; row++) {
+    for (let col = 0; col < FOG_TILE_CELLS; col++) {
+      const cellWorldX = worldX + col * def.cellSize;
+      const cellWorldY = worldY + row * def.cellSize;
+      const outside = cellWorldX < def.bounds.x || cellWorldY < def.bounds.y || cellWorldX >= boundsRight || cellWorldY >= boundsBottom;
+      if (outside) {
+        setBit(bytes, col, row, baseVal);
+      }
+    }
+  }
+}
+function canonicalizeFogTile(tile, def) {
+  const bytes = decodeBase64(tile.data);
+  canonicalizeEdgePadding(bytes, def, tile.x, tile.y);
+  if (isTileBase(bytes, def.base)) return null;
+  return { x: tile.x, y: tile.y, data: encodeBase64(bytes) };
+}
+function isCanonicalBase64(str) {
+  if (str.length !== CANONICAL_B64_LENGTH) return false;
+  if (str[str.length - 1] !== "=" || str[str.length - 2] === "=") return false;
+  for (let i = 0; i < str.length - 1; i++) {
+    if (!B64_CHARS.includes(str[i])) return false;
+  }
+  const finalSextet = B64_CHARS.indexOf(str[str.length - 2]);
+  return finalSextet >= 0 && (finalSextet & 3) === 0;
+}
+function isSafeInteger(n2) {
+  return typeof n2 === "number" && Number.isSafeInteger(n2);
+}
+function isFinitePositive(n2) {
+  return typeof n2 === "number" && Number.isFinite(n2) && n2 > 0;
+}
+function isFiniteBounds(b) {
+  if (typeof b !== "object" || b === null) return false;
+  const r = b;
+  return typeof r["x"] === "number" && Number.isFinite(r["x"]) && typeof r["y"] === "number" && Number.isFinite(r["y"]) && isFinitePositive(r["w"]) && isFinitePositive(r["h"]);
+}
+function tileIntersectsBounds(x, y, def) {
+  const tileWorldX = x * FOG_TILE_CELLS * def.cellSize;
+  const tileWorldY = y * FOG_TILE_CELLS * def.cellSize;
+  const tileWorldW = FOG_TILE_CELLS * def.cellSize;
+  const tileWorldH = FOG_TILE_CELLS * def.cellSize;
+  return !(tileWorldX + tileWorldW <= def.bounds.x || tileWorldY + tileWorldH <= def.bounds.y || tileWorldX >= def.bounds.x + def.bounds.w || tileWorldY >= def.bounds.y + def.bounds.h);
+}
+function validateFogDefinition(def) {
+  if (typeof def !== "object" || def === null) {
+    throw new Error("Invalid fog definition: expected an object");
+  }
+  const d = def;
+  if (d["version"] !== 1) throw new Error("Invalid fog definition: unsupported version");
+  if (typeof d["generation"] !== "string" || d["generation"].length === 0 || d["generation"].length > 128 || !/^[\x20-\x7e]+$/.test(d["generation"])) {
+    throw new Error("Invalid fog definition: invalid generation");
+  }
+  if (!isFiniteBounds(d["bounds"])) {
+    throw new Error("Invalid fog definition: invalid bounds");
+  }
+  if (!isFinitePositive(d["cellSize"])) {
+    throw new Error("Invalid fog definition: invalid cellSize");
+  }
+  if (d["tileCells"] !== 128) {
+    throw new Error("Invalid fog definition: tileCells must be 128");
+  }
+  if (d["base"] !== "covered" && d["base"] !== "revealed") {
+    throw new Error("Invalid fog definition: invalid base");
+  }
+}
+function validateFogTile(tile, def) {
+  if (typeof tile !== "object" || tile === null) {
+    throw new Error("Invalid fog tile: expected an object");
+  }
+  const t = tile;
+  if (!isSafeInteger(t["x"]) || !isSafeInteger(t["y"])) {
+    throw new Error("Invalid fog tile: coordinates must be safe integers");
+  }
+  if (!tileIntersectsBounds(t["x"], t["y"], def)) {
+    throw new Error("Invalid fog tile: coordinates outside bounds");
+  }
+  if (typeof t["data"] !== "string" || !isCanonicalBase64(t["data"])) {
+    throw new Error("Invalid fog tile: invalid data");
+  }
+  const decoded = decodeBase64(t["data"]);
+  if (decoded.length !== TILE_BYTES) {
+    throw new Error("Invalid fog tile: decoded data wrong length");
+  }
+  if (isTileBase(decoded, def.base)) {
+    throw new Error("Invalid fog tile: base-value tiles must be omitted");
+  }
+  const canonical = new Uint8Array(decoded);
+  canonicalizeEdgePadding(canonical, def, t["x"], t["y"]);
+  for (let i = 0; i < decoded.length; i++) {
+    if (decoded[i] !== canonical[i]) {
+      throw new Error("Invalid fog tile: non-canonical edge padding");
+    }
+  }
+}
+function validateFogState(state) {
+  if (typeof state !== "object" || state === null) {
+    throw new Error("Invalid fog state: expected an object");
+  }
+  const s = state;
+  validateFogDefinition(s["definition"]);
+  const def = s["definition"];
+  if (!Array.isArray(s["tiles"])) {
+    throw new Error("Invalid fog state: tiles must be an array");
+  }
+  const tiles = s["tiles"];
+  if (tiles.length > FOG_MAX_TILES) {
+    throw new Error(`Invalid fog state: too many tiles (${tiles.length} > ${FOG_MAX_TILES})`);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const tile of tiles) {
+    validateFogTile(tile, def);
+    const t = tile;
+    const key = `${t.x},${t.y}`;
+    if (seen.has(key)) {
+      throw new Error(`Invalid fog state: duplicate tile at (${t.x}, ${t.y})`);
+    }
+    seen.add(key);
+  }
+}
+function recommendedFogCellSize(bounds) {
+  let cellSize = 1;
+  while (true) {
+    const tileWorldSize = FOG_TILE_CELLS * cellSize;
+    const minTX = Math.floor(bounds.x / tileWorldSize);
+    const minTY = Math.floor(bounds.y / tileWorldSize);
+    const maxTX = Math.ceil((bounds.x + bounds.w) / tileWorldSize) - 1;
+    const maxTY = Math.ceil((bounds.y + bounds.h) / tileWorldSize) - 1;
+    const tw = maxTX - minTX + 1;
+    const th = maxTY - minTY + 1;
+    if (tw * th <= FOG_MAX_TILES) return cellSize;
+    cellSize++;
+    if (cellSize > 1e4) return cellSize;
+  }
+}
+function tileKey(x, y) {
+  return `${x},${y}`;
+}
+function worldToCell(worldX, worldY, cellSize) {
+  const cellX = Math.floor(worldX / cellSize);
+  const cellY = Math.floor(worldY / cellSize);
+  const tx = Math.floor(cellX / FOG_TILE_CELLS);
+  const ty = Math.floor(cellY / FOG_TILE_CELLS);
+  let col = cellX - tx * FOG_TILE_CELLS;
+  let row = cellY - ty * FOG_TILE_CELLS;
+  if (col < 0) col += FOG_TILE_CELLS;
+  if (row < 0) row += FOG_TILE_CELLS;
+  return { tx, ty, col, row };
+}
+function rasterizeRegion(state, region, operation) {
+  const { definition } = state;
+  const bitValue = operation === "reveal";
+  const tileMap = /* @__PURE__ */ new Map();
+  for (const tile of state.tiles) {
+    tileMap.set(tileKey(tile.x, tile.y), decodeBase64(tile.data));
+  }
+  const baseFill = isBaseValue(definition.base);
+  const affectedTiles = /* @__PURE__ */ new Set();
+  const setCellIfInBounds = (worldX, worldY) => {
+    if (worldX < definition.bounds.x || worldY < definition.bounds.y || worldX >= definition.bounds.x + definition.bounds.w || worldY >= definition.bounds.y + definition.bounds.h) {
+      return;
+    }
+    const { tx, ty, col, row } = worldToCell(worldX, worldY, definition.cellSize);
+    if (!tileIntersectsBounds(tx, ty, definition)) return;
+    const key = tileKey(tx, ty);
+    let bytes = tileMap.get(key);
+    if (!bytes) {
+      bytes = createTileBytes(baseFill);
+      tileMap.set(key, bytes);
+    } else if (!affectedTiles.has(key)) {
+      const clone = new Uint8Array(bytes);
+      tileMap.set(key, clone);
+      bytes = clone;
+    }
+    affectedTiles.add(key);
+    setBit(bytes, col, row, bitValue);
+  };
+  switch (region.kind) {
+    case "brush":
+      rasterizeBrush(region.points, region.radius, definition, setCellIfInBounds);
+      break;
+    case "rectangle":
+      rasterizeRectangle(region.from, region.to, definition, setCellIfInBounds);
+      break;
+    case "polygon":
+      rasterizePolygon(region.points, definition, setCellIfInBounds);
+      break;
+  }
+  if (affectedTiles.size === 0) return { changed: [], noop: true };
+  const changedTiles = [];
+  let hasChange = false;
+  for (const key of affectedTiles) {
+    const bytes = tileMap.get(key);
+    const [txStr, tyStr] = key.split(",");
+    const tx = Number(txStr);
+    const ty = Number(tyStr);
+    canonicalizeEdgePadding(bytes, definition, tx, ty);
+    const newData = encodeBase64(bytes);
+    const originalTile = state.tiles.find((t) => t.x === tx && t.y === ty);
+    if (originalTile) {
+      if (originalTile.data !== newData) {
+        hasChange = true;
+        changedTiles.push({ x: tx, y: ty, data: newData });
+      }
+    } else if (!isTileBase(bytes, definition.base)) {
+      hasChange = true;
+      changedTiles.push({ x: tx, y: ty, data: newData });
+    }
+  }
+  if (!hasChange) return { changed: [], noop: true };
+  return { changed: changedTiles, noop: false };
+}
+function applyRasterResult(state, result) {
+  if (result.noop) return state;
+  const changedMap = /* @__PURE__ */ new Map();
+  for (const t of result.changed) changedMap.set(tileKey(t.x, t.y), t);
+  const tiles = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const tile of state.tiles) {
+    const key = tileKey(tile.x, tile.y);
+    seen.add(key);
+    const changed = changedMap.get(key);
+    if (changed) {
+      const bytes = decodeBase64(changed.data);
+      if (!isTileBase(bytes, state.definition.base)) {
+        tiles.push(changed);
+      }
+    } else {
+      tiles.push(tile);
+    }
+  }
+  for (const t of result.changed) {
+    const key = tileKey(t.x, t.y);
+    if (seen.has(key)) continue;
+    const bytes = decodeBase64(t.data);
+    if (!isTileBase(bytes, state.definition.base)) {
+      tiles.push(t);
+    }
+  }
+  if (tiles.length > FOG_MAX_TILES) {
+    throw new Error(`Fog tile cap exceeded: ${tiles.length} > ${FOG_MAX_TILES}`);
+  }
+  return { definition: state.definition, tiles };
+}
+function sampleAndSimplify(points, tolerance) {
+  if (points.length <= 2) return [...points];
+  const sampled = [points[0]];
+  let lastSampled = points[0];
+  for (let i = 1; i < points.length - 1; i++) {
+    const p = points[i];
+    const dx = p.x - lastSampled.x;
+    const dy = p.y - lastSampled.y;
+    if (dx * dx + dy * dy >= tolerance * tolerance) {
+      sampled.push(p);
+      lastSampled = p;
+    }
+  }
+  sampled.push(points[points.length - 1]);
+  return sampled;
+}
+function rasterizeBrush(points, radius, def, setCell) {
+  if (points.length === 0) return;
+  const simplified = sampleAndSimplify(points, def.cellSize * 0.5);
+  for (let i = 0; i < simplified.length; i++) {
+    const p = simplified[i];
+    rasterizeDisc(p.x, p.y, radius, def, setCell);
+    if (i > 0) {
+      const prev = simplified[i - 1];
+      rasterizeCapsuleSegment(prev.x, prev.y, p.x, p.y, radius, def, setCell);
+    }
+  }
+}
+function rasterizeDisc(cx, cy, radius, def, setCell) {
+  const minX = Math.max(def.bounds.x, cx - radius);
+  const maxX = Math.min(def.bounds.x + def.bounds.w - 1, cx + radius);
+  const minY = Math.max(def.bounds.y, cy - radius);
+  const maxY = Math.min(def.bounds.y + def.bounds.h - 1, cy + radius);
+  const startCol = Math.floor(minX / def.cellSize) * def.cellSize;
+  const startRow = Math.floor(minY / def.cellSize) * def.cellSize;
+  const r2 = radius * radius;
+  for (let wy = startRow; wy <= maxY; wy += def.cellSize) {
+    for (let wx = startCol; wx <= maxX; wx += def.cellSize) {
+      const cellCenterX = wx + def.cellSize * 0.5;
+      const cellCenterY = wy + def.cellSize * 0.5;
+      const dx = cellCenterX - cx;
+      const dy = cellCenterY - cy;
+      if (dx * dx + dy * dy <= r2) {
+        setCell(wx, wy);
+      }
+    }
+  }
+}
+function rasterizeCapsuleSegment(x1, y1, x2, y2, radius, def, setCell) {
+  const segDx = x2 - x1;
+  const segDy = y2 - y1;
+  const segLen2 = segDx * segDx + segDy * segDy;
+  if (segLen2 === 0) return;
+  const minX = Math.max(def.bounds.x, Math.min(x1, x2) - radius);
+  const maxX = Math.min(def.bounds.x + def.bounds.w - 1, Math.max(x1, x2) + radius);
+  const minY = Math.max(def.bounds.y, Math.min(y1, y2) - radius);
+  const maxY = Math.min(def.bounds.y + def.bounds.h - 1, Math.max(y1, y2) + radius);
+  const startCol = Math.floor(minX / def.cellSize) * def.cellSize;
+  const startRow = Math.floor(minY / def.cellSize) * def.cellSize;
+  const r2 = radius * radius;
+  for (let wy = startRow; wy <= maxY; wy += def.cellSize) {
+    for (let wx = startCol; wx <= maxX; wx += def.cellSize) {
+      const cellCenterX = wx + def.cellSize * 0.5;
+      const cellCenterY = wy + def.cellSize * 0.5;
+      const t = Math.max(
+        0,
+        Math.min(1, ((cellCenterX - x1) * segDx + (cellCenterY - y1) * segDy) / segLen2)
+      );
+      const projX = x1 + t * segDx;
+      const projY = y1 + t * segDy;
+      const dx = cellCenterX - projX;
+      const dy = cellCenterY - projY;
+      if (dx * dx + dy * dy <= r2) {
+        setCell(wx, wy);
+      }
+    }
+  }
+}
+function rasterizeRectangle(from, to, def, setCell) {
+  const minX = Math.max(def.bounds.x, Math.min(from.x, to.x));
+  const maxX = Math.min(def.bounds.x + def.bounds.w - 1, Math.max(from.x, to.x));
+  const minY = Math.max(def.bounds.y, Math.min(from.y, to.y));
+  const maxY = Math.min(def.bounds.y + def.bounds.h - 1, Math.max(from.y, to.y));
+  const startCol = Math.floor(minX / def.cellSize) * def.cellSize;
+  const startRow = Math.floor(minY / def.cellSize) * def.cellSize;
+  for (let wy = startRow; wy <= maxY; wy += def.cellSize) {
+    for (let wx = startCol; wx <= maxX; wx += def.cellSize) {
+      setCell(wx, wy);
+    }
+  }
+}
+function rasterizePolygon(points, def, setCell) {
+  if (points.length < 3) return;
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  for (const p of points) {
+    if (p.x < minX) minX = p.x;
+    if (p.x > maxX) maxX = p.x;
+    if (p.y < minY) minY = p.y;
+    if (p.y > maxY) maxY = p.y;
+  }
+  minX = Math.max(def.bounds.x, minX);
+  maxX = Math.min(def.bounds.x + def.bounds.w - 1, maxX);
+  minY = Math.max(def.bounds.y, minY);
+  maxY = Math.min(def.bounds.y + def.bounds.h - 1, maxY);
+  const startCol = Math.floor(minX / def.cellSize) * def.cellSize;
+  const startRow = Math.floor(minY / def.cellSize) * def.cellSize;
+  for (let wy = startRow; wy <= maxY; wy += def.cellSize) {
+    for (let wx = startCol; wx <= maxX; wx += def.cellSize) {
+      const cx = wx + def.cellSize * 0.5;
+      const cy = wy + def.cellSize * 0.5;
+      if (pointInPolygon(cx, cy, points)) {
+        setCell(wx, wy);
+      }
+    }
+  }
+}
+function pointInPolygon(x, y, polygon) {
+  let inside = false;
+  const n2 = polygon.length;
+  for (let i = 0, j = n2 - 1; i < n2; j = i++) {
+    const pi = polygon[i];
+    const pj = polygon[j];
+    if (pi.y > y !== pj.y > y && x < (pj.x - pi.x) * (y - pi.y) / (pj.y - pi.y) + pi.x) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
 // src/core/state-serializer.ts
-var CURRENT_VERSION = 2;
+var CURRENT_VERSION = 3;
 var ELEMENT_TYPES = [
   "stroke",
   "note",
@@ -605,7 +1074,7 @@ var ELEMENT_TYPES = [
   "grid",
   "template"
 ];
-function exportState(elements, camera, layers = [], activeLayerId) {
+function exportState(elements, camera, layers = [], activeLayerId, fog) {
   const state = {
     version: CURRENT_VERSION,
     camera: {
@@ -622,6 +1091,7 @@ function exportState(elements, camera, layers = [], activeLayerId) {
     layers: layers.map((l) => ({ ...l }))
   };
   if (activeLayerId) state.activeLayerId = activeLayerId;
+  if (fog) state.fog = structuredClone(fog);
   return state;
 }
 function parseState(json) {
@@ -699,6 +1169,9 @@ function validateState(data) {
     }
   }
   cleanBindings(elements);
+  if (obj["fog"] !== void 0 && obj["fog"] !== null) {
+    validateFogState(obj["fog"]);
+  }
 }
 function validateElement(el) {
   if (!isRecord(el)) {
@@ -844,12 +1317,14 @@ var AutoSave = class {
     this.key = options.key ?? DEFAULT_KEY;
     this.debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
     this.layerManager = options.layerManager;
+    this.fogManager = options.fogManager;
     this.adapter = options.adapter ?? new LocalStorageAdapter();
     this.onError = options.onError;
   }
   key;
   debounceMs;
   layerManager;
+  fogManager;
   adapter;
   timerId = null;
   unsubscribers = [];
@@ -867,6 +1342,9 @@ var AutoSave = class {
     if (this.layerManager) {
       this.unsubscribers.push(this.layerManager.on("change", schedule));
     }
+    if (this.fogManager) {
+      this.unsubscribers.push(this.fogManager.on("change", schedule));
+    }
   }
   stop() {
     this.cancelPending();
@@ -903,7 +1381,8 @@ var AutoSave = class {
     this.saving = true;
     try {
       const layers = this.layerManager?.snapshot() ?? [];
-      const state = exportState(this.store.snapshot(), this.camera, layers);
+      const fog = this.fogManager?.getState() ?? void 0;
+      const state = exportState(this.store.snapshot(), this.camera, layers, void 0, fog);
       await this.adapter.save(this.key, JSON.stringify(state));
     } catch (e) {
       this.onError?.(e instanceof Error ? e : new Error(String(e)));
@@ -5235,6 +5714,8 @@ var MinimapController = class {
   // read the `viewport` parameter. Assigned in the constructor body instead.
   htmlPainters;
   scene = null;
+  fogRenderer = null;
+  fogUnsub = null;
   frameId = null;
   debounceTimer = null;
   dragging = false;
@@ -5249,6 +5730,15 @@ var MinimapController = class {
     this.renderScene();
     this.requestDraw();
   }
+  setFogRenderer(renderer) {
+    if (this.disposed) return;
+    if (this.fogUnsub) {
+      this.fogUnsub();
+      this.fogUnsub = null;
+    }
+    this.fogRenderer = renderer;
+    this.invalidateScene();
+  }
   requestDraw() {
     if (this.disposed || this.frameId !== null) return;
     this.frameId = this.requestFrame(this.draw);
@@ -5310,8 +5800,15 @@ var MinimapController = class {
   }
   currentMapping() {
     const viewportRect = this.viewport.getVisibleRect();
-    const content = getElementsBoundingBox(this.sceneElements());
-    return content ? unionBounds(content, viewportRect) : viewportRect;
+    let mapping = getElementsBoundingBox(this.sceneElements());
+    mapping = mapping ? unionBounds(mapping, viewportRect) : viewportRect;
+    if (this.fogRenderer?.isVisible()) {
+      const fogState = this.fogRenderer.getState();
+      if (fogState) {
+        mapping = unionBounds(mapping, fogState.definition.bounds);
+      }
+    }
+    return mapping;
   }
   onViewChanged() {
     if (this.disposed) return;
@@ -5369,6 +5866,23 @@ var MinimapController = class {
       ctx.drawImage(layerCanvas, 0, 0);
       ctx.restore();
     }
+    if (this.fogRenderer?.isVisible()) {
+      const fogState = this.fogRenderer.getState();
+      const fogMode = this.fogRenderer.getViewMode();
+      if (fogState && (fogMode === "editor" || fogMode === "player")) {
+        ctx.save();
+        ctx.setTransform(
+          dpr * transform.scale,
+          0,
+          0,
+          dpr * transform.scale,
+          dpr * transform.offsetX,
+          dpr * transform.offsetY
+        );
+        this.fogRenderer.renderForExport(ctx, fogState, fogMode);
+        ctx.restore();
+      }
+    }
     this.scene = { canvas: sceneCanvas, transform, mapping };
   }
   renderLayerElements(ctx, elements, t, dpr) {
@@ -5481,9 +5995,15 @@ var Minimap = class {
     this.canvas = canvas;
     this.controller = new MinimapController(viewport, canvas, { width: WIDTH, height: HEIGHT });
   }
+  setFogRenderer(renderer) {
+    this.controller.setFogRenderer(renderer);
+  }
   scheduleDraw() {
     this.controller.requestDraw();
   }
+  invalidateScene() {
+    this.controller.invalidateScene();
+  }
   destroy() {
     this.controller.dispose();
     this.canvas.remove();
@@ -6805,6 +7325,220 @@ async function renderHtmlElements(elements, options) {
   return sources;
 }
 
+// src/fog/fog-renderer.ts
+var DEFAULT_EDITOR_COLOR = "rgba(30, 40, 60, 0.45)";
+var DEFAULT_PLAYER_COLOR = "#0b1020";
+var FogRenderer = class {
+  tileCache = /* @__PURE__ */ new Map();
+  state = null;
+  viewMode = "off";
+  dirty = true;
+  editorColor;
+  playerColor;
+  constructor(options = {}) {
+    this.editorColor = options.editorColor ?? DEFAULT_EDITOR_COLOR;
+    this.playerColor = options.playerColor ?? DEFAULT_PLAYER_COLOR;
+  }
+  setState(state) {
+    this.state = state;
+    this.dirty = true;
+  }
+  setViewMode(mode) {
+    if (mode === this.viewMode) return;
+    this.viewMode = mode;
+    this.dirty = true;
+  }
+  getState() {
+    return this.state;
+  }
+  getViewMode() {
+    return this.viewMode;
+  }
+  markDirty() {
+    this.dirty = true;
+  }
+  isDirty() {
+    return this.dirty;
+  }
+  isVisible() {
+    return this.viewMode !== "off" && this.state !== null;
+  }
+  render(ctx, camera, viewportWidth, viewportHeight, _dpr) {
+    if (!this.state || this.viewMode === "off") return;
+    const def = this.state.definition;
+    const cellSize = def.cellSize;
+    const tileWorldSize = FOG_TILE_CELLS * cellSize;
+    const color = this.viewMode === "editor" ? this.editorColor : this.playerColor;
+    const worldBounds = getVisibleWorld(camera, viewportWidth, viewportHeight);
+    const minTX = Math.floor(Math.max(def.bounds.x, worldBounds.x) / tileWorldSize);
+    const minTY = Math.floor(Math.max(def.bounds.y, worldBounds.y) / tileWorldSize);
+    const maxTX = Math.floor(
+      Math.min(def.bounds.x + def.bounds.w - 1, worldBounds.x + worldBounds.w) / tileWorldSize
+    );
+    const maxTY = Math.floor(
+      Math.min(def.bounds.y + def.bounds.h - 1, worldBounds.y + worldBounds.h) / tileWorldSize
+    );
+    ctx.save();
+    ctx.translate(camera.position.x, camera.position.y);
+    ctx.scale(camera.zoom, camera.zoom);
+    const tileMap = /* @__PURE__ */ new Map();
+    for (const tile of this.state.tiles) {
+      tileMap.set(`${tile.x},${tile.y}`, tile.data);
+    }
+    const baseCovered = def.base === "covered";
+    for (let ty = minTY; ty <= maxTY; ty++) {
+      for (let tx = minTX; tx <= maxTX; tx++) {
+        const key = `${tx},${ty}`;
+        const data = tileMap.get(key);
+        const tileWorldX = tx * tileWorldSize;
+        const tileWorldY = ty * tileWorldSize;
+        if (!data && baseCovered) {
+          ctx.fillStyle = color;
+          const clipX = Math.max(tileWorldX, def.bounds.x);
+          const clipY = Math.max(tileWorldY, def.bounds.y);
+          const clipR = Math.min(tileWorldX + tileWorldSize, def.bounds.x + def.bounds.w);
+          const clipB = Math.min(tileWorldY + tileWorldSize, def.bounds.y + def.bounds.h);
+          if (clipR > clipX && clipB > clipY) {
+            ctx.fillRect(clipX, clipY, clipR - clipX, clipB - clipY);
+          }
+          continue;
+        }
+        if (!data && !baseCovered) {
+          continue;
+        }
+        if (data) {
+          this.renderTile(ctx, data, tx, ty, def, color);
+        }
+      }
+    }
+    ctx.restore();
+    this.dirty = false;
+  }
+  renderForExport(ctx, state, mode, color) {
+    const def = state.definition;
+    const cellSize = def.cellSize;
+    const tileWorldSize = FOG_TILE_CELLS * cellSize;
+    const fogColor = color ?? (mode === "editor" ? this.editorColor : this.playerColor);
+    const baseCovered = def.base === "covered";
+    const tileMap = /* @__PURE__ */ new Map();
+    for (const tile of state.tiles) {
+      tileMap.set(`${tile.x},${tile.y}`, tile.data);
+    }
+    const minTX = Math.floor(def.bounds.x / tileWorldSize);
+    const minTY = Math.floor(def.bounds.y / tileWorldSize);
+    const maxTX = Math.floor((def.bounds.x + def.bounds.w - 1) / tileWorldSize);
+    const maxTY = Math.floor((def.bounds.y + def.bounds.h - 1) / tileWorldSize);
+    for (let ty = minTY; ty <= maxTY; ty++) {
+      for (let tx = minTX; tx <= maxTX; tx++) {
+        const key = `${tx},${ty}`;
+        const data = tileMap.get(key);
+        const tileWorldX = tx * tileWorldSize;
+        const tileWorldY = ty * tileWorldSize;
+        if (!data && baseCovered) {
+          ctx.fillStyle = fogColor;
+          const clipX = Math.max(tileWorldX, def.bounds.x);
+          const clipY = Math.max(tileWorldY, def.bounds.y);
+          const clipR = Math.min(tileWorldX + tileWorldSize, def.bounds.x + def.bounds.w);
+          const clipB = Math.min(tileWorldY + tileWorldSize, def.bounds.y + def.bounds.h);
+          if (clipR > clipX && clipB > clipY) {
+            ctx.fillRect(clipX, clipY, clipR - clipX, clipB - clipY);
+          }
+          continue;
+        }
+        if (data) {
+          this.renderTileForExport(ctx, data, tx, ty, def, fogColor);
+        }
+      }
+    }
+  }
+  dispose() {
+    this.tileCache.clear();
+    this.state = null;
+  }
+  tileRaster(data, color) {
+    const key = `${color}\0${data}`;
+    const cached = this.tileCache.get(key);
+    if (cached) return cached;
+    if (typeof document === "undefined") return null;
+    const canvas = document.createElement("canvas");
+    canvas.width = FOG_TILE_CELLS;
+    canvas.height = FOG_TILE_CELLS;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return null;
+    const bytes = decodeBase64(data);
+    ctx.fillStyle = color;
+    for (let row = 0; row < FOG_TILE_CELLS; row++) {
+      for (let col = 0; col < FOG_TILE_CELLS; col++) {
+        const index = row * FOG_TILE_CELLS + col;
+        const byteIndex = index >> 3;
+        const bitIndex = 7 - (index & 7);
+        const revealed = (bytes[byteIndex] >> bitIndex & 1) === 1;
+        if (!revealed) ctx.fillRect(col, row, 1, 1);
+      }
+    }
+    if (this.tileCache.size >= 256) {
+      const oldest = this.tileCache.keys().next().value;
+      if (oldest !== void 0) this.tileCache.delete(oldest);
+    }
+    this.tileCache.set(key, canvas);
+    return canvas;
+  }
+  renderTile(ctx, data, tx, ty, def, color) {
+    const cellSize = def.cellSize;
+    const tileWorldX = tx * FOG_TILE_CELLS * cellSize;
+    const tileWorldY = ty * FOG_TILE_CELLS * cellSize;
+    const raster = this.tileRaster(data, color);
+    if (raster) {
+      ctx.save();
+      ctx.beginPath();
+      ctx.rect(def.bounds.x, def.bounds.y, def.bounds.w, def.bounds.h);
+      ctx.clip();
+      ctx.imageSmoothingEnabled = false;
+      ctx.drawImage(
+        raster,
+        tileWorldX,
+        tileWorldY,
+        FOG_TILE_CELLS * cellSize,
+        FOG_TILE_CELLS * cellSize
+      );
+      ctx.restore();
+      return;
+    }
+    const bytes = decodeBase64(data);
+    ctx.fillStyle = color;
+    for (let row = 0; row < FOG_TILE_CELLS; row++) {
+      for (let col = 0; col < FOG_TILE_CELLS; col++) {
+        const cellWorldX = tileWorldX + col * cellSize;
+        const cellWorldY = tileWorldY + row * cellSize;
+        if (cellWorldX < def.bounds.x || cellWorldY < def.bounds.y || cellWorldX >= def.bounds.x + def.bounds.w || cellWorldY >= def.bounds.y + def.bounds.h) {
+          continue;
+        }
+        const index = row * FOG_TILE_CELLS + col;
+        const byteIndex = index >> 3;
+        const bitIndex = 7 - (index & 7);
+        const revealed = (bytes[byteIndex] >> bitIndex & 1) === 1;
+        const covered = !revealed;
+        if (covered) {
+          ctx.fillRect(cellWorldX, cellWorldY, cellSize, cellSize);
+        }
+      }
+    }
+  }
+  renderTileForExport(ctx, data, tx, ty, def, color) {
+    this.renderTile(ctx, data, tx, ty, def, color);
+  }
+};
+function getVisibleWorld(camera, viewportWidth, viewportHeight) {
+  const topLeft = camera.screenToWorld({ x: 0, y: 0 });
+  const bottomRight = camera.screenToWorld({ x: viewportWidth, y: viewportHeight });
+  return {
+    x: topLeft.x,
+    y: topLeft.y,
+    w: bottomRight.x - topLeft.x,
+    h: bottomRight.y - topLeft.y
+  };
+}
+
 // src/canvas/export-image.ts
 var DEFAULT_IMAGE_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_DIMENSION = 16384;
@@ -7217,6 +7951,10 @@ async function exportImage(store, options = {}, layerManager) {
     renderGridForBounds(ctx, grid, bounds);
     ctx.restore();
   }
+  if (options.fog) {
+    const fogRenderer = new FogRenderer();
+    fogRenderer.renderForExport(ctx, options.fog.state, options.fog.mode, options.fog.color);
+  }
   const mimeType = format === "jpeg" ? "image/jpeg" : "image/png";
   return new Promise((resolve) => {
     canvas.toBlob((blob) => resolve(blob), mimeType, options.quality);
@@ -7598,6 +8336,27 @@ async function exportSvg(store, options = {}, layerManager) {
     const opacity = layerManager?.getLayer?.(grid.layerId)?.opacity ?? 1;
     body += opacity === 1 ? emitted : `<g opacity="${n(opacity)}">${emitted}</g>`;
   }
+  if (options.fog && typeof document !== "undefined") {
+    const fogState = options.fog.state;
+    const fogW = Math.max(1, Math.ceil(bounds.w));
+    const fogH = Math.max(1, Math.ceil(bounds.h));
+    const fogCanvas = document.createElement("canvas");
+    fogCanvas.width = fogW;
+    fogCanvas.height = fogH;
+    const fogCtx = fogCanvas.getContext("2d");
+    if (fogCtx) {
+      fogCtx.translate(-bounds.x, -bounds.y);
+      const fogRenderer = new FogRenderer();
+      fogRenderer.renderForExport(fogCtx, fogState, options.fog.mode, options.fog.color);
+      try {
+        const fogDataUri = fogCanvas.toDataURL("image/png");
+        if (fogDataUri.startsWith("data:")) {
+          body += `<image href="${esc(fogDataUri)}" x="${n(bounds.x)}" y="${n(bounds.y)}" width="${n(bounds.w)}" height="${n(bounds.h)}" />`;
+        }
+      } catch {
+      }
+    }
+  }
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${n(bounds.w)}" height="${n(bounds.h)}" viewBox="${n(bounds.x)} ${n(bounds.y)} ${n(bounds.w)} ${n(bounds.h)}">${body}</svg>`;
 }
 function emitElement(el, imageDataUris, htmlDataUris, rasterScale, firstGrid, store, resourceOptions) {
@@ -8435,6 +9194,7 @@ var RenderLoop = class {
   layerCache;
   marginViewport;
   hybridSurface;
+  fogRenderer;
   activeDrawingLayerId = null;
   gridCacheDirty = true;
   // set on recenter/viewport-change; consumed by the grid block
@@ -8458,6 +9218,7 @@ var RenderLoop = class {
     this.layerCache = deps.layerCache;
     this.marginViewport = deps.marginViewport;
     this.hybridSurface = deps.hybridSurface;
+    this.fogRenderer = deps.fogRenderer;
   }
   requestRender() {
     this.needsRender = true;
@@ -8767,9 +9528,12 @@ var RenderLoop = class {
       group.push(element);
     }
     const activeTool = this.toolManager.activeTool;
-    const overlayOrder = visibleElements.length + 1;
+    const fogVisible = this.fogRenderer?.isVisible() ?? false;
+    const fogOrder = visibleElements.length + 1;
+    const overlayOrder = fogVisible ? fogOrder + 1 : visibleElements.length + 1;
     const hasOverlay = activeTool?.renderOverlay !== void 0 || this.overlays.size > 0;
-    if (hybridActive && hasOverlay) hybridOrders.add(overlayOrder);
+    if (fogVisible) hybridOrders.add(fogOrder);
+    if (hasOverlay && (hybridActive || fogVisible)) hybridOrders.add(overlayOrder);
     this.hybridSurface.beginFrame(hybridOrders, this.canvasEl.width, this.canvasEl.height);
     for (const [layerId, elements] of this.layerGroups) {
       const isActiveDrawingLayer = layerId === this.activeDrawingLayerId;
@@ -8883,8 +9647,18 @@ var RenderLoop = class {
       }
       hybridCtx.restore();
     }
+    if (fogVisible && this.fogRenderer) {
+      const fogCtx = this.hybridSurface.getContext(fogOrder);
+      if (fogCtx) {
+        fogCtx.clearRect(0, 0, this.canvasEl.width, this.canvasEl.height);
+        fogCtx.save();
+        fogCtx.scale(dpr, dpr);
+        this.fogRenderer.render(fogCtx, this.camera, cssWidth, cssHeight, dpr);
+        fogCtx.restore();
+      }
+    }
     const overlayT0 = performance.now();
-    if (hybridActive && hasOverlay) {
+    if ((hybridActive || fogVisible) && hasOverlay) {
       const overlayCtx = this.hybridSurface.getContext(overlayOrder);
       if (overlayCtx) {
         overlayCtx.clearRect(0, 0, this.canvasEl.width, this.canvasEl.height);
@@ -9895,6 +10669,248 @@ var ElementActivation = class {
   }
 };
 
+// src/fog/fog-command.ts
+var FogRegionCommand = class {
+  constructor(manager, before, after) {
+    this.manager = manager;
+    this.before = before;
+    this.after = after;
+  }
+  execute(_store) {
+    this.manager.applyTilesDirect(this.after);
+  }
+  undo(_store) {
+    this.manager.applyTilesDirect(this.before);
+  }
+};
+var FogResetCommand = class {
+  constructor(manager, before, after) {
+    this.manager = manager;
+    this.before = before;
+    this.after = after;
+  }
+  execute(_store) {
+    this.manager.restoreHistoryState(this.after);
+  }
+  undo(_store) {
+    this.manager.restoreHistoryState(this.before);
+  }
+};
+
+// src/fog/fog-manager.ts
+function defaultIdFactory() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `fog-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+var FogManager = class {
+  state = null;
+  viewMode = "off";
+  idFactory;
+  onCommand;
+  changeListeners = /* @__PURE__ */ new Set();
+  viewListeners = /* @__PURE__ */ new Set();
+  constructor(options = {}) {
+    this.idFactory = options.idFactory ?? defaultIdFactory;
+    this.onCommand = options.onCommand;
+  }
+  getState() {
+    if (!this.state) return null;
+    return {
+      definition: { ...this.state.definition, bounds: { ...this.state.definition.bounds } },
+      tiles: this.state.tiles.map((t) => ({ ...t }))
+    };
+  }
+  getViewMode() {
+    return this.viewMode;
+  }
+  initialize(options) {
+    const base = options.base ?? "covered";
+    const cellSize = options.cellSize ?? recommendedFogCellSize(options.bounds);
+    const generation = this.idFactory();
+    const newState = {
+      definition: {
+        version: 1,
+        generation,
+        bounds: { ...options.bounds },
+        cellSize,
+        tileCells: FOG_TILE_CELLS,
+        base
+      },
+      tiles: []
+    };
+    validateFogState(newState);
+    const before = this.state;
+    this.state = newState;
+    const command = new FogResetCommand(this, before, newState);
+    this.onCommand?.(command);
+    this.notifyChange({ kind: "definition" });
+    return structuredClone(newState);
+  }
+  loadState(state, meta) {
+    if (state !== null) {
+      validateFogState(state);
+      this.state = structuredClone(state);
+    } else {
+      this.state = null;
+    }
+    this.notifyChange({
+      kind: state === null ? "disable" : "definition",
+      origin: meta?.origin
+    });
+  }
+  /** Restores a historical visual state without reusing its causal generation id. */
+  restoreHistoryState(state) {
+    if (state === null) {
+      this.loadState(null);
+      return;
+    }
+    this.loadState({
+      definition: { ...state.definition, generation: this.idFactory() },
+      tiles: state.tiles
+    });
+  }
+  setBounds(bounds) {
+    if (!this.state) return;
+    const def = this.state.definition;
+    validateFogState({
+      definition: { ...def, bounds: { ...bounds } },
+      tiles: []
+    });
+    const shrinks = bounds.x > def.bounds.x || bounds.y > def.bounds.y || bounds.x + bounds.w < def.bounds.x + def.bounds.w || bounds.y + bounds.h < def.bounds.y + def.bounds.h;
+    const nextDefinition = {
+      ...def,
+      bounds: { ...bounds },
+      generation: shrinks ? this.idFactory() : def.generation
+    };
+    const tiles = this.state.tiles.flatMap((tile) => {
+      const tileWorldX = tile.x * FOG_TILE_CELLS * def.cellSize;
+      const tileWorldY = tile.y * FOG_TILE_CELLS * def.cellSize;
+      const tileWorldW = FOG_TILE_CELLS * def.cellSize;
+      const tileWorldH = FOG_TILE_CELLS * def.cellSize;
+      const intersects2 = !(tileWorldX + tileWorldW <= bounds.x || tileWorldY + tileWorldH <= bounds.y || tileWorldX >= bounds.x + bounds.w || tileWorldY >= bounds.y + bounds.h);
+      if (!intersects2) return [];
+      const canonical = canonicalizeFogTile(tile, nextDefinition);
+      return canonical ? [canonical] : [];
+    });
+    const before = this.state;
+    this.state = {
+      definition: nextDefinition,
+      tiles
+    };
+    const command = new FogResetCommand(this, before, this.state);
+    this.onCommand?.(command);
+    this.notifyChange({ kind: "definition" });
+  }
+  reset(base) {
+    if (!this.state) return;
+    const before = this.state;
+    const generation = this.idFactory();
+    this.state = {
+      definition: { ...this.state.definition, base, generation },
+      tiles: []
+    };
+    const command = new FogResetCommand(this, before, this.state);
+    this.onCommand?.(command);
+    this.notifyChange({ kind: "reset" });
+  }
+  disable() {
+    if (!this.state) return;
+    const before = this.state;
+    this.state = null;
+    const command = new FogResetCommand(this, before, null);
+    this.onCommand?.(command);
+    this.notifyChange({ kind: "disable" });
+  }
+  setViewMode(mode) {
+    if (mode === this.viewMode) return;
+    this.viewMode = mode;
+    this.notifyView({ mode });
+  }
+  applyRegion(region, operation) {
+    if (!this.state) return;
+    const result = rasterizeRegion(this.state, region, operation);
+    if (result.noop) return;
+    const before = this.collectTiles(result.changed);
+    const newState = applyRasterResult(this.state, result);
+    this.state = newState;
+    const command = new FogRegionCommand(this, before, result.changed);
+    this.onCommand?.(command);
+    this.notifyChange({
+      kind: "tiles",
+      tiles: result.changed.map((t) => ({ x: t.x, y: t.y }))
+    });
+  }
+  applyPatchDirect(patch, meta) {
+    if (!this.state) return;
+    const result = applyRasterResult(this.state, { changed: patch.tiles, noop: false });
+    this.state = result;
+    this.notifyChange({
+      kind: "tiles",
+      tiles: patch.tiles.map((t) => ({ x: t.x, y: t.y })),
+      origin: meta?.origin
+    });
+  }
+  applyTilesDirect(tiles) {
+    if (!this.state) return;
+    const result = applyRasterResult(this.state, { changed: tiles, noop: false });
+    this.state = result;
+    this.notifyChange({
+      kind: "tiles",
+      tiles: tiles.map((t) => ({ x: t.x, y: t.y }))
+    });
+  }
+  on(event, listener) {
+    if (event === "change") {
+      const l2 = listener;
+      this.changeListeners.add(l2);
+      return () => this.changeListeners.delete(l2);
+    }
+    const l = listener;
+    this.viewListeners.add(l);
+    return () => this.viewListeners.delete(l);
+  }
+  dispose() {
+    this.changeListeners.clear();
+    this.viewListeners.clear();
+  }
+  collectTiles(changed) {
+    if (!this.state) return [];
+    const result = [];
+    for (const c of changed) {
+      const existing = this.state.tiles.find((t) => t.x === c.x && t.y === c.y);
+      if (existing) {
+        result.push(existing);
+      } else {
+        const baseVal = this.state.definition.base === "revealed";
+        result.push({
+          x: c.x,
+          y: c.y,
+          data: encodeBase64(createTileBytes(baseVal))
+        });
+      }
+    }
+    return result;
+  }
+  notifyChange(event) {
+    for (const listener of this.changeListeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  notifyView(event) {
+    for (const listener of this.viewListeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+};
+
 // src/canvas/viewport.ts
 var EMPTY_IDS = [];
 function noop2() {
@@ -10021,8 +11037,13 @@ var Viewport = class _Viewport {
       });
     }
     this.unsubToolChange = this.toolManager.onChange(() => this.contextMenu?.close());
+    this.fogManager = new FogManager({
+      onCommand: (cmd) => this.history.push(cmd)
+    });
+    this.fogRenderer = new FogRenderer(options.fog);
     if (options.minimap) {
       this.minimap = new Minimap(this.wrapper, this);
+      this.minimap.setFogRenderer(this.fogRenderer);
     }
     this.domNodeManager = new DomNodeManager({
       domLayer: this.paintStack,
@@ -10052,7 +11073,18 @@ var Viewport = class _Viewport {
       domNodeManager: this.domNodeManager,
       layerCache,
       marginViewport: this.marginViewport,
-      hybridSurface: new HybridRenderSurface(this.paintStack)
+      hybridSurface: new HybridRenderSurface(this.paintStack),
+      fogRenderer: this.fogRenderer
+    });
+    this.fogManager.on("change", () => {
+      this.fogRenderer.setState(this.fogManager.getState());
+      this.renderLoop.requestRender();
+      this.minimap?.invalidateScene();
+    });
+    this.fogManager.on("view", () => {
+      this.fogRenderer.setViewMode(this.fogManager.getViewMode());
+      this.renderLoop.requestRender();
+      this.minimap?.invalidateScene();
     });
     this.unsubHtmlPainters = this.htmlPainters.onChange(() => this.onHtmlRegistryChanged());
     this.unsubCamera = this.camera.onChange(() => {
@@ -10164,6 +11196,8 @@ var Viewport = class _Viewport {
   _smartGuides = false;
   _gridSize;
   renderLoop;
+  fogManager;
+  fogRenderer;
   domNodeManager;
   interactMode;
   onHtmlElementMount;
@@ -10199,6 +11233,9 @@ var Viewport = class _Viewport {
   get ctx() {
     return this.canvasEl.getContext("2d");
   }
+  get fog() {
+    return this.fogManager;
+  }
   get snapToGrid() {
     return this._snapToGrid;
   }
@@ -10283,7 +11320,8 @@ var Viewport = class _Viewport {
       this.store.snapshot(),
       this.camera,
       this.layerManager.snapshot(),
-      this.layerManager.activeLayerId
+      this.layerManager.activeLayerId,
+      this.fogManager.getState()
     );
   }
   exportJSON() {
@@ -10305,12 +11343,31 @@ var Viewport = class _Viewport {
     return { ...base, htmlPainters: registry, expectedCanvasTypes: expected };
   }
   async exportImage(options) {
-    return exportImage(this.store, this.withHtmlDefaults(options), this.layerManager);
+    const opts = this.withHtmlDefaults(options);
+    if (opts.fog === void 0 && this.fogRenderer.isVisible()) {
+      const state = this.fogManager.getState();
+      if (state) {
+        const mode = this.fogRenderer.getViewMode();
+        opts.fog = { state, mode };
+      }
+    }
+    return exportImage(this.store, opts, this.layerManager);
   }
   async exportSVG(options) {
-    return exportSvg(this.store, this.withHtmlDefaults(options), this.layerManager);
+    const opts = this.withHtmlDefaults(options);
+    if (opts.fog === void 0 && this.fogRenderer.isVisible()) {
+      const state = this.fogManager.getState();
+      if (state) {
+        const mode = this.fogRenderer.getViewMode();
+        opts.fog = { state, mode };
+      }
+    }
+    return exportSvg(this.store, opts, this.layerManager);
   }
   loadState(state) {
+    if (state.fog != null) {
+      validateFogState(state.fog);
+    }
     this.inputHandler.flushPendingHistory();
     this.historyRecorder.pause();
     this.noteEditor.destroy(this.store);
@@ -10345,6 +11402,7 @@ var Viewport = class _Viewport {
         }
       }
     }
+    this.fogManager.loadState(state.fog ?? null);
     this.history.clear();
     this.historyRecorder.resume();
     this.camera.moveTo(state.camera.position.x, state.camera.position.y);
@@ -10756,6 +11814,8 @@ var Viewport = class _Viewport {
     this.unsubToolRegister();
     this.unsubRecorderEnd();
     this.unsubHtmlPainters();
+    this.fogManager.dispose();
+    this.fogRenderer.dispose();
     this.activation?.dispose();
     this.activation = null;
     this.activationListeners.clear();
@@ -15597,8 +16657,188 @@ var PingTool = class {
   }
 };
 
+// src/tools/fog-tool.ts
+var DEFAULT_RADIUS5 = 40;
+var MIN_POINT_DISTANCE = 4;
+var FogTool = class {
+  name = "fog";
+  drawing = false;
+  points = [];
+  startPoint = null;
+  operation;
+  shape;
+  radius;
+  manager;
+  optionListeners = /* @__PURE__ */ new Set();
+  constructor(manager, options = {}) {
+    this.manager = manager;
+    this.operation = options.operation ?? "reveal";
+    this.shape = options.shape ?? "brush";
+    this.radius = options.radius ?? DEFAULT_RADIUS5;
+  }
+  onActivate(ctx) {
+    ctx.setCursor?.("crosshair");
+  }
+  onDeactivate(ctx) {
+    this.cancelGesture(ctx);
+    ctx.setCursor?.("default");
+  }
+  getOptions() {
+    return {
+      operation: this.operation,
+      shape: this.shape,
+      radius: this.radius
+    };
+  }
+  setOptions(options) {
+    if (options.operation !== void 0) this.operation = options.operation;
+    if (options.shape !== void 0) this.shape = options.shape;
+    if (options.radius !== void 0 && Number.isFinite(options.radius) && options.radius > 0) {
+      this.radius = options.radius;
+    }
+    for (const listener of this.optionListeners) listener();
+  }
+  onOptionsChange(listener) {
+    this.optionListeners.add(listener);
+    return () => this.optionListeners.delete(listener);
+  }
+  onPointerDown(state, ctx) {
+    if (this.drawing) return;
+    this.drawing = true;
+    const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
+    this.startPoint = world;
+    this.points = [world];
+    ctx.requestRender();
+  }
+  onPointerMove(state, ctx) {
+    if (!this.drawing) return;
+    const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
+    if (this.shape === "rectangle") {
+      if (this.startPoint) this.points = [this.startPoint, world];
+    } else {
+      const last = this.points[this.points.length - 1];
+      if (last) {
+        const dx = world.x - last.x;
+        const dy = world.y - last.y;
+        if (dx * dx + dy * dy < MIN_POINT_DISTANCE * MIN_POINT_DISTANCE) return;
+      }
+      this.points.push(world);
+    }
+    ctx.requestRender();
+  }
+  onPointerUp(_state, ctx) {
+    if (!this.drawing) return;
+    this.drawing = false;
+    const region = this.buildRegion();
+    if (region) {
+      this.manager.applyRegion(region, this.operation);
+    }
+    this.points = [];
+    this.startPoint = null;
+    ctx.requestRender();
+  }
+  onPointerCancel(_state, ctx) {
+    this.cancelGesture(ctx);
+  }
+  onKeyDown(event, ctx) {
+    if (event.key === "Escape" && this.drawing) {
+      this.cancelGesture(ctx);
+      return true;
+    }
+    return false;
+  }
+  renderOverlay(ctx) {
+    if (!this.drawing || this.points.length === 0) return;
+    ctx.save();
+    ctx.strokeStyle = this.operation === "reveal" ? "rgba(255,255,255,0.6)" : "rgba(0,0,0,0.4)";
+    ctx.fillStyle = this.operation === "reveal" ? "rgba(255,255,255,0.15)" : "rgba(0,0,0,0.1)";
+    ctx.lineWidth = 2;
+    ctx.setLineDash([6, 4]);
+    switch (this.shape) {
+      case "brush":
+        this.renderBrushPreview(ctx);
+        break;
+      case "rectangle":
+        this.renderRectanglePreview(ctx);
+        break;
+      case "polygon":
+        this.renderPolygonPreview(ctx);
+        break;
+    }
+    ctx.restore();
+  }
+  buildRegion() {
+    switch (this.shape) {
+      case "brush": {
+        if (this.points.length === 0) return null;
+        return { kind: "brush", points: this.points, radius: this.radius };
+      }
+      case "rectangle": {
+        if (!this.startPoint || this.points.length < 2) return null;
+        const end = this.points[this.points.length - 1];
+        if (this.startPoint.x === end.x && this.startPoint.y === end.y) return null;
+        return { kind: "rectangle", from: this.startPoint, to: end };
+      }
+      case "polygon": {
+        if (this.points.length < 3) return null;
+        return { kind: "polygon", points: this.points };
+      }
+    }
+  }
+  cancelGesture(ctx) {
+    this.drawing = false;
+    this.points = [];
+    this.startPoint = null;
+    ctx.requestRender();
+  }
+  renderBrushPreview(ctx) {
+    if (this.points.length === 1) {
+      const p = this.points[0];
+      ctx.beginPath();
+      ctx.arc(p.x, p.y, this.radius, 0, Math.PI * 2);
+      ctx.fill();
+      ctx.stroke();
+      return;
+    }
+    ctx.beginPath();
+    for (let i = 0; i < this.points.length; i++) {
+      const p = this.points[i];
+      if (i === 0) ctx.moveTo(p.x, p.y);
+      else ctx.lineTo(p.x, p.y);
+    }
+    ctx.lineWidth = this.radius * 2;
+    ctx.lineCap = "round";
+    ctx.lineJoin = "round";
+    ctx.stroke();
+  }
+  renderRectanglePreview(ctx) {
+    if (this.points.length < 2) return;
+    const from = this.points[0];
+    const to = this.points[this.points.length - 1];
+    const x = Math.min(from.x, to.x);
+    const y = Math.min(from.y, to.y);
+    const w = Math.abs(to.x - from.x);
+    const h = Math.abs(to.y - from.y);
+    ctx.fillRect(x, y, w, h);
+    ctx.strokeRect(x, y, w, h);
+  }
+  renderPolygonPreview(ctx) {
+    if (this.points.length < 2) return;
+    const first = this.points[0];
+    ctx.beginPath();
+    ctx.moveTo(first.x, first.y);
+    for (let i = 1; i < this.points.length; i++) {
+      const p = this.points[i];
+      ctx.lineTo(p.x, p.y);
+    }
+    ctx.closePath();
+    ctx.fill();
+    ctx.stroke();
+  }
+};
+
 // src/index.ts
-var VERSION = "0.65.0";
+var VERSION = "0.66.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AWARENESS_MAX_SELECTION,
@@ -15612,6 +16852,12 @@ var VERSION = "0.65.0";
   ElementStore,
   EraserTool,
   FOCUS_PRESENCE_KIND,
+  FOG_MAX_TILES,
+  FOG_STATE_VERSION,
+  FOG_TILE_CELLS,
+  FogManager,
+  FogRenderer,
+  FogTool,
   HandTool,
   HistoryStack,
   HtmlPainterMissingError,
@@ -15655,6 +16901,7 @@ var VERSION = "0.65.0";
   attachAwareness,
   boundsIntersect,
   cameraOriginForView,
+  canonicalizeFogTile,
   captureCameraView,
   computeElementRects,
   createArrow,
@@ -15672,6 +16919,8 @@ var VERSION = "0.65.0";
   exportImage,
   exportSvg,
   fitZoomForView,
+  fogDecodeBase64,
+  fogEncodeBase64,
   footprintFromSize,
   getActiveFormats,
   getArrowBounds,
@@ -15697,6 +16946,7 @@ var VERSION = "0.65.0";
   isPathPresence,
   isPingPresence,
   pathDistanceCells,
+  recommendedFogCellSize,
   resolveHtmlRouting,
   setFontSize,
   smartSnap,
@@ -15713,6 +16963,9 @@ var VERSION = "0.65.0";
   toggleBold,
   toggleItalic,
   toggleStrikethrough,
-  toggleUnderline
+  toggleUnderline,
+  validateFogDefinition,
+  validateFogState,
+  validateFogTile
 });
 //# sourceMappingURL=index.cjs.map