Artstr-Studio/docs/VECTOR_SHAPES_FEATURE.md

Vector Shapes, Fills, and Masking

Goals

Expand the layer system from "image / text / color rectangle" into a real vector design surface: shape primitives, custom paths, solid + gradient fills, strokes, and clip/mask composition. All purely client-side, all JSON-serializable, all backwards-compatible with existing templates and the existing print/PDF/JPEG export.

Product goals

1. Open the door to creative work that requires more than photos + text — accents, frames, geometric overlays, stylized backgrounds, branded shapes.
2. Make masking (circle crops, star-shaped photos, gradient-faded artwork) possible inside the editor without external tools.
3. Stay print-safe: vectors render crisply at any output resolution.
4. Round-trip through the existing project JSON and Nostr publish flow with no migration step.

Non-goals (v1)

• A pen tool / interactive bezier editing surface. Users paste an SVG d= string for custom paths.
• SVG import as a whole (parsing <svg> files, handling nested groups). Single <path d=…> only.
• Conic gradients, mesh gradients, patterns, image-fill of shapes.
• Outside / inside stroke positions (center stroke only — outside-positioned strokes require path inflation).
• Stroke dash editing UI. v1 picks from a small preset list.
• Mask groups (multiple shapes union'd as a single mask). v1 supports a single shape clip per layer or a single layer-as-mask reference.
• Animated gradients or shapes.

---

Current state

Layers today are objects in state.layers[]:

{ id, type, name, target, x, y, w, h, rotate, opacity, z, locked, …type-specific }

with three concrete types:

• image → src, fit?
• text → html, fontSize, color, align, bold, italic, fontFamily
• color → color (flat rectangle fill, currently the closest we have to a shape primitive)

Renderers branch on type in roughly five places:

1. renderLayers (main editor canvas)
2. renderTemplatePreviewDOM (cover preview)
3. renderDiscSheetPreviewDOM (disc-sheet preview)
4. renderJewelPreviewDOM (jewel preview)
5. renderDiscPreviewDOM (disc-design preview)
6. renderCustomArtPreviewDOM (custom art preview)
7. Canvas rendering for PDF/JPEG export

Each renderer has the same shape:

if (layer.type === 'text') { … }
else if (layer.type === 'image' && layer.src) { … }
else if (layer.type === 'color') { … }

Coordinates are in inches for x, y, w, h.

---

Data model

New layer type: shape

A single mega-type covers every primitive plus custom paths, with a discriminated shape.kind field. This keeps the number of renderer branches at one (not seven, one per primitive).

{
  id: 'layer-…',
  type: 'shape',
  name: 'Star burst',
  target: 'cover-trim' | 'back' | 'spine' | 'front' | 'disc-top' | 'disc-bottom' | 'jewel-front' | 'jewel-tray' | 'designer-disc' | 'canvas',
  x, y, w, h, rotate, opacity, z, locked,
  shape: {
    kind: 'rect' | 'rounded-rect' | 'ellipse' | 'circle' | 'polygon' | 'star' | 'line' | 'path',
    // kind-specific (all optional except where noted):
    cornerRadius?: number,        // rounded-rect (in shape-local units, 0..min(w,h)/2)
    sides?: number,               // polygon (default 6)
    points?: number,              // star (default 5)
    innerRadiusRatio?: number,    // star (0..1, default 0.45)
    d?: string,                   // path — SVG path data normalized to a 0..1 viewbox
    x1?, y1?, x2?, y2?: number    // line endpoints (0..1 in shape-local)
  },
  fill: {
    type: 'none' | 'solid' | 'linear-gradient' | 'radial-gradient',
    color?: '#hex',               // solid
    stops?: [{ at: 0..1, color: '#hex' }, …],  // gradients, at least 2 stops
    angle?: number,               // linear gradient, degrees
    center?: { x: 0..1, y: 0..1 },// radial gradient center (in shape-local coords)
    radius?: number               // radial gradient radius (0..1)
  },
  stroke: {
    type: 'none' | 'solid',
    color?: '#hex',
    width?: number,               // inches
    dash?: 'solid' | 'dashed' | 'dotted' | string  // string = SVG dash array
  },
  clip?: {
    kind: 'inline-shape',
    shape: { /* full shape sub-object, same structure as `shape` above */ }
  } | {
    kind: 'layer-ref',
    layerId: 'layer-…'
  }
}

The clip field is optional and can be applied to any layer type, not just shapes. So an image layer can have clip: { kind: 'inline-shape', shape: { kind: 'circle' } } to mask a photo into a circle without needing a separate shape layer.

Why one mega-type instead of one per primitive

• Keeps renderer code to a single case 'shape': branch in every renderer.
• Selected-layer controls dispatch on shape.kind for kind-specific params (corner radius, sides, etc.) but share the fill / stroke / clip panels.
• Easier to add a new kind later (e.g. arrow, speech-bubble) without touching every renderer.

Why a discriminated clip object

• kind: 'inline-shape' covers 90% of users — "crop my photo to a circle / star / heart."
• kind: 'layer-ref' covers the power case — "let me use that hand-drawn vector shape as a mask for this image."
• A future kind: 'union' could combine multiple mask shapes; not v1.

Backwards / forwards compat

• Existing color layers are untouched. A flat-color rectangle is now possible two ways: legacy type: 'color' (kept forever) and new type: 'shape', shape: { kind: 'rect' }, fill: { type: 'solid' }. The renderer handles both.
• Old clients seeing type: 'shape' skip the layer — the rest of the design still renders. Same fail-soft behavior as today's old clients ignoring type: 'color'.
• Future shape.kind values we haven't shipped yet are also skipped individually by clients that don't recognize them.
• clip on existing layer types is purely additive. Clients that don't know about it render the layer un-clipped, which is uglier but not broken.

JSON example (one shape layer with a gradient and a clip)

{
  "id": "layer-1742000000-001",
  "type": "shape",
  "name": "Accent burst",
  "target": "cover-trim",
  "x": 1.5, "y": 0.5, "w": 1.0, "h": 1.0,
  "rotate": 0, "opacity": 0.85, "z": 7,
  "shape": {
    "kind": "star",
    "points": 8,
    "innerRadiusRatio": 0.4
  },
  "fill": {
    "type": "linear-gradient",
    "angle": 135,
    "stops": [
      { "at": 0, "color": "#fbbf24" },
      { "at": 1, "color": "#dc2626" }
    ]
  },
  "stroke": {
    "type": "solid",
    "color": "#7f1d1d",
    "width": 0.01,
    "dash": "solid"
  }
}

That's it. No new top-level fields on the project JSON, no migration step, no external assets.

---

Rendering

DOM (editor + 6 preview surfaces)

Today each layer renders as a <div> positioned absolutely with transform: translate() rotate(). For shape layers, we keep the <div> wrapper (so the position / rotation / opacity / drag-handle code is unchanged), and inject an inline <svg> filling 100% of the wrapper.

The SVG sets viewBox="0 0 100 100" (a normalized coordinate space) so all shape math works in 0–100 units regardless of the actual layer w/h in inches. Stroke width converts: (stroke.width / max(w_inches, h_inches)) * 100.

function renderShape(svgEl, layer) {
  const { shape, fill, stroke } = layer;
  const defs = [];

  if (fill.type === 'linear-gradient' || fill.type === 'radial-gradient') {
    defs.push(buildGradientDef(layer.id, fill));
  }

  const path = buildShapePath(shape);   // returns SVG <path> / <circle> / etc.
  applyFill(path, fill, layer.id);
  applyStroke(path, stroke, layer);

  svgEl.innerHTML = `<defs>${defs.join('')}</defs>${path}`;
}

buildShapePath is a switch on shape.kind:

• rect: <rect width="100" height="100"/> (with rx for rounded-rect)
• circle / ellipse: <ellipse cx="50" cy="50" rx="50" ry="50"/>
• polygon: compute <polygon points="…"> from sides
• star: compute <polygon points="…"> from points + innerRadiusRatio
• line: <line x1=… y1=… x2=… y2=… />
• path: <path d="<sanitized d>" />

Inline gradients are referenced via fill="url(#grad-<layerId>)". The gradient id is namespaced by layer id so multiple shape layers don't collide.

Canvas (PDF / JPEG export)

Canvas2D natively supports everything we need:

• ctx.beginPath() / ellipse() / rect() / moveTo() / lineTo() / fill() / stroke()
• ctx.createLinearGradient(x0,y0,x1,y1) / addColorStop(...)
• ctx.createRadialGradient(...) for radial
• ctx.setLineDash([...]) for dash patterns
• ctx.clip() for masks (called after a fill or shape path is built but before the next layer draws — needs save/restore discipline)

The canvas renderer parallels the SVG renderer 1:1. Each shape kind has a "build the path on the context" function that the SVG renderer would translate to attributes.

Print/PDF fidelity

• SVG renders crisply in window.print() PDF in all modern browsers. We've already verified this with the existing text layer rendering.
• clip-path: path(…) is well-supported in Chromium (Chrome, Edge, Brave) and Safari ≥ 16. Older Firefox versions had known bugs.
• Fallback: when print fidelity matters most (the JPEG export path), we route through canvas, where ctx.clip() is rock-solid.

---

UX

Adding shapes

Next to the existing "Add image / Add text / Add color block" buttons in each layer panel:

[ + Image ]  [ + Text ]  [ + Color ]  [ + Shape ▾ ]
                                        │
                                        ├─ Rectangle
                                        ├─ Rounded rect
                                        ├─ Circle
                                        ├─ Ellipse
                                        ├─ Triangle
                                        ├─ Polygon
                                        ├─ Star
                                        ├─ Line
                                        └─ Custom path (SVG)…

Clicking a primitive inserts a centered shape at 50% of the target bounds with a sensible default fill (the existing accent blue at 100% opacity).

"Custom path (SVG)" opens a small modal:

• Textarea for the d= data
• Live preview as the user pastes
• Validate: parse d and reject anything containing <, >, or script (defensive; we never innerHTML the raw data, only set it as a d attribute)
• "Add to canvas" inserts it as a path-kind shape layer

Selected-layer controls

When a shape layer is selected, the existing "Selected layer" panel grows three sub-panels (in addition to the existing position/rotation/opacity controls):

1. Shape — kind-specific params:

   • rounded-rect: corner radius slider
   • polygon: sides number (3..12)
   • star: points number (3..12) + inner-radius slider
   • line: stroke-width is the visible attribute; the path is built from endpoints
   • path: a small "Edit path data…" button that reopens the SVG textarea modal

2. Fill — fill-type select (none / solid / linear / radial), with conditional sub-controls:

   • solid → one <input type="color">
   • linear → start color, end color, angle slider (0–360°)
   • radial → start color, end color, center XY (two sliders), radius slider
   • v1 limits gradients to two stops for UI simplicity; the JSON model supports N stops so a future picker can extend without a migration.

3. Stroke — stroke-type select (none / solid), with color, width (in inches with .001 step), dash style (solid / dashed / dotted).

The same Fill/Stroke pattern can be added to existing color layers later as a quality-of-life pass, since the JSON already supports it.

Clip / mask controls (any layer type)

A new "Clip to shape" toggle in the selected-layer controls applies to any layer:

• Off → render normally (default)
• On → small sub-panel:
  • "Inline shape" tab: pick a primitive, set its kind-specific params. Renders the chosen shape as a clip-path over the current layer.
  • "Another layer" tab: dropdown of other layers in the same target. The chosen layer's shape becomes the mask. Greyed-out if no other shape layer exists in the target.

Discoverability

A small one-line hint under the layer list when no shape layer exists:

"Tip: Shape layers let you make circular avatars, banner gradients, and custom vector accents."

---

Engineering plan

Pre-work (small refactor)

Each of the 6+ renderers branches on type. Adding a 7th branch for shape in each one is mechanical but expensive to maintain forever. Worth extracting a single renderLayerVisualInto(el, layer, opts) helper that all surface renderers call. The helper handles type-dispatch once; surface renderers handle bounds and positioning. Estimate ~1 day, no behavior change.

Phase A — Shape primitives + solid fill

1. Add type: 'shape' to the layer schema.
2. addShapeLayer(kind, targetOverride) helper, mirroring addColorLayer.
3. "Add Shape" button + sub-menu in each layer panel.
4. Selected-layer controls: Shape sub-panel (kind-specific) + Fill (solid only) sub-panel.
5. SVG renderer that handles all 8 kinds with solid fill.
6. Canvas renderer that parallels the SVG one.
7. JSON round-trip — verify save/load and Nostr publish/import preserve everything.
8. The 6 preview surfaces all pick up shape rendering for free via the new renderLayerVisualInto.

Ship gate: a star with solid red fill drops onto a cover, gets resized + rotated, saves, reloads, exports to PDF, and ends up looking the same in all four places (editor / browser preview / saved JSON / PDF).

Phase B — Gradients

1. Extend the Fill sub-panel with linear / radial pickers (start color, end color, angle / center / radius).
2. buildGradientDef for SVG, equivalent path on canvas.
3. v1: 2-stop only. JSON model already supports N stops for the future.

Ship gate: a linear-gradient circle exports to PDF without banding or color shift.

Phase C — Strokes

1. Extend the Stroke sub-panel: color, width (inches), dash preset.
2. SVG renderer applies stroke, stroke-width, stroke-dasharray.
3. Canvas renderer applies strokeStyle + lineWidth + setLineDash.

Ship gate: a 0.05-inch dashed black stroke around a rounded rectangle renders identically in editor and PDF.

Phase D — Custom SVG path

1. "Custom path (SVG)" modal with paste + validate.
2. Sanitization (only parse d; reject anything that looks like markup).
3. Render via SVG <path d> and Canvas2D Path2D(d).
4. Optional: a small library of "shape presets" (heart, arrow, speech bubble, etc.) bundled as path data.

Ship gate: pasting a known SVG icon's d attribute produces a clean layer that exports correctly.

Phase E — Masking

1. Add clip field to the universal layer schema (any layer type).
2. "Clip to shape" toggle + inline-shape picker in the controls panel.
3. SVG renderer: emit <clipPath id="clip-<layerId>"><path d="…"/></clipPath> in defs, set clip-path: url(#clip-<layerId>) via CSS on the wrapper.
4. Canvas renderer: ctx.save() → buildShapePath → ctx.clip() → draw layer → ctx.restore().
5. "Layer reference" tab: resolves another layer's shape at render time. Reject reference cycles (defensive).

Ship gate: a photo of a person clipped to a circle exports as a circular thumbnail in PDF; same photo clipped to a custom heart path does too.

---

Risks and tradeoffs

Risk	Mitigation
Six renderers to update for one new type	Pre-refactor to a shared renderLayerVisualInto first. Cost is paid once, benefits every future type.
Print fidelity for clip-path varies across older browsers	All four supported browsers (recent Chrome/Edge/Brave/Safari) handle it. We document the browser-version floor in the README.
path d= from user input is a security surface	We only set it as a d attribute (never innerHTML), and validate it's a parseable path string. No script execution surface — d attributes can't carry JS.
Gradient picker is the meatiest UI piece	Start with 2-stop only. JSON allows N stops so a v2 picker is non-breaking.
Stroke "position" (inside/center/outside)	Center only in v1. Outside-stroke needs path inflation, which is heavy. Document the limitation.
100+ shape layers in one design	SVG handles this well; we already do similar with text layers. Canvas export is the main perf risk and can be deferred via progress UI.
Old clients see and skip our shape layers	Acceptable. The rest of the design still renders. We could add a top-level schemaVersion bump but it's not strictly needed — type is the existing discriminator.
Reference cycles in layer-ref clips	Detect at render time and break the cycle (render unclipped + console.warn).
Two ways to make a rectangle (color and shape)	Live with it. Document the recommendation: new templates should prefer shape; old color layers keep working forever.
Gradient color picking (no eyedropper)	Standard <input type="color">. Out of scope to build a custom picker in v1.

---

Out of scope (future work)

• SVG file import — let users drop an .svg file and we parse it into one or more shape layers. Big can of worms (groups, transforms, embedded <style>, <image> refs). Future feature.
• Boolean operations — union / intersect / subtract two shapes into one. Useful for masks. Out of scope.
• Pattern fills — repeating image fills inside a shape. Future.
• Mesh / conic gradients — niche, browser support uneven.
• Drop shadows / blur / glow — own feature doc (docs/LAYER_EFFECTS_FEATURE.md).
• Interactive bezier pen tool — significant editor work. Out of scope.
• Animated SVG / CSS animations — these are print-oriented designs; animation isn't a fit.

---

Open questions

1. Should shape deprecate color? No. Keep color as a shortcut. New templates can use either. Documenting the recommendation is enough.
2. Should clip be on any layer or only image layers? Any layer. The model is general; the UI surfaces it for image / shape / text alike. Text-clip is a small win nobody asked for, but it's free.
3. Stroke widths in inches or pixels? Inches, matching the rest of the coordinate system. Convert to SVG units at render time.
4. Do we ship a curated shape preset library (heart, arrow, etc.)? v1: no — the basic primitives are enough. A small JSON file of preset d= strings would be a tiny, decoupled v2.
5. Should the gradient picker support N stops out of the gate? No. 2-stop covers most real use. JSON supports N; UI grows later if asked.
6. Should the layer panel show a small icon preview per layer (especially shapes)? Nice-to-have. Not required for the feature to ship.

---

Acceptance summary

Phase A

• Adding a shape from the layer panel produces a JSON-serializable shape layer with sensible defaults.
• All 6 surface renderers (editor + 5 previews) render the shape.
• Canvas PDF/JPEG export renders the shape.
• Save → load round-trips the shape correctly.
• Publish → fork → load round-trips the shape correctly.
• Selected-layer controls let the user change kind-specific params.

Phase B

• Linear and radial gradient fills work in editor + previews + canvas export.
• Gradient picker UI (2-stop) is intuitive and doesn't fight existing fill controls.

Phase C

• Solid strokes with width and dash render in editor + previews + canvas export.
• Stroke and fill compose correctly (fill underneath, stroke on top).

Phase D

• Pasting an SVG d= string adds a valid path layer.
• Bad input rejects with a friendly error, never throws.

Phase E

• Inline-shape clip works on image, text, color, and shape layers.
• Layer-ref clip works and detects cycles.
• Clipped layers export to PDF and JPEG with the same visual result as in the editor.