Apply twelve Nostr-driven revisions to the Book Designer spec:
1. **Sidecar architecture.** Pages, masters, and the cover spread
are now separate addressable kind-30078 events
(`casewrap-page`, role-discriminated). The book is a thin
`casewrap-book` manifest that references them by
`{ kind, pubkey, dTag }` — the same shape Linked Designs
already speaks. Edit one page → that page event replaces; the
manifest only changes when order / list / spec moves.
2. **Masters as Nostr objects.** Each master is its own event; one
"Body pages" master can be referenced by many books and forked
by other authors. Default master lives on the manifest spec.
3. **Cover as a sidecar event** with `role: 'cover-spread'` so it
can iterate independently and be republished as standalone
marketing art.
4. **Linked Designs is the precedent.** The resolver IIFE,
progressive fetch, localStorage disk cache, batched relay
queries, upstream-update notifications, and attribution chain
all transfer verbatim. Call this out explicitly so we don't
reinvent the wheel.
5. **Addressable refs everywhere.** Manifest entries use the
existing `{ kind, pubkey, dTag }` form (convertible to naddr at
the UI layer), not local UUIDs.
6. **Premium gating + tips.** New "Premium, tipping, gating"
section covers whole-book paywall (gate the manifest),
per-chapter paywall (gate individual page events via
PREMIUM_DESIGNS), and NIP-57 zaps at any granularity.
7. **Reader Mode** added as Phase G — the Slide Decks' Presenter
Mode counterpart, with progressive page fetch, TOC sidebar,
page-flip nav, and inline zap-to-unlock.
8. **Embed integration.** EXTERNAL_EMBED learns `?book=<naddr>`
for a flip-book iframe player; same transport + CSP rules.
9. **Per-page reactions / comments** work for free because each
page is its own addressable event (NIP-25 + kind-1). One-liner
in product goals + Reader Mode acceptance.
10. **`{page-count}` semantics pinned.** Defaults to *numbered*
pages; new `{physical-page-count}` exposes the raw total.
Plus `{book-author}` for the manifest pubkey.
11. **NIP-23 distinction.** Explicit non-goal — Book mode is
fixed-layout design, not reflowable prose; for prose use
NIP-23 long-form articles directly.
12. **Manifest schema.** Pages now carry
`{ ref, label?, inheritsMasterRef, skipNumber, gating? }`;
page-side fields that vary per-book (master, skipNumber,
label) moved off the page event onto the manifest entry.
Phase D split into D1 (publish individual page / master / cover
events) and D2 (publish the manifest); new Phase G (Reader Mode +
embed); new Phase H (premium gating). Acceptance summary,
cross-surface reactivity, and risks updated to match.
TODO.md's Book Designer summary rewritten to reflect the
sidecar plan.
New BOOK_DESIGNER_FEATURE.md drafts a top-level templateMode: 'book'
that orchestrates the existing cover designer, deck overview, and
custom-art canvas around a shared document spec (trim size, page
count, paper thickness, bleed). Spine width derives from page count
× paper thickness; the cover view goes read-only on the spine
column when in derived mode. Pages reuse the deck-sorter UI for
reordering; the per-page editor is the custom-art canvas bound to
a book-page:<id> target with prev / next page nav. Masters render
underneath each inheriting page and support {page-number} /
{page-count} / {book-title} token substitution.
PDF export ships in its own phase (E), backed by a vendored
pdf-lib (~80 KB). Single-file (cover + interior) and split (cover
PDF + interior PDF) output modes; bleed + crop-mark options;
v1 flattens text to vector for font-fidelity, with vector PDF
text as a follow-up.
Phased: A (spec + skeleton) → B (pages + editor) → C (masters) →
D (publish) → E (PDF export) → F (templates + deck-to-book
import). Non-goals: reflowable text, footnotes, automatic TOC,
CMYK / ICC, imposition, mixed page sizes in one book.
Linked from README's "Drafted-but-unbuilt" list and TODO.md.
startLayerRotate and startLayerSelectionRotate called render() on
every pointermove, which tore down the .freeLayer wrapper that owns
the rotation handle. That dropped pointerCapture mid-drag, so after
the first move event the gesture "let go" — the handle stopped
following the cursor and only a few degrees of rotation registered
before the user had to grab again.
Fixed both paths the same way the resize handler does: mutate the
layer's rotate (and centre, for multi-layer) and apply the change
directly to the affected .freeLayer's transform / position styles
inside move; only call render() on pointerup so the rest of the UI
catches up. The sidebar Rotation field updates live via
syncLayerInputs() as before.
The Shape tool's fill / stroke colour pickers and stroke-width input
shared DOM ids (shapeFillColor, shapeStrokeColor, shapeStrokeWidth)
with the selected-shape-layer edit panel's equivalents.
document.getElementById returns only the first match, so the input
listeners that drive _shapeToolOpts attached to the layer-panel
inputs (which aren't visible while the Shape tool is active), not
the tool-panel inputs. Result: changing fill / stroke colour or
stroke width on the tool panel had no effect on the next shape drawn.
Renamed the three tool-panel inputs to shapeToolFillColor /
shapeToolStrokeColor / shapeToolStrokeWidth (and their <label for>
references and the syncToolOptionInputs + input-event listeners).
A full repo scan confirms no other duplicate DOM ids remain.
PEN_TOOL_FEATURE.md gets a 2026-06-02 status block documenting
everything that landed on top of Phase D — Direct Selection split,
auto-add/auto-delete, click-vs-drag convert, Alt-click curved ↔
pointed, multi-anchor select / marquee / arrow nudge, drag-segment
bow, continue-endpoint, spacebar reposition, Alt mid-draw, handle
break, Cmd+J / Cmd+Alt+J, Path Actions side panel — plus the
adjacent design-tool features that shipped in the same arc
(Eyedropper, Align & distribute, Free Transform rotation,
Pathfinder, marquee box-select, dive-into-edit on dbl-click).
TODO.md gets a "Design-tool follow-ups" section listing the gaps:
Smart Guides, Gradients + shadows, Scissors / Outline text /
Command palette, Flip H / V (needs renderer scaleX/scaleY),
Pathfinder rotation support, pixel-art frame timeline.
- Double-click a vector shape with the Select tool active and we
flip to Direct Selection on that shape, auto-converting non-pen
primitives (rect / circle / polygon / etc.) to editable pen paths
first so anchors appear immediately — Illustrator's dive-into-
isolation behavior. Double-click is ignored if any other tool is
active or the click landed on a transform handle.
- Direct Selection on the canvas: a plain click in empty space
(anywhere the overlay covers, including beyond the layer's bbox)
now clears the layer selection entirely, not just the anchor
sub-selection. The anchor-marquee path still kicks in for real
drags. Off-canvas clicks already deselected via the previewShell
handler, so this closes the last in-canvas gap.
The 0.0075 dot / 0.0018 line ratios still rendered as ~14px dots
with thick stems on a 1920px-wide preview, which dominated short
paths. Dropped the dot radius to 0.0028 and the line width to ~0.001
so the editing UI reads as a tiny on-canvas widget (~7px) rather
than a UI element fighting the artwork. Both renderPenEditHandles
and renderPenDraft use the new sizes so live drawing and post-commit
editing stay consistent.
The hollow white arrow distinction was too subtle when both V and A
tools are side-by-side. Switched to a solid light blue (#60a5fa)
arrow so Direct Selection reads as visually distinct at a glance;
the regular Select arrow stays the default black.
The pen draft path was using a canvas-relative thickness (lineW * 2,
derived from the canvas dimensions) for its preview stroke, so the
ribbon you saw while drawing looked different from the path you got
after committing. The committed path stores its stroke width in
pixel-space (1 unit = 1 px @ 96 dpi); the overlay renders in inch
space, so the live preview now divides _penToolOpts.penStrokeWidth
by 96 — same trick the pencil draft already uses — and adds round
line-cap / line-join so curves look consistent with the committed
path.
Click-and-drag on an empty area of the canvas (with the V tool
active) now draws a marching-ants rectangle. On release, every
layer whose bounding box intersects the rectangle is selected;
Shift / Ctrl / Cmd held during the drag adds to the existing
selection instead of replacing it.
Plain clicks (no drag past the 4 px deadzone) still clear the
selection, preserving the previous "click empty area to deselect"
behaviour. Other tools own their own canvas drags (Pen creates
anchors, Hand pans, Shape drags out a primitive, Direct Select
marquees over anchors), so this only kicks in for V.
Shift+click on a layer to add or remove it from the current
selection was already wired — confirmed working through the
existing additive path in startLayerDrag.
Boolean ops on 2+ selected shape layers, backed by the vendored
polygon-clipping library (29 KB minified, MIT) loaded from
src/vendor/. Adds a new "Pathfinder" details block in the sidebar
under Align & distribute.
- Unite combines all selected shapes into one outline.
- Subtract removes upper shapes from the bottom-most shape.
- Intersect keeps only the overlapping region.
- Exclude keeps only the non-overlapping regions (XOR).
Pipeline: each selected layer's pen path is sampled to a polygon
(16 samples per Bézier segment, in world inches), the chosen op
runs, and the result is rebuilt as a new pen layer that inherits
the bottom-most input layer's z-order, target, fill and stroke —
matching Illustrator's Pathfinder convention. Non-pen primitives
(rect, circle, etc.) are auto-converted to pen paths first.
Limitations baked in:
- Rotated layers aren't supported yet (we'd need to rotate the
sampled polygon before clipping). The op refuses with a toast.
- Curves are flattened — the result is a polygon approximation
with `fill-rule: evenodd` so multi-ring outputs (donut from a
subtraction) render correctly. The renderer learned to honor
shape.fillRule for this commit.
- Multi-polygon results stay rendered correctly but only the
first polygon's outer ring is preserved in pen.nodes, so
Direct Select editing post-op is partial.
A 9th handle (round, accent-colored, sitting above the bounding box
on a thin connector line) joins the existing 8 scale handles on both
the single-layer overlay and the multi-layer selection box.
- Single layer: drag rotates the layer about its own centre, with
Shift snapping to 15° increments. The existing resize handles
already account for layer.rotate in their local-frame math, so
resizing keeps working at any rotation.
- Multi-layer selection: drag rotates each layer's centre around the
selection bbox's centre AND advances each layer's own rotation by
the same delta — the group spins as a rigid body. Pre-snapshotting
the centres + rotations keeps the math stable across long drags.
- Locked / generated-disc layers are filtered out as everywhere else.
A new "Align & distribute" details block in the layer-controls sidebar
surfaces eight ops: left / horizontal-centre / right and top / middle
/ bottom alignment, plus horizontal and vertical distribution.
- Multi-selection (2+ layers) aligns within the selection's own
bounding box, so the outer layers stay put and the rest snap into
line with them.
- Single-layer selection aligns to the layer's target bounds (page
panel / disc face / custom canvas), making it easy to centre or
pin a single asset without setting up a dummy second layer.
- Distribute requires three or more layers — the outermost two stay
pinned and the inner layers slide so consecutive centres are
evenly spaced along the chosen axis. Helpers toast a hint when the
selection is too small.
- Locked / generated-disc layers are skipped automatically.
Flip H / V were prototyped here but pulled out — they need a renderer
extension to honour per-layer scaleX/scaleY, which is a separate change.
A new ⊙ button in the tool palette and the I keyboard shortcut open
the browser's window.EyeDropper picker so the user can sample any
pixel anywhere on screen (not just our canvas) and apply the
sampled hex to a smart target:
- Selected shape layer → fill color (Shift = stroke color).
- Selected text layer → text color.
- No layer selected → pen / shape tool's default fill (or
stroke), so the next thing drawn picks up the sampled hue.
The eyedropper is a transient action rather than a persistent tool —
invoking it doesn't change the active tool, so users can sample
mid-edit without losing their cursor. Falls back to a hint toast in
browsers that don't yet support window.EyeDropper (Safari).
A new "Path actions" block appears in the right-side tool options panel
whenever Pen (P) or Direct Selection (A) is active and an editable pen
layer is selected. The block surfaces the most useful anchor- / path-
level operations as buttons so they're discoverable without keyboard
shortcuts:
- Pointed corner / Curved smooth — flip the selected anchors (or all,
if none are selected) between handle-less corner and symmetric-handle
smooth, matching the Alt-click convert behavior.
- Delete anchor — bulk-delete the current anchor selection (Backspace
equivalent).
- Average — move selected anchors to their centroid (Cmd+Alt+J).
- Join endpoints — close an open path when both its endpoints are
selected (Cmd+J); button auto-disables otherwise.
- Close / Open path — toggle the path's closed flag.
- Reverse direction — flip the order anchors are drawn in.
A small hint at the top of the block reflects the current selection
size, so the user knows what an action will affect. The "Join" button
auto-disables when join would be a no-op; "Average" requires at least
two anchors. Direct Selection also gets a short panel reminding the
user how anchor editing works (multi-select via Shift / marquee, arrow
keys nudge selected anchors).
The presence of handles is now the source of truth for whether a
node is pointed or curved, so Alt-click does a full flip in either
direction:
- Anchor with any handle → drops both handles and demotes to a real
corner. The path renders straight segments through it.
- Anchor with no handles → grows symmetric Bézier handles aimed along
the chord through this anchor (using neighbouring anchors when they
exist, falling back to the single available neighbour for endpoints
of an open path). Handle length is 1/3 of the chord, so the curve
bends visibly without ballooning out.
Previously the toggle only flipped the kind flag without touching
handles, so a smooth-to-corner click left the curve looking unchanged
and a corner-with-no-handles click did nothing visible at all.
- Cmd+J closes an open path when both its endpoints are part of the
current anchor selection. No-op if the path is already closed or
the selection doesn't cover both endpoints; the user gets a hint
toast in that case.
- Cmd+Alt+J averages every selected anchor to the centroid of the
selection. Handles slide with their anchors so local curvature is
preserved. Requires at least two anchors selected.
While the pen tool's click-drag is still down (the gesture that pulls
Bézier handles out of a freshly-placed anchor), two modifiers now
match Illustrator's pen behavior:
- Hold Alt during the drag and only the outgoing handle is pulled.
The incoming side stays at the anchor, giving an asymmetric corner
that's perfect for tangent-then-corner transitions without lifting
the pen.
- Hold Space and the drag stops growing handles and starts sliding
the anchor itself, carrying any handles along. Release Space to
resume handle-pulling from the anchor's new position. Mouse delta
is tracked from the moment each mode is entered, so toggling Space
on/off mid-drag doesn't introduce drift.
- Pen tool over an existing segment now auto-inserts an anchor at the
click with no modifier (was Alt-only). Pen over an anchor deletes it
on click — Illustrator's default "Auto Add/Delete Anchor" behavior.
- Drag (past a small threshold) on an existing anchor with the Pen tool
converts the anchor on the fly: pulls symmetric handles from the
drag, promoting corner → smooth. Alt-drag pulls only the outgoing
handle for an asymmetric corner.
- Alt-click an anchor in Pen mode still toggles corner ↔ smooth (drops
or pairs handles without a drag), preserving the existing modifier.
- Alt-drag a handle in Direct Selection breaks the smooth-anchor's
handle symmetry: the node becomes a corner so the opposite handle
stays put while the dragged one moves independently.
- Endpoint-of-open-path still wins over auto-delete: hovering the start
or last anchor of an open path shows the "continue" pointer cue, and
clicking resumes drawing rather than deleting.
- Hover cursors updated: − (delete) over a deletable anchor, + (add)
over a segment in Pen mode, grab over a segment in Direct Select.
With the Pen tool, clicking an endpoint of an open path resumes
drawing from that anchor. The source path is hidden for the duration
of the draft; on commit (Enter / click-back-to-start / Escape) the
old layer is dropped and the new (longer) path takes its place,
preserving the original z-order, target, fill and stroke. Clicking
the start anchor reverses the node order so the next click extends
in the natural direction. Cancelling the draft restores the source
path unchanged.
- Multi-anchor selection. Shift-click an anchor to add/remove it from
the selection set; click without modifier selects just that anchor.
Dragging any selected anchor moves the whole set rigidly (anchors +
handles), so reshape operations affect groups in one gesture.
- Arrow keys nudge selected anchors. Direct Selection (or Pen) with at
least one anchor in the selection: ←/→/↑/↓ moves the anchors and
their handles by 1px (10px with Shift) in pixel-space; bbox refits
automatically. Falls back to the existing layer-nudge when no anchor
is selected.
- Marquee anchor box-select. In Direct Selection, drag from empty
space inside the layer to draw a dashed rectangle; on release, every
anchor whose center lies inside the box is selected. Shift+drag adds
to the existing selection.
- Drag a curve segment to bow it. Equal-split delta distributed
across the two inner control points so the cursor tracks the grabbed
point; smooth anchors on either end keep their handles mirrored. Lines
are auto-promoted to cubics on first bow.
- Alt-click a segment in Direct Selection now inserts an anchor at the
click (mirrors the Pen tool's segment-insert), and Alt-click an
anchor still toggles corner/smooth.
- Backspace deletes every selected anchor at once (bulk delete), with
the "path needs at least two anchors" guard applied to the resulting
size.
- New Direct Selection tool (A) as a separate palette button, distinct
from the regular Select tool. Anchors and handles only appear when
Pen or Direct Select is the effective tool, matching Illustrator's
V/A split.
- Cmd/Ctrl temporary toggle: holding the modifier from any non-Pen tool
flips the effective tool to Direct Selection so a quick anchor tweak
doesn't require dropping the current tool; release restores it.
- Hover cursor feedback on pen/direct-select: shows + when over the
end of an open path, - over an existing anchor (delete-adjacent),
✕ near the start to close, default crosshair otherwise.
- Shift constrains pen segments to 0/45/90 degrees while drawing and
while previewing the next click, matching Illustrator's constrain.
Foundation for the multi-anchor select + drag-segment + continue-path
endpoint work that follows.
Selecting a pen-shape layer with the Select tool now reveals its
anchors + handles for inline editing — no need to switch to the
Pen tool first. Drag anchors / handles to reshape; right-click
or Backspace to delete; Alt-click toggles corner ↔ smooth. Pen
mode keeps the richer affordances (segment-click to insert
anchor, click-to-create-new-path) since those would conflict with
the Select tool's normal layer-click behavior.
Three small changes:
- getEditablePenLayer drops the strict 'pen' tool requirement and
also accepts 'select'.
- syncPenOverlay keeps the overlay alive in select mode when a
pen-shape layer is selected; render() now re-syncs each frame
so the overlay appears / disappears as selection changes
(without requiring a tool change).
- renderPenEditHandles marks anchor + handle elements
pointer-events: all (with `cursor: pointer`) while the overlay
base stays pointer-events: none. Empty-space clicks fall
through to the layer's normal selection behavior; only clicks
on anchors / handles register as edit ops.
onPenPointerDown gains a select-mode branch that:
- Only handles anchor / handle hits; segment clicks pass through
to the layer (so dragging the path body still selects / moves
the layer as expected).
- preventDefault + stopPropagation on anchor / handle hits so
the underlying layer-drag handler doesn't also fire.
Two pen paths with the same stored stroke number rendered at very
different on-screen thicknesses — strokes scaled with layer size
because nodes lived in a 0-100 normalized viewBox. The pencil tool
solved this exact problem (see commitPencilStroke ~line 9580 with
the inline comment about pixel-space viewBox = "true on-screen
thickness, identical no matter how long the stroke is"). Switching
pen paths to the same scheme.
Pen nodes now live in a pixel-space viewBox where 1 unit = 1 px
at 96 dpi: viewBox dims = (layer.w * 96, layer.h * 96). Because
the viewBox aspect matches the layer aspect, the renderer's
sx == sy (uniform scale) AND the same stroke-width number produces
the same device-pixel thickness on every pen path regardless of
size.
Five touchpoints updated:
- finishPenPath: node remap multiplies bbox-relative coords by 96
instead of normalizing to 0-100; viewBox.w / viewBox.h written
as bbox.w*96 / bbox.h*96.
- penNodeToInch / inchToPenNode: convert via /96 (was /100 of
layer dim).
- regenPenLayerD: viewBox rewritten as (layer.w*96, layer.h*96)
on every edit. Catches user-resizes via corner handles too.
- refitPenLayerIfNeeded: bounds checked against pixel-space
viewBox; layer position/size translated via /96; node remap is
now a pure translation (no rescale, since the units stay
pixel-space).
- "Make editable path" conversion: 0-100 primitive nodes mapped
to pixel-space relative to the existing layer's dimensions.
Strokes are now consistent across pen paths of any size, and the
in-progress draft (rendered in the pen overlay's inch-space) still
matches the final committed path's visual stroke weight at the
canvas's natural 96-DPI mapping.
The previous "uniform-scale remap" commit fixed node coordinates to
land in 0-100 × 0-(100*h/w), but the renderer (buildShapeSvgInner
path branch) reads shape.viewBox and computes sx = 100/vb.w,
sy = vbH/vb.h. With shape.viewBox.h hardcoded to 100, sx ≠ sy for
non-square layers and the path got stretched again — strokes
distorted around curves after the path was committed, even though
the in-progress draft (which renders inside the pen overlay, not
the layer SVG) looked fine.
Fix is the matching half: also write shape.viewBox.h = 100*lh/lw
wherever we touch the pen data, so sx == sy and the renderer
applies a uniform scale.
- finishPenPath now sets viewBox.h = vbH from the bbox aspect.
- regenPenLayerD (called on every edit drag + insert/delete/toggle)
recomputes vbH from current layer.w/h before writing the new d
string. This catches the rare case where layer.w/h change between
refit calls without my refit running.
- The "Make editable path" conversion remaps primitiveToPenNodes /
parsePathDToNodes results (which always come in 0-100×0-100) into
the layer's actual aspect space, and writes viewBox.h to match.
Result: converting a rect → editable path on a non-square layer
keeps its proportions, and the resulting pen path edits cleanly
with uniform strokes.
Strokes now stay a constant width all the way around closed
shapes, even after the path is fully committed and re-rendered
through the standard shape-layer pipeline.
Two visual issues on top of the Phase D close-out commit:
1. **Stroke width varied along curves.** The pre-existing pipeline
stored nodes in 0-100 × 0-100 viewBox space and let the SVG
renderer pick `vbH = 100 * layer.h / layer.w` with
`preserveAspectRatio="none"`. For any non-square layer, the
0-100×0-100 node range got stretched non-uniformly into a 100×vbH
viewBox, distorting the path: strokes appeared wider where the
curve traveled more in one axis. Phase D's refit made this much
more likely because dragging anchors out of bounds routinely
produced non-square layers.
Fix in two places:
- finishPenPath: uniform-scale the bbox by `100/bbox.w` so y
range lands at exactly `100 * h/w = vbH`. The viewBox aspect
matches the layer aspect, no stretching.
- refitPenLayerIfNeeded: same uniform-scale invariant. Also
respects the layer's current vbH when deciding whether nodes
are "out of bounds" — was previously hard-coded at 100, which
wrongly fired refit on every drag in already-non-square layers.
2. **Anchor + handle glyphs were too prominent.** On a 1920px-wide
slide preview the old `dotR = 0.013 * unit` rendered ~25px
dots. Reduced to `0.0075 * unit` (~12px) and stroke from
`0.003 * unit` to `0.0018 * unit`. The in-progress draft
renderer matches.
Strokes now stay constant width all the way around a curve, and
the editing UI reads as overlay rather than as part of the artwork.
Finished the deferred Phase D pieces from PEN_TOOL_FEATURE.md.
New affordances on the editable pen layer:
- Click a segment between anchors → inserts a new anchor at the
click point via de Casteljau cubic split. Curve shape is
preserved exactly: a's hOut, b's hIn, and the new mid-anchor's
handles all derive from the split. Lines (no handles either
side) get a plain midpoint anchor with no handles. The new
anchor is selected and immediately drag-able.
- Right-click an anchor → delete it. Suppresses the browser
context menu on the pen overlay always.
- Backspace / Delete with an anchor selected → delete it.
Layer-delete still wins when no anchor is selected. The pen
tool's selected-anchor sentinel `_penSelectedAnchor` is reset
on tool change.
- Alt-click an anchor → toggle between `kind: 'corner'` (handles
move independently) and `kind: 'smooth'` (handles stay mirrored
across the anchor). Promoting to smooth re-derives the missing
handle (or re-mirrors both if independent) so the curve
actually becomes continuous. New nodes from pen click-drag
default to smooth; new nodes from a single click are corners.
- Drag an anchor or handle past the original 0–100 viewBox →
the layer's bounding rect auto-refits. New `refitPenLayerIfNeeded`
computes the bbox over all nodes + handles, translates
layer.x/y by the bbox offset (scaled to current w/h), updates
layer.w/h, then remaps every node into the new 0–100 space.
Path stays visually anchored to the canvas — no more clipping
at the layer edge.
Anchor glyphs now distinguish kind: smooth = circle (existing
look), corner = square. The selected anchor renders with an amber
stroke (#f97316) so the Backspace-to-delete target is unmistakable.
Spec updated to mark Phase D complete and the deferred items
shipped. Rotated paths are still not node-editable in v1 (the
deferral remains).
Removed three superseded spec files now that the work they
described is either shipped (under newer specs) or formally
replaced:
docs/ZAP_GATED_TEMPLATES_FEATURE.md
docs/ZAPS_NWC_FEATURE.md
docs/ZAP_GATED_PREMIUM_FEATURE.md
The history is preserved in git. The current canonical premium
plan is docs/PREMIUM_DESIGNS_FEATURE.md (which absorbed the
zap-gated+NWC infrastructure plus added the soft-gate KDF +
encrypted envelopes + purchase vault).
README's docs paragraph now lists every active spec by status —
shipped / partial / drafted — and adds the transparency-iframe
baseline stub that landed alongside the embed feature.
The embed feature is essentially complete — phases 0-6 are live
on main, Phase 7 hardening shipped alongside Phase 1. Updated
the spec to reflect that:
- Status block flipped from "Nothing in this spec is implemented
yet" to "Shipped (2026-06-01)" with date.
- Every shipped phase gets a ✅ marker on its heading.
- Phase 7 (Hardening + headers) body rewritten to record what
actually shipped (CSP frame-ancestors, SPA rewrites, error
handling, sanitization reuse) plus what's still optional
(?debug=1 surface, hard relay-count cap).
- Phase 8 (Polish) deliberately dropped — the previously-drafted
Credits overlay, postMessage handshake, and explicit
light/dark/auto theming weren't needed for the use cases the
feature is actually solving. Replaced with a clear "dropped"
note listing each item and why.
- Phase 9 (Future) reframed as the natural follow-up arcs if we
revisit (oEmbed endpoint, render-to-image, OG images,
lightweight embed.html bundle).
The Acceptance Criteria for Embed v1 stays valid as-is — every
bullet is true.
Animated pixel-art embeds (frames > 1) now respect three controls
per docs/EXTERNAL_EMBED_FEATURE.md §6.3 / §11.4:
- ?play=1 / ?play=0 — explicit auto-play toggle. If the param
isn't set, autoplay follows the visitor's prefers-reduced-motion
preference: motion-OK users get auto-play, reduced-motion users
get start-paused with a play CTA. ?play=1 forces auto-play even
in reduced-motion mode (the spec's "user opt-in" wording).
- ?fps=N — override frame rate, clamped to 1-60. Falls back to the
payload's stored fps (default 8) when not set.
- A play/pause chip in the embed footer's left side that toggles
on click. Re-renders the artwork with the new autoplay state;
the renderer's RAF self-stops when the canvas leaves the DOM, so
the swap is leak-free.
Renderer changes (renderPixelArtPreviewDOM):
- New opts.autoplay (default true) gates the requestAnimationFrame.
When false, frame 0 is drawn but no animation loop starts.
- New opts.fps (number, optional) overrides pa.fps. Defaults
unchanged for all existing callers (linked-design renderer,
feed cards, modal preview) because they don't pass either opt.
Single-frame pixel art is unaffected — the play/pause chip only
appears for frames.length > 1, and the renderer ignores autoplay
for the still-image path.
Public multi-slide deck embeds get a paginated viewer instead of
the single-thumbnail-with-badge that was hitting before (the
shared renderDeckPreviewDOM compact path).
_paintEmbed now branches on mode === 'deck' && slides > 1 into a
new _paintEmbedDeck that:
- Reads ?slide=N (1-based) from the route params for the initial
index; clamps to [0, slides.length-1].
- Renders the current slide via composeSlideForDeck +
renderDesignPayloadPreview into a .designObjectFitWrap and
fitMiniPreview-scales it.
- Adds prev / counter / next pill chips to the footer left side
(only when slides > 1 and controls=1), and the existing author
chip after them.
- Adds a fullscreen chip ⛶ + the Open-in-Artstr link to the
footer right side.
- Wires keyboard nav on document.keydown:
ArrowRight / PageDown / Space → next
ArrowLeft / PageUp → prev
Home → first; End → last
F → toggle fullscreen
Single handler is swapped via the _paintEmbedDeck._kbd sentinel
so re-renders (e.g., the refresh-error path) don't stack
listeners. Form-element targets (none today, future-proof) are
ignored so the embed doesn't eat typing.
- New _toggleEmbedFullscreen helper calls
documentElement.requestFullscreen() / exitFullscreen with a
graceful catch.
Touch swipe, autoplay (?autoplay / ?loop / ?interval), and
prefers-reduced-motion respect are deferred — they fit naturally
on top of this scaffold whenever we want them.
Both card builders (buildFeedCard + buildResultCard) had a
dedicated "Preview" button on the action row that just called
openDesignPreview(row). The whole card already has a click
handler doing exactly that, so the button was redundant — it
just added visual noise next to the Use/Fork (or premium-unlock)
CTA.
Removed the prevBtn from both builders. Existing card-click
behavior unchanged, so the preview still opens on click; the
action row now has only the reactions + the action button(s)
specific to that card state.
Swapped the embed code generator's live-preview backdrop from
the dev-time bright magenta/yellow checker to the standard
Photoshop-style light-gray/white transparency indicator
(#e5e7eb / #ffffff, 14×14 tiles). Reads as "this is where
transparency shows through" without screaming.
src/transparency-iframe.html is a tiny html+body=transparent
stub we serve at /transparency-iframe.html so dev hosts (and
future debug tools) can include it via iframe to confirm that
cross-origin iframe transparency is working in the target
browser without involving any of the Artstr embed JS.
Validated end-to-end:
- srcdoc iframe → magenta shows through ✓
- cross-origin minimal page → magenta shows through ✓
- cross-origin Artstr embed → magenta shows through the
Computer_Icon's transparent ring ✓
What looked like opaque white on the stress-test host was the
artwork's natural fill + the host's pink/yellow checker reading
as noise rather than see-through. Magenta on a flat backdrop
made the transparency unambiguous.
The generator was emitting /embed/<id> URLs (the canonical clean
path from the spec). Vercel rewrites that to / in production —
but on hosts without SPA rewrites (including local dev with
python http.server, and many static hosts users will paste into
WITHOUT Vercel-style routing), it 404s. The Embed modal's live
preview showed a "404 — File not found" error on localhost.
Switched to the ?embed=<id> query form. Universal: works on any
host that serves the index.html at /, no rewrite dependency.
The published Vercel deploy supports both forms via the existing
rewrites, so the change is backward-compatible for production
consumers.
If anyone wants the clean /embed/<id> form they can hand-edit
the snippet after copying; the embed runtime accepts all three
forms (path, hash, query) on the receive side.
openEmbedCodeDialog set modal.style.display = '' to show the
modal, which falls back to the CSS default `.modal { display:
none }` — so the dialog never appeared. Every other modal in the
app sets `'flex'` explicitly. Matching that pattern.
Also fixes the symptom "Embed button doesn't work / doesn't
copy anything" — the dialog was always present in the DOM but
invisible, so the copy buttons inside it couldn't be reached.
Per docs/EXTERNAL_EMBED_FEATURE.md §13 / §18 Phase 6 — the embed-
code generator now ships alongside Phase 1's viewer so authors
can grab iframe snippets directly from the community preview.
UX:
- New "Embed ↗" button in the preview pane's action row, between
the share-link button and Use/Fork. Hidden for private rows
(embed refuses them anyway); shown for locked-premium rows so
designs can be embedded as watermarked-preview teasers pre-
purchase.
- Click opens #embedCodeModal: a single-screen dialog with
identifier selector, size preset, options checkboxes, live
iframe preview, and the generated iframe HTML in a copy-ready
textarea + Copy URL / Copy iframe code buttons.
Controls:
- Identifier: naddr (latest version, auto-updates) | nevent
(snapshot, frozen to this exact event). naddr is the default
but falls back to nevent when the row has no d-tag.
- Size: responsive 16:9 (recommended) | square 320 / 480 | fixed
640×360 / 800×450 / 960×540 | custom WxH.
- Options: controls / author chip / "Open in Artstr" link /
credits row — each toggled via a query param (controls=0,
attr=0, open=0, credits=1).
The live-preview pane uses a pink/yellow checker background so
transparency in the embedded design shows through visually
(verifies that the iframe is actually transparent before the
user pastes the snippet on their own site).
Copy buttons use navigator.clipboard.writeText with a graceful
fallback toast on permission denial. The URL extracted from the
generated iframe's src=, so URL/iframe stay in sync.
Defensive: also setProperty('background-image', 'none', 'important')
and ('background-color', 'transparent', 'important') on both
documentElement and body. Catches any inherited background-image
that might be painting a pattern instead of a flat color.
Added a console.log('[embed] boot v3', { route }) at the top of
bootEmbedViewer so the user can confirm the new code is reaching
the iframe — if the log doesn't appear in the iframe's dev-tools
console, the browser cache hasn't refreshed yet.
Previous fix set documentElement.style.background = 'transparent'
but didn't beat the global
html, body { background: var(--bg); ... }
rule at the top of the stylesheet. --bg is #e8f4f8 (light cyan,
reads as near-white), so pixel-art transparent pixels were showing
that light cyan through instead of the host page background.
Two fixes layered:
1. CSS rule using :has() so html is targeted only when an
embed-mode body is its descendant:
html:has(body.embed-mode), body.embed-mode {
background: transparent !important;
}
:has() is supported in all current browsers (Chrome 105+,
Safari 15.4+, Firefox 121+). The !important flag beats the
global var(--bg) declaration.
2. Inline override via style.setProperty('background',
'transparent', 'important') on both documentElement and body
at the top of bootEmbedViewer. Inline + !important = highest
specificity possible, so this guarantees transparency even on
browsers/edge cases where :has() doesn't trigger immediately
on dynamic class change.
Net effect: from <html> → <body> → #embedRoot → .embedStage →
.designObjectFitWrap → renderer's pixel-art box → canvas, every
layer is transparent. Host backgrounds (color, image, gradient)
now actually show through transparent pixel-art cells.
Two follow-ups from the size/aspect stress test:
1. Retryable error states (relay query failed, event not found
on any relay) now render a "↻ Refresh" chip below the message.
Click re-runs bootEmbedViewer(route) — same boot path,
re-issues the relay race. Non-retryable errors (private,
premium, malformed identifier, wrong-payload-shape) don't show
the button because retrying wouldn't change the outcome.
_setEmbedStatus now accepts an optional { retry } callback;
only the two relay-failure call sites in bootEmbedViewer pass
it.
2. Pixel art (and any other design with transparent pixels) was
rendering on a white default background because the browser
paints document.documentElement white when nothing overrides
it. body.embed-mode set background:transparent, but the
<html> root was unaffected — leaving a white layer behind the
transparent body.
Fixed by setting document.documentElement.style.background =
'transparent' at the top of bootEmbedViewer. Combined with the
already-transparent body + embedRoot + embedStage chain, the
iframe document is now fully transparent from html down. Host
pages can place the embed over background images / colors and
the unfilled pixel-art cells show the host through.
Host-side defensive: dummy host CSS now explicitly sets
`.frame iframe { background: transparent }`. Modern browsers
default this for transparent-document iframes, but explicit is
safer across browser versions.
The grid swap fixed the squish but introduced the inverse: the
renderer's 720px box stayed at 720px without scaling down to the
iframe viewport. fitMiniPreview was firing, but something in the
grid layout path was preventing the transform: scale() from
shrinking the visible artwork.
Reverted the wrap to the same pattern the existing linked-design
renderer uses for in-app layer previews — flex centering + the
.designObjectFitWrap CSS class, which sets
.designObjectFitWrap > * { flex: 0 0 auto; max-width: none;
max-height: none; transform-origin: center center;
margin: 0 !important; }
flex: 0 0 auto on the direct child explicitly disables both
flex-grow and flex-shrink, so the renderer's fixed 720×720 box
stays at its natural size in layout. fitMiniPreview then reads
naturalW=720, wrapW=iframe-width, and scales uniformly with
correct aspect.
This is the exact pattern that works for linked-design layers in
the editor; the embed inherits the same correctness guarantees.
The embed wrap was using display:flex with align-items+justify-content
to center the rendered design. Flex's default flex-shrink:1 on a
fixed-pixel child (the renderer creates a 720×720 box) shrinks the
box horizontally to fit the wrap width on iframes narrower than
720px.
fitMiniPreview then reads naturalW from the box's inline style
(720) — not the post-flex-shrink computed width — and applies
transform: scale(min(wrapW/720, wrapH/720)). The horizontal axis
ends up scaled twice: once by flex (down to wrap width), then
again by the transform. Result: horizontal squish equal to
(wrapW / 720), visible especially on aspect-ratio:1/1 iframes
hosting square pixel art.
Switched both the public paint wrap and the locked-premium paint
wrap to `display: grid; place-items: center`. Grid centers fixed-
size children without shrinking them, so the box stays 720×720 in
layout. fitMiniPreview's scale calc is then accurate and uniform.
User feedback: the embed frame's white footer band clashes with
host site themes. Refactored so the frame is fully transparent
and every control floats as its own pill chip over the bottom
edge of the stage. Each chip carries a semi-opaque dark
backdrop + blur so it stays readable on any host background
(light, dark, branded).
Style changes:
- .embedFooter is now absolute-positioned, transparent, with
pointer-events: none so the artwork beneath stays interactive
(pixel-art animation, future deck swipe gestures).
- New .embedChip base class for every control:
- rgba(17,24,39,0.7) bg + white text
- 12px backdrop-filter blur for cross-theme legibility
- rounded-pill shape, 1px white-translucent border
- Variants:
- .embedChipUnlock — amber accent for the premium CTA
- .embedChipCounter — slightly lighter, cursor:default
- .embedChipBadge — for the top-right "🔒 PREMIUM" badge
JS changes:
- New _makeAuthorChip(pubkey) helper used by both the public and
premium paint paths.
- _paintEmbed and _paintEmbedLockedPremium drop all inline
color/background overrides — every control gets a chip class
instead.
- The locked-premium prev/next buttons are now plain chips
(were amber-on-amber buttons before, hard to read on dark
artwork). The amber accent only stays on the unlock CTA where
it's a semantic signal.
Status placeholder ("⟳ Loading…", error messages) keeps a soft
white-translucent backdrop so it's visible while there's no
artwork behind it yet.
Smoke-test target: the dummy host page (localhost:8001) now
includes a dark-themed section so chip legibility against dark
backgrounds is verifiable visually.
Per docs/EXTERNAL_EMBED_FEATURE.md §10 / §11.6 / §18 Phase 1+
(promoted from Phase 2 since it's natural to ship alongside the
public render path).
The envelope on a premium event ships an unencrypted `preview`
field:
- watermarked-image: single watermarked JPEG (`preview.dataUrl`).
- watermarked-deck: paginated watermarked slides
(`preview.slides[]`, each { dataUrl, width, height }).
The embed loads the envelope from event.content, branches into a
new `_paintEmbedLockedPremium` paint path, and renders the
preview directly. No relay re-query, no decryption attempt.
UX:
- Stage gets a dark backdrop + the watermarked preview centered.
- A small "🔒 PREMIUM" badge sits top-right of the stage so the
lock is visible without obscuring the artwork.
- Deck previews get prev/next controls in the footer with a
"Slide N of M · K in deck" counter that surfaces the deck's
full slide count (preview ships a capped sample).
- Footer's right side has "🔒 Open in Artstr to unlock ↗" in
amber — the only path to unlock. The iframe never initiates a
zap.
Phase 1's premium-refuse fallback still kicks in for envelopes
that ship without a preview field (legacy / malformed) — same
text-only placeholder as before.
Per docs/EXTERNAL_EMBED_FEATURE.md §18 Phase 1.
- parseEmbedRoute() detects three URL forms so the embed works on
Vercel-rewrite-friendly hosts AND on plain static servers:
/embed/<id> (canonical; needs SPA rewrite)
#/embed/<id> (hash; works on any host)
?embed=<id> (query; works on any host)
- Early-return at the top of init() routes embed mode to
bootEmbedViewer; skips welcome modal, slot/disc/jewel controls,
attachEvents, walletUI, autosave restore, share-route popstate.
Editor JS stays loaded (single bundle), but none of its boot
steps run.
- bootEmbedViewer() decodes the identifier via the existing
decodeNostrId helper (note / nevent / naddr / hex), races the
hint relays then user relays + DEFAULT_NOSTR_RELAYS for the
event, warms linked-design sub-trees in one prefetchBatch
round-trip, then paints via the existing
renderDesignPayloadPreview + fitMiniPreview path.
- Premium events refuse with "🔒 Premium design — open in Artstr
to unlock" placeholder; Phase 2 will render the watermarked
preview JPEG with an inline CTA.
- Private (encrypted) envelopes refuse with a 🔒 placeholder; no
decryption attempted.
- body.embed-mode CSS hides every existing top-level element
(`body.embed-mode > :not(#embedRoot) { display: none !important }`)
and shows a single #embedRoot with a stage + thin footer (author
chip + "Open in Artstr ↗"). attr / open / controls query params
toggle each piece.
- vercel.json gains /embed/:id SPA rewrites and a
Content-Security-Policy: frame-ancestors * header so the route
is iframe-able from any origin. Production behavior; dev (python
http.server) needs no headers — cross-origin framing works by
default.
Manual smoke-test paths:
http://localhost:8000/?embed=<naddr> (query form)
http://localhost:8000/#/embed/<naddr> (hash form)
http://localhost:8001/ (cross-origin
iframe host)
Updated rewrite of the earlier embed plan covering every Artstr
feature shipped since the original sketch:
- Linked sub-design resolution inside embeds (reuses
linkedDesigns.prefetchBatch + resolveLinked + disk cache, full
cycle/depth/byte safety).
- Premium boundary: watermarked preview + "Open in Artstr to
unlock" CTA; no in-iframe zap.
- Private boundary: hard refuse with 🔒 placeholder; no decrypt
attempts.
- Pixel-art animation playback (auto-play, fps override,
prefers-reduced-motion respected).
- Deck slide picker — `?slide=N` deep-links; linked-deck layers
carrying design.slideIndex project to a single-slide payload.
- Credits overlay (opt-in via `?credits=1`), mirroring the
in-app Credits panel.
- PostMessage handshake for parent-page integration (deck
control, fullscreen request, ready/error events).
- Layer-group handling falls out naturally — groups are flat
layers with groupId; the existing renderers already paint them.
- Open Graph metadata on the embed route URL itself.
- Per-event + per-tree byte caps inherited from linked-designs.
- Phase plan + acceptance criteria + risks updated.
No code; this is the planning artifact. Implementation phases
0-9 are scoped inside the doc.
Last Phase 3 polish piece per LINKED_DESIGNS_FEATURE.md §14. The
cold-start path used to fire one parallel queryRelays per linked
layer — a host with 20 distinct linked sources opened 20 sockets
to each relay in the union. Now restoreAutosave issues one
batched relay round-trip via the new linkedDesigns.prefetchBatch.
Mechanics:
1. queryRelays accepts either a single filter object (existing
callers) or an array of filters; arrays spread into the NIP-01
REQ after the sub id (OR semantics). One-line change at the
send site; zero impact on existing call sites.
2. prefetchBatch(specs) skips anything already in the in-memory
cache, inflight map, or disk cache — partial cache hits only
fetch what's missing. Distinct address-coord refs are grouped
by (kind, pubkey) into one filter each (#d set of dTags);
pinned event ids collapse into a single ids-filter. Events
bucket by id (for pinned matches) and by address coord with
latest created_at wins (for ref matches).
3. restoreAutosave's per-spec resolveLinked loop becomes a single
prefetchBatch call. The disk-cache pre-filter inside
prefetchBatch means a reload of a previously-resolved host
pays zero network cost; only newly-linked refs hit the wire.
Per-layer resolveLinked calls in the renderer still work the way
they did — this only changes the bulk warm-up path. Interactive
adds (one new linked layer at a time) keep their single-filter
fast path.
Three bugs in the freshly-shipped extract flow:
1. Group extract baked customArt.background='#ffffff' so the
extracted design lost any transparency the group had. Now
defaults to 'transparent' so the extracted design composites
cleanly into any host. Users can pick a solid fill later via
the customart background control if they want one.
2. Double-clicking a linked layer ran beginDesignObjectEdit
which loads layer.design.payload — but linked layers have no
local payload, just a ref. loadProjectFromText('{}') then
fell back to the default cover/casewrap mode with empty
layers, hence "opens the case wrap editor" and "design is
missing completely."
beginDesignObjectEdit now detects design.kind === 'linked',
pulls the resolved payload from linkedDesigns.peek, and opens
THAT for editing. The edit session is tagged with
{ isLinked, linkedContext } so finishDesignObjectEdit knows
to take the republish path on save instead of mutating
layer.design.payload (which doesn't exist for linked
layers).
3. Guard rails on the linked-edit path:
- Refuse if the resolver hasn't cached the source yet
("Refresh the layer and try again").
- Refuse if the layer is pinned ("Unpin to edit — pinned
versions are frozen").
- Refuse if the source author isn't the current user
("Only the source author can edit; fork or unlink it for
a local copy"). Soft permission — relays decide who can
replace a kind-30078 by pubkey + d-tag, so non-authors
couldn't republish even if we let them try.
On save, _republishLinkedDesignSource:
- Strips linked-design ephemera + builds attribution tags
(same as host publish).
- Publishes a fresh kind-30078 under the same author + d-tag,
which is NIP-33 in-place replace.
- clearCache(key) + seed both resolver caches from the new
signed event so every linked layer on this canvas paints the
updated version on next render.
- Refreshes the layer name from the (possibly edited) payload
title with the 🔗 prefix preserved.
finishDesignObjectEdit is now async; existing call sites are
fire-and-forget which is fine — user feedback flows through
toasts, not the return value.
Extends the per-layer "🔗 Publish + link" pattern to layer groups.
A new 🔗 button sits next to the eye-toggle in each group's
header (layerGroupBlock); clicking it publishes the group as a
single customart-mode design and replaces the group with one
linked layer at the group's bounding box.
Implementation:
- layersBounds() over the group's layers gives the bbox in inches.
- customArt.width/height = bbox in pixels (×96 DPI).
- Each layer is cloned with x/y translated so the group's
top-left becomes (0, 0); target forced to 'canvas'; groupId
stripped. Group can contain mixed layer types (shapes, text,
design objects, images) — customart is the right canvas type
for any of them.
- Strip linked-design ephemera + walk attribution like the
host-publish path so the new event ships proper p / link tags.
- d-tag = "extracted:customart:<slug>:<rand>" to avoid colliding
with the user's regular published designs.
- After publish: remove the original group layers from
state.layers, drop the group entry from state.layerGroups, add
one linked layer at the bbox position with the host's original
target (cover-front / canvas / etc.). The replacement layer's
rotation is 0 — group rotation is intrinsically per-layer.
- linkedDesigns.seed primes both caches from the signed event
so the replacement layer paints instantly.
Confirmation copy warns about publishing under the user's
identity (spec §10.3) and explains the bbox + relative-position
behavior so the conversion isn't surprising.
Mixed-target groups (e.g., one layer on cover-front, one on
cover-back) collapse to a single canvas; this matches user
expectation since "the group" only exists when its members are
selected together as a unit.
thePR0M3TH3AN