Phoenix LiveView function component that attaches Etcher's annotation overlay to a named <Fresco.canvas> or <Fresco.scroll_strip>.

The component renders a hidden host <div phx-hook="EtcherLayer">. The client-side hook:

• Looks up the named Fresco viewer via window.Fresco.onReady/2
• Detects whether the handle is a <Fresco.canvas> (single canvas- pixel coordinate space, exposes getCanvasSize) or a <Fresco.scroll_strip> (per-image natural pixel coordinates, exposes scrollTo + getImages) and routes to the matching renderer
• Appends a pencil button to Fresco's nav column via handle.appendNavButton/3
• On pencil click, opens a bottom toolbar with the configured drawing tools and toggles annotation mode
• Draws shapes as SVG overlays — one canvas-spanning SVG in canvas mode, one per-image SVG sibling in strip mode
• Hydrates initial annotations from handle.getExtension("etcher")
• Pushes etcher:annotations-changed events to the consumer's LiveView with the full annotations array on every commit / edit / delete

Canvas mode

<Fresco.canvas id="board" canvas={@canvas} class="w-full h-screen" />

<Etcher.layer
  fresco_id="board"
  tools={[:grabber, :rectangle, :circle, :polygon, :freehand, :marker, :callout, :text, :dimension, :eraser]}
/>

Strip mode

<Fresco.scroll_strip id="reader" sources={@pages} extensions={@reader_extensions} />

<Etcher.layer fresco_id="reader" tools={[:rectangle, :freehand, :text]} />

The component is identical in both cases — fresco_id is the only thing that changes. Strip-mode annotations carry an extra image_idx field on each shape identifying which image they live on.

The event your LiveView must handle (canvas)

def handle_event("etcher:annotations-changed", %{"annotations" => annotations}, socket) do
  new_canvas =
    Fresco.Canvas.put_extension(socket.assigns.canvas, "etcher", %{
      "version" => "1",
      "annotations" => annotations
    })

  {:noreply, assign(socket, canvas: new_canvas)}
end

The event your LiveView must handle (strip)

Strip-mode annotations carry image_idx (which page they're on). Strip viewers don't have a %Fresco.Canvas{} struct or a put_extension/3 helper — the consumer just maintains the :extensions map (a plain %{}) in socket assigns and threads it through the component:

def handle_event("etcher:annotations-changed", %{"annotations" => annotations}, socket) do
  extensions =
    Map.put(socket.assigns.reader_extensions, "etcher", %{
      "version" => "1",
      "annotations" => annotations
    })

  {:noreply, assign(socket, reader_extensions: extensions)}
end

When a LiveView hosts multiple Etcher layers, the "etcher:annotations-changed" payload includes a "fresco_id" key so consumers can pattern-match on the source:

def handle_event(
      "etcher:annotations-changed",
      %{"fresco_id" => "reader", "annotations" => annotations},
      socket
    ) do
  # ...
end

UUIDs are generated client-side (UUIDv7) in both modes, so there's no tmp_id ⇄ real-uuid round-trip — the server never has to assign ids.

Color slots and the etcher:colors-changed hook

The toolbar shows 5 fixed, editable color slots. Clicking a slot selects it; opening the hue picker and choosing a color overwrites the selected slot in place. Each committed edit reports the full palette through two channels (mirroring etcher:annotations-changed + the JS lifecycle events) — Etcher itself persists nothing:

• a LiveView event your handle_event/3 can store, and
• a bubbling DOM CustomEvent for pure-JS consumers.

Seed the slots with the :colors attr (per-user palette) or via extensions["etcher"]["colors"]; the save/load is generic so the same hook can target a .fresco/extension blob here or a per-user store (e.g. phoenix_kit custom_fields) in a host app.

def handle_event(
      "etcher:colors-changed",
      %{"fresco_id" => "board", "colors" => colors},
      socket
    ) do
  # `colors` is a list of "#rrggbb" strings. Persist however you
  # like — alongside annotations in the canvas extension, or in the
  # current user's metadata. Round-trip it back through `:colors`
  # (or the extension) on the next mount.
  etcher = Map.put(socket.assigns.canvas.extensions["etcher"] || %{}, "colors", colors)
  {:noreply,
   assign(socket,
     canvas: Fresco.Canvas.put_extension(socket.assigns.canvas, "etcher", etcher)
   )}
end

Programmatic control mirrors the colors: layer.getColors(), layer.setColors([...]), layer.setSlotColor(i, "#rrggbb") on the window.Etcher.layerFor(id) handle.

Line params and the etcher:line-params-changed hook

The Parameters popup (thickness / opacity / dash) sets the global default new strokes inherit. With no shape selected, committing a slider or picking a dash reports the new default through the same two channels as the colors hook, so you can persist per-user "ink":

def handle_event(
      "etcher:line-params-changed",
      %{"fresco_id" => "board", "line_params" => lp},
      socket
    ) when is_map(lp) do
  # `lp` is %{"width" => n, "opacity" => n, "dash" => "solid"|"dashed"|
  # "dotted"}. Persist it (e.g. in the current user's metadata) and feed
  # it back through the `:line_params` attr on the next mount.
  {:noreply, socket}
end

Seed the default with the :line_params attr; missing keys fall back to the built-ins (width: 2, opacity: 1, dash: "solid"). Editing a selected shape's style instead keeps flowing through etcher:annotations-changed (it's saved with the shape) and does not fire this event. Programmatic: layer.getLineParams() / layer.setLineParams(%{...}) (the latter doesn't echo the event).

Tools

Configure which drawing tools appear in the bottom toolbar. The default exposes the navigation grabber, all drawing kinds, and the eraser:

tools={[:grabber, :rectangle, :circle, :polygon, :freehand, :marker, :callout, :text, :dimension, :line, :eraser]}

Subsetting hides specific tools (e.g. only :rectangle, :freehand). Drop :eraser if you don't want users deleting from the toolbar, or :grabber if pan-only mode isn't needed.

Annotation hydration

Initial annotations come from the viewer's extensions.etcher map. The consumer's mount/3 typically reads a .fresco file (canvas mode):

canvas = Fresco.Canvas.read!("/path/to/scene.fresco")
{:ok, assign(socket, canvas: canvas)}

…or assigns the strip's extension map directly (strip mode):

extensions = %{
  "etcher" => %{
    "version" => "1",
    "annotations" => [
      %{"uuid" => "01HXY...", "kind" => "rectangle",
        "geometry" => %{"x" => 100, "y" => 200, "w" => 50, "h" => 50},
        "image_idx" => 2}
    ]
  }
}
{:ok, assign(socket, pages: @pages, reader_extensions: extensions)}

Either way <Etcher.layer> reads the annotations through Fresco's handle at mount time and renders each shape on the matching page.

Coordinate spaces

Shape geometry is stored in the same coordinate system the host Fresco component reports for that image, never as a normalized fraction. Two cases:

• Strip mode (<Fresco.scroll_strip> / <FrescoStrip.viewer>) — geometry is in source-pixel space: a circle's cx, cy, r, a polygon's points[].x/y, are integers in the image's own natural-pixel grid (e.g. a 720×9200 page uses 0..720 / 0..9200). Independent of the rendered display size, so shapes survive strip width changes without recomputation.
• Canvas mode (<Fresco.canvas>) — geometry is in canvas- pixel space: a unified stage spanning all images in the scene, sized in canvas-internal pixels (the dimensions returned by the canvas handle's getCanvasSize()). A single coord pair can address any image since they're all laid out on the same stage.

Consumers that scroll to a shape, render mini-maps, or persist shape positions outside of Etcher should know which space they're in. layer.getShape(uuid) returns the shape descriptor with either image_idx (strip) or image_id (canvas multi-image) attached so routing UI doesn't need to scrape DOM data-attrs.

Z-order (arrange)

Shapes paint in list order, so the newest covers everything drawn before it — an image pasted after a caption hides it. The four arrange actions move the current selection (the multi-selection when there is one, else the shape in edit mode) through that order:

layer.bringToFront();   // ⌘] — past everything
layer.bringForward();   // ]  — one step
layer.sendBackward();   // [  — one step
layer.sendToBack();     // ⌘[ — behind everything

Each returns true when something actually moved and false at the edge or with nothing selected, so external buttons can reflect that; layer.canArrange() answers the same question without moving anything. The same four sit in the toolbar's [⋯] overflow, disabled until something is selected — they act on a selection rather than being drawing modes, so they belong with undo/redo rather than in :tools.

Reordering is undoable and re-emits etcher:annotations-changed with the new order, so a host that persists the annotation list persists the layering with it, and collaborators receive it like any other edit.

layer.setShapeOrder(uuids) forces an explicit order — shapes missing from the list keep their relative position at the end. It deliberately records no undo entry and emits nothing, because it exists for applying an order that arrived from somewhere authoritative (a peer, a server load), where echoing it back would loop.

Reaching a buried shape

A pointer event only ever reaches the topmost shape under it, which would leave anything fully covered impossible to select — and so impossible to arrange out from underneath. Tapping the same spot again therefore walks down the stack instead of re-selecting the top, putting the covered shape two taps away. Moving more than ~14px, or pausing longer than 1.5s, starts a fresh cycle.

Programmatic API

Each mounted layer registers a handle on window.Etcher.layerFor(id):

var layer = window.Etcher.layerFor("reader");
layer.setMode(true);                       // enter annotation mode
layer.selectTool("rectangle");
layer.deleteShape("01HXY...");

// Shape descriptors include image_idx (strip) / image_id (canvas):
var shape = layer.getShape("01HXY...");
// → { uuid, kind, geometry, style, metadata,
//     image_idx?: 4,         // strip mode
//     image_id?: "page-5" }  // canvas multi-image

// Reveal a shape — Promise-returning, polls for late-mounted
// shapes, optional pulse flash, fires `etcher:shape-revealed`.
layer.revealShape("01HXY...", { pulse: true })
  .then(function (r) { console.log("revealed on image", r.image_idx); })
  .catch(function (e) { console.warn(e.reason); });

// Hit-test a point against the current shapes. Returns the
// top-most shape descriptor (uuid, kind, geometry, image_idx /
// image_id, …) under `pt`, or null. Use when wiring custom
// tap-zone navigation so the tap can be ignored when it lands
// on an annotation:
//   const hit = layer.shapeAt({ imageIdx: 2, x: 540, y: 920 });
//   if (hit) return; // let etcher handle it
// Strip handles: pt = { imageIdx, x, y } in source-pixel space.
// Canvas handles: pt = { x, y } in canvas-pixel space.

See priv/static/etcher.js for the full API surface.