simdref 0.0.3__tar.gz → 0.0.4__tar.gz

{simdref-0.0.3/src/simdref.egg-info → simdref-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simdref
-Version: 0.0.3
+Version: 0.0.4
 Summary: Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, LSP, and static web export.
 Author: Marco
 License: GPL-3.0-or-later
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: click<10,>=8.1
 Requires-Dist: httpx<1,>=0.28
 Requires-Dist: msgpack<2,>=1.0
 Requires-Dist: pdfplumber<1,>=0.11

{simdref-0.0.3 → simdref-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simdref"
-version = "0.0.3"
+version = "0.0.4"
 description = "Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, LSP, and static web export."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,6 +26,7 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
+  "click>=8.1,<10",
   "httpx>=0.28,<1",
   "msgpack>=1.0,<2",
   "pdfplumber>=0.11,<1",

simdref-0.0.4/src/simdref/__init__.py

@@ -0,0 +1,10 @@
+"""simdref package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+__all__ = ["__version__"]
+
+try:
+    __version__ = version("simdref")
+except PackageNotFoundError:  # uninstalled source checkout
+    __version__ = "0.0.0+source"

{simdref-0.0.3 → simdref-0.0.4}/src/simdref/annotate.py

@@ -68,8 +68,6 @@ def parse_asm_line(line: str, *, track_positions: bool = False) -> AsmLine:
         return AsmLine(LineKind.COMMENT, stripped)
     if bare.startswith("."):
         return AsmLine(LineKind.DIRECTIVE, stripped)
-    if _LABEL_RE.match(stripped):
-        return AsmLine(LineKind.LABEL, stripped)
 
     address: int | None = None
     if track_positions:
@@ -97,6 +95,9 @@ def parse_asm_line(line: str, *, track_positions: bool = False) -> AsmLine:
         # source keywords ("return", "if", "for", ...) as mnemonics.
         return AsmLine(LineKind.COMMENT, stripped)
 
+    if _LABEL_RE.match(stripped):
+        return AsmLine(LineKind.LABEL, stripped)
+
     m = _INSTR_RE.match(stripped)
     if not m:
         return AsmLine(LineKind.COMMENT, stripped)

{simdref-0.0.3 → simdref-0.0.4}/src/simdref/cli.py

@@ -70,6 +70,7 @@ from simdref.ingest_sources import (
     refresh_local_arm_intrinsics_bundle,
 )
 from simdref.manpages import open_manpage, write_manpages
+from simdref import perf
 from simdref.perf import variant_perf_summary
 from simdref.queries import intrinsic_perf_summary_runtime, instruction_rows_for_intrinsic
 from simdref.search import (
@@ -92,10 +93,12 @@ from simdref.storage import (
     load_instructions_by_mnemonic_from_db,
     load_instructions_by_mnemonic_prefix_from_db,
     open_db,
+    read_installed_version_stamp,
     save_catalog,
     search_instruction_candidates_from_db,
     search_intrinsic_candidates_from_db,
     sqlite_schema_is_current,
+    write_installed_version_stamp,
 )
 from simdref.web import export_web
 
@@ -287,6 +290,18 @@ def _download_from_release() -> None:
                     f"failed to download {asset}: {exc.response.status_code}", style="red"
                 )
                 raise typer.Exit(code=1) from exc
+            except (
+                httpx.ConnectError,
+                httpx.ConnectTimeout,
+                httpx.ReadTimeout,
+                httpx.NetworkError,
+            ) as exc:
+                err_console.print(
+                    "[bold yellow]warning:[/bold yellow] no internet connectivity — "
+                    f"could not reach the release server ({exc.__class__.__name__}). "
+                    "Some features may not work correctly until the catalog is refreshed.",
+                )
+                raise typer.Exit(code=1) from exc
         return False
 
     for asset in ("catalog.msgpack", "catalog.db"):
@@ -444,6 +459,7 @@ def _build_runtime_locally(*, man_dir: Path, include_sdm: bool = False) -> None:
         f"updated catalog with {len(catalog.intrinsics)} intrinsics and {len(catalog.instructions)} instructions",
         style="green",
     )
+    write_installed_version_stamp(__version__)
 
 
 def _refresh_runtime_from_existing_catalog(*, man_dir: Path) -> None:
@@ -463,6 +479,7 @@ def _refresh_runtime_from_existing_catalog(*, man_dir: Path) -> None:
         f"refreshed runtime from existing catalog with {len(catalog.intrinsics)} intrinsics and {len(catalog.instructions)} instructions",
         style="green",
     )
+    write_installed_version_stamp(__version__)
 
 
 def _finalize_runtime_from_download(*, man_dir: Path) -> None:
@@ -476,6 +493,7 @@ def _finalize_runtime_from_download(*, man_dir: Path) -> None:
         f"refreshed local web/man assets from downloaded catalog with {len(catalog.intrinsics)} intrinsics and {len(catalog.instructions)} instructions",
         style="green",
     )
+    write_installed_version_stamp(__version__)
 
 
 def _download_release_or_fallback(*, man_dir: Path) -> None:
@@ -559,9 +577,16 @@ def ensure_catalog():
 
 
 def ensure_runtime() -> None:
-    """Ensure catalog + SQLite are present and current."""
+    """Ensure catalog + SQLite are present and current.
+
+    If the package version recorded in the data dir does not match the
+    currently installed version, transparently re-run the release-download
+    flow so users don't need to invoke ``simdref update`` manually after
+    a ``pip``/``uv`` install or upgrade. Honors ``SIMDREF_SKIP_AUTOUPDATE``.
+    """
     if not CATALOG_PATH.exists():
         _bootstrap_interactive()
+        _maybe_auto_update_for_version_change()
         return
     if not sqlite_schema_is_current():
         err_console.print(
@@ -569,6 +594,37 @@ def ensure_runtime() -> None:
             style="yellow",
         )
         _refresh_runtime_from_existing_catalog(man_dir=DEFAULT_MAN_DIR)
+    _maybe_auto_update_for_version_change()
+
+
+def _maybe_auto_update_for_version_change() -> None:
+    """Refresh data when the package version differs from the stamped one."""
+    if os.environ.get("SIMDREF_SKIP_AUTOUPDATE"):
+        return
+    stamped = read_installed_version_stamp()
+    if stamped == __version__:
+        return
+    if stamped is None:
+        # First run after install: stamp without re-downloading. The catalog
+        # we just bootstrapped (or that already exists locally) is what the
+        # user expects to see.
+        write_installed_version_stamp(__version__)
+        return
+    err_console.print(
+        f"simdref upgraded from {stamped} to {__version__}; refreshing catalog "
+        "(set SIMDREF_SKIP_AUTOUPDATE=1 to disable)",
+        style="yellow",
+    )
+    try:
+        _download_release_or_fallback(man_dir=DEFAULT_MAN_DIR)
+    except typer.Exit:
+        err_console.print(
+            "[bold yellow]warning:[/bold yellow] auto-update failed; continuing with the existing catalog. "
+            "Some features may not work correctly until `simdref update` succeeds.",
+        )
+        # Stamp anyway so we don't retry on every invocation; the user has
+        # been warned and can re-run `simdref update` once back online.
+        write_installed_version_stamp(__version__)
 
 
 def _catalog_meta(catalog) -> dict:
@@ -700,10 +756,11 @@ def _llm_result_payload(
                 intrinsic_map[result.key] = item
         if item is not None:
             lat, cpi = intrinsic_perf_summary_runtime(conn, item, instruction_map)
-            return {
+            payload: dict = {
                 "query": item.name,
                 "intrinsic": item.name,
                 "signature": item.signature,
+                "url": getattr(item, "url", "") or "",
                 "instructions": item.instructions,
                 "instruction_refs": item.instruction_refs,
                 "summary": item.description,
@@ -711,6 +768,10 @@ def _llm_result_payload(
                 "lat": lat,
                 "cpi": cpi,
             }
+            operation = _intrinsic_operation_text(item)
+            if operation:
+                payload["operation"] = operation
+            return payload
     item = instruction_map.get(result.key)
     if item is None:
         item = load_instruction_from_db(conn, result.key)
@@ -739,7 +800,7 @@ def _llm_result_payload(
 def _llm_intrinsic_payload(conn, intrinsic) -> dict:
     instruction_map: dict[str, object] = {}
     lat, cpi = intrinsic_perf_summary_runtime(conn, intrinsic, instruction_map)
-    return {
+    payload: dict = {
         "query": intrinsic.name,
         "intrinsic": intrinsic.name,
         "signature": intrinsic.signature,
@@ -751,6 +812,23 @@ def _llm_intrinsic_payload(conn, intrinsic) -> dict:
         "cpi": cpi,
         "summary": intrinsic.description,
     }
+    operation = _intrinsic_operation_text(intrinsic)
+    if operation:
+        # Encodes algorithmic quirks (e.g. the bit-1 selector in
+        # ``_mm_permutevar_pd``) that the one-line summary cannot convey.
+        payload["operation"] = operation
+    return payload
+
+
+def _intrinsic_operation_text(intrinsic) -> str:
+    """Return the SDM-style ``Operation`` pseudocode for *intrinsic*, or ``""``.
+
+    Intel ingest stores it under ``doc_sections["Operation"]``; ARM ACLE under
+    ``doc_sections["ACLE Operation"]``. Both are pseudocode the LLM payload
+    needs to surface so callers can reason about behavior beyond the summary.
+    """
+    sections = getattr(intrinsic, "doc_sections", None) or {}
+    return (sections.get("Operation") or sections.get("ACLE Operation") or "").strip()
 
 
 def _llm_instruction_payload(item) -> dict:
@@ -762,9 +840,24 @@ def _llm_instruction_payload(item) -> dict:
         "lat": lat,
         "cpi": cpi,
         "summary": item.summary,
+        "source_kinds": _payload_source_kinds(item.arch_details),
     }
 
 
+def _payload_source_kinds(arch_details) -> list[str]:
+    """Return the distinct provenance kinds present in an instruction's arch_details."""
+    if not isinstance(arch_details, dict):
+        return []
+    kinds: list[str] = []
+    for details in arch_details.values():
+        if not isinstance(details, dict):
+            continue
+        kind = perf._source_kind(details)
+        if kind not in kinds:
+            kinds.append(kind)
+    return kinds
+
+
 # ---------------------------------------------------------------------------
 # Search results
 # ---------------------------------------------------------------------------
@@ -1184,6 +1277,9 @@ def _llm_filter_records(
 
 def _record_has_source_kind(rec: dict, wanted: str) -> bool:
     """Check whether an llm payload dict carries at least one entry with *wanted* provenance."""
+    slim = rec.get("source_kinds")
+    if isinstance(slim, list) and any(k == wanted for k in slim):
+        return True
     arch_details = rec.get("arch_details") or {}
     if isinstance(arch_details, dict):
         for details in arch_details.values():
@@ -1323,6 +1419,14 @@ def _llm_schema_payload() -> dict:
                     "lat": {"type": "string"},
                     "cpi": {"type": "string"},
                     "summary": {"type": "string"},
+                    "url": {
+                        "type": "string",
+                        "description": "Vendor documentation URL (Intel Intrinsics Guide / ARM ACLE).",
+                    },
+                    "operation": {
+                        "type": "string",
+                        "description": "SDM-style pseudocode describing the intrinsic's behavior, when available.",
+                    },
                 },
             },
             "results": {"type": "array", "items": {"$ref": "#/properties/result"}},

{simdref-0.0.3 → simdref-0.0.4}/src/simdref/ingest_catalog.py

@@ -275,6 +275,13 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
             name = node.attrib.get("name", "").strip()
             if not name:
                 continue
+            operation_text = ""
+            op_node = node.find("./operation")
+            if op_node is not None:
+                # ``<operation>`` carries SDM-style pseudocode; preserve internal
+                # whitespace (it encodes the algorithm) but trim outer padding.
+                raw = "".join(op_node.itertext())
+                operation_text = raw.strip("\n").rstrip() if raw else ""
             return_node = node.find("./return")
             ret = (
                 node.attrib.get("rettype", "").strip()
@@ -321,6 +328,7 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
                     header=(
                         (node.findtext("./header") or "").strip() or node.attrib.get("header", "")
                     ),
+                    url=_intel_intrinsic_url(name),
                     architecture="x86",
                     isa=_normalize_isa(
                         cpuid or node.attrib.get("isa", "") or node.attrib.get("tech", "")
@@ -332,6 +340,7 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
                     subcategory=node.attrib.get("tech", "").strip(),
                     instructions=instructions,
                     instruction_refs=[ref | {"architecture": "x86"} for ref in instruction_refs],
+                    doc_sections=({"Operation": operation_text} if operation_text else {}),
                     notes=notes,
                     aliases=[],
                 )
@@ -384,12 +393,16 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
         description = str(
             item.get("description") or item.get("summary") or item.get("technology", "")
         ).strip()
+        operation_text = (
+            str(item.get("operation") or item.get("Operation") or "").strip("\n").rstrip()
+        )
         records.append(
             IntrinsicRecord(
                 name=name,
                 signature=signature,
                 description=description,
                 header=str(item.get("header") or item.get("include") or "").strip(),
+                url=str(item.get("url") or "").strip() or _intel_intrinsic_url(name),
                 architecture="x86",
                 isa=_normalize_isa(
                     item.get("isa") or item.get("tech") or item.get("instructionSet") or []
@@ -402,6 +415,7 @@ def parse_intel_payload(text: str) -> list[IntrinsicRecord]:
                     for value in instructions
                     if str(value).strip()
                 ],
+                doc_sections=({"Operation": operation_text} if operation_text else {}),
                 notes=[str(value).strip() for value in notes if str(value).strip()],
                 aliases=[str(value).strip() for value in aliases if str(value).strip()],
             )
@@ -476,6 +490,16 @@ def _arm_intrinsic_url(name: str) -> str:
     return urljoin(_ARM_ACLE_INTRINSIC_BASE_URL, quote(name))
 
 
+_INTEL_INTRINSIC_BASE_URL = (
+    "https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html"
+)
+
+
+def _intel_intrinsic_url(name: str) -> str:
+    """Stable Intel Intrinsics Guide deep link for *name* (uses ``#text=`` fragment)."""
+    return f"{_INTEL_INTRINSIC_BASE_URL}#text={quote(name)}"
+
+
 def _arm_slug(text: str) -> str:
     slug = re.sub(r"[^a-z0-9]+", "-", text.casefold()).strip("-")
     return slug or "intrinsics"

{simdref-0.0.3 → simdref-0.0.4}/src/simdref/perf.py

@@ -70,9 +70,16 @@ def latency_cycle_values(latencies: list[dict[str, Any]]) -> list[str]:
     """
     values: list[str] = []
     for latency in latencies:
+        mem_is_upper = latency.get("cycles_mem_is_upper_bound") == "1"
         for key in ("cycles", "cycles_mem", "cycles_addr", "cycles_addr_index"):
             value = latency.get(key)
-            if value and value not in values:
+            if not value:
+                continue
+            if key == "cycles_mem" and mem_is_upper and _is_numeric(value) and float(value) == 0:
+                # uops.info convention: cycles_mem=0 with the upper-bound flag
+                # is a "not measured" marker, not a real zero-cycle latency.
+                continue
+            if value not in values:
                 values.append(value)
     return values
 

{simdref-0.0.3 → simdref-0.0.4}/src/simdref/storage.py

@@ -82,7 +82,27 @@ else:
 
 CATALOG_PATH = DATA_DIR / "catalog.msgpack"
 SQLITE_PATH = DATA_DIR / "catalog.db"
-SQLITE_SCHEMA_VERSION = "11"
+INSTALLED_VERSION_STAMP = DATA_DIR / "installed_version"
+SQLITE_SCHEMA_VERSION = "12"
+
+
+def read_installed_version_stamp() -> str | None:
+    """Return the package version that last refreshed the data dir, or None."""
+    try:
+        return INSTALLED_VERSION_STAMP.read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+
+
+def write_installed_version_stamp(version: str) -> None:
+    """Record the package version that just refreshed the data dir."""
+    try:
+        INSTALLED_VERSION_STAMP.parent.mkdir(parents=True, exist_ok=True)
+        INSTALLED_VERSION_STAMP.write_text(version.strip() + "\n", encoding="utf-8")
+    except OSError:
+        pass  # best-effort — stamp persistence must not break commands
+
+
 FTS_TOKEN_RE = re.compile(r"[A-Za-z0-9]+")
 SQLITE_INSERT_BATCH_SIZE = 512
 

{simdref-0.0.3 → simdref-0.0.4}/src/simdref/templates/app.js

@@ -21,7 +21,7 @@ const themeIconDark  = $("theme-icon-dark");
 const shortcutsOverlay = $("shortcuts-overlay");
 
 /* ── State ────────────────────────────────────────────────────────── */
-let catalog = null;            // search-index.json payload
+let catalog = null;            // merged search-index-* shard payload
 let searchEntries = [];
 let searchTokenIndex = new Map();
 let searchPrefixIndex = new Map();
@@ -207,8 +207,18 @@ function _pushBucket(map, key, i) {
 
 function buildBuckets() {
   byKind.clear(); byFamily.clear(); byCategory.clear(); byArmArch.clear();
-  for (let i = 0; i < searchEntries.length; i++) {
-    const e = searchEntries[i];
+  extendBuckets(searchEntries, 0);
+  bucketsBuilt = true;
+}
+
+/* Append ``entries`` to the kind/family/category/arm-arch buckets at
+ * absolute positions ``baseIndex + offset``. Used by Phase-2 intrinsic
+ * ingest so newly-arrived entries are reachable via the kind filter
+ * without rebuilding from scratch. */
+function extendBuckets(entries, baseIndex) {
+  for (let k = 0; k < entries.length; k++) {
+    const e = entries[k];
+    const i = baseIndex + k;
     _pushBucket(byKind, e.kind, i);
     const fams = e.item.isa_families || [];
     if (fams.length === 0) _pushBucket(byFamily, "__none", i);
@@ -218,7 +228,6 @@ function buildBuckets() {
     const arch = e.item.arm_arch || "__none";
     _pushBucket(byArmArch, arch, i);
   }
-  bucketsBuilt = true;
 }
 
 function _unionKeys(map, keys) {
@@ -468,18 +477,27 @@ function rankEntry(query, entry) {
 function buildSearchIndexes(entries) {
   searchTokenIndex = new Map();
   searchPrefixIndex = new Map();
-  entries.forEach((entry, i) => {
+  extendSearchIndexes(entries, 0);
+}
+
+/* Append ``entries`` to the existing token/prefix maps, treating their
+ * absolute position in ``searchEntries`` as ``baseIndex + offset``. Used
+ * by the Phase-2 batched intrinsic ingest to avoid the full-rebuild stall. */
+function extendSearchIndexes(entries, baseIndex) {
+  for (let k = 0; k < entries.length; k++) {
+    const entry = entries[k];
+    const idx = baseIndex + k;
     entry.searchTokens = [...new Set(entry.fields.flatMap(f => tokens(f)))];
     for (const t of entry.searchTokens) {
       if (!searchTokenIndex.has(t)) searchTokenIndex.set(t, []);
-      searchTokenIndex.get(t).push(i);
+      searchTokenIndex.get(t).push(idx);
       for (let sz = 1; sz <= Math.min(t.length, 6); sz++) {
         const pfx = t.slice(0, sz);
         if (!searchPrefixIndex.has(pfx)) searchPrefixIndex.set(pfx, []);
-        searchPrefixIndex.get(pfx).push(i);
+        searchPrefixIndex.get(pfx).push(idx);
       }
     }
-  });
+  }
 }
 
 function candidateIndexes(query) {
@@ -1508,22 +1526,54 @@ queryInput.addEventListener("keydown", (e) => {
 });
 
 /* ── Hash navigation ──────────────────────────────────────────────── */
+let intrinsicsReady = null;  // resolved by Phase-2 bootstrap
+
+function _hashEntry(key) {
+  if (!catalog || !key) return null;
+  return resultPool.find(e => e.key === key)
+    || (catalog.intrByName && catalog.intrByName[key] ? {kind: "intrinsic", key, title: key, subtitle: catalog.intrByName[key].subtitle || "", item: catalog.intrByName[key], fields: catalog.intrByName[key].search_fields || []} : null)
+    || (catalog.instrByKey && catalog.instrByKey[key] ? {kind: "instruction", key, title: catalog.instrByKey[key].display_key || key, subtitle: catalog.instrByKey[key].summary || "", item: catalog.instrByKey[key], fields: catalog.instrByKey[key].search_fields || []} : null);
+}
+
 window.addEventListener("hashchange", () => {
   const key = decodeURIComponent(location.hash.replace(/^#/, ""));
   if (!catalog || !key) return;
-  const entry = resultPool.find(e => e.key === key)
-    || (catalog.intrByName[key] ? {kind: "intrinsic", key, title: key, subtitle: catalog.intrByName[key].subtitle || "", item: catalog.intrByName[key], fields: catalog.intrByName[key].search_fields || []} : null)
-    || (catalog.instrByKey[key] ? {kind: "instruction", key, title: catalog.instrByKey[key].display_key || key, subtitle: catalog.instrByKey[key].summary || "", item: catalog.instrByKey[key], fields: catalog.instrByKey[key].search_fields || []} : null);
-  if (entry) renderDetail(entry);
+  let entry = _hashEntry(key);
+  if (entry) { renderDetail(entry); return; }
+  // Hash may name an intrinsic that Phase 2 hasn't ingested yet.
+  if (intrinsicsReady) {
+    intrinsicsReady.then(() => {
+      const retry = _hashEntry(key);
+      if (retry) renderDetail(retry);
+    });
+  }
+});
+
+/* ── Bootstrap ──────────────────────────────────────────────────────
+ *
+ * Two-phase load:
+ *   Phase 1  — meta + filter_spec + build_stamp + instructions. These
+ *              are small (~1 MB gz total) and let us paint the UI with
+ *              the instruction pool searchable immediately.
+ *   Phase 2  — intrinsics (~1.7 MB gz). Fetched in parallel from boot,
+ *              joined into the search index in idle-time batches so the
+ *              page stays responsive while ~93 k entries hydrate.
+ */
+const _intrinsicsFetch = fetchJson("search-index-intrinsics.json").catch((err) => {
+  console.error("simdref: failed to load intrinsic search shard", err);
+  return null;
 });
 
-/* ── Bootstrap ────────────────────────────────────────────────────── */
 Promise.all([
-  fetchJson("search-index.json"),
+  fetchJson("search-index-meta.json"),
+  fetchJson("search-index-instructions.json"),
   fetchJson("filter_spec.json").catch(() => null),
   fetchJson("build_stamp.json").catch(() => null),
 ])
-  .then(([data, spec, stamp]) => {
+  .then(([meta, instructions, spec, stamp]) => {
+    const data = meta || {};
+    data.instructions = instructions || [];
+    data.intrinsics = [];  // populated in Phase 2
     catalog = data;
     // Prefer filter_spec.json (single source of truth) over embedded isa_config.
     const config = spec || data.isa_config || {};
@@ -1541,25 +1591,24 @@ Promise.all([
       metaNode.dataset.stamp = label;
       if (stale) metaNode.classList.add("stale");
     }
-    catalog.intrByName = Object.fromEntries(data.intrinsics.map(i => [i.name, i]));
+    catalog.intrByName = Object.create(null);
     catalog.instrByKey = Object.fromEntries(data.instructions.map(i => [i.key, i]));
     catalog.instrByDisplayKey = Object.fromEntries(data.instructions.map(i => [i.display_key || i.key, i]));
     catalog.instrByMnem = Object.fromEntries(data.instructions.map(i => [i.mnemonic, i]));
 
-    searchEntries = [
-      ...data.intrinsics.map(i => ({
-        kind: "intrinsic", key: i.name, title: i.name, subtitle: i.subtitle || i.description || "", item: i,
-        fields: i.search_fields || [i.name, i.description || "", i.display_isa || displayIsa(i.isa), (i.instructions || []).join(" ")],
-      })),
-      ...data.instructions.map(i => ({
-        kind: "instruction", key: i.key, title: i.display_key || i.key, subtitle: i.summary || "", item: i,
-        fields: i.search_fields || [i.display_mnemonic || i.mnemonic || "", i.display_form || i.form || "", i.summary || "", i.display_isa || displayIsa(i.isa)],
-      })),
-    ];
+    searchEntries = data.instructions.map(i => ({
+      kind: "instruction", key: i.key, title: i.display_key || i.key, subtitle: i.summary || "", item: i,
+      fields: i.search_fields || [i.display_mnemonic || i.mnemonic || "", i.display_form || i.form || "", i.summary || "", i.display_isa || displayIsa(i.isa)],
+    }));
 
     buildSearchIndexes(searchEntries);
 
-    availableIsas = [...new Set(searchEntries.flatMap(e => e.item.isa_families || []))]
+    // Seed the filter chips from the meta shard so the union of ISA
+    // families is correct from first paint, not just instruction families.
+    const seededIsas = Array.isArray(data.available_isas) && data.available_isas.length
+      ? data.available_isas
+      : [...new Set(searchEntries.flatMap(e => e.item.isa_families || []))];
+    availableIsas = [...new Set(seededIsas)]
       .sort((a, b) => (isaFamilyOrder[a] ?? 99) - (isaFamilyOrder[b] ?? 99) || a.localeCompare(b));
     enabledIsas = new Set([...defaultEnabledIsas].filter(v => availableIsas.includes(v)));
     initEnabledSubIsas();
@@ -1588,12 +1637,16 @@ Promise.all([
     // Build-stamp badge text is set above if a stamp is present; only fall
     // back to the catalog-size summary when no stamp was emitted.
     if (!metaNode.dataset.stamp) {
-      metaNode.textContent = `${data.intrinsics.length} intrinsics \u00b7 ${data.instructions.length} instructions`;
+      // Intrinsic count is filled in by Phase 2 once the shard arrives.
+      metaNode.textContent = `${data.instructions.length} instructions`;
     }
 
     const fromHash = decodeURIComponent(location.hash.replace(/^#/, ""));
     if (fromHash) queryInput.value = fromHash;
     renderResults();
+
+    // Phase 2: fold intrinsics into the search index without blocking.
+    intrinsicsReady = _ingestIntrinsics(metaNode);
   })
   .catch((err) => {
     // Fetch failure (CORS, 404, gzip misconfig) should not leave "Loading..." up forever.
@@ -1606,6 +1659,80 @@ Promise.all([
     }
   });
 
+/* Phase 2 — fold the intrinsic shard into searchEntries / search index in
+ * idle-time batches so the main thread keeps responding to scrolls and
+ * keystrokes. Resolves once every intrinsic is searchable. */
+function _ingestIntrinsics(metaNode) {
+  const BATCH = 5000;
+  const schedule = window.requestIdleCallback
+    ? (cb) => window.requestIdleCallback(cb, {timeout: 250})
+    : (cb) => setTimeout(cb, 0);
+
+  // Badge: surface to the user that intrinsics are still streaming in.
+  let badge = null;
+  const savedStamp = metaNode ? metaNode.dataset.stamp || "" : "";
+  if (metaNode) {
+    badge = document.createElement("span");
+    badge.className = "meta-loading";
+    badge.style.marginLeft = "0.5rem";
+    badge.style.color = "var(--text-muted, #888)";
+    badge.textContent = "loading intrinsics…";
+    metaNode.appendChild(badge);
+  }
+
+  return _intrinsicsFetch.then(intrinsics => new Promise(resolve => {
+    if (!Array.isArray(intrinsics) || !intrinsics.length) {
+      if (badge && badge.parentNode) badge.parentNode.removeChild(badge);
+      resolve();
+      return;
+    }
+    catalog.intrinsics = intrinsics;
+    for (const item of intrinsics) catalog.intrByName[item.name] = item;
+
+    let cursor = 0;
+    const total = intrinsics.length;
+    const pump = () => {
+      const stop = Math.min(cursor + BATCH, total);
+      const batch = [];
+      for (let i = cursor; i < stop; i++) {
+        const item = intrinsics[i];
+        batch.push({
+          kind: "intrinsic",
+          key: item.name,
+          title: item.name,
+          subtitle: item.subtitle || item.description || "",
+          item,
+          fields: item.search_fields || [item.name, item.description || "", item.display_isa || displayIsa(item.isa), (item.instructions || []).join(" ")],
+        });
+      }
+      const base = searchEntries.length;
+      for (const e of batch) searchEntries.push(e);
+      extendSearchIndexes(batch, base);
+      if (bucketsBuilt) extendBuckets(batch, base);
+      cursor = stop;
+
+      // Re-render if the user is already typing or the visible list is
+      // short enough that new hits would actually show up.
+      visibleSet = null;
+      if ((queryInput && queryInput.value) || resultPool.length < 100) {
+        renderResults();
+      }
+
+      if (cursor < total) {
+        schedule(pump);
+      } else {
+        if (badge && badge.parentNode) badge.parentNode.removeChild(badge);
+        if (metaNode && !metaNode.dataset.stamp) {
+          metaNode.textContent = `${total} intrinsics · ${(catalog.instructions || []).length} instructions`;
+        }
+        renderResults();
+        resolve();
+      }
+    };
+    schedule(pump);
+  }));
+}
+
 /* ── Annotate tab ────────────────────────────────────────────────────
  * Client-side port of src/simdref/annotate.py. Reuses the existing
  * fetchJson, chunkPrefix, loadChunk helpers. Zero backend.