dbdocs 1.0.1__tar.gz → 1.1.0__tar.gz

{dbdocs-1.0.1 → dbdocs-1.1.0}/.gitignore

@@ -152,6 +152,8 @@ frontend/dist/
 frontend/.vite/
 frontend/coverage/
 frontend/*.tsbuildinfo
+frontend/test-results/
+frontend/playwright-report/
 .eslintcache
 
 # npm / yarn / pnpm logs & debug output
@@ -166,3 +168,4 @@ pnpm-debug.log*
 
 # dbdocs DEBUG file log
 logs/
+.DS_Store

{dbdocs-1.0.1 → dbdocs-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbdocs
-Version: 1.0.1
+Version: 1.1.0
 Summary: Alternative dbt docs site: Catalog + ERD + column-level lineage
 Project-URL: Homepage, https://github.com/datnguye/dbt-docs
 Project-URL: Repository, https://github.com/datnguye/dbt-docs
@@ -27,7 +27,7 @@ Description-Content-Type: text/markdown
 <p align="center"><b>An alternative dbt docs site — catalog + ERD + column-level lineage, baked into one file.</b></p>
 
 <p align="center">
-  <a href="https://dbdocs.datnguye.me/latest/demo/"><img src="https://img.shields.io/badge/live-demo-FF694A?style=flat&logo=rocket&logoColor=white" alt="live demo"></a>
+  <a href="https://dbdocs.datnguye.me/latest/demo/latest/"><img src="https://img.shields.io/badge/live-demo-FF694A?style=flat&logo=rocket&logoColor=white" alt="live demo"></a>
   <a href="https://dbdocs.datnguye.me/"><img src="https://img.shields.io/badge/docs-visit%20site-blue?style=flat&logo=gitbook&logoColor=white" alt="docs"></a>
   <a href="https://pypi.org/project/dbdocs/"><img src="https://badge.fury.io/py/dbdocs.svg" alt="PyPI version"></a>
   <img src="https://img.shields.io/badge/CLI-Python-FFCE3E?labelColor=14354C&logo=python&logoColor=white" alt="python-cli">

{dbdocs-1.0.1 → dbdocs-1.1.0}/README.md

@@ -5,7 +5,7 @@
 <p align="center"><b>An alternative dbt docs site — catalog + ERD + column-level lineage, baked into one file.</b></p>
 
 <p align="center">
-  <a href="https://dbdocs.datnguye.me/latest/demo/"><img src="https://img.shields.io/badge/live-demo-FF694A?style=flat&logo=rocket&logoColor=white" alt="live demo"></a>
+  <a href="https://dbdocs.datnguye.me/latest/demo/latest/"><img src="https://img.shields.io/badge/live-demo-FF694A?style=flat&logo=rocket&logoColor=white" alt="live demo"></a>
   <a href="https://dbdocs.datnguye.me/"><img src="https://img.shields.io/badge/docs-visit%20site-blue?style=flat&logo=gitbook&logoColor=white" alt="docs"></a>
   <a href="https://pypi.org/project/dbdocs/"><img src="https://badge.fury.io/py/dbdocs.svg" alt="PyPI version"></a>
   <img src="https://img.shields.io/badge/CLI-Python-FFCE3E?labelColor=14354C&logo=python&logoColor=white" alt="python-cli">

{dbdocs-1.0.1 → dbdocs-1.1.0}/dbdocs/cli/main.py

@@ -40,7 +40,7 @@ def dbdocs(ctx, config_path):
 )
 @click.pass_obj
 def generate(config: DbDocsConfig, output_dir, dialect):
-    """Build the self-contained site from dbt artifacts."""
+    """Build the site from dbt artifacts (served over HTTP; data loaded externally)."""
     if dialect is not None:
         config.dialect = dialect
     try:

{dbdocs-1.0.1 → dbdocs-1.1.0}/dbdocs/core/config.py

@@ -49,6 +49,13 @@ class DbDocsConfig:
     #: Project README rendered on the overview (relative to the working dir). Set
     #: empty to omit the README section. Missing file ⇒ section simply absent.
     readme: str = "README.md"
+    #: Custom header logo (path relative to the working dir). Empty ⇒ the bundled
+    #: default mark. A missing file or a path escaping the cwd is ignored
+    #: (fail-soft, like ``readme``) ⇒ the default mark.
+    logo: str = ""
+    #: Custom favicon (path relative to the working dir). Empty ⇒ the bundled
+    #: default favicon. Same fail-soft handling as ``logo``.
+    favicon: str = ""
     target_dir: str = "target"
     #: Where the generated site is written. Nested under the dbt ``target/`` by
     #: default so docs sit alongside the artifacts they're built from.
@@ -92,6 +99,8 @@ class DbDocsConfig:
         return cls(**raw)
 
     #: Build-control fields that are not part of the site's display metadata.
+    #: ``logo``/``favicon`` are excluded too — they're *source* paths; the builder
+    #: copies the files into the output and injects their *deployed* asset URLs.
     _NON_METADATA_FIELDS = (
         "target_dir",
         "output_dir",
@@ -99,6 +108,8 @@ class DbDocsConfig:
         "default_version",
         "dbterd",
         "readme",
+        "logo",
+        "favicon",
     )
 
     def render_context(self) -> dict:

{dbdocs-1.0.1 → dbdocs-1.1.0}/dbdocs/extract/column_lineage.py

@@ -12,6 +12,7 @@ must never sink the whole ``generate`` — it's caught, logged, and skipped, and
 the run reports how many were skipped.
 """
 
+from concurrent.futures import ProcessPoolExecutor
 from typing import Any
 
 from sqlglot import exp
@@ -27,6 +28,14 @@ _DIALECT_ALIASES = {
     "databricks": "spark",
 }
 
+#: Parse + qualify is CPU-bound and embarrassingly parallel across models. Below
+#: this model count the ProcessPoolExecutor's spawn + pickle overhead outweighs
+#: the win, so we stay serial; at or above it we fan out across cores.
+_PARALLEL_THRESHOLD = 500
+
+#: Errors a single model's lineage may raise that must not sink the whole run.
+_MODEL_ERRORS = (SqlglotError, LineageError, KeyError, ValueError, RecursionError)
+
 
 def _to_dialect(adapter_type: "str | None") -> "str | None":
     if not adapter_type:
@@ -34,6 +43,95 @@ def _to_dialect(adapter_type: "str | None") -> "str | None":
     return _DIALECT_ALIASES.get(adapter_type, adapter_type)
 
 
+def _map_table(table: exp.Table, relation_to_node: dict) -> "str | None":
+    """Map a sqlglot ``Table`` to a dbt unique_id via the relation index."""
+    candidates = [
+        f"{table.catalog}.{table.db}.{table.name}",
+        f"{table.db}.{table.name}",
+        table.name,
+    ]
+    for candidate in candidates:
+        mapped = relation_to_node.get(candidate.lower().strip("."))
+        if mapped:
+            return mapped
+    return None
+
+
+def _leaf_columns(root: Node, relation_to_node: dict) -> list:
+    """Collect distinct upstream ``{node, column}`` leaves of a lineage tree.
+
+    A leaf is a node whose source is a real ``Table`` (not a CTE/subquery scope)
+    that maps back to a dbt node. The root itself is skipped.
+    """
+    seen = set()
+    upstream = []
+    for node in root.walk():
+        if node is root:
+            continue
+        source = node.source
+        if not isinstance(source, exp.Table):
+            continue
+        mapped = _map_table(source, relation_to_node)
+        if mapped is None:
+            continue
+        column = node_name(node.name)
+        key = (mapped, column)
+        if key in seen:
+            continue
+        seen.add(key)
+        upstream.append({"node": mapped, "column": column})
+    return upstream
+
+
+def _extract_model_columns(
+    unique_id: str,
+    compiled: str,
+    output_columns: list,
+    schema: dict,
+    dialect: "str | None",
+    relation_to_node: dict,
+) -> dict:
+    """Trace every output column of one model to its upstream columns.
+
+    Pure and picklable (plain str/list/dict args, no manifest/catalog objects) so
+    it runs unchanged in the serial loop or a ``ProcessPoolExecutor`` worker.
+    Builds the scope once per model — qualify is the expensive part and is
+    identical for every column — then traces each column against it.
+    """
+    out: dict = {}
+    scope = prepare_scope(compiled, schema=schema, dialect=dialect)
+    for column in output_columns:
+        try:
+            root = lineage(column, compiled, dialect=dialect, scope=scope)
+        except SqlglotError:
+            # One unresolvable column shouldn't drop the rest of the model.
+            continue
+        upstream = _leaf_columns(root, relation_to_node)
+        if upstream:
+            out[f"{unique_id}.{column}"] = upstream
+    return out
+
+
+def _extract_model_task(work: tuple) -> tuple:
+    """Worker wrapper: returns ``(unique_id, columns_map, error_str_or_None)``.
+
+    Catching here (rather than letting the exception cross the process boundary)
+    keeps the fail-soft contract: one unparseable model is reported and skipped,
+    never sinking the pool.
+    """
+    unique_id, compiled, output_columns, schema, dialect, relation_to_node = work
+    try:
+        return (
+            unique_id,
+            _extract_model_columns(
+                unique_id, compiled, output_columns, schema, dialect, relation_to_node
+            ),
+            None,
+        )
+    except _MODEL_ERRORS as exc:
+        return unique_id, {}, str(exc)
+
+
 class ColumnLineageExtractor:
     """Build the ``columnLineage`` map for a dbt project's models.
 
@@ -54,86 +152,74 @@ class ColumnLineageExtractor:
         self.skipped = 0
 
     def extract(self) -> dict:
-        """Return the ``columnLineage`` map across all models (fail-soft)."""
+        """Return the ``columnLineage`` map across all models (fail-soft).
+
+        Runs serially for small projects; fans the per-model sqlglot work across
+        processes once a project has ``_PARALLEL_THRESHOLD`` models or more, where
+        the CPU-bound parse/qualify dominates the pool's spawn cost.
+        """
+        work = self._work_items()
+        if not work:
+            return {}
+        if len(work) >= _PARALLEL_THRESHOLD:
+            results = self._extract_parallel(work)
+        else:
+            results = (_extract_model_task(item) for item in work)
+
         result: dict = {}
+        for unique_id, columns, error in results:
+            if error is not None:
+                self.skipped += 1
+                logger.warning("Column lineage skipped for %s: %s", node_name(unique_id), error)
+                continue
+            result.update(columns)
+        if self.skipped:
+            logger.info("Column lineage: skipped %s model(s) that failed to parse.", self.skipped)
+        return result
+
+    def _extract_parallel(self, work: list) -> list:
+        """Run the per-model tasks across a process pool, returning their results."""
+        with ProcessPoolExecutor() as pool:
+            return list(pool.map(_extract_model_task, work))
+
+    def _work_items(self) -> list:
+        """Build the picklable per-model work tuples for the (serial or pool) run.
+
+        Each item is ``(unique_id, compiled, output_columns, schema, dialect,
+        relation_to_node)`` — all plain str/list/dict, so it crosses a process
+        boundary cleanly (the Pydantic manifest/catalog never do).
+        """
+        work = []
         for unique_id, model in (getattr(self.manifest, "nodes", {}) or {}).items():
             if not str(unique_id).startswith("model."):
                 continue
             compiled = getattr(model, "compiled_code", "") or ""
             if not compiled.strip():
                 continue
-            try:
-                self._extract_model(unique_id, compiled, result)
-            except (SqlglotError, LineageError, KeyError, ValueError, RecursionError) as exc:
-                self.skipped += 1
-                logger.warning("Column lineage skipped for %s: %s", node_name(unique_id), exc)
-        if self.skipped:
-            logger.info("Column lineage: skipped %s model(s) that failed to parse.", self.skipped)
-        return result
+            output_columns = self._output_columns(unique_id, model)
+            if not output_columns:
+                continue
+            work.append(
+                (
+                    unique_id,
+                    compiled,
+                    output_columns,
+                    self.schema,
+                    self.dialect,
+                    self._relation_to_node,
+                )
+            )
+        return work
 
-    def _extract_model(self, unique_id: str, compiled: str, result: dict) -> None:
-        node = self.manifest.nodes[unique_id]
-        output_columns = [c for c in (getattr(node, "columns", {}) or {})]
-        # Fall back to the catalog's column list when the manifest has none.
+    def _output_columns(self, unique_id: str, model: Any) -> list:
+        """The model's documented columns, falling back to the catalog's list."""
+        output_columns = [c for c in (getattr(model, "columns", {}) or {})]
         if not output_columns:
             catalog_node = (getattr(self.catalog, "nodes", {}) or {}).get(unique_id)
             output_columns = (
                 list(getattr(catalog_node, "columns", {}) or {}) if catalog_node else []
             )
-        if not output_columns:
-            return
-        # Build the scope once per model, then trace each column against it —
-        # qualify is the expensive part and is identical for every column.
-        scope = prepare_scope(compiled, schema=self.schema, dialect=self.dialect)
-        for column in output_columns:
-            try:
-                root = lineage(column, compiled, dialect=self.dialect, scope=scope)
-            except SqlglotError:
-                # One unresolvable column shouldn't drop the rest of the model.
-                continue
-            upstream = self._leaf_columns(root)
-            if upstream:
-                result[f"{unique_id}.{column}"] = upstream
-
-    def _leaf_columns(self, root: Node) -> list:
-        """Collect distinct upstream ``{node, column}`` leaves of a lineage tree.
-
-        A leaf is a node whose source is a real ``Table`` (not a CTE/subquery
-        scope) that we can map back to a dbt node. The root itself is skipped.
-        """
-        seen = set()
-        upstream = []
-        for node in root.walk():
-            if node is root:
-                continue
-            source = node.source
-            if not isinstance(source, exp.Table):
-                continue
-            mapped = self._map_table(source)
-            if mapped is None:
-                continue
-            column = node_name(node.name)
-            key = (mapped, column)
-            if key in seen:
-                continue
-            seen.add(key)
-            upstream.append({"node": mapped, "column": column})
-        return upstream
-
-    def _map_table(self, table: exp.Table) -> "str | None":
-        catalog = table.catalog
-        db = table.db
-        name = table.name
-        candidates = [
-            f"{catalog}.{db}.{name}",
-            f"{db}.{name}",
-            name,
-        ]
-        for candidate in candidates:
-            mapped = self._relation_to_node.get(candidate.lower().strip("."))
-            if mapped:
-                return mapped
-        return None
+        return output_columns
 
     def _relation_index(self) -> dict:
         """Map ``db.schema.table`` (and shorter forms) → dbt unique_id."""

{dbdocs-1.0.1 → dbdocs-1.1.0}/dbdocs/extract/erd.py

@@ -9,12 +9,21 @@ foreign-key edges between them, all keyed by dbt unique_id.
 
 import json
 
-from dbterd.api import DbtErd
+from dbterd.api import DbtErd, default
 
 # Importing the module registers the "json" target with dbterd's PluginRegistry.
 from dbdocs.extract import erd_json  # noqa: F401
 
 
+def erd_algo(dbterd_options: "dict | None" = None) -> str:
+    """The dbterd algorithm that detected the ERD relationships.
+
+    Reads the configured ``algo`` from the ``dbterd:`` block, falling back to
+    dbterd's own default. Surfaced into the SPA so it can explain an empty ERD.
+    """
+    return (dbterd_options or {}).get("algo") or default.default_algo()
+
+
 def build_erd(dbterd_options: "dict | None" = None, artifacts_dir: "str | None" = None) -> DbtErd:
     """Build the ERD generator (json target) from dbdocs' ``dbterd`` options.
 

{dbdocs-1.0.1 → dbdocs-1.1.0}/dbdocs/extract/nodes.py

@@ -12,27 +12,52 @@ from typing import Any
 from dbdocs.core.artifacts import NODE_PREFIXES, db_schema, node_name
 
 
+def _column_entry(name: str, manifest_column: Any, col_type: str) -> dict:
+    """One column record. Newlines in the description become ``<br>`` for HTML."""
+    description = getattr(manifest_column, "description", "") or "" if manifest_column else ""
+    return {
+        "name": name,
+        "type": col_type or "",
+        "tags": (getattr(manifest_column, "tags", []) or []) if manifest_column else [],
+        "description": description.replace("\n", "<br>"),
+    }
+
+
 def _columns(model: Any, catalog_node: Any) -> list:
-    """Merge manifest column metadata (description/tags) with catalog types.
+    """Build a node's columns: the manifest is the source of truth, the catalog
+    enriches it.
+
+    The **manifest** decides which columns are documented and carries their
+    metadata (description, tags, ``data_type``); the **catalog** *enriches* — it
+    supplies the warehouse-confirmed type and any columns the manifest didn't
+    document. It never replaces the manifest, so a model absent from a
+    stale/partial ``catalog.json`` still shows every documented column.
 
-    Iterates the catalog's columns (the warehouse truth for which columns exist
-    and their types) and layers on the manifest description/tags when present.
-    Newlines in descriptions become ``<br>`` so they survive HTML rendering.
+    Manifest columns come first, in manifest order, each with its type enriched
+    from the catalog when present (falling back to the manifest ``data_type``).
+    The catalog keys columns by the warehouse's casing (Snowflake upper-cases
+    them) while the manifest keeps the modeled casing, so the catalog type lookup
+    is case-insensitive. Catalog-only columns are appended afterwards.
     """
     manifest_columns = getattr(model, "columns", {}) or {}
     catalog_columns = getattr(catalog_node, "columns", {}) or {} if catalog_node else {}
+    catalog_by_lower = {str(name).lower(): col for name, col in catalog_columns.items()}
+
     columns = []
-    for name in catalog_columns:
-        manifest_column = manifest_columns.get(name)
-        description = getattr(manifest_column, "description", "") or "" if manifest_column else ""
-        columns.append(
-            {
-                "name": name,
-                "type": catalog_columns[name].type,
-                "tags": (getattr(manifest_column, "tags", []) or []) if manifest_column else [],
-                "description": description.replace("\n", "<br>"),
-            }
+    seen_lower = set()
+    for name, manifest_column in manifest_columns.items():
+        lower = str(name).lower()
+        seen_lower.add(lower)
+        catalog_column = catalog_by_lower.get(lower)
+        col_type = getattr(catalog_column, "type", None) or getattr(
+            manifest_column, "data_type", None
         )
+        columns.append(_column_entry(name, manifest_column, col_type or ""))
+
+    for name, catalog_column in catalog_columns.items():
+        if str(name).lower() in seen_lower:
+            continue
+        columns.append(_column_entry(name, None, getattr(catalog_column, "type", "") or ""))
     return columns
 
 

{dbdocs-1.0.1 → dbdocs-1.1.0}/dbdocs/site/builder.py

@@ -6,10 +6,11 @@ column-level lineage, ERDs, nav tree) → stage the bundled SPA → base64-injec
 data → write ``index.html`` + a debug ``dbdocs-data.json``.
 """
 
+import gzip
 import json
 from datetime import datetime
 from pathlib import Path
-from shutil import copytree, rmtree
+from shutil import copyfile, copytree, rmtree
 from typing import Any
 
 from dbdocs.core.artifacts import adapter_type, load_artifacts
@@ -17,10 +18,10 @@ from dbdocs.core.config import DbDocsConfig, _resolve_within_cwd
 from dbdocs.core.exceptions import DbDocsConfigError
 from dbdocs.core.log import logger
 from dbdocs.extract.column_lineage import ColumnLineageExtractor
-from dbdocs.extract.erd import build_erd, build_erd_data
+from dbdocs.extract.erd import build_erd, build_erd_data, erd_algo
 from dbdocs.extract.graph import LineageGraph
 from dbdocs.extract.nodes import build_nodes, build_tree
-from dbdocs.site.inject import inject
+from dbdocs.site.inject import strip_marker
 
 #: The bundled SPA (shell + assets), shipped in the wheel.
 BUNDLE_DIR = Path(__file__).resolve().parent / "bundle"
@@ -54,6 +55,7 @@ class ReportBuilder:
                 "generated_at": datetime.now().isoformat(sep=" ", timespec="seconds"),
                 "adapter_type": adapter,
                 "dialect": dialect,
+                "erd_algo": erd_algo(self.config.dbterd),
                 "counts": self._counts(manifest),
             },
             "nodes": nodes,
@@ -82,6 +84,40 @@ class ReportBuilder:
         except OSError:
             return ""
 
+    def _stage_branding(self, out: Path) -> dict:
+        """Copy any custom logo/favicon into the output and return their metadata.
+
+        Returns a dict with ``logo`` / ``favicon`` keys set to the deployed asset
+        URL (e.g. ``assets/logo.png``) for each override that resolved to a real
+        file. Absent/unresolvable overrides are simply omitted — the SPA then
+        keeps the bundled default. Fail-soft, mirroring ``_read_readme``.
+        """
+        meta: dict = {}
+        for field_name in ("logo", "favicon"):
+            url = self._copy_branding_asset(getattr(self.config, field_name), field_name, out)
+            if url:
+                meta[field_name] = url
+        return meta
+
+    @staticmethod
+    def _copy_branding_asset(source: str, name: str, out: Path) -> str:
+        """Copy *source* into ``out/assets`` as ``<name><ext>``; return its URL.
+
+        ``""`` for an empty config value, a path escaping the cwd, or a missing
+        file (fail-soft — bad branding must never sink generate).
+        """
+        if not source:
+            return ""
+        try:
+            path = _resolve_within_cwd(source, name)
+        except DbDocsConfigError:
+            return ""
+        if not path.is_file():
+            return ""
+        target_name = f"{name}{path.suffix}"
+        copyfile(path, out / "assets" / target_name)
+        return f"assets/{target_name}"
+
     #: Manifest collections that aren't keyed by a ``<type>.`` unique_id prefix,
     #: mapped to the resource-type label to report them under.
     _MANIFEST_COLLECTIONS = {
@@ -112,7 +148,15 @@ class ReportBuilder:
         return counts
 
     def generate(self, output_dir: "str | None" = None) -> str:
-        """Render the site into ``output_dir`` (or config's). Returns its path."""
+        """Render the site into ``output_dir`` (or config's). Returns its path.
+
+        The data dict is written as an external ``dbdocs-data.json.gz`` that the
+        SPA fetches at load — never inlined into ``index.html``. This keeps the
+        HTML tiny regardless of project size, where a multi-MB inlined base64
+        payload would otherwise make the page slow to parse. The site must be
+        served over HTTP (``dbdocs serve`` or any static host); a plain
+        ``dbdocs-data.json`` is written alongside for debugging.
+        """
         out = Path(output_dir) if output_dir else Path(self.config.output_path)
         if out.exists():
             rmtree(out)
@@ -120,13 +164,18 @@ class ReportBuilder:
         copytree(src=BUNDLE_DIR, dst=out, dirs_exist_ok=True)
 
         data = self.build_data()
+        data["metadata"].update(self._stage_branding(out))
         index = out / "index.html"
-        index.write_text(inject(index.read_text(encoding="utf-8"), data), encoding="utf-8")
-        # Compact, not indented — keeps the debug dump cheap on large projects.
-        (out / "dbdocs-data.json").write_text(
-            json.dumps(data, separators=(",", ":"), sort_keys=True, default=self._json_default),
-            encoding="utf-8",
-        )
+        index.write_text(strip_marker(index.read_text(encoding="utf-8")), encoding="utf-8")
+        # Serialize once (compact, not indented — keeps it cheap on large
+        # projects); write the plain debug dump and the gzipped payload the SPA
+        # fetches.
+        payload = json.dumps(
+            data, separators=(",", ":"), sort_keys=True, default=self._json_default
+        ).encode("utf-8")
+        (out / "dbdocs-data.json").write_bytes(payload)
+        # mtime=0 keeps the gzip header byte-for-byte reproducible across runs.
+        (out / "dbdocs-data.json.gz").write_bytes(gzip.compress(payload, mtime=0))
 
         logger.info(
             "Generated site at %s (%s nodes, %s column-lineage edges).",

{dbdocs-1.0.1/dbdocs/site/bundle/assets → dbdocs-1.1.0/dbdocs/site/bundle/assets/css}/style.css

@@ -53,7 +53,11 @@ code, pre { font-family: "SF Mono", "Roboto Mono", Menlo, Consolas, monospace; }
   position: sticky; top: 0; z-index: 30;
 }
 .brand { display: flex; align-items: center; gap: 8px; font-weight: 600; min-width: 160px; }
-.brand-mark { display: block; width: 24px; height: 24px; border-radius: 6px; }
+/* The logo + name link home (catalog overview). */
+.brand-home { display: flex; align-items: center; gap: 8px; color: var(--text); }
+.brand-home:hover { text-decoration: none; color: var(--accent); }
+.brand-mark { display: block; width: 24px; height: 24px; border-radius: 6px; align-self: center; }
+.brand-generated { color: var(--text-soft); font-size: 12px; font-weight: 400; white-space: nowrap; }
 .search-wrap { position: relative; flex: 1; max-width: 520px; }
 #search {
   width: 100%; padding: 7px 12px; border-radius: var(--radius);
@@ -118,21 +122,16 @@ code, pre { font-family: "SF Mono", "Roboto Mono", Menlo, Consolas, monospace; }
 }
 .footer-copy { color: var(--text-soft); font-size: 12px; }
 
-/* Build metadata in the header (generated / adapter / edges) */
-.topbar-meta {
-  color: var(--text-soft); font-size: 11.5px; white-space: nowrap;
-  padding-right: 6px; flex-shrink: 0;
-}
-@media (max-width: 1100px) { .topbar-meta { display: none; } }
-
 /* End-of-page content footer */
 .content-foot {
   display: flex; align-items: center; justify-content: space-between; gap: 12px;
   margin-top: 40px; padding-top: 16px; border-top: 1px solid var(--border);
   color: var(--text-soft); font-size: 12px;
 }
-.content-foot .cf-left { display: inline-flex; align-items: center; gap: 6px; }
+.content-foot .cf-left { display: inline-flex; align-items: center; gap: 6px; flex-wrap: wrap; }
 .content-foot .cf-left .ic { color: var(--text-soft); }
+/* Build metadata (generated / adapter / edges) appended to the footer's left */
+.content-foot .cf-meta { color: var(--text-soft); }
 .content-foot .cf-top { color: var(--text-soft); }
 .content-foot .cf-top:hover { color: var(--accent); }
 .bmc {
@@ -212,6 +211,14 @@ th, td { text-align: left; padding: 7px 10px; border-bottom: 1px solid var(--bor
 th { color: var(--text-soft); font-weight: 600; font-size: 12px; text-transform: uppercase; letter-spacing: .03em; }
 td code { background: var(--code-bg); padding: 1px 5px; border-radius: 4px; }
 
+/* Briefly highlight a column row deep-linked from an upstream-lineage chip. */
+tr.col-flash > td { background: var(--accent-soft); }
+tr.col-flash { animation: col-flash-fade 1.6s ease-out; }
+@keyframes col-flash-fade {
+  0% { background: var(--accent-soft); }
+  100% { background: transparent; }
+}
+
 /* Tabs */
 .tabs { display: flex; gap: 4px; border-bottom: 1px solid var(--border); margin-top: 8px; }
 .tab { padding: 6px 14px; cursor: pointer; border: 1px solid transparent; border-bottom: none; border-radius: 6px 6px 0 0; color: var(--text-soft); }
@@ -287,3 +294,61 @@ details.macro pre.code { margin: 0; border: none; border-top: 1px solid var(--bo
 .markdown-body th { background: var(--bg-soft); }
 .markdown-body img { max-width: 100%; height: auto; border-radius: 6px; }
 .markdown-body hr { border: none; border-top: 1px solid var(--border); margin: 20px 0; }
+
+/* Hamburger + search toggle — hidden on desktop, revealed on phones below. */
+.nav-toggle { display: none; font-size: 18px; }
+.search-toggle { display: none; }
+/* Backdrop behind the off-canvas sidebar drawer. */
+.nav-overlay {
+  position: fixed; inset: 52px 0 0 0; z-index: 25;
+  background: rgba(0, 0, 0, 0.4);
+}
+
+/* Responsive: collapse the fixed sidebar into a drawer, reflow the topbar, and
+   let wide tables scroll instead of overflowing the viewport. */
+@media (max-width: 768px) {
+  .nav-toggle { display: inline-flex; }
+  .brand { min-width: 0; }
+  .layout { height: calc(100vh - 52px); }
+  /* Sidebar becomes an off-canvas drawer, slid in when body.nav-open is set. */
+  .sidebar-col {
+    position: fixed; top: 52px; bottom: 0; left: 0; z-index: 26;
+    width: 84vw; max-width: 320px;
+    transform: translateX(-100%); transition: transform 0.2s ease;
+    box-shadow: var(--shadow);
+  }
+  body.nav-open .sidebar-col { transform: translateX(0); }
+  .content { padding: 20px 16px; }
+  /* Let the columns table scroll horizontally rather than blow out the page. */
+  .content table { display: block; overflow-x: auto; white-space: nowrap; }
+}
+
+/* Phones: the topbar is a single row (hamburger + brand + actions, including a
+   search-toggle icon). The search hides until the icon reveals it as a
+   full-width row underneath, so it never fights the actions for space. */
+@media (max-width: 480px) {
+  .topbar {
+    flex-wrap: wrap; gap: 8px 10px; padding: 8px 10px; height: auto;
+  }
+  .brand-generated { display: none; }
+  /* The long project name forces the actions onto a second row, so on phones
+     keep just the logo mark — the page heading already names the project. */
+  .brand-name { display: none; }
+  .search-toggle { display: inline-flex; }
+  /* Row 1 order: hamburger, brand mark, actions (all fit once the name is out). */
+  .nav-toggle { order: 0; }
+  .brand { order: 1; }
+  .topbar-actions { order: 2; margin-left: auto; }
+  /* The search is its own full-width row, collapsed until toggled open. */
+  .search-wrap {
+    order: 3; flex-basis: 100%; max-width: none;
+    display: none;
+  }
+  body.search-open .search-wrap { display: block; }
+  body.search-open .search-toggle { border-color: var(--accent); color: var(--accent); }
+  /* Drawer/overlay clear the single-row topbar (taller only while search open,
+     where the sticky topbar's higher z-index covers any slight overlap). */
+  .sidebar-col { top: 52px; }
+  .nav-overlay { top: 0; }
+  .content-foot { flex-direction: column; align-items: flex-start; gap: 8px; }
+}