visiter 0.1.0__tar.gz

visiter-0.1.0/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Edit(*)",
+      "Write(*)",
+      "Read(*)",
+      "Glob(*)",
+      "Grep(*)",
+      "Agent(*)",
+      "NotebookEdit(*)",
+      "WebFetch(*)",
+      "WebSearch(*)",
+      "TodoWrite(*)"
+    ],
+    "deny": [
+      "Bash(git push*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git commit *)",
+            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"ask\", \"permissionDecisionReason\": \"git commit requires user approval\"}}'",
+            "statusMessage": "Checking git commit..."
+          }
+        ]
+      }
+    ]
+  }
+}

visiter-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.swp
+.DS_Store
+demos/out/
+

visiter-0.1.0/CLAUDE.md

@@ -0,0 +1,218 @@
+# CLAUDE.md — VisIter project notes for Claude Code
+
+This file collects project-specific conventions, design decisions, and
+workflow rules that were agreed on during the initial extraction of
+VisIter from the `_math` research project. Read this at the start of
+every session before making non-trivial changes.
+
+---
+
+## 1. Project purpose
+
+VisIter provides two composable pieces:
+
+- **`iterate`** — builds an iteration graph from guard-and-op Rules via
+  BFS, records per-node depth, and emits pseudo-edges for structural
+  boundaries (`Rule.bound`, `max_depth`).
+- **`to_dot`** — converts the graph dict into a `graphviz.Digraph` with
+  cropping, coloring, ghost stubs, and node annotations.
+
+They are connected only by a documented dict shape (see
+`docs/manual.md` §6). Either can be used without the other.
+
+---
+
+## 2. Design decisions already made
+
+These are the results of deliberate earlier discussions; do not
+re-litigate without a clear reason.
+
+### API shape
+
+- `iterate(start, rules, *, default, ...)` — `default` is required
+  (keyword-only, no Python default value) to force the caller to make
+  the "no rule matched" case explicit. Pass `None` for "that value is
+  a leaf"; pass an `Op` for the else branch.
+- `Rule(condition, op, bound=None)` — three-field namedtuple. The
+  `condition` asks "is this op applicable at all?" (mathematical
+  predicate). The optional `bound` asks "should we stop here anyway?"
+  (structural cutoff). When `condition` is True but `bound` is False,
+  a pseudo-edge is recorded and the renderer draws a ghost stub.
+- `Op(func, label)` — the label is the identity key for color
+  assignment, ordering, and op_colors lookup. Two Op instances with
+  the same label are treated as the same op.
+- iterate uses **BFS** (not DFS) so each node's recorded `depth` is
+  the minimum hop count from the nearest start.
+- `on_limit` governs `max_nodes` and `time_limit` ("raise" or "stop").
+  `max_depth` is always a soft topological stop; it does not raise.
+- The graph dict is the single data contract. `op_order` is part of it
+  and drives palette assignment; it follows rule-declaration order
+  (not traversal-first-seen). Preserve `op_order` across any
+  transformation that rewrites the graph (e.g. cropping in `to_dot`).
+
+### Rendering model
+
+- **Two-layer palette**: each palette slot is a `(fill, edge)` pair.
+  Light pastel for node fills (readable labels), saturated mid-tone
+  for edges (visible thin lines). The caller can override via
+  `op_colors` with a single hex (applies to both) or a tuple (fill,
+  edge).
+- **Highlight** (the `"highlight"` tag): darkens fills in **HSL
+  space** (lightness-only reduction, hue+saturation preserved), not
+  RGB-toward-black. RGB-toward-black desaturates; HSL preserves the
+  color identity. Default factor 0.45.
+- **Node fill comes from outgoing op labels**, not from node identity.
+  0 out-ops → no fill (leaf, default white). 1 out-op → solid fill.
+  N ≥ 2 → `style="wedged"` with colon-joined colors (pie segments).
+- **Roots** are marked with `penwidth="3"` (bold border). Not with
+  `peripheries`, not with a distinct fill.
+- **Ghost stubs** appear for three reasons, all rendered the same:
+  (a) outgoing cut (kept_src → outside_dst filtered),
+  (b) incoming cut (outside_src → kept_dst filtered),
+  (c) pseudo-edge (iterate recorded Rule.bound=False or max_depth).
+  All three fold into one `cut_edges` list with a `kept_is_src` flag.
+  Only case (a) and (c) contribute to `extra_out_ops` (fill lives on
+  outgoing edges only — incoming cuts don't need a fill counterpart).
+
+### CLI shape
+
+- **One** entry point `visiter` with subcommands. Subcommands are
+  registered in `src/visiter/cli.py::SUBCOMMANDS`. Adding a new
+  subcommand means writing a module with a `main()` function and
+  adding one entry there.
+- **Each subcommand takes a single positional Python expression** as
+  its "argstring", spliced into the corresponding function call and
+  eval'd in a namespace where `Op`, `Rule`, `iterate`, `to_dot`, and
+  `graph` (for to-dot) are pre-bound. This deliberately avoids a
+  per-flag DSL — any Python-API kwarg is expressible on the shell,
+  and future API additions cost nothing in CLI glue.
+- **Pipe composition is the idiom**: `visiter iterate '...' | visiter
+  to-dot '...' | dot -Tsvg > out.svg`. Input/output conventions are
+  stdin/stdout with `--input FILE` / `-o FILE` overrides.
+- `eval` is appropriate: this is a local research tool, not a
+  network-exposed service. Errors propagate as normal Python
+  exceptions; no parser front-end to misdiagnose input.
+
+### Why subcommands (not separate console scripts)
+
+We explicitly chose the subcommand layout over multiple separate
+`visiter-X` scripts because we expect more commands to be added
+(e.g. `analyze` for jq-style queries over the graph JSON, `stats` for
+depth-distribution/fan-out summaries, `diff` for comparing two
+iteration graphs). One stable command name, `visiter --help` as a
+single discovery point, and a minimal dispatcher makes that growth
+cheap.
+
+---
+
+## 3. Workflow rules
+
+### Commits
+
+- **Use conventional-commit prefixes** (`feat:`, `fix:`, `refactor:`,
+  `docs:`, `chore:`, `test:`). Match the ones already in the log.
+- **Never add `Co-Authored-By` trailers.** Not here, not anywhere.
+- **Always propose the commit message first and wait for user
+  approval** before executing the commit. The user says "ja" / "okay"
+  or asks for changes.
+- **Message describes net diff, not session steps.** A mid-session
+  dead-end doesn't belong in the message.
+- **Before every `git commit`, run `git status`** and cross-check
+  that the staged set matches the work. Nothing relevant should be
+  left Untracked or unstaged. Files referenced by the commit message
+  must actually be in the commit.
+- **Don't ask "commit or review first?"** — the user reviews before
+  saying "commit". The question is a false dichotomy.
+- **Never `git push`** without explicit user request. (Enforced by
+  the deny rule in `.claude/settings.json`.)
+
+### Verification
+
+- **Always verify.** `make test` after any logic change. `make build`
+  after any packaging change. For CLI changes, at least one
+  end-to-end pipe-through-dot smoke test.
+- **Don't report success without confirming.** Build output, test
+  status, or rendered artefact is what confirms; "I think it works"
+  is not.
+
+### Testing
+
+- Tests live in `tests/`. They use only the public package API
+  (`from visiter import …`), not internal paths, so we'd notice if
+  re-exports drift.
+- New features: add at least one test exercising the happy path and
+  one exercising a limit/error case (e.g. `max_nodes` raise vs stop).
+- When a bug is found, the repro-first rule applies: write a failing
+  test, confirm it fails, then fix, then confirm it passes.
+
+### Dependencies
+
+- **Never `pip install` directly**. Add to `pyproject.toml` (core
+  deps or `[project.optional-dependencies].dev`), then `make setup`.
+- Keep the dep list minimal. Currently `graphviz` and `sympy`;
+  anything new needs a clear justification.
+
+---
+
+## 4. Open topics (not decided, worth revisiting)
+
+### Versioning of the eval-based CLI
+
+The CLI eval contract means any shell script that embeds an argstring
+is effectively coupled to the **implementation version** of the
+called function — its parameter names, `Rule`/`Op` fields, default
+behavior, etc. If we change a parameter name or add a required field
+to `Rule`, downstream shell scripts break silently-until-executed.
+
+Unresolved:
+
+- Should we document a stability guarantee (semver-style, where
+  parameter-name / signature breakage requires a major bump)?
+- Should the CLI check some form of `visiter.__version__` in the
+  argstring context, so scripts can assert compatibility?
+- Is there a less-coupled interface worth exposing alongside (e.g. a
+  JSON-in / JSON-out config for the common cases) without losing the
+  expressivity of eval?
+
+This should be addressed before `v1.0`.
+
+### Other candidates for future work
+
+- `visiter analyze` subcommand: jq-style or xpath-like queries over
+  the graph JSON (e.g. "show all nodes with depth > 5 and fan-out >
+  1").
+- `visiter stats`: depth distribution, op frequency, average fan-out,
+  cycle detection summary.
+- `visiter diff`: compare two graphs structurally (added/removed
+  nodes/edges, shifted depths).
+- Depth-based rendering affordances (`to_dot` `depth_gradient=True`,
+  or per-depth op_colors override).
+- A proper Graphviz-side timeout that's integrated rather than left
+  to callers (the `with_timeout` wrapper in the notebook).
+
+---
+
+## 5. Pointers
+
+- Package source: `src/visiter/`
+- Public API surface: `src/visiter/__init__.py`
+- Subcommand registry: `src/visiter/cli.py`
+- Tests: `tests/`
+- User-facing docs: `README.md` (quickstart) and `docs/manual.md`
+  (full reference, including the graph-dict shape)
+- Build / test / publish pipeline: `Makefile`
+
+---
+
+## 6. Things that are NOT conventions
+
+Don't propagate from other codebases without re-litigating:
+
+- No Python typing (`type: ignore`, `TYPE_CHECKING`, `typing.Protocol`) is
+  used pervasively yet. If you start adding annotations, do it
+  consistently and run mypy — don't sprinkle them.
+- No linter/formatter is configured yet. Don't reformat existing code
+  on unrelated changes.
+- No GitHub Actions, no pre-commit hooks, no automated release
+  pipeline. All of these are reasonable next steps but should be
+  introduced deliberately, not opportunistically.

visiter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakob Stemberger
+
+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.

visiter-0.1.0/Makefile

@@ -0,0 +1,46 @@
+VENV := .venv
+VENV_BIN := $(VENV)/bin
+VENV_STAMP := $(VENV)/.installed
+
+.PHONY: setup test demo build publish test-publish clean help
+
+help:
+	@echo "Targets:"
+	@echo "  setup         create venv and install package + dev deps"
+	@echo "  test          run pytest"
+	@echo "  demo          run all demos/*.sh (writes to demos/out/)"
+	@echo "  build         build sdist + wheel into dist/"
+	@echo "  publish       upload dist/ to PyPI (requires credentials)"
+	@echo "  test-publish  upload dist/ to TestPyPI"
+	@echo "  clean         remove build artefacts"
+
+setup: $(VENV_STAMP)
+
+$(VENV_STAMP): pyproject.toml
+	python3 -m venv $(VENV)
+	$(VENV_BIN)/pip install -U pip
+	$(VENV_BIN)/pip install -e ".[dev]"
+	@touch $@
+
+test: setup
+	$(VENV_BIN)/pytest
+
+demo: setup
+	@command -v dot >/dev/null || { echo "demos require 'dot' (Graphviz) on PATH"; exit 1; }
+	@for s in demos/*.sh; do \
+	    echo "== $$s =="; \
+	    PATH="$(CURDIR)/$(VENV_BIN):$$PATH" bash "$$s" || exit 1; \
+	done
+	@echo "all demos succeeded — see demos/out/"
+
+build: setup clean
+	$(VENV_BIN)/python -m build
+
+test-publish: build
+	$(VENV_BIN)/python -m twine upload --repository testpypi dist/*
+
+publish: build
+	$(VENV_BIN)/python -m twine upload dist/*
+
+clean:
+	rm -rf dist/ build/ src/visiter.egg-info src/*.egg-info

visiter-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: visiter
+Version: 0.1.0
+Summary: Build and visualize iteration graphs from rule-based state transitions.
+Project-URL: Homepage, https://github.com/yaccob/visiter
+Project-URL: Issues, https://github.com/yaccob/visiter/issues
+Author-email: Jakob Stemberger <jakob.stemberger@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: bfs,graph,graphviz,iteration,state-transition,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Requires-Dist: graphviz>=0.20
+Requires-Dist: sympy>=1.10
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: jsonschema>=4.18; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine>=4; extra == 'dev'
+Provides-Extra: validate
+Requires-Dist: jsonschema>=4.18; extra == 'validate'
+Description-Content-Type: text/markdown
+
+# VisIter
+
+Build and visualize iteration graphs from rule-based state transitions.
+
+VisIter is a small library that does two complementary things:
+
+1. **`iterate(start, rules, default=..., max_depth=..., ...)`** —
+   applies a list of guard-and-operation Rules to seed values via BFS,
+   producing a graph (nodes, edges, per-node depth, optional pseudo-edges
+   marking structural boundaries).
+
+2. **`to_dot(graph, ...)`** — turns the graph into a Graphviz
+   Digraph for SVG/HTML/PDF rendering, with anchor/radius cropping,
+   per-rule edge coloring, wedged-pie node fills for branching nodes,
+   and dashed ghost stubs at every kind of cut boundary.
+
+The two are independent: any graph dict that fits the documented shape
+can be rendered, and `iterate` can be used purely for graph construction
+without ever touching the renderer.
+
+## Install
+
+```bash
+pip install visiter
+```
+
+Graphviz must be available on `PATH` for image rendering (the Python
+`graphviz` package wraps the system tool).
+
+## Quickstart — descent with divisor rule
+
+A rule that divides by three when applicable, with a `+2` fallback for
+all other values. Every integer path eventually joins one of two small
+cycles (`1 → 3 → 1`, `2 → 4 → 6 → 2`).
+
+```python
+from visiter import iterate, Op, Rule, to_dot
+
+graph = iterate(
+    start=range(1, 30),
+    rules=[Rule(lambda x: x % 3 == 0, Op(lambda x: x // 3, "÷3"))],
+    default=Op(lambda x: x + 2, "+2"),
+)
+dot = to_dot(graph, anchor=1, radius=8, direction="backward")
+dot.render("descent", format="svg")
+```
+
+## Quickstart — reverse binary tree with bound
+
+Generate every positive integer up to a ceiling as the binary tree of
+`×2` / `×2+1` successors of 1. `Rule.bound` keeps the expansion inside
+the ceiling; to_dot draws the frontier as dashed ghost stubs.
+
+```python
+from visiter import iterate, Op, Rule, to_dot
+
+ceiling = 64
+
+graph = iterate(
+    start=[1],
+    rules=[
+        Rule(lambda x: True,
+             Op(lambda x: 2 * x, "×2"),
+             bound=lambda x: 2 * x <= ceiling),
+        Rule(lambda x: True,
+             Op(lambda x: 2 * x + 1, "×2+1"),
+             bound=lambda x: 2 * x + 1 <= ceiling),
+    ],
+    default=None,
+)
+dot = to_dot(graph, show_binary=True)
+dot.render("binary_tree", format="svg")
+```
+
+## CLI
+
+A single `visiter` command with subcommands. Each subcommand takes its
+function's keyword arguments as a single Python expression that is
+`eval`'d in a namespace where `Op`, `Rule`, `iterate`, and `to_dot` are
+pre-bound. Output is JSON (`iterate`) and DOT (`to-dot`) on stdout, so
+they pipe directly:
+
+```bash
+visiter iterate 'range(1, 30),
+                 [Rule(lambda x: x%3==0, Op(lambda x: x//3, "÷3"))],
+                 default=Op(lambda x: x+2, "+2")' \
+  | visiter to-dot 'anchor=1, radius=8, direction="backward"' \
+  | dot -Tsvg > descent.svg
+```
+
+The `validate` subcommand checks a graph JSON document against the
+bundled JSON Schema (`schemas/v1/graph.schema.json`, Draft 2020-12):
+
+```bash
+pip install visiter[validate]
+visiter iterate '...' | visiter validate
+```
+
+## Documentation
+
+- [docs/tutorial.md](docs/tutorial.md) — gentle introduction: what
+  problem the tool solves, smallest example, what each piece does,
+  what the dashed arrows mean. Start here.
+- [docs/manual.md](docs/manual.md) — reference: every parameter,
+  every data field, the rendering model in full, design decisions.
+- [demos/](demos/) — runnable end-to-end examples: `make demo` writes
+  SVG/PDF/DOT into `demos/out/`.
+
+## License
+
+MIT

visiter-0.1.0/README.md

@@ -0,0 +1,111 @@
+# VisIter
+
+Build and visualize iteration graphs from rule-based state transitions.
+
+VisIter is a small library that does two complementary things:
+
+1. **`iterate(start, rules, default=..., max_depth=..., ...)`** —
+   applies a list of guard-and-operation Rules to seed values via BFS,
+   producing a graph (nodes, edges, per-node depth, optional pseudo-edges
+   marking structural boundaries).
+
+2. **`to_dot(graph, ...)`** — turns the graph into a Graphviz
+   Digraph for SVG/HTML/PDF rendering, with anchor/radius cropping,
+   per-rule edge coloring, wedged-pie node fills for branching nodes,
+   and dashed ghost stubs at every kind of cut boundary.
+
+The two are independent: any graph dict that fits the documented shape
+can be rendered, and `iterate` can be used purely for graph construction
+without ever touching the renderer.
+
+## Install
+
+```bash
+pip install visiter
+```
+
+Graphviz must be available on `PATH` for image rendering (the Python
+`graphviz` package wraps the system tool).
+
+## Quickstart — descent with divisor rule
+
+A rule that divides by three when applicable, with a `+2` fallback for
+all other values. Every integer path eventually joins one of two small
+cycles (`1 → 3 → 1`, `2 → 4 → 6 → 2`).
+
+```python
+from visiter import iterate, Op, Rule, to_dot
+
+graph = iterate(
+    start=range(1, 30),
+    rules=[Rule(lambda x: x % 3 == 0, Op(lambda x: x // 3, "÷3"))],
+    default=Op(lambda x: x + 2, "+2"),
+)
+dot = to_dot(graph, anchor=1, radius=8, direction="backward")
+dot.render("descent", format="svg")
+```
+
+## Quickstart — reverse binary tree with bound
+
+Generate every positive integer up to a ceiling as the binary tree of
+`×2` / `×2+1` successors of 1. `Rule.bound` keeps the expansion inside
+the ceiling; to_dot draws the frontier as dashed ghost stubs.
+
+```python
+from visiter import iterate, Op, Rule, to_dot
+
+ceiling = 64
+
+graph = iterate(
+    start=[1],
+    rules=[
+        Rule(lambda x: True,
+             Op(lambda x: 2 * x, "×2"),
+             bound=lambda x: 2 * x <= ceiling),
+        Rule(lambda x: True,
+             Op(lambda x: 2 * x + 1, "×2+1"),
+             bound=lambda x: 2 * x + 1 <= ceiling),
+    ],
+    default=None,
+)
+dot = to_dot(graph, show_binary=True)
+dot.render("binary_tree", format="svg")
+```
+
+## CLI
+
+A single `visiter` command with subcommands. Each subcommand takes its
+function's keyword arguments as a single Python expression that is
+`eval`'d in a namespace where `Op`, `Rule`, `iterate`, and `to_dot` are
+pre-bound. Output is JSON (`iterate`) and DOT (`to-dot`) on stdout, so
+they pipe directly:
+
+```bash
+visiter iterate 'range(1, 30),
+                 [Rule(lambda x: x%3==0, Op(lambda x: x//3, "÷3"))],
+                 default=Op(lambda x: x+2, "+2")' \
+  | visiter to-dot 'anchor=1, radius=8, direction="backward"' \
+  | dot -Tsvg > descent.svg
+```
+
+The `validate` subcommand checks a graph JSON document against the
+bundled JSON Schema (`schemas/v1/graph.schema.json`, Draft 2020-12):
+
+```bash
+pip install visiter[validate]
+visiter iterate '...' | visiter validate
+```
+
+## Documentation
+
+- [docs/tutorial.md](docs/tutorial.md) — gentle introduction: what
+  problem the tool solves, smallest example, what each piece does,
+  what the dashed arrows mean. Start here.
+- [docs/manual.md](docs/manual.md) — reference: every parameter,
+  every data field, the rendering model in full, design decisions.
+- [demos/](demos/) — runnable end-to-end examples: `make demo` writes
+  SVG/PDF/DOT into `demos/out/`.
+
+## License
+
+MIT

visiter-0.1.0/demos/01_one_data_many_views.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Generate one iteration graph, then render it three different ways:
+#   (a) full backward neighborhood of the cycle attractor at 1
+#   (b) a tight 2-hop crop around 1 (shows the ghost-stub mechanism)
+#   (c) full graph with custom op_colors
+# All three views share the same input data (descent.json), proving
+# that iterate and to_dot are decoupled by the documented graph dict.
+set -euo pipefail
+cd "$(dirname "$0")"
+mkdir -p out
+
+DATA="out/descent.json"
+EXPR="$(cat data/descent.expr)"
+
+visiter iterate "$EXPR" > "$DATA"
+echo "wrote $DATA"
+
+visiter to-dot 'anchor=1, radius=10, direction="backward"' \
+  < "$DATA" > out/descent_full.dot
+dot -Tsvg out/descent_full.dot -o out/descent_full.svg
+echo "wrote out/descent_full.svg"
+
+visiter to-dot 'anchor=1, radius=2, direction="backward"' \
+  < "$DATA" > out/descent_tight.dot
+dot -Tsvg out/descent_tight.dot -o out/descent_tight.svg
+echo "wrote out/descent_tight.svg (tight crop — note the ghost stubs)"
+
+visiter to-dot 'op_colors={"÷3": "#a83232", "+2": "#3266a8"}' \
+  < "$DATA" > out/descent_recolored.dot
+dot -Tsvg out/descent_recolored.dot -o out/descent_recolored.svg
+echo "wrote out/descent_recolored.svg (custom palette)"

visiter-0.1.0/demos/02_pipeline_to_pdf.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Full pipe composition: build a graph, render to DOT, hand to `dot` for
+# layout + format conversion. Two output formats demonstrate that the
+# downstream stage is just a Graphviz invocation.
+set -euo pipefail
+cd "$(dirname "$0")"
+mkdir -p out
+
+# Reverse binary tree: from 1, doubling and double-plus-one until 64.
+EXPR='start=[1], rules=[
+    Rule(lambda x: True, Op(lambda x: 2*x, "×2"),
+         bound=lambda x: 2*x <= 64),
+    Rule(lambda x: True, Op(lambda x: 2*x+1, "×2+1"),
+         bound=lambda x: 2*x+1 <= 64),
+], default=None'
+
+visiter iterate "$EXPR" \
+  | visiter to-dot 'show_binary=True' \
+  | tee out/binary_tree.dot \
+  | dot -Tsvg -o out/binary_tree.svg
+echo "wrote out/binary_tree.svg"
+
+# Same data, PDF instead of SVG.
+dot -Tpdf out/binary_tree.dot -o out/binary_tree.pdf
+echo "wrote out/binary_tree.pdf"

visiter-0.1.0/demos/03_validate_in_pipeline.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Insert schema validation as a pipeline checkpoint. `tee` forks the
+# graph JSON to `visiter validate` (which writes its verdict to stderr
+# / a side file) while the main pipe continues into `to-dot`. If the
+# graph ever drifted from the documented shape — say, after a future
+# breaking change to iterate — this would catch it before rendering.
+set -euo pipefail
+cd "$(dirname "$0")"
+mkdir -p out
+
+EXPR="$(cat data/descent.expr)"
+
+VALIDATE_LOG="out/validate.log"
+visiter iterate "$EXPR" \
+  | tee >(visiter validate > "$VALIDATE_LOG" 2>&1) \
+  | visiter to-dot 'anchor=1, radius=10, direction="backward"' \
+  | dot -Tsvg -o out/descent_validated.svg
+
+# Surface the validator's verdict.
+echo "validator said: $(cat "$VALIDATE_LOG")"
+echo "wrote out/descent_validated.svg"

visiter-0.1.0/demos/04_string_iteration.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Iteration on strings, not numbers. Rule: if the word ends in a vowel,
+# drop the last character. Default: none — words ending in a consonant
+# are leaves. Demonstrates that `iterate`'s value type can be any
+# hashable, str()-able Python object.
+set -euo pipefail
+cd "$(dirname "$0")"
+mkdir -p out
+
+EXPR='start=["banana", "garage", "queue", "iterator"],
+rules=[Rule(lambda s: len(s) > 0 and s[-1] in set("aeiou"),
+            Op(lambda s: s[:-1], "drop-vowel"))],
+default=None'
+
+visiter iterate "$EXPR" \
+  | visiter to-dot '' \
+  | dot -Tsvg -o out/words.svg
+echo "wrote out/words.svg (string-valued iteration)"