# DOC-0029 — NumberBox Operation / HTML Functional Class

## 0. Document information

- UI: `UI-029` / Component: `#029 NumberBox`
- Runtime: `BoneNumberBox v1.0.19`
- DOC Version: `1.0.3`
- HTML Functional Class: `bf-numberbox`
- Shared DOC runtime is referenced but not modified.

## 1. What NumberBox does

NumberBox is a single-line numeric editor. It deliberately separates the text being edited from the finite number/null that has been committed and from display-only formatting.

### 1.1 Terms you need first

- **editingValue** — text currently being edited, for example `"1e3"`.
- **committedValue** — the accepted finite `number` or `null` used by Bone and OUT.
- **displayValue** — ordinary formatted text shown by the input.
- **voucherDisplayValue** — display-only voucher text. Currency marks, grouping separators, grid lines and negative glyphs never enter OUT.
- **commit** — validates editingValue and updates committedValue only when Validation and Security permit it.
- **Validation** — required/min/max/step checks.
- **Security** — rejects unsafe types, NaN/Infinity, unsafe strings/accessors and excessive lengths before state changes.

### 1.2 Basic operation

1. Type a numeric expression accepted by the editing contract.
2. Press Enter or blur to commit with the default settings.
3. Validation failure preserves the previous committed value unless `commitInvalid=true`; Security failures are never bypassed.
4. Escape resets the editing text to the committed value.
5. Voucher mode shows a display-only digit layout when not actively editing.

## 2. HTML Functional Class `bf-numberbox`

### 2.1 Minimal use

```html
<input class="bf-numberbox" type="number" value="1000">
```

The declaration input is hidden after mount and a real `BoneNumberBox v1.0.19` is inserted. A successful commit is mirrored back to the declaration input value.

### 2.2 Setting example

```html
<input class="bf-numberbox" type="number" value="-1234567.89" data-display-decimal-places="2" data-use-grouping="true" data-voucher-mode="true" data-voucher-yen-mark="true" data-voucher-negative-red="true">
```

### 2.3 Settings → live rendering

#### Number / validation

[[BF-NUMBERBOX-SAMPLE:basic]]
[[BF-NUMBERBOX-SAMPLE:minmax]]
[[BF-NUMBERBOX-SAMPLE:decimal2]]
[[BF-NUMBERBOX-SAMPLE:display2]]
[[BF-NUMBERBOX-SAMPLE:grouping]]
[[BF-NUMBERBOX-SAMPLE:roundHalf]]
[[BF-NUMBERBOX-SAMPLE:roundUp]]
[[BF-NUMBERBOX-SAMPLE:roundDown]]

#### Theme / appearance

[[BF-NUMBERBOX-SAMPLE:themeDefault]]
[[BF-NUMBERBOX-SAMPLE:themeDark]]
[[BF-NUMBERBOX-SAMPLE:themeLight]]
[[BF-NUMBERBOX-SAMPLE:themeNeon]]
[[BF-NUMBERBOX-SAMPLE:bgTransparent]]
[[BF-NUMBERBOX-SAMPLE:bgRgba]]
[[BF-NUMBERBOX-SAMPLE:appNormal]]
[[BF-NUMBERBOX-SAMPLE:appFlat]]
[[BF-NUMBERBOX-SAMPLE:appBorderless]]
[[BF-NUMBERBOX-SAMPLE:appInherit]]

#### Alignment / state

[[BF-NUMBERBOX-SAMPLE:alignAuto]]
[[BF-NUMBERBOX-SAMPLE:alignLeft]]
[[BF-NUMBERBOX-SAMPLE:alignCenter]]
[[BF-NUMBERBOX-SAMPLE:alignRight]]
[[BF-NUMBERBOX-SAMPLE:disabled]]
[[BF-NUMBERBOX-SAMPLE:readonly]]
[[BF-NUMBERBOX-SAMPLE:required]]
[[BF-NUMBERBOX-SAMPLE:select]]
[[BF-NUMBERBOX-SAMPLE:commitPolicy]]

#### Voucher

[[BF-NUMBERBOX-SAMPLE:voucherBasic]]
[[BF-NUMBERBOX-SAMPLE:voucherYen]]
[[BF-NUMBERBOX-SAMPLE:voucherGridOff]]
[[BF-NUMBERBOX-SAMPLE:voucherTriangle]]
[[BF-NUMBERBOX-SAMPLE:voucherRed]]
[[BF-NUMBERBOX-SAMPLE:voucherDigits]]
[[BF-NUMBERBOX-SAMPLE:voucherAutoFont]]
[[BF-NUMBERBOX-SAMPLE:voucherFixedFont]]
[[BF-NUMBERBOX-SAMPLE:voucherHoverEdit]]
[[BF-NUMBERBOX-SAMPLE:voucherStyle]]

#### Active effect

[[BF-NUMBERBOX-SAMPLE:activeNormal]]
[[BF-NUMBERBOX-SAMPLE:activeNeon]]
[[BF-NUMBERBOX-SAMPLE:activeSpin]]
[[BF-NUMBERBOX-SAMPLE:activeCross]]
[[BF-NUMBERBOX-SAMPLE:activeBlink]]

#### Position

[[BF-NUMBERBOX-SAMPLE:posTopLeft]]
[[BF-NUMBERBOX-SAMPLE:posTopCenter]]
[[BF-NUMBERBOX-SAMPLE:posTopRight]]
[[BF-NUMBERBOX-SAMPLE:posMiddleLeft]]
[[BF-NUMBERBOX-SAMPLE:posCenter]]
[[BF-NUMBERBOX-SAMPLE:posMiddleRight]]
[[BF-NUMBERBOX-SAMPLE:posBottomLeft]]
[[BF-NUMBERBOX-SAMPLE:posBottomCenter]]
[[BF-NUMBERBOX-SAMPLE:posBottomRight]]

#### Parent / security

[[BF-NUMBERBOX-SAMPLE:sizeCustom]]
[[BF-NUMBERBOX-SAMPLE:inheritParent]]
[[BF-NUMBERBOX-SAMPLE:security]]
[[BF-NUMBERBOX-SAMPLE:...]]

### 2.4 HTML-declarable Properties — quick guide

- `placeholder` — Placeholder text shown only while the editing field is empty.
- `disabled` — Disables focus, user editing, and commit while keeping the current value visible.
- `readonly` — Keeps the value readable/selectable but blocks user edits and commit from the editor.
- `required` — Makes null/empty input fail Validation with NUMBERBOX_REQUIRED.
- `min` — Sets the minimum numeric value accepted by Validation.
- `max` — Sets the maximum numeric value accepted by Validation.
- `step` — Checks that the committed number follows the configured numeric increment.
- `decimalPlaces` — Commit/setValue/Joint IN round the actual committed number. OUT therefore uses the rounded number.
- `displayDecimalPlaces` — For example 1000 can be shown as 1000.00 while committedValue and OUT remain numeric 1000.
- `useGrouping` — For example 1234567.89 is displayed as 1,234,567.89 while the underlying number stays unchanged.
- `roundingMode` — Selects how decimalPlaces and displayDecimalPlaces round digits.
- `name` — Sets the internal input name used by form integration.
- `autocomplete` — Passes the browser autocomplete hint to the internal input.
- `spellcheck` — Keeps spellcheck disabled for numeric editing.
- `inputMode` — Sets the browser inputMode hint, typically decimal for numeric keyboards.
- `enterCommit` — Controls whether Enter commits editingValue by default.
- `blurCommit` — Controls whether leaving focus commits editingValue.
- `commitInvalid` — Allows Validation-invalid values to commit; Security rejections are never bypassed.
- `selectOnFocus` — Selects the full editing text when the field receives focus.
- `ariaLabel` — Sets the accessible label on the internal input.
- `className` — Adds an extra class to the Runtime root at create time.
- `theme` — Selects the base surface, text, border, and accent theme.
- `backgroundColor` — Overrides only the NumberBox background with theme, transparent, or a HEX color.
- `appearance` — Changes the normal/flat/borderless presentation or enables parent inheritance.
- `inheritParent` — Parent size/background/text/border/radius/text-align take priority over standalone width/height/position/inputAlign.
- `width` — Sets standalone Runtime width in pixels.
- `height` — Sets standalone Runtime height in pixels.
- `position` — Places the NumberBox at one of nine positions inside its layout container.
- `inputAlign` — Aligns numeric text left, center, or right; auto resolves to right for NumberBox.
- `voucherMode` — Shows a voucher-style digit layout while not actively editing.
- `voucherYenMark` — The visible yen sign is display-only and is never inserted into committedValue or OUT.
- `voucherGridLines` — Switches voucher separators between grid lines and display punctuation.
- `voucherAutoFontSize` — Automatically fits voucher text size to cell width.
- `voucherFontSize` — Sets the voucher font size when automatic sizing is disabled.
- `voucherDigitCount` — Sets the total number of voucher digit cells.
- `voucherLineColor` — Sets the normal voucher grid-line HEX color.
- `voucherLineWidth` — Sets normal voucher grid-line width.
- `voucherGroupLineWidth` — Sets the thicker line width used at three-digit group boundaries.
- `voucherDecimalLineColor` — Sets the separator color between integer and decimal sections.
- `voucherDecimalLineWidth` — Sets the separator width between integer and decimal sections.
- `voucherNegativeMark` — Chooses minus, triangle, or no visible negative mark in voucher mode.
- `voucherNegativeRed` — Only the voucher presentation becomes red for negative values; the committed number is unchanged.
- `voucherHoverEdit` — Temporarily returns to the editable input while hovering voucher display.
- `activeBorderEffect` — The effect appears only while focused and is detached on blur; actual rendering is delegated to #022.
- `activeEffectColor` — Chooses the active effect color from theme or a solid HEX value.
- `activeEffectDirection` — Sets clockwise or counterclockwise movement for directional effects.
- `activeEffectSpeed` — Sets slow, normal, or fast timing for animated active effects.
- `securityMaxLength` — Over-limit editing or input is rejected before unsafe state replaces the last safe committed value.

## 3. Default Properties — detailed reference

### 3.1 `placeholder`

- Type: `string`
- Runtime Default: `""`
- HTML: `placeholder / data-placeholder`
- Purpose: Placeholder text shown only while the editing field is empty.
- Allowed / range: a value of the documented type; see Runtime validation for the exact contract
- Invalid example: `a value outside the documented `placeholder` contract`
- Fix example: `use a value accepted by `placeholder / data-placeholder` and the Runtime contract`
- Visible / runtime behavior: Placeholder text shown only while the editing field is empty.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.2 `disabled`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `disabled / data-disabled`
- Purpose: Disables focus, user editing, and commit while keeping the current value visible.
- Allowed / range: true / false
- Invalid example: `data-disabled="maybe"`
- Fix example: `use a value accepted by `disabled / data-disabled` and the Runtime contract`
- Visible / runtime behavior: Disables focus, user editing, and commit while keeping the current value visible.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.3 `readonly`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `readonly / data-readonly`
- Purpose: Keeps the value readable/selectable but blocks user edits and commit from the editor.
- Allowed / range: true / false
- Invalid example: `data-readonly="maybe"`
- Fix example: `use a value accepted by `readonly / data-readonly` and the Runtime contract`
- Visible / runtime behavior: Keeps the value readable/selectable but blocks user edits and commit from the editor.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.4 `required`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `required / data-required`
- Purpose: Makes null/empty input fail Validation with NUMBERBOX_REQUIRED.
- Allowed / range: true / false
- Invalid example: `data-required="maybe"`
- Fix example: `use a value accepted by `required / data-required` and the Runtime contract`
- Visible / runtime behavior: Makes null/empty input fail Validation with NUMBERBOX_REQUIRED.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.5 `min`

- Type: `number|null`
- Runtime Default: `null`
- HTML: `min / data-min`
- Purpose: Sets the minimum numeric value accepted by Validation.
- Allowed / range: finite number or null; min must be <= max
- Invalid example: `a value outside the documented `min` contract`
- Fix example: `use a value accepted by `min / data-min` and the Runtime contract`
- Visible / runtime behavior: Sets the minimum numeric value accepted by Validation.
- Related / conflict: max / step / validate / commit

### 3.6 `max`

- Type: `number|null`
- Runtime Default: `null`
- HTML: `max / data-max`
- Purpose: Sets the maximum numeric value accepted by Validation.
- Allowed / range: finite number or null; max must be >= min
- Invalid example: `a value outside the documented `max` contract`
- Fix example: `use a value accepted by `max / data-max` and the Runtime contract`
- Visible / runtime behavior: Sets the maximum numeric value accepted by Validation.
- Related / conflict: min / step / validate / commit

### 3.7 `step`

- Type: `number|"any"`
- Runtime Default: `"any"`
- HTML: `step / data-step`
- Purpose: Checks that the committed number follows the configured numeric increment.
- Allowed / range: "any" or a finite number > 0
- Invalid example: `step="0"`
- Fix example: `step="0.5"`
- Visible / runtime behavior: Checks that the committed number follows the configured numeric increment.
- Related / conflict: min / validate / commit

### 3.8 `decimalPlaces`

- Type: `integer|null`
- Runtime Default: `null`
- HTML: `data-decimal-places`
- Purpose: Rounds the committed numeric value itself to the requested number of decimal places.
- Allowed / range: null or integer 0..15
- Invalid example: `data-decimal-places="16"`
- Fix example: `data-decimal-places="2"`
- Visible / runtime behavior: Commit/setValue/Joint IN round the actual committed number. OUT therefore uses the rounded number.
- Related / conflict: roundingMode / displayDecimalPlaces / commit / setValue

### 3.9 `displayDecimalPlaces`

- Type: `integer|null`
- Runtime Default: `null`
- HTML: `data-display-decimal-places`
- Purpose: Formats only the displayed text to a fixed decimal count; it does not change the committed number.
- Allowed / range: null or integer 0..20
- Invalid example: `data-display-decimal-places="21"`
- Fix example: `data-display-decimal-places="2"`
- Visible / runtime behavior: For example 1000 can be shown as 1000.00 while committedValue and OUT remain numeric 1000.
- Related / conflict: decimalPlaces / roundingMode / useGrouping

### 3.10 `useGrouping`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-use-grouping`
- Purpose: Adds thousands separators to display text without changing the numeric value.
- Allowed / range: true / false
- Invalid example: `data-use-grouping="maybe"`
- Fix example: `use a value accepted by `data-use-grouping` and the Runtime contract`
- Visible / runtime behavior: For example 1234567.89 is displayed as 1,234,567.89 while the underlying number stays unchanged.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.11 `roundingMode`

- Type: `enum`
- Runtime Default: `"half-up"`
- HTML: `data-rounding-mode`
- Purpose: Selects how decimalPlaces and displayDecimalPlaces round digits.
- Allowed / range: half-up / up / down
- Invalid example: `data-rounding-mode="bankers"`
- Fix example: `data-rounding-mode="half-up"`
- Visible / runtime behavior: Selects how decimalPlaces and displayDecimalPlaces round digits.
- Related / conflict: decimalPlaces / displayDecimalPlaces

### 3.12 `name`

- Type: `string`
- Runtime Default: `""`
- HTML: `name / data-name`
- Purpose: Sets the internal input name used by form integration.
- Allowed / range: a value of the documented type; see Runtime validation for the exact contract
- Invalid example: `a value outside the documented `name` contract`
- Fix example: `use a value accepted by `name / data-name` and the Runtime contract`
- Visible / runtime behavior: Sets the internal input name used by form integration.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.13 `autocomplete`

- Type: `string`
- Runtime Default: `"off"`
- HTML: `autocomplete / data-autocomplete`
- Purpose: Passes the browser autocomplete hint to the internal input.
- Allowed / range: a value of the documented type; see Runtime validation for the exact contract
- Invalid example: `a value outside the documented `autocomplete` contract`
- Fix example: `use a value accepted by `autocomplete / data-autocomplete` and the Runtime contract`
- Visible / runtime behavior: Passes the browser autocomplete hint to the internal input.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.14 `spellcheck`

- Type: `boolean (runtime-fixed)`
- Runtime Default: `false`
- HTML: `spellcheck / data-spellcheck`
- Purpose: Keeps spellcheck disabled for numeric editing.
- Allowed / range: Runtime-fixed false
- Invalid example: `a value outside the documented `spellcheck` contract`
- Fix example: `use a value accepted by `spellcheck / data-spellcheck` and the Runtime contract`
- Visible / runtime behavior: Keeps spellcheck disabled for numeric editing.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.15 `inputMode`

- Type: `string`
- Runtime Default: `"decimal"`
- HTML: `inputmode / data-input-mode`
- Purpose: Sets the browser inputMode hint, typically decimal for numeric keyboards.
- Allowed / range: a value of the documented type; see Runtime validation for the exact contract
- Invalid example: `a value outside the documented `inputMode` contract`
- Fix example: `use a value accepted by `inputmode / data-input-mode` and the Runtime contract`
- Visible / runtime behavior: Sets the browser inputMode hint, typically decimal for numeric keyboards.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.16 `enterCommit`

- Type: `boolean`
- Runtime Default: `true`
- HTML: `data-enter-commit`
- Purpose: Controls whether Enter commits editingValue by default.
- Allowed / range: true / false
- Invalid example: `data-enter-commit="maybe"`
- Fix example: `use a value accepted by `data-enter-commit` and the Runtime contract`
- Visible / runtime behavior: Controls whether Enter commits editingValue by default.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.17 `blurCommit`

- Type: `boolean`
- Runtime Default: `true`
- HTML: `data-blur-commit`
- Purpose: Controls whether leaving focus commits editingValue.
- Allowed / range: true / false
- Invalid example: `data-blur-commit="maybe"`
- Fix example: `use a value accepted by `data-blur-commit` and the Runtime contract`
- Visible / runtime behavior: Controls whether leaving focus commits editingValue.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.18 `commitInvalid`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-commit-invalid`
- Purpose: Allows Validation-invalid values to commit; Security rejections are never bypassed.
- Allowed / range: true / false
- Invalid example: `data-commit-invalid="maybe"`
- Fix example: `use a value accepted by `data-commit-invalid` and the Runtime contract`
- Visible / runtime behavior: Allows Validation-invalid values to commit; Security rejections are never bypassed.
- Related / conflict: Validation / Security / commit

### 3.19 `selectOnFocus`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-select-on-focus`
- Purpose: Selects the full editing text when the field receives focus.
- Allowed / range: true / false
- Invalid example: `data-select-on-focus="maybe"`
- Fix example: `use a value accepted by `data-select-on-focus` and the Runtime contract`
- Visible / runtime behavior: Selects the full editing text when the field receives focus.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.20 `ariaLabel`

- Type: `string`
- Runtime Default: `""`
- HTML: `aria-label / data-aria-label`
- Purpose: Sets the accessible label on the internal input.
- Allowed / range: a value of the documented type; see Runtime validation for the exact contract
- Invalid example: `a value outside the documented `ariaLabel` contract`
- Fix example: `use a value accepted by `aria-label / data-aria-label` and the Runtime contract`
- Visible / runtime behavior: Sets the accessible label on the internal input.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.21 `className`

- Type: `string`
- Runtime Default: `""`
- HTML: `data-class-name`
- Purpose: Adds an extra class to the Runtime root at create time.
- Allowed / range: a value of the documented type; see Runtime validation for the exact contract
- Invalid example: `a value outside the documented `className` contract`
- Fix example: `use a value accepted by `data-class-name` and the Runtime contract`
- Visible / runtime behavior: Adds an extra class to the Runtime root at create time.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.22 `theme`

- Type: `enum`
- Runtime Default: `"default"`
- HTML: `data-theme`
- Purpose: Selects the base surface, text, border, and accent theme.
- Allowed / range: default / dark / light / neon
- Invalid example: `data-theme="blue"`
- Fix example: `data-theme="neon"`
- Visible / runtime behavior: Selects the base surface, text, border, and accent theme.
- Related / conflict: backgroundColor / activeEffectColor

### 3.23 `backgroundColor`

- Type: `color`
- Runtime Default: `"theme"`
- HTML: `data-background-color`
- Purpose: Overrides only the NumberBox background with theme, transparent, or a HEX color.
- Allowed / range: theme / transparent / #RGB / #RGBA / #RRGGBB / #RRGGBBAA
- Invalid example: `backgroundColor="red" (named colors are not accepted by this contract)`
- Fix example: `data-background-color="#26354acc"`
- Visible / runtime behavior: Overrides only the NumberBox background with theme, transparent, or a HEX color.
- Related / conflict: theme / #040 ColorPicker

### 3.24 `appearance`

- Type: `enum`
- Runtime Default: `"normal"`
- HTML: `data-appearance`
- Purpose: Changes the normal/flat/borderless presentation or enables parent inheritance.
- Allowed / range: normal / flat / borderless / inherit
- Invalid example: `a value outside the documented `appearance` contract`
- Fix example: `use a value accepted by `data-appearance` and the Runtime contract`
- Visible / runtime behavior: Changes the normal/flat/borderless presentation or enables parent inheritance.
- Related / conflict: inheritParent

### 3.25 `inheritParent`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-inherit-parent`
- Purpose: Makes the Runtime follow parent size and visual/text alignment styles.
- Allowed / range: true / false
- Invalid example: `data-inherit-parent="maybe"`
- Fix example: `use a value accepted by `data-inherit-parent` and the Runtime contract`
- Visible / runtime behavior: Parent size/background/text/border/radius/text-align take priority over standalone width/height/position/inputAlign.
- Related / conflict: width / height / position / inputAlign

### 3.26 `width`

- Type: `number px`
- Runtime Default: `320`
- HTML: `data-width`
- Purpose: Sets standalone Runtime width in pixels.
- Allowed / range: 40..4000 px
- Invalid example: `data-width="20" (below 40 px)`
- Fix example: `data-width="320"`
- Visible / runtime behavior: Sets standalone Runtime width in pixels.
- Related / conflict: inheritParent

### 3.27 `height`

- Type: `number px`
- Runtime Default: `44`
- HTML: `data-height`
- Purpose: Sets standalone Runtime height in pixels.
- Allowed / range: 24..2000 px
- Invalid example: `data-height="10" (below 24 px)`
- Fix example: `data-height="44"`
- Visible / runtime behavior: Sets standalone Runtime height in pixels.
- Related / conflict: inheritParent

### 3.28 `position`

- Type: `enum`
- Runtime Default: `"center"`
- HTML: `data-position`
- Purpose: Sets one of nine positions **inside a CSS Grid parent**. The Runtime applies `justify-self / align-self` to the NumberBox root.
- Allowed / range: top-left / top-center / top-right / middle-left / center / middle-right / bottom-left / bottom-center / bottom-right
- Invalid example: `data-position="left"`
- Fix example: `data-position="bottom-right"`
- Visible / runtime behavior: Works as a 9-way position in the formal `display:grid` Preview. A plain block/flex parent does not guarantee the same result. `inheritParent=true` overrides it with stretch.
- Related / conflict: inheritParent / parent layout

### 3.29 `inputAlign`

- Type: `enum`
- Runtime Default: `"right"`
- HTML: `data-input-align`
- Purpose: Aligns numeric text left, center, or right; auto resolves to right for NumberBox.
- Allowed / range: auto / left / center / right
- Invalid example: `a value outside the documented `inputAlign` contract`
- Fix example: `use a value accepted by `data-input-align` and the Runtime contract`
- Visible / runtime behavior: Aligns numeric text left, center, or right; auto resolves to right for NumberBox.
- Related / conflict: inheritParent

### 3.30 `voucherMode`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-voucher-mode`
- Purpose: Shows a voucher-style digit layout while not actively editing.
- Allowed / range: true / false
- Invalid example: `data-voucher-mode="maybe"`
- Fix example: `use a value accepted by `data-voucher-mode` and the Runtime contract`
- Visible / runtime behavior: Shows a voucher-style digit layout while not actively editing.
- Related / conflict: voucherHoverEdit / displayDecimalPlaces

### 3.31 `voucherYenMark`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-voucher-yen-mark`
- Purpose: Adds a display-only yen sign cell to voucher mode.
- Allowed / range: true / false
- Invalid example: `data-voucher-yen-mark="maybe"`
- Fix example: `use a value accepted by `data-voucher-yen-mark` and the Runtime contract`
- Visible / runtime behavior: The visible yen sign is display-only and is never inserted into committedValue or OUT.
- Related / conflict: voucherMode

### 3.32 `voucherGridLines`

- Type: `boolean`
- Runtime Default: `true`
- HTML: `data-voucher-grid-lines`
- Purpose: Switches voucher separators between grid lines and display punctuation.
- Allowed / range: true / false
- Invalid example: `data-voucher-grid-lines="maybe"`
- Fix example: `use a value accepted by `data-voucher-grid-lines` and the Runtime contract`
- Visible / runtime behavior: Switches voucher separators between grid lines and display punctuation.
- Related / conflict: voucherLineColor / voucherLineWidth / voucherGroupLineWidth

### 3.33 `voucherAutoFontSize`

- Type: `boolean`
- Runtime Default: `true`
- HTML: `data-voucher-auto-font-size`
- Purpose: Automatically fits voucher text size to cell width.
- Allowed / range: true / false
- Invalid example: `data-voucher-auto-font-size="maybe"`
- Fix example: `use a value accepted by `data-voucher-auto-font-size` and the Runtime contract`
- Visible / runtime behavior: Automatically fits voucher text size to cell width.
- Related / conflict: voucherFontSize

### 3.34 `voucherFontSize`

- Type: `number px`
- Runtime Default: `20`
- HTML: `data-voucher-font-size`
- Purpose: Sets the voucher font size when automatic sizing is disabled.
- Allowed / range: 8..96 px
- Invalid example: `data-voucher-font-size="100"`
- Fix example: `data-voucher-font-size="20"`
- Visible / runtime behavior: Sets the voucher font size when automatic sizing is disabled.
- Related / conflict: voucherAutoFontSize

### 3.35 `voucherDigitCount`

- Type: `integer`
- Runtime Default: `12`
- HTML: `data-voucher-digit-count`
- Purpose: Sets the total number of voucher digit cells.
- Allowed / range: integer 1..30
- Invalid example: `data-voucher-digit-count="0"`
- Fix example: `data-voucher-digit-count="12"`
- Visible / runtime behavior: Sets the total number of voucher digit cells.
- Related / conflict: displayDecimalPlaces

### 3.36 `voucherLineColor`

- Type: `HEX color`
- Runtime Default: `"#6ea3ff"`
- HTML: `data-voucher-line-color`
- Purpose: Sets the normal voucher grid-line HEX color.
- Allowed / range: #RGB / #RGBA / #RRGGBB / #RRGGBBAA
- Invalid example: `voucherLineColor="red" (named colors are not accepted by this contract)`
- Fix example: `use a value accepted by `data-voucher-line-color` and the Runtime contract`
- Visible / runtime behavior: Sets the normal voucher grid-line HEX color.
- Related / conflict: #040 ColorPicker

### 3.37 `voucherLineWidth`

- Type: `number px`
- Runtime Default: `1`
- HTML: `data-voucher-line-width`
- Purpose: Sets normal voucher grid-line width.
- Allowed / range: 0..8 px
- Invalid example: `a value outside the documented `voucherLineWidth` contract`
- Fix example: `use a value accepted by `data-voucher-line-width` and the Runtime contract`
- Visible / runtime behavior: Sets normal voucher grid-line width.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.38 `voucherGroupLineWidth`

- Type: `number px`
- Runtime Default: `3`
- HTML: `data-voucher-group-line-width`
- Purpose: Sets the thicker line width used at three-digit group boundaries.
- Allowed / range: 0..12 px
- Invalid example: `a value outside the documented `voucherGroupLineWidth` contract`
- Fix example: `use a value accepted by `data-voucher-group-line-width` and the Runtime contract`
- Visible / runtime behavior: Sets the thicker line width used at three-digit group boundaries.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.39 `voucherDecimalLineColor`

- Type: `HEX color`
- Runtime Default: `"#d96a6a"`
- HTML: `data-voucher-decimal-line-color`
- Purpose: Sets the separator color between integer and decimal sections.
- Allowed / range: #RGB / #RGBA / #RRGGBB / #RRGGBBAA
- Invalid example: `voucherDecimalLineColor="red" (named colors are not accepted by this contract)`
- Fix example: `use a value accepted by `data-voucher-decimal-line-color` and the Runtime contract`
- Visible / runtime behavior: Sets the separator color between integer and decimal sections.
- Related / conflict: #040 ColorPicker

### 3.40 `voucherDecimalLineWidth`

- Type: `number px`
- Runtime Default: `2`
- HTML: `data-voucher-decimal-line-width`
- Purpose: Sets the separator width between integer and decimal sections.
- Allowed / range: 0..12 px
- Invalid example: `a value outside the documented `voucherDecimalLineWidth` contract`
- Fix example: `use a value accepted by `data-voucher-decimal-line-width` and the Runtime contract`
- Visible / runtime behavior: Sets the separator width between integer and decimal sections.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.41 `voucherNegativeMark`

- Type: `enum`
- Runtime Default: `"minus"`
- HTML: `data-voucher-negative-mark`
- Purpose: Chooses minus, triangle, or no visible negative mark in voucher mode.
- Allowed / range: minus / triangle / none
- Invalid example: `a value outside the documented `voucherNegativeMark` contract`
- Fix example: `use a value accepted by `data-voucher-negative-mark` and the Runtime contract`
- Visible / runtime behavior: Chooses minus, triangle, or no visible negative mark in voucher mode.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.42 `voucherNegativeRed`

- Type: `boolean`
- Runtime Default: `false`
- HTML: `data-voucher-negative-red`
- Purpose: Shows negative voucher digits/mark in red without changing the number.
- Allowed / range: true / false
- Invalid example: `data-voucher-negative-red="maybe"`
- Fix example: `use a value accepted by `data-voucher-negative-red` and the Runtime contract`
- Visible / runtime behavior: Only the voucher presentation becomes red for negative values; the committed number is unchanged.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.43 `voucherHoverEdit`

- Type: `boolean`
- Runtime Default: `true`
- HTML: `data-voucher-hover-edit`
- Purpose: Temporarily returns to the editable input while hovering voucher display.
- Allowed / range: true / false
- Invalid example: `data-voucher-hover-edit="maybe"`
- Fix example: `use a value accepted by `data-voucher-hover-edit` and the Runtime contract`
- Visible / runtime behavior: Temporarily returns to the editable input while hovering voucher display.
- Related / conflict: No special conflict beyond the normal Runtime option contract.

### 3.44 `activeBorderEffect`

- Type: `enum`
- Runtime Default: `"normal"`
- HTML: `data-active-border-effect`
- Purpose: Chooses the border effect shown while the NumberBox is focused.
- Allowed / range: normal / neon / spin / cross / blink
- Invalid example: `a value outside the documented `activeBorderEffect` contract`
- Fix example: `use a value accepted by `data-active-border-effect` and the Runtime contract`
- Visible / runtime behavior: The effect appears only while focused and is detached on blur; actual rendering is delegated to #022.
- Related / conflict: #022 Hover Border Effect

### 3.45 `activeEffectColor`

- Type: `color`
- Runtime Default: `"theme"`
- HTML: `data-active-effect-color`
- Purpose: Chooses the active effect color from theme or a solid HEX value.
- Allowed / range: theme or #RGB / #RGBA / #RRGGBB / #RRGGBBAA
- Invalid example: `activeEffectColor="red" (named colors are not accepted by this contract)`
- Fix example: `data-active-effect-color="#35f4ff"`
- Visible / runtime behavior: Chooses the active effect color from theme or a solid HEX value.
- Related / conflict: #022 / #040

### 3.46 `activeEffectDirection`

- Type: `enum`
- Runtime Default: `"clockwise"`
- HTML: `data-active-effect-direction`
- Purpose: Sets clockwise or counterclockwise movement for directional effects.
- Allowed / range: clockwise / counterclockwise
- Invalid example: `a value outside the documented `activeEffectDirection` contract`
- Fix example: `use a value accepted by `data-active-effect-direction` and the Runtime contract`
- Visible / runtime behavior: Sets clockwise or counterclockwise movement for directional effects.
- Related / conflict: #022

### 3.47 `activeEffectSpeed`

- Type: `enum`
- Runtime Default: `"normal"`
- HTML: `data-active-effect-speed`
- Purpose: Sets slow, normal, or fast timing for animated active effects.
- Allowed / range: slow / normal / fast (#022: 2s / 1.2s / 0.65s)
- Invalid example: `a value outside the documented `activeEffectSpeed` contract`
- Fix example: `use a value accepted by `data-active-effect-speed` and the Runtime contract`
- Visible / runtime behavior: Sets slow, normal, or fast timing for animated active effects.
- Related / conflict: #022

### 3.48 `securityMaxLength`

- Type: `integer`
- Runtime Default: `262144`
- HTML: `data-security-max-length`
- Purpose: Limits accepted editing/numeric representation length at the Security Gate.
- Allowed / range: integer 1..1048576
- Invalid example: `data-security-max-length="0"`
- Fix example: `data-security-max-length="262144"`
- Visible / runtime behavior: Over-limit editing or input is rejected before unsafe state replaces the last safe committed value.
- Related / conflict: Security Gate

## 4. Numeric value vs display formatting

- `decimalPlaces` rounds the **committed number itself** during commit/setValue/Joint IN.
- `displayDecimalPlaces` pads/rounds only display text; committedValue and OUT stay numeric.
- `useGrouping=true` adds thousands separators only to display text.
- `roundingMode` accepts `half-up`, `up`, or `down` and controls the rounding direction used by decimal formatting.

## 5. Voucher mode

- Voucher mode is a display mode, not a second numeric value.
- `voucherYenMark=true` displays a separate `￥` cell; the symbol is never part of committedValue.
- Grid lines, group separators, decimal separator styling and negative marks are display-only.
- `voucherNegativeRed=true` paints negative voucher digits/mark red without changing the numeric value.
- `voucherHoverEdit=true` can temporarily reveal the editing input while hovering.

## 6. Position all 9 values / parent dependency

`position` is not absolute page positioning. The Runtime sets CSS Grid `justify-self / align-self` on the NumberBox root, so the 9-way contract is defined with a **`display:grid` parent**, like the formal Preview. A plain block/flex parent does not guarantee these 9 visual positions.

- `top-left` — `justify-self:start` + `align-self:start`.
- `top-center` — `justify-self:center` + `align-self:start`.
- `top-right` — `justify-self:end` + `align-self:start`.
- `middle-left` — `justify-self:start` + `align-self:center`.
- `center` — `justify-self:center` + `align-self:center` / Default.
- `middle-right` — `justify-self:end` + `align-self:center`.
- `bottom-left` — `justify-self:start` + `align-self:end`.
- `bottom-center` — `justify-self:center` + `align-self:end`.
- `bottom-right` — `justify-self:end` + `align-self:end`.

Live Samples use the same Grid-parent condition. With `inheritParent=true` or `appearance=inherit`, the root stretches to 100% and parent styling takes precedence over `position / width / height / inputAlign`.

## 7. Active Border Effect / #022

NumberBox stores only the active-state effect options. Actual border-effect rendering is delegated to #022 Hover Border Effect v1.0.10.

- Effect: `normal / neon / spin / cross / blink`
- Direction: `clockwise / counterclockwise`
- Speed: `slow / normal / fast` = 2s / 1.2s / 0.65s in #022 v1.0.10
- Color: `theme` or a solid HEX color. Color selection UI belongs to #040.

## 8. #040 ColorPicker responsibility

#040 chooses and returns a solid HEX color. #029 applies that string to `backgroundColor`, `activeEffectColor`, `voucherLineColor`, or `voucherDecimalLineColor`. NumberBox does not create a separate color picker.

## 9. Untrusted IN / Security

Joint IN accepts only finite `number` or `null`. Numeric strings such as `"22.5"`, NaN, Infinity, arbitrary objects, getters and Proxy traps are rejected instead of being coerced. A rejected input preserves the previous committed value.

## 10. JavaScript-only callbacks — 15

Every callback payload includes `componentId / componentName / version / boneId / boneType` in addition to event-specific fields.

#### 10.1 `onInput`

- When: after user editing changes.
- Event-specific payload: `value / previousValue / source / composing`
- Example: `onInput: payload => console.log(payload)`

#### 10.2 `onChange`

- When: when the editing value changes through the Runtime change path.
- Event-specific payload: `value / previousValue / source`
- Example: `onChange: payload => console.log(payload)`

#### 10.3 `onCommit`

- When: after a commit attempt completes.
- Event-specific payload: `value / previousValue / source / validation / bone`
- Example: `onCommit: payload => console.log(payload)`

#### 10.4 `onInvalid`

- When: when Validation reports invalid input.
- Event-specific payload: `value / previousValue / source / validation`
- Example: `onInvalid: payload => console.log(payload)`

#### 10.5 `onFocus`

- When: when the internal input gains focus.
- Event-specific payload: `value / source`
- Example: `onFocus: payload => console.log(payload)`

#### 10.6 `onBlur`

- When: when the internal input loses focus.
- Event-specific payload: `value / source`
- Example: `onBlur: payload => console.log(payload)`

#### 10.7 `onCompositionstart`

- When: when IME composition starts.
- Event-specific payload: `value / source`
- Example: `onCompositionstart: payload => console.log(payload)`

#### 10.8 `onCompositionupdate`

- When: while IME composition text updates.
- Event-specific payload: `value / source`
- Example: `onCompositionupdate: payload => console.log(payload)`

#### 10.9 `onCompositionend`

- When: when IME composition ends.
- Event-specific payload: `value / source`
- Example: `onCompositionend: payload => console.log(payload)`

#### 10.10 `onReset`

- When: when Escape or reset() restores editing state.
- Event-specific payload: `value / source`
- Example: `onReset: payload => console.log(payload)`

#### 10.11 `onInAccepted`

- When: when Joint IN is accepted safely.
- Event-specific payload: `accepted / blocked / source / value / state`
- Example: `onInAccepted: payload => console.log(payload)`

#### 10.12 `onInRejected`

- When: when Joint IN is rejected.
- Event-specific payload: `accepted / blocked / code / message / preservedValue`
- Example: `onInRejected: payload => console.log(payload)`

#### 10.13 `onSecurityRejected`

- When: when editing/input is rejected by the Security Gate.
- Event-specific payload: `code / message / source`
- Example: `onSecurityRejected: payload => console.log(payload)`

#### 10.14 `onDeliveryState`

- When: when #002 Delivery Channel state changes.
- Event-specific payload: `deliveryState / detail / targetReady / queueLength`
- Example: `onDeliveryState: payload => console.log(payload)`

#### 10.15 `onDelivery`

- When: when OUT delivery is attempted after commit.
- Event-specific payload: `source / output / result`
- Example: `onDelivery: payload => console.log(payload)`

## 11. Joint IN

Use `applyJointInput(root,{source,value,state})`. Accepted finite numbers/null update the committed value and emit `in-accepted`. Rejected input emits `in-rejected`, preserves the previous committed value, and can result in BLOCKED delivery state.

## 12. OUT WAIT / FIFO / BLOCKED

### 12.1 WAIT → FIFO

1. Connect an OUT channel with `targetReady:false`; the connection remains bound.
2. Commit values 11 and 22; their numeric OUT payloads queue in that order.
3. Call `setTargetReady(root,true)`; delivery resumes as 11 → 22 in FIFO order.

### 12.2 BLOCKED

If a guard rejects a value, the channel remains connected but the rejected number is not delivered. Inspect `getOutputState()`, call `clearOutputBlock()`, then deliver the next safe value.

## 13. Basic operation / Focus / IME / selection

Enter commits by default. Escape resets editing text. Enter commit is suppressed while IME composition is active. Selection APIs operate on the internal text input. Voucher display can be switched explicitly with `showVoucherDisplay()` and `showInputMode()`.

## 14. Public API — 44

#### 14.1 `defaults()`

- Purpose: Executes the documented `defaults` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const d=BoneNumberBox.defaults();`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.2 `normalizeOptions(options)`

- Purpose: Executes the documented `normalizeOptions` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const o=BoneNumberBox.normalizeOptions({step:0.5,theme:"neon"});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.3 `validateValue(value, options)`

- Purpose: Executes the documented `validateValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.validateValue(12.5,{min:0,max:100,step:0.5});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.4 `inspectUntrustedNumber(value)`

- Purpose: Executes the documented `inspectUntrustedNumber` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.inspectUntrustedNumber(10);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.5 `inspectEditingText(value, limit)`

- Purpose: Executes the documented `inspectEditingText` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.inspectEditingText("123.45",262144);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.6 `roundValue(value, decimalPlaces, roundingMode)`

- Purpose: Executes the documented `roundValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.roundValue(1.235,2,"half-up");`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.7 `formatDisplayValue(value, options)`

- Purpose: Executes the documented `formatDisplayValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.formatDisplayValue(1000,{displayDecimalPlaces:2,useGrouping:true});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.8 `create(boneInput, options)`

- Purpose: Executes the documented `create` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const root=BoneNumberBox.create({id:"amount",type:"NUMBERBOX",value:1000},{step:1});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.9 `isInstance(element)`

- Purpose: Executes the documented `isInstance` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.isInstance(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.10 `getInput(element)`

- Purpose: Executes the documented `getInput` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const input=BoneNumberBox.getInput(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.11 `getValue(element)`

- Purpose: Executes the documented `getValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const value=BoneNumberBox.getValue(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.12 `getEditingValue(element)`

- Purpose: Executes the documented `getEditingValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const editing=BoneNumberBox.getEditingValue(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.13 `getCommittedValue(element)`

- Purpose: Executes the documented `getCommittedValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const committed=BoneNumberBox.getCommittedValue(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.14 `getDisplayValue(element)`

- Purpose: Executes the documented `getDisplayValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const display=BoneNumberBox.getDisplayValue(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.15 `getVoucherDisplayValue(element)`

- Purpose: Executes the documented `getVoucherDisplayValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const voucher=BoneNumberBox.getVoucherDisplayValue(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.16 `getVoucherLayout(element)`

- Purpose: Executes the documented `getVoucherLayout` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const layout=BoneNumberBox.getVoucherLayout(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.17 `getDisplayMode(element)`

- Purpose: Executes the documented `getDisplayMode` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const mode=BoneNumberBox.getDisplayMode(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.18 `getBone(element)`

- Purpose: Executes the documented `getBone` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const bone=BoneNumberBox.getBone(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.19 `getOptions(element)`

- Purpose: Executes the documented `getOptions` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const options=BoneNumberBox.getOptions(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.20 `getState(element)`

- Purpose: Executes the documented `getState` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const state=BoneNumberBox.getState(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.21 `setValue(element, value, options)`

- Purpose: Executes the documented `setValue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.setValue(root,2500,{source:"api"});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.22 `setOptions(element, patch)`

- Purpose: Executes the documented `setOptions` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.setOptions(root,{useGrouping:true,displayDecimalPlaces:2});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.23 `applyBone(element, boneInput)`

- Purpose: Executes the documented `applyBone` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.applyBone(root,{id:"amount",type:"NUMBERBOX",value:3000});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.24 `applyJointInput(element, payload)`

- Purpose: Executes the documented `applyJointInput` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.applyJointInput(root,{source:"joint",value:10,state:{status:"connected"}});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.25 `buildOutput(element, source)`

- Purpose: Executes the documented `buildOutput` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const out=BoneNumberBox.buildOutput(root,"manual");`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.26 `connectOutput(element, options)`

- Purpose: Executes the documented `connectOutput` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.connectOutput(root,{targetReady:true,deliver:o=>console.log(o.value)});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.27 `disconnectOutput(element)`

- Purpose: Executes the documented `disconnectOutput` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.disconnectOutput(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.28 `setTargetReady(element, ready)`

- Purpose: Executes the documented `setTargetReady` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.setTargetReady(root,false);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.29 `clearOutputBlock(element)`

- Purpose: Executes the documented `clearOutputBlock` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.clearOutputBlock(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.30 `getOutputState(element)`

- Purpose: Executes the documented `getOutputState` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const state=BoneNumberBox.getOutputState(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.31 `getOutputQueue(element)`

- Purpose: Executes the documented `getOutputQueue` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const queue=BoneNumberBox.getOutputQueue(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.32 `commit(element, source)`

- Purpose: Executes the documented `commit` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const result=BoneNumberBox.commit(root,"save-button");`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.33 `reset(element)`

- Purpose: Executes the documented `reset` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.reset(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.34 `validate(element)`

- Purpose: Executes the documented `validate` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const v=BoneNumberBox.validate(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.35 `focus(element)`

- Purpose: Executes the documented `focus` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.focus(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.36 `blur(element)`

- Purpose: Executes the documented `blur` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.blur(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.37 `showVoucherDisplay(element)`

- Purpose: Executes the documented `showVoucherDisplay` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.showVoucherDisplay(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.38 `showInputMode(element)`

- Purpose: Executes the documented `showInputMode` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.showInputMode(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.39 `select(element)`

- Purpose: Executes the documented `select` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.select(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.40 `setSelectionRange(element,start,end,direction)`

- Purpose: Executes the documented `setSelectionRange` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.setSelectionRange(root,0,3,"forward");`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.41 `getSelection(element)`

- Purpose: Executes the documented `getSelection` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `const sel=BoneNumberBox.getSelection(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.42 `setFeedback(element, feedback)`

- Purpose: Executes the documented `setFeedback` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.setFeedback(root,{level:"warning",message:"Please check"});`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.43 `syncParentStyle(element)`

- Purpose: Executes the documented `syncParentStyle` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.syncParentStyle(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

#### 14.44 `destroy(element)`

- Purpose: Executes the documented `destroy` NumberBox operation without bypassing Runtime validation/security responsibilities.
- Before: Prepare the required Runtime root/arguments using the documented types.
- Call: `BoneNumberBox.destroy(root);`
- After / return: Inspect the documented return value and Runtime state; do not confuse display-only voucher/formatted text with committed numeric value.
- Failure: Invalid arguments/options are rejected with the corresponding `NUMBERBOX_*` contract while safe existing state is preserved where applicable.

## 15. Error codes

### 15.1 Runtime Error — 50

**`NUMBERBOX_022_EFFECT_UNSUPPORTED`**
- Meaning: Requested #022 Effect is unsupported by the connected formal runtime.
- Invalid example: selecting `wave` with an older #022 runtime.
- Resolution: Check `BoneHoverBorderEffect.effects` before selecting a style; legacy cross maps to newer corner.
- On failure: The unsupported effect is rejected rather than advertised as successful.

**`NUMBERBOX_022_DEPENDENCY_REQUIRED`**

- Meaning: #022 Hover Border Effect v1.0.10 is missing or does not expose the required API.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_022_DEPENDENCY_REQUIRED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_022_DEPENDENCY_REQUIRED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_ACTIVE_EFFECT_COLOR_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the active effect color invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_ACTIVE_EFFECT_COLOR_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_ACTIVE_EFFECT_COLOR_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_BACKGROUND_COLOR_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the background color invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_BACKGROUND_COLOR_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_BACKGROUND_COLOR_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_BONE_ID_TYPE_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the bone id type invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_BONE_ID_TYPE_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_BONE_ID_TYPE_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_BONE_INPUT_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the bone input invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_BONE_INPUT_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_BONE_INPUT_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_CONTROL_CHARACTER_REJECTED`**

- Meaning: Text contains a rejected control character.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_CONTROL_CHARACTER_REJECTED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_CONTROL_CHARACTER_REJECTED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_DECIMAL_PLACES_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the decimal places invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_DECIMAL_PLACES_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_DECIMAL_PLACES_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_DEPENDENCY_CORE_MISSING`**

- Meaning: The required #001 Bone Core API is missing.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_DEPENDENCY_CORE_MISSING`.
- Invalid example: `an input/configuration that violates NUMBERBOX_DEPENDENCY_CORE_MISSING`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_DEPENDENCY_JOINT_MISSING`**

- Meaning: The required #002 Bone Joint v1.1.36 delivery API is missing.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_DEPENDENCY_JOINT_MISSING`.
- Invalid example: `an input/configuration that violates NUMBERBOX_DEPENDENCY_JOINT_MISSING`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_DOM_REQUIRED`**

- Meaning: A DOM environment is required to create the NumberBox UI.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_DOM_REQUIRED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_DOM_REQUIRED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_EDITING_TYPE_REJECTED`**

- Meaning: The Runtime rejected data or configuration that violates the editing type rejected contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_EDITING_TYPE_REJECTED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_EDITING_TYPE_REJECTED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_EXISTING_VALUE_SECURITY_LIMIT`**

- Meaning: The Runtime rejected data or configuration that violates the existing value security limit contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_EXISTING_VALUE_SECURITY_LIMIT`.
- Invalid example: `an input/configuration that violates NUMBERBOX_EXISTING_VALUE_SECURITY_LIMIT`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_FEEDBACK_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the feedback invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_FEEDBACK_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_FEEDBACK_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_INSTANCE_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the instance invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_INSTANCE_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_INSTANCE_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_IN_REJECTED`**

- Meaning: The Runtime rejected data or configuration that violates the in rejected contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_IN_REJECTED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_IN_REJECTED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_JOINT_INPUT_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the joint input invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_JOINT_INPUT_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_JOINT_INPUT_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_JOINT_SOURCE_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the joint source invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_JOINT_SOURCE_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_JOINT_SOURCE_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_JOINT_STATE_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the joint state invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_JOINT_STATE_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_JOINT_STATE_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_JOINT_STATE_REASON_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the joint state reason invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_JOINT_STATE_REASON_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_JOINT_STATE_REASON_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_JOINT_STATE_STATUS_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the joint state status invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_JOINT_STATE_STATUS_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_JOINT_STATE_STATUS_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_MAX`**

- Meaning: Validation rejected a number above max.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_MAX`.
- Invalid example: `an input/configuration that violates NUMBERBOX_MAX`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_MIN`**

- Meaning: Validation rejected a number below min.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_MIN`.
- Invalid example: `an input/configuration that violates NUMBERBOX_MIN`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_NON_FINITE_REJECTED`**

- Meaning: NaN, Infinity, or another non-finite numeric value was rejected.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_NON_FINITE_REJECTED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_NON_FINITE_REJECTED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_NUMBER_SYNTAX_INVALID`**

- Meaning: Editing text is not valid numeric syntax.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_NUMBER_SYNTAX_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_NUMBER_SYNTAX_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_NUMERIC_OPTION_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the numeric option invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_NUMERIC_OPTION_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_NUMERIC_OPTION_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_OPTIONS_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the options invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_OPTIONS_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_OPTIONS_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_OPTION_ENUM_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the option enum invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_OPTION_ENUM_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_OPTION_ENUM_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_OPTION_TYPE_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the option type invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_OPTION_TYPE_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_OPTION_TYPE_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_OUTPUT_CHANNEL_UNBOUND`**

- Meaning: OUT delivery was requested before a delivery channel was connected.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_OUTPUT_CHANNEL_UNBOUND`.
- Invalid example: `an input/configuration that violates NUMBERBOX_OUTPUT_CHANNEL_UNBOUND`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_OUTPUT_DELIVER_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the output deliver invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_OUTPUT_DELIVER_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_OUTPUT_DELIVER_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_OUTPUT_GUARD_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the output guard invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_OUTPUT_GUARD_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_OUTPUT_GUARD_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_OUTPUT_OPTIONS_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the output options invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_OUTPUT_OPTIONS_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_OUTPUT_OPTIONS_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_OUTPUT_STATE_CALLBACK_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the output state callback invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_OUTPUT_STATE_CALLBACK_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_OUTPUT_STATE_CALLBACK_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_RANGE_INVALID`**

- Meaning: min must be less than or equal to max.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_RANGE_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_RANGE_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_REQUIRED`**

- Meaning: Validation rejected an empty value because required=true.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_REQUIRED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_REQUIRED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_SECURITY_LENGTH_EXCEEDED`**

- Meaning: Input exceeded securityMaxLength and was rejected by the Security Gate.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_SECURITY_LENGTH_EXCEEDED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_SECURITY_LENGTH_EXCEEDED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_SECURITY_LIMIT_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the security limit invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_SECURITY_LIMIT_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_SECURITY_LIMIT_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_SIZE_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the size invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_SIZE_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_SIZE_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_STEP`**

- Meaning: Validation rejected a number that does not match the configured step.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_STEP`.
- Invalid example: `an input/configuration that violates NUMBERBOX_STEP`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_STEP_INVALID`**

- Meaning: step must be "any" or a finite number greater than zero.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_STEP_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_STEP_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_UNPAIRED_SURROGATE_REJECTED`**

- Meaning: Text contains an unpaired Unicode surrogate and was rejected.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_UNPAIRED_SURROGATE_REJECTED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_UNPAIRED_SURROGATE_REJECTED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_UNTRUSTED_ACCESSOR_REJECTED`**

- Meaning: An untrusted accessor/getter was rejected instead of being executed as data.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_UNTRUSTED_ACCESSOR_REJECTED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_UNTRUSTED_ACCESSOR_REJECTED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_UNTRUSTED_PROPERTY_MISSING`**

- Meaning: The Runtime rejected data or configuration that violates the untrusted property missing contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_UNTRUSTED_PROPERTY_MISSING`.
- Invalid example: `an input/configuration that violates NUMBERBOX_UNTRUSTED_PROPERTY_MISSING`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_UNTRUSTED_PROPERTY_TRAP`**

- Meaning: An untrusted Proxy/property access trap was rejected.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_UNTRUSTED_PROPERTY_TRAP`.
- Invalid example: `an input/configuration that violates NUMBERBOX_UNTRUSTED_PROPERTY_TRAP`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_UNTRUSTED_RECORD_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the untrusted record invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_UNTRUSTED_RECORD_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_UNTRUSTED_RECORD_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_VALUE_TYPE_REJECTED`**

- Meaning: The input value type is not accepted by the NumberBox contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_VALUE_TYPE_REJECTED`.
- Invalid example: `an input/configuration that violates NUMBERBOX_VALUE_TYPE_REJECTED`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_VOUCHER_DIGIT_COUNT_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the voucher digit count invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_VOUCHER_DIGIT_COUNT_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_VOUCHER_DIGIT_COUNT_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_VOUCHER_FONT_SIZE_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the voucher font size invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_VOUCHER_FONT_SIZE_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_VOUCHER_FONT_SIZE_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_VOUCHER_LINE_COLOR_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the voucher line color invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_VOUCHER_LINE_COLOR_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_VOUCHER_LINE_COLOR_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

**`NUMBERBOX_VOUCHER_LINE_WIDTH_INVALID`**

- Meaning: The Runtime rejected data or configuration that violates the voucher line width invalid contract.
- Main trigger: Data, option, dependency, delivery, or security input violates the contract identified by `NUMBERBOX_VOUCHER_LINE_WIDTH_INVALID`.
- Invalid example: `an input/configuration that violates NUMBERBOX_VOUCHER_LINE_WIDTH_INVALID`
- Fix: Use the property/API rules in this guide and provide a value that satisfies the documented type/range/dependency.
- Effect on state: The failing operation is rejected; the previous safe value/state is preserved where the Runtime contract allows it.

### 15.2 HTML Functional Class Integration Error

- `NUMBERBOX_FUNCTIONAL_CLASS_RUNTIME_MISSING` — Load `bone-numberbox.js` before `bone-numberbox-functional-class.js`.
- `NUMBERBOX_FUNCTIONAL_CLASS_ANCHOR_INVALID` — Put `class="bf-numberbox"` on a valid HTML Element.
- `NUMBERBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID` — Use a supported boolean spelling such as true/false.
- `NUMBERBOX_FUNCTIONAL_CLASS_VALUE_INVALID` — Use an empty value or a finite numeric string such as `12.5`.

## 16. Lifecycle

`bf-numberbox` mounts one Runtime per declaration element. Attribute changes refresh value/options. `unmount()` destroys the Runtime and restores the original declaration element. Runtime `destroy()` also disposes #002 OUT and detaches #022 effects.

## 17. Troubleshooting

- If `1,000.00` is displayed but OUT must stay numeric, inspect `getCommittedValue()`/`buildOutput()` rather than display text.
- Voucher `￥`, grid lines, triangle/minus and commas are display-only; never parse them back into the number.
- If commit does not update the value, inspect `validate()` and Security state before changing test expectations.
- If WAIT does not flush, confirm the output channel is connected and call `setTargetReady(root,true)`.
- If a raw `[[BF-NUMBERBOX-SAMPLE:...]]` marker remains in the DOC, verify the component DOC integration script and shared Guide DOM contract.

## 18. Responsibility boundaries

- #029 NumberBox: numeric editing, rounding, formatting, voucher display, Validation and commit.
- #002 Joint: connection and WAIT/FIFO/BLOCKED delivery.
- #022 Hover Border Effect: active border-effect rendering.
- #040 ColorPicker: choosing and returning solid colors.
- #017 provides display/layout conventions only; NumberBox does not depend on the BoneText Runtime.