@inkra/react 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Inkra
 
-Inkra is a pencil-styled React component library. It includes action, form, overlay, navigation, content and feedback components, plus Calendar, DayAgenda, JourneyMap and deterministic drawing primitives. The first `0.1.0` release is being prepared; this package is still an unpublished candidate unless a corresponding registry release has been announced.
+Inkra is a pencil-styled React component library. It includes action, form, overlay, navigation, content and feedback components, plus Calendar, DayAgenda, JourneyMap and deterministic drawing primitives. This document describes the APIs shipped with this package; see the repository changelog and npm registry for release status.
 
 Source and maintenance: [inkrajs/inkra](https://github.com/inkrajs/inkra).
 
@@ -80,6 +80,18 @@ All standard `button` props, including `disabled`, `name`, `value`, `form`, `ari
 
 `InputNumber` places decrease and increase buttons on either side of a centered numeric input, with no clear button. Keyboard deletion produces `null`; decimal stepping and out-of-range validation remain native. `Slider` supports single/range values, horizontal/vertical layout and `standard` or `inset` appearance.
 
+`InputNumber` supports Shift-click and Shift-arrow increments of 10 by default.
+Use `stepModifiers={[{ shiftKey: true, step: 10 }, { altKey: true, step: 0.1 }]}`
+to configure exact modifier chords with absolute increments, or `[]` to disable
+overrides. The first valid matching rule wins; unspecified modifiers must be
+released. Values remain bounded by `min`/`max`; `step="any"` disables stepping.
+`pressAndHold` defaults to true, with `repeatDelay={400}` and
+`repeatInterval={80}` in milliseconds. Release, cancellation, blur, backgrounding,
+disabling and value boundaries stop repetition. Delay/interval are bounded to
+150-60000/32-60000 ms. Numeric values use pencil lettering at rest and during
+button stepping. Direct text entry deliberately stays native until blur, keeping
+browser-owned incomplete drafts such as `-`, `1.` and `1e` readable.
+
 `Select.Root` uses string values for single selection and string arrays with `multiple`. Multi-select remains open while toggling items and submits repeated values under the same field name. `Select.Clear` is a separate button; never nest it inside the trigger.
 
 `Select.Trigger` supports `startIcon`, `endIcon`, `hideValue`, `hideIndicator`, `iconOnly`, `fullWidth` and `textAlign`. The existing `icon` prop replaces the dropdown indicator. Icon-only mode keeps a square hit target of at least 44px and retains selected text as an accessible description. Provide a Field/ARIA name and Tooltip for icon-only triggers. Decorative slots must not contain interactive controls.
@@ -150,12 +162,31 @@ outside interaction, modal focus trapping and focus return.
 <Skeleton style={{ width: 200, height: 20 }} />
 <Progress label="Uploading" value={60} />
 <Progress aria-label="Loading" value={null} />
+<Progress shape="circular" value={72} diameter={128} thickness={6} aria-label="Download">
+  {({ percent }) => `${Math.round(percent ?? 0)}%`}
+</Progress>
+<Progress shape="circular" value={3} max={5} contentPosition="end" label="Files">
+  <span>3 / 5 files</span>
+</Progress>
 ```
 
 `Badge` variants are `neutral`, `accent`, `success`, `warning`, `danger` and `info`. `Separator` has horizontal/vertical orientation and a decorative opt-out. `Skeleton` is a static, aria-hidden placeholder; mark its loading container `aria-busy`. `Progress` clamps numeric values to `0..max` (default 100); `null` is indeterminate without a fabricated percentage. Always provide a progress label.
 
 `Badge.size` accepts `sm | md | lg` with optional `startIcon` and `endIcon`. `Separator.weight` clamps to 0.3–2 (default 0.9). `Skeleton.radius` uses the existing 0–8px pencil corner contract. `Progress.size` selects a 12/16/24px track (`sm/md/lg`); `dir`, `aria-valuetext`, refs and native DOM attributes remain available. Tooltip exposes the underlying delay, alignment, collision and hoverable-content controls alongside `Content.surfaceRadius`.
 
+Circular Progress uses a grainy pencil arc with naturally tapered ends and an
+empty gap for the remaining progress.
+`size` selects a 64/96/128px diameter; `diameter` overrides it (32-512px), and
+`thickness` sets the base stroke width (1-diameter/8px, affected by global stroke
+settings). `children` accepts non-interactive icons/text or a render function
+receiving normalized `{ value, max, percent }`; unknown value/percent are null.
+`contentPosition` supports `center`, `top`, `bottom`, `start`, and `end`; logical
+sides follow RTL. Circular defaults to center, linear to end (including explicit
+center). Keep center content short; longer descriptions belong outside the ring.
+Always supply a label or ARIA name, even for icon content. Progress updates reveal
+the existing texture; only unknown progress rotates, respecting reduced motion.
+Canvas failures, forced colors and printing retain an SVG progress fallback.
+
 ## Menus And Content
 
 `DropdownMenu` exposes `Root`, `Trigger`, `Portal`, `Content`, `Item`, `CheckboxItem`, `RadioGroup`, `RadioItem`, `Group`, `Label` and `Separator`. It supports controlled open state, placement/collision props, disabled items, keyboard navigation and focus return. Use `Trigger asChild` with a Button; use `Item.destructive` for dangerous actions. Portal content inherits the trigger theme. Submenus are not included yet.
@@ -176,6 +207,133 @@ Content layout options preserve existing defaults:
 - `Avatar.Root.radius` clamps to 0-8px, including pencil and image corners; `bordered={false}` removes the outline. `Avatar.Image.fit` accepts `cover | contain` (default cover).
 - `Table.Root.striped`, `hoverable` and `stickyHeader` default to false. Constrain `Table.Container` with `style={{ maxHeight: 240 }}` for sticky scrolling. `captionSide` accepts `top | bottom`. `Head.align` and `Cell.align` accept logical `start | center | end`, retaining native alignment values for compatibility. Hover feedback does not imply row actions.
 
+## Additional Components
+
+These exports extend the original core component set. The documentation playground includes
+working examples, live property tabs and per-component API/accessibility notes.
+
+| Component | Contract |
+| --- | --- |
+| Toast | `Provider`, `useToastManager`, `createToastManager`; add/update/close/promise notifications, named actions and timer pause managed by Base UI |
+| AlertDialog | Always-modal confirmation; `Root`, `Trigger`, `Portal`, `Backdrop`, `Content`, `Header`, `Body`, `Footer`, `Title`, `Description`, `Cancel`, `Action`; pending blocks user dismissal, async actions use `closeOnAction={false}` |
+| Drawer | Dialog parts plus section layout, four `Content.direction` values and token/custom `size`; focus trap, Escape and return focus, no swipe gesture API |
+| DatePicker | Calendar/Popover composition; single/range local dates, controlled/default values, clear, form fields and localized labels; no UTC conversion |
+| TimePicker | Native time input with clear, disabled/readOnly, min/max/step and optional seconds; browser/OS controls the native presentation |
+| Pagination | Page count/current page, boundary actions and ellipses; buttons change local state rather than pretending to navigate URLs |
+| Empty | Optional `Root`, `Icon`, `Title`, `Description`, `Actions`; no mandatory card or live-region role |
+| ToggleGroup | `Root` and `Item`; array values for single/multiple toggles, roving focus and `aria-pressed`, not tabs |
+| Command | cmdk-backed search, grouped commands, empty/disabled states and optional modal composition |
+| Upload | File selection/drop, type/size/count rejection, removal, progress, cancel and retry; application transport receives `AbortSignal` and `reportProgress` |
+| DataTable | Typed columns, required stable `getRowId`, sorting, filtering, pagination, selection, empty/loading state; native table semantics |
+| Tree | `Root`, `Item`, `ItemContent`, `ItemTitle`, `ItemDescription`; stable keys, expansion and selection via React Aria; no drag/drop |
+| Steps | Ordered `items`, `current`, orientation and optional `onStepChange`; status and disabled steps |
+| Timeline | Ordered `items` with date/title/description/content, semantic `dateTime` and horizontal/vertical orientation |
+
+## Utility Components (Unreleased)
+
+`Slot` is a fixed square visual container for arbitrary icons or content. Static
+slots render a `div`; `interactive` slots render one native button with
+`aria-pressed` selection and native Enter/Space behavior. `empty` preserves
+geometry, `count` reuses Badge, and `renderCount` keeps custom rendering at the
+logical corner. Keep nested controls out of interactive slots. Slot does not
+implement equipment rules, rarity, sorting or drag and drop.
+
+`Hotkey` formats shortcut values for Mac or Windows. `HotkeyInput` records only
+while its native input is focused, supports controlled/uncontrolled values,
+clear, Escape cancellation, read-only/disabled states, IME safeguards and
+caller-owned conflict validation. It does not register global shortcut listeners
+or suppress browser shortcuts.
+
+`NumberTicker` formats values with `Intl.NumberFormat`, optionally animates from
+the currently displayed frame, and can show a temporary signed delta. Reduced
+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.
+
+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,
+Sx, Sp, Oc, No, Dc (10^3 through 10^33, increasing by 10^3).
+Chinese uses 千 (10^3), then 万, 亿, 兆, 京, 垓, 秭, 穰, 沟, 涧, 正, 载, 极,
+恒河沙, 阿僧祇, 那由他, 不可思议, 无量大数 (10^4 through 10^68, increasing by 10^4).
+`numberTickerUnits` exports both tables. A space separates numbers and units by default.
+The default is `false`, preserving existing `formatOptions` behavior. Compact mode
+uses at most one fractional digit by default; customize precision with
+`formatOptions`. Explicit scientific/engineering notation takes priority over compact.
+Currency/percent affixes are preserved. By default rounding can promote the unit
+(999,950 becomes 1 M). Deltas use the same unit
+system with their own precision; announcements and `getValueLabel` receive the
+unabbreviated formatted value. `renderValue` receives the abbreviated value in
+`details.formattedValue`. NumberTicker never changes the supplied numeric value.
+
+`compactOptions` supports:
+
+- `minUnit` / `maxUnit`: allowed unit labels; equal bounds fix the unit. An empty
+  label denotes the unitless base. For example `maxUnit: '万'` keeps 10^8 as `10,000 万`.
+- `separator`: defaults to one space; `''` removes it.
+- `promotionThreshold`: positive multiplier on each unit's factor (default 1).
+  Set 10 to wait until 10,000 before entering K. `promoteAfterRounding: false`
+  compares raw magnitudes instead of rounded current-unit values.
+- `units`: replace the table with `{ factor, label, threshold? }` entries.
+  `threshold` overrides the multiplier with an absolute display-magnitude trigger;
+  e.g. `{ factor: 10000, label: '万', threshold: 100000 }`. Binary factors work too.
+  Entries are sorted without mutation; labels/factors must be unique, factors > 1,
+  and thresholds positive, finite and strictly increasing. Invalid configurations
+  and unknown/reversed bounds throw RangeError. The unitless base is implicit.
+- `overflow`: `unit` keeps the largest permitted unit; `scientific` switches at
+  the next unit's threshold (or extrapolates the last step at the table end).
+  Explicit `maxUnit` defaults to `unit`; otherwise the default is `scientific`.
+
+Use `formatOptions.notation: 'scientific' | 'engineering'` for exponent notation.
+`maximumFractionDigits` controls decimals, `minimumFractionDigits` pads zeros,
+and `roundingMode: 'trunc'` truncates instead of rounding (`halfExpand` is default).
+Other Intl rounding modes are supported when provided by the runtime; unsupported
+nondefault rounding modes throw rather than silently round differently.
+`value`, unit `factor` / `threshold`, and `promotionThreshold` accept
+`number | bigint | string`. Use bigint for exact integers and decimal strings for
+exact fractions or exponents beyond JavaScript's numeric range. Already-rounded
+`number` inputs cannot regain lost digits. Decimal arithmetic uses an isolated
+`decimal.js` context without modifying the application's Decimal settings.
+
+```tsx
+<NumberTicker value={9007199254740993n} showDelta />
+<NumberTicker value="12345678901234567890.123456" formatOptions={{ maximumFractionDigits: 6 }} />
+<NumberTicker value="1.23456789e1000" formatOptions={{ notation: 'scientific' }} />
+```
+
+Strings accept signs, decimal points, e/E exponents and outer whitespace, but
+not grouping separators, hex, empty strings or non-finite spellings. Inputs are
+bounded to 10,000 coefficient digits and written/normalized exponents within
+-10,000..10,000; invalid or oversized exact inputs throw `RangeError`. Decimal
+fractions require exact Intl decimal-string support in the runtime; unsupported
+engines throw rather than silently lose precision. Native number NaN/Infinity
+formatting is unchanged.
+
+`renderValue` and `getValueLabel` retain the input type; prefer the supplied
+formatted text when custom rendering. Deltas between bigints are bigint, between
+numbers are number, and mixed/string deltas are exact decimal strings. Bigint
+animation frames stay integral. Input-type changes or exact arithmetic spanning
+more than 512 digits settle immediately, as do reduced-motion updates.
+`createNumberFormatter` remains a native Intl formatter; use
+`formatTickerValue(formatter, value)` for precise numeric-string formatting.
+
+`prefix` and `suffix` accept icons, text or fragments. Pass `PencilIcon` to keep
+the library material, and `getValueLabel` to describe icon meanings to assistive
+technology; decorative affixes are not announced twice.
+
+`Log` renders caller-ordered records with stable ids, optional level filters and
+pause/follow controls. It follows only append updates while the viewport remains
+near the bottom. The named scroll region supports Home/End and intentionally is
+not a live region, so a long stream is not repeatedly announced. Log does not
+provide persistence, virtualization or transport.
+
+Upload does not send files anywhere unless the application supplies `onUpload`.
+Without a transport, files remain selected, not successfully uploaded. Client
+validation is a convenience; the receiving server must validate files itself.
+DataTable does not replace `Table` and does not promise virtualization, cell
+editing or server-side transport. Tree is not a file-system permission boundary.
+All examples use public sample data.
+
 ## Travel Components
 
 `Calendar` wraps React DayPicker with default `appearance="itinerary"` day cards and optional `appearance="picker"`. It retains single/multiple/range selection, month control, disabled matchers, locale and keyboard navigation. Supply `selected` and `onSelect` for controlled selection. Events have independent `onEventSelect` handling; `displayRange` and `renderDayAccessory` customize the itinerary. Narrow itinerary grids retain seven columns and hide event text while preserving accessible names; picker targets remain at least 44px.
@@ -199,6 +357,33 @@ Content layout options preserve existing defaults:
 <PencilLine orientation="vertical" seed="sidebar-divider" className="sidebar-divider" />
 ```
 
+### Rendering tokens
+
+`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
+text within that scope without changing layout, selectable text, or labels.
+
+`PencilLine` reads `--inkra-stroke-width` (0.3-3) and
+`--inkra-stroke-amplitude` (0-4) when `weight` or `roughness` is omitted.
+Explicit props take precedence. These tokens also scale surface outlines and icon
+strokes relative to their original presets, including button/card/input borders.
+The default values are 2 and 1.5. They do not change layout or text lettering.
+
+Surface fills read `--inkra-wash-strength` (0-1, default 0.8),
+`--inkra-wash-spacing` (1-6, default 2), `--inkra-wash-roughness` (0-6,
+default 3), and `--inkra-wash-angle` (-85 to 85 degrees, default -45).
+Strength scales each variant's original light/dark pigment intensity relative to
+the original 0.48 reference. These settings affect button fills, selections
+and swatches, not paper or lettering. Selection reveals follow the chosen angle.
+
+Only self/ancestor appearance changes invalidate decoration, not unrelated theme
+subtrees. Unchanged computed paint settings are reused, including when a dialog
+changes body pointer events or scroll locks. Rendering settings are part of the
+bounded texture cache keys. No page remount is needed. Forced-color, print, and
+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.

package/dist/PencilIcon.js

@@ -4,6 +4,7 @@ import { BoundedCache, PENCIL_RENDERER_VERSION, canvasByteCost, canvasIsUsable,
 import { observeCanvasRecovery } from './internal/recovery.js';
 import { seedToNumber } from './internal/random.js';
 import { pencilStroke } from './internal/stroke.js';
+import { maxStrokeRoughness, pencilRenderDefaults, readRenderToken } from './internal/renderTokens.js';
 const geometryCache = new BoundedCache(256, 180000);
 const imageCache = new BoundedCache(128, 24 * 1024 * 1024);
 function cachedPathParts(data) {
@@ -45,6 +46,7 @@ function drawFallbackPath(context, data, color, mode, weightScale = 1) {
 function renderIcon(paths, options) {
     const { seed, size, sourceSize, active, color, dpr } = options;
     const weightScale = options.weightScale ?? 1;
+    const roughnessScale = options.roughnessScale ?? 1;
     const canvas = document.createElement('canvas');
     canvas.width = Math.round(size * dpr);
     canvas.height = Math.round(size * dpr);
@@ -76,7 +78,7 @@ function renderIcon(paths, options) {
         try {
             const parts = cachedPathParts(path.d);
             for (const points of parts) {
-                pencilStroke(context, points, color, (mode === 'scuff' ? 0.55 : 1.65) * weightScale, pathSeed, 0.3, mode === 'scuff' ? 1 : 3, false, {
+                pencilStroke(context, points, color, (mode === 'scuff' ? 0.55 : 1.65) * weightScale, pathSeed, 0.3 * roughnessScale, mode === 'scuff' ? 1 : 3, false, {
                     variation: 0.82,
                     breaks: 0.18,
                     grain: 0.68,
@@ -91,7 +93,7 @@ function renderIcon(paths, options) {
         }
     });
     if (active) {
-        pencilStroke(context, [[sourceSize * 0.2, sourceSize - 2], [sourceSize * 0.5, sourceSize - 1.5], [sourceSize * 0.8, sourceSize - 2.2]], color, 1.1, seed + 977, 0.25, 3, false, { variation: 0.8, breaks: 0.25, grain: 0.7, gain: 2.8, step: 0.35 });
+        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, breaks: 0.25, grain: 0.7, gain: 2.8, step: 0.35 });
     }
     if (options.badge?.paths.length) {
         const badge = options.badge;
@@ -104,7 +106,7 @@ function renderIcon(paths, options) {
         const y = position.startsWith('top') ? 0 : 40 - extent;
         const badgeImage = renderIcon(badge.paths, {
             seed: seed + 1543, size: size * scale, sourceSize: badgeSourceSize, active: false, color, dpr,
-            weightScale: 1 / scale,
+            weightScale: weightScale / scale, roughnessScale,
         });
         const mask = document.createElement('canvas');
         mask.width = badgeImage.width;
@@ -135,6 +137,7 @@ function renderIcon(paths, options) {
 }
 export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge, className = '', decorative = true, paths, seed, size = 40, sourceSize = 32, ...props }, forwardedRef) {
     const canvasRef = useRef(null);
+    const lastPaintRef = useRef('');
     useImperativeHandle(forwardedRef, () => canvasRef.current);
     const geometryKey = useMemo(() => JSON.stringify(paths), [paths]);
     const badgeKey = useMemo(() => badge ? JSON.stringify(badge) : '', [badge]);
@@ -144,7 +147,6 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
         if (!canvas)
             return undefined;
         let disposed = false;
-        let lastPaint = '';
         const paint = () => {
             if (disposed)
                 return;
@@ -152,6 +154,8 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             const computed = getComputedStyle(canvas);
             const color = computed.color;
             const rtl = computed.direction === 'rtl';
+            const weightScale = readRenderToken(computed, '--inkra-stroke-width', pencilRenderDefaults.strokeWidth, 0.3, 3) / 1.2;
+            const roughnessScale = readRenderToken(computed, '--inkra-stroke-amplitude', pencilRenderDefaults.strokeRoughness, 0, maxStrokeRoughness) / 0.6;
             const key = JSON.stringify([
                 PENCIL_RENDERER_VERSION,
                 geometryKey,
@@ -163,8 +167,9 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
                 active,
                 color,
                 dpr,
+                weightScale, roughnessScale,
             ]);
-            if (key === lastPaint && canvasIsUsable(canvas))
+            if (key === lastPaintRef.current && canvasIsUsable(canvas))
                 return;
             let image = imageCache.get(key);
             if (image && !canvasIsUsable(image)) {
@@ -172,7 +177,7 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
                 image = undefined;
             }
             if (!image) {
-                image = renderIcon(paths, { seed: resolvedSeed, size, sourceSize, active, color, dpr, badge, rtl });
+                image = renderIcon(paths, { seed: resolvedSeed, size, sourceSize, active, color, dpr, badge, rtl, weightScale, roughnessScale });
                 imageCache.set(key, image, canvasByteCost(image));
             }
             canvas.width = image.width;
@@ -181,26 +186,19 @@ export const PencilIcon = forwardRef(function PencilIcon({ active = false, badge
             if (!context || context.isContextLost?.())
                 return;
             context.drawImage(image, 0, 0);
-            lastPaint = key;
+            lastPaintRef.current = key;
         };
-        const appearance = new MutationObserver(paint);
-        appearance.observe(document.documentElement, {
-            attributes: true,
-            subtree: true,
-            attributeFilter: ['data-theme', 'data-inkra-theme'],
-        });
         const inheritedColor = new MutationObserver(paint);
         for (let element = canvas; element; element = element.parentElement) {
-            inheritedColor.observe(element, { attributes: true, attributeFilter: ['style', 'class', 'dir'] });
+            inheritedColor.observe(element, { attributes: true, attributeFilter: ['style', 'class', 'dir', 'data-theme', 'data-inkra-theme'] });
         }
         const colorScheme = window.matchMedia('(prefers-color-scheme: dark)');
         colorScheme.addEventListener('change', paint);
-        const stopRecovery = observeCanvasRecovery(() => { lastPaint = ''; paint(); });
+        const stopRecovery = observeCanvasRecovery(() => { lastPaintRef.current = ''; paint(); });
         paint();
         return () => {
             disposed = true;
             stopRecovery();
-            appearance.disconnect();
             inheritedColor.disconnect();
             colorScheme.removeEventListener('change', paint);
         };

package/dist/PencilLine.js

@@ -5,6 +5,7 @@ import { observeCanvasRecovery } from './internal/recovery.js';
 import { seedToNumber } from './internal/random.js';
 import { createPencilLinePoints, pencilLineHasDrawableSize } from './internal/line.js';
 import { pencilStroke } from './internal/stroke.js';
+import { maxStrokeRoughness, pencilRenderDefaults, readRenderToken } from './internal/renderTokens.js';
 const lineCache = new BoundedCache(96, 12 * 1024 * 1024);
 function renderLine(width, height, color, seed, weight, roughness, orientation, dpr) {
     const canvas = document.createElement('canvas');
@@ -17,7 +18,7 @@ function renderLine(width, height, color, seed, weight, roughness, orientation,
     pencilStroke(context, createPencilLinePoints(width, height, orientation, roughness), color, weight, seed, roughness, 3, false, { variation: 0.82, breaks: 0.18, grain: 0.68, gain: 2.6, step: 0.5, taperLength: 1.4 });
     return canvas;
 }
-export const PencilLine = forwardRef(function PencilLine({ className = '', orientation = 'horizontal', roughness = 0.6, seed = 'inkra-pencil-line', weight = 1.2, ...props }, forwardedRef) {
+export const PencilLine = forwardRef(function PencilLine({ className = '', orientation = 'horizontal', roughness, seed = 'inkra-pencil-line', weight, ...props }, forwardedRef) {
     const canvasRef = useRef(null);
     useImperativeHandle(forwardedRef, () => canvasRef.current);
     useEffect(() => {
@@ -26,6 +27,7 @@ export const PencilLine = forwardRef(function PencilLine({ className = '', orien
             return undefined;
         let frame = 0;
         let disposed = false;
+        let lastPaint = '';
         const paint = () => {
             frame = 0;
             if (disposed)
@@ -35,18 +37,23 @@ export const PencilLine = forwardRef(function PencilLine({ className = '', orien
             if (!pencilLineHasDrawableSize(width, height, orientation))
                 return;
             const dpr = effectiveDpr(2);
-            const color = getComputedStyle(canvas).color;
+            const style = getComputedStyle(canvas);
+            const color = style.color;
+            const resolvedWeight = weight ?? readRenderToken(style, '--inkra-stroke-width', pencilRenderDefaults.strokeWidth, 0.3, 3);
+            const resolvedRoughness = roughness ?? readRenderToken(style, '--inkra-stroke-amplitude', pencilRenderDefaults.strokeRoughness, 0, maxStrokeRoughness);
             const numericSeed = seedToNumber(seed);
             const key = JSON.stringify([
-                PENCIL_RENDERER_VERSION, orientation, width, height, color, numericSeed, weight, roughness, dpr,
+                PENCIL_RENDERER_VERSION, orientation, width, height, color, numericSeed, resolvedWeight, resolvedRoughness, dpr,
             ]);
+            if (key === lastPaint && canvasIsUsable(canvas))
+                return;
             let image = lineCache.get(key);
             if (image && !canvasIsUsable(image)) {
                 lineCache.delete(key);
                 image = undefined;
             }
             if (!image) {
-                image = renderLine(width, height, color, numericSeed, weight, roughness, orientation, dpr);
+                image = renderLine(width, height, color, numericSeed, resolvedWeight, resolvedRoughness, orientation, dpr);
                 lineCache.set(key, image, canvasByteCost(image));
             }
             canvas.width = image.width;
@@ -55,6 +62,7 @@ export const PencilLine = forwardRef(function PencilLine({ className = '', orien
             if (!context || context.isContextLost?.())
                 return;
             context.drawImage(image, 0, 0);
+            lastPaint = key;
         };
         const schedule = () => {
             if (!frame)
@@ -62,21 +70,19 @@ export const PencilLine = forwardRef(function PencilLine({ className = '', orien
         };
         const resize = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
         resize?.observe(canvas);
-        const appearance = new MutationObserver(schedule);
-        appearance.observe(document.documentElement, {
-            attributes: true,
-            subtree: true,
-            attributeFilter: ['data-theme', 'data-inkra-theme'],
-        });
         const colorScheme = window.matchMedia('(prefers-color-scheme: dark)');
+        const inheritedStyle = new MutationObserver(schedule);
+        for (let element = canvas; element; element = element.parentElement) {
+            inheritedStyle.observe(element, { attributes: true, attributeFilter: ['style', 'class', 'data-theme', 'data-inkra-theme'] });
+        }
         colorScheme.addEventListener('change', schedule);
-        const stopRecovery = observeCanvasRecovery(schedule);
+        const stopRecovery = observeCanvasRecovery(() => { lastPaint = ''; schedule(); });
         paint();
         return () => {
             disposed = true;
             stopRecovery();
             resize?.disconnect();
-            appearance.disconnect();
+            inheritedStyle.disconnect();
             colorScheme.removeEventListener('change', schedule);
             cancelAnimationFrame(frame);
         };