@inkra/react 0.8.0 → 0.10.0

package/README.md

@@ -17,6 +17,52 @@ Inkra components require a React client boundary. Next.js and React Server Compo
 
 ## Usage
 
+### Guided And Asynchronous Experiences
+
+`Guide.Root`, `Guide.Trigger` and `Guide.Step` compose a targeted walkthrough.
+`showSkip` exposes skipping; `onSkip` is separate from `onFinish`, so leaving
+early never reports completion. Controlled `open` and `step`, target resolution,
+focus restoration and localized labels are available.
+
+`Loading` supports `inline`, `region` and `fullscreen` carriers with six layout
+presets: `brand-center`, `scene-bottom`, `intel`, `staged`, `edge` and `skeleton`.
+Supply real progress or `null` for indeterminate progress. The application owns
+`status` and the cancel/retry/continue actions. Fullscreen blocking and scroll
+locking can be configured independently; the edge preset is non-blocking by
+default. Backgrounds, logos, stages, six logical content slots and rotating
+ReactNode tips share the same component. Tips support manual navigation, pause,
+controlled indices and sequential or non-repeating random rotation.
+
+`InfiniteScroll` loads at `top`, `bottom`, `left` or `right` boundaries. Configure
+automatic boundary loading and touch pull-and-release separately per direction;
+buttons remain available for keyboard use. `onLoad` receives an abort signal,
+direction and source. Stable item identities support anchored prepends, while
+errors, retry, exhausted directions and in-flight requests remain explicit.
+
+`Masonry` arranges measured items in shortest-column or sequential order while
+retaining DOM order. It supports adaptive or fixed columns, independent gaps,
+RTL and dynamic item sizes. Supply unique stable keys, image alternatives and
+your own data fetching, optionally through `InfiniteScroll`:
+
+```tsx
+<InfiniteScroll
+  directions="bottom"
+  hasMore={hasMore}
+  onLoad={({ signal }) => fetchNextPage(signal)}
+  style={{ maxHeight: 640, overflow: 'auto' }}
+>
+  <Masonry
+    items={items}
+    getItemKey={item => item.id}
+    minColumnWidth={220}
+    renderItem={({ item }) => <article>{item.content}</article>}
+  />
+</InfiniteScroll>
+```
+
+These APIs are included in this source candidate. Local browser checks are not
+real-device certification or a claim that this candidate has been published.
+
 Import the component styles once near the application entry point:
 
 ```tsx
@@ -435,6 +481,22 @@ motion and SSR show deterministic final values. Intermediate frames are visual;
 the polite announcement updates only at the final value. Use `getValueLabel`
 when units or custom rendering need a complete accessible phrase.
 
+Use `animation="roll"` for vertical, place-aligned digit reels. Integers align
+from the right and fractions from the decimal point; carry, multiplication,
+shrinking values and sign changes expand or collapse the affected columns.
+Grouping, signs, currency and compact units remain formatted text, not digit
+reels. `rollDirection="auto"` rolls up for increasing values and down for
+decreasing values; `up` or `down` fixes the direction. `duration` and `easing`
+apply to both modes. The default `animation="count"` retains value interpolation.
+`renderValue` takes precedence over the built-in reels. Changing the formatting
+or animation mode settles immediately, as do disabled/reduced motion, invalid
+durations, and transitions with more than 128 formatted tokens. Exact strings
+and bigint values retain their original precision in either mode.
+
+```tsx
+<NumberTicker value={amount} animation="roll" rollDirection="auto" duration={650} />
+```
+
 Set `compact` to follow `locale` (Chinese units for `zh`, English units otherwise),
 or use `compact="en"` / `compact="zh"` to select a unit table explicitly.
 English uses this library's short-scale suffix convention: K, M, B, T, Qa, Qi,
@@ -546,6 +608,33 @@ The matching inherited tokens are `--inkra-icon-stroke-width`,
 and `--inkra-icon-break-count`. Finite explicit props override those tokens.
 See `docs/pencil-contract.md` in the workspace for the material contract.
 
+Icons support `variant="outline"` (default) and `variant="filled"`. Filled icons
+keep holes and internal marks transparent, join overlapping silhouettes and do
+not close open arrows or checks into polygons. Set `fillColor` independently of
+the contour's CSS `color`; it defaults to `currentColor` and accepts CSS variables.
+The silhouette stays continuous while stroke controls affect its exterior.
+
+```tsx
+<PencilIcon paths={folderPaths} variant="filled" fillColor="var(--folder-color)"
+  sourceSize={24} size={32} style={{ color: 'var(--inkra-ink)' }} />
+```
+
+Supply `filledPaths` when a shape needs a dedicated filled silhouette. Each path
+can use `mode: 'fill'` with an optional `color` for independently colored regions,
+or `mode: 'cutout'` for transparent details. Closed cutouts remove an area; open
+cutouts remove a stroke without implicitly closing it. Explicit fills accept
+`fillRule: 'nonzero' | 'evenodd'` (default `nonzero`). These authored regions do
+not add their own contour stroke. For lighter colored-pencil regions, use
+`mode: 'wash'` with the same optional `color` and `fillRule`: paper remains visible
+between pigment strokes, with a light pencil edge in the icon's CSS `color`.
+Dense `fill` regions are unchanged.
+Explicit `mode: 'stroke'` keeps a line symbol
+even when its path closes; omitted mode detects filled silhouettes automatically.
+An empty `filledPaths` intentionally hides the
+base shape in filled mode. `badge` accepts the same three props and inherits the
+base variant and fill color unless overridden. Intensity applies once to the
+completed image, including its fills, exterior strokes and badge.
+
 `PencilLine` is an aria-hidden canvas decoration using the same pressure, grain, breaks, and repeated-pass renderer as surfaces and icons. It defaults to horizontal and supports a native vertical stroke without rotating a horizontal bitmap:
 
 ```tsx
@@ -555,10 +644,28 @@ See `docs/pencil-contract.md` in the workspace for the material contract.
 
 ### Rendering tokens
 
+`ThemeProvider` accepts typography through `tokens`. Set
+`--inkra-font-hand`, `--inkra-font-body` and `--inkra-font-display` to CSS font
+stacks (load your chosen font separately). Set `--inkra-letter-effect: 0` to
+display plain selectable text in that font, without the pencil canvas.
+The default is 1 (enabled). This inherited toggle preserves all lettering
+parameters and does not affect icons, surface fills or borders.
+
+```tsx
+<ThemeProvider tokens={{
+  '--inkra-font-hand': '"Inkra Xiaolai", cursive',
+  '--inkra-font-body': '"Inkra Xiaolai", cursive',
+  '--inkra-font-display': '"Inkra Xiaolai", cursive',
+  '--inkra-letter-effect': 0,
+}}>
+  <Button>普通字体效果</Button>
+</ThemeProvider>
+```
+
 `PencilText` reads `--inkra-letter-variation`, `--inkra-letter-breaks`,
 `--inkra-letter-outline`, `--inkra-letter-fill`, and `--inkra-letter-grain` from
 its computed style. Values are clamped to 0-1; missing or invalid values use the
-default lettering preset (0.20, 0.50, 0.90, 0.90, 0.60 respectively). Apply these tokens to an ancestor to customize all
+default Xiaolai lettering preset (0.10, 0.31, 0.44, 0.85, 0.40 respectively, revised 2026-10-28). Apply these tokens to an ancestor to customize all
 text within that scope without changing layout, selectable text, or labels.
 
 `PencilLine` reads `--inkra-stroke-width` (0.3-3) and
@@ -583,7 +690,13 @@ unavailable-canvas fallbacks remain intact.
 
 ## Font license
 
-The package includes `Trip Map Hand`, a modified web subset of Yozai Light v0.868, under the SIL Open Font License 1.1. The font is not covered by Inkra's MIT software license. See `THIRD_PARTY_NOTICES.md` and `Yozai-OFL.txt` in the package.
+The default font is Xiaolai SC Regular v3.120, registered as `Inkra Xiaolai`.
+Common and extended characters are separate WOFF2 resources loaded through
+`unicode-range`. Override `--inkra-font-hand` to choose another font; the source
+text and canvas use the same computed family. The package also retains
+`Trip Map Hand`, a web subset of Yozai Light v0.868, for compatibility.
+Both fonts use SIL OFL 1.1, separately from Inkra's MIT software license.
+See `THIRD_PARTY_NOTICES.md`, `Xiaolai-OFL.txt` and `Yozai-OFL.txt`.
 
 ## Development
 
@@ -594,3 +707,25 @@ npm run pack:check
 ```
 
 `npm test` builds the package before running the SSR and determinism tests. `pack:check` prints the files that would be included without publishing anything.
+
+## Slider endpoints and circular dragging
+
+Slider and RangeSlider use `thumbAlignment="edge"` by default: the thumb center
+reaches either end of the track. Set `thumbAlignment="contain"` to keep the
+previous inset positioning. This setting is independent of the visual variant.
+
+`CircularSlider` is an optional single-value control exported from
+`@inkra/react` and `@inkra/react/slider`. It supports controlled and uncontrolled
+values, min/max/step, pointer and touch dragging, keyboard controls, disabled
+and read-only states, form submission/reset, and a configurable arc. Angles are
+measured clockwise from the top; `startAngle={0} sweepAngle={360}` draws a full
+ring. `clockwise` controls the value direction. Arrow Right/Up increase,
+Arrow Left/Down decrease, Home/End reach bounds and Page keys take larger steps.
+Give the control an accessible name and use `getValueLabel` for units.
+
+Use `centerIcon` for a decorative icon. The default center displays the value;
+set `showValue={false}` for an icon alone. `centerContent` accepts a React node
+or `(value: number) => ReactNode`, overriding the default value display when
+provided; `null` hides the text. Strings and numbers retain the pencil text
+appearance. Center content is inert and hidden from accessibility APIs;
+keep the slider's `aria-label` and `getValueLabel` meaningful independently.

package/THIRD_PARTY_NOTICES.md

@@ -1,5 +1,14 @@
 # Third-Party Notices
 
+## Xiaolai SC
+
+`dist/assets/ui-hand-xiaolai*.woff2` contains Xiaolai SC Regular v3.120 by LXGW,
+converted to WOFF2 and split into common and extended character sets without
+dropping mapped characters. It is registered as `Inkra Xiaolai` in CSS.
+Source: https://github.com/lxgw/kose-font/releases/tag/v3.120
+License: SIL Open Font License 1.1, reproduced in `Xiaolai-OFL.txt`.
+This font is not covered by Inkra's MIT software license.
+
 ## Trip Map Hand font subset
 
 `dist/assets/ui-hand-yozai.woff2` is a web subset of Yozai Light v0.868 by LXGW, derived from work by Y.Oz. The subset uses the modified family name `Trip Map Hand` and is included to provide the handwriting geometry used by Inkra's pencil-text renderer.

package/Xiaolai-OFL.txt

@@ -0,0 +1,94 @@
+Copyright 2020-2024 LXGW (https://github.com/lxgw/kose-font)
+Copyright 2014 Nozomi Seto (https://ja.osdn.net/projects/setofont/)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/PencilIcon.d.ts

@@ -1,10 +1,17 @@
 import type { CanvasHTMLAttributes } from 'react';
 export interface PencilIconPath {
     d: string;
-    mode?: 'stroke' | 'wash' | 'scuff';
+    /** Filled icons: stroke stays a line, wash exposes paper, fill is dense; omitted mode detects closed silhouettes. */
+    mode?: 'stroke' | 'wash' | 'scuff' | 'fill' | 'cutout';
+    /** Optional pigment for an explicit fill region, including CSS custom properties. */
+    color?: string;
+    fillRule?: CanvasFillRule;
 }
 export interface PencilIconBadge {
     paths: readonly PencilIconPath[];
+    filledPaths?: readonly PencilIconPath[];
+    variant?: 'outline' | 'filled';
+    fillColor?: string;
     sourceSize?: number;
     position?: 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
     /** Relative canvas size, clamped to 0.35-0.65. Defaults to 0.55. */
@@ -12,6 +19,12 @@ export interface PencilIconBadge {
 }
 export interface PencilIconProps extends Omit<CanvasHTMLAttributes<HTMLCanvasElement>, 'children' | 'height' | 'width'> {
     paths: readonly PencilIconPath[];
+    /** Filled icons retain open symbols and use negative space for interior details. */
+    variant?: 'outline' | 'filled';
+    /** Optional authored geometry for shapes whose filled silhouette differs from the outline. */
+    filledPaths?: readonly PencilIconPath[];
+    /** Body pigment, independent of the CSS color used for the contour. Defaults to currentColor. */
+    fillColor?: string;
     badge?: PencilIconBadge;
     seed?: string | number;
     size?: number;

package/dist/PencilIcon.js

@@ -6,6 +6,7 @@ import { seedToNumber } from './internal/random.js';
 import { pencilStroke } from './internal/stroke.js';
 import { maxStrokeRoughness, pencilRenderDefaults, readRenderToken } from './internal/renderTokens.js';
 import { cachedPathParts } from './internal/iconGeometry.js';
+import { paintFilledIcon } from './internal/iconFill.js';
 const imageCache = new BoundedCache(128, 24 * 1024 * 1024);
 function drawFallbackPath(context, data, color, mode, weightScale = 1) {
     try {
@@ -47,56 +48,62 @@ function renderIcon(paths, options) {
     const offset = (40 - sourceSize) / 2;
     context.translate(offset, offset);
     let sampledPoints = 0;
-    paths.forEach((path, index) => {
-        if (path.d.length > 65536)
-            return;
-        const mode = path.mode ?? 'stroke';
-        const pathSeed = seed + index * 137;
-        if (mode === 'wash') {
+    if (options.variant === 'filled') {
+        paintFilledIcon(context, paths, { color, fillColor: options.fillColor ?? color, sourceSize, seed, weightScale, roughnessScale, breaks, breakCount, pressureVariation, coordinateScale });
+    }
+    else
+        paths.forEach((path, index) => {
+            if (path.d.length > 65536)
+                return;
+            const mode = path.mode ?? 'stroke';
+            if (mode === 'cutout')
+                return;
+            const pathSeed = seed + index * 137;
+            if (mode === 'wash' || mode === 'fill') {
+                try {
+                    context.save();
+                    context.clip(new Path2D(path.d));
+                    context.globalAlpha = active ? 0.76 : 0.34;
+                    for (let y = sourceSize * 0.18; y < sourceSize; y += 1.6) {
+                        pencilStroke(context, [[sourceSize * 0.15, y + 3], [sourceSize * 0.85, y - 3]], color, 1.1 * weightScale / (pencilRenderDefaults.strokeWidth / 1.2), pathSeed + Math.round(y * 17), 0.25, 2, false, { variation: Math.min(1, 0.85 * variationScale), fitPressure: true, breaks, breakCount, breakScale: coordinateScale, continuousBreaks: true, grain: 0.7, gain: 2.2, step: 0.35 });
+                    }
+                    context.restore();
+                }
+                catch {
+                    drawFallbackPath(context, path.d, color, mode, weightScale);
+                }
+                return;
+            }
             try {
-                context.save();
-                context.clip(new Path2D(path.d));
-                context.globalAlpha = active ? 0.76 : 0.34;
-                for (let y = sourceSize * 0.18; y < sourceSize; y += 1.6) {
-                    pencilStroke(context, [[sourceSize * 0.15, y + 3], [sourceSize * 0.85, y - 3]], color, 1.1 * weightScale / (pencilRenderDefaults.strokeWidth / 1.2), pathSeed + Math.round(y * 17), 0.25, 2, false, { variation: Math.min(1, 0.85 * variationScale), fitPressure: true, breaks, breakCount, breakScale: coordinateScale, continuousBreaks: true, grain: 0.7, gain: 2.2, step: 0.35 });
+                if (sampledPoints >= 65536) {
+                    drawFallbackPath(context, path.d, color, mode, weightScale);
+                    return;
+                }
+                const parts = cachedPathParts(path.d);
+                sampledPoints += parts.reduce((total, part) => total + part.length, 0);
+                if (sampledPoints > 65536) {
+                    drawFallbackPath(context, path.d, color, mode, weightScale);
+                    return;
+                }
+                for (const points of parts) {
+                    pencilStroke(context, points, color, (mode === 'scuff' ? 0.55 : 1.65) * weightScale, pathSeed, 0.3 * roughnessScale, mode === 'scuff' ? 1 : 3, false, {
+                        variation: pressureVariation,
+                        fitPressure: true,
+                        breaks,
+                        breakCount,
+                        breakScale: coordinateScale,
+                        continuousBreaks: true,
+                        grain: 0.68,
+                        gain: mode === 'scuff' ? 1.5 : 3,
+                        step: 0.35,
+                        taperLength: 0.65,
+                    });
                 }
-                context.restore();
             }
             catch {
                 drawFallbackPath(context, path.d, color, mode, weightScale);
             }
-            return;
-        }
-        try {
-            if (sampledPoints >= 65536) {
-                drawFallbackPath(context, path.d, color, mode, weightScale);
-                return;
-            }
-            const parts = cachedPathParts(path.d);
-            sampledPoints += parts.reduce((total, part) => total + part.length, 0);
-            if (sampledPoints > 65536) {
-                drawFallbackPath(context, path.d, color, mode, weightScale);
-                return;
-            }
-            for (const points of parts) {
-                pencilStroke(context, points, color, (mode === 'scuff' ? 0.55 : 1.65) * weightScale, pathSeed, 0.3 * roughnessScale, mode === 'scuff' ? 1 : 3, false, {
-                    variation: pressureVariation,
-                    fitPressure: true,
-                    breaks,
-                    breakCount,
-                    breakScale: coordinateScale,
-                    continuousBreaks: true,
-                    grain: 0.68,
-                    gain: mode === 'scuff' ? 1.5 : 3,
-                    step: 0.35,
-                    taperLength: 0.65,
-                });
-            }
-        }
-        catch {
-            drawFallbackPath(context, path.d, color, mode, weightScale);
-        }
-    });
+        });
     if (active) {
         pencilStroke(context, [[sourceSize * 0.2, sourceSize - 2], [sourceSize * 0.5, sourceSize - 1.5], [sourceSize * 0.8, sourceSize - 2.2]], color, 1.1 * weightScale, seed + 977, 0.25 * roughnessScale, 3, false, { variation: 0.8 * variationScale, fitPressure: true, breaks, breakCount, breakScale: coordinateScale, continuousBreaks: true, grain: 0.7, gain: 2.8, step: 0.35 });
     }
@@ -109,8 +116,10 @@ function renderIcon(paths, options) {
         const extent = 40 * scale;
         const x = onLeft ? 0 : 40 - extent;
         const y = position.startsWith('top') ? 0 : 40 - extent;
-        const badgeImage = renderIcon(badge.paths, {
+        const badgeVariant = badge.variant ?? options.variant;
+        const badgeImage = renderIcon(badgeVariant === 'filled' ? badge.filledPaths ?? badge.paths : badge.paths, {
             seed: seed + 1543, size: size * scale, sourceSize: badgeSourceSize, active: false, color, dpr,
+            variant: badgeVariant, fillColor: badge.fillColor ?? options.fillColor,
             weightScale: weightScale / scale, roughnessScale, breaks, breakCount, pressureVariation,
         });
         const mask = document.createElement('canvas');
@@ -140,17 +149,18 @@ function renderIcon(paths, options) {
     }
     return canvas;
 }
-export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge, className = '', decorative = true, paths, seed, size = 40, sourceSize = 32, strokeWidth, intensity, breaks, breakCount, pressureVariation, ...props }, forwardedRef) {
+export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge, className = '', decorative = true, paths, variant = 'outline', filledPaths, fillColor, seed, size = 40, sourceSize = 32, strokeWidth, intensity, breaks, breakCount, pressureVariation, ...props }, forwardedRef) {
     const canvasRef = useRef(null);
     const lastPaintRef = useRef('');
     useImperativeHandle(forwardedRef, () => canvasRef.current);
     // Compare values, not caller object identity. Serializing each render also
     // detects in-place edits; the effect receives a stable snapshot of that value.
-    const geometryKey = JSON.stringify(paths);
+    const originalGeometryKey = JSON.stringify(paths);
+    const geometryKey = variant === 'filled' && filledPaths ? JSON.stringify(filledPaths) : originalGeometryKey;
     const badgeKey = badge ? JSON.stringify(badge) : '';
     const stablePaths = useMemo(() => JSON.parse(geometryKey), [geometryKey]);
     const stableBadge = useMemo(() => badgeKey ? JSON.parse(badgeKey) : undefined, [badgeKey]);
-    const resolvedSeed = seedToNumber(seed ?? geometryKey);
+    const resolvedSeed = seedToNumber(seed ?? originalGeometryKey);
     useEffect(() => {
         const canvas = canvasRef.current;
         if (!canvas)
@@ -162,6 +172,28 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             const dpr = effectiveDpr(3);
             const computed = getComputedStyle(canvas);
             const color = computed.color;
+            const resolveColor = (value) => {
+                if (!value || value === 'currentColor')
+                    return color;
+                const probe = document.createElement('span');
+                probe.style.color = value;
+                // Canvas fallback children inherit its own color and custom properties, not just its parent's.
+                canvas.appendChild(probe);
+                try {
+                    return getComputedStyle(probe).color || color;
+                }
+                finally {
+                    probe.remove();
+                }
+            };
+            const resolvedFill = variant === 'filled' ? resolveColor(fillColor) : color;
+            const resolvePaths = (items) => items.map(path => path.color ? { ...path, color: resolveColor(path.color) } : path);
+            const renderedPaths = variant === 'filled' ? resolvePaths(stablePaths) : stablePaths;
+            const renderedBadge = stableBadge ? { ...stableBadge,
+                fillColor: resolveColor(stableBadge.fillColor ?? fillColor),
+                paths: resolvePaths(stableBadge.paths),
+                filledPaths: stableBadge.filledPaths ? resolvePaths(stableBadge.filledPaths) : undefined,
+            } : undefined;
             const rtl = computed.direction === 'rtl';
             const iconWeight = readRenderToken(computed, '--inkra-icon-stroke-width', pencilRenderDefaults.iconStrokeWidth, 0.3, 3);
             const weightScale = (typeof strokeWidth === 'number' && Number.isFinite(strokeWidth) ? Math.min(3, Math.max(0.3, strokeWidth)) : iconWeight) / 1.2;
@@ -180,9 +212,10 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
                 : readRenderToken(computed, '--inkra-icon-break-count', pencilRenderDefaults.iconBreakCount, 0, 12));
             const key = JSON.stringify([
                 PENCIL_RENDERER_VERSION,
-                'icon-path-pressure-gaps-v4',
+                'icon-path-paper-wash-v8',
                 geometryKey,
                 badgeKey,
+                variant, resolvedFill, renderedPaths, renderedBadge,
                 rtl,
                 resolvedSeed,
                 size,
@@ -202,7 +235,7 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
                 image = undefined;
             }
             if (!image) {
-                image = renderIcon(stablePaths, { seed: resolvedSeed, size, sourceSize, active, color, dpr, badge: stableBadge, rtl, weightScale, roughnessScale, breaks: strokeBreaks, breakCount: strokeBreakCount, pressureVariation: strokeVariation });
+                image = renderIcon(renderedPaths, { seed: resolvedSeed, size, sourceSize, active, color, dpr, variant, fillColor: resolvedFill, badge: renderedBadge, rtl, weightScale, roughnessScale, breaks: strokeBreaks, breakCount: strokeBreakCount, pressureVariation: strokeVariation });
                 imageCache.set(key, image, canvasByteCost(image));
             }
             canvas.width = image.width;
@@ -236,7 +269,9 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             inheritedColor.observe(element, { attributes: true, attributeFilter: ['style', 'class', 'dir', 'data-theme', 'data-inkra-theme'] });
         }
         const colorScheme = window.matchMedia('(prefers-color-scheme: dark)');
+        const forcedColors = window.matchMedia('(forced-colors: active)');
         colorScheme.addEventListener('change', paint);
+        forcedColors.addEventListener('change', paint);
         const stopRecovery = observeCanvasRecovery(() => { lastPaintRef.current = ''; paint(); });
         paint();
         return () => {
@@ -245,10 +280,11 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             stopRecovery();
             inheritedColor.disconnect();
             colorScheme.removeEventListener('change', paint);
+            forcedColors.removeEventListener('change', paint);
         };
-    }, [active, stableBadge, badgeKey, geometryKey, stablePaths, resolvedSeed, size, sourceSize, strokeWidth, intensity, breaks, breakCount, pressureVariation]);
+    }, [active, stableBadge, badgeKey, geometryKey, stablePaths, resolvedSeed, size, sourceSize, strokeWidth, intensity, breaks, breakCount, pressureVariation, variant, fillColor]);
     const accessibilityProps = decorative
         ? { 'aria-hidden': true }
         : { role: props.role ?? 'img' };
-    return (_jsx("canvas", { ...props, ...accessibilityProps, className: ['inkra-pencil-icon', className].filter(Boolean).join(' '), "data-active": active || undefined, "data-composite": Boolean(badge?.paths.length) || undefined, "data-renderer": "inkra-pressure-pencil", ref: canvasRef, style: { width: size, height: size, ...props.style } }));
+    return (_jsx("canvas", { ...props, ...accessibilityProps, className: ['inkra-pencil-icon', className].filter(Boolean).join(' '), "data-active": active || undefined, "data-icon-variant": variant, "data-composite": Boolean(badge?.paths.length) || undefined, "data-renderer": "inkra-pressure-pencil", ref: canvasRef, style: { width: size, height: size, ...props.style } }));
 });

package/dist/PencilText.js

@@ -97,6 +97,9 @@ function measureLocalTextLines(element, liveSource, text, width, height) {
 }
 function paintText(element, source, canvas, text, seed, glyphSeed) {
     const style = getComputedStyle(element);
+    // Plain mode retains the selectable source and font metrics, without painting.
+    if (readRenderToken(style, '--inkra-letter-effect', 1, 0, 1) === 0)
+        return false;
     const { width: localWidth, height: localHeight } = localBorderBox(element, style);
     if (!localWidth || !localHeight || text.length > 4096 || !source.firstChild)
         return false;
@@ -255,7 +258,7 @@ const PencilTextImplementation = forwardRef(function PencilText({ as: Element =
                 ...['color', 'font-family', 'font-size', 'font-weight', 'font-style', 'line-height', 'text-align', 'text-indent',
                     'letter-spacing', 'white-space', 'word-break', 'overflow-wrap', 'direction',
                     'padding-top', 'padding-left', 'padding-right', 'padding-bottom',
-                    '--inkra-letter-variation', '--inkra-letter-breaks', '--inkra-letter-outline',
+                    '--inkra-letter-effect', '--inkra-letter-variation', '--inkra-letter-breaks', '--inkra-letter-outline',
                     '--inkra-letter-fill', '--inkra-letter-grain'].map(name => style.getPropertyValue(name)),
             ]);
         };