# Bone Flow #022 - Hover Border Effect Guide

## 1. Start

#022 attaches a reusable border effect around an arbitrary HTMLElement.
Runtime: `BoneHoverBorderEffect 1.0.12`.
General-use class: `bf-hover-border-effect`.

## 2. Purpose

The runtime tracks the target rectangle with an overlay in document.body.
Effects: `normal / neon / spin / blink / dash / corner / chase / double / wave`.
Triggers: `mouseover / active / both`.

## 3. HTML Functional Class `bf-hover-border-effect`

```html
<button class="bf-hover-border-effect">Hover me</button>
```
The class alone mounts Runtime defaults. Use Property Editor or Public API for detailed options.

## 4. Minimal HTML

```js
BoneHoverBorderEffect.attach(document.querySelector("#sample"), { effect:"normal" });
```

## 5. Configured API sample

```js
BoneHoverBorderEffect.attach(target,{trigger:"mouseover",effect:"neon",color:"#35f4ff",direction:"clockwise",speed:"normal",lineWidth:3,spinWidth:2,spinGlow:12});
```

## 6. Live Samples

When this Guide is open, the page integration injects live samples using the real runtime, following the #017 Guide pattern.

## 7. Runtime Defaults

trigger=mouseover
effect=normal
color=#35f4ff
direction=clockwise
speed=normal
lineWidth=3
spinWidth=2
spinGlow=12

## 8. Runtime-owned Property Schema

Use `getPropertySchema()`, `getPropertyDefaults()`, and `getPropertyDefinition(key)`.

## 9. Properties

trigger enum: mouseover/active/both
effect enum: normal/neon/spin/blink/dash/corner/chase/double/wave
color string
direction enum: clockwise/counterclockwise
speed enum: slow/normal/fast
lineWidth number 1..12 px (perimeter width for normal/neon/blink/dash/corner/chase/double/wave; spin uses spinWidth)
spinWidth number 1..24 px
spinGlow number 0..40 px

## 10. Effects

normal: fixed border
neon: moving luminous perimeter
spin: rotating conic rotor clipped to the perimeter mask
blink: blinking border
dash: moving dashed perimeter
corner: animated L-shaped corners only
chase: one short luminous segment chasing around the perimeter
double: two parallel perimeter lines
wave: moving brightness band along the perimeter

`cross` is removed and is rejected with `BONE_022_EFFECT_INVALID`. All nine effects stay on the perimeter and do not fill the element interior.

### Formal effect registration change

- Removed: `cross`
- Added: `dash / corner / chase / double / wave`
- Current formal enum: `normal / neon / spin / blink / dash / corner / chase / double / wave`
- Runtime Schema `effect.enum`, Property UI, Guide Live Samples, Smoke, and Validation are synchronized to this nine-effect set.

## 11. Triggers

mouseover: enter/leave
active: setActive
both: hover OR active

## 12. Public API

defaults / schema APIs / normalizeOptions / attach / update / setActive / refresh / getOptions / getState / getOverlay / isAttached / detach

## 13. Attach / Update / Detach

```js
BoneHoverBorderEffect.attach(target,{trigger:"active",effect:"spin"});
BoneHoverBorderEffect.setActive(target,true);
BoneHoverBorderEffect.update(target,{speed:"fast"});
BoneHoverBorderEffect.detach(target);
```

## 14. #040 ColorPicker

Use the formal #040 Caller API. Do not implement a private ColorPicker.

## 15. #002 Bone Joint

Connection Image uses BoneJoint 1.1.36 formal evaluation and drawing APIs.

## 16. Smoke / Validation

Smoke operates the real DOM/runtime. Validation checks structure, invalid inputs, Joint, Guide, Caller, and Completion gate.

## 17. Completion

Completion stays locked until both Smoke and Validation pass. User localhost confirmation is still required.

## 18. Errors

BONE_022_TARGET_INVALID
BONE_022_NOT_ATTACHED
BONE_022_TRIGGER_INVALID
BONE_022_EFFECT_INVALID
BONE_022_DIRECTION_INVALID
BONE_022_SPEED_INVALID

## 19. Copy-ready sample

```html
<button id="hover-target">Hover Border</button>
```
```js
BoneHoverBorderEffect.attach(document.getElementById("hover-target"),{trigger:"both",effect:"neon",color:"#35f4ff"});
```

## 20. Checklist

Runtime loaded
Property to Preview works
Nine effects
Three triggers
#040 Caller
#002 Connection Image
Smoke
Validation
Guide live samples
HTML Functional Class
Console errors checked

## Appendix A. Property table

| Key | Type | Default | Values / Range |
|---|---|---|---|
| trigger | enum | mouseover | mouseover / active / both |
| effect | enum | normal | normal / neon / spin / blink / dash / corner / chase / double / wave |
| color | color string | #35f4ff | #040 Caller RETURN |
| direction | enum | clockwise | clockwise / counterclockwise |
| speed | enum | normal | slow / normal / fast |
| lineWidth | number | 3 | 1..12 px (perimeter width except spin) |
| spinWidth | number | 2 | 1..24 px |
| spinGlow | number | 12 | 0..40 px |

## Appendix B. Runtime state

`getState(target)` returns attached / hovered / active / visible / trigger / effect.

## Appendix C. Responsibility boundary

#022 owns border effects only. #040 owns ColorPicker, #002 owns Joint evaluation/drawing, and shared BoneDocGuide/BoneDocLoader own the Guide modal and loading.


## v1.0.27 display/report consistency
The formal Runtime is BoneHoverBorderEffect 1.0.12. The test page, Completion panel, saved report, and Runtime identity check all use 1.0.12. #022 Runtime/CSS assets use versioned query URLs so a cached 1.0.11 asset is not reused after installation.