anywidget-vector 0.3.1__tar.gz → 0.4.0__tar.gz

anywidget_vector-0.4.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "release/**", "support/**"]
+  pull_request:
+    branches: [main]
+  # The release workflow runs the full suite before it publishes
+  workflow_call:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+
+      - name: Check that uv.lock matches pyproject.toml
+        run: uv lock --check
+
+      - name: Run ruff check
+        run: uv run --locked --only-group dev ruff check .
+
+      - name: Run ruff format check
+        run: uv run --locked --only-group dev ruff format --check .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@v7
+
+      # Sets UV_PYTHON, so uv uses this version instead of .python-version
+      - name: Install uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # The ESM bundle tests parse and run the widget's JavaScript with Node
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: uv sync --locked --extra dev
+
+      - name: Run tests
+        run: uv run --locked --extra dev pytest
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package
+        run: uvx twine check dist/*

anywidget_vector-0.4.0/.github/workflows/grafeo-latest.yml

@@ -0,0 +1,72 @@
+name: Grafeo Latest
+
+# Early warning for engine changes: runs the suite against the newest grafeo on
+# PyPI (pre-releases included, even outside the pinned range) and the browser
+# backend against the pinned and the newest @grafeo-db/wasm on npm.
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"  # Mondays 06:00 UTC
+  workflow_dispatch:
+
+jobs:
+  python:
+    name: Test with newest grafeo (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+          uv pip install --upgrade --prerelease allow grafeo
+
+      - name: Show grafeo build
+        run: uv run --no-sync python -c "import grafeo; print(grafeo.__version__); print(grafeo.build_info())"
+
+      - name: Run tests
+        run: uv run --no-sync pytest
+
+  wasm:
+    name: WASM smoke test (${{ matrix.release }} @grafeo-db/wasm)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        release: [pinned, newest]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v7
+        with:
+          node-version: "22"
+
+      - name: Resolve version
+        id: version
+        run: |
+          if [ "${{ matrix.release }}" = "pinned" ]; then
+            version=$(sed -n 's/^export const GRAFEO_WASM_VERSION = "\(.*\)";$/\1/p' src/anywidget_vector/backends/grafeo/embed.js)
+          else
+            version=$(npm view @grafeo-db/wasm versions --json | node -e 'const v = JSON.parse(require("fs").readFileSync(0, "utf8")); console.log([].concat(v).pop())')
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Download @grafeo-db/wasm@${{ steps.version.outputs.version }}
+        run: |
+          mkdir -p "$RUNNER_TEMP/wasm"
+          cd "$RUNNER_TEMP/wasm"
+          npm pack "@grafeo-db/wasm@${{ steps.version.outputs.version }}"
+          tar -xzf grafeo-db-wasm-*.tgz
+
+      - name: Run smoke test
+        run: node tests/js/wasm_smoke.mjs "$RUNNER_TEMP/wasm/package"

{anywidget_vector-0.3.1 → anywidget_vector-0.4.0}/.github/workflows/pypi.yml

@@ -15,25 +15,34 @@ on:
           - pypi
 
 jobs:
+  test:
+    name: Test
+    uses: ./.github/workflows/ci.yml
+
   build:
     name: Build distribution
+    needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
+      - name: Check the release tag matches the package version
+        if: github.event_name == 'release'
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "Release tag $GITHUB_REF_NAME does not match the package version $version"
+            exit 1
+          fi
 
-      - name: Install build dependencies
-        run: pip install build
+      - name: Install uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
 
       - name: Build package
-        run: python -m build
+        run: uv build
 
       - name: Upload distribution artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -48,7 +57,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -68,7 +77,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

anywidget_vector-0.4.0/CHANGELOG.md

@@ -0,0 +1,191 @@
+# Changelog
+
+## 0.4.0 (2026-10-28)
+
+Requires Python 3.12 or later; the Grafeo backend requires grafeo 0.6. See "Upgrading to 0.4" in the README.
+
+### Breaking
+
+- **Grafeo 0.6**: The `grafeo` extra requires `grafeo>=0.6.0,<0.7`; grafeo 0.5.x is no longer supported. Grafeo 0.6 changes query results and files, and these reach the widget's Grafeo backend:
+  - Every database is a single file. The first read-write open of a 0.5.x database migrates it and keeps the old file as `<file>.pre-0.6`, which 0.5.x needs to go back; opening a directory that is not a 0.5.x database fails
+  - A GQL number with a point is an exact decimal, so `0.0/0.0` and `1/0` fail the query (division by zero) where they gave NaN or null, and so does integer overflow. Use exponent literals (`0.0e0/0.0e0`) for IEEE floats
+  - A `WHERE` right after `INSERT`, `CREATE`, `MERGE` or `DELETE` is an error, and an `INSERT` alone returns no rows, so running one from the toolbar clears the scene
+  - GQL `ORDER BY` puts nulls last in both directions
+- **Theme follows the page until you choose**: `dark_mode` reports the theme in use. The widget follows the host page until a theme is chosen (`VectorSpace(dark_mode=...)`, `widget.dark_mode = ...` before or after display, even to the value it already reports, or the settings toggle) and then keeps the choice, also in later views; before, the page theme overwrote `dark_mode` passed from Python, and the widget stopped following the page after its first automatic change. The canvas `background` follows the theme unless chosen the same way; before, the theme overwrote it. Same contract as anywidget-graph and anywidget-archimate (`_theme_explicit`, `_background_explicit`)
+- **Compact toolbar in a narrow widget**: The toolbar tightens when the widget itself is narrower than 600 px (a container query), not only when the window is narrow, as in anywidget-graph. Panels over the canvas (window narrower than 768 px) now cover the canvas's zoom and selection controls instead of sitting under them
+- **WASM engine 0.6**: The browser-side Grafeo backend loads `@grafeo-db/wasm` 0.6.0 (was 0.5.0 in 0.3.2) from jsDelivr. The version is set once, `GRAFEO_WASM_VERSION` in `backends/grafeo/embed.js`, and a test keeps it in lockstep with the Python pin (npm and PyPI spellings of a pre-release, such as `0.6.1-rc.2` and `0.6.1rc2`, compare as the same version)
+
+### Improvements
+
+- **Decimals become numbers**: Grafeo 0.6 returns decimals (`decimal.Decimal` in Python, `{"$decimal": "1.50"}` in WASM). The widget turns them into floats in every Grafeo mode, also inside lists, maps and node properties, so `RETURN 0.5 AS score` maps to color and size, `1.5 AS x` places a point, and a plain list `[1.0, 0.0, 0.0]` still gives a vector. Without this, Python points could not be sent to the browser as JSON and WASM points landed at the origin
+- **Vector search errors**: A query vector of the wrong size or with NaN is a regular `grafeo.GrafeoError` in Grafeo 0.6 (0.5.44 panicked, and its WASM build trapped), shown in the widget with the sizes it names. The panic guard stays for any other engine bug
+- **Three.js 0.186.1, bundled**: The widget and `to_html()` use Three.js 0.186.1 (was 0.160.0 from esm.sh), bundled with the package (`ui/vendor/three.min.js` with its license, built by `scripts/vendor`), so both work offline and under a strict Content Security Policy. Only the `wasm` Grafeo mode loads code from a CDN. Three.js dropped WebGL 1 in 0.163, so a browser needs WebGL 2
+- **Theme detection**: A `data-theme="dark"` or `"light"` on the widget's closest ancestor wins, then on `<html>` and `<body>`, then a `dark` or `light` class, then the operating system. `data-theme="light"` no longer loses to a dark operating system, and other `data-theme` values (design-system names) are ignored
+- **Release safety**: The PyPI workflow runs the full CI suite first and stops when the release tag is not `v` plus the `pyproject.toml` version. CI also runs on `release/**` and `support/**` branches
+- **Credentials documented**: The README says where backend credentials end up (the browser and saved notebook widget state) and how to limit that
+- **Dependencies**: Requires anywidget 0.11 or later (was 0.9.21). The `chroma` and `all` extras pin `chromadb==1.5.8`, because 1.5.9 has security issues. All locked dependencies refreshed (`uv lock --upgrade`), and the dev tools need current releases (pytest 9.2, ruff 0.17.3, ty 0.0.94, prek 0.5.7, marimo 0.25.2); the `dev` extra includes grafeo, numpy and packaging so the full test suite runs everywhere. CI and the release workflow use uv (`uv lock --check`, `uv sync --locked`, `uv build`) and current GitHub Actions (checkout v7, setup-uv v10.3.3 pinned by commit since setup-uv publishes no moving major tag, setup-node v7, upload-artifact v7, download-artifact v8). The `tool.uv.dev-dependencies` table moved to `[dependency-groups]`, and ruff leaves Markdown files alone
+- **Engine contract tests**: The tests that pin Grafeo behavior now cover 0.6: error classes and messages for unknown metrics, zero dimensions, wrong-size and NaN query vectors and NaN in an indexed vector, filter operators (`$in`, `$ne`), tied distances, decimal literals and an `INSERT` without rows. `tests/js/wasm_smoke.mjs` checks decimals and the wrong-size error in WASM
+- **Same points in every Grafeo mode**: Embedded, server and WASM results go through the same rules: node values (`RETURN n`) contribute their properties, labels and id, unaliased columns such as `n.embedding` or `id(n)` are recognized, and explicit `x`/`y`/`z` win over the first vector components
+- **Server errors**: grafeo-server error responses show their `detail` text instead of raw JSON
+- **Scheduled engine check**: A weekly workflow runs the suite against the newest grafeo on PyPI (pre-releases included) and a smoke test against the pinned and the newest `@grafeo-db/wasm`
+- **Python 3.15**: Tested on Python 3.15; CI runs the suite on 3.12 to 3.15 and the classifiers list 3.12 to 3.15
+
+### Bug Fixes
+
+- **Embedded Grafeo queries**: Queries failed with "'QueryBuilder' object is not iterable" because the client called `GrafeoDB.query()`, which returns a query builder. It now calls `execute()`
+- **WASM mode**: `@grafeo-db/wasm` is published for bundlers since 0.5.x, so importing it from esm.sh no longer yields a working `Database`. The loader now imports the JS glue and instantiates the binary itself. WASM vectors (`Float32Array`) are converted to arrays, so they place points and sync to Python
+- **Engine panics**: A Grafeo panic (for example a vector search with the wrong number of dimensions) escaped the query callback because pyo3 raises it as a `BaseException`. It is now reported as a query error
+- **Query status**: A Python-side query with an empty result left the status at "connecting" and kept the old points. The result now replaces the points and the status becomes "connected"; a new query clears the previous error
+- **NaN and infinity in points**: These values are not valid JSON and one NaN coordinate broke camera framing for the whole scene. Top-level non-finite values are now replaced with `None` (with a `RuntimeWarning`), and distance and focus methods treat `None` coordinates as 0
+- **HTML injection**: Point labels and values from a database were inserted as HTML in the tooltip, the properties panel and the exported HTML page. They are now set as text. `to_html()` also escapes the title and keeps a `</script>` inside the data from ending the script
+- **Vector edge cases**: `add_numpy()` with a single high-dimensional row, a 1-D or one-column array, or ids/labels/metadata of the wrong length raised an unrelated `IndexError`; it now works (single row) or raises a clear `ValueError`. `project()` handles a single point and reports ragged or non-finite vectors clearly. `compute_distances(vector_field=...)` leaves out points without that vector instead of returning infinity, and raises on vectors of different lengths instead of truncating them
+- **Version**: `anywidget_vector.__version__` reported 0.2.5; it now reads the installed package version
+- **Removed views kept running**: A removed or re-rendered widget kept its model listeners, its theme observers and its dark-mode media listener, so old views went on updating `dark_mode` and `background`. Removing a view now detaches all of them
+- **WASM engine loaded twice**: Two copies of the widget module on one page (a cell run again, a marimo reconnect, anywidget-graph next to it) each instantiated the cached `@grafeo-db/wasm` glue, which broke the databases of the first copy. The loading promise now lives on `globalThis`, keyed by the glue URL
+- **Stale query results**: A slower, older browser-side query could overwrite the result of a newer one. Only the newest query per widget now sets points, errors and the loading state
+- **HTML export sizes**: `to_html(width=..., height=...)` placed the values in the page's `<style>` unchecked; a value that is not a plain CSS size now raises `ValueError`
+- **Source distribution**: A local `uv build` packed the `.claude/` folder (agent notes and local settings) into the sdist; it is now excluded
+
+## 0.3.2 (2026-03-16)
+
+### Improvements
+
+- **Marimo reactivity fix**: Removed camera and hover JS-to-Python sync to prevent continuous cell re-execution. Only user-initiated actions (selection, mode change) now trigger marimo reactive updates
+- **Custom scroll zoom**: Replaced OrbitControls zoom with a custom wheel handler for much finer granularity
+- **Selection hides completely**: Lasso/box selection now fully hides non-selected points (scale-to-zero for instanced meshes) instead of dimming
+- **Auto zoom-to-fit on selection**: Camera automatically frames the selected points after lasso/box selection
+- **Search filter modes**: Typing in the search bar dims non-matching points as a preview, pressing Run/Enter hides them completely
+- **Hover via callback**: Properties panel hover now uses a direct JS callback instead of model sync, eliminating unnecessary Python round-trips
+
+### Bug Fixes
+
+- **setSelection scoping**: Moved `setSelection` helper to `createCanvas` scope so lasso/box/click handlers can access it
+- **Camera debounce variable**: Fixed `_cameraDebounce` lexical declaration error by moving it to the correct scope
+
+## 0.3.1 (2026-03-16)
+
+### New Features
+
+- **Lasso selection**: New lasso mode for freehand point selection in the 3D canvas, with point-in-polygon hit testing
+- **Selection highlighting**: Selected points show wireframe highlight rings and non-selected points are dimmed to 15% brightness
+- **Auto-sizing**: Width defaults to 100% (fill container), height defaults to 1:1 aspect ratio. Both can still be set to fixed pixel values
+
+### Bug Fixes
+
+- **Properties panel**: Panel is now always created (previously skipped when `show_properties=False`), so the toolbar button always works. Starts closed unless `show_properties=True`
+- **Distance metric feedback**: Changing the metric now auto-enables k=5 connections when a point is selected, giving immediate visual feedback
+
+### Improvements
+
+- Reduced scroll zoom sensitivity (`zoomSpeed` halved to 0.5)
+- Search filter dimming increased from 12% to 6% opacity for clearer visual contrast
+- Camera no longer resets on every point update (only on initial load)
+- Cross-widget filtering: example updated so VectorSpace lasso selection feeds back into ParallelCoordinates dimming via marimo reactivity
+
+## 0.3.0 (2026-03-16)
+
+### New Features
+
+- **Distance metrics sidebar**: Distance section with metric selector (euclidean, cosine, manhattan, dot product), configurable k-neighbors (0-50) and live nearest-neighbor display for the selected point
+- **Dimension mapping display**: Sidebar now shows active visual mapping fields: color field, size range, shape field and unique shape count
+
+### Improvements
+
+- Improved sidebar styling and layout
+
+## 0.2.8 (2026-03-15)
+
+### New Features
+
+- **6D parallel coordinates example**: Fashion-MNIST demo with PCA across 6+ dimensions, interactive axis mapping and shape mapping to categorical labels
+
+## 0.2.7 (2026-03-15)
+
+### New Features
+
+- **Dark/light mode toggle**: `dark_mode` trait with real-time CSS color scheme switching and theme-aware styling across all panels
+
+## 0.2.6 (2026-03-15)
+
+### New Features
+
+- **NumPy array support**: `add_numpy()` method for adding points from arrays with automatic PCA projection for high-dimensional data (D > 3)
+- **Dimensionality reduction**: `project()` method with PCA, t-SNE and UMAP support; `set_vectors()` for storing high-dimensional vectors separately
+- **Example scripts**: Projection demo and numpy integration examples
+
+### Improvements
+
+- High-dimensional vector storage without syncing to JavaScript
+- Coordinate normalization after projection
+- Added demo screenshot to README
+
+## 0.2.5 (2026-03-04)
+
+### Bug Fixes
+
+- Fixed lasso selection stability issues
+- Removed problematic custom traitlets implementation
+
+### Improvements
+
+- Added keyboard shortcuts: F to fit view, Escape to clear selection
+- Better visual feedback for selection modes
+- Cleaner toolbar layout with integrated mode controls
+
+## 0.2.4 (2026-03-02)
+
+### New Features
+
+- **Zoom and pan controls**: Zoom in, zoom out and fit-to-view buttons in the toolbar
+- **Box selection mode**: New selection mode alongside click and multi-select, with visual feedback during selection
+- **HTML export**: `to_html()` and `save_html()` methods for self-contained HTML output with embedded data and Three.js
+
+### Improvements
+
+- Improved camera fitting algorithm for better initial view framing
+- Updated README with comprehensive usage examples
+- Updated dependencies
+
+## 0.2.3 (2026-02-12)
+
+### New Features
+
+- **Sidebar explorer**: Three collapsible sections: collections browser, dimensions explorer (point count, dimensionality, axis ranges) and clusters explorer (grouped by color field with sizes)
+- **Browser-side Grafeo backend**: JavaScript client for Grafeo server and WASM-embedded queries
+- **Demo module**: Reference implementation showing various widget features
+
+### Improvements
+
+- Consistency pass across all backend modules
+- Ruff configuration tuned for marimo compatibility
+
+## 0.2.2 (2026-02-07)
+
+### New Features
+
+- **Streaming factory methods**: `from_numpy()`, `from_umap()` and `from_arrays()` constructors for various data formats
+
+### Improvements
+
+- Added Apache 2.0 license
+- Expanded test suite with 194 additional test cases
+- ESM bundle aggregation for widget JavaScript
+
+## 0.2.1 (2026-02-03)
+
+### New Features
+
+- **Multi-backend architecture**: Six backends: Qdrant, Pinecone, Weaviate (browser-side REST), Chroma, LanceDB, Grafeo (Python-side)
+- **Modular UI**: Separated rendering into canvas, settings, properties and toolbar components
+- **Backend factory methods**: `from_qdrant()`, `from_pinecone()`, `from_weaviate()`, `from_chroma()`, `from_lancedb()`, `from_grafeo()`
+- **Event system**: `on_click()`, `on_hover()` and `on_selection()` decorators with callback signatures
+- **CI/CD**: GitHub Actions pipelines for testing and PyPI publishing
+
+### Improvements
+
+- Refactored monolithic widget into modular component architecture
+- Added README with usage examples
+
+## 0.1.0 (2026-02-03)
+
+- Initial release: Three.js-based interactive 3D vector visualization with instanced rendering, six shape types, continuous and categorical color mapping, orbit controls, hover tooltips, axes/grid display and raycast-based selection

{anywidget_vector-0.3.1 → anywidget_vector-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: anywidget-vector
-Version: 0.3.1
+Version: 0.4.0
 Summary: Interactive 3D vector visualization with query UI for vector databases
 Project-URL: Homepage, https://grafeo.dev/
 Project-URL: Repository, https://github.com/GrafeoDB/anywidget-vector
@@ -17,11 +17,12 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.12
-Requires-Dist: anywidget>=0.9.21
+Requires-Dist: anywidget>=0.11.0
 Provides-Extra: all
-Requires-Dist: chromadb>=1.5; extra == 'all'
+Requires-Dist: chromadb==1.5.8; extra == 'all'
 Requires-Dist: lancedb>=0.29.2; extra == 'all'
 Requires-Dist: numpy>=2.4; extra == 'all'
 Requires-Dist: pandas>=3; extra == 'all'
@@ -29,17 +30,20 @@ Requires-Dist: pinecone-client>=6.0; extra == 'all'
 Requires-Dist: qdrant-client>=1; extra == 'all'
 Requires-Dist: weaviate-client>=4.20; extra == 'all'
 Provides-Extra: chroma
-Requires-Dist: chromadb>=0.4; extra == 'chroma'
+Requires-Dist: chromadb==1.5.8; extra == 'chroma'
 Provides-Extra: demo
 Provides-Extra: dev
-Requires-Dist: marimo>=0.20; extra == 'dev'
-Requires-Dist: prek>=0.3; extra == 'dev'
-Requires-Dist: pytest>=9.0.2; extra == 'dev'
-Requires-Dist: ruff>=0.15; extra == 'dev'
-Requires-Dist: ty>=0.0; extra == 'dev'
+Requires-Dist: grafeo<0.7,>=0.6.0; extra == 'dev'
+Requires-Dist: marimo>=0.25.2; extra == 'dev'
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: packaging>=24; extra == 'dev'
+Requires-Dist: prek>=0.5.7; extra == 'dev'
+Requires-Dist: pytest>=9.2; extra == 'dev'
+Requires-Dist: ruff>=0.17.3; extra == 'dev'
+Requires-Dist: ty>=0.0.94; extra == 'dev'
 Provides-Extra: embed
 Provides-Extra: grafeo
-Requires-Dist: grafeo>=0.5; extra == 'grafeo'
+Requires-Dist: grafeo<0.7,>=0.6.0; extra == 'grafeo'
 Provides-Extra: lancedb
 Requires-Dist: lancedb>=0.1; extra == 'lancedb'
 Provides-Extra: numpy
@@ -69,7 +73,7 @@ Works with Marimo, Jupyter, VS Code, Colab, anywhere [anywidget](https://anywidg
 
 - **Universal**: One widget, every notebook environment
 - **6D Visualization**: X, Y, Z position + Color, Shape, Size encoding
-- **Backend-agnostic**: NumPy, pandas, Qdrant, Chroma, Pinecone, Weaviate, LanceDB, or raw dicts
+- **Backend-agnostic**: NumPy, pandas, Grafeo, Qdrant, Chroma, Pinecone, Weaviate, LanceDB, or raw dicts
 - **Interactive**: Orbit, pan, zoom, click, hover, box select
 - **Customizable**: Color scales, shapes, sizes, themes
 - **Performant**: Instanced rendering for large point clouds
@@ -78,8 +82,12 @@ Works with Marimo, Jupyter, VS Code, Colab, anywhere [anywidget](https://anywidg
 
 ```bash
 uv add anywidget-vector
+uv add "anywidget-vector[grafeo]"   # with the embedded Grafeo backend (grafeo 0.6)
 ```
 
+Requires Python 3.12 or later. The `grafeo` extra installs grafeo 0.6 (`grafeo>=0.6.0,<0.7`); the browser-side WASM mode loads the matching `@grafeo-db/wasm` from a CDN. Upgrading from 0.3 with Grafeo:
+see [Upgrading to 0.4](#upgrading-to-04).
+
 ## Quick Start
 
 ```python
@@ -347,7 +355,8 @@ widget = VectorSpace(
     points=data,
     width=1000,
     height=700,
-    background="#1a1a2e",         # Dark theme default
+    dark_mode=None,               # None (default) follows the page theme; True or False fixes it
+    background=None,              # None (default) uses the theme's canvas color
     show_axes=True,
     show_grid=True,
     axis_labels={"x": "PC1", "y": "PC2", "z": "PC3"},
@@ -358,6 +367,16 @@ widget = VectorSpace(
 )
 ```
 
+### Theme
+
+The widget follows the theme of the page it is on: a `data-theme="dark"` or `"light"` on the widget's closest ancestor,
+then on `<html>` and `<body>`, then a `dark` or `light` class on `<html>` or `<body>`, then the operating system's
+dark-mode setting. It keeps following as the page changes. `dark_mode` reports the theme in use.
+
+A theme you choose stays: `VectorSpace(dark_mode=False)`, `widget.dark_mode = ...` before or after the widget is shown
+(also to the value it already reports), or the toggle in the settings panel. The canvas color follows the theme unless
+you choose a `background` the same way. anywidget-graph and anywidget-archimate behave the same.
+
 ## Backends
 
 Configure a backend for interactive querying:
@@ -368,6 +387,96 @@ widget.set_backend("lancedb", client=table)
 widget.set_backend("grafeo", client=db)
 ```
 
+Type a query in the toolbar and press Run (or Enter). An empty result clears the scene; errors show in
+the settings panel.
+
+### Credentials
+
+Connection settings, including `apiKey`, `authToken`, `username` and `password` in `set_backend(...)` and the
+embedding key in the settings panel, are widget state: they reach the browser, which needs them for the browser-side
+backends (Qdrant, Pinecone, Weaviate, grafeo-server), and Jupyter saves them in the notebook file when it saves widget
+state. Use a read-only key with the narrowest scope the backend offers, keep it out of notebooks you share, or query
+from Python (`from_qdrant(...)`, `set_backend("chroma", client=...)` and the other Python-side clients keep their
+credentials in the kernel).
+
+### Grafeo
+
+[Grafeo](https://grafeo.dev/) is the default backend. It runs in three modes, set with
+`grafeo_connection_mode`:
+
+| Mode | Where queries run | Setup |
+|------|-------------------|-------|
+| `embedded` (default) | In Python, on a `grafeo.GrafeoDB` | `uv add "anywidget-vector[grafeo]"` and `set_backend("grafeo", client=db)` |
+| `server` | Over HTTP, `POST /query` on [grafeo-server](https://github.com/GrafeoDB/grafeo-server) | `grafeo_server_url="http://localhost:7474"`; start the server with `--cors-origins` so the notebook's origin may call it |
+| `wasm` | In the browser, in-memory | Nothing to install: `@grafeo-db/wasm` 0.6.0 loads from the jsDelivr CDN on the first query (the only code the widget loads from a CDN) |
+
+```python
+import grafeo
+from anywidget_vector import VectorSpace
+
+db = grafeo.GrafeoDB()
+db.create_node(["Doc"], {"title": "Graphs", "embedding": [0.9, 0.1, 0.0]})
+db.create_node(["Doc"], {"title": "Vectors", "embedding": [0.1, 0.9, 0.2]})
+db.create_vector_index("Doc", "embedding", metric="cosine")
+
+widget = VectorSpace(color_field="distance")
+widget.set_backend("grafeo", client=db)
+widget
+```
+
+A k-nearest-neighbor query for the toolbar (GQL, one statement per query):
+
+```
+CALL grafeo.search.vector('Doc', 'embedding', [1.0, 0.0, 0.0], 10) YIELD node_id, distance
+NEXT MATCH (n:Doc) WHERE id(n) = node_id RETURN n, distance ORDER BY distance
+```
+
+How results become points, the same in every mode:
+
+- A node (`RETURN n`) contributes its properties, its labels (`labels`) and its id (`id`).
+- An unaliased column is named after its expression (`n.embedding`), and the widget reads it as `embedding`.
+- The first of `vector`, `embedding` or `embeddings` becomes the point's `vector`; its first three components
+  are the coordinates unless the row also has `x`, `y` and `z`.
+- A GQL number with a point (`0.5`) is an exact decimal in Grafeo 0.6; the widget turns it into a float, also inside
+  lists and maps, so `RETURN 0.5 AS score` colors and sizes points like any other number.
+
+In `wasm` mode the database starts empty, so load data with one `INSERT` per query and create the index with
+`CREATE VECTOR INDEX doc_embedding ON :Doc(embedding) DIMENSION 3 METRIC 'cosine'`. Store embeddings
+as `vector([...])` there: a plain list is not indexed. An `INSERT` returns no rows, so it clears the scene; run a
+`MATCH` or a search afterwards to see the data.
+
+A query vector with another number of dimensions than the index, or with NaN, is a query error that names the
+sizes (for example "the query vector has 2 dimensions; the index on :Doc(embedding) expects 3"); the points stay
+as they were.
+
+The distance metrics of a Grafeo vector index (`cosine`, `euclidean`, `dot_product`, `manhattan`) give the
+same values as the widget's `distance_metric` and `compute_distances()`.
+
+The browser engine version is set in one place, `GRAFEO_WASM_VERSION` in
+`src/anywidget_vector/backends/grafeo/embed.js`, and moves in lockstep with the `grafeo` extra. Before a bump,
+run `node tests/js/wasm_smoke.mjs <unpacked @grafeo-db/wasm package>`.
+
+### Upgrading to 0.4
+
+0.4 moves the Grafeo backend to Grafeo 0.6, which changes some query results. What to check:
+
+- **Install**: the `grafeo` extra needs grafeo 0.6; `uv add "anywidget-vector[grafeo]"` upgrades it. The `wasm` mode
+  loads `@grafeo-db/wasm` 0.6 from the CDN by itself.
+- **Database files**: Grafeo 0.6 keeps every database in a single file. The first read-write open of a 0.5.x
+  database migrates it and keeps the old file as `<file>.pre-0.6`; 0.5.x cannot open the migrated file, so stop
+  every 0.5.x process first and keep the `.pre-0.6` copy until you no longer need to go back. Opening a directory that
+  is not a 0.5.x database fails: pass a file path, such as `data/vectors.grafeo`.
+- **Numbers with a point**: `0.1` is an exact decimal in GQL, so `0.0/0.0` and `1/0` now fail the query (division by
+  zero) instead of giving NaN or null, and integer overflow fails too. Write float literals with an exponent
+  (`0.0e0 / 0.0e0`) where you want IEEE results.
+- **Writes**: a `WHERE` right after `INSERT`, `CREATE`, `MERGE` or `DELETE` is an error; put the condition before the
+  write. An `INSERT` alone returns no rows.
+- **Ordering**: GQL `ORDER BY` puts nulls last in both directions; add `NULLS FIRST` for the old descending order.
+- **Errors**: a vector search with a query of the wrong size raises `grafeo.GrafeoError` (Grafeo 0.5.44 panicked);
+  the widget shows it as a query error either way.
+
+See Grafeo's [Upgrading to 0.6](https://grafeo.dev/upgrading/0.6/) for the full list.
+
 ## Export
 
 ```python
@@ -377,6 +486,13 @@ widget.to_html(title="My Vectors")          # Custom title
 widget.save_html("vectors.html")            # Write HTML to file
 ```
 
+Three.js is bundled with the package (`ui/vendor/three.min.js`, built by `scripts/vendor`), so the widget and its
+HTML export work offline and under a strict Content Security Policy. Only the `wasm` Grafeo mode loads code from a
+CDN.
+
+NaN and infinity cannot travel as JSON, so the widget replaces them with `None` in point values (with a
+`RuntimeWarning`); a missing coordinate is drawn at 0.
+
 ## Environment Support
 
 | Environment | Supported |