Make authoring activation and element targeting contextual and unambiguous #43

Parent epic: #40

Outcome

Every authoring control says what it will do in the current context. Once an editable interface exists, a person can point at what they see, understand the selected semantic target, make a small reversible visual change through a compact contextual overlay, and continue in the same conversation. A person is never asked to select an element before an editable interface exists, nor offered an “open” or “start” action that cannot meaningfully activate Flect.

Product-quality coverage

FQ-02.2–FQ-02.4, FQ-03.2, FQ-03.5, FQ-03.7, FQ-04.1, FQ-04.3–FQ-04.8, FQ-05.1, FQ-06.1–FQ-06.4, FQ-13.1, FQ-13.5, FQ-15.2–FQ-15.3, FQ-18.1–FQ-18.9, and FQ-19.2–FQ-19.6.

Dependencies

• Make the running interface the live editing canvas #32 is the live-canvas contract.
• Host each Flect app in a persistent incremental frontend workspace #33 owns persistent incremental source and build state.
• Add element selection and direct manipulation for targeted UI edits #35 is the existing semantic selection and direct-manipulation contract.
• Adopt an Astro activation shell with an on-demand Flect runtime #37 is the explicit activation boundary for an opened interface.
• Complete accessibility, reflow, and adaptive appearance gates #22 owns the accessible equivalent of selection and manipulation.
• Prevent protected-shell visibility regressions across all interaction states #44 owns protected-shell visibility regression gates.

Delivery order

1. Source-aware contextual selection

• Replace the ambiguous standalone selection control with an affordance that appears only when a valid editable canvas exists.
• Provide pointer hover framing, click selection, Escape/back-out behavior, and a complete keyboard equivalent.
• Resolve a visible target to a bounded CanvasSelection containing stable semantic identity, accessible label, source location when available, component ancestry, geometry, responsive viewport, and only the computed styles required by the requested operation.
• Support Flect interface documents directly and imported same-origin framework canvases through bounded adapters. Treat framework internals and DOM selectors as fallible evidence, not identity or authority.
• Exclude protected shell controls, host chrome, credentials, cross-origin content, invisible page-covering overlays, and unrelated document data.
• Detect rerender, navigation, revision replacement, and disconnected targets; clear or re-resolve selection without silently targeting a different element.

2. Compact contextual editing overlay

• Show a small protected palette near the selected element without moving canvas layout or permanently occupying a side rail.
• Begin with text, ordering, size, spacing, and alignment. Offer the continuous composer for complex or ambiguous changes.
• Show the selected element label and dimensions; make scope and target correction understandable before applying.
• Position selection chrome and controls within the viewport without covering the target where another placement is available.
• Keep normal product interaction active outside explicit selection/edit interaction. Preserve navigation, scrolling, text selection, clipboard, canvas focus, and the separate conversation/settings overlays.
• Provide complete hover, active, disabled, busy, success, error, light/dark, forced-colors, reduced-motion, zoom, reflow, and touch-target states.

3. Typed reversible edit intent and live application

• Define Effect Schema boundaries for target identity, operation, scope, viewport, before/after values, gesture identity, and validation result. Do not make a generated prose prompt the application contract.
• Route preview, source application, validation, activation, checkpointing, recovery, and cancellation through named Effect services and the shared FlectWorkspaceController.
• Apply transient live preview through an isolated removable layer. Do not treat inline DOM mutation or preview CSS as source of truth.
• Coalesce every slider, drag, or paired-property gesture into one attributable edit and one Undo step.
• Translate a valid edit into maintainable responsive source using existing tokens and styling conventions where they can be resolved safely.
• Automatically activate and checkpoint valid local UI edits. On ambiguity, stale context, unsupported source, build failure, or validation failure, retain the last-known-good canvas and provide a bounded recovery path.

4. Public proof

• Contract tests cover schema decoding, controller routing, target loss, stale results, preview cleanup, gesture coalescing, validation, automatic checkpoint, Undo, and deterministic failure recovery.
• Production Chromium covers pointer and keyboard selection across nested content, scroll, zoom, iframe boundaries supported by Flect, rerenders, large/animated DOMs, repeated edits, source-resolution failure, light/dark, forced colors, reduced motion, and compact reflow.
• Packaged macOS public UI and AXI cover activation, native focus, overlay placement, window movement/resizing, selected-target continuity, Undo, restart, and model-free recovery.
• Performance evidence records activation, hover, target resolution, live gesture responsiveness, idle overhead, and repeated-edit memory behavior against the existing budgets.
• Manual assistive-technology and comprehension evidence confirms that people understand activation, selected target, local automatic edit, Undo, and the distinction from authority-changing actions.

State-driven activation behavior

• Blank workspace: one direct first-request action; no selection control.
• View-only interface: one activation affordance only when the host can activate Flect.
• Activating: bounded progress; no duplicate actions.
• Active canvas: contextual conversation and a quiet editing affordance.
• Selecting: hover/keyboard target indication and a clear Escape path; normal application actions are not triggered by selection clicks.
• Selected target: visible semantic label, correctable scope, compact edit actions, and composer context before send.
• Previewing a gesture: immediate reversible visual feedback and one coherent pending change.
• Applying: target and foreground canvas remain legible; duplicate edits are prevented.
• Failure or stale target: last-known-good canvas remains; preview is removed; safe retry, retarget, or conversational repair is available.
• Authority decision: existing explicit protected decision path; never disguised as a visual edit.

Acceptance criteria

• A state matrix demonstrates one unambiguous primary action in every state above.
• No element-selection or editing control is visible or actionable without a valid live target surface; no activation control claims to open a surface that is already open or unavailable.
• A user can select an element, verify or correct the target, edit its text or basic layout, see immediate preview, apply one validated automatic checkpoint, Undo it once, and then make a global conversational change without selecting an agent role or entering a mode-oriented workflow.
• A single gesture never produces multiple user-visible history entries; failed and cancelled gestures leave neither canonical source changes nor hidden preview mutations.
• Source-aware targeting survives supported rerenders and list instances, and fails closed instead of applying to a heuristic CSS match when identity is ambiguous.
• The user can distinguish an automatic local edit from an authority or outside-effect decision before execution.
• Keyboard and assistive-technology flows can perform every targeting and correction action and return focus to the running interface.
• Production Chromium and packaged macOS flows prove activation, selection, target loss after update, direct edit, Undo, cancellation, reload, recovery, zoom/reflow, light/dark, reduced motion, and performance behavior.

Research and reuse boundary

• Evaluate focused, compatible-licensed primitives for deep hit testing, iframe/shadow-root geometry, source-map/component context, selection chrome, overlay event isolation, and grouped history before writing equivalents.
• Apache-2.0, MIT, and BSD code may be adopted only after recording attribution, package health, bundle/runtime impact, security surface, framework coupling, and compatibility with Flect’s Effect/controller boundaries.
• AGPL and noncompete/source-available implementations are reference material only unless a separate legal and architectural decision explicitly changes that boundary.
• Do not import a full visual-builder state model, agent runtime, credential flow, editor shell, or cloud dependency merely to obtain selection or overlay behavior.

Constraints

• All decisions, selection requests, and edits enter through schema-defined Effect capabilities and the FlectWorkspaceController; no DOM-selector outside adapter, React component, iframe bridge, or client-storage state becomes an authority.
• React may render ephemeral overlay state, but source mapping, edit intent, validation, preview lifecycle, checkpointing, and recovery remain owned by Effect services and Layers.
• Do not reveal internal App/Shaper/Guardian identities, candidate state, branches, or review ceremony.
• Selection and captured page content are bounded untrusted input and must not expose protected shell controls, credentials, capability handles, or unrelated document data to a model or user-created interface.
• The overlay remains protected and recoverable while visually deferring to the user’s interface.

Non-goals

• A permanent inspector, Figma-like mode, unrestricted CSS IDE, or project-management sidebar.
• Multi-selection, freeform drawing, a complete breakpoint editor, arbitrary component creation, or design-token management in the first slice.
• Adding authority to user-created interfaces.
• Replacing normal application clicks with edit targeting by default.

Owning documentation

DESIGN.md, docs/superpowers/specs/2026-07-31-flect-embedded-axi-design.md, docs/local-control.md, and docs/product-quality.md; record behavior evidence under docs/verification/.

Bounded preview tools

• Keep the editable interface in an embedded canvas that can be inspected without replacing the protected shell or becoming a second browser authority.
• Provide explicit system, light, and dark appearance previews plus supported viewport presets without mutating canonical source until the user applies an edit.
• Let a user capture the current canvas or selected semantic target as a bounded screenshot for comparison, evidence, or conversation context; clearly show its scope before capture.
• Treat captured pixels and page content as untrusted, ephemeral input. Exclude protected chrome, credentials, capability handles, and unrelated windows; never attach a capture to a model turn implicitly.
• Cover appearance switching, viewport changes, selection continuity, capture scope, cancellation, focus return, and cleanup in production-browser and packaged-host tests.