Shared editor components

Studio tools in the Glyphfield codebase are built from shared components and hooks for the tool shell, color fields, zoom, layer editing, select menus, source editing and draft storage. A contributor who builds a tool from them gets the same interaction, accessibility, automation and export behavior as the other tools.

Component map

Color control

ColorControl is one component with optional features. By default it is compact: a row with the swatch, the label, the HEX value and the opacity opens a picker popover. compact={false} shows the swatch, HEX and OKLCH fields inline for dedicated color-editing surfaces.

The conversion functions (normalizeHex, formatOklch, parseOklch, oklchToHex, hexToHsv and hsvToHex) live in src/lib/color.ts.

The eyedropper (src/components/ui/ScreenColorPicker.tsx) uses the browser's EyeDropper API, which needs a supporting browser on HTTPS or localhost. Without it, the button is disabled with an explanation, and the other color controls keep working. Closing the picker or unmounting it cancels an unfinished sample. Browser API control discovery lists the button as <color label> pick screen color. Screen sampling needs a real user gesture and a native screen selection, so agents set colors through the HEX or OKLCH fields and re-read the source to confirm the change.

Canvas viewport

CanvasViewport wraps the artifact without changing its aspect ratio. The stage scales on screen, and exports keep the artifact's declared pixel size.

• Zoom runs from 40% to 200% by default. Hosts can change the range: Design Lab uses 5% to 800%.
• The percentage button restores 100%. Reset view restores 100% and the starting pan. Fit canvas (F) fits the content at no more than 100%. Zoom in (+) and Zoom out (−) step by 10%.
• The mouse wheel or trackpad zooms around the pointer. Dragging on empty workspace, middle-button dragging or Space + drag pans the view.
• Zoom is stored with useStudioDraft for each project and tool. Pan resets when the tool remounts.
• When the host passes actionHistory, the toolbar shows Undo, Redo and Action history, and ⌘/Ctrl + Z and Shift + ⌘/Ctrl + Z work while the pointer is over the canvas or the canvas has focus.

These gestures change only the view transform. The document and its export geometry stay the same.

Source drawer

SourceCodeDrawer keeps source editing next to the canvas. The host controls it through four props:

• source is the current serialized document of the tool.
• onApply parses and validates the edited text, then updates the host state. An error it throws appears in the drawer and leaves the visual document unchanged.
• format and title label the drawer.
• onClose closes it. The tool and the canvas position stay as they were.

The drawer is a shared editing shell, and each tool owns its schema. Each tool checks its own fields and converts valid source into the same state that its visual controls use. Lottie and Animation use CanvasDocument envelopes with their own metadata, the expression tools use expression documents, and the foundation and component tools use their own versioned objects.

See Source code editing, the Source format reference and the Studio Browser API.

Direct manipulation

EditableCanvasLayer draws one movable object on the artboard. The host gives it a base box and a CanvasLayerTransform (offset, scale, optional width and height scale, and rotation) and receives the new transform in onChange.

The host owns the selection. The expression tools start with nothing selected and select a layer when it is added. Design Lab passes onRotate, rotation and canvasThirdsSnapTargets (rule-of-thirds lines on artboards). The expression tools rotate layers through the inspector and use the default snap lines.

CanvasDocument model

src/lib/canvasDocument.ts defines the portable document model that people and agents share. It is separate from React component state and records:

• The schema version, brand binding, capabilities, revision and metadata.
• Pages with dimensions, safe area, bleed, background, notes and ordered element IDs.
• Elements of the kinds text, image, logo, shape, line, frame, group, gradient, texture, shader, effect, video and component.
• Bounds, rotation, anchors, locks for position, dimensions, aspect ratio and rotation, visibility, blend mode, border, radius, opacity and shadow.
• Font bindings, text roles and text style.
• Non-destructive image crop, focal point, fit, saturation, dither, grain, blur, posterization and halation.
• Asset and font records that elements reference by ID.

applyCanvasMutation supports these mutations: move several elements, resize, lock, delete, reorder, update and replace an asset. Replacing an asset changes only the source reference and keeps geometry, crop, image treatment, effects and constraints.

The module also exports history and checking helpers. commitCanvasChange takes one mutation or a batch, and a batch is one undo step. undoCanvasChange and redoCanvasChange restore cloned documents. saveCanvasVersion records an author, time, name, note and revision, and restoreCanvasVersion returns a clone. preflightCanvasDocument reports missing assets, missing fonts, assets and fonts that are not embedded, elements that extend beyond their page and text over its line limit. Tests cover these helpers, and no Studio tool calls them yet. Each editor keeps its own undo stack (the expression tools use useExpressionDocument, with 120 steps), and saved checkpoints live in src/lib/savedDesigns.ts.

Logo appearance

LogoAppearanceControls and src/lib/logoAppearance.ts keep logo treatment the same across tools. The CSS preview filter, the SVG export filter and the canvas renderer all read the same settings.

• Invert reverses the colors of the resolved mark or image. No second file is needed.
• Dither applies an ordered print pattern with an amount (0–100%), a cell size (2–18 px) and a direction (0–360°). The source file stays unchanged.
• Outline follows the alpha of the SVG or transparent image, with its own color, opacity and width.
• Shadow has a color, opacity, blur and horizontal and vertical offsets.
• The outline and shadow colors use ColorControl with opacity.

The settings are stored with the layer or element that uses them. In Brand elements, one setting applies to every logo in the selected element.

Third-party libraries

Studio tools use third-party packages through local components, so a tool does not depend on each library's API.

Build a new tool

1. Wrap the tool in ToolShell, or compose StudioToolHeader, StudioFileMenu and LazySourceCodeDrawer yourself.
2. Store tool fields with useStudioDraft(identity.id, tool.id, field, initialValue).
3. Use ColorControl for every editable color and opacity.
4. Wrap the artifact in CanvasViewport and keep its declared aspect ratio.
5. Represent every movable object with a CanvasLayerTransform and render it with EditableCanvasLayer.
6. Use StudioSelect, Button and the fields in src/components/tools/ToolFields.tsx (ControlSection, Field, RangeField, UploadField and SegmentedChoice) instead of one-off controls.
7. Build exports from the same resolved settings that drive the preview.
8. Serialize the editable state for the source drawer and validate edits with the sourceCode.ts readers, so source edits go through the same validators and state setters as the visual controls. A tool that stores a CanvasDocument can use usePortableCanvasWorkspace for serialization and autosave.
9. Register Browser API actions through the automation prop of ToolShell, add their contracts to STUDIO_TOOL_ACTION_CONTRACTS in src/lib/studioAgentCapabilities.ts, and document every action name. src/lib/__tests__/documentationCoverage.test.ts fails when an action is missing from the docs.

A tool built this way looks and behaves like the rest of the Studio, and its renderer can still be SVG, Canvas, HTML or WebGL.