← Qmap · c16

PLAN.md

c16.view-contexts — Cycle Plan

Contents
  1. Context
  2. What c16 Explores
  3. Steps
  4. Verification
  5. Key Files to Reference

Context

QMap is now a production component (c15) with a props-driven API: <QMap :actors :connections :groupBy />. But different consumers need fundamentally different configurations — a policy violation page needs a focused, non-interactive view highlighting specific flows; the marketing site needs an animated demo; a worker needs to render a static image for a report.

The initial prompt asks: what's the best way to codify these "views" for simple use?

Answer: Wrapper components. Each view is its own component that internally configures QMap with the right defaults. The system must support:

  • Same data, different framing (security audit vs traffic overview)
  • Different data shapes entirely (policy violation vs network map)
  • Interactive browser use AND headless/worker image generation

What c16 Explores

Core question: What is the right "view context" abstraction that wrapper components use to configure QMap?

View Context Shape (to be designed in the experiment)

A view context likely includes:

  • Data selection — which actors/connections to show, filtering/highlighting rules
  • Layout — groupBy config, camera position/angle, frustumSize
  • Visual treatment — highlight colors, flow emphasis, selection behavior
  • Interactivity — selectable, camera controls enabled, click behavior
  • Rendering mode — interactive (canvas in DOM) vs snapshot (offscreen → image)

Experiment Strategies to Explore

  1. Strategy A: Config object — createViewContext(type, overrides) returns a plain config object. Wrapper components spread it as QMap props.
  2. Strategy B: Composable — useViewContext(type) returns reactive refs + methods. Wrapper components get computed props that respond to data changes.
  3. Strategy C: Slot-based — QMap exposes named slots/render hooks. Wrapper components inject behavior via slots rather than props.

Example Wrapper Components to Prototype

  1. <QMapPolicyViolation> — Takes a policy violation payload, highlights offending actors/flows in red, dims everything else, non-interactive, tight camera framing
  2. <QMapNetworkOverview> — Full actor set, interactive, grouping controls exposed
  3. <QMapDemo> — Curated actors, auto-rotating camera, scripted selection sequence for marketing

Files to Create

dev/experiments/c16.view-contexts/
├── ExperimentsApp.vue              # Strategy switcher + demo harness
├── shared/
│   ├── ExperimentBase.js           # Copy from c14 (useExperiment composable)
│   ├── viewContext.js              # Core abstraction: createViewContext()
│   ├── views/
│   │   ├── policyViolation.js      # View config for policy violation
│   │   ├── networkOverview.js      # View config for full network map
│   │   └── demo.js                 # View config for marketing demo
│   └── data/
│       ├── policyViolationData.js  # Sample violation payload
│       └── demoData.js             # Curated demo actors
├── components/
│   ├── QMapPolicyViolation.vue     # Wrapper: policy violation view
│   ├── QMapNetworkOverview.vue     # Wrapper: interactive overview
│   └── QMapDemo.vue                # Wrapper: marketing demo

Key Design Questions to Answer

  1. How much of the view config is "QMap props" vs "new behavior"? (e.g., camera auto-animation isn't a QMap prop today)
  2. Should QMap gain new props (e.g., highlights, cameraPreset, interactive) or should wrapper components manipulate it externally?
  3. How does snapshot/image rendering work? (offscreen canvas, renderer.domElement.toDataURL(), or headless Three.js?)

Steps

  1. Scaffold c16 — Create dev/experiments/c16.view-contexts/ with ExperimentsApp.vue and shared base
  2. Design viewContext.js — The core abstraction. Start with Strategy A (config object), evolve if needed
  3. Build policyViolation view — Simplest case: filtered data, highlight config, non-interactive
  4. Build networkOverview view — Interactive case: full data, grouping, selection
  5. Build demo view — Scripted animation case: auto-play, curated data
  6. Wire ExperimentsApp — Toggle between the three wrapper components
  7. Document — Write CYCLE.md with findings on which abstraction works best

Verification

  • npm run dev → navigate to c16 experiment page
  • Toggle between three wrapper components in the experiment harness
  • Each wrapper should render QMap with its distinct visual treatment
  • Policy violation: focused, highlighted actors, no interaction
  • Network overview: full interactive map
  • Demo: auto-animated sequence

Key Files to Reference

  • src/components/QMap.vue — Current props API (actors, connections, groupBy, selectable, etc.)
  • src/composables/useSceneReactivity.js — How props drive scene updates
  • src/composables/useActorSelection.js — Selection/highlight system
  • src/core/CameraControls.js — Camera manipulation API
  • dev/experiments/c14.actor-expansion/ExperimentsApp.vue — Latest experiment harness pattern
  • dev/experiments/c14.actor-expansion/shared/ExperimentBase.js — Composable to copy

Qpoint Brand Style Guide