Hotspot editor

UI Brief: Hotspot / Imagemap Editor

1. 1. Context: Where Does This Feature Live?
2. 2. Design Alternatives
3. 3. Comparative Evaluation
4. 4. Recommended Approach: Alternative D — "Split Pane in Object Authoring"
5. 5. Detailed Design
6. 6. Priority Mapping
7. 7. Open Design Questions

UI Brief: Hotspot / Imagemap Editor

> For: Front-end developers and AI coding agents

> Feature branch: 048-hotspot-editor

> Companion spec: spec.md

> Platform IA reference: INFORMATION_ARCHITECTURE.md

> Date: 2026-05-05

1. Context: Where Does This Feature Live?

The hotspot editor is an authoring tool for creating interactive regions on graphics. It is not a new top-level page — it extends the existing Object Authoring page (/ws/:workspaceId/object-authoring) which already renders different adapters based on object type (DITA → XML editor, Markdown → text editor, Graphics → asset preview).

The hotspot editor becomes a new mode or adapter for graphics objects, activated when an author wants to add interactive regions to an image.

Existing Object Authoring shell (for reference):

┌────────────────────────────────────────────────────────────┐
│ [Object Authoring Shell] │
│ ─ Object name / breadcrumb │
│ ─ Action bar (save, check-in, check-out, close) │
├────────────────────────────────────────────────────────────┤
│ │
│ [Adapter renders based on object type:] │
│ │
│ DITA: XML structured editor │
│ Markdown: Text editor + live preview pane │
│ Graphics: Asset preview + replace/upload controls │
│ │
└────────────────────────────────────────────────────────────┘

The hotspot editor will extend or replace the Graphics adapter when the graphic has (or is being given) hotspot configurations.

2. Design Alternatives

Five alternative UX approaches are evaluated below. They are not mutually exclusive — the final design will likely combine elements.

Alternative A — "Canvas Overlay" (Dedicated Hotspot Editing Page)

Concept: The hotspot editor is a full-page experience within Object Authoring. When an author opens a graphic's hotspot configuration, the Object Authoring shell renders a canvas editor: the graphic fills the main area with a drawing overlay on top, and a properties sidebar sits to the right.

┌────────────────────────────────────────────────────────────────────┐
│ Hotspot Editor: engine-diagram.png [Save] [✕] │
│ Configuration: "Service Manual 2025" │
├────────────────────────────────────────────────┬───────────────────┤
│ │ │
│ ┌──────────────────────────────────────────┐ │ HOTSPOT PANEL │
│ │ │ │ ─────────────── │
│ │ [GRAPHIC with overlay] │ │ │
│ │ │ │ Selected: #3 │
│ │ ┌─────┐ │ │ Shape: Rectangle │
│ │ │ HS1 │ ○ HS2 │ │ │
│ │ └─────┘ ╱╲ │ │ ── Content ── │
│ │ ╱HS3╲ │ │ [Rich text area] │
│ │ ╱────╲ │ │ │
│ │ │ │ ── Target ── │
│ │ │ │ [Type ▾] [Pick…] │
│ │ │ │ │
│ └──────────────────────────────────────────┘ │ ── Profiling ── │
│ │ [Add profile…] │
│ ──────────────────────────────────────────── │ │
│ Tools: [▲ Point] [○ Circle] [▬ Rect] │ [Delete Hotspot] │
│ [⬠ Polygon] [⊙ SVG Select] │ │
├────────────────────────────────────────────────┴───────────────────┤
│ [Status bar] │
└────────────────────────────────────────────────────────────────────┘

Interaction flow:

• Author opens a graphic object in Object Authoring.
• They click "Edit Hotspots" (or the editor auto-launches if a hotspot configuration exists).
• The canvas renders the graphic at maximum size with a transparent overlay for drawing.
• Tool palette at the bottom (or left) for shape selection.
• Right panel shows properties for the selected hotspot (content, target, profiling).
• Save persists the hotspot configuration; Close returns to Author View.

Alternative B — "Author View Panel" (Inline in Zone C)

Concept: The hotspot editor renders inside Zone C of the Author View — the same zone where Preview and Versions panels live. The graphic fills the panel with an overlay. A collapsible section below the canvas handles hotspot properties.

┌──────┬──────────────┬──────────────────┬───────────────────────────┐
│ S │ ZONE A │ ZONE B │ ZONE C │
│ I │ Folder │ Object List │ ┌───────────────────┐ │
│ D │ Explorer │ │ │ Hotspot Editor │ │
│ E │ │ │ │ │ │
│ B │ │ │ │ [GRAPHIC] │ │
│ A │ │ │ │ ┌──┐ ○ │ │
│ R │ │ │ │ │H1│ ╱╲ │ │
│ │ ├──────────────────┤ │ └──┘ ╱H3╲ │ │
│ │ │ Properties │ │ ╱──╲ │ │
│ │ │ │ ├───────────────────┤ │
│ │ ├──────────────────┤ │ Tools: [▲][○][▬] │ │
│ │ │ Change History │ │ [⬠][⊙ SVG] │ │
│ │ │ │ ├───────────────────┤ │
│ │ │ │ │ ▾ Selected: H1 │ │
│ │ │ │ │ Content: [___] │ │
│ │ │ │ │ Target: [___] │ │
│ │ │ │ │ Profile: [___] │ │
│ │ │ │ └───────────────────┘ │
├──────┴──────────────┴──────────────────┴───────────────────────────┤
│ [Status bar] │
└────────────────────────────────────────────────────────────────────┘

Interaction flow:

• Author selects a graphic in Object List.
• Zone C switches from Preview to "Hotspot Editor" mode (a tab or panel swap within Zone C).
• The graphic renders with overlay + drawing tools inline.
• Hotspot properties appear in a collapsible section below the canvas.
• Author stays in the Author View throughout — can still see folders, object list, and properties.

Alternative C — "Dialog Overlay" (Modal Workspace)

Concept: The hotspot editor opens as a large modal dialog (Radix Dialog, ~90% viewport) overlaying the Author View. This is the same pattern used for the Comparison View in the content comparison spec. The Author View remains behind, dimmed.

┌─────────────────────────────────────────────────────────────────────┐
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ Hotspot Editor: engine-diagram.png [Preview] [↗] [✕] │ │
│ │ Configuration: "Service Manual 2025" │ │
│ ├──────────────────────────────────────────┬────────────────────┤ │
│ │ │ │ │
│ │ [GRAPHIC with overlay] │ HOTSPOT DETAILS │ │
│ │ │ ────────────── │ │
│ │ ┌─────┐ │ │ │
│ │ │ HS1 │ ○ HS2 │ ▾ Content │ │
│ │ └─────┘ ╱╲ │ [Rich text area] │ │
│ │ ╱HS3╲ │ │ │
│ │ ╱────╲ │ ▾ Target │ │
│ │ │ [Type▾] [Pick…] │ │
│ │ ─ Tools: [▲ Pt][○ Circ][▬ Rect] │ │ │
│ │ [⬠ Poly][⊙ SVG] │ ▾ Profiling │ │
│ │ │ [Add profile…] │ │
│ ├──────────────────────────────────────────┤ │ │
│ │ Hotspot List │ │ │
│ │ [H1: Oil filter] [H2: Drain plug] │ [Delete] │ │
│ │ [H3: Gasket] [H4: Torque spec] │ │ │
│ └──────────────────────────────────────────┴────────────────────┘ │
│ │
│ [Author View — dimmed behind] │
└─────────────────────────────────────────────────────────────────────┘

Interaction flow:

• Author selects a graphic, then clicks "Edit Hotspots" in the Action Bar or context menu.
• A large dialog opens over the Author View.
• Left area: graphic canvas with drawing overlay and tool palette.
• Right panel: hotspot details (content, target, profiling) for the selected hotspot.
• Bottom strip: horizontal hotspot list showing all hotspots as chips/tags for quick navigation.
• [Preview] toggles into preview mode within the same dialog.
• [↗] pops out to a separate window. [✕] saves and closes.

Alternative D — "Split Pane in Object Authoring" (Extended Adapter)

Concept: Within the Object Authoring page, the Graphics adapter extends to a horizontal split: the top pane renders the graphic with its overlay, and the bottom pane shows a tabbed area for hotspot list, selected hotspot properties, and preview. The drawing tools float on the canvas.

┌────────────────────────────────────────────────────────────────────┐
│ Object Authoring: engine-diagram.png [Save] [✕] │
│ Config: [Service Manual 2025 ▾] Mode: [Edit | Preview] │
├────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │
│ ┌────────────────────┐ │
│ │ │ ▲ Pt ○ Circ │ [GRAPHIC with overlay] │ │
│ │ ▬ Rect ⬠ Poly │ │
│ │ │ ⊙ SVG ↕ Select │ ┌──┐ ╱╲ │ │
│ └────────────────────┘ │H1│ ╱H3╲ │
│ │ floating tools └──┘ ○H2 ╱──╲ │ │
│ │
│ └─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘ │
│ ═══════════════════ drag to resize ═══════════════════════════ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ [Hotspot List | Properties | Profiling] tabs │ │
│ ├────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ Hotspot List tab: │ │
│ │ # │ Label │ Shape │ Target │ Status │ │
│ │ 1 │ Oil filter │ Rect │ obj:abc123 │ ✓ Complete │ │
│ │ 2 │ Drain plug │ Circle │ — │ ⚠ No target│ │
│ │ 3 │ Gasket area │ Polygon │ search:gasket… │ ✓ Complete │ │
│ │ │ │
│ │ Properties tab (selected hotspot): │ │
│ │ Content: [Rich text editor] │ │
│ │ Target: [Type ▾] [Pick/Enter…] │ │
│ │ │ │
│ │ Profiling tab (selected hotspot): │ │
│ │ [Profile picker — reuse existing platform component] │ │
│ │ │ │
│ └────────────────────────────────────────────────────────────┘ │
├────────────────────────────────────────────────────────────────────┤
│ [Status bar] │
└────────────────────────────────────────────────────────────────────┘

Interaction flow:

• Author opens a graphic in Object Authoring.
• If hotspot configurations exist, a config selector dropdown appears. Otherwise, "Create Hotspot Configuration" is shown.
• Canvas fills the top half with floating drawing tools.
• Bottom half provides a tabbed workspace: Hotspot List (overview), Properties (selected hotspot details), Profiling.
• Click a hotspot on the canvas → selects it → Properties tab auto-switches → canvas pans/zooms to fit.
• Click a row in the Hotspot List → highlights on canvas + shows properties.
• [Edit | Preview] toggle switches the canvas from editable overlay to preview-only mode.

Alternative E — "Inline Zone C + Popout" (Minimal-Change Approach)

Concept: The lightest-touch approach. The hotspot editor is just an enhanced Preview panel in Zone C. Drawing tools appear as an action bar above the preview. Hotspot properties go in the existing Properties panel in Zone B. No new pages, no new panels — only enhanced existing ones.

┌──────┬──────────────┬──────────────────┬───────────────────────────┐
│ S │ ZONE A │ ZONE B │ ZONE C │
│ I │ Folder │ Object List │ ┌───────────────────┐ │
│ D │ Explorer │ │ │ [▲][○][▬][⬠][⊙] │ │
│ E │ │ │ │ [Edit|Preview] │ │
│ B │ │ │ │ ─────────────── │ │
│ A │ │ │ │ │ │
│ R │ │ │ │ [GRAPHIC] │ │
│ │ ├──────────────────┤ │ ┌──┐ ○ │ │
│ │ │ Properties │ │ │H1│ ╱╲ │ │
│ │ │ ── Hotspot ── │ │ └──┘ ╱H3╲ │ │
│ │ │ Content: [___] │ │ │ │
│ │ │ Target: [___] │ │ │ │
│ │ │ Profile: [___] │ │ │ │
│ │ ├──────────────────┤ ├───────────────────┤ │
│ │ │ Hotspot List │ │ Versions │ │
│ │ │ H1, H2, H3… │ │ │ │
│ │ │ │ │ │ │
├──────┴──────────────┴──────────────────┴───────────────────────────┤
│ [Status bar] │
└────────────────────────────────────────────────────────────────────┘

Interaction flow:

• Author selects a graphic in Object List.
• Zone C shows the graphic with a small tool bar at the top (shape tools + edit/preview toggle).
• The existing Properties panel in Zone B gains a "Hotspot" section when a hotspot is selected.
• A new "Hotspot List" panel can be added to Zone B, showing the structured overview.
• Clicking a hotspot on the graphic in Zone C → Properties panel updates → Hotspot List highlights.
• For more space, the author uses the existing popout mechanism to open Zone C in a separate window.

3. Comparative Evaluation

4. Recommended Approach: Alternative D — "Split Pane in Object Authoring"

Why this alternative

• Canvas precision is non-negotiable for this feature. Authors are placing shapes on technical diagrams — engine cutaways, circuit boards, mechanical assemblies. Alternatives B and E fail here because Zone C is too narrow for accurate polygon editing.
• Alternative A (dedicated page) and Alternative D (split pane) both offer full-page canvas. But D is superior because it puts the hotspot editor inside the existing Object Authoring adapter pattern rather than inventing a new page type. The Object Authoring shell already handles save, check-in, check-out, and breadcrumbs — D reuses all of that.
• Alternative C (dialog overlay) is viable but creates an isolated workspace. The modal blocks all interaction with the Author View, and dialog-in-dialog stacking (e.g., opening an object picker from inside the hotspot editor dialog) is awkward.
• Alternative D's tabbed bottom pane naturally accommodates the hotspot list overview (FR-011), per-hotspot property editing (FR-004/005), and profiling (FR-013) without cramming them into a sidebar or a floating panel.
• The configuration selector dropdown at the top handles multi-configuration reuse (FR-015/016/017) cleanly — one graphic, multiple hotspot setups, explicitly named.

Entry to the hotspot editor

The author reaches the hotspot editor via the same path they reach any Object Authoring page:

Author View → double-click graphic object (or click Edit)
 → /ws/:workspaceId/object-authoring?objectId=...
 → Object Authoring Shell detects object type = graphic with hotspot capability
 → Renders the Hotspot Editor adapter (Split Pane)

If the graphic has no hotspot configurations yet, the editor shows the graphic with a clear empty state:

┌────────────────────────────────────────────────────────────────────┐
│ [GRAPHIC displayed at full width] │
│ │
│ No hotspots configured yet │
│ [+ Create Hotspot Configuration] │
│ │
└────────────────────────────────────────────────────────────────────┘

5. Detailed Design

5.1 Object Authoring Shell — Hotspot Adapter

The Object Authoring shell renders the same top bar for all object types. For the hotspot adapter, it adds a configuration selector.

┌────────────────────────────────────────────────────────────────────┐
│ Object Authoring: engine-diagram.png [Save] [✕] │
│ Config: [Service Manual 2025 ▾] [+ New Config] │
│ Mode: [Edit | Preview] │
├────────────────────────────────────────────────────────────────────┤
│ ... │

Configuration selector:

• Dropdown listing all hotspot configurations for this graphic.
• Each config has a user-defined label (e.g., "Service Manual 2025", "Training Material", "Parts Catalog").
• [+ New Config] creates a blank configuration for the same graphic.
• Switching configs reloads the canvas overlay and hotspot list — the graphic itself stays the same.
• The currently active config name is always visible in the header so the author knows which one they're editing (FR-017).

5.2 Canvas Area (Top Pane)

The top pane contains the graphic and the drawing overlay.

Viewport controls:

• Mouse wheel / pinch: zoom in/out
• Click-drag on empty space (with hand tool or middle mouse button): pan
• Ctrl+0 / double-click empty space: fit-to-view (reset zoom)
• Zoom level indicator in the top-right corner of the canvas: [75%]

Drawing tools — floating palette, anchored to the top-left of the canvas:

┌────────────────────────────────────┐
│ ↕ Select ▲ Point ○ Circle │
│ ▬ Rect ⬠ Polygon ⊙ SVG Sel │
└────────────────────────────────────┘

SVG Select tool is only available (enabled) when the graphic is an SVG. For raster graphics, it is greyed out with a tooltip: "Only available for SVG graphics."

Hotspot rendering on canvas:

Overlapping hotspots: When hotspots overlap, the author can cycle through overlapping regions at a click location via Tab key or a small disambiguation popup:

┌──────────────────────┐
│ Multiple hotspots: │
│ ▸ H1: Oil filter │
│ ▸ H3: Gasket area │
└──────────────────────┘

5.3 Bottom Pane (Tabbed Detail Area)

The bottom pane is separated from the canvas by a drag-to-resize handle. Default height: 35% of the available space. Min: 100px (collapsed to tab bar only). Max: 60%.

Three tabs:

#### Tab: Hotspot List

A table showing all hotspots for the current configuration. This is the structured overview (FR-011).

┌────────────────────────────────────────────────────────────────┐
│ # │ Label │ Shape │ Target │ Profile │ Status │
│ 1 │ Oil filter │ Rect │ obj:abc123 │ — │ ✓ Complete │
│ 2 │ Drain plug │ Circle │ — │ — │ ⚠ No target │
│ 3 │ Gasket area │ Polygon │ search:gasket… │ Audience │ ✓ Complete │
│ 4 │ Hydraulic port│ SVG path │ ext:https://… │ — │ ✓ Complete │
│ 5 │ Torque ref │ Point │ drill:config-2 │ Market │ ✓ Complete │
└────────────────────────────────────────────────────────────────┘

• Clicking a row selects that hotspot on the canvas (pans/zooms to fit it in view).
• Status column shows ✓ when content and target are both present, ⚠ with a reason when something is missing (FR-012).
• Profile column shows the profiling dimension name or "—" if no profiling.
• Rows are reorderable via drag (order may affect delivery precedence for overlapping regions).

#### Tab: Properties (Selected Hotspot)

Shows content and target configuration for the currently selected hotspot. If no hotspot is selected, shows an empty state: "Select a hotspot on the graphic or from the list."

┌────────────────────────────────────────────────────────────────┐
│ Hotspot: H3 — "Gasket area" │
│ ───────────────────────────── │
│ │
│ Label: [Gasket area________________] │
│ │
│ Content: │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ [Rich text editor — paragraph-level, no full DITA] │ │
│ │ The gasket must be replaced every 10,000 km… │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ Target: │
│ Type: [Platform Object ▾] │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 🔍 [Search objects…________________________] │ │
│ │ Selected: gasket-replacement-procedure.dita [✕ clear] │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ — OR no target (informational only): [☐ No navigation] │
│ │
│ [Delete Hotspot] │
└────────────────────────────────────────────────────────────────┘

Target type selector:

When target type is "Drill-down", the picker shows available hotspot configurations:

┌────────────────────────────────────────────┐
│ Select drill-down target: │
│ ───────────────────── │
│ Same graphic: │
│ ▸ Parts Catalog (this graphic) │
│ Other graphics: │
│ ▸ engine-cutaway.svg → Assembly View │
│ ▸ hydraulic-system.png → Service View │
│ ───────────────────── │
│ [Cancel] [Select] │
└────────────────────────────────────────────┘

#### Tab: Profiling (Selected Hotspot)

Shows and edits the applicability rules for the currently selected hotspot. Reuses the platform's existing profile picker component.

┌────────────────────────────────────────────────────────────────┐
│ Profiling for: H3 — "Gasket area" │
│ ───────────────────────────── │
│ │
│ This hotspot is visible when: │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Audience: [Technician ▾] │ │
│ │ Market: [All ▾] │ │
│ │ Product: [All ▾] │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ [Remove all profiling] (makes hotspot always visible) │
│ │
└────────────────────────────────────────────────────────────────┘

When no profiling is applied: "This hotspot is always visible. [+ Add profiling]"

5.4 Preview Mode

Toggled via [Edit | Preview] in the header. In Preview mode:

• Drawing tools are hidden.
• Hotspot borders, labels, and status indicators are hidden.
• The graphic looks clean — as an end user would see it.
• Hovering over a hotspot area shows a subtle highlight (cursor changes to pointer).
• Clicking a hotspot shows a popup with its content:

┌───────────────────────────────────┐
│ Gasket area │
│ ───────────── │
│ The gasket must be replaced │
│ every 10,000 km or when… │
│ │
│ [→ Go to: gasket-replacement…] │ ← shown only if target is configured
└───────────────────────────────────┘

• If the hotspot has a drill-down target, the popup shows: [↓ Drill down: Assembly View] — clicking it does not navigate (authoring preview) but shows a toast: "Would navigate to: Assembly View."
• Bottom pane stays visible in preview mode but is read-only.
• Escape or clicking [Edit] returns to edit mode.

5.5 SVG Shape Selection Mode

When the graphic is an SVG and the SVG Select tool (⊙) is active:

• All existing SVG shapes become individually hoverable. On hover, the shape gets a highlight border.
• Clicking a shape selects it. A small popover appears near the shape:

┌────────────────────────────┐
│ SVG shape selected: │
│ Type: <path> │
│ ID: "oil-filter-shape" │
│ │
│ [Make Hotspot] [Cancel] │
└────────────────────────────┘

• "Make Hotspot" converts the SVG shape into a hotspot. The shape's existing coordinates and geometry are used — the author does not redraw anything.
• Nested/grouped SVG elements: when a click lands on a group (<g>), the editor shows a disambiguation list of the group and its children, letting the author pick the intended element.

5.6 Keyboard Shortcuts

6. Priority Mapping

7. Open Design Questions