# #125 Blend Operation / HTML Functional Class Guide

## About this guide
This guide covers #125 Blend responsibility, normal HTML use, the eight formal modes, Runtime, Joint integration, and validation. Development Order v1.1.1 defines the responsibility as managing drawing composition methods.

## Blend
#125 Blend controls how an element's drawing is composited with the backdrop. Runtime 1.0.0 applies CSS `mix-blend-mode`. It does not own #124 Filter or opacity itself.

## Formal modes
Normal / Multiply / Screen / Overlay / Darken / Lighten / Difference / Add. `Add` is the formal Bone Flow name and maps to CSS `plus-lighter` in Runtime 1.0.0.

## HTML Functional Class
The single normal-use class is **`bf-blend`**. Public APIs do not create additional HTML classes.

### When to use it
Use it when foreground and backdrop drawing should be composited with Multiply, Screen, Overlay, Difference, additive blending, and the other formal modes.

### Where to use it
Put `class="bf-blend"` on the foreground element whose drawing should blend with content behind it.

### Data
- `class="bf-blend"` — normal-use entry point.
- `data-blend-mode` — one of the eight exact formal mode names.

### Minimal HTML
```html
<div class="bf-blend">Blend target</div>
```
Result: **`mix-blend-mode: normal`**.

### Complete load example
```html
<link rel="stylesheet" href="/boneflow/css/bone-blend.css">
<div class="bf-blend" data-blend-mode="Multiply">Blend target</div>
<script src="/boneflow/js/bone-blend.js"></script>
<script src="/boneflow/js/bone-blend-functional-class.js"></script>
```
Result: **`mix-blend-mode: multiply`**.

### Configured HTML
```html
<div class="bf-blend" data-blend-mode="Screen">Screen target</div>
<div class="bf-blend" data-blend-mode="Add">Add target</div>
```
The results are `screen` and `plus-lighter`.

### JavaScript
```js
const target = document.querySelector('.bf-blend');
BoneBlendFunctionalClass.setMode(target, 'Overlay');
console.log(BoneBlendFunctionalClass.getCssBlendMode(target)); // overlay
```

## Operation
For normal use: add `bf-blend`, then select a mode with `data-blend-mode`. Use the Functional Class or Runtime API only for dynamic changes. TEST-page QA button order is not the component usage model.

## Preview
The TEST page overlaps foreground and backdrop layers and applies the selected real CSS `mix-blend-mode`.

## Dependencies / responsibility boundary
#001 Bone Core is the foundation. Connection Image and Delivery QA use canonical #002 Bone Joint 1.1.36. #125 does not own #124 Filter, #117 Animation, #118 Transition, #120 Trigger, #121 Timeline, or #123 Particle.

## Connection Image / Joint
Normal connections are Source.mode (String) → Blend.mode (String), and Blend.cssBlendMode (String) → Target.cssBlendMode (String). Missing fields and type mismatch use official #002 abnormal rendering.

## WAIT / FIFO / BLOCKED
Delivery uses official #002 `createDeliveryChannel()`. WAIT queues while targetReady is false and then delivers FIFO. BLOCKED does not deliver to the target. `getState()` is not extended with a fake `connectionEstablished`; `BoneJoint.evaluate(...)` is used separately.

## Security
Unknown modes, wrong case, arrays, null, and accessor properties are rejected without executing untrusted getters.

## Smoke Test / Validation
Smoke covers Runtime, eight modes, Functional Class, Preview, #002 Joint, and Delivery. Validation covers responsibility boundaries, HTML IDs, Completion gate, and abnormal connection cases. Unexecuted localhost tests are not ALL PASS.

## Completion
Completion requires executed Smoke/Validation plus visual confirmation of Blend Preview, Joint, WAIT→READY→FIFO, and BLOCKED. Before USER LOCALHOST confirmation the package remains Development / Candidate.

## Public API
### BoneBlend Runtime
`getFormalModes`, `getBlendDefinition`, `normalizeMode`, `normalizeExpression`, `validateExpression`, `toCssBlendMode`, `toCssDeclaration`, `create`, `mount`, `setExpression`, `setMode`, `getExpression`, `getMode`, `getCssBlendMode`, `getCssDeclaration`, `getState`, `complete`, `reopen`, `destroy`, `isInstance`.

### BoneBlendFunctionalClass
`mount`, `mountAll`, `refresh`, `setExpression`, `setMode`, `getExpression`, `getMode`, `getCssBlendMode`, `unmount`, `isMounted`.

## Error / Troubleshooting
- No visible blend: verify overlapping backdrop colors and Runtime/Functional Class loading.
- `BLEND_MODE_INVALID`: use exact formal spelling and case.
- `BLEND_UNTRUSTED_ACCESSOR`: do not use accessor properties in the expression object.
- Changed HTML attribute not reflected: call `BoneBlendFunctionalClass.refresh(element)`.

## Version / Status
Package Version 1.0.1 / Runtime BoneBlend 1.0.0 / HTML Functional Class `bf-blend` 1.0.0. Development / Candidate until USER LOCALHOST confirmation.