@snowcone-app/canvas 0.1.0

package/dist/kits/types.d.ts

@@ -0,0 +1,129 @@
+import { EditorCapabilities } from '../types/capabilities.js';
+/**
+ * Runtime theme overrides -- maps to CSS custom properties on the root element.
+ * All values are CSS color strings (hex, oklch, hsl, rgb, etc.).
+ *
+ * @example
+ * ```ts
+ * const theme: RuntimeTheme = {
+ *   primary: 'oklch(0.55 0.2 270)',
+ *   background: '#ffffff',
+ * };
+ * ```
+ */
+export interface RuntimeTheme {
+    /** Primary/accent color used for buttons, links, and interactive elements */
+    primary?: string;
+    /** Page background color */
+    background?: string;
+    /** Default text color */
+    foreground?: string;
+    /** Card/panel background color */
+    content1?: string;
+    /** Elevated surface background color */
+    content2?: string;
+    /** Border/divider color */
+    divider?: string;
+    /** Danger/error color for destructive actions */
+    danger?: string;
+    /** Success color for positive feedback */
+    success?: string;
+}
+/**
+ * A complete editor configuration that defines layout, capabilities,
+ * behavior, and styling for a specific use case.
+ *
+ * Three built-in presets are available:
+ * - `COMPACT_CUSTOMIZER` -- Canvas + contextual toolbar, text/image only
+ * - `PRO_STUDIO` -- Full panels, all features, multi-artboard
+ * - `EMBED_ONLY` -- Canvas only, auto-export, no UI chrome
+ *
+ * @example
+ * ```tsx
+ * import { KitRenderer, COMPACT_CUSTOMIZER } from '@snowcone-app/canvas';
+ *
+ * <KitRenderer kit={COMPACT_CUSTOMIZER} />
+ * ```
+ */
+export interface KitDefinition {
+    /**
+     * Kit name for identification and debugging.
+     * Should be a kebab-case string (e.g., 'compact-customizer').
+     */
+    name: string;
+    /**
+     * Layout slot configuration.
+     * Maps named slots to arrays of section IDs that should be rendered
+     * in that position. The KitRenderer resolves section IDs to components
+     * via the section registry.
+     */
+    layout: {
+        /** Maps slot names to arrays of registered section IDs */
+        slots: {
+            /** Sections rendered at the top of the editor (toolbar area) */
+            topbar?: string[];
+            /** Sections rendered on the left side (panels) */
+            left?: string[];
+            /** Sections rendered in the center (main canvas area) */
+            canvas?: string[];
+            /** Sections rendered on the right side (properties panels) */
+            right?: string[];
+            /** Sections rendered at the bottom (status bar area) */
+            bottombar?: string[];
+        };
+    };
+    /**
+     * Editor capabilities (what features are enabled).
+     * Controls which elements, transforms, effects, panels, and tools
+     * are available to the user.
+     */
+    capabilities: EditorCapabilities;
+    /**
+     * Behavioral configuration that controls how the editor responds
+     * to user interactions.
+     */
+    behavior: {
+        /** How the toolbar is displayed: contextual (near selection), fixed, floating, or hidden */
+        toolbar: 'contextual' | 'fixed' | 'floating' | 'none';
+        /** Whether the user can select one or multiple elements */
+        selection: 'single' | 'multi';
+        /** How panels are displayed: sidebar, drawer, overlay, or inline */
+        panelMode: 'sidebar' | 'drawer' | 'overlay' | 'inline';
+        /** What happens when the user clicks empty canvas space */
+        onEmptyClick: 'deselect' | 'add-text' | 'noop';
+        /** Whether to automatically export on every change */
+        autoExport: boolean;
+        /**
+         * Maximum number of elements allowed on a single artboard.
+         * Set to 0 or leave undefined for unlimited.
+         */
+        maxElements?: number;
+    };
+    /**
+     * Visual style configuration that controls the editor's appearance.
+     */
+    style: {
+        /** Theme variant name (e.g., 'dark', 'indigo-light') */
+        theme?: string;
+        /** UI density -- how tightly elements are packed */
+        density?: 'compact' | 'comfortable' | 'spacious';
+        /** Toolbar visual variant */
+        toolbarVariant?: 'pill' | 'flat' | 'minimal';
+        /** Panel visual variant */
+        panelVariant?: 'card' | 'flush' | 'floating';
+    };
+    /**
+     * Default content configuration for new elements.
+     */
+    content?: {
+        /** Default text for new text elements */
+        sampleText?: string;
+        /** Default font family for new text elements */
+        defaultFontFamily?: string;
+    };
+}
+/**
+ * String identifiers for built-in kit presets.
+ * Use with `resolveKit()` to get the full `KitDefinition`.
+ */
+export type KitPresetId = 'compact-customizer' | 'pro-studio' | 'embed-only';

package/dist/kits/validation.d.ts

@@ -0,0 +1,36 @@
+import { KitDefinition } from './types.js';
+/**
+ * Result of validating a {@link KitDefinition}.
+ */
+export interface KitValidationResult {
+    /** Whether the kit is valid (no errors). Warnings do not affect validity. */
+    valid: boolean;
+    /** Fatal configuration errors that would prevent the editor from functioning. */
+    errors: string[];
+    /** Non-fatal issues that may produce unexpected behavior. */
+    warnings: string[];
+}
+/**
+ * Validates a {@link KitDefinition} for consistency and completeness.
+ *
+ * Use this to catch configuration errors before passing a kit to `KitRenderer`.
+ * Errors indicate fatal issues (editor won't work), while warnings indicate
+ * potential misconfigurations that may produce unexpected behavior.
+ *
+ * @param kit - The kit definition to validate.
+ * @returns A {@link KitValidationResult} with errors and warnings.
+ *
+ * @example
+ * ```ts
+ * import { validateKit, COMPACT_CUSTOMIZER } from '@snowcone-app/canvas';
+ *
+ * const result = validateKit(COMPACT_CUSTOMIZER);
+ * if (!result.valid) {
+ *   console.error('Kit errors:', result.errors);
+ * }
+ * if (result.warnings.length > 0) {
+ *   console.warn('Kit warnings:', result.warnings);
+ * }
+ * ```
+ */
+export declare function validateKit(kit: KitDefinition): KitValidationResult;

package/dist/lib/utils.d.ts

@@ -0,0 +1,2 @@
+import { ClassValue } from 'clsx';
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/plugins/ElementTypePlugin.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ElementTypePlugin - Plugin API for registering custom element types
+ *
+ * Allows external developers to add new element types without modifying
+ * core canvas files. Custom types integrate with the transform registry
+ * so that GroupElement reconstruction, ElementFactory, and all other
+ * registry consumers work seamlessly.
+ *
+ * @example
+ * ```typescript
+ * import { registerElementType } from '@snowcone-app/canvas/advanced';
+ *
+ * registerElementType({
+ *   type: 'custom-shape',
+ *   Component: CustomShapeElement,
+ *   label: 'Custom Shape',
+ *   icon: 'lucide:shapes',
+ *   category: 'custom',
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Registration descriptor for a custom element type.
+ */
+export interface ElementTypeRegistration {
+    /** Unique type identifier (must not conflict with built-in types) */
+    type: string;
+    /**
+     * Element class constructor.
+     * Must accept a config object and produce a valid element instance
+     * (i.e., something that extends BaseElement).
+     */
+    Component: new (config: any) => any;
+    /** Display label for UI (e.g., "Custom Shape") */
+    label: string;
+    /** Icon identifier in Iconify format (e.g., "lucide:shapes") */
+    icon?: string;
+    /** Category for grouping in the add-element menu */
+    category?: 'text' | 'image' | 'shape' | 'custom';
+    /** Default config for new elements of this type */
+    defaultConfig?: Record<string, unknown>;
+}
+/**
+ * Register a custom element type.
+ *
+ * - Validates the registration (type must be non-empty, Component must be a constructor)
+ * - Prevents conflicts with built-in types and duplicate registrations
+ * - Adds the type to the transform registry so GroupElement, ElementFactory,
+ *   and other registry consumers recognize it
+ *
+ * @param registration - The element type registration descriptor
+ * @throws Error if type conflicts with a built-in type
+ * @throws Error if type is already registered as a custom type
+ * @throws Error if registration is invalid (missing type/Component/label)
+ */
+export declare function registerElementType(registration: ElementTypeRegistration): void;
+/**
+ * Unregister a custom element type.
+ *
+ * Removes the type from both the plugin registry and the transform registry.
+ * Built-in types cannot be unregistered.
+ *
+ * @param type - The type identifier to unregister
+ * @throws Error if attempting to unregister a built-in type
+ */
+export declare function unregisterElementType(type: string): void;
+/**
+ * Get all registered custom element types.
+ *
+ * Returns only plugin-registered types, not built-in types.
+ * The returned array is a snapshot; mutations do not affect the registry.
+ *
+ * @returns Array of ElementTypeRegistration descriptors
+ */
+export declare function getCustomElementTypes(): ElementTypeRegistration[];
+/**
+ * Check if a type identifier is registered (built-in or custom).
+ *
+ * @param type - The type identifier to check
+ * @returns true if the type exists in the transform registry
+ */
+export declare function isRegisteredElementType(type: string): boolean;
+/**
+ * Reset all custom element type registrations (for testing only).
+ * Also resets the underlying dynamic transforms in the registry.
+ * @internal
+ */
+export declare function _resetCustomElementTypes(): void;

package/dist/presets/artboard-color-presets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Artboard Color Presets
+ * A curated set of 10 background colors for artboards
+ */
+export interface ArtboardColor {
+    id: string;
+    name: string;
+    color: string;
+}
+/**
+ * Artboard color presets
+ * Includes a variety of colors for different design needs
+ */
+export declare const ARTBOARD_COLORS: ArtboardColor[];
+/**
+ * Get a random artboard color
+ */
+export declare function getRandomArtboardColor(): string;
+/**
+ * Find artboard color by hex value
+ */
+export declare function findArtboardColor(hexColor: string): ArtboardColor | undefined;

package/dist/presets/tshirt-presets.d.ts

@@ -0,0 +1,60 @@
+/**
+ * T-Shirt Color Presets
+ * Comprehensive color library for previewing designs on different shirt colors
+ * Used for background preview system (PREVIEW ONLY - never exported)
+ */
+export interface TShirtColor {
+    id: string;
+    name: string;
+    color: string;
+    category: 'basic' | 'vibrant' | 'pastel' | 'dark' | 'heather' | 'neon';
+    isPopular?: boolean;
+}
+/**
+ * Complete t-shirt color library
+ * Organized by category for easy browsing
+ */
+export declare const TSHIRT_COLORS: TShirtColor[];
+/**
+ * Get popular colors (most commonly used)
+ */
+export declare function getPopularColors(): TShirtColor[];
+/**
+ * Get colors by category
+ */
+export declare function getColorsByCategory(category: TShirtColor['category']): TShirtColor[];
+/**
+ * Get color by ID
+ */
+export declare function getColorById(id: string): TShirtColor | undefined;
+/**
+ * Get all categories
+ */
+export declare function getAllCategories(): TShirtColor['category'][];
+/**
+ * Get category display name
+ */
+export declare function getCategoryName(category: TShirtColor['category']): string;
+/**
+ * Get color contrast for text visibility
+ * Returns 'light' or 'dark' based on background color
+ */
+export declare function getColorContrast(hexColor: string): 'light' | 'dark';
+/**
+ * Get recommended knockout elements for color
+ * Some colors work better with specific knockout configurations
+ */
+export declare function getRecommendedKnockout(colorId: string): {
+    useKnockout: boolean;
+    strokeKnockout: boolean;
+    fillKnockout: boolean;
+};
+/**
+ * Default preview color (transparent/none)
+ */
+export declare const NO_PREVIEW_COLOR: TShirtColor;
+/**
+ * Get default preview color
+ * Returns the first popular color or black
+ */
+export declare function getDefaultPreviewColor(): TShirtColor;

package/dist/rendering/CompositingRenderer.d.ts

@@ -0,0 +1,33 @@
+import { AnyElementConfig } from '../types/index.js';
+/** Supported composite operations */
+export type CompositeOp = 'destination-out' | 'destination-in';
+/**
+ * Render element with compositing (knockout or clip)
+ * This is the main entry point for compositing rendering
+ */
+export declare function renderWithCompositing(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, compositingElement: AnyElementConfig, allElements: AnyElementConfig[], renderElementFn: (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: AnyElementConfig) => void, artboardBackgroundColor?: string, artboard?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, compositeOp?: CompositeOp): void;
+/**
+ * Render element with knockout compositing (destination-out)
+ * Convenience wrapper — backward-compatible entry point
+ */
+export declare function renderWithKnockout(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, knockoutElement: AnyElementConfig, allElements: AnyElementConfig[], renderElementFn: (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: AnyElementConfig) => void, artboardBackgroundColor?: string, artboard?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): void;
+/**
+ * Render element with clip compositing (destination-in)
+ * Keeps only content within the element shape
+ */
+export declare function renderWithClip(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, clipElement: AnyElementConfig, allElements: AnyElementConfig[], renderElementFn: (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: AnyElementConfig) => void, artboardBackgroundColor?: string, artboard?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): void;

package/dist/rendering/DistressTextureRenderer.d.ts

@@ -0,0 +1,39 @@
+import { ArtboardDistressTexture, DistressEffect } from '../types/index.js';
+type ContextLike = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/**
+ * Apply artboard-level distress texture.
+ *
+ * Only knocks out element pixels — the artboard background stays solid.
+ *
+ * Algorithm:
+ * 1. Copy the current artboard region (background + elements) to an offscreen canvas
+ * 2. Draw the alpha mask with `destination-out` to knock holes in everything
+ * 3. Clear the artboard region on the main canvas
+ * 4. Redraw the artboard background color (fills the holes that were in the bg)
+ * 5. Draw the distressed result on top (element holes reveal the fresh background)
+ */
+export declare function applyArtboardDistressTexture(ctx: ContextLike, config: ArtboardDistressTexture, artboard: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, artboardBackgroundColor?: string): void;
+/**
+ * Apply per-element distress texture using `destination-out` compositing.
+ *
+ * Called within the element rendering pipeline when an element has
+ * `distressEffect.style === 'custom'` and a `textureUrl`.
+ *
+ * Works by:
+ * 1. Creating an offscreen canvas
+ * 2. Rendering the element content via the provided renderFn
+ * 3. Drawing the alpha mask with `destination-out` + intensity
+ * 4. Drawing the composited result back to the main canvas
+ */
+export declare function applyElementDistressTexture(ctx: ContextLike, distress: DistressEffect, elementBounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, renderFn: (offCtx: ContextLike) => void): void;
+export {};

package/dist/rendering/ElementRenderUtils.d.ts

@@ -0,0 +1,17 @@
+import { AnyElementConfig, RenderingContext } from '../types/index.js';
+/**
+ * Rendering mode options
+ */
+export type RenderMode = 'fill' | 'stroke' | 'both';
+/**
+ * Options for element rendering
+ */
+export interface ElementRenderOptions {
+    mode?: RenderMode;
+    renderingContext?: RenderingContext;
+    loadedImage?: HTMLImageElement;
+}
+/**
+ * Main dispatcher: Render any element type based on its transformType
+ */
+export declare function renderElement(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: AnyElementConfig, options?: ElementRenderOptions): void;

package/dist/rendering/MaskRenderer.d.ts

@@ -0,0 +1,41 @@
+import { AnyElementConfig, ArtboardImageMask } from '../types/index.js';
+/**
+ * Register a pre-loaded ImageBitmap for a mask image URL.
+ * Call from the export worker after fetching mask images.
+ */
+export declare function registerMaskBitmap(imageUrl: string, bitmap: ImageBitmap): void;
+/**
+ * Clear all registered mask bitmaps (call after export completes).
+ */
+export declare function clearMaskBitmaps(): void;
+/**
+ * Clear mask cache for an element (call when element or masks change)
+ */
+export declare function invalidateMaskCache(elementId: string): void;
+/**
+ * Clear entire mask cache
+ */
+export declare function clearMaskCache(): void;
+/**
+ * Render element with masks applied
+ * This is the main entry point for masked rendering
+ */
+export declare function renderWithMasks(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: AnyElementConfig, renderFn: (ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D) => void): void;
+/**
+ * Apply artboard-level image mask.
+ *
+ * Same algorithm as applyArtboardDistressTexture in DistressTextureRenderer.ts:
+ * only masks element pixels — artboard background stays solid.
+ *
+ * Algorithm:
+ * 1. Copy the artboard region to an offscreen canvas
+ * 2. Load mask image from ImageCache
+ * 3. Apply composite op based on maskType + inverted
+ * 4. Clear + redraw background + draw masked result
+ */
+export declare function applyArtboardImageMask(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, config: ArtboardImageMask, artboard: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, artboardBackgroundColor?: string): void;

package/dist/rendering/PieceGuideRenderer.d.ts

@@ -0,0 +1,177 @@
+import { PieceGuide, SvgPath, ZoneShape, GuideLabel } from '../components/VisualGuideOverlay.js';
+export type { PieceGuide, SvgPath, ZoneShape, GuideLabel };
+/** Minimum piece info the renderer needs. Matches the ADR-0054 backend shape. */
+export interface PieceGuideRendererPiece {
+    /** Stable piece id (matches placements[].name and pieceGuides keys). */
+    id: string;
+    /** Piece's top-left position in artboard pixel coords. */
+    x: number;
+    y: number;
+    /** Piece-local dimensions in px. */
+    width: number;
+    height: number;
+    /**
+     * Fallback safe-area inset (piece-local px) when no authored
+     * `pieceGuide.safeArea` is present. Used only if the caller wants the
+     * legacy centered-inset fallback; otherwise omit.
+     */
+    safeAreaInsetPx?: number;
+    /** Clockwise rotation in degrees about the piece center. Default 0. */
+    rotation?: number;
+}
+export interface PieceGuideRendererStyle {
+    /**
+     * Bleed-ring rendering mode. Default `'gradient'` (the original
+     * Apple-style vignette: opaque fill softly fading into the design
+     * canvas via a blurred destination-out knockout).
+     *
+     * `'solid'` draws a flat uniform fill over `pieceRect ∖ boundary` at
+     * `bleedOpacity`. Useful when the vignette's soft inner edge reads as
+     * visual noise against the artwork — e.g. photographic designs where
+     * a clean sharp bleed edge is preferred.
+     */
+    bleedMode?: 'gradient' | 'solid';
+    /**
+     * Which shape the bleed ring rings around. Default `'boundary'` (the
+     * design-canvas edge — the current behaviour). `'safeArea'` pulls the
+     * inner edge inwards to the safe-area shape, so the fade starts from
+     * the text-safe zone outward and the region between safe area and
+     * boundary is covered too. Falls back to `'boundary'` if the piece
+     * has no safeArea authored.
+     */
+    bleedInnerEdge?: 'boundary' | 'safeArea';
+    /** Bleed-ring fill colour. Defaults to #333. */
+    bleedFill?: string;
+    /**
+     * Bleed-ring opacity (0–1). Default 1.0.
+     *
+     * Must be 1.0 whenever the main canvas does any per-boundary
+     * clipping. Translucent overlays combined with sharp underlying
+     * clips produce a visible "halo then jump" at the boundary instead
+     * of a smooth vignette — see the rendering contract in this file's
+     * header. If you lower this, the bleed band will read as a tinted
+     * wash instead of a solid frame.
+     */
+    bleedOpacity?: number;
+    /**
+     * Die-cut rendering mode.
+     *
+     * - `'blur-tint'` (default) — the current behaviour. The zone's
+     *   artwork is blurred and a dark tint composites on top so the
+     *   punched hole reads as a "window" onto the product underneath.
+     * - `'knockout'` — the zone's pixels are cleared from the canvas
+     *   with `destination-out` compositing. Whatever's drawn *beneath*
+     *   the canvas element (page background, a product mockup layered
+     *   underneath, etc.) shows through. Useful when the canvas sits
+     *   on top of a real product mockup and you want the hole to be
+     *   honestly transparent.
+     */
+    dieCutMode?: 'blur-tint' | 'knockout';
+    /** Die-cut tint colour. Defaults to --color-bg-tertiary. Only used in `'blur-tint'` mode. */
+    dieCutTint?: string;
+    /** Alpha applied to the die-cut tint (0–1). Default 0.7 (matches old overlay). */
+    dieCutTintAlpha?: number;
+    /** Gaussian blur radius (CSS pixels) applied to bleed + die-cut content. Default 4. */
+    dieCutBlurPx?: number;
+    /**
+     * Die-cut outline stroke colour. Empty string (default) disables the
+     * stroke — matches the canvas renderer's historical behaviour. Set
+     * to e.g. `'#ffffff'` to get a thin rim around the punched hole.
+     */
+    dieCutStroke?: string;
+    /** Die-cut outline stroke width (CSS pixels). Default 1. */
+    dieCutStrokeWidthPx?: number;
+    /** Extra blur radius (CSS pixels) for the bleed ring only. Scales with artboard size. */
+    bleedBlurScale?: number;
+    /** Boundary outline stroke colour. Empty string disables (default). */
+    boundaryStroke?: string;
+    boundaryStrokeWidthPx?: number;
+    /** Legacy dashed safe-area outline. Empty string disables (default). */
+    safeAreaStroke?: string;
+    safeAreaStrokeWidthPx?: number;
+    safeAreaDashPx?: [number, number];
+    /** Per-kind zone fill colours (rgba). */
+    zoneFill?: Partial<Record<ZoneShape['kind'], string>>;
+    /** Per-kind zone stroke colours. */
+    zoneStroke?: Partial<Record<ZoneShape['kind'], string>>;
+    /** Label text + halo style. */
+    labelColor?: string;
+    labelFontSizePx?: number;
+    labelFontFamily?: string;
+    labelHaloColor?: string;
+}
+export interface PieceGuideVisibility {
+    bleed?: boolean;
+    zones?: boolean;
+    boundary?: boolean;
+    safeArea?: boolean;
+    labels?: boolean;
+}
+export interface PieceGuideRenderParams {
+    ctx: CanvasRenderingContext2D;
+    /**
+     * The artboard-local origin (in world pixels). The render loop has
+     * already applied DPR/zoom/padding transforms, so shape coordinates
+     * can be used directly after `ctx.translate(artboard.x + piece.x, ...)`
+     * — artboardOrigin is just where the artboard itself starts in world
+     * space (typically the active artboard's (x, y)).
+     */
+    artboardOrigin: {
+        x: number;
+        y: number;
+    };
+    artboardWidth: number;
+    artboardHeight: number;
+    pieces: PieceGuideRendererPiece[];
+    pieceGuides?: Record<string, PieceGuide>;
+    show?: PieceGuideVisibility;
+    style?: PieceGuideRendererStyle;
+    /** Canvas CSS pixels per world pixel (from useCanvasLayout). */
+    zoom: number;
+    /**
+     * True while an element is selected, hovered, dragged, or otherwise
+     * being manipulated. When set, die-cut zones in `dieCutMode:
+     * 'knockout'` skip the `destination-out` fill that erases pixels
+     * inside the cut shape — the stroke / outline still renders, but
+     * underlying artwork (and any selection chrome the element drew
+     * during its own render pass) stays visible. This mirrors the
+     * rounded-outer-corner behaviour: idle reads as a hard knockout to
+     * the page chrome below, but during interaction the user sees what
+     * sits beneath the cutout so resize/drag feedback isn't suddenly
+     * "punched out". Idle behaviour (false / undefined) is unchanged.
+     */
+    interacting?: boolean;
+    /**
+     * ADR-0060: id of the piece currently in focus. When set, ONLY that
+     * piece's guide chrome (boundary, safe area, bleed ring, die-cut
+     * zones, labels) is drawn — every other piece is skipped entirely.
+     * The companion narrowing in `useCanvasRenderLoop` filters the
+     * artboard's `composite-path` clip to the focused piece's
+     * silhouette so element rendering only paints inside that piece
+     * either; neighbour artwork and chrome are completely hidden.
+     * When `null` / `undefined` every piece renders (spread mode).
+     *
+     * Earlier this dimmed neighbours to ≈0.3 alpha for "structural
+     * context", but the current UX preference is to fully hide them
+     * when focused — the focus picker is the affordance to switch back
+     * to spread, neighbour pieces don't need to leak through.
+     */
+    focusedPieceId?: string | null;
+}
+/**
+ * Quick "is this ink dark / light" check used to decide whether to
+ * flip an author-supplied colour for the current theme. We only
+ * need to handle hex literals (`#rgb`, `#rrggbb`) and `rgb(...)` —
+ * the formats Loom emits. CSS colour names / `hsl()` would fall
+ * through to "neither" and skip the flip, which is the safe choice
+ * (no surprising visual change for unfamiliar inputs).
+ *
+ * @internal — exposed for tests; not part of the package's public
+ * API. Don't import these from outside the canvas package.
+ */
+export declare function isInkDark(css: string): boolean;
+/** @internal */
+export declare function isInkLight(css: string): boolean;
+/** @internal */
+export declare function inkLuminance(css: string): number | null;
+export declare function renderPieceGuides(params: PieceGuideRenderParams): void;

package/dist/rendering/StrokeRenderer.d.ts

@@ -0,0 +1,24 @@
+import { StrokeConfig, AnyElementConfig, ImageElementConfig, RenderingContext } from '../types/index.js';
+/**
+ * Apply stroke style to canvas context
+ */
+export declare function applyStrokeStyle(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, stroke: StrokeConfig): void;
+/**
+ * Render stroke for text element
+ * Uses ctx.strokeText() for proper text outline stroking
+ * Now supports text wrapping for CustomTransform elements
+ *
+ * When stroke.opacity < 1, renders the entire stroke to a temporary canvas at
+ * full opacity, then composites that layer onto the main canvas at the desired
+ * opacity. This prevents darkening where adjacent characters' strokes overlap.
+ */
+export declare function renderTextStroke(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: AnyElementConfig, renderingContext?: RenderingContext): void;
+/**
+ * Render stroke for image element
+ */
+export declare function renderImageStroke(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, element: ImageElementConfig, renderingContext?: RenderingContext): void;
+/**
+ * Render stroke for arbitrary path
+ * Used for custom shapes and transforms
+ */
+export declare function renderPathStroke(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, stroke: StrokeConfig, pathFn: () => void): void;