c16 Controls — QMap Configuration Surface

Controls that wrapper components use to configure QMap behavior. Each control is either a QMap prop today, a behavior config field, or a gap to fill.

1. View (Camera Preset)

What: Switch between isometric and top-down camera angles.

• Defined in CAMERA_PRESETS — viewContext.js:102-105
• Isometric: ~55° angle + 38° rotation
• Top-down: ~100° angle + 0° rotation
• Status: QMap prop. Applied instantly on mount, animated on change via animateCameraFocus(). Exported from src/index.js as CAMERA_PRESETS.

2. User Controls (Interactive)

What: Enable or disable pan, zoom, and rotate.

• selectable is already a QMap prop — controls click-to-select behavior
• interactive is behavior-only — controls camera interaction (pan/zoom/rotate)
• Status: QMap prop. Wired to SceneManager.enableControls()/disableControls() via watcher. If false on mount, controls are disabled after scene init.

3. View Mode (Grouping)

What: Control how actors are spatially grouped — by type, infrastructure topology, or geography.

Wrappers call computeGrouping(actors, mode, options) from src/core/GroupingStrategy.js and pass the result's groupBy to QMap.

Three modes:

• group — Groups by actor type (App, Database, Vendor, etc.). Always safe — synthesizes _actorType from actor.type.
• topology — Groups by infra tags (Cloud > Region > Pod Namespace). Data-dependent.
• geography — Groups by geo tags (Continent > Country > City). Data-dependent.

Caution on data-dependent modes: Topology and geography require actors to carry matching tag keys. When tags are missing, actors silently fall to root level (ungrouped) — no error, just a flat layout. Wrappers should validate before enabling these modes:

import { getAvailableTags, getAvailableTagsByType } from 'qmap'

const tags = getAvailableTags(actors)          // all unique tag keys
const byType = getAvailableTagsByType(actors)  // { app: ['Team', 'Cloud'], ... }

// Only show topology mode if actors have the required tags
const canTopology = topologyTags.every(t => tags.includes(t))

Group mode is always safe as a default/fallback.

4. Actor Focus

What: Programmatically select an actor and frame the camera on it.

• Gap: Not a QMap prop. Today wrappers reach through defineExpose to call selection.selectActor(actorId).
• The exposed selection object has selectActor(), clearSelection(), and refreshSelection().
• To implement as a prop: add focusActorId to QMap, watch it, call selection.selectActor() on change and selection.clearSelection() when set to null.

5. Dataflow Focus

What: Highlight a specific connection between two actors.

• Gap: Not implemented at any level. useActorSelection is actor-centric — selecting an actor shows its flows, but there's no way to select a specific connection directly.
• To implement: find both endpoint actors from the connection, create the flow line between them, frame the camera to contain both actors, and apply a highlight style to the flow.
• Depends on actor focus working first.

Future Ideas

Not designed yet — brief notes for reference:

• highlights — Array of { match, style } rules applied to actor meshes. Infrastructure exists in viewContext.js (applyHighlights, HIGHLIGHT_STYLES) but not as a QMap prop.
• autoPlay / autoPlaySequence — Scripted actor selection sequence for demos. Behavior config fields exist, wrappers implement the timer loop.
• renderMode — 'interactive' vs 'snapshot' for headless image generation.
• cameraAngle / cameraRotation — Fine-grained camera control beyond presets.
• flowFilter — Filter which connections are visualized (by protocol, volume threshold, etc.).
• dragMode — Switch between pan-on-drag and select-on-drag behaviors.