ttl3d 0.2.2__tar.gz

ttl3d-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soheil Abadifard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ttl3d-0.2.2/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: ttl3d
+Version: 0.2.2
+Summary: Turn any Turtle / RDF graph into a self-contained, offline 2D/3D HTML viewer
+Author: Soheil Abadifard
+License: MIT
+Project-URL: Repository, https://github.com/soheilabadifard/TTL_to_3D
+Project-URL: Issues, https://github.com/soheilabadifard/TTL_to_3D/issues
+Keywords: rdf,turtle,owl,ontology,knowledge-graph,semantic-web,linked-data,visualization,3d,2d,graph-visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rdflib>=7
+Requires-Dist: networkx>=3
+Requires-Dist: numpy
+Requires-Dist: scipy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: browser
+Requires-Dist: pytest; extra == "browser"
+Requires-Dist: playwright; extra == "browser"
+Dynamic: license-file
+
+# ttl3d
+
+[![tests](https://github.com/soheilabadifard/TTL_to_3D/actions/workflows/tests.yml/badge.svg)](https://github.com/soheilabadifard/TTL_to_3D/actions/workflows/tests.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+Turn any Turtle / RDF graph into a single self-contained HTML page with a 3D
+view (shaded spheres) and a 2D view (a flat canvas), permanent labels, predicate
+labels on the edges, a clickable legend, label search, and a detail card for
+every node. The page embeds all of its JavaScript, so it opens from a file,
+works offline, and never sends your data anywhere.
+
+![ttl3d rendering the Solar System demo ontology](docs/screenshot.png)
+
+## Why
+
+Ontology editors show class trees. SPARQL browsers show one neighbourhood at a
+time. Sometimes you want the whole graph on screen at once: to see which
+modules actually connect, which file asserted which edge, or which node
+everything hangs from. ttl3d was written for exactly that while building a
+multi-file ontology, then generalized to any RDF input.
+
+## Install
+
+Python 3.10 or newer.
+
+```bash
+pip install git+https://github.com/soheilabadifard/TTL_to_3D
+```
+
+Or clone the repository and run `pip install -e .`. The dependencies are
+`rdflib`, `networkx`, `numpy` and `scipy`, all available on conda-forge as
+well.
+
+## Quick start
+
+```bash
+ttl3d examples/solar-system.ttl examples/solar-system-missions.ttl -o solar.html
+```
+
+Open `solar.html` in any browser. Pass several files and they merge into one
+graph; the default colouring then shows which file declared each node and
+which file asserted each edge.
+
+Without installing, run the module from a clone: `python -m ttl3d ...`.
+
+## Options
+
+| Option | Values | Meaning |
+|--------|--------|---------|
+| `-o, --out` | path | Output file. Default: `<first file stem>-<view>.html` in the current directory. |
+| `--color-by` | `file` (default), `type`, `namespace` | What node colours and the legend mean. In `file` mode edges also take the colour of the file asserting them. |
+| `--layout` | `auto` (default), `stress`, `force` | `stress` pins every node to a precomputed Kamada-Kawai position, one layout per view (3D and 2D); `force` runs the live simulation. `auto` picks `stress` up to 1000 nodes. |
+| `--labels` | `auto` (default), `always`, `hover` | Permanent label sprites. `auto` keeps node labels up to 800 nodes and edge labels up to 800 links; `hover` leaves tooltips only. |
+| `--view` | `3d` (default), `2d` | Starting view. The page has a `3D \| 2D` switch either way, and each view is pinned to its own stress layout. |
+| `--title` | text | Page title. Default: the first file's stem. |
+| `--lang` | language tag, default `en` | Preferred language for labels and definitions. Untagged literals rank next; other languages become synonyms on the card. Matched exactly: `--lang en` does not select `@en-GB`. |
+| `--format` | rdflib parser name | Force a parser for every input (`turtle`, `xml`, `nt`, `json-ld`, ...). Default: guess from the extension, then try Turtle. |
+| `--type-links` | flag | Draw `rdf:type` as an edge from each instance to its class instead of listing it on the card only. |
+| `--attribute-preds` | `prefix:local`, full IRI, or `<urn:...>` | Predicates to keep off the picture and show on the card, e.g. `foaf:homepage,rdfs:seeAlso`. Repeatable; wrap a URN or mailto in angle brackets. |
+| `--version` | flag | Print `ttl3d <version>` and exit. |
+
+Input formats are guessed from the extension (`.ttl`, `.nt`, `.n3`, `.rdf`,
+`.owl`, `.jsonld`, ...) through rdflib.
+
+## What becomes a node, what becomes a link
+
+- A node is every IRI that is the subject of some triple or the object of a
+  link, except IRIs of the RDF, RDFS, OWL and XSD vocabularies and ontology
+  headers (`owl:Ontology`). Blank nodes are skipped.
+- A link is an IRI-to-IRI triple whose predicate is a relation. `rdf:type`,
+  `owl:imports`, `owl:versionIRI`, `owl:priorVersion`, `rdfs:isDefinedBy`,
+  `prov:wasDerivedFrom` and `dcterms:source` describe the node instead and go
+  to its card. Parallel edges collapse into one link listing every predicate.
+- Label: `rdfs:label`, else `skos:prefLabel`, else the local name.
+  Definition: `skos:definition`, else `rdfs:comment`, else `dcterms:description`.
+  Every other literal lands in the card's property table.
+- Each node remembers the file that first declares it; each link remembers the
+  files asserting it. A file that only adds edges between other files' nodes
+  still owns something visible.
+- An edge asserted in both directions (`:Luna :orbits :Earth` and `:Earth :hasMoon :Luna`) is one link labelled `orbits ⇄ hasMoon`, without an arrowhead.
+- Labels follow `--lang`: the requested language first, then untagged literals, then anything else; every other label value becomes a synonym on the card, and a `rdfs:comment` that loses to a `skos:definition` still appears in the property table.
+
+## In the page
+
+- Legend rows filter inclusively: a selected group keeps its own nodes, their
+  direct neighbours, and the endpoints of every edge it asserts.
+- The `3D | 2D` switch rebuilds the picture in the other view. Legend filters, the
+  search text and the open card carry over, and in pinned mode each view has its own
+  precomputed stress layout. A browser without WebGL opens in 2D and says so.
+- Search dims everything whose label does not match.
+- Click a node for its card: types, file, namespace, definition, synonyms,
+  properties, incoming and outgoing relations (clickable), and sources.
+- The label toggles rebuild the scene, so a big graph can start without
+  sprites and switch them on later.
+- "Free-float physics" releases pinned nodes into the live force layout and
+  pins them back where they were.
+- No fog: white fog made distant nodes vanish on zoom-out.
+- Past twelve groups only the eleven largest keep a colour; the rest share one grey "other" row that filters them together.
+
+## Scale
+
+The stress layout is quadratic in the number of nodes and label sprites are
+scene objects, so the automatic modes degrade instead of freezing:
+
+| Graph size | Layout | Labels |
+|-----------|--------|--------|
+| up to 800 nodes / 800 links | pinned stress layout | nodes and edges |
+| up to 1000 nodes | pinned stress layout | tooltips for the layer over its threshold |
+| larger | live force simulation | tooltips; switch sprites on from the panel |
+
+The stress layout is computed twice, once per view, so a pinned page takes about
+twice the layout time of 0.1.0.
+
+Force the behaviour you want with `--layout` and `--labels`.
+
+## Limitations
+
+- Blank nodes are skipped, so OWL restrictions and RDF lists do not appear.
+- No reasoning: only asserted triples are drawn.
+- One page holds one graph; there is no incremental loading.
+- The stress layout is quadratic: `--layout stress` on graphs far beyond 1000 nodes can take minutes, and the CLI says so on stderr.
+
+## Development
+
+```bash
+pip install -e .[test]
+python -m pytest -q
+```
+
+The tests cover the loader, the node and link rules, the layout, the generated page, the vendored
+bundle's pins and licence notices, and the command line. The viewer's CSS and JavaScript live in `ttl3d/viewer.css`, `ttl3d/viewer.js` (shared by both views), `ttl3d/viewer-3d.js` and `ttl3d/viewer-2d.js` (one renderer per view)
+and are inlined into every page; when `node` is installed the suite syntax-checks the
+JavaScript. `pip install -e .[browser] && playwright install chromium` enables the headless
+browser tests that load the demo pages, switch views and assert zero console errors
+(`TTL3D_BROWSER=firefox` or `webkit` picks another engine). CI runs the suite on Linux, Windows
+and macOS, the browser tests on Chromium, Firefox and WebKit, and checks that the demo pages
+built on the three systems are identical apart from the pinned layout's last digits. The vendored JavaScript
+in `ttl3d/vendor/` bundles 3d-force-graph, force-graph, three-spritetext and one shared three.js;
+`VENDOR.md` there has the rebuild recipe and `LICENSES.md` the upstream notices.
+
+## License
+
+MIT. The vendored JavaScript is under permissive licences (MIT, ISC and others); `ttl3d/vendor/LICENSES.md` lists every bundled package with its licence and copyright line.

ttl3d-0.2.2/README.md

@@ -0,0 +1,144 @@
+# ttl3d
+
+[![tests](https://github.com/soheilabadifard/TTL_to_3D/actions/workflows/tests.yml/badge.svg)](https://github.com/soheilabadifard/TTL_to_3D/actions/workflows/tests.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)
+
+Turn any Turtle / RDF graph into a single self-contained HTML page with a 3D
+view (shaded spheres) and a 2D view (a flat canvas), permanent labels, predicate
+labels on the edges, a clickable legend, label search, and a detail card for
+every node. The page embeds all of its JavaScript, so it opens from a file,
+works offline, and never sends your data anywhere.
+
+![ttl3d rendering the Solar System demo ontology](docs/screenshot.png)
+
+## Why
+
+Ontology editors show class trees. SPARQL browsers show one neighbourhood at a
+time. Sometimes you want the whole graph on screen at once: to see which
+modules actually connect, which file asserted which edge, or which node
+everything hangs from. ttl3d was written for exactly that while building a
+multi-file ontology, then generalized to any RDF input.
+
+## Install
+
+Python 3.10 or newer.
+
+```bash
+pip install git+https://github.com/soheilabadifard/TTL_to_3D
+```
+
+Or clone the repository and run `pip install -e .`. The dependencies are
+`rdflib`, `networkx`, `numpy` and `scipy`, all available on conda-forge as
+well.
+
+## Quick start
+
+```bash
+ttl3d examples/solar-system.ttl examples/solar-system-missions.ttl -o solar.html
+```
+
+Open `solar.html` in any browser. Pass several files and they merge into one
+graph; the default colouring then shows which file declared each node and
+which file asserted each edge.
+
+Without installing, run the module from a clone: `python -m ttl3d ...`.
+
+## Options
+
+| Option | Values | Meaning |
+|--------|--------|---------|
+| `-o, --out` | path | Output file. Default: `<first file stem>-<view>.html` in the current directory. |
+| `--color-by` | `file` (default), `type`, `namespace` | What node colours and the legend mean. In `file` mode edges also take the colour of the file asserting them. |
+| `--layout` | `auto` (default), `stress`, `force` | `stress` pins every node to a precomputed Kamada-Kawai position, one layout per view (3D and 2D); `force` runs the live simulation. `auto` picks `stress` up to 1000 nodes. |
+| `--labels` | `auto` (default), `always`, `hover` | Permanent label sprites. `auto` keeps node labels up to 800 nodes and edge labels up to 800 links; `hover` leaves tooltips only. |
+| `--view` | `3d` (default), `2d` | Starting view. The page has a `3D \| 2D` switch either way, and each view is pinned to its own stress layout. |
+| `--title` | text | Page title. Default: the first file's stem. |
+| `--lang` | language tag, default `en` | Preferred language for labels and definitions. Untagged literals rank next; other languages become synonyms on the card. Matched exactly: `--lang en` does not select `@en-GB`. |
+| `--format` | rdflib parser name | Force a parser for every input (`turtle`, `xml`, `nt`, `json-ld`, ...). Default: guess from the extension, then try Turtle. |
+| `--type-links` | flag | Draw `rdf:type` as an edge from each instance to its class instead of listing it on the card only. |
+| `--attribute-preds` | `prefix:local`, full IRI, or `<urn:...>` | Predicates to keep off the picture and show on the card, e.g. `foaf:homepage,rdfs:seeAlso`. Repeatable; wrap a URN or mailto in angle brackets. |
+| `--version` | flag | Print `ttl3d <version>` and exit. |
+
+Input formats are guessed from the extension (`.ttl`, `.nt`, `.n3`, `.rdf`,
+`.owl`, `.jsonld`, ...) through rdflib.
+
+## What becomes a node, what becomes a link
+
+- A node is every IRI that is the subject of some triple or the object of a
+  link, except IRIs of the RDF, RDFS, OWL and XSD vocabularies and ontology
+  headers (`owl:Ontology`). Blank nodes are skipped.
+- A link is an IRI-to-IRI triple whose predicate is a relation. `rdf:type`,
+  `owl:imports`, `owl:versionIRI`, `owl:priorVersion`, `rdfs:isDefinedBy`,
+  `prov:wasDerivedFrom` and `dcterms:source` describe the node instead and go
+  to its card. Parallel edges collapse into one link listing every predicate.
+- Label: `rdfs:label`, else `skos:prefLabel`, else the local name.
+  Definition: `skos:definition`, else `rdfs:comment`, else `dcterms:description`.
+  Every other literal lands in the card's property table.
+- Each node remembers the file that first declares it; each link remembers the
+  files asserting it. A file that only adds edges between other files' nodes
+  still owns something visible.
+- An edge asserted in both directions (`:Luna :orbits :Earth` and `:Earth :hasMoon :Luna`) is one link labelled `orbits ⇄ hasMoon`, without an arrowhead.
+- Labels follow `--lang`: the requested language first, then untagged literals, then anything else; every other label value becomes a synonym on the card, and a `rdfs:comment` that loses to a `skos:definition` still appears in the property table.
+
+## In the page
+
+- Legend rows filter inclusively: a selected group keeps its own nodes, their
+  direct neighbours, and the endpoints of every edge it asserts.
+- The `3D | 2D` switch rebuilds the picture in the other view. Legend filters, the
+  search text and the open card carry over, and in pinned mode each view has its own
+  precomputed stress layout. A browser without WebGL opens in 2D and says so.
+- Search dims everything whose label does not match.
+- Click a node for its card: types, file, namespace, definition, synonyms,
+  properties, incoming and outgoing relations (clickable), and sources.
+- The label toggles rebuild the scene, so a big graph can start without
+  sprites and switch them on later.
+- "Free-float physics" releases pinned nodes into the live force layout and
+  pins them back where they were.
+- No fog: white fog made distant nodes vanish on zoom-out.
+- Past twelve groups only the eleven largest keep a colour; the rest share one grey "other" row that filters them together.
+
+## Scale
+
+The stress layout is quadratic in the number of nodes and label sprites are
+scene objects, so the automatic modes degrade instead of freezing:
+
+| Graph size | Layout | Labels |
+|-----------|--------|--------|
+| up to 800 nodes / 800 links | pinned stress layout | nodes and edges |
+| up to 1000 nodes | pinned stress layout | tooltips for the layer over its threshold |
+| larger | live force simulation | tooltips; switch sprites on from the panel |
+
+The stress layout is computed twice, once per view, so a pinned page takes about
+twice the layout time of 0.1.0.
+
+Force the behaviour you want with `--layout` and `--labels`.
+
+## Limitations
+
+- Blank nodes are skipped, so OWL restrictions and RDF lists do not appear.
+- No reasoning: only asserted triples are drawn.
+- One page holds one graph; there is no incremental loading.
+- The stress layout is quadratic: `--layout stress` on graphs far beyond 1000 nodes can take minutes, and the CLI says so on stderr.
+
+## Development
+
+```bash
+pip install -e .[test]
+python -m pytest -q
+```
+
+The tests cover the loader, the node and link rules, the layout, the generated page, the vendored
+bundle's pins and licence notices, and the command line. The viewer's CSS and JavaScript live in `ttl3d/viewer.css`, `ttl3d/viewer.js` (shared by both views), `ttl3d/viewer-3d.js` and `ttl3d/viewer-2d.js` (one renderer per view)
+and are inlined into every page; when `node` is installed the suite syntax-checks the
+JavaScript. `pip install -e .[browser] && playwright install chromium` enables the headless
+browser tests that load the demo pages, switch views and assert zero console errors
+(`TTL3D_BROWSER=firefox` or `webkit` picks another engine). CI runs the suite on Linux, Windows
+and macOS, the browser tests on Chromium, Firefox and WebKit, and checks that the demo pages
+built on the three systems are identical apart from the pinned layout's last digits. The vendored JavaScript
+in `ttl3d/vendor/` bundles 3d-force-graph, force-graph, three-spritetext and one shared three.js;
+`VENDOR.md` there has the rebuild recipe and `LICENSES.md` the upstream notices.
+
+## License
+
+MIT. The vendored JavaScript is under permissive licences (MIT, ISC and others); `ttl3d/vendor/LICENSES.md` lists every bundled package with its licence and copyright line.

ttl3d-0.2.2/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ttl3d"
+dynamic = ["version"]
+description = "Turn any Turtle / RDF graph into a self-contained, offline 2D/3D HTML viewer"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [{name = "Soheil Abadifard"}]
+requires-python = ">=3.10"
+dependencies = ["rdflib>=7", "networkx>=3", "numpy", "scipy"]
+keywords = ["rdf", "turtle", "owl", "ontology", "knowledge-graph", "semantic-web",
+            "linked-data", "visualization", "3d", "2d", "graph-visualization"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.urls]
+Repository = "https://github.com/soheilabadifard/TTL_to_3D"
+Issues = "https://github.com/soheilabadifard/TTL_to_3D/issues"
+
+[project.scripts]
+ttl3d = "ttl3d.cli:main"
+
+[project.optional-dependencies]
+test = ["pytest"]
+browser = ["pytest", "playwright"]
+
+[tool.setuptools.packages.find]
+include = ["ttl3d*"]
+
+[tool.setuptools.package-data]
+ttl3d = ["vendor/*.js", "vendor/*.md", "viewer.js", "viewer-3d.js", "viewer-2d.js", "viewer.css"]
+
+[tool.setuptools.dynamic]
+version = {attr = "ttl3d.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110

ttl3d-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ttl3d-0.2.2/tests/test_bundle.py

@@ -0,0 +1,35 @@
+"""The vendored bundle is the only JavaScript the page loads; it must carry all four globals,
+and its rebuild must be reproducible from the pins next to it."""
+import json
+from pathlib import Path
+
+VENDOR = Path(__file__).resolve().parents[1] / "ttl3d" / "vendor" / "fg-bundle.min.js"
+
+
+def test_bundle_exposes_required_globals():
+    lib = VENDOR.read_text(encoding="utf-8")
+    # `window.ForceGraph=` with the `=` so `ForceGraph3D` cannot stand in for the 2D library
+    for g in ("ForceGraph3D", "ForceGraph", "SpriteText", "THREE"):
+        assert f"window.{g}=" in lib, g
+    assert "</script" not in lib and "sourceMappingURL" not in lib
+
+
+def test_vendor_pins_are_exact_and_locked():
+    pins = json.loads((VENDOR.parent / "package.json").read_text(encoding="utf-8"))
+    for name, ver in {**pins["dependencies"], **pins["devDependencies"]}.items():
+        assert ver[0].isdigit(), f"{name} is not pinned exactly: {ver}"
+    assert pins["dependencies"]["force-graph"] == "1.51.4" and pins["dependencies"]["three"] == "0.185.1"
+    assert (VENDOR.parent / "package-lock.json").exists()
+
+
+def test_vendor_notices_cover_every_runtime_package_in_the_lockfile():
+    # MIT and ISC both require the copyright notice to travel with copies; the bundle
+    # inlines every runtime package of the lockfile, so every one needs a line here
+    lock = json.loads((VENDOR.parent / "package-lock.json").read_text(encoding="utf-8"))
+    notices = (VENDOR.parent / "LICENSES.md").read_text(encoding="utf-8")
+    runtime = {(path.split("node_modules/")[-1], meta["version"])
+               for path, meta in lock["packages"].items() if path and not meta.get("dev")}
+    missing = sorted(f"{name} {version}" for name, version in runtime
+                     if f"- {name} {version} " not in notices)
+    assert not missing, missing
+    assert "## The MIT License" in notices and "## The ISC License" in notices

ttl3d-0.2.2/tests/test_cli.py

@@ -0,0 +1,227 @@
+"""ttl3d.cli: the command line entry point."""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from ttl3d import cli
+
+REPO = Path(__file__).resolve().parents[1]
+
+
+def test_cli_writes_the_page_and_reports_what_it_did(tmp_path, library, library_extra, capsys):
+    out = tmp_path / "lib.html"
+    rc = cli.main([str(library), str(library_extra), "-o", str(out), "--title", "Lib"])
+    assert rc == 0
+    html = out.read_text(encoding="utf-8")
+    assert "<title>Lib</title>" in html and '"pinned": true' in html
+    printed = capsys.readouterr().out
+    assert "12 nodes" in printed and "6 links" in printed and "stress" in printed
+
+
+def test_cli_default_output_is_named_after_the_first_file(tmp_path, library, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert cli.main([str(library)]) == 0
+    assert (tmp_path / "library-3d.html").exists()
+
+
+def test_cli_color_by_type_puts_types_in_the_legend(tmp_path, library):
+    out = tmp_path / "t.html"
+    cli.main([str(library), "-o", str(out), "--color-by", "type"])
+    assert 'data-group="Book"' in out.read_text(encoding="utf-8")
+
+
+def test_cli_force_layout_leaves_nodes_unpinned(tmp_path, library):
+    out = tmp_path / "f.html"
+    cli.main([str(library), "-o", str(out), "--layout", "force"])
+    assert '"pinned": false' in out.read_text(encoding="utf-8")
+
+
+def test_cli_hover_labels_disable_both_label_layers(tmp_path, library):
+    out = tmp_path / "h.html"
+    cli.main([str(library), "-o", str(out), "--labels", "hover"])
+    assert '"node": false' in out.read_text(encoding="utf-8") and '"edge": false' in out.read_text(encoding="utf-8")
+
+
+def test_cli_rejects_an_unknown_color_key(library):
+    with pytest.raises(SystemExit) as e:
+        cli.main([str(library), "--color-by", "colour"])
+    assert e.value.code == 2
+
+
+def test_module_entry_point_runs(tmp_path, library):
+    out = tmp_path / "m.html"
+    r = subprocess.run([sys.executable, "-m", "ttl3d", str(library), "-o", str(out)],
+                       capture_output=True, text=True, cwd=REPO, check=False)
+    assert r.returncode == 0, r.stderr
+    assert out.exists()
+
+
+def test_cli_missing_file_is_a_clean_error(tmp_path, capsys):
+    out = tmp_path / "x.html"
+    rc = cli.main([str(tmp_path / "nope.ttl"), "-o", str(out)])
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert err.startswith("ttl3d: error:") and "nope.ttl" in err
+    assert not out.exists()
+
+
+def test_cli_malformed_file_is_a_clean_error(tmp_path, capsys):
+    bad = tmp_path / "bad.ttl"
+    bad.write_text("this is not turtle @@@\n", encoding="utf-8")
+    rc = cli.main([str(bad), "-o", str(tmp_path / "x.html")])
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert err.startswith("ttl3d: error:") and "bad.ttl" in err
+    assert err.count("\n") == 1
+
+
+def test_cli_refuses_to_overwrite_an_input(tmp_path, library, capsys):
+    victim = tmp_path / "victim.ttl"
+    victim.write_text(library.read_text(encoding="utf-8"), encoding="utf-8")
+    rc = cli.main([str(victim), "-o", str(victim)])
+    assert rc == 1
+    assert victim.read_text(encoding="utf-8") == library.read_text(encoding="utf-8")
+    assert "input" in capsys.readouterr().err
+
+
+def test_cli_output_directory_is_a_clean_error(tmp_path, library, capsys):
+    rc = cli.main([str(library), "-o", str(tmp_path)])
+    assert rc == 1
+    assert capsys.readouterr().err.startswith("ttl3d: error:")
+
+
+def test_cli_header_only_file_produces_an_empty_page(tmp_path, capsys):
+    ttl = tmp_path / "header.ttl"
+    ttl.write_text("@prefix owl: <http://www.w3.org/2002/07/owl#> .\n"
+                   "<http://example.org/o> a owl:Ontology .\n", encoding="utf-8")
+    out = tmp_path / "header.html"
+    assert cli.main([str(ttl), "-o", str(out)]) == 0
+    assert "0 nodes" in capsys.readouterr().out and out.exists()
+
+
+def test_cli_announces_a_big_stress_layout_on_stderr(tmp_path, capsys):
+    from ttl3d import layout
+    n = layout.PROGRESS_MIN_NODES + 1
+    ttl = tmp_path / "big.ttl"
+    ttl.write_text("@prefix ex: <http://example.org/b#> .\n"
+                   + "".join(f"ex:n{i} ex:p ex:n{i + 1} .\n" for i in range(n)), encoding="utf-8")
+    assert cli.main([str(ttl), "-o", str(tmp_path / "big.html")]) == 0
+    assert "stress layout" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("view", ["3d", "2d"])
+def test_cli_output_is_identical_across_processes(tmp_path, view):
+    pages = []
+    for seed in ("1", "2"):
+        out = tmp_path / f"solar-{seed}.html"
+        r = subprocess.run([sys.executable, "-m", "ttl3d",
+                            str(REPO / "examples" / "solar-system.ttl"),
+                            str(REPO / "examples" / "solar-system-missions.ttl"),
+                            "-o", str(out), "--view", view],
+                           capture_output=True, text=True, cwd=REPO, check=False,
+                           env={**os.environ, "PYTHONHASHSEED": seed})
+        assert r.returncode == 0, r.stderr
+        pages.append(out.read_bytes())
+    assert pages[0] == pages[1]
+
+
+def test_cli_lang_picks_the_label_language(tmp_path):
+    ttl = tmp_path / "lang.ttl"
+    ttl.write_text("@prefix ex: <http://example.org/l#> .\n"
+                   "@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n"
+                   'ex:z rdfs:label "Zebra"@en, "Antilope"@de ; ex:p ex:b .\n', encoding="utf-8")
+    out = tmp_path / "l.html"
+    cli.main([str(ttl), "-o", str(out)])
+    assert '"label": "Zebra"' in out.read_text(encoding="utf-8")
+    cli.main([str(ttl), "-o", str(out), "--lang", "de"])
+    assert '"label": "Antilope"' in out.read_text(encoding="utf-8")
+
+
+def test_cli_format_flag(tmp_path, library):
+    weird = tmp_path / "data.txt"
+    weird.write_text(library.read_text(encoding="utf-8"), encoding="utf-8")
+    out = tmp_path / "f.html"
+    assert cli.main([str(weird), "-o", str(out), "--format", "xml"]) == 1      # forced parser rejects Turtle
+    assert cli.main([str(weird), "-o", str(out), "--format", "turtle"]) == 0 and out.exists()
+
+
+def test_cli_type_links_and_attribute_preds(tmp_path, library):
+    out = tmp_path / "t.html"
+    cli.main([str(library), "-o", str(out), "--type-links", "--attribute-preds", "ex:wrote,rdfs:subClassOf"])
+    payload = out.read_text(encoding="utf-8").split("const DATA = ", 1)[1].split(";\n", 1)[0]
+    assert '"predicates": ["type"]' in payload          # Herbert -> Author is now drawn
+    assert '"predicates": ["wrote"]' not in payload     # ex:wrote is demoted to the card
+    assert '"predicates": ["subClassOf"]' not in payload
+
+
+def test_cli_unknown_prefix_in_attribute_preds_is_a_clean_error(tmp_path, library, capsys):
+    rc = cli.main([str(library), "-o", str(tmp_path / "x.html"), "--attribute-preds", "nope:thing"])
+    assert rc == 1 and "nope" in capsys.readouterr().err
+
+
+def test_cli_pages_start_in_3d(tmp_path, library):
+    out = tmp_path / "d.html"
+    assert cli.main([str(library), "-o", str(out)]) == 0
+    assert '"view": "3d"' in out.read_text(encoding="utf-8")
+
+
+def _first_node(page_path):
+    payload = page_path.read_text(encoding="utf-8").split("const DATA = ", 1)[1].split(";\n", 1)[0]
+    return json.loads(payload)["nodes"][0]
+
+
+def test_cli_pinned_pages_carry_a_layout_per_view(tmp_path, library):
+    out = tmp_path / "p.html"
+    assert cli.main([str(library), "-o", str(out)]) == 0
+    assert {"x", "y", "z", "x2", "y2"} <= set(_first_node(out))
+    assert cli.main([str(library), "-o", str(out), "--layout", "force"]) == 0
+    assert not {"x", "y", "z", "x2", "y2"} & set(_first_node(out))
+
+
+def test_cli_view_flag_sets_the_starting_view_and_the_default_name(tmp_path, library, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    assert cli.main([str(library), "--view", "2d"]) == 0
+    assert '"view": "2d"' in (tmp_path / "library-2d.html").read_text(encoding="utf-8")
+    assert "view: 2d" in capsys.readouterr().out
+
+
+def test_cli_rejects_an_unknown_view(library):
+    with pytest.raises(SystemExit) as e:
+        cli.main([str(library), "--view", "4d"])
+    assert e.value.code == 2
+
+
+def test_output_naming_an_input_in_another_case_is_refused_where_the_filesystem_ignores_case(tmp_path, library,
+                                                                                            capsys):
+    (tmp_path / "probe").write_text("", encoding="utf-8")
+    if not (tmp_path / "PROBE").exists():
+        pytest.skip("case-sensitive filesystem")
+    src = tmp_path / "graph.ttl"
+    src.write_text(library.read_text(encoding="utf-8"), encoding="utf-8")
+    rc = cli.main([str(src), "-o", str(tmp_path / "GRAPH.TTL")])
+    assert rc == 1 and "also an input" in capsys.readouterr().err
+    assert src.read_text(encoding="utf-8") == library.read_text(encoding="utf-8")   # the input is intact
+
+
+ASCII_CONSOLE = {**os.environ, "PYTHONIOENCODING": "ascii"}   # a console that cannot show an é
+
+
+def test_an_error_message_survives_a_console_that_cannot_encode_it(tmp_path):
+    bad = tmp_path / "données.ttl"
+    bad.write_text("@prefix ex: <http://example.org/é#> .\nex:a ex:b \"unterminated .\n", encoding="utf-8")
+    r = subprocess.run([sys.executable, "-m", "ttl3d", str(bad), "-o", str(tmp_path / "out.html")],
+                       capture_output=True, env=ASCII_CONSOLE, cwd=REPO, check=False)
+    err = r.stderr.decode("ascii")
+    assert r.returncode == 1 and err.startswith("ttl3d: error:") and "Traceback" not in err, err
+
+
+def test_the_summary_line_survives_a_console_that_cannot_encode_the_output_path(tmp_path, library):
+    out = tmp_path / "sortie-é.html"
+    r = subprocess.run([sys.executable, "-m", "ttl3d", str(library), "-o", str(out)],
+                       capture_output=True, env=ASCII_CONSOLE, cwd=REPO, check=False)
+    assert r.returncode == 0 and out.exists(), r.stderr.decode("ascii", "replace")
+    assert r.stdout.decode("ascii").split()[0].isdigit()