lvkit 0.6.2__tar.gz → 0.6.3__tar.gz

{lvkit-0.6.2 → lvkit-0.6.3}/.gitignore

@@ -133,3 +133,7 @@ experiments/
 
 # Claude Code agent worktrees (transient)
 .claude/worktrees/
+
+# CI deploy keys — never commit
+pragmatest_deploy
+pragmatest_deploy.pub

{lvkit-0.6.2 → lvkit-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lvkit
-Version: 0.6.2
+Version: 0.6.3
 Summary: Understand and convert LabVIEW VIs to Python without a LabVIEW license
 Project-URL: Repository, https://github.com/pragmatest-dev/lvkit
 Project-URL: Issues, https://github.com/pragmatest-dev/lvkit/issues

{lvkit-0.6.2 → lvkit-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lvkit"
-version = "0.6.2"
+version = "0.6.3"
 description = "Understand and convert LabVIEW VIs to Python without a LabVIEW license"
 readme = "README.md"
 requires-python = ">=3.10"

lvkit-0.6.3/scripts/build_example_pages.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Regenerate the pragmatest.com lvkit example pages from PUBLIC sources cloned at
+# build time — no local corpus, no hand-staged fixtures. Every input is a public
+# git ref, so this runs identically on a fresh CI runner and on a dev box.
+#
+#   scripts/build_example_pages.sh <output-dir>
+#
+# Produces, under <output-dir>:
+#   render/testcase.html  — JKI VI Tester TestCase/run.vi @ tag 3.0.0
+#   diff/testcase.html    — that VI 3.0.0 (base) -> 3.0.1 (head)
+#   render/md5.html       — OpenG MD5 Message Digest (Binary String)__ogtk.vi
+#
+# Sources (both OSI-approved, redistributable):
+#   JKI-VI-Tester   BSD-3-Clause   github.com/JKISoftware/JKI-VI-Tester
+#   OpenG Toolkit   BSD-3-Clause   reproduced from upstream .vip via scripts/
+set -euo pipefail
+
+OUT="${1:?usage: build_example_pages.sh <output-dir>}"
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+mkdir -p "$OUT/render" "$OUT/diff"
+OUT="$(cd "$OUT" && pwd)"  # absolute — lvk() renders from $ROOT, OUT must not be relative to it
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+lvk() { ( cd "$ROOT" && uv run lvkit "$@" ); }
+
+# --- JKI VI Tester: TestCase/run.vi at 3.0.0 (base) vs 3.0.1 (head) -----------
+# run_base = the committed run.vi at tag 3.0.0; run_head = the same file at 3.0.1
+# (JKI wrapped several nodes in a new Case between those releases). Both are real
+# public commits — extracted with `git show`, never hand-edited.
+JKI="$WORK/JKI-VI-Tester"
+RUNVI="source/Classes/TestCase/run.vi"
+echo "clone JKI-VI-Tester (BSD-3-Clause)"
+git clone --quiet https://github.com/JKISoftware/JKI-VI-Tester.git "$JKI"
+git -C "$JKI" show 3.0.0:"$RUNVI" > "$WORK/run_base.vi"
+git -C "$JKI" show 3.0.1:"$RUNVI" > "$WORK/run_head.vi"
+
+echo "→ render: testcase  ($OUT/render/testcase.html)"
+lvk render "$WORK/run_base.vi" --format html --search-path "$JKI/source" \
+    --no-cache -o "$OUT/render/testcase.html"
+
+echo "→ diff:   testcase  ($OUT/diff/testcase.html)"
+lvk diff "$WORK/run_base.vi" "$WORK/run_head.vi" --format html \
+    --search-path "$JKI/source" --no-cache -o "$OUT/diff/testcase.html"
+
+# --- OpenG MD5 (BSD-3-Clause), reproduced from upstream .vip packages ---------
+OPENG="$WORK/openg"
+echo "reproduce OpenG corpus (BSD-3-Clause; fetches upstream .vip)"
+uv run python "$ROOT/scripts/reproduce_openg_corpus.py" "$OPENG"
+MD5="$OPENG/File Group 0/user.lib/_OpenG.lib/md5/md5.llb/MD5 Message Digest (Binary String)__ogtk.vi"
+
+echo "→ render: md5       ($OUT/render/md5.html)"
+lvk render "$MD5" --format html --search-path "$OPENG" \
+    --no-cache -o "$OUT/render/md5.html"
+
+echo "done → $OUT"

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/__init__.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "0.6.2"
+__version__ = "0.6.3"
 
 # The public API is exposed LAZILY (PEP 562 module ``__getattr__``): the graph /
 # parser / structure stacks (networkx, pydantic, pylabview, PIL — ~230 ms) load

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/cache_paths.py

@@ -33,6 +33,7 @@ legibly separated at the top.
 
 from __future__ import annotations
 
+import functools
 import hashlib
 import json
 import os
@@ -201,6 +202,60 @@ def sha256_file(path: Path) -> str:
     return hashlib.sha256(Path(path).read_bytes()).hexdigest()
 
 
+# Top-level package subdirs that DEMONSTRABLY feed NO cached artifact — verified
+# absent from the import closure of the fact/render producers and pinned by
+# ``test_facts_fingerprint_skips_only_non_facts_dirs``. Skipping them means
+# editing codegen / docs / the formula transpiler / the MCP transport layer
+# doesn't force a needless rebuild. (Verified: ``render/`` imports none of these
+# — Formula NODES are drawn from graph models, not the ``formula/`` transpiler.)
+#
+# This is an EXCLUDE list on purpose: the default for any file — including a
+# brand-new module or ``data/`` table — is to be hashed, so a new dependency can
+# never silently escape the fingerprint. The only failure mode (a dep ADDED under
+# one of these dirs) trips the guard test, which fails loudly rather than letting
+# staleness back in.
+_FINGERPRINT_SKIP_DIRS = frozenset({"codegen", "docs", "formula", "mcp"})
+
+
+@functools.lru_cache(maxsize=1)
+def source_fingerprint() -> str:
+    """A hash of lvkit's own SOURCE + bundled data, so EVERY derived cache (the
+    SQLite index AND the render/diff output cache) self-invalidates the moment
+    that code changes — with no manual version to bump. This is the SINGLE shared
+    invalidation used by all caches; do not reintroduce a per-cache version.
+
+    A cache keyed only on input VI bytes cannot see a change to lvkit's own logic
+    (the VI bytes are identical) — so an edit to the parser/graph/render/index
+    code, or to a ``data/`` primitive/vilib table, would otherwise keep serving
+    output built by the OLD code. That is silent staleness. A hand-bumped version
+    can't defend against it because in active development the bump is forgotten
+    far more often than not.
+
+    Hashes every file in the package EXCEPT the ``_FINGERPRINT_SKIP_DIRS`` known
+    to feed no cache. Skipping is done by directory (a coarse, verifiable unit),
+    never by hand-picking modules — an *include* list is a guess that can miss a
+    transitive dep and reintroduce staleness, whereas defaulting to "hash it"
+    over-invalidates at worst (one extra cold rebuild). Memoized: the source
+    cannot change within a live process (Python does not hot-reload), and a dev
+    editing lvkit restarts it before the next run anyway.
+    """
+    import lvkit
+
+    pkg = Path(lvkit.__file__).resolve().parent
+    h = hashlib.sha256()
+    for f in sorted(pkg.rglob("*")):
+        if not f.is_file() or f.suffix == ".pyc" or "__pycache__" in f.parts:
+            continue
+        rel = f.relative_to(pkg)
+        if rel.parts[0] in _FINGERPRINT_SKIP_DIRS:
+            continue
+        h.update(rel.as_posix().encode())
+        h.update(b"\0")
+        h.update(f.read_bytes())
+        h.update(b"\0")
+    return h.hexdigest()
+
+
 def meta_fresh(vi_path: Path, meta_path: Path, extra: dict | None = None) -> bool:
     """True if the cached artifact described by ``meta_path`` is still valid for
     ``vi_path``.

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/data/connector_pane_patterns.json

@@ -125,15 +125,15 @@
       "name": "special-7",
       "terminal_count": 7,
       "corpus_files": 2,
-      "grid": {"cols": 3, "rows": 4},
+      "grid": {"cols": 3, "rows": 6},
       "cells": [
-        {"index": 0, "col": 0, "row": 0, "colspan": 1, "rowspan": 1},
-        {"index": 1, "col": 1, "row": 0, "colspan": 1, "rowspan": 1},
-        {"index": 5, "col": 2, "row": 0, "colspan": 1, "rowspan": 2},
-        {"index": 2, "col": 0, "row": 1, "colspan": 2, "rowspan": 2},
-        {"index": 6, "col": 2, "row": 2, "colspan": 1, "rowspan": 2},
-        {"index": 3, "col": 0, "row": 3, "colspan": 1, "rowspan": 1},
-        {"index": 4, "col": 1, "row": 3, "colspan": 1, "rowspan": 1}
+        {"index": 0, "col": 0, "row": 0, "colspan": 1, "rowspan": 2},
+        {"index": 1, "col": 1, "row": 0, "colspan": 1, "rowspan": 2},
+        {"index": 5, "col": 2, "row": 0, "colspan": 1, "rowspan": 3},
+        {"index": 2, "col": 0, "row": 2, "colspan": 2, "rowspan": 2},
+        {"index": 6, "col": 2, "row": 3, "colspan": 1, "rowspan": 3},
+        {"index": 3, "col": 0, "row": 4, "colspan": 1, "rowspan": 2},
+        {"index": 4, "col": 1, "row": 4, "colspan": 1, "rowspan": 2}
       ]
     },
     "4818": {

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/data/primitives.json

@@ -305,40 +305,41 @@
       "verified": true
     },
     "1540": {
-      "name": "Format Value",
+      "name": "Array To Spreadsheet String",
       "terminals": [
         {
           "index": 0,
           "direction": "out",
-          "name": "result string",
-          "type": "polymorphic"
+          "name": "spreadsheet_string",
+          "type": "String"
         },
         {
           "index": 1,
           "direction": "in",
-          "name": "format string",
-          "type": "polymorphic"
+          "name": "delimiter",
+          "type": "String",
+          "default_value": "'\\t'"
         },
         {
           "index": 2,
           "direction": "in",
-          "name": "value",
-          "type": "polymorphic"
+          "name": "array",
+          "type": "Array"
         },
         {
           "index": 3,
           "direction": "in",
-          "name": "initial string",
-          "type": "polymorphic",
-          "default_value": "''"
+          "name": "format_string",
+          "type": "String"
         }
       ],
       "python_code": {
-        "result_string": "in_3 + (in_1 % in_2)"
+        "spreadsheet_string": "(in_1 or '\\t').join(in_3 % x for x in in_2)"
       },
       "inline": true,
       "verified": true,
-      "doc_url": "https://www.ni.com/docs/en-US/bundle/labview-api-ref/page/functions/format-value.html"
+      "doc_url": "https://www.ni.com/docs/en-US/bundle/labview-api-ref/page/functions/array-to-spreadsheet-string.html",
+      "note": "parmIndex from OBSERVED caller dataflow (OpenG '1D Array to String' control wiring: in_1<-delimiter, in_2<-array, in_3<-format '%s'): in_1=delimiter (default Tab), in_2=array, in_3=format string, out=spreadsheet string. python_code covers the common 1-D case; full N-D (Tab columns / EOL rows / page headers) would need an lvkit runtime helper, as with 1539."
     },
     "1050": {
       "name": "Add",
@@ -2206,12 +2207,12 @@
       "note": "Search 1D Array -- returns the index of element (searching from start_index) or -1 if not found. Delete From Array (class='aDelete') is a separate node_type entry. Was mislabeled 'Delete From Array'."
     },
     "1902": {
-      "name": "Reverse 1D Array",
+      "name": "Transpose 2D Array",
       "terminals": [
         {
           "index": 0,
           "direction": "out",
-          "name": "reversed_array",
+          "name": "transposed_array",
           "type": "Array"
         },
         {
@@ -2222,11 +2223,11 @@
         }
       ],
       "python_code": {
-        "reversed_array": "in_1[::-1]"
+        "transposed_array": "[list(r) for r in zip(*in_1)]"
       },
       "inline": true,
       "verified": true,
-      "doc_url": "https://www.ni.com/docs/en-US/bundle/labview-api-ref/page/functions/reverse-1d-array.html"
+      "doc_url": "https://www.ni.com/docs/en-US/bundle/labview-api-ref/page/functions/transpose-2d-array.html"
     },
     "1128": {
       "name": "Not A Number/Path/Refnum?",

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/docs/generate.py

@@ -17,6 +17,7 @@ from lvkit.graph import InMemoryVIGraph
 from lvkit.graph.loading import LoadMode
 from lvkit.models import CaseOperation, SequenceOperation
 from lvkit.render import render_vi_with_subvis
+from lvkit.render.icons import resolve_icon_png
 from lvkit.structure import parse_lvclass, parse_lvlib
 
 logger = logging.getLogger(__name__)
@@ -106,11 +107,9 @@ def _collect_icons(graph: InMemoryVIGraph, output_dir: Path) -> dict[str, str]:
 
         vi_path = Path(vi_path)
 
-        icon_source = vi_path.parent / f"{vi_path.stem}_ICON.png"
-        if not icon_source.exists():
-            icon_source = vi_path.parent / f"{vi_path.stem}_icl8.png"
+        icon_source = resolve_icon_png(vi_path.parent, vi_path.stem)
 
-        if icon_source.exists():
+        if icon_source is not None:
             safe_name = vi_name.replace(":", "_").replace("/", "_").replace("\\", "_")
             safe_name = safe_name.replace(" ", "_").replace(".", "_")
             icon_dest = icons_dir / f"{safe_name}.png"

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/graph/core.py

@@ -193,6 +193,9 @@ class InMemoryVIGraph(
         self._dep_load_mode: dict[str, LoadMode] = {}
         # Source file paths: vi_name -> Path to original .vi file
         self._source_paths: dict[str, Path] = {}
+        # vi_key -> qualified DISPLAY name (qname/basename). Display only, never a
+        # lookup key — resolve_vi_name still returns the vi_key (path) identity.
+        self._vi_display_names: dict[str, str] = {}
         # Search paths the graph was loaded with, retained so decoration-only
         # lookups (a SubVI's own _ICON.png) can locate a project-local .vi by
         # name even under a MINIMAL load that never walks the SubVI tree.

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/graph/loading.py

@@ -190,6 +190,7 @@ class LoadingMixin:
     _loaded_vis: set[str]
     _dep_load_mode: dict[str, LoadMode]
     _source_paths: dict[str, Path]
+    _vi_display_names: dict[str, str]
     _vi_metadata: dict[str, VIMetadata]
     _vi_properties: dict[str, VIProperties]
     _vi_health: dict[str, VIHealth]
@@ -814,6 +815,10 @@ class LoadingMixin:
         visited.add(vi_key)
 
         self._source_paths[vi_key] = source_file
+        # vi_key -> its qualified DISPLAY name (qname, else bare filename). Never a
+        # lookup key (vi_key/path is the identity); this is the human-facing title
+        # only, so the render/viewer shows "Class.lvclass:vi.vi" not the abspath.
+        self._vi_display_names[vi_key] = own_qname
         # Reverse indexes: display-name / qname -> [vi_key], for resolve_vi_name.
         # List-valued: on-disk duplicates share a name/qname across distinct keys.
         if vi_key not in self._name_to_keys.setdefault(unqualified_name, []):

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/graph/queries.py

@@ -65,6 +65,7 @@ class QueryMixin:
     _qname_to_keys: dict[str, list[str]]
     _loaded_vis: set[str]
     _source_paths: dict[str, Path]
+    _vi_display_names: dict[str, str]
     _vi_metadata: dict[str, VIMetadata]
     _vi_properties: dict[str, VIProperties]
     _vi_health: dict[str, VIHealth]
@@ -119,6 +120,19 @@ class QueryMixin:
                 return self._pick_vi_key(keys)
         return vi_name
 
+    def vi_display_name(self, vi_name: str) -> str:
+        """The VI's human-facing qualified name (``Class.lvclass:vi.vi``, else the
+        bare filename) for titles/headers. DISPLAY ONLY — never a lookup key. The
+        identity remains the ``vi_key`` (path) from :meth:`resolve_vi_name`; this
+        maps that key to its qname so the viewer shows the qualified name instead
+        of the absolute source path. Falls back to the resolved key's basename,
+        then the input, when no display name was recorded."""
+        key = self.resolve_vi_name(vi_name)
+        display = self._vi_display_names.get(key)
+        if display:
+            return display
+        return Path(key).name or vi_name
+
     def _pick_vi_key(self, keys: list[str]) -> str:
         """Deterministically choose among duplicate ``vi_key``s that share a
         name/qname. Prefer the richest copy -- a stripped built copy loses
@@ -154,13 +168,32 @@ class QueryMixin:
         """Get the source file path for a VI (accepts a vi_key, qname, or name)."""
         return self._source_paths.get(self.resolve_vi_name(vi_name))
 
-    def locate_vi_file(self, vi_name: str) -> Path | None:
-        """Best-effort on-disk ``.vi`` for a SubVI by name: an already-loaded
-        source first, else a filename search of the graph's retained search
-        paths. Decoration-only (SubVI icons) — never forces a load. Under a
-        MINIMAL load the SubVIs aren't in ``_source_paths``, so this filename
-        search is what lets a project-local SubVI's own ``_ICON.png`` resolve.
-        The search-path index is built once, lazily, and cached."""
+    def locate_vi_file(
+        self, vi_name: str, qualified_path: str | None = None
+    ) -> Path | None:
+        """Best-effort on-disk ``.vi`` for a SubVI. Decoration-only (SubVI icons /
+        click-nav) — never forces a load.
+
+        ``qualified_path`` (the caller's project-relative token, e.g.
+        ``/Lib1/Do.vi``) resolves to the EXACT file by PATH: joined to each search
+        root, the file AT that path IS the SubVI. This is what disambiguates two
+        SubVIs that share a bare filename across libraries (``Lib1/Do.vi`` vs
+        ``Lib2/Do.vi``) — a bare-name lookup collides, the path does not. A
+        ``<vilib>``/``<userlib>`` token is skipped here (resolved separately).
+
+        Falls back to an already-loaded source, then a bare-filename search of the
+        retained search paths (the last-resort path, which CAN collide on
+        duplicate names — callers with a ``qualified_path`` never reach it). Under
+        a MINIMAL load the SubVIs aren't in ``_source_paths``, so the filename
+        search is what lets a project-local SubVI's own ``_ICON.png`` resolve; its
+        index is built once, lazily, and cached."""
+        if qualified_path:
+            rel = qualified_path.replace("\\", "/").lstrip("/")
+            if rel and not rel.startswith("<"):
+                for root in self._search_paths:
+                    candidate = root / rel
+                    if candidate.is_file():
+                        return candidate
         loaded = self._source_paths.get(self.resolve_vi_name(vi_name))
         if loaded is not None:
             return loaded

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/index/store.py

@@ -29,8 +29,6 @@ version bump to forget. See ``_ensure_facts_version``.
 
 from __future__ import annotations
 
-import functools
-import hashlib
 import json
 import sqlite3
 from collections.abc import Iterable
@@ -289,58 +287,13 @@ _FLAT_PROPERTY_COLUMNS: tuple[tuple[str, bool], ...] = (
 )
 
 
-# Top-level package subdirs that DEMONSTRABLY don't feed the index — verified
-# absent from the import closure of ``index.build``/``index.store`` (the code
-# that actually produces facts), and pinned by
-# ``test_facts_fingerprint_skips_only_non_facts_dirs``. Skipping them means
-# editing codegen / docs / the formula transpiler / the MCP transport layer
-# doesn't force a needless full-corpus rebuild.
-#
-# This is an EXCLUDE list on purpose: the default for any file — including a
-# brand-new module or ``data/`` table — is to be hashed, so a new facts
-# dependency can never silently escape the fingerprint. The only failure mode
-# (a facts dep ADDED under one of these dirs) trips the guard test, which fails
-# loudly rather than letting staleness back in.
-_FINGERPRINT_SKIP_DIRS = frozenset({"codegen", "docs", "formula", "mcp"})
-
-
-@functools.lru_cache(maxsize=1)
-def _facts_fingerprint() -> str:
-    """A hash of lvkit's own facts-producing SOURCE + bundled data, so the index
-    self-invalidates the moment that changes — with no manual version to bump.
-
-    The index is a CACHE of what lvkit derives from each VI. Per-VI freshness is
-    keyed on VI bytes (``meta.content_sha``), but that cannot see a change to
-    lvkit's *extraction logic* (the VI bytes are identical) — so an edit to the
-    parser/graph/index code, or to a ``data/`` primitive/vilib table, would
-    otherwise keep serving facts built by the OLD code. That is silent staleness,
-    and it corrupts everything reading the index: queries, the MCP server, and
-    evals. A hand-bumped ``SCHEMA_VERSION`` can't defend against it because in
-    active development the bump is forgotten far more often than not.
-
-    Hashes every file in the package EXCEPT the ``_FINGERPRINT_SKIP_DIRS`` known
-    not to feed facts. Skipping is done by directory (a coarse, verifiable unit),
-    never by hand-picking the facts modules — an *include* list is a guess that
-    can miss a transitive dep and reintroduce staleness, whereas defaulting to
-    "hash it" over-invalidates at worst (one extra cold rebuild). Memoized: the
-    source cannot change within a live process (Python does not hot-reload), and
-    a dev editing lvkit restarts it before the next run anyway.
-    """
-    import lvkit
-
-    pkg = Path(lvkit.__file__).resolve().parent
-    h = hashlib.sha256()
-    for f in sorted(pkg.rglob("*")):
-        if not f.is_file() or f.suffix == ".pyc" or "__pycache__" in f.parts:
-            continue
-        rel = f.relative_to(pkg)
-        if rel.parts[0] in _FINGERPRINT_SKIP_DIRS:
-            continue
-        h.update(rel.as_posix().encode())
-        h.update(b"\0")
-        h.update(f.read_bytes())
-        h.update(b"\0")
-    return h.hexdigest()
+# The source fingerprint that invalidates the index now lives in ``cache_paths``
+# (the light, dependency-free module) so EVERY cache — this SQLite index and the
+# render/diff output cache — shares the exact SAME invalidation. Re-exported here
+# under the historical names the index code + guard test reference. See
+# ``cache_paths.source_fingerprint`` / ``_FINGERPRINT_SKIP_DIRS``.
+_FINGERPRINT_SKIP_DIRS = cache_paths._FINGERPRINT_SKIP_DIRS
+_facts_fingerprint = cache_paths.source_fingerprint
 
 
 def db_path(project_root: Path) -> Path:

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/output_cache.py

@@ -17,9 +17,12 @@ Addressing mirrors extraction (see :mod:`lvkit.cache_paths`):
   addressed** in a flat ``<cache>/adhoc/render/<sha>.<ext>`` and swept by TTL.
 
 Freshness = the VI-content signal ``cache_paths.meta_fresh`` already uses PLUS
-the lvkit ``version``, text encoding, and an ``options`` tag — so a VI edit, an
-lvkit upgrade, a system-code-page change, or different ``--format``/``--theme``
-is a miss.
+the SHARED ``cache_paths.source_fingerprint()`` (the same hash-of-lvkit-source
+that invalidates the SQLite index — so a renderer/graph/parser/data edit busts
+this cache too, with no version bump), the lvkit ``version`` (kept for readable
+meta), text encoding, and an ``options`` tag — so a VI edit, an lvkit CODE
+change, a system-code-page change, or different ``--format``/``--theme`` is a
+miss.
 """
 
 from __future__ import annotations
@@ -154,6 +157,7 @@ def lookup_render(input_path: Path, fmt: str, options: str, version: str) -> str
         meta_path,
         {
             "lvkit_version": version,
+            "source_fingerprint": cache_paths.source_fingerprint(),
             "options": options,
             "text_encoding": labview_text_encoding(),
         },
@@ -172,6 +176,7 @@ def store_render(
         body,
         {
             "lvkit_version": version,
+            "source_fingerprint": cache_paths.source_fingerprint(),
             "options": options,
             "kind": "render",
             "text_encoding": labview_text_encoding(),
@@ -191,6 +196,7 @@ def lookup_diff(
         meta_path,
         {
             "lvkit_version": version,
+            "source_fingerprint": cache_paths.source_fingerprint(),
             "options": options,
             "before_sha": before_sha,
             "text_encoding": labview_text_encoding(),
@@ -215,6 +221,7 @@ def store_diff(
         body,
         {
             "lvkit_version": version,
+            "source_fingerprint": cache_paths.source_fingerprint(),
             "options": options,
             "before_sha": before_sha,
             "kind": "diff",

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/render/__init__.py

@@ -344,6 +344,7 @@ def render_vi(
         interactive=interactive,
         extra_css=extra_css,
         extra_attrs=extra_attrs,
+        display_name=graph.vi_display_name(vi_name),
     )
     aside = _vi_aside_svg(graph, vi_name, scene, theme)
     if aside:
@@ -377,7 +378,7 @@ def _vi_aside_svg(
     panel = render_connector_pane_help(
         ctx.connector_pattern_id,
         pane_terminals((*ctx.inputs, *ctx.outputs)),
-        title=vi_name.split(":")[-1],
+        title=graph.vi_display_name(vi_name).split(":")[-1],
         description=ctx.description,
         icon_uri=icon_uri,
         theme=theme,
@@ -438,6 +439,7 @@ def _render_scene_svg(
     interactive: bool = True,
     extra_css: str = "",
     extra_attrs: dict[str, str] | None = None,
+    display_name: str | None = None,
 ) -> str:
     """Draw an already-built ``Scene`` to a self-contained interactive SVG.
 
@@ -445,7 +447,11 @@ def _render_scene_svg(
     dark ``--lv-*`` palette block for ``dark``/``auto`` theme modes. Empty keeps
     the ``<style>`` byte-identical to the legacy light output. ``extra_attrs``
     (``None`` by default) becomes root-``<svg>`` ``data-*`` attributes — e.g.
-    ``render_vi``'s ``data-lv-properties``/``data-lv-health`` (task #19)."""
+    ``render_vi``'s ``data-lv-properties``/``data-lv-health`` (task #19).
+    ``display_name`` (defaults to ``vi_name``) is the DISPLAY-only accessible
+    name (aria-label): the qualified name, so the SVG never exposes the abspath
+    ``vi_name`` key. ``vi_name`` still drives the scoping ``root_id``."""
+    title = display_name if display_name is not None else vi_name
     backend = SvgBackend()
     draw_scene(scene, backend, theme)
     style = _BASE_CSS + extra_css
@@ -467,7 +473,7 @@ def _render_scene_svg(
         script = "\n".join(scripts).replace("__ROOT_ID__", json.dumps(root_id))
         return backend.render(
             scene.bounds,
-            title=vi_name,
+            title=title,
             script=script,
             root_id=root_id,
             style=style,
@@ -475,7 +481,7 @@ def _render_scene_svg(
         )
     return backend.render(
         scene.bounds,
-        title=vi_name,
+        title=title,
         style=style,
         extra_attrs=extra_attrs,
     )
@@ -505,7 +511,10 @@ def render_vi_with_subvis(
         if isinstance(rn.node, VINode):
             target = rn.node.qualified_name or rn.node.name
             if target:
-                subvis[rn.node.id] = target
+                # Key by the DOCUMENT-LOCAL dom_id — the same value emitted as
+                # ``data-node`` — so the docs NAV map matches the SVG (and neither
+                # carries the abspath vi_key).
+                subvis[rn.dom_id] = target
     return _render_scene_svg(scene, vi_name, theme), subvis
 
 
@@ -586,4 +595,6 @@ def render_vi_file_titled(
 
     warm_all_loaded(graph)
     svg = render_vi(graph, name, theme=theme, theme_mode=theme_mode)
-    return svg, name
+    # `name` is the vi_key (canonical source path) — the render identity. The
+    # TITLE is display-only: the qualified name, never the abspath key.
+    return svg, graph.vi_display_name(name)

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/render/draw.py

@@ -362,7 +362,7 @@ def draw_node(node: RenderNode, backend: Backend, theme: Theme = DEFAULT_THEME)
     # the node's group to open even when it otherwise carries no tooltip.
     group_needed = bool(tooltip) or node.subvi_rel is not None
     if group_needed:
-        data = {"node": node.node.id}
+        data = {"node": node.dom_id}
         if node.subvi_rel is not None:
             data["lv-vi-rel"] = node.subvi_rel
         # A resolvable node (primitive / vi.lib VI) links to its NI docs page
@@ -936,7 +936,7 @@ def _draw_connector_panel(node: RenderNode, backend: Backend, theme: Theme) -> N
     # All panel styling (hidden-until-hover, no pointer capture, drop shadow)
     # lives in the .lv-help CSS rule (render/__init__.py _BASE_CSS) — the single
     # source both the in-place reveal and a host's cloned overlay inherit.
-    backend.begin_group(cls="lv-help", data={"node": node.node.id})
+    backend.begin_group(cls="lv-help", data={"node": node.dom_id})
     backend.rect(
         0.0,
         0.0,

{lvkit-0.6.2 → lvkit-0.6.3}/src/lvkit/render/icons.py

@@ -16,6 +16,24 @@ import base64
 from collections import defaultdict
 from pathlib import Path
 
+# LabVIEW dumps a VI's icon in several depth layers next to its heap XML. The
+# block diagram shows the COLOR icon, so prefer the 256-color layer (icl8), then
+# the 16-color layer (icl4), and only fall back to the 1-bit black-and-white
+# ``_ICON.png`` when no color layer exists — otherwise a class/library banner
+# color is silently dropped (e.g. Lib1/Lib2 members render mono).
+_ICON_LAYER_SUFFIXES = ("_icl8.png", "_icl4.png", "_ICON.png")
+
+
+def resolve_icon_png(directory: Path, stem: str) -> Path | None:
+    """Best available icon PNG for ``<stem>`` under ``directory``: 256-color,
+    else 16-color, else the 1-bit B&W fallback; ``None`` if none exist."""
+    for suffix in _ICON_LAYER_SUFFIXES:
+        candidate = directory / f"{stem}{suffix}"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
 _WHITE_CUTOFF = 238  # channel value at/above which a pixel counts as background