feat(visualize): add --canvas flag for Cursor topology view

README.md

@@ -107,7 +107,7 @@ chmod +x threescale-visualize
 ./threescale-visualize ./export -o ./report
 ```
 
-See **[docs/VISUALIZE.md](docs/VISUALIZE.md)** for report layout.
+See **[docs/VISUALIZE.md](docs/VISUALIZE.md)** for report layout and optional Cursor topology canvas.
 
 ---
 

docs/TEST_CASES.md

@@ -426,6 +426,37 @@ Automation references are verified against the repository at the time of writing
 
 ---
 
+### TC-VIZ-004 — Generate Cursor topology canvas from export
+
+| Field | Value |
+|-------|-------|
+| Priority | P2 |
+| CLI | `threescale-visualize --canvas` |
+| Automation | **covered** (`TestVisualizeCanvasFlag`, `TestWriteCanvasTSX`) |
+
+**Preconditions**
+
+- Built `threescale-visualize` binary
+- Valid export directory (fixture or lab export)
+
+**Steps**
+
+1. Run `threescale-visualize ./export --canvas ./topology.canvas.tsx`
+2. Open the generated file in Cursor (`~/.cursor/projects/<workspace>/canvases/`)
+
+**Expected results**
+
+- Exit code 0
+- `.canvas.tsx` contains `TopologyCanvas`, embedded product data, and `cursor/canvas` import
+- No customer-specific paths or tenant names in committed demo (`docs/examples/topology-demo.canvas.tsx` uses `seed_alpha` fixture)
+
+**Notes**
+
+- Canvas is optional; Markdown report is still generated by default
+- Policy chains fall back to `proxy.json` when `policies.json` is empty
+
+---
+
 ## Lab pipeline
 
 ### TC-PIPE-001 — Seed → export → visualize

docs/VISUALIZE.md

@@ -2,13 +2,16 @@
 
 **Optional** tool that generates a Markdown report from a directory exported by `threescale-export`. Useful for migration reviews without opening JSON/YAML manually.
 
+It can also generate a **Cursor IDE topology canvas** (`.canvas.tsx`) for interactive exploration of products, backends, applications, and policies.
+
 To export a tenant, use the [main README](../README.md).
 
 ## Requirements
 
 - Go 1.22+ (to compile; release binary does not require Go)
 - An existing export with `schema_version` **1.0** (`manifest.json` at the root)
 - **No** Admin API, Docker, or `THREESCALE_*` variables required
+- Cursor IDE (only if you open the optional topology canvas)
 
 ## Install
 
@@ -21,13 +24,17 @@ Or download `threescale-visualize-v*.*.*-linux-amd64.tar.gz` from [Releases](htt
 ## Usage
 
 ```bash
-# After an export (default ./export)
+# Markdown report (default ./report)
 bin/threescale-visualize ./export -o ./report
+
+# Report + Cursor topology canvas
+bin/threescale-visualize ./export -o ./report --canvas ./topology.canvas.tsx
 ```
 
 | Flag | Description |
 |------|-------------|
 | `-o`, `--output` | Report directory (default `./report`) |
+| `--canvas` | Write a Cursor IDE topology canvas (`.canvas.tsx`) |
 | `--version` | Binary version |
 
 ## Report layout
@@ -43,6 +50,35 @@ report/
 
 Open `index.md` in GitHub, VS Code, or Cursor to navigate via relative links. Mermaid diagrams render on GitHub and in compatible editors.
 
+## Cursor topology canvas
+
+The canvas is an optional interactive view (charts, product→backend graph, sortable product table with policy names). Generate it from the same export directory:
+
+```bash
+bin/threescale-visualize ./export --canvas ./topology.canvas.tsx
+```
+
+### Open the canvas in Cursor
+
+1. Copy or move the generated file into your Cursor project canvases folder:
+   `~/.cursor/projects/<workspace-id>/canvases/topology.canvas.tsx`
+2. Open the file from the Cursor canvases panel (beside the chat).
+
+The canvas embeds data from **your local export only**. Do not commit generated `.canvas.tsx` files from production tenants to public repositories.
+
+### Demo canvas (lab fixture)
+
+The repository includes a demo generated from the offline fixture (`seed_alpha`, `seed_multi_backend`):
+
+- [`docs/examples/topology-demo.canvas.tsx`](examples/topology-demo.canvas.tsx)
+
+Regenerate it after template changes:
+
+```bash
+bin/threescale-visualize internal/visualize/testdata/export-minimal \
+  --canvas docs/examples/topology-demo.canvas.tsx
+```
+
 ## Demo with seed data
 
 ```bash
@@ -52,13 +88,16 @@ bin/threescale-seed
 # 2. Export lab tenant
 bin/threescale-export --output ./export --include-applications --redact-secrets
 
-# 3. Generate report
-bin/threescale-visualize ./export -o ./report
+# 3. Generate report and optional canvas
+bin/threescale-visualize ./export -o ./report --canvas ./topology.canvas.tsx
 ```
 
+Use `--include-applications` on export when you want subscribed applications in the canvas graph.
+
 ## Limitations (v1)
 
 - Read-only from on-disk export; does not call Admin API
 - Does not include `policies/catalog.json` content (global reference, not tenant config)
+- Policy chains are read from `policies.json` when present, otherwise from `proxy.json` (`policies_config`)
 - Redacted secrets (`***REDACTED***`) are shown as-is — not de-redacted
-- No HTTP server or HTML (planned for future versions)
+- Canvas requires Cursor IDE; the Markdown report works everywhere