@inkra/react 0.3.0 → 0.5.0

package/dist/input-number/index.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useInkraLocale } from '../i18n/index.js';
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from 'react';
 import { useBrowserLayoutEffect } from '../internal/useBrowserLayoutEffect.js';
 import { Button } from '../Button.js';
@@ -13,7 +14,9 @@ const minusPaths = [{ d: 'M5 12h14' }];
 const finiteValue = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
 const format = (value) => String(finiteValue(value) ?? '');
 const numberFromDraft = (draft) => draft === '' ? null : finiteValue(Number(draft));
-export const InputNumber = forwardRef(function InputNumber({ classNames, controls = true, decrementButtonLabel = 'Decrease value', defaultValue, disabled, incrementButtonLabel = 'Increase value', inputMode = 'decimal', max, min, onChange, onBlur, onKeyDown, onValueChange, pressAndHold = true, readOnly, repeatDelay = 400, repeatInterval = 80, size = 'md', step = 1, stepModifiers, textAlign = 'center', value, ...props }, forwardedRef) {
+export const InputNumber = forwardRef(function InputNumber(inkraProps, forwardedRef) {
+    const { t } = useInkraLocale();
+    const { classNames, controls = true, decrementButtonLabel = t('inputNumber.decrease'), defaultValue, disabled, incrementButtonLabel = t('inputNumber.increase'), inputMode = 'decimal', max, min, onChange, onBlur, onKeyDown, onValueChange, pressAndHold = true, readOnly, repeatDelay = 400, repeatInterval = 80, size = 'md', step = 1, stepModifiers, textAlign = 'center', value, ...props } = inkraProps;
     const inputRef = useRef(null);
     const isControlled = value !== undefined;
     const [draft, setDraft] = useState(() => format(isControlled ? value : defaultValue));
@@ -25,9 +28,12 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
     const holdRef = useRef(null);
     const timerRef = useRef(undefined);
     const suppressClickRef = useRef(false);
+    const removeHoldListeners = useRef(undefined);
     const stopHolding = useCallback(() => {
         clearTimeout(timerRef.current);
         timerRef.current = undefined;
+        removeHoldListeners.current?.();
+        removeHoldListeners.current = undefined;
         const hold = holdRef.current;
         holdRef.current = null;
         if (hold?.button.hasPointerCapture?.(hold.pointerId)) {
@@ -37,7 +43,8 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
             catch { /* The pointer may already be inactive. */ }
         }
     }, []);
-    useEffect(() => {
+    // Idle controls do not need global pointer, keyboard or visibility listeners.
+    const listenWhileHolding = () => {
         const onVisibilityChange = () => { if (document.hidden)
             stopHolding(); };
         const onPointerEnd = (event) => {
@@ -56,8 +63,7 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
         window.addEventListener('keydown', updateModifiers);
         window.addEventListener('keyup', updateModifiers);
         document.addEventListener('visibilitychange', onVisibilityChange);
-        return () => {
-            stopHolding();
+        removeHoldListeners.current = () => {
             window.removeEventListener('blur', stopHolding);
             window.removeEventListener('pointerup', onPointerEnd);
             window.removeEventListener('pointercancel', onPointerEnd);
@@ -65,7 +71,8 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
             window.removeEventListener('keyup', updateModifiers);
             document.removeEventListener('visibilitychange', onVisibilityChange);
         };
-    }, [stopHolding]);
+    };
+    useEffect(() => stopHolding, [stopHolding]);
     useBrowserLayoutEffect(() => {
         if (isControlled && currentValue !== finiteValue(value))
             setDraft(format(value));
@@ -136,6 +143,7 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
         if (!button.isConnected || button.disabled)
             return;
         holdRef.current = { button, pointerId: event.pointerId, direction, modifiers };
+        listenWhileHolding();
         try {
             button.setPointerCapture(event.pointerId);
         }

package/dist/internal/cache.d.ts

@@ -9,6 +9,10 @@ export declare class BoundedCache<Value> {
     set(key: string, value: Value, cost: number): Value;
     delete(key: string): void;
 }
+export declare function boundedCanvasSize(width: number, height: number, dpr: number): {
+    width: number;
+    height: number;
+};
 export declare function canvasByteCost(canvas: HTMLCanvasElement): number;
 export declare function canvasIsUsable(canvas: HTMLCanvasElement): boolean;
 export declare function effectiveDpr(limit?: number): number;

package/dist/internal/cache.js

@@ -15,6 +15,12 @@ export class BoundedCache {
         return entry.value;
     }
     set(key, value, cost) {
+        // A one-off oversized image must not flush every useful cached control.
+        // Invalid accounting must never disable the byte budget (NaN) either.
+        if (!Number.isFinite(cost) || cost < 0 || cost > this.maxCost || this.maxEntries < 1) {
+            this.delete(key);
+            return value;
+        }
         const previous = this.entries.get(key);
         if (previous) {
             this.totalCost -= previous.cost;
@@ -24,7 +30,7 @@ export class BoundedCache {
         this.totalCost += cost;
         while (this.entries.size > this.maxEntries || this.totalCost > this.maxCost) {
             const oldestKey = this.entries.keys().next().value;
-            if (!oldestKey)
+            if (oldestKey === undefined)
                 break;
             const oldest = this.entries.get(oldestKey);
             this.entries.delete(oldestKey);
@@ -40,6 +46,17 @@ export class BoundedCache {
         this.totalCost -= entry.cost;
     }
 }
+// Cache limits apply after drawing. Check allocation limits before asking the
+// browser for a backing store, including transient canvases that are not cached.
+export function boundedCanvasSize(width, height, dpr) {
+    const pixelWidth = Math.ceil(width * dpr);
+    const pixelHeight = Math.ceil(height * dpr);
+    if (![width, height, dpr].every(value => Number.isFinite(value) && value > 0)
+        || pixelWidth > 8192 || pixelHeight > 8192 || pixelWidth * pixelHeight > 4 * 1024 * 1024) {
+        throw new RangeError('Pencil canvas exceeds the bounded pixel budget');
+    }
+    return { width: pixelWidth, height: pixelHeight };
+}
 export function canvasByteCost(canvas) {
     return canvas.width * canvas.height * 4;
 }

package/dist/internal/iconGeometry.d.ts

@@ -0,0 +1,2 @@
+import type { PencilPoint } from './stroke.js';
+export declare function cachedPathParts(data: string): readonly PencilPoint[][];

package/dist/internal/iconGeometry.js

@@ -0,0 +1,32 @@
+import { BoundedCache, PENCIL_RENDERER_VERSION } from './cache.js';
+const geometryCache = new BoundedCache(256, 180000);
+export function cachedPathParts(data) {
+    // Limit both parsing input and samples before allocating. Cache eviction only
+    // bounds retained geometry, not the work needed to construct a huge path.
+    if (data.length > 65536)
+        throw new RangeError('Pencil icon path exceeds the bounded input');
+    const key = `${PENCIL_RENDERER_VERSION}:${data}`;
+    const cached = geometryCache.get(key);
+    if (cached)
+        return cached;
+    const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+    path.setAttribute('d', data);
+    const length = path.getTotalLength();
+    const count = Math.max(1, Math.ceil(length / 0.25));
+    if (!Number.isFinite(length) || length < 0 || count > 16384) {
+        throw new RangeError('Pencil icon path exceeds the bounded sampling budget');
+    }
+    const parts = [[]];
+    for (let index = 0; index <= count; index += 1) {
+        const point = path.getPointAtLength(length * index / count);
+        if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) {
+            throw new RangeError('Pencil icon path contains invalid coordinates');
+        }
+        const activePart = parts[parts.length - 1];
+        const previous = activePart[activePart.length - 1];
+        if (previous && Math.hypot(point.x - previous[0], point.y - previous[1]) > 0.5)
+            parts.push([]);
+        parts[parts.length - 1].push([point.x, point.y]);
+    }
+    return geometryCache.set(key, parts, parts.reduce((total, part) => total + part.length, 0));
+}

package/dist/internal/renderTokens.d.ts

@@ -1,5 +1,9 @@
 export declare const pencilRenderDefaults: Readonly<{
     strokeWidth: 2;
+    iconStrokeWidth: 1.5;
+    iconBreaks: 0.18;
+    iconBreakCount: 1;
+    iconPressureVariation: 0.82;
     strokeRoughness: 1.5;
     washStrength: 0.8;
     washSpacing: 2;

package/dist/internal/renderTokens.js

@@ -1,5 +1,9 @@
 export const pencilRenderDefaults = Object.freeze({
     strokeWidth: 2,
+    iconStrokeWidth: 1.5,
+    iconBreaks: 0.18,
+    iconBreakCount: 1,
+    iconPressureVariation: 0.82,
     strokeRoughness: 1.5,
     washStrength: 0.8,
     washSpacing: 2,

package/dist/internal/stroke.d.ts

@@ -2,6 +2,12 @@ export type PencilPoint = readonly [x: number, y: number];
 export interface StrokeSettings {
     variation?: number;
     breaks?: number;
+    continuousBreaks?: boolean;
+    /** Maximum gaps per path; short paths reduce the actual count. */
+    breakCount?: number;
+    /** Display pixels per path unit, excluding device pixel ratio. */
+    breakScale?: number;
+    fitPressure?: boolean;
     grain?: number;
     taperLength?: number;
     scale?: number;
@@ -20,5 +26,6 @@ export declare function strokeProfile(at: number, total: number, seed: number, s
     contact: number;
     deposit: number;
     taper: number;
+    gapDistance: number;
 };
 export declare function pencilStroke(context: CanvasRenderingContext2D, points: readonly PencilPoint[], color: string, width: number, seed: number, amplitude: number, passes?: number, closed?: boolean, settings?: StrokeSettings): void;

package/dist/internal/stroke.js

@@ -14,14 +14,52 @@ export function strokeProfile(at, total, seed, settings = {}) {
     const variation = settings.variation ?? 1;
     const breaks = settings.breaks ?? 0.8;
     const grainValue = settings.grain ?? 0.7;
-    const force = clamp(0.12 + noise(at / 19, seed + 17) * 0.97
+    let force = clamp(0.12 + noise(at / 19, seed + 17) * 0.97
         + (noise(at / 5.3, seed + 39) - 0.5) * 0.3);
+    if (settings.fitPressure && total > 0 && total < 48) {
+        // Short icon paths need a full pressure gesture, not a nearly flat slice
+        // of the long-stroke noise. Blend back to the original profile by 48 units.
+        const phase = (at / total + hash(0, seed + 61)) * Math.PI * 2;
+        const gesture = 0.25 + (1 - Math.cos(phase)) * 0.35
+            + (noise(at / 5.3, seed + 39) - 0.5) * 0.08;
+        const blend = clamp((48 - total) / 24);
+        force = force * (1 - blend) + gesture * blend;
+    }
     const pressure = clamp(0.72 * (1 - variation) + force * variation);
     let contact = 1;
-    const cell = Math.floor(at / 37);
-    for (let index = cell - 1; index <= cell + 1; index += 1) {
-        if (hash(index, seed + 277) > breaks * 0.9)
+    let gapDistance = Infinity;
+    // Reserve at least 12 CSS pixels per gap, measured over the full path.
+    // Display size affects density, but device pixel ratio must not affect it.
+    const breakScale = Number.isFinite(settings.breakScale) && settings.breakScale > 0 ? settings.breakScale : 1;
+    const gapCount = Number.isFinite(settings.breakCount)
+        ? Math.max(0, Math.min(12, Math.floor(settings.breakCount), Math.floor(total * breakScale / 12)))
+        : undefined;
+    const gapSpacing = settings.continuousBreaks
+        ? gapCount ? total / gapCount : Math.min(37, Math.max(1, total))
+        : 37;
+    const cell = Math.floor(at / gapSpacing);
+    // A fixed iteration count also terminates for out-of-range numeric input.
+    for (let offset = -1; offset <= 1; offset += 1) {
+        const index = cell + offset;
+        if (!settings.continuousBreaks && hash(index, seed + 277) > breaks * 0.9)
+            continue;
+        if (settings.continuousBreaks) {
+            if (gapCount !== undefined && (index < 0 || index >= gapCount))
+                continue;
+            const amount = clamp(breaks);
+            if (!amount)
+                continue;
+            // Fixed locations with linearly growing gap and feather widths avoid
+            // switching an entire gap on when a slider crosses a random threshold.
+            const middle = gapSpacing * (index + (gapCount === undefined
+                ? 0.2 + hash(index, seed + 283) * 0.6
+                : 0.3 + hash(index, seed + 283) * 0.4));
+            const gapScale = Math.min(1, gapSpacing / 24);
+            const halfGap = (1.1 + hash(index, seed + 293) * 3.6) * amount * gapScale;
+            gapDistance = Math.min(gapDistance, Math.abs(at - middle) - halfGap - 2.1 * amount * gapScale);
+            contact = Math.min(contact, clamp((Math.abs(at - middle) - halfGap) / (2.1 * amount * gapScale)));
             continue;
+        }
         const middle = index * 37 + 5 + hash(index, seed + 283) * 27;
         const halfGap = (1.1 + hash(index, seed + 293) * 3.6) * breaks;
         contact = Math.min(contact, clamp((Math.abs(at - middle) - halfGap) / 2.1));
@@ -29,13 +67,22 @@ export function strokeProfile(at, total, seed, settings = {}) {
     const tooth = noise(at * 1.6, seed + 401);
     const deposit = clamp((tooth - grainValue * 0.22) / Math.max(0.2, 1 - grainValue * 0.22));
     const taper = 0.2 + 0.8 * clamp(Math.min(at, total - at) / (settings.taperLength ?? 3));
-    return { pressure, contact, deposit, taper };
+    return { pressure, contact, deposit, taper, gapDistance };
 }
 export function pencilStroke(context, points, color, width, seed, amplitude, passes = 2, closed = false, settings = {}) {
-    if (points.length < 2)
+    const pointCount = points.length;
+    if (pointCount < 2 || pointCount > 65536)
         return;
+    // Validate the coordinates we retain, without scanning then cloning them again.
+    const line = [];
+    for (let index = 0; index < pointCount; index += 1) {
+        const point = points[index];
+        const x = point[0], y = point[1];
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            return;
+        line.push([x, y]);
+    }
     const scale = Math.max(0.4, settings.scale ?? 1);
-    const line = points.map(point => [...point]);
     const lastPoint = line[line.length - 1];
     if (closed && Math.hypot(line[0][0] - lastPoint[0], line[0][1] - lastPoint[1]) > 0.01) {
         line.push(line[0]);
@@ -56,6 +103,13 @@ export function pencilStroke(context, points, color, width, seed, amplitude, pas
     const distanceOffset = settings.distanceOffset ?? 0;
     const totalDistance = settings.totalDistance ?? distanceOffset + total;
     const step = settings.step ?? (settings.detail === 'fill' ? 2.1 : 1.05);
+    // Stop invalid steps and huge geometry before entering the sampling loop.
+    if (!Number.isFinite(total) || !Number.isFinite(step) || step <= 0 || total / step > 65536
+        || !Number.isFinite(distanceOffset) || Math.abs(distanceOffset) > Number.MAX_SAFE_INTEGER
+        || !Number.isFinite(totalDistance) || Math.abs(totalDistance) > Number.MAX_SAFE_INTEGER
+        || !Number.isFinite(passes) || passes < 0 || passes > 16
+        || !Number.isFinite(settings.filaments ?? 3) || (settings.filaments ?? 3) > 16)
+        return;
     const samples = [];
     let segmentIndex = 0;
     for (let at = 0;; at = Math.min(total, at + step)) {
@@ -103,6 +157,8 @@ export function pencilStroke(context, points, color, width, seed, amplitude, pas
             if (opacity < 0.012)
                 continue;
             const nib = width * (0.3 + pressure * 1.65) * Math.pow(scale, 0.32);
+            // Round segment caps must not paint back across intentional short gaps.
+            context.lineCap = Math.min(a.gapDistance, b.gapDistance) < nib / 2 + step ? 'butt' : 'round';
             const drift = pass ? (noise(a.at / 6, seed + pass * 107) - 0.5) * width * 1.1 : 0;
             context.globalAlpha = Math.min(1, inheritedAlpha * opacity * (pass ? 0.56 : 1.2)
                 * (settings.gain ?? 1));

package/dist/internal/surfaceBudget.d.ts

@@ -0,0 +1,20 @@
+export declare const MAX_SURFACE_PHYSICAL_EDGE = 8192;
+export declare const MAX_SURFACE_LAYER_PIXELS: number;
+export declare const MAX_SURFACE_TOTAL_PIXELS: number;
+export type SurfaceAllocationFailure = 'invalid-size' | 'edge-limit' | 'layer-budget' | 'surface-budget';
+export type SurfaceAllocation = {
+    ok: true;
+    dpr: number;
+    width: number;
+    height: number;
+    layerPixels: number;
+    totalPixels: number;
+} | {
+    ok: false;
+    reason: SurfaceAllocationFailure;
+};
+export declare function resolveSurfaceAllocation(width: number, height: number, dpr: number, bleed: number, layers: 1 | 2): SurfaceAllocation;
+type CanvasBitmap = Pick<HTMLCanvasElement, 'width' | 'height'>;
+export declare function resizeSurfaceBitmap(canvas: CanvasBitmap, width: number, height: number): void;
+export declare function releaseSurfaceBitmaps(...canvases: Array<CanvasBitmap | null | undefined>): void;
+export {};

package/dist/internal/surfaceBudget.js

@@ -0,0 +1,69 @@
+// 1024x640 at DPR 2 is 2.62M pixels per layer and 5.24M with a clipped border layer.
+export const MAX_SURFACE_PHYSICAL_EDGE = 8192;
+export const MAX_SURFACE_LAYER_PIXELS = 4 * 1024 * 1024;
+export const MAX_SURFACE_TOTAL_PIXELS = 6 * 1024 * 1024;
+const DPR_PRECISION = 1024;
+function allocationAtDpr(logicalWidth, logicalHeight, dpr, layers) {
+    const physicalWidth = Math.ceil(logicalWidth * dpr);
+    const physicalHeight = Math.ceil(logicalHeight * dpr);
+    if (!Number.isSafeInteger(physicalWidth) || !Number.isSafeInteger(physicalHeight)
+        || physicalWidth < 1 || physicalHeight < 1) {
+        return { ok: false, reason: 'invalid-size' };
+    }
+    if (physicalWidth > MAX_SURFACE_PHYSICAL_EDGE || physicalHeight > MAX_SURFACE_PHYSICAL_EDGE) {
+        return { ok: false, reason: 'edge-limit' };
+    }
+    const layerPixels = physicalWidth * physicalHeight;
+    if (!Number.isSafeInteger(layerPixels) || layerPixels > MAX_SURFACE_LAYER_PIXELS) {
+        return { ok: false, reason: 'layer-budget' };
+    }
+    const totalPixels = layerPixels * layers;
+    if (!Number.isSafeInteger(totalPixels) || totalPixels > MAX_SURFACE_TOTAL_PIXELS) {
+        return { ok: false, reason: 'surface-budget' };
+    }
+    return { ok: true, dpr, width: physicalWidth, height: physicalHeight, layerPixels, totalPixels };
+}
+export function resolveSurfaceAllocation(width, height, dpr, bleed, layers) {
+    if (![width, height, dpr, bleed].every(Number.isFinite)
+        || width <= 0 || height <= 0 || dpr < 1 || bleed < 0) {
+        return { ok: false, reason: 'invalid-size' };
+    }
+    const logicalWidth = width + bleed * 2;
+    const logicalHeight = height + bleed * 2;
+    const requested = allocationAtDpr(logicalWidth, logicalHeight, dpr, layers);
+    if (requested.ok)
+        return requested;
+    const minimum = allocationAtDpr(logicalWidth, logicalHeight, 1, layers);
+    if (!minimum.ok)
+        return minimum;
+    let lower = 1;
+    let upper = dpr;
+    for (let iteration = 0; iteration < 40; iteration += 1) {
+        const candidate = (lower + upper) / 2;
+        if (allocationAtDpr(logicalWidth, logicalHeight, candidate, layers).ok)
+            lower = candidate;
+        else
+            upper = candidate;
+    }
+    const resolvedDpr = Math.max(1, Math.floor(lower * DPR_PRECISION) / DPR_PRECISION);
+    const resolved = allocationAtDpr(logicalWidth, logicalHeight, resolvedDpr, layers);
+    return resolved.ok ? resolved : minimum;
+}
+export function resizeSurfaceBitmap(canvas, width, height) {
+    if (canvas.width === width && canvas.height === height) {
+        canvas.width = width;
+        return;
+    }
+    canvas.width = 0;
+    canvas.height = 0;
+    canvas.width = width;
+    canvas.height = height;
+}
+export function releaseSurfaceBitmaps(...canvases) {
+    for (const canvas of canvases) {
+        if (!canvas)
+            continue;
+        canvas.width = 0;
+        canvas.height = 0;
+    }
+}

package/dist/internal/surfaceRenderer.js

@@ -2,6 +2,8 @@ import { pencilPaper } from './paper.js';
 import { pencilStroke } from './stroke.js';
 import { drawPencilWash } from './wash.js';
 import { pencilRenderDefaults } from './renderTokens.js';
+import { BoundedCache, PENCIL_RENDERER_VERSION, canvasByteCost, canvasIsUsable } from './cache.js';
+import { releaseSurfaceBitmaps, resizeSurfaceBitmap, resolveSurfaceAllocation } from './surfaceBudget.js';
 export const PENCIL_ACTION_WASH = Object.freeze({
     lightStrength: 0.2,
     darkStrength: 0.12,
@@ -71,19 +73,27 @@ function paperPattern(context, color, dark, dpr) {
     }
     return pattern;
 }
-export function drawPencilSurface(canvas, borderCanvas, width, height, variant, seed, dpr, theme, radius) {
+function allocateSurface(canvas, borderCanvas, width, height, dpr, bleed) {
+    const allocation = resolveSurfaceAllocation(width, height, dpr, bleed, borderCanvas ? 2 : 1);
+    if (!allocation.ok) {
+        releaseSurfaceBitmaps(canvas, borderCanvas);
+        throw new RangeError(`PencilSurface allocation rejected: ${allocation.reason}`);
+    }
+    return allocation;
+}
+function paintPencilSurface(canvas, borderCanvas, width, height, variant, seed, allocation, theme, radius) {
     const bleed = variant === 'wash' ? 12 : 0;
-    canvas.width = Math.ceil((width + bleed * 2) * dpr);
-    canvas.height = Math.ceil((height + bleed * 2) * dpr);
+    const renderDpr = allocation.dpr;
+    resizeSurfaceBitmap(canvas, allocation.width, allocation.height);
     const context = canvas.getContext('2d');
-    if (!context)
+    if (!context) {
+        releaseSurfaceBitmaps(canvas, borderCanvas);
         throw new Error('Canvas 2D is unavailable');
+    }
+    if (borderCanvas)
+        resizeSurfaceBitmap(borderCanvas, allocation.width, allocation.height);
     context.setTransform(canvas.width / (width + bleed * 2), 0, 0, canvas.height / (height + bleed * 2), 0, 0);
     if (variant === 'wash') {
-        if (borderCanvas) {
-            borderCanvas.width = canvas.width;
-            borderCanvas.height = canvas.height;
-        }
         context.translate(bleed, bleed);
         drawPencilWash(context, { x: 0, y: 0, width, height }, theme.wash, seed, {
             strength: theme.washSettings?.strength ?? pencilRenderDefaults.washStrength / 0.48,
@@ -93,40 +103,28 @@ export function drawPencilSurface(canvas, borderCanvas, width, height, variant,
             inset: 2,
             radius: 8,
             edgeReach: 8,
-            dpr,
+            dpr: renderDpr,
         });
         return undefined;
     }
     if (variant === 'selection') {
-        if (borderCanvas) {
-            borderCanvas.width = canvas.width;
-            borderCanvas.height = canvas.height;
-        }
         drawPencilWash(context, { x: 0, y: 0, width, height }, theme.wash, seed, {
             strength: (theme.dark ? PENCIL_SELECTION_WASH.darkStrength : PENCIL_SELECTION_WASH.lightStrength) * (theme.washSettings?.strength ?? pencilRenderDefaults.washStrength / 0.48),
             spacing: theme.washSettings?.spacing ?? PENCIL_SELECTION_WASH.spacing,
             roughness: theme.washSettings?.roughness ?? PENCIL_SELECTION_WASH.roughness,
             inset: PENCIL_SELECTION_WASH.inset,
-            radius: PENCIL_SELECTION_WASH.radius,
+            radius: radius !== undefined && Number.isFinite(radius) ? Math.max(0, Math.min(radius, 8)) : PENCIL_SELECTION_WASH.radius,
             edgeReach: PENCIL_SELECTION_WASH.edgeReach,
             angle: theme.washSettings?.angle ?? PENCIL_SELECTION_WASH.angle,
-            dpr,
+            dpr: renderDpr,
         });
         return undefined;
     }
     if (variant === 'ghost') {
-        if (borderCanvas) {
-            borderCanvas.width = canvas.width;
-            borderCanvas.height = canvas.height;
-        }
         return undefined;
     }
     if (variant === 'full') {
-        if (borderCanvas) {
-            borderCanvas.width = canvas.width;
-            borderCanvas.height = canvas.height;
-        }
-        context.fillStyle = paperPattern(context, theme.paper, theme.dark, dpr);
+        context.fillStyle = paperPattern(context, theme.paper, theme.dark, renderDpr);
         context.fillRect(0, 0, width, height);
         return undefined;
     }
@@ -144,7 +142,7 @@ export function drawPencilSurface(canvas, borderCanvas, width, height, variant,
             context.lineTo(...point);
         context.closePath();
         context.clip();
-        context.fillStyle = paperPattern(context, theme.paper, theme.dark, dpr);
+        context.fillStyle = paperPattern(context, theme.paper, theme.dark, renderDpr);
         context.fillRect(0, 0, width, height);
         if (strength) {
             drawPencilWash(context, { x: 0, y: 0, width, height }, theme.wash, seed, {
@@ -152,15 +150,13 @@ export function drawPencilSurface(canvas, borderCanvas, width, height, variant,
                 ...theme.washSettings,
                 strength: strength * (theme.washSettings?.strength ?? pencilRenderDefaults.washStrength / 0.48),
                 radius: resolvedRadius,
-                dpr,
+                dpr: renderDpr,
             });
         }
         context.restore();
     }
     let borderContext = context;
     if (borderCanvas) {
-        borderCanvas.width = canvas.width;
-        borderCanvas.height = canvas.height;
         const separateContext = borderCanvas.getContext('2d');
         if (separateContext) {
             separateContext.setTransform(canvas.width / width, 0, 0, canvas.height / height, 0, 0);
@@ -176,3 +172,66 @@ export function drawPencilSurface(canvas, borderCanvas, width, height, variant,
     });
     return points;
 }
+const surfaceCache = new BoundedCache(64, 16 * 1024 * 1024);
+// Admit only a repeat within the recent working set. Cold mounts and long scans
+// must not pay for snapshots that will be evicted before they are ever reused.
+const surfaceRequests = new BoundedCache(64, 64);
+function copyCanvas(source, target) {
+    resizeSurfaceBitmap(target, source.width, source.height);
+    const context = target.getContext('2d');
+    if (!context || context.isContextLost?.())
+        throw new Error('Canvas 2D is unavailable');
+    context.drawImage(source, 0, 0);
+}
+export function drawPencilSurface(canvas, borderCanvas, width, height, variant, seed, dpr, theme, radius) {
+    // Transparent surfaces have no pixels to allocate or cache.
+    if (variant === 'ghost') {
+        canvas.width = canvas.height = 0;
+        if (borderCanvas)
+            borderCanvas.width = borderCanvas.height = 0;
+        return undefined;
+    }
+    const bleed = variant === 'wash' ? 12 : 0;
+    const allocation = allocateSurface(canvas, borderCanvas, width, height, dpr, bleed);
+    const key = JSON.stringify([
+        PENCIL_RENDERER_VERSION, variant, width, height, seed, allocation.dpr, Boolean(borderCanvas), radius,
+        theme.paper, theme.dark, theme.ink, theme.wash, theme.strokeWidth, theme.strokeRoughness,
+        theme.washSettings?.strength, theme.washSettings?.spacing,
+        theme.washSettings?.roughness, theme.washSettings?.angle,
+    ]);
+    const cached = surfaceCache.get(key);
+    if (cached?.valid && canvasIsUsable(cached.ink) && (!cached.border || canvasIsUsable(cached.border))) {
+        copyCanvas(cached.ink, canvas);
+        if (cached.border && borderCanvas)
+            copyCanvas(cached.border, borderCanvas);
+        return cached.points?.map(([x, y]) => [x, y]);
+    }
+    if (cached)
+        surfaceCache.delete(key);
+    const points = paintPencilSurface(canvas, borderCanvas, width, height, variant, seed, allocation, theme, radius);
+    const cost = canvasByteCost(canvas) + (borderCanvas ? canvasByteCost(borderCanvas) : 0);
+    const repeated = surfaceRequests.get(key) === true;
+    surfaceRequests.set(key, true, 1);
+    // Keep the cache useful for repeated controls, not a single large panel.
+    if (repeated && cost <= 2 * 1024 * 1024) {
+        try {
+            const ink = document.createElement('canvas');
+            const border = borderCanvas ? document.createElement('canvas') : null;
+            copyCanvas(canvas, ink);
+            if (border && borderCanvas)
+                copyCanvas(borderCanvas, border);
+            const image = { ink, border, points: points?.map(([x, y]) => [x, y]), valid: true };
+            // A restored context can report healthy after losing all of its pixels.
+            // Keep that entry invalid even if loss and restoration precede the next hit.
+            const invalidate = () => { image.valid = false; };
+            ink.addEventListener?.('contextlost', invalidate, { once: true });
+            border?.addEventListener?.('contextlost', invalidate, { once: true });
+            surfaceCache.set(key, image, cost);
+        }
+        catch {
+            // Caching is optional: a snapshot allocation failure must not discard a
+            // successfully painted live surface.
+        }
+    }
+    return points;
+}

package/dist/internal/surfaceVisibility.d.ts

@@ -0,0 +1,3 @@
+export declare function surfaceIsNearViewport(root: HTMLElement, margin?: number): boolean;
+/** One observer per document, explicitly released after the final subscription. */
+export declare function observeSurfaceViewport(root: HTMLElement, refresh: () => void): (() => void) | undefined;

package/dist/internal/surfaceVisibility.js

@@ -0,0 +1,60 @@
+// Keep visible/prewarm surfaces synchronous. An offscreen surface retains DOM,
+// geometry and any existing bitmap; only its decorative paint is deferred.
+export function surfaceIsNearViewport(root, margin = 240) {
+    const view = root.ownerDocument?.defaultView;
+    if (!view || !Number.isFinite(view.innerWidth) || !Number.isFinite(view.innerHeight)
+        || typeof root.getBoundingClientRect !== 'function')
+        return true;
+    const rect = root.getBoundingClientRect();
+    if (![rect.left, rect.right, rect.top, rect.bottom].every(Number.isFinite))
+        return true;
+    return rect.bottom >= -margin && rect.top <= view.innerHeight + margin
+        && rect.right >= -margin && rect.left <= view.innerWidth + margin;
+}
+const documents = new WeakMap();
+/** One observer per document, explicitly released after the final subscription. */
+export function observeSurfaceViewport(root, refresh) {
+    if (typeof IntersectionObserver === 'undefined' || !root.ownerDocument)
+        return undefined;
+    const document = root.ownerDocument;
+    let state = documents.get(document);
+    if (!state) {
+        const callbacks = new Map();
+        try {
+            const observer = new IntersectionObserver(entries => {
+                for (const entry of entries)
+                    if (entry.isIntersecting)
+                        callbacks.get(entry.target)?.();
+            }, { rootMargin: '240px', threshold: 0 });
+            state = { observer, callbacks };
+            documents.set(document, state);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const current = state;
+    current.callbacks.set(root, refresh);
+    try {
+        current.observer.observe(root);
+    }
+    catch {
+        current.callbacks.delete(root);
+        if (!current.callbacks.size) {
+            current.observer.disconnect();
+            documents.delete(document);
+        }
+        return undefined;
+    }
+    return () => {
+        // Ignore a stale unsubscribe if a newer owner registered the same element.
+        if (current.callbacks.get(root) !== refresh)
+            return;
+        current.callbacks.delete(root);
+        current.observer.unobserve(root);
+        if (!current.callbacks.size) {
+            current.observer.disconnect();
+            documents.delete(document);
+        }
+    };
+}

package/dist/internal/textRenderer.d.ts

@@ -16,9 +16,12 @@ export interface PencilTextSprite {
 }
 export declare const pencilLettering: PencilLetteringSettings;
 export declare const pencilHandwriting = "\"Trip Map Hand\",\"HanziPen SC\",\"Hannotate SC\",\"Kaiti SC\",\"STKaiti\",cursive";
+export declare function boundedTextResolution(width: number, height: number, dpr: number): number;
 export declare function renderPencilText(text: string, options: {
     size: number;
     family?: string;
+    weight?: string;
+    style?: string;
     color: string;
     seed: number;
     dpr: number;