@ifc-lite/viewer 1.25.1 → 1.26.0

package/src/hooks/useSymbolicAnnotations.ts

@@ -91,13 +91,31 @@ export interface AnnotationFill2D {
   };
 }
 
-/** Cached parse result keyed by source identity. */
+/** Cached parse result keyed by source identity.
+ *
+ * IfcAnnotation and IfcGridAxis primitives are stored in PARALLEL bucket
+ * collections (issue #862). They share the same parse pass and the same
+ * storey-resolution logic, but the renderer treats them differently:
+ *
+ *   - Annotation buckets always lift every storey (memory
+ *     `feedback_3d_annotation_overlay_no_section_filter.md`: the user
+ *     expects every storey's dimensions to be visible in 3D).
+ *   - Grid buckets get optional section-plane filtering and an
+ *     independent visibility toggle, so dense-grid models can hide
+ *     grids per storey without losing dimensions.
+ */
 interface ParseResult {
+  // IfcAnnotation buckets
   byStorey: Map<number, AnnotationsForStorey>;
-  /** Annotations with no resolvable storey — shown on every floor as a fallback. */
   loose: DrawingLine2D[];
   looseTexts: AnnotationText2D[];
   looseFills: AnnotationFill2D[];
+
+  // IfcGridAxis buckets (issue #862)
+  gridByStorey: Map<number, AnnotationsForStorey>;
+  gridLoose: DrawingLine2D[];
+  gridLooseTexts: AnnotationText2D[];
+  gridLooseFills: AnnotationFill2D[];
 }
 
 const CIRCLE_SEGMENTS_FULL = 32;
@@ -212,6 +230,10 @@ async function parseAnnotations(
     loose: [],
     looseTexts: [],
     looseFills: [],
+    gridByStorey: new Map(),
+    gridLoose: [],
+    gridLooseTexts: [],
+    gridLooseFills: [],
   };
   const source = store.source;
   if (!source || source.byteLength === 0) {
@@ -256,6 +278,7 @@ async function parseAnnotations(
     const ensureBucket = (
       expressId: number,
       primitiveWorldY: number,
+      ifcType: string,
     ): AnnotationsForStorey | null => {
       let effectiveY: number | null = null;
       if (Number.isFinite(primitiveWorldY) && primitiveWorldY !== 0) {
@@ -269,7 +292,11 @@ async function parseAnnotations(
       }
       if (effectiveY === null) return null;
       const key = Math.round(effectiveY * 1000);
-      let bucket = result.byStorey.get(key);
+      // Issue #862: IfcGridAxis primitives land in a parallel bucket
+      // collection so the renderer can section-clip + visibility-toggle
+      // them independently of IfcAnnotation (text/dimension symbols).
+      const storeyMap = ifcType === 'IfcGridAxis' ? result.gridByStorey : result.byStorey;
+      let bucket = storeyMap.get(key);
       if (!bucket) {
         bucket = {
           storeyId: key,
@@ -278,7 +305,7 @@ async function parseAnnotations(
           texts: [],
           fills: [],
         };
-        result.byStorey.set(key, bucket);
+        storeyMap.set(key, bucket);
       }
       return bucket;
     };
@@ -287,8 +314,9 @@ async function parseAnnotations(
       const poly = collection.getPolyline(i);
       if (!poly) continue;
       if (poly.ifcType !== 'IfcAnnotation' && poly.ifcType !== 'IfcGridAxis') continue;
-      const bucket = ensureBucket(poly.expressId, poly.worldY);
-      const out = bucket ? bucket.lines : result.loose;
+      const bucket = ensureBucket(poly.expressId, poly.worldY, poly.ifcType);
+      const looseTarget = poly.ifcType === 'IfcGridAxis' ? result.gridLoose : result.loose;
+      const out = bucket ? bucket.lines : looseTarget;
       polylineToSegments(poly.points, poly.pointCount, poly.isClosed, out);
     }
 
@@ -296,8 +324,9 @@ async function parseAnnotations(
       const circle = collection.getCircle(i);
       if (!circle) continue;
       if (circle.ifcType !== 'IfcAnnotation' && circle.ifcType !== 'IfcGridAxis') continue;
-      const bucket = ensureBucket(circle.expressId, circle.worldY);
-      const out = bucket ? bucket.lines : result.loose;
+      const bucket = ensureBucket(circle.expressId, circle.worldY, circle.ifcType);
+      const looseTarget = circle.ifcType === 'IfcGridAxis' ? result.gridLoose : result.loose;
+      const out = bucket ? bucket.lines : looseTarget;
       circleToSegments(
         circle.centerX,
         circle.centerY,
@@ -335,7 +364,8 @@ async function parseAnnotations(
       // Industry-standard line-spacing (CSS line-height ≈ 1.2). Picks up
       // a little air between rows so descenders don't kiss the next cap.
       const lineSpacing = perLineHeight * 1.2;
-      const bucket = ensureBucket(text.expressId, text.worldY);
+      const bucket = ensureBucket(text.expressId, text.worldY, text.ifcType);
+      const looseTextTarget = text.ifcType === 'IfcGridAxis' ? result.gridLooseTexts : result.looseTexts;
       // All annotation text — grid bubbles, dimension callouts, leader labels —
       // billboards to the camera so it stays legible in any view orientation
       // (top-down, eye-level, oblique). The shader rebuilds the quad in the
@@ -366,7 +396,7 @@ async function parseAnnotations(
           color: textColor,
           targetPx,
         };
-        (bucket ? bucket.texts : result.looseTexts).push(t2d);
+        (bucket ? bucket.texts : looseTextTarget).push(t2d);
       }
     }
 
@@ -389,8 +419,9 @@ async function parseAnnotations(
             }
           : undefined,
       };
-      const bucket = ensureBucket(fill.expressId, fill.worldY);
-      (bucket ? bucket.fills : result.looseFills).push(f2d);
+      const bucket = ensureBucket(fill.expressId, fill.worldY, fill.ifcType);
+      const looseFillTarget = fill.ifcType === 'IfcGridAxis' ? result.gridLooseFills : result.looseFills;
+      (bucket ? bucket.fills : looseFillTarget).push(f2d);
     }
   } finally {
     processor.dispose();
@@ -521,17 +552,48 @@ function resolveBucketY(elevation: number | null, fallbackY: number): number {
   return elevation === null ? fallbackY : elevation;
 }
 
+/** Section-clip parameters for grid lines (issue #862). Grids ARE clipped
+ *  by the active section plane; IfcAnnotation overlays are NOT (per the
+ *  feedback_3d_annotation_overlay_no_section_filter memory). When
+ *  `enabled === false` no clipping happens — grids lift to every storey
+ *  same as annotations.
+ */
+export interface SectionClipForGrid {
+  enabled: boolean;
+  /** World coord on the cut axis (e.g. world-Y for axis='down'). */
+  posWorld: number;
+  /** Half-thickness of the visible band around the cut, world units. */
+  viewDepth: number;
+  /** Cut axis. Only `'down'` performs vertical clipping; other axes pass through unfiltered (grid lines are vertical and don't project meaningfully onto elevation cuts). */
+  axis: 'down' | 'front' | 'side';
+}
+
 export function useSymbolicAnnotations(params: {
+  /** Enable IfcAnnotation lift (the existing default behaviour). */
   enabled: boolean;
+  /**
+   * Enable IfcGrid lift. Independent of `enabled` so a user can hide
+   * annotations while keeping grids, or vice versa (issue #862).
+   * Defaults to `enabled` so existing call sites that don't set it
+   * keep the legacy combined behaviour.
+   */
+  gridEnabled?: boolean;
+  /** Section clipping for grids only — see [`SectionClipForGrid`]. */
+  gridSectionClip?: SectionClipForGrid;
   /** World Y to use for annotations with no resolvable storey. Defaults to 0. */
   fallbackY?: number;
 }): Float32Array {
-  const { enabled, fallbackY = 0 } = params;
+  const { enabled, gridEnabled, gridSectionClip, fallbackY = 0 } = params;
+  const effectiveGridEnabled = gridEnabled ?? enabled;
   const stores = useActiveStores();
-  const version = useAnnotationParseTrigger(enabled, stores);
+  // Trigger parse if EITHER subset is enabled — the parse pass is shared.
+  const version = useAnnotationParseTrigger(enabled || effectiveGridEnabled, stores);
+  const clipEnabled = !!gridSectionClip && gridSectionClip.enabled && gridSectionClip.axis === 'down';
+  const clipPos = clipEnabled ? gridSectionClip!.posWorld : 0;
+  const clipDepth = clipEnabled ? gridSectionClip!.viewDepth : 0;
 
   return useMemo(() => {
-    if (!enabled) return EMPTY_F32;
+    if (!enabled && !effectiveGridEnabled) return EMPTY_F32;
     void version; // depend on parse-completion ticks
 
     const verts: number[] = [];
@@ -546,22 +608,49 @@ export function useSymbolicAnnotations(params: {
         continue;
       }
       if (debugEnabled()) {
-        const buckets = cached.byStorey.size;
-        const looseLines = cached.loose.length;
-        console.log(`[annotations] store ${storeIdx}: lifting ${buckets} storey buckets + ${looseLines} loose lines (key=${key}, fallbackY=${fallbackY})`);
+        console.log(
+          `[annotations] store ${storeIdx}: annotation buckets=${cached.byStorey.size}+${cached.loose.length}loose, grid buckets=${cached.gridByStorey.size}+${cached.gridLoose.length}loose (annot=${enabled}, grid=${effectiveGridEnabled}, clip=${clipEnabled})`,
+        );
+      }
+
+      if (enabled) {
+        for (const bucket of cached.byStorey.values()) {
+          liftTo3DLineList(bucket.lines, resolveBucketY(bucket.storeyElevation, fallbackY), verts);
+        }
+        liftTo3DLineList(cached.loose, fallbackY, verts);
       }
 
-      for (const bucket of cached.byStorey.values()) {
-        liftTo3DLineList(bucket.lines, resolveBucketY(bucket.storeyElevation, fallbackY), verts);
+      if (effectiveGridEnabled) {
+        // Issue #862: section-clip grid buckets only — IfcAnnotation
+        // intentionally bypasses this per the feedback memory ("the
+        // user expects every storey's dimensions/grid bubbles to lift
+        // into the viewport when [the annotation toggle is] on, even
+        // while a section cut is active").
+        if (clipEnabled) {
+          const lo = clipPos - clipDepth;
+          const hi = clipPos + clipDepth;
+          for (const bucket of cached.gridByStorey.values()) {
+            const y = resolveBucketY(bucket.storeyElevation, fallbackY);
+            if (y < lo || y > hi) continue;
+            liftTo3DLineList(bucket.lines, y, verts);
+          }
+          if (fallbackY >= lo && fallbackY <= hi) {
+            liftTo3DLineList(cached.gridLoose, fallbackY, verts);
+          }
+        } else {
+          for (const bucket of cached.gridByStorey.values()) {
+            liftTo3DLineList(bucket.lines, resolveBucketY(bucket.storeyElevation, fallbackY), verts);
+          }
+          liftTo3DLineList(cached.gridLoose, fallbackY, verts);
+        }
       }
-      liftTo3DLineList(cached.loose, fallbackY, verts);
       storeIdx++;
     }
 
     if (debugEnabled()) console.log(`[annotations] total 3D line vertices: ${verts.length / 3} from ${stores.length} stores`);
     if (verts.length === 0) return EMPTY_F32;
     return new Float32Array(verts);
-  }, [enabled, stores, version, fallbackY]);
+  }, [enabled, effectiveGridEnabled, clipEnabled, clipPos, clipDepth, stores, version, fallbackY]);
 }
 
 /**
@@ -723,13 +812,19 @@ export function useSymbolicAnnotationsForDrawing(params: {
       const cached = PARSE_CACHE.get(key);
       if (!cached) continue;
 
-      for (const bucket of cached.byStorey.values()) {
+      // Drawing-2D pulls BOTH annotation and grid buckets (issue #862
+      // split them at parse time so the 3D viewport can clip them
+      // separately — the 2D Section panel still wants the combined
+      // overlay).
+      const collectBucket = (bucket: AnnotationsForStorey) => {
         const bucketY = resolveBucketY(bucket.storeyElevation, fallbackY);
-        if (bucketY < rangeMin || bucketY > rangeMax) continue;
+        if (bucketY < rangeMin || bucketY > rangeMax) return;
         for (const ln of bucket.lines) pushLine(ln);
         for (const t of bucket.texts) pushText(t);
         for (const f of bucket.fills) pushFill(f);
-      }
+      };
+      for (const bucket of cached.byStorey.values()) collectBucket(bucket);
+      for (const bucket of cached.gridByStorey.values()) collectBucket(bucket);
 
       // Loose annotations have no resolvable storey — include them if the
       // fallback Y lands in the view range. That keeps malformed exports
@@ -739,6 +834,9 @@ export function useSymbolicAnnotationsForDrawing(params: {
         for (const ln of cached.loose) pushLine(ln);
         for (const t of cached.looseTexts) pushText(t);
         for (const f of cached.looseFills) pushFill(f);
+        for (const ln of cached.gridLoose) pushLine(ln);
+        for (const t of cached.gridLooseTexts) pushText(t);
+        for (const f of cached.gridLooseFills) pushFill(f);
       }
     }
 
@@ -757,14 +855,24 @@ export function useSymbolicAnnotationsForDrawing(params: {
  */
 export function useSymbolicAnnotationsRichData(params: {
   enabled: boolean;
+  /** Lift grid-bubble texts + fills. Independent of `enabled` (issue #862).
+   *  Defaults to `enabled` for legacy callers. */
+  gridEnabled?: boolean;
+  /** Section clipping for grid texts/fills only — same semantics as
+   *  [`useSymbolicAnnotations`]. */
+  gridSectionClip?: SectionClipForGrid;
   fallbackY?: number;
 }): { texts: readonly AnnotationText3D[]; fills: readonly AnnotationFill3D[] } {
-  const { enabled, fallbackY = 0 } = params;
+  const { enabled, gridEnabled, gridSectionClip, fallbackY = 0 } = params;
+  const effectiveGridEnabled = gridEnabled ?? enabled;
   const stores = useActiveStores();
-  const version = useAnnotationParseTrigger(enabled, stores);
+  const version = useAnnotationParseTrigger(enabled || effectiveGridEnabled, stores);
+  const clipEnabled = !!gridSectionClip && gridSectionClip.enabled && gridSectionClip.axis === 'down';
+  const clipPos = clipEnabled ? gridSectionClip!.posWorld : 0;
+  const clipDepth = clipEnabled ? gridSectionClip!.viewDepth : 0;
 
   return useMemo(() => {
-    if (!enabled) return { texts: EMPTY_TEXTS, fills: EMPTY_FILLS };
+    if (!enabled && !effectiveGridEnabled) return { texts: EMPTY_TEXTS, fills: EMPTY_FILLS };
     void version;
 
     const texts: AnnotationText3D[] = [];
@@ -803,18 +911,45 @@ export function useSymbolicAnnotationsRichData(params: {
         });
       };
 
-      for (const bucket of cached.byStorey.values()) {
-        const y = resolveBucketY(bucket.storeyElevation, fallbackY);
-        for (const t of bucket.texts) pushText(t, y);
-        for (const f of bucket.fills) pushFill(f, y);
+      if (enabled) {
+        for (const bucket of cached.byStorey.values()) {
+          const y = resolveBucketY(bucket.storeyElevation, fallbackY);
+          for (const t of bucket.texts) pushText(t, y);
+          for (const f of bucket.fills) pushFill(f, y);
+        }
+        for (const t of cached.looseTexts) pushText(t, fallbackY);
+        for (const f of cached.looseFills) pushFill(f, fallbackY);
+      }
+
+      if (effectiveGridEnabled) {
+        if (clipEnabled) {
+          const lo = clipPos - clipDepth;
+          const hi = clipPos + clipDepth;
+          for (const bucket of cached.gridByStorey.values()) {
+            const y = resolveBucketY(bucket.storeyElevation, fallbackY);
+            if (y < lo || y > hi) continue;
+            for (const t of bucket.texts) pushText(t, y);
+            for (const f of bucket.fills) pushFill(f, y);
+          }
+          if (fallbackY >= lo && fallbackY <= hi) {
+            for (const t of cached.gridLooseTexts) pushText(t, fallbackY);
+            for (const f of cached.gridLooseFills) pushFill(f, fallbackY);
+          }
+        } else {
+          for (const bucket of cached.gridByStorey.values()) {
+            const y = resolveBucketY(bucket.storeyElevation, fallbackY);
+            for (const t of bucket.texts) pushText(t, y);
+            for (const f of bucket.fills) pushFill(f, y);
+          }
+          for (const t of cached.gridLooseTexts) pushText(t, fallbackY);
+          for (const f of cached.gridLooseFills) pushFill(f, fallbackY);
+        }
       }
-      for (const t of cached.looseTexts) pushText(t, fallbackY);
-      for (const f of cached.looseFills) pushFill(f, fallbackY);
     }
 
     return {
       texts: texts.length ? texts : EMPTY_TEXTS,
       fills: fills.length ? fills : EMPTY_FILLS,
     };
-  }, [enabled, stores, version, fallbackY]);
+  }, [enabled, effectiveGridEnabled, clipEnabled, clipPos, clipDepth, stores, version, fallbackY]);
 }

package/src/lib/clash/persistence.ts

@@ -0,0 +1,308 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * localStorage persistence for clash detection settings + the user's rule preset
+ * set. Mirrors the lens slice's "built-ins + overrides + custom" model and the
+ * scripts module's quota-safe `SaveResult`:
+ *
+ * - Presets: the built-in `CLASH_RULE_PRESETS` are always present (projected to
+ *   editable items with `enabled`/`builtin`); the user may toggle/edit them
+ *   (stored as overrides) and add custom presets. Only customs + modified
+ *   built-ins are persisted, so shipping a new built-in just works.
+ * - Settings: one flat JSON blob (mode/tolerance/clearance/clusterEpsilon/
+ *   reportTouch/groupBy), every numeric clamped to a sane range on load.
+ */
+
+import {
+  CLASH_RULE_PRESETS,
+  type ClashRulePreset,
+  type ClashMode,
+  type ClashSeverity,
+} from '@ifc-lite/clash';
+
+/** A built-in or user-defined clash rule preset, with editor/runtime flags. */
+export type ClashPreset = ClashRulePreset & { enabled: boolean; builtin: boolean };
+
+/** How the panel groups the flat clash list (display only). */
+export type ClashSettingsGroupBy = 'severity' | 'rule' | 'typePair';
+
+/** Global detection settings, persisted as one blob. */
+export interface ClashGlobalSettings {
+  mode: ClashMode;
+  tolerance: number;
+  clearance: number;
+  clusterEpsilon: number;
+  reportTouch: boolean;
+  groupBy: ClashSettingsGroupBy;
+}
+
+export type SaveResult =
+  | { ok: true }
+  | { ok: false; reason: 'quota' | 'serialize' | 'too_many'; message: string };
+
+const PRESETS_KEY = 'ifc-lite-clash-presets';
+const SETTINGS_KEY = 'ifc-lite-clash-settings';
+const SCHEMA_VERSION = 1;
+
+const MAX_PRESETS = 200;
+const MAX_NAME = 100;
+
+/** [min, max] clamps applied to settings numerics on load and on commit. */
+export const CLASH_BOUNDS = {
+  tolerance: [0, 1] as const,
+  clearance: [0, 5] as const,
+  clusterEpsilon: [0.01, 50] as const,
+};
+
+export const DEFAULT_CLASH_SETTINGS: ClashGlobalSettings = {
+  mode: 'hard',
+  tolerance: 0.002,
+  clearance: 0.05,
+  clusterEpsilon: 1.5,
+  reportTouch: false,
+  groupBy: 'severity',
+};
+
+const BUILTIN_PRESET_IDS = new Set(CLASH_RULE_PRESETS.map((p) => p.id));
+const SEVERITIES: ClashSeverity[] = ['critical', 'major', 'minor', 'info'];
+const GROUP_BYS: ClashSettingsGroupBy[] = ['severity', 'rule', 'typePair'];
+
+export function clampToBounds(value: unknown, [min, max]: readonly [number, number], fallback: number): number {
+  const n = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(max, Math.max(min, n));
+}
+
+/** Trim + length-cap a preset name; null if empty (invalid). */
+export function validatePresetName(name: string): string | null {
+  const t = name.trim();
+  return t ? t.slice(0, MAX_NAME) : null;
+}
+
+/** Trim a selector; null if empty (invalid). An empty selector matches everything. */
+export function validateSelector(selector: string): string | null {
+  const t = selector.trim();
+  return t ? t : null;
+}
+
+function isValidStoredPreset(p: unknown): p is ClashPreset {
+  if (!p || typeof p !== 'object') return false;
+  const r = p as Record<string, unknown>;
+  return (
+    typeof r.id === 'string' && r.id.length > 0 &&
+    typeof r.name === 'string' && r.name.trim().length > 0 &&
+    typeof r.selectorA === 'string' && r.selectorA.trim().length > 0 &&
+    typeof r.selectorB === 'string' && r.selectorB.trim().length > 0 &&
+    typeof r.severity === 'string' && SEVERITIES.includes(r.severity as ClashSeverity)
+  );
+}
+
+/** Read stored presets, accepting the versioned wrapper or a legacy bare array. */
+function readStoredPresets(): ClashPreset[] {
+  try {
+    const raw = localStorage.getItem(PRESETS_KEY);
+    if (!raw) return [];
+    const parsed: unknown = JSON.parse(raw);
+    const list = Array.isArray(parsed)
+      ? parsed
+      : parsed && typeof parsed === 'object' && Array.isArray((parsed as { presets?: unknown }).presets)
+        ? (parsed as { presets: unknown[] }).presets
+        : [];
+    return list
+      .filter(isValidStoredPreset)
+      .map((p) => ({
+        id: p.id,
+        name: p.name,
+        description: typeof p.description === 'string' ? p.description : '',
+        severity: p.severity,
+        selectorA: p.selectorA,
+        selectorB: p.selectorB,
+        enabled: p.enabled !== false,
+        builtin: BUILTIN_PRESET_IDS.has(p.id),
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/** The pristine built-in preset set, no overrides/customs — the "reset" target. */
+export function defaultPresets(): ClashPreset[] {
+  return CLASH_RULE_PRESETS.map((p) => ({ ...p, enabled: true, builtin: true }));
+}
+
+/**
+ * The full preset list shown to the user: every built-in (with any saved
+ * override applied) followed by custom presets. Built-ins are always present
+ * even if storage is empty or dropped them.
+ */
+/**
+ * Resolve a stored (customs + modified-built-ins) list into the full preset
+ * list: every built-in (with any override applied), then customs. Built-ins are
+ * always present, so a list from an older app version still picks up new ones.
+ */
+export function mergeStoredPresets(stored: ClashPreset[]): ClashPreset[] {
+  const overrides = new Map(stored.filter((p) => p.builtin).map((p) => [p.id, p]));
+  const builtins: ClashPreset[] = CLASH_RULE_PRESETS.map(
+    (p) => overrides.get(p.id) ?? { ...p, enabled: true, builtin: true },
+  );
+  const custom = stored.filter((p) => !p.builtin);
+  return [...builtins, ...custom];
+}
+
+export function buildInitialPresets(): ClashPreset[] {
+  return mergeStoredPresets(readStoredPresets());
+}
+
+function builtinDiffersFromDefault(p: ClashPreset): boolean {
+  const orig = CLASH_RULE_PRESETS.find((b) => b.id === p.id);
+  if (!orig) return true;
+  return (
+    !p.enabled ||
+    p.name !== orig.name ||
+    p.severity !== orig.severity ||
+    p.selectorA !== orig.selectorA ||
+    p.selectorB !== orig.selectorB ||
+    p.description !== orig.description
+  );
+}
+
+/** The minimal stored shape: customs + only the built-ins that differ from default. */
+export function presetsToStore(presets: ClashPreset[]): ClashPreset[] {
+  return [
+    ...presets.filter((p) => !p.builtin),
+    ...presets.filter((p) => p.builtin && builtinDiffersFromDefault(p)),
+  ];
+}
+
+/** Persist only custom presets + modified built-ins (quota-safe). */
+export function savePresets(presets: ClashPreset[]): SaveResult {
+  const custom = presets.filter((p) => !p.builtin);
+  if (custom.length > MAX_PRESETS) {
+    return { ok: false, reason: 'too_many', message: `Too many custom rules (max ${MAX_PRESETS}).` };
+  }
+  const toStore = presetsToStore(presets);
+  let payload: string;
+  try {
+    payload = JSON.stringify({ schemaVersion: SCHEMA_VERSION, presets: toStore });
+  } catch {
+    return { ok: false, reason: 'serialize', message: 'Could not serialize clash rules.' };
+  }
+  try {
+    localStorage.setItem(PRESETS_KEY, payload);
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: 'quota', message: 'Browser storage is full — clash rules were not saved.' };
+  }
+}
+
+/** Coerce arbitrary input into valid, bounds-clamped settings (defaults on junk). */
+export function normalizeSettings(raw: unknown): ClashGlobalSettings {
+  const s = (raw && typeof raw === 'object' && 'settings' in raw
+    ? (raw as { settings: unknown }).settings
+    : raw) as Partial<ClashGlobalSettings> | null;
+  if (!s || typeof s !== 'object') return { ...DEFAULT_CLASH_SETTINGS };
+  return {
+    mode: s.mode === 'clearance' ? 'clearance' : 'hard',
+    tolerance: clampToBounds(s.tolerance, CLASH_BOUNDS.tolerance, DEFAULT_CLASH_SETTINGS.tolerance),
+    clearance: clampToBounds(s.clearance, CLASH_BOUNDS.clearance, DEFAULT_CLASH_SETTINGS.clearance),
+    clusterEpsilon: clampToBounds(s.clusterEpsilon, CLASH_BOUNDS.clusterEpsilon, DEFAULT_CLASH_SETTINGS.clusterEpsilon),
+    reportTouch: s.reportTouch === true,
+    groupBy: GROUP_BYS.includes(s.groupBy as ClashSettingsGroupBy) ? (s.groupBy as ClashSettingsGroupBy) : 'severity',
+  };
+}
+
+export function loadSettings(): ClashGlobalSettings {
+  try {
+    const raw = localStorage.getItem(SETTINGS_KEY);
+    if (!raw) return { ...DEFAULT_CLASH_SETTINGS };
+    return normalizeSettings(JSON.parse(raw));
+  } catch {
+    return { ...DEFAULT_CLASH_SETTINGS };
+  }
+}
+
+export function saveSettings(settings: ClashGlobalSettings): SaveResult {
+  try {
+    localStorage.setItem(SETTINGS_KEY, JSON.stringify({ schemaVersion: SCHEMA_VERSION, settings }));
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: 'quota', message: 'Browser storage is full — clash settings were not saved.' };
+  }
+}
+
+/** Download the user's presets (customs + modified built-ins) as a JSON file. */
+export function exportPresets(presets: ClashPreset[]): void {
+  const custom = presets.filter((p) => !p.builtin || builtinDiffersFromDefault(p));
+  const blob = new Blob([JSON.stringify({ schemaVersion: SCHEMA_VERSION, presets: custom }, null, 2)], {
+    type: 'application/json',
+  });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = 'clash-rules.clash-presets.json';
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+/** Parse an exported file into custom presets (ids regenerated, `builtin` stripped). */
+export async function importPresets(file: File): Promise<ClashPreset[]> {
+  const text = await file.text();
+  const parsed: unknown = JSON.parse(text);
+  const list = Array.isArray(parsed)
+    ? parsed
+    : parsed && typeof parsed === 'object' && Array.isArray((parsed as { presets?: unknown }).presets)
+      ? (parsed as { presets: unknown[] }).presets
+      : [];
+  return list.filter(isValidStoredPreset).map((p) => ({
+    id: `custom-${crypto.randomUUID()}`,
+    name: p.name.slice(0, MAX_NAME),
+    description: typeof p.description === 'string' ? p.description : '',
+    severity: p.severity,
+    selectorA: p.selectorA,
+    selectorB: p.selectorB,
+    enabled: p.enabled !== false,
+    builtin: false,
+  }));
+}
+
+// ── Flavor integration ───────────────────────────────────────────────────────
+// Clash config rides inside a flavor's generic `settings.clash` blob, so each
+// flavor/profile carries its own rule-set + detection settings (and they travel
+// with flavor export/import). Serialize stores the minimal shape (customs +
+// modified built-ins + settings); deserialize rebuilds the full, validated state.
+
+/** Plain-JSON snapshot of clash config stored in a flavor. */
+export interface ClashFlavorConfig {
+  schemaVersion: number;
+  settings: ClashGlobalSettings;
+  /** Customs + modified built-ins only (built-ins are re-merged on restore). */
+  presets: ClashPreset[];
+}
+
+export function serializeClashConfig(presets: ClashPreset[], settings: ClashGlobalSettings): ClashFlavorConfig {
+  return { schemaVersion: SCHEMA_VERSION, settings: { ...settings }, presets: presetsToStore(presets) };
+}
+
+/**
+ * Rebuild clash state from a flavor blob: the full resolved preset list (defaults
+ * + the blob's overrides/customs) and bounds-clamped settings. Returns null when
+ * the blob is missing/garbage so the caller can skip the restore.
+ */
+export function deserializeClashConfig(blob: unknown): { presets: ClashPreset[]; settings: ClashGlobalSettings } | null {
+  if (!blob || typeof blob !== 'object') return null;
+  const b = blob as Partial<ClashFlavorConfig>;
+  const storedRaw = Array.isArray(b.presets) ? b.presets : [];
+  const stored = storedRaw.filter(isValidStoredPreset).map((p) => ({
+    id: p.id,
+    name: p.name,
+    description: typeof p.description === 'string' ? p.description : '',
+    severity: p.severity,
+    selectorA: p.selectorA,
+    selectorB: p.selectorB,
+    enabled: p.enabled !== false,
+    builtin: BUILTIN_PRESET_IDS.has(p.id),
+  }));
+  return { presets: mergeStoredPresets(stored), settings: normalizeSettings(b.settings) };
+}