examples: add a direct-manipulation visual editor built with Foldkit #1556

Summary

Add a production-quality direct-manipulation visual editor example built with Foldkit. Use a focused social-card or OpenGraph editor so the example has real interaction requirements without becoming a general design application.

Foldkit has examples for declarative Canvas drawing, animation, and pixel editing, but no canonical example in which users select objects on a composed visual surface, move them directly, and edit text in place. Without that reference, generated apps tend to move every property into a separate inspector control.

Goals

Prove and document the Foldkit architecture for direct manipulation:

• the Model is the single source of truth for document content and selection
• pointer and keyboard events become Messages
• dragging and editing update the document through update
• side effects such as loading or exporting assets remain Commands
• direct manipulation and secondary inspector controls stay synchronized because both derive from the same Model

The example should become the canonical reference for agents building card editors, diagram editors, image annotation tools, canvas workspaces, and similar interfaces.

Example scope

Build a 1200 by 630 social-card editor with a compact but meaningful document model:

• text and graphic or image-backed layers with stable ids
• a selected-layer union or Option in the Model
• click or pointer selection on the artboard
• drag to reposition a selected layer
• visible selection bounds or handles
• inline text editing on or immediately over the selected text layer
• a contextual toolbar or Popover for common typography and appearance changes
• a secondary inspector for precise values, without making it the primary editing workflow
• keyboard nudging, deletion, Escape, and predictable focus behavior
• layer ordering if it fits without overwhelming the example

Undo and redo are desirable if they remain a clear domain operation rather than dominating the example. Export is optional; if included, it must be modeled as a Command with success and failure Messages.

Architecture

Use an application-owned editor Submodel that owns the workspace interaction. Its internal view can compose DOM layers, Canvas, contenteditable hosts, Popover, Input, Slider, and other primitives as appropriate.

Do not split each editor control into an unrelated top-level surface. Code can be decomposed into view helpers and child Submodels while the rendered experience remains one editor.

Prefer proving the interaction with existing primitives before adding framework APIs. In particular:

• Try DOM-positioned editable layers when they provide better native text editing than Canvas text.
• Use Canvas where deterministic drawing or export genuinely benefits from it.
• Record any unavoidable pointer-capture, hit-testing, bitmap, text-measurement, or focus limitation as concrete evidence for a focused follow-up issue.

Do not add speculative Canvas.Image, generic hit-testing, or a package-level Editor component as part of this issue unless the example demonstrates that the feature cannot be built correctly without it.

Verification

• Story tests cover selection, dragging state transitions, inline text updates, keyboard operations, and any undo/redo behavior.
• Scene tests cover accessible selection controls, inline contenteditable editing, contextual controls, and visible Model-driven updates.
• Browser verification covers real pointer dragging, focus handoff, selection persistence, editing, and viewport behavior.
• The example has an accessibility pass covering keyboard alternatives to drag, visible focus, control names, and text-editing semantics.

Scene does not need to synthesize an entire real drag if its current pointer vocabulary cannot express one. Put state-transition coverage in Story and keep real pointer behavior in browser verification rather than weakening the interaction to fit the test harness.

Documentation and agent guidance

• Register the app in the example gallery with a description centered on direct manipulation.
• Add a short architecture explanation linking Model, selection state, pointer Messages, inline editing, and contextual controls.
• Link it from Canvas and relevant UI pages.
• Once it lands, make it the canonical direct-manipulation reference for skills: preserve compound interactions instead of flattening them into isolated controls #1555.

Scope boundary

This is an exemplar, not a proposal for a generic OpenGraphEditor or VisualEditor component. The reusable framework result is the proven architecture and any narrowly evidenced primitive gaps discovered while building it.

Acceptance criteria

• Users can select, move, and edit content directly on the artboard.
• Inspector controls are synchronized but secondary to direct manipulation.
• The editor is one cohesive feature-level surface even when its code uses several helpers or Submodels.
• Story, Scene, browser, and accessibility verification cover the interaction at the appropriate layer.
• Any required framework follow-up is filed from a concrete limitation reproduced by the example.
• generate-program can cite the example for direct-manipulation requests.

AI-generated by Sol (Codex), posted at the user's request.