/** * @file canvas-lib.tsx — dev-server-bundled canvas library * @scope apps/studio/canvas-lib.tsx * Ships with the dev-server install; resolved at canvas build time * via the `@maude/canvas-lib` virtual specifier. Per DDR-025, this * is the single source of truth — no project-side copy. * @purpose Shared primitives + helpers + hooks for every TSX canvas * (UI mocks + DS specimens). Imported via the virtual module * specifier `@maude/canvas-lib`, which the dev-server's Bun.build * resolver maps to this file. On /design:handoff the used exports * are AST-inlined into the emitted registry-item so the consumer * never sees the `@maude/canvas-lib` specifier. * * Exports (cold-reader cheat sheet): * * Frame envelope ───────────────────────────────────────────────────────── * DesignCanvas Root wrapper.

holding a * transformable

world plane. * DCArtboard children inside the world are absolutely * positioned in world coords; pan/zoom (Phase 4 T2) * applies a single transform to the world plane. * DCSection Group label. Inside DesignCanvas it collapses to a * transparent wrapper (DCArtboard children take their * own world coords); standalone it keeps the legacy *

chrome for specimens. * DCArtboard Bordered artboard with SKU strip header. Inside * DesignCanvas it absolutely-positions itself in world * coords resolved from meta.layout (or default grid). * Standalone it renders a fixed-size block at its given * width/height (specimens / legacy uses). * DCPostIt
— sticky-note annotation. * DrawProof (Phase 25) Renders one vector mark across a size ladder * × {light, dark, single-color flatten} as labeled * DCArtboards — the draw engine's render/verify harness. * * Specimen helpers ─────────────────────────────────────────────────────── * SpecimenHeader The .specimen-hd row (sku + crumbs + ThemeToggle). * SpecimenMeta
ladder from entries[]. * KbdHint chrome. * TokenChip Inline visualiser for a var(--) value. ColorSwatch Square + label for a color token. * TypeScaleRow One row of a type-ladder specimen. * ThemeToggle Light/dark )} {hasVideo ? ( ) : null} {children} {showActivity ? ( ) : null} {/* T4 — world-coord sibling, same reasoning as ArtboardActivityOverlay above: must stay OUTSIDE `.dc-artboard`'s contain:paint/ content-visibility subtree so guides are never culled/frozen with exported content (they're never exported at all). */} ); } DCArtboard.displayName = 'DCArtboard'; // ───────────────────────────────────────────────────────────────────────────── // window.__maudeCanvasRects() — the whiteboard-toolkit geometry manifest hook // (feature-whiteboard-ai-toolkit). `maude design canvas-rects` (a headless // Chromium shim) calls this to get every artboard's + every meaningful // element's WORLD-coordinate rect, so the annotation read/write verbs // (`read-annotations --rects`, `annotate --in/--pin/--board`) never need to // hand-compute a coordinate. Pure DOM + the `liveViewport` mirror above — no // React context needed, so it works from a plain page.evaluate() call with no // regard for which component tree happens to be mounted. // // World-coord conversion mirrors DesignCanvasInner's `activeArtboardId` math // (canvas = translate(vp.x,vp.y) then scale(vp.zoom) applied to `.dc-world`): // worldX = (screenX - hostRect.left - vp.x) / vp.zoom // A `.dc-canvas` host is required (bare DS specimens have no world plane — // this hook is for UI canvases with artboards, so it returns an empty // manifest there rather than guessing). export interface CanvasRectsElement { cdId: string | null; selector: string; index: number; artboard: string | null; x: number; y: number; w: number; h: number; tag: string; text: string; } export interface CanvasRectsManifest { artboards: ArtboardRect[]; elements: CanvasRectsElement[]; elementsTruncated: boolean; } // Comment/annotation/chrome subtrees never make useful annotation targets — // mirrors the pickSpecimenEl chrome denylist (canvas-comment-mount.tsx) plus // the annotation layer's own root. const RECTS_CHROME_SELECTOR = '.cm-composer, .cm-thread, .cm-mention-popup, .cm-pin, [data-mc-hover-halo], [data-mdcc-annotations], .dc-minimap, .dc-zoom-toolbar'; const RECTS_INTERACTIVE_TAGS = new Set([ 'button', 'a', 'input', 'textarea', 'select', 'option', 'label', 'summary', 'img', 'svg', 'video', 'picture', ]); const RECTS_ELEMENT_CAP = 400; /** True when `el` has no `[data-cd-id]` descendant — a "leaf" in the pipeline's * stamped tree, i.e. the finest element the JSX source actually distinguishes * (a text run, an icon, a leaf ``) rather than a structural wrapper. */ function isCdIdLeaf(el: Element): boolean { return el.querySelector('[data-cd-id]') === null; } function elementIsCandidate(el: Element): boolean { const tag = el.tagName.toLowerCase(); if (RECTS_INTERACTIVE_TAGS.has(tag)) return true; if (el.hasAttribute('role') && el.getAttribute('role') === 'button') return true; if (el.hasAttribute('tabindex')) return true; if (!isCdIdLeaf(el)) return false; // structural wrapper — a leaf sibling/descendant covers it return shortText(el, 1).length > 0; } function buildCanvasRectsManifest(): CanvasRectsManifest { const empty: CanvasRectsManifest = { artboards: [], elements: [], elementsTruncated: false }; if (typeof document === 'undefined') return empty; const host = document.querySelector('.dc-canvas') as HTMLElement | null; if (!host) return empty; // bare specimen / no world plane — nothing to resolve against const vp = getLiveViewport() ?? { x: 0, y: 0, zoom: 1 }; const hostRect = host.getBoundingClientRect(); const toWorld = (r: DOMRect): { x: number; y: number; w: number; h: number } => ({ x: (r.left - hostRect.left - vp.x) / vp.zoom, y: (r.top - hostRect.top - vp.y) / vp.zoom, w: r.width / vp.zoom, h: r.height / vp.zoom, }); const artboards: ArtboardRect[] = []; const artboardEls = Array.from(document.querySelectorAll('[data-dc-screen]')); for (const el of artboardEls) { const rect = (el as HTMLElement).getBoundingClientRect(); if (rect.width <= 0 || rect.height <= 0) continue; const id = el.getAttribute('data-dc-screen'); if (!id) continue; // `kind` is part of ArtboardRect and the manifest's consumers (canvas-rects // → the whiteboard toolkit, DDR-151) read it. It was being dropped here — // invisible until A2 put this file under a checker. Same element carries // `data-dc-kind`, always stamped by DCArtboard; 'digital' is its own default. const kindAttr = el.getAttribute('data-dc-kind'); const kind: ArtboardKind = kindAttr === 'print' || kindAttr === 'web' || kindAttr === 'video' ? kindAttr : 'digital'; artboards.push({ id, kind, ...toWorld(rect) }); } const elements: CanvasRectsElement[] = []; let truncated = false; const candidateEls = Array.from(document.querySelectorAll('[data-cd-id]')); for (const el of candidateEls) { if (elements.length >= RECTS_ELEMENT_CAP) { truncated = true; break; } if (el.closest(RECTS_CHROME_SELECTOR)) continue; const artboardEl = el.closest('[data-dc-screen]'); if (!artboardEl) continue; // off-artboard chrome (menubar, panels, toolbars) if (!elementIsCandidate(el)) continue; const rect = (el as HTMLElement).getBoundingClientRect(); if (rect.width <= 0 || rect.height <= 0) continue; const cdId = el.getAttribute('data-cd-id'); const artboardId = artboardEl.getAttribute('data-dc-screen'); const selector = cdId ? scopedCdSelector(cdId, artboardId) : ''; const index = cdId ? selectorIndex(document, selector, el) : 0; elements.push({ cdId, selector, index, artboard: artboardId, ...toWorld(rect), tag: el.tagName.toLowerCase(), text: shortText(el, 120), }); } return { artboards, elements, elementsTruncated: truncated }; } declare global { interface Window { maudeCanvasRects?: () => CanvasRectsManifest; } } if (typeof window !== 'undefined') { window.maudeCanvasRects = buildCanvasRectsManifest; } // ───────────────────────────────────────────────────────────────────────────── // DrawProof (Phase 25) — the render/verify harness for the draw engine. Renders // ONE vector mark across a size ladder × {light, dark, single-color flatten} as // labeled DCArtboards, so a single `maude design screenshot --all-screens` // operationalizes the whole graphic rubric at once: // • per-size legibility (does the 16px instance survive the favicon test?) // • dark-mode correctness (does `currentColor` flip cleanly?) // • the single-color flatten test (pure #000 on #fff — logo must hold) // Reference frames are FIXED (not DS tokens) on purpose: the flatten/legibility // tests must be objective, independent of whichever DS the canvas declares. // Additive export (DDR-025) — no existing canvas-lib surface changes. const DRAW_PROOF_MODES = { light: { bg: '#ffffff', fg: '#111111', label: 'light' }, dark: { bg: '#111111', fg: '#f5f5f5', label: 'dark' }, flatten: { bg: '#ffffff', fg: '#000000', label: 'single-color flatten' }, } as const; export type DrawProofMode = keyof typeof DRAW_PROOF_MODES; /** * Render a single mark across the verification ladder. `mark` is the inline SVG * (the engine's `toJsx` output, dropped in as JSX). Each mode becomes one * labeled DCArtboard (a `--all-screens` target) showing the mark at every size, * so the proof PNGs are `proof-.png`. / export function DrawProof({ mark, name = 'mark', sizes = [16, 24, 48, 256], modes = ['light', 'dark', 'flatten'], }: { mark: ReactNode; name?: string; sizes?: number[]; modes?: DrawProofMode[]; }) { const maxSize = Math.max(...sizes, 64); const cellGap = 32; const padding = 32; const boardWidth = padding 2 + sizes.reduce((acc, s) => acc + Math.max(s, 56), 0) + cellGap * (sizes.length - 1); const boardHeight = padding * 2 + maxSize + 28; return ( {modes.map((mode) => { const m = DRAW_PROOF_MODES[mode]; return ( {sizes.map((s) => ( {mark} {s}px ))} ); })} ); } DrawProof.displayName = 'DrawProof'; // ───────────────────────────────────────────────────────────────────────────── // PhotoLayer (feature-photo-editor, Task 6) — the non-destructive WebGL photo // compositor surface. Renders a source photo (artboard `` or annotation // `ImageStroke`) with a live `PhotoEdit` applied through pixi.js. // // LAZY-BUNDLE GUARANTEE (the plan's load-bearing acceptance criterion + BUILDER's // flagged top risk): an UNEDITED photo (`isDefaultEdit(edit)`) renders as the // plain `` and NEVER touches pixi. The compositor module (photo/pipeline.ts) // is only reached through a DYNAMIC `import()` inside the effect, so a canvas // with zero edited photos pays zero pixi.js/bg-removal cost. Verified empirically // against `buildCanvasModule` (no eager `pixi.js` import in the default-edit // bundle) — see test/photo-canvas-bundle.test.ts. // // A11y: the pixi output is a `