<!-- 04_VISUAL/xwui/xwui-lib/xwui-lib-super/src/display/XWUIDepthOrnament/XWUIDepthOrnament.md -->
# XWUIDepthOrnament

Decorative ornaments, drawn by xw3d (`@exonware/xw3d/css3d` css3dPart) and painted by token NAMES: a lit orb, a translucent cube, a ring (one tone, a swept tone list or the
brand spectrum; solid or dashed; round or tilted into an ellipse), a tick ring, a halo aura, a perspective floor grid, stacked
slabs, flowing wires and the import intake funnel (eight spinning rings, a glowing throat and record chips spiralling down). It
carries no information: always `aria-hidden`, never focusable, no copy of its own. xw3d owns the geometry and the motion
(Web Animations on transform, opacity and a wire's dash, one shared clock, nothing declared while still); this component owns
the paint, in a sheet with no CSS 3D. The shared playback rule decides whether it moves (reduced motion, off screen, hidden
tab, a host pause) and hands that verdict to the part.

## Basic Usage

```example
file: examples/BasicUsage.ts
html: examples/BasicUsage.html
title: Basic Usage
description: One glowing orb in a token hue.
```

```example
file: examples/HeroAuras.ts
html: examples/HeroAuras.html
title: Hero Auras
description: Two halos behind a hero with a lower strength in a light scheme.
```

```example
file: examples/TrustRings.ts
html: examples/TrustRings.html
title: Trust Rings
description: A dashed boundary ring and a tick-ring gauge.
```

```example
file: examples/IntakeFunnel.ts
html: examples/IntakeFunnel.html
title: Intake Funnel
description: The import intake funnel with record chips, busy while a file is read.
```

## Data

```ts
data: {
  kind?:   'orb' | 'cube' | 'ring' | 'tickRing' | 'halo' | 'floor' | 'slabs' | 'wires' | 'funnel';  // default 'orb'
  tone?:   Tone;                                   // default 'violet'
  tones?:  Tone[];                                 // ring sweep (2+), wires (1 to 3), funnel dashed + solid rings
  plates?: (Tone | { from: Tone; to: Tone })[];    // slabs, bottom to top, 1 to 8
  labels?: string[];                               // funnel particle chips (decorative, 12 characters each)
}
```

`Tone` is a token NAME, never a colour: any plain identifier resolves to `var(--xwui-hue-<name>, <fallback>)`, so a host may
declare its own (`--xwui-hue-budget` for the plnx identity colours). The nine core names (`lime cyan violet pink orange green
amber red blue`) are declared only by the xwflow-neon theme; elsewhere they fall back to the nearest token every theme carries
(cyan to sky, violet to purple, pink to fuchsia, amber to yellow, red to rose, blue to indigo, lime, green and orange to the heat
ramp solids), then to the accent. Special names: `spectrum` (a ring sweeps cyan, violet, pink, orange, lime; other kinds take
violet), `accent`, `neutral` (secondary ink), `ground` (the raised card surface a plate fades into). An unknown kind, an invalid
tone or a junk list entry renders the default or is dropped; nothing throws.

## Options

| Option | Default | What it does |
| --- | --- | --- |
| `size` | `'md'` | `xs` 2rem, `sm` 3.5, `md` 5, `lg` 8, `xl` 12, `2xl` 18. |
| `diameter` | null | Edge length in rem (0.5 to 80), overriding `size`. The artboards' 620 px aura is 38.75. |
| `ringWidth` | null | Band of a ring or tick ring in rem (0.0625 to 8). Null: 5.5 percent (ring) or 9.4 percent (tick ring) of the size. |
| `aspect` | null | Block over inline (0.1 to 4): an oval halo, a wide floor; a ring or tick ring tilts into an ellipse (1 or less), so its dashes and spin stay in its own plane. |
| `dashed` | `false` | A dashed ring (dashes cut in the ring's plane, so a swept ring can be dashed too). |
| `rotateSeconds` | null | Period of the kind's motion (an xw3d part option): ring 18 s, tick ring 40 s, cube 16 s, orb bob 7 s, floor 7 s, wires 1.2 s, funnel 8 s (3 s busy). |
| `opacity` | null | Paint strength 0 to 1. Null: 0.55 for a halo, 1 otherwise. |
| `opacityLight` | null | Paint strength under a light colour scheme (read live from the theme's `color-scheme` through `light-dark()`). |
| `animate` | `true` | Idle motion; always off under `prefers-reduced-motion`. |
| `layers` | `3` | Plates of `slabs` without a `plates` list (1 to 8). |
| `particles` | null | Funnel particles (0 to 12). Null: 5, or 9 when busy. |
| `busy` | `false` | Funnel working state: faster rings, a pulsing throat, more particles. |
| `className` | `''` | Extra classes, such as a positioning utility. |

## Events and methods

| Event | Detail | When |
| --- | --- | --- |
| `kindChange` | `{ kind, previous }` | The drawn kind changed (`setData`, `updateData`, `setKind`, a framework prop update). Also a bubbling DOM `kind-change` CustomEvent on the host. |

`setKind(kind)`, `setTone(name)`, `pause()` and `play()` (a page-level "pause all motion"), `isMoving()`,
`onKindChange(handler)`, `updateData(patch)`, `updateConfig(patch)`, `getElement()`, `destroy()` (idempotent; releases the
on-screen observer and the reduced-motion listener). `XWUIDepthOrnament.projectView(data, config)` composes the flat twin of an ornament
(plain 2D shapes painted by the same sheet, still, no particles, class `xwui-depth-ornament--flat`) into another component's view tree.

The 5th constructor argument `{ clock?, environment? }` is the test and host seam for the page signals.

## Geometry, paint and the flat twin

The adapter builds the shape in a host-owned stage inside the first render, so the ornament paints in its first frame. Its size
comes from the measured root (a `ResizeObserver` callback that fires before the first paint), so every size, `diameter` and
`aspect` works in px inside xw3d. The sheet paints the xw3d elements through the BEM classes the adapter adds
(`xwui-depth-ornament__orb`, `__face`, `__band`, `__plate`, `__wire`, `__funnel-ring`, and so on), so the part and the flat twin
share one set of paint rules. The twin is the face when the ornament is composed into another view with `projectView` (no adapter, so
no part); reduced motion keeps the part in its static pose (xw3d declares no animation at all).
Removed with the move: the `--xwui-depth-ornament-period` and `--xwui-depth-ornament-tilt` custom properties (use
`rotateSeconds` and `aspect`), `--xwui-depth-ornament-wire-travel` (xw3d travels 2.5rem at 16 px) and the `--animated` and
`--paused` rules of the sheet (the classes stay on the root for hosts).

## Placement

The root is `position: relative` at zero specificity, so a positioning utility in `className` (or a wrapper) wins. Sizes are
rem, so ornaments scale with the root font size. Wires fill their container at 8 to 3; set `block-size` and
`aspect-ratio: auto` on the root for another height.

## Accessibility, motion and RTL

`aria-hidden="true"`, `pointer-events: none`, nothing focusable and no text twin: a twin of decoration would be noise to a
screen reader, and the spec says the ornament never carries information (put any meaning in real text beside it; the funnel
labels are decorative record ids). Motion starts when the ornament is first on screen, pauses (holding its pose) off screen,
in a hidden tab or on `pause()`, and never runs under reduced motion: the view drops the `--animated` class and the part is
built still (live, both ways); a still funnel shows no particles. There is no WCAG 2.2.2
control on the ornament itself: a page with long-running decorative motion offers its own "pause all motion" and calls
`pause()`. Logical properties only; xw3d mirrors the slabs' turn and the wires' flow on a right-to-left page (the `mirrored` part option, from
the component's direction); the shapes are symmetric.

## Provenance

Promoted from the tested app-owned `03_BASE/xwflow/xwflow-web/src/components/XWUIDepthOrnament` (1,166 lines of TS; kinds orb,
cube, ring, halo, floor, slabs, wires; spectrum and tone-list rings; two-tone plates; diameter and ring width in rem). Its
state and view tests are kept as the regression floor in `XWUIDepthOrnament.test.ts`. Changes in the library: the four-layer
anatomy (calc, logic with the shared playback rule, view, persistent-mount adapter); tone names resolve to `--xwui-hue-*` with
fallbacks instead of the xwflow `--lime`, `--g-*`, `--bg-2` tokens (the xwflow node-family names are now host-declared hue
names); no colour keywords (light and shade come from the scene palette); the XWUIBox stage is a plain element; new kinds
`tickRing` and `funnel` (P-G15), ring `dashed` and `aspect`, `rotateSeconds`, per-scheme `opacity`/`opacityLight`, floor scroll,
off-screen pause and host pause, RTL wire flow. `xwflow-web` keeps its copy until it switches imports (no shim either way).

```api
```