@ifc-lite/viewer 1.26.0 → 1.27.0

package/src/components/mcp/playground-dispatcher.ts

@@ -53,6 +53,19 @@ import {
   type BCFTopic,
 } from '@ifc-lite/bcf';
 import { parseIDS, validateIDS, type IDSDocument } from '@ifc-lite/ids';
+import { GeometryProcessor, type MeshData } from '@ifc-lite/geometry';
+import {
+  createClashEngine,
+  disciplineMatrixRules,
+  groupClashes,
+  type Clash,
+  type ClashMode,
+  type ClashResult,
+  type ClashRule,
+  type GroupOptions,
+} from '@ifc-lite/clash';
+import { elementsFromStep } from '@ifc-lite/clash/step';
+import { createBCFFromClashResult } from '@ifc-lite/clash/bcf';
 import { CATALOG, paramsFor } from './data';
 import type { CatalogTool } from './types';
 import type { ViewerController, ColorTuple } from './PlaygroundViewer';
@@ -248,6 +261,149 @@ function formatColorTuple(c: ColorTuple): string {
  */
 const PROXIED_BSDD = new BsddNamespace({ apiBase: '/api/bsdd' });
 
+// ── Clash detection (in-browser meshing → TS clash engine) ─────────────────
+// Mirrors `packages/mcp/src/tools/clash.ts`: the whole model is meshed once
+// (headless WASM pipeline, same as the inline viewer) and cached by model id,
+// then the representation-agnostic clash engine runs against TYPE selectors.
+
+/** Cap on clashes returned in a tool result. The dropped count is reported. */
+const CLASH_DISPLAY_CAP = 50;
+
+/**
+ * Runaway guardrail for the TS clash engine: the whole-run candidate-pair
+ * budget (broad-phase AABB-overlap survivors across every rule). The engine
+ * yields between chunks so it never hard-freezes the tab, but an agent can
+ * fire `clash_check` (all-vs-all) on an arbitrarily large uploaded model
+ * unattended — this ceiling bounds the narrow-phase work and is reported via
+ * `result.truncated` (never silent). Generous on purpose: real building models
+ * stay well under it, so totals match the viewer's (unbounded) ClashPanel; only
+ * pathological models get bounded.
+ */
+const CLASH_MAX_CANDIDATE_PAIRS = 5_000_000;
+
+/** Max distinct models whose meshes we keep cached at once (LRU). The playground
+ *  is effectively single-model, so a small bound is plenty and stops a long
+ *  session of re-uploads from pinning every model's meshes in memory. */
+const CLASH_MESH_CACHE_MAX = 3;
+
+/**
+ * Module-level mesh cache so repeated clash calls on the same model don't
+ * re-run the (expensive) headless tessellation. Keyed by `id:fileSize`, NOT id
+ * alone: the playground reuses a filename-slug id, so an edited re-upload would
+ * otherwise hit a stale mesh — folding in the byte length forces a re-mesh when
+ * the bytes change. Bounded to CLASH_MESH_CACHE_MAX entries with LRU eviction.
+ */
+const clashMeshCache = new Map<string, MeshData[]>();
+
+function meshCacheKey(m: LoadedPlaygroundModel): string {
+  return `${m.id}:${m.fileSize}`;
+}
+
+/** LRU get: a hit refreshes recency so the active model survives eviction. */
+function getCachedMeshes(key: string): MeshData[] | undefined {
+  const hit = clashMeshCache.get(key);
+  if (hit) {
+    clashMeshCache.delete(key);
+    clashMeshCache.set(key, hit);
+  }
+  return hit;
+}
+
+/** LRU set: insert then evict the least-recently-used entries past the bound. */
+function setCachedMeshes(key: string, meshes: MeshData[]): void {
+  clashMeshCache.set(key, meshes);
+  while (clashMeshCache.size > CLASH_MESH_CACHE_MAX) {
+    const oldest = clashMeshCache.keys().next().value;
+    if (oldest === undefined) break;
+    clashMeshCache.delete(oldest);
+  }
+}
+
+/** Mesh the whole model once (in-browser, same path as PlaygroundViewer) and
+ *  cache it. Throws UNSUPPORTED_OPERATION when the model carries no drawable
+ *  geometry — clash needs tessellated solids, not quantity sets. */
+async function meshForClash(m: LoadedPlaygroundModel): Promise<MeshData[]> {
+  const key = meshCacheKey(m);
+  const cached = getCachedMeshes(key);
+  if (cached) return cached;
+
+  const processor = new GeometryProcessor({ preferNative: false });
+  await processor.init();
+  // Use our owning byte snapshot — store.source can be a detached sub-view.
+  const result = await processor.process(
+    m.bytes,
+    m.store.entityIndex.byId as unknown as Map<number, unknown>,
+  );
+  const meshes = result.meshes ?? [];
+  if (meshes.length === 0) {
+    throw new ToolExecutionError({
+      code: ToolErrorCode.UNSUPPORTED_OPERATION,
+      message: 'No mesh geometry could be produced for this model; clash detection needs tessellated solids.',
+      hint: 'Confirm the model carries explicit geometry (not schema/quantity-only data).',
+    });
+  }
+  setCachedMeshes(key, meshes);
+  return meshes;
+}
+
+/**
+ * The most recent clash result, so `clash_bcf_export` can turn the last run into
+ * a rich BCF without re-clashing (mirrors the viewer, where the ClashPanel holds
+ * the result the export dialog reads). Keyed by the SAME `id:fileSize` identity
+ * as the mesh cache — keying by `m.id` alone would serve a stale result after an
+ * edited re-upload (same filename slug) even though the meshes re-compute.
+ */
+const lastClashResult = new Map<string, ClashResult>();
+
+/** Run a rule set against a model's meshes, returning (and caching) the result. */
+async function runClashRules(m: LoadedPlaygroundModel, rules: ClashRule[]): Promise<ClashResult> {
+  const meshes = await meshForClash(m);
+  const { elements, exclusions } = elementsFromStep({ store: m.store, meshes, modelId: m.id });
+  const engine = createClashEngine({ backend: 'ts' });
+  const result = await engine.run(elements, rules, { exclusions, maxCandidatePairs: CLASH_MAX_CANDIDATE_PAIRS });
+  lastClashResult.set(meshCacheKey(m), result);
+  return result;
+}
+
+/** When the candidate-pair guardrail bit, say so in the human-readable text so
+ *  totals are never silently a lower bound. Empty string when the run was
+ *  complete. */
+function clashCapNote(result: ClashResult): string {
+  if (!result.truncated) return '';
+  return ` Note: the ${CLASH_MAX_CANDIDATE_PAIRS.toLocaleString()}-candidate-pair guardrail was hit`
+    + ` (${result.truncated.droppedPairs.toLocaleString()} pairs not evaluated) — totals are a lower bound.`;
+}
+
+/**
+ * Top clashes by signed distance (deepest penetration / smallest gap first),
+ * capped for display. Sort by RAW distance ascending, not |distance|: hard
+ * clashes carry a negative penetration depth, so most-negative-first surfaces
+ * the DEEPEST penetrations (the worst, most actionable rows) instead of
+ * burying them past the cap; clearance gaps are positive, so the same order
+ * surfaces the tightest gaps first.
+ */
+function topClashRows(clashes: Clash[], cap: number): {
+  rows: Record<string, unknown>[];
+  truncated: { shown: number; dropped: number; total: number } | null;
+} {
+  const sorted = [...clashes].sort((x, y) => x.distance - y.distance);
+  const shown = sorted.slice(0, cap);
+  const rows = shown.map((c) => ({
+    id: c.id,
+    rule: c.rule,
+    status: c.status,
+    severity: c.severity,
+    distance: c.distance,
+    point: c.point,
+    a: { key: c.a.key, ref: c.a.ref, tag: c.a.tag, name: c.a.name },
+    b: { key: c.b.key, ref: c.b.ref, tag: c.b.tag, name: c.b.name },
+  }));
+  const truncated = sorted.length > cap
+    ? { shown: shown.length, dropped: sorted.length - shown.length, total: sorted.length }
+    : null;
+  return { rows, truncated };
+}
+
 const IMPLS: Record<string, ToolImpl> = {
   // ── Discovery ───────────────────────────────────────────────────────────
   async model_info(m) {
@@ -523,6 +679,127 @@ const IMPLS: Record<string, ToolImpl> = {
     return { text: area == null ? 'No Area quantity present.' : `Area = ${area.toFixed(3)} m².`, structured: { area } };
   },
 
+  // ── Clash detection ───────────────────────────────────────────────────────
+  async clash_check(m, args) {
+    const a = (args.a as string | undefined) ?? '*';
+    const b = args.b as string | undefined;
+    const mode = (args.mode as ClashMode | undefined) ?? 'hard';
+    const tolerance = args.tolerance as number | undefined;
+    const clearance = args.clearance as number | undefined;
+    // No `b` => self-clash within A (every element vs every other in the
+    // group); with the default a="*" that is "all clashes in the model".
+    const label = b ? `${a} vs ${b}` : a === '*' ? 'all elements (self-clash)' : `${a} (self-clash)`;
+
+    const rule: ClashRule = {
+      id: 'clash_check',
+      name: label,
+      a,
+      ...(b != null ? { b } : {}),
+      mode,
+      ...(tolerance != null ? { tolerance } : {}),
+      ...(clearance != null ? { clearance } : {}),
+    };
+
+    const result = await runClashRules(m, [rule]);
+    const { rows, truncated } = topClashRows(result.clashes, CLASH_DISPLAY_CAP);
+    const capNote = truncated
+      ? ` Showing top ${truncated.shown} by penetration depth; ${truncated.dropped} more not shown.`
+      : '';
+    return {
+      text: `Found ${result.summary.total} clash(es) for ${label} (mode=${mode}).${capNote}${clashCapNote(result)}`,
+      structured: {
+        summary: result.summary,
+        settings: { a, b: b ?? null, mode, tolerance: tolerance ?? null, clearance: clearance ?? null },
+        engineSettings: result.settings,
+        truncated: result.truncated ?? null,
+        clashes: rows,
+        clashesTruncated: truncated,
+      },
+    };
+  },
+  async clash_matrix(m, args) {
+    const mode = (args.mode as ClashMode | undefined) ?? 'hard';
+    const clearance = args.clearance as number | undefined;
+    const rules = disciplineMatrixRules(mode, clearance);
+
+    const result = await runClashRules(m, rules);
+    const { rows, truncated } = topClashRows(result.clashes, CLASH_DISPLAY_CAP);
+    const capNote = truncated
+      ? ` Sampling top ${truncated.shown} by penetration depth; ${truncated.dropped} more not shown.`
+      : '';
+    return {
+      text: `Discipline matrix (mode=${mode}, ${rules.length} rules): ${result.summary.total} clash(es).${capNote}${clashCapNote(result)}`,
+      structured: {
+        mode,
+        ruleCount: rules.length,
+        byRule: result.summary.byRule,
+        bySeverity: result.summary.bySeverity,
+        byTypePair: result.summary.byTypePair,
+        summary: result.summary,
+        engineSettings: result.settings,
+        truncated: result.truncated ?? null,
+        sampleClashes: rows,
+        sampleTruncated: truncated,
+      },
+    };
+  },
+  async clash_bcf_export(m, args) {
+    const groupBy = (args.group_by as GroupOptions['by'] | undefined) ?? 'cluster';
+    const epsilon = args.cluster_epsilon as number | undefined;
+    const status = args.status as string | undefined;
+    const maxTopics = args.max_topics as number | undefined;
+
+    // Reuse the last clash run for this model; if there is none, run a default
+    // all-vs-all hard self-clash so the tool works standalone (and caches it).
+    let result = lastClashResult.get(meshCacheKey(m));
+    if (!result) {
+      result = await runClashRules(m, [{ id: 'clash_check', name: 'all elements (self-clash)', a: '*', mode: 'hard' }]);
+    }
+    if (result.summary.total === 0) {
+      return {
+        text: 'No clashes to export — the last clash run found 0. Run clash_check first (omit a and b for every element vs every other).',
+        structured: { topics: 0, clashes: 0 },
+      };
+    }
+
+    // One BCF topic per clash group, each carrying a framed viewpoint (camera +
+    // the clashing elements as components) and severity/status/distance
+    // metadata — the same bridge the viewer's clash→BCF export uses. Snapshots
+    // are omitted: the inline ViewerController can't render frames headlessly,
+    // and BCF viewpoints are valid without an embedded image.
+    const groups = groupClashes(result, { by: groupBy, ...(epsilon != null ? { epsilon } : {}) });
+    const project = await createBCFFromClashResult(result, groups, {
+      author: 'clash@ifc-lite',
+      projectName: 'Clash report',
+      ...(status ? { status } : {}),
+      ...(maxTopics != null ? { maxTopics } : {}),
+    });
+
+    const filename = coerceFilename(args.file_path as string | undefined, 'bcfzip', 'clashes');
+    const blob = await writeBCF(project);
+    const file = playgroundFiles.add({
+      filename,
+      mimeType: 'application/zip',
+      size: blob.size,
+      blob,
+      source: 'clash_bcf_export',
+      description: `${project.topics.size} clash topic(s), grouped by ${groupBy}`,
+    });
+    return {
+      text: `Bundled ${filename}: ${project.topics.size} BCF topic(s) from ${result.summary.total} clash(es), grouped by ${groupBy}`
+        + ` — each with a framed viewpoint + clashing components + severity/distance metadata. (Snapshots omitted: the inline viewer can't capture frames headlessly.)`,
+      structured: {
+        fileId: file.id,
+        filename,
+        bytes: blob.size,
+        topics: project.topics.size,
+        groupBy,
+        clashes: result.summary.total,
+      },
+      download: { fileId: file.id, filename, mimeType: 'application/zip', size: blob.size, label: 'Get .bcfzip' },
+    };
+  },
+
   // ── Validation ──────────────────────────────────────────────────────────
   async model_audit(m) {
     let issues = 0;

package/src/components/mcp/types.ts

@@ -22,7 +22,8 @@ export type ToolCategory =
   | 'bSDD'
   | 'Diff'
   | 'Export'
-  | 'Viewer';
+  | 'Viewer'
+  | 'Clash';
 
 export interface CatalogTool {
   name: string;

package/src/components/ui/combo-input.tsx

@@ -0,0 +1,163 @@
+/* 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/. */
+
+/**
+ * ComboInput — a free-text input that opens a suggestion dropdown on focus
+ * and filters it as you type. Pick a suggestion or keep typing anything;
+ * the value is never restricted to the options. Used by the filter chip
+ * editors to surface real model values (materials, classifications,
+ * property values, pset/qto names) without hiding them behind a tiny chevron.
+ *
+ * The list is portaled to `document.body` and fixed-positioned under the
+ * input so it's never clipped by the modal's scroll container, and it
+ * follows the input on scroll / resize.
+ */
+
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Input } from '@/components/ui/input';
+import { cn } from '@/lib/utils';
+
+export interface ComboInputProps {
+  value: string;
+  onChange: (next: string) => void;
+  options: ReadonlyArray<string>;
+  placeholder?: string;
+  className?: string;
+  /** Cap rendered suggestions (filtering still scans all options). */
+  maxRendered?: number;
+  'aria-label'?: string;
+}
+
+interface Anchor { left: number; top: number; width: number }
+
+export function ComboInput({
+  value,
+  onChange,
+  options,
+  placeholder,
+  className,
+  maxRendered = 50,
+  'aria-label': ariaLabel,
+}: ComboInputProps) {
+  const [open, setOpen] = useState(false);
+  const [highlight, setHighlight] = useState(0);
+  const [anchor, setAnchor] = useState<Anchor | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  const filtered = useMemo(() => {
+    const q = value.trim().toLowerCase();
+    const matches = q ? options.filter((o) => o.toLowerCase().includes(q)) : options;
+    return matches.slice(0, maxRendered);
+  }, [options, value, maxRendered]);
+
+  useEffect(() => { setHighlight(0); }, [filtered]);
+
+  const reposition = useCallback(() => {
+    const el = inputRef.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    setAnchor({ left: r.left, top: r.bottom, width: r.width });
+  }, []);
+
+  // Track the input's position while open (capture = also catch ancestor
+  // scrolls inside the modal), and close on outside pointer-down / Escape.
+  useLayoutEffect(() => {
+    if (!open) return;
+    reposition();
+    const onScroll = () => reposition();
+    window.addEventListener('scroll', onScroll, true);
+    window.addEventListener('resize', onScroll);
+    const onDown = (e: MouseEvent) => {
+      const t = e.target as Node;
+      if (inputRef.current?.contains(t) || listRef.current?.contains(t)) return;
+      setOpen(false);
+    };
+    window.addEventListener('mousedown', onDown);
+    return () => {
+      window.removeEventListener('scroll', onScroll, true);
+      window.removeEventListener('resize', onScroll);
+      window.removeEventListener('mousedown', onDown);
+    };
+  }, [open, reposition]);
+
+  const showList = open && filtered.length > 0 && anchor !== null;
+
+  const commit = (v: string) => {
+    onChange(v);
+    setOpen(false);
+  };
+
+  return (
+    <>
+      <Input
+        ref={inputRef}
+        value={value}
+        placeholder={placeholder}
+        onChange={(e) => { onChange(e.target.value); setOpen(true); }}
+        onFocus={() => setOpen(true)}
+        onClick={() => setOpen(true)}
+        onKeyDown={(e) => {
+          if (e.key === 'ArrowDown') {
+            e.preventDefault();
+            setOpen(true);
+            setHighlight((h) => Math.min(h + 1, filtered.length - 1));
+          } else if (e.key === 'ArrowUp') {
+            e.preventDefault();
+            setHighlight((h) => Math.max(h - 1, 0));
+          } else if (e.key === 'Enter') {
+            if (showList && filtered[highlight] !== undefined) {
+              e.preventDefault();
+              commit(filtered[highlight]);
+            }
+          } else if (e.key === 'Escape') {
+            if (open) { e.stopPropagation(); setOpen(false); }
+          }
+        }}
+        className={className}
+        autoComplete="off"
+        role="combobox"
+        aria-expanded={showList}
+        aria-label={ariaLabel}
+      />
+      {showList && createPortal(
+        <div
+          ref={listRef}
+          role="listbox"
+          // Portaled to <body>, which sits OUTSIDE the Radix Dialog. Radix's
+          // scroll-lock disables pointer events on everything outside the
+          // dialog, so re-enable them here or mouse clicks/scroll are dead.
+          // Stop pointerdown from bubbling to the dialog's dismissable layer
+          // so selecting a value doesn't also close the whole modal.
+          style={{ position: 'fixed', left: anchor.left, top: anchor.top + 4, minWidth: anchor.width, pointerEvents: 'auto' }}
+          onPointerDown={(e) => e.stopPropagation()}
+          className="z-[120] max-h-60 w-max max-w-[20rem] overflow-y-auto rounded-md border border-zinc-200 bg-white py-1 shadow-lg dark:border-zinc-800 dark:bg-zinc-950"
+        >
+          {filtered.map((o, i) => (
+            <button
+              key={o}
+              type="button"
+              role="option"
+              aria-selected={i === highlight}
+              // mousedown (not click) so the input doesn't blur-close first.
+              onMouseDown={(e) => { e.preventDefault(); commit(o); }}
+              onMouseEnter={() => setHighlight(i)}
+              className={cn(
+                'block w-full truncate px-2 py-1 text-left text-xs font-mono',
+                i === highlight
+                  ? 'bg-zinc-100 dark:bg-zinc-800'
+                  : 'hover:bg-zinc-50 dark:hover:bg-zinc-900',
+              )}
+              title={o}
+            >
+              {o}
+            </button>
+          ))}
+        </div>,
+        document.body,
+      )}
+    </>
+  );
+}

package/src/components/ui/tabs.tsx

@@ -30,7 +30,7 @@ const TabsTrigger = React.forwardRef<
   <TabsPrimitive.Trigger
     ref={ref}
     className={cn(
-      'inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+      'inline-flex items-center justify-center whitespace-nowrap rounded-md px-3 py-1 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
       className
     )}
     {...props}

package/src/components/viewer/PropertiesPanel.tsx

@@ -512,7 +512,7 @@ export function PropertiesPanel() {
     if (!entityNode) return [];
 
     const rawProps = entityNode.properties();
-    let result = rawProps.map(pset => ({
+    let result: DisplayPropertySet[] = rawProps.map(pset => ({
       name: pset.name,
       properties: pset.properties.map(p => ({ name: p.name, value: p.value, isMutated: false })),
       isNewPset: false,
@@ -970,21 +970,28 @@ export function PropertiesPanel() {
     }));
   }, [nativeDetails]);
 
+  // Overlay (authored) entities — split halves, duplicates, scripted
+  // adds — live only in the StoreEditor overlay, NOT the parsed store.
+  // `modelQuery.entity()` always returns a node, and its getters fall
+  // back to the 'Unknown'/'' sentinels for ids absent from the parsed
+  // table (entity-table.ts#getTypeName). Those non-null sentinels would
+  // shadow the overlay record in an `entityNode ?? overlay` chain, so
+  // when an overlay record exists it MUST take precedence.
   const renderedEntityType = isNativeLazySelection
     ? (nativeDetails?.summary.type ?? 'Loading...')
-    : (entityNode?.type ?? overlayEntity?.type ?? 'Unknown');
+    : (overlayEntity?.type ?? entityNode?.type ?? 'Unknown');
   const renderedEntityName = isNativeLazySelection
     ? (nativeDetails?.summary.name ?? `#${selectedEntity?.expressId ?? ''}`)
-    : (entityNode?.name ?? overlayAttr(2) ?? undefined);
+    : (overlayAttr(2) ?? entityNode?.name ?? undefined);
   const renderedEntityGlobalId = isNativeLazySelection
     ? (nativeDetails?.summary.globalId ?? null)
-    : (entityNode?.globalId ?? overlayAttr(0));
+    : (overlayAttr(0) ?? entityNode?.globalId);
   const renderedEntityDescription = isNativeLazySelection
     ? undefined
-    : (entityNode?.description ?? overlayAttr(3) ?? undefined);
+    : (overlayAttr(3) ?? entityNode?.description ?? undefined);
   const renderedEntityObjectType = isNativeLazySelection
     ? undefined
-    : (entityNode?.objectType ?? overlayAttr(4) ?? undefined);
+    : (overlayAttr(4) ?? entityNode?.objectType ?? undefined);
   const renderedSpatialInfo = isNativeLazySelection ? nativeSpatialInfo : spatialInfo;
   const renderedOccurrenceProperties = isNativeLazySelection ? nativeOccurrenceProperties : occurrenceProperties;
   const renderedInheritedTypeProperties = isNativeLazySelection ? [] : inheritedTypeProperties;

package/src/components/viewer/SearchInline.tsx

@@ -25,7 +25,7 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { Search, Clock, X } from 'lucide-react';
+import { Search, Clock, X, SlidersHorizontal } from 'lucide-react';
 import { useShallow } from 'zustand/react/shallow';
 import { Input } from '@/components/ui/input';
 import { useViewerStore } from '@/store';
@@ -79,6 +79,9 @@ export function SearchInline() {
     exitVimCycle,
     stepVimCycle,
     setSearchModalOpen,
+    setSearchModalTab,
+    activeRuleCount,
+    clearFilterRules,
     models,
     setSelectedEntity,
     setSelectedEntityId,
@@ -99,6 +102,9 @@ export function SearchInline() {
       exitVimCycle: s.exitVimCycle,
       stepVimCycle: s.stepVimCycle,
       setSearchModalOpen: s.setSearchModalOpen,
+      setSearchModalTab: s.setSearchModalTab,
+      activeRuleCount: s.searchFilter.rules.length,
+      clearFilterRules: s.clearFilterRules,
       models: s.models,
       setSelectedEntity: s.setSelectedEntity,
       setSelectedEntityId: s.setSelectedEntityId,
@@ -395,8 +401,10 @@ export function SearchInline() {
         e.preventDefault();
         // ⌘↵ / Ctrl+↵ opens the advanced modal instead of committing — the
         // inline query is preserved so the modal opens already populated.
+        // Text-search entry point, so land on the Search tab.
         if (e.metaKey || e.ctrlKey) {
           setSearchOpen(false);
+          setSearchModalTab('search');
           setSearchModalOpen(true);
           return;
         }
@@ -416,9 +424,19 @@ export function SearchInline() {
         if (target) commitResult(target, idx, e.shiftKey, liveResults, live);
       }
     },
-    [commitResult, results, searchHighlightIndex, searchOpen, setSearchHighlightIndex, setSearchModalOpen, setSearchOpen],
+    [commitResult, results, searchHighlightIndex, searchOpen, setSearchHighlightIndex, setSearchModalOpen, setSearchModalTab, setSearchOpen],
   );
 
+  const hasFilters = activeRuleCount > 0;
+
+  /** Open the advanced modal straight to the Filter builder — the
+   *  always-visible entry point to structured filtering. */
+  const openAdvancedFilter = useCallback(() => {
+    setSearchOpen(false);
+    setSearchModalTab('filter');
+    setSearchModalOpen(true);
+  }, [setSearchOpen, setSearchModalTab, setSearchModalOpen]);
+
   const queryTrimmedLen = searchQuery.trim().length;
   const showPopover = searchOpen && (results.length > 0 || queryTrimmedLen > 0 || recents.length > 0);
   const showRecents = searchOpen && queryTrimmedLen === 0 && recents.length > 0;
@@ -437,11 +455,52 @@ export function SearchInline() {
         }}
         onFocus={() => setSearchOpen(true)}
         onKeyDown={handleInputKeyDown}
+        className={cn(hasFilters ? 'pr-[4.5rem]' : 'pr-9')}
         aria-label="Search entities"
         aria-autocomplete="list"
         aria-expanded={showPopover}
         aria-controls="search-inline-popover"
       />
+      {/* Advanced-filter affordance — always visible so structured
+          filtering is discoverable without the ⌘⇧F shortcut. Shows the
+          active rule count and a quick-clear when a filter is applied. */}
+      <div className="absolute right-1.5 top-1/2 -translate-y-1/2 flex items-center gap-0.5">
+        {hasFilters && (
+          <button
+            type="button"
+            aria-label="Clear filters"
+            title="Clear filters"
+            onMouseDown={(e) => {
+              e.preventDefault();
+              clearFilterRules();
+            }}
+            className="rounded p-1 text-muted-foreground transition-colors hover:bg-zinc-100 hover:text-foreground dark:hover:bg-zinc-800"
+          >
+            <X className="h-3.5 w-3.5" />
+          </button>
+        )}
+        <button
+          type="button"
+          aria-label={hasFilters ? `Advanced filter — ${activeRuleCount} active` : 'Advanced filter'}
+          aria-pressed={hasFilters}
+          title="Advanced filter (⌘⇧F)"
+          onMouseDown={(e) => {
+            e.preventDefault();
+            openAdvancedFilter();
+          }}
+          className={cn(
+            'flex items-center gap-1 rounded px-1.5 py-1 text-xs transition-colors',
+            hasFilters
+              ? 'bg-primary/10 text-primary hover:bg-primary/15'
+              : 'text-muted-foreground hover:bg-zinc-100 hover:text-foreground dark:hover:bg-zinc-800',
+          )}
+        >
+          <SlidersHorizontal className="h-3.5 w-3.5" />
+          {hasFilters && (
+            <span className="font-mono text-[10px] font-semibold leading-none">{activeRuleCount}</span>
+          )}
+        </button>
+      </div>
       {/* Vim cycle hint — shows below the input whenever a cycle is active
           and the popover is closed. Clicking it exits the cycle. */}
       {searchVimCycle && !showPopover && (
@@ -475,6 +534,7 @@ export function SearchInline() {
           onHover={(i) => setSearchHighlightIndex(i)}
           onOpenAdvanced={() => {
             setSearchOpen(false);
+            setSearchModalTab('search');
             setSearchModalOpen(true);
           }}
         />