@inkra/react 0.2.0 → 0.4.3

package/dist/input-number/index.js

@@ -1,18 +1,19 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from 'react';
 import { useBrowserLayoutEffect } from '../internal/useBrowserLayoutEffect.js';
 import { Button } from '../Button.js';
 import { PencilIcon } from '../PencilIcon.js';
 import { Input } from '../form/Input.js';
 import { useResolvedControlProps } from '../form/controlProps.js';
 import { Tooltip } from '../tooltip/Tooltip.js';
+import { normalizeInputNumberRepeat, resolveInputNumberStep, stepInputNumber, } from './model.js';
 // Lucide Plus / Minus ISC geometry uses the shared pencil renderer.
 const plusPaths = [{ d: 'M5 12h14' }, { d: 'M12 5v14' }];
 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, onValueChange, readOnly, size = 'md', step = 1, textAlign = 'center', value, ...props }, forwardedRef) {
+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) {
     const inputRef = useRef(null);
     const isControlled = value !== undefined;
     const [draft, setDraft] = useState(() => format(isControlled ? value : defaultValue));
@@ -21,6 +22,54 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
     const latest = useRef({ isControlled, value, defaultValue });
     latest.current = { isControlled, value, defaultValue };
     useImperativeHandle(forwardedRef, () => inputRef.current);
+    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)) {
+            try {
+                hold.button.releasePointerCapture(hold.pointerId);
+            }
+            catch { /* The pointer may already be inactive. */ }
+        }
+    }, []);
+    // Idle controls do not need global pointer, keyboard or visibility listeners.
+    const listenWhileHolding = () => {
+        const onVisibilityChange = () => { if (document.hidden)
+            stopHolding(); };
+        const onPointerEnd = (event) => {
+            if (event.pointerId === holdRef.current?.pointerId)
+                stopHolding();
+        };
+        const updateModifiers = (event) => {
+            if (holdRef.current)
+                holdRef.current.modifiers = {
+                    shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey,
+                };
+        };
+        window.addEventListener('blur', stopHolding);
+        window.addEventListener('pointerup', onPointerEnd);
+        window.addEventListener('pointercancel', onPointerEnd);
+        window.addEventListener('keydown', updateModifiers);
+        window.addEventListener('keyup', updateModifiers);
+        document.addEventListener('visibilitychange', onVisibilityChange);
+        removeHoldListeners.current = () => {
+            window.removeEventListener('blur', stopHolding);
+            window.removeEventListener('pointerup', onPointerEnd);
+            window.removeEventListener('pointercancel', onPointerEnd);
+            window.removeEventListener('keydown', updateModifiers);
+            window.removeEventListener('keyup', updateModifiers);
+            document.removeEventListener('visibilitychange', onVisibilityChange);
+        };
+    };
+    useEffect(() => stopHolding, [stopHolding]);
     useBrowserLayoutEffect(() => {
         if (isControlled && currentValue !== finiteValue(value))
             setDraft(format(value));
@@ -32,6 +81,7 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
             return;
         let resetTimer;
         const reset = (event) => {
+            stopHolding();
             clearTimeout(resetTimer);
             // Native reset runs after the event; restore the public default, not the latest draft.
             resetTimer = setTimeout(() => {
@@ -45,33 +95,99 @@ export const InputNumber = forwardRef(function InputNumber({ classNames, control
         };
         form.addEventListener('reset', reset);
         return () => { clearTimeout(resetTimer); form.removeEventListener('reset', reset); };
-    }, [props.form]);
+    }, [props.form, stopHolding]);
     const cannotStep = state.disabled || state.readOnly || step === 'any' || (min !== undefined && max !== undefined && min > max);
     const decreaseDisabled = cannotStep || (currentValue !== null && min !== undefined && currentValue <= min);
     const increaseDisabled = cannotStep || (currentValue !== null && max !== undefined && currentValue >= max);
-    function changeStep(direction) {
+    useBrowserLayoutEffect(() => {
+        const direction = holdRef.current?.direction;
+        if (cannotStep || !controls || !pressAndHold
+            || (direction === 'increment' && increaseDisabled)
+            || (direction === 'decrement' && decreaseDisabled))
+            stopHolding();
+    }, [cannotStep, controls, decreaseDisabled, increaseDisabled, pressAndHold, stopHolding]);
+    function changeStep(direction, modifiers) {
         const input = inputRef.current;
         if (!input || input.matches(':disabled') || input.readOnly || cannotStep)
-            return;
-        const before = input.value;
-        // Native stepping applies the step base and decimal rounding without a custom parser.
-        if (direction === 'increment')
-            input.stepUp();
-        else
-            input.stepDown();
+            return false;
+        const changed = stepInputNumber(input, direction, resolveInputNumberStep(modifiers, stepModifiers));
         input.focus({ preventScroll: true });
-        if (input.value === before)
-            return;
+        if (!changed)
+            return false;
         setDraft(input.value);
         onValueChange?.(Number.isFinite(input.valueAsNumber) ? input.valueAsNumber : null, { reason: direction });
+        return true;
+    }
+    const stepRef = useRef(changeStep);
+    stepRef.current = changeStep;
+    const intervalRef = useRef(repeatInterval);
+    intervalRef.current = repeatInterval;
+    function startHolding(event, direction) {
+        if (event.button !== 0 || !event.isPrimary)
+            return;
+        event.preventDefault();
+        stopHolding();
+        suppressClickRef.current = false;
+        if (!pressAndHold)
+            return;
+        suppressClickRef.current = true;
+        const modifiers = {
+            shiftKey: event.shiftKey, altKey: event.altKey, ctrlKey: event.ctrlKey, metaKey: event.metaKey,
+        };
+        if (!changeStep(direction, modifiers))
+            return;
+        const button = event.currentTarget;
+        if (!button.isConnected || button.disabled)
+            return;
+        holdRef.current = { button, pointerId: event.pointerId, direction, modifiers };
+        listenWhileHolding();
+        try {
+            button.setPointerCapture(event.pointerId);
+        }
+        catch { /* Window listeners retain release handling. */ }
+        const repeat = () => {
+            const hold = holdRef.current;
+            if (!hold || document.hidden || !stepRef.current(hold.direction, hold.modifiers)) {
+                stopHolding();
+                return;
+            }
+            if (holdRef.current)
+                timerRef.current = setTimeout(repeat, normalizeInputNumberRepeat(intervalRef.current, 80, 32));
+        };
+        timerRef.current = setTimeout(repeat, normalizeInputNumberRepeat(repeatDelay, 400, 150));
+    }
+    function buttonEvents(direction) {
+        return {
+            onPointerDown: (event) => startHolding(event, direction),
+            onPointerUp: stopHolding,
+            onPointerCancel: stopHolding,
+            onLostPointerCapture: stopHolding,
+            onBlur: stopHolding,
+            onClick: (event) => {
+                if (event.detail > 0 && suppressClickRef.current) {
+                    suppressClickRef.current = false;
+                    return;
+                }
+                suppressClickRef.current = false;
+                changeStep(direction, event);
+            },
+        };
     }
     const iconSize = size === 'sm' ? 18 : size === 'lg' ? 26 : 22;
     const buttonSize = size === 'sm' ? 'icon-sm' : size === 'lg' ? 'icon-lg' : 'icon';
-    return _jsx(Input, { ...props, ref: inputRef, type: "number", inputMode: inputMode, textAlign: textAlign, clearable: false, size: size, min: min, max: max, step: step, disabled: state.disabled, readOnly: state.readOnly, value: draft, classNames: { ...classNames, root: ['inkra-input-number', classNames?.root].filter(Boolean).join(' ') }, onChange: event => {
+    return _jsx(Input, { ...props, ref: inputRef, type: "number", inputMode: inputMode, textAlign: textAlign, clearable: false, size: size, min: min, max: max, step: step, disabled: state.disabled, readOnly: state.readOnly, value: draft, classNames: { ...classNames, root: ['inkra-input-number', classNames?.root].filter(Boolean).join(' ') }, onBlur: event => { stopHolding(); onBlur?.(event); }, onKeyDown: event => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented || event.nativeEvent.isComposing || (event.key !== 'ArrowUp' && event.key !== 'ArrowDown'))
+                return;
+            if (resolveInputNumberStep(event, stepModifiers) === undefined)
+                return;
+            event.preventDefault();
+            changeStep(event.key === 'ArrowUp' ? 'increment' : 'decrement', event);
+        }, onChange: event => {
             const input = event.currentTarget;
             const nextValue = Number.isFinite(input.valueAsNumber) ? input.valueAsNumber : null;
             setDraft(input.value);
             onChange?.(event);
             onValueChange?.(nextValue, { reason: 'input' });
-        }, startAction: controls ? _jsx(Tooltip.Provider, { children: _jsx("span", { className: "inkra-input-number__controls", children: _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: _jsx(Button, { type: "button", size: buttonSize, variant: "ghost", disabled: decreaseDisabled, "aria-label": decrementButtonLabel, onPointerDown: event => event.preventDefault(), onClick: () => changeStep('decrement'), children: _jsx(PencilIcon, { paths: minusPaths, size: iconSize, sourceSize: 24 }) }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { children: decrementButtonLabel }) })] }) }) }) : undefined, endAction: controls ? _jsx(Tooltip.Provider, { children: _jsx("span", { className: "inkra-input-number__controls", children: _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: _jsx(Button, { type: "button", size: buttonSize, variant: "ghost", disabled: increaseDisabled, "aria-label": incrementButtonLabel, onPointerDown: event => event.preventDefault(), onClick: () => changeStep('increment'), children: _jsx(PencilIcon, { paths: plusPaths, size: iconSize, sourceSize: 24 }) }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { children: incrementButtonLabel }) })] }) }) }) : undefined });
+        }, startAction: controls ? _jsx(Tooltip.Provider, { children: _jsx("span", { className: "inkra-input-number__controls", children: _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: _jsx(Button, { type: "button", size: buttonSize, variant: "ghost", disabled: decreaseDisabled, "aria-label": decrementButtonLabel, ...buttonEvents('decrement'), children: _jsx(PencilIcon, { paths: minusPaths, size: iconSize, sourceSize: 24 }) }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { children: decrementButtonLabel }) })] }) }) }) : undefined, endAction: controls ? _jsx(Tooltip.Provider, { children: _jsx("span", { className: "inkra-input-number__controls", children: _jsxs(Tooltip.Root, { children: [_jsx(Tooltip.Trigger, { asChild: true, children: _jsx(Button, { type: "button", size: buttonSize, variant: "ghost", disabled: increaseDisabled, "aria-label": incrementButtonLabel, ...buttonEvents('increment'), children: _jsx(PencilIcon, { paths: plusPaths, size: iconSize, sourceSize: 24 }) }) }), _jsx(Tooltip.Portal, { children: _jsx(Tooltip.Content, { children: incrementButtonLabel }) })] }) }) }) : undefined });
 });

package/dist/input-number/model.d.ts

@@ -0,0 +1,13 @@
+export interface InputNumberStepModifier {
+    shiftKey?: boolean;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    step: number;
+}
+export type InputNumberModifierState = Pick<KeyboardEvent, 'shiftKey' | 'altKey' | 'ctrlKey' | 'metaKey'>;
+export type InputNumberStepDirection = 'increment' | 'decrement';
+export declare const defaultInputNumberStepModifiers: readonly InputNumberStepModifier[];
+export declare function resolveInputNumberStep(modifiers: InputNumberModifierState, rules?: readonly InputNumberStepModifier[]): number | undefined;
+export declare function normalizeInputNumberRepeat(value: number | undefined, fallback: number, minimum: number): number;
+export declare function stepInputNumber(input: HTMLInputElement, direction: InputNumberStepDirection, modifierStep?: number): boolean;

package/dist/input-number/model.js

@@ -0,0 +1,50 @@
+export const defaultInputNumberStepModifiers = [
+    { shiftKey: true, step: 10 },
+];
+export function resolveInputNumberStep(modifiers, rules = defaultInputNumberStepModifiers) {
+    return rules.find(rule => Number.isFinite(rule.step) && rule.step > 0
+        && Boolean(rule.shiftKey) === modifiers.shiftKey
+        && Boolean(rule.altKey) === modifiers.altKey
+        && Boolean(rule.ctrlKey) === modifiers.ctrlKey
+        && Boolean(rule.metaKey) === modifiers.metaKey)?.step;
+}
+export function normalizeInputNumberRepeat(value, fallback, minimum) {
+    return value === undefined || !Number.isFinite(value)
+        ? fallback
+        : Math.min(60000, Math.max(minimum, value));
+}
+export function stepInputNumber(input, direction, modifierStep) {
+    const before = input.value;
+    const min = input.min === '' ? -Infinity : Number(input.min);
+    const max = input.max === '' ? Infinity : Number(input.max);
+    if (input.disabled || input.readOnly || input.step === 'any' || min > max)
+        return false;
+    if ((direction === 'increment' && input.valueAsNumber >= max)
+        || (direction === 'decrement' && input.valueAsNumber <= min))
+        return false;
+    if (modifierStep === undefined) {
+        if (direction === 'increment')
+            input.stepUp();
+        else
+            input.stepDown();
+    }
+    else {
+        // A detached native input anchors the step base at the current value, so
+        // modifier steps are absolute deltas without floating-point arithmetic.
+        const probe = input.cloneNode(false);
+        probe.removeAttribute('min');
+        probe.removeAttribute('max');
+        probe.step = String(modifierStep);
+        probe.defaultValue = before || '0';
+        probe.value = before;
+        if (direction === 'increment')
+            probe.stepUp();
+        else
+            probe.stepDown();
+        const next = probe.valueAsNumber;
+        if (!Number.isFinite(next))
+            return false;
+        input.value = String(Math.min(Number.isFinite(max) ? max : Infinity, Math.max(Number.isFinite(min) ? min : -Infinity, next)));
+    }
+    return before !== input.value;
+}

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;
+    }
+}