# #116 Effect Guide
Version: Runtime 1.0.14 Candidate
Status: Development
HTML Functional Class: `bf-effect`
DOC: DOC-0116 / TOC-0116
## 1. Introduction
#116 Effect applies a visual effect to the target element owned by the Consumer. The formal Development Order contains exactly nine effects. #117 Animation and #118 Transition are separate components.
## 2. Responsibility boundary
- #116: effect type, apply/clear, effect-color Properties, Effect output state.
- #017 Text: actual Text rendering used by the Preview/Consumer.
- #040 ColorPicker: solid color selection for Shadow / Glow / Color Change. The Consumer must not duplicate #040 Palette DOM or CSS.
- #002 Bone Joint: #116 Effect → #017 Text relation, WAIT/FIFO/BLOCKED delivery, and abnormal relation rendering.
- #118 Transition: not a direct #116 dependency. It is used transitively by the completed #040 Picker OPEN/CLOSE path only.
## 3. HTML Functional Class
The normal-use class is one class: `bf-effect`. Public API names are not converted into HTML classes.
Minimal #017 Text example:
```html
Effect Text
```
The same element is both the #017 Text target and the #116 Effect target. Do not introduce a generic Target or an `effectTarget` field.
When `bf-text` is combined with `bf-effect`, #116 does not duplicate #017 Text creation. It delegates to the formal `BoneTextHTMLClass.mount()` API, obtains the actual BoneText element, and attaches the Effect to that actual element. #116 preserves its own `data-effect`, `data-shadow-color`, `data-glow-color`, and `data-color-change` attributes on the actual target.
## 4. Configured HTML
Glow:
```html
Glow Text
```
Shadow:
```html
Shadow Text
```
Color Change:
```html
Color Change Text
```
## 5. HTML attributes
| Attribute | Required | Meaning |
|---|---:|---|
| `data-effect` | optional | One of the nine formal effects; default `fade` |
| `data-shadow-color` | for Shadow | #040 solid `#RRGGBB` |
| `data-glow-color` | for Glow | #040 solid `#RRGGBB` |
| `data-color-change` | for Color Change | #040 solid `#RRGGBB` |
| `data-fade-opacity` | Fade | 0.00–1.00 / default `0.30` |
| `data-fade-saturation` | Fade | >= 0 / default `0.55` |
| `data-glow-blur-1` | Glow | px / >= 0 / default `6` |
| `data-glow-blur-2` | Glow | px / >= 0 / default `14` |
| `data-shadow-x` | Shadow | px / default `4` |
| `data-shadow-y` | Shadow | px / default `4` |
| `data-shadow-blur` | Shadow | px / >= 0 / default `7` |
| `data-blur-radius` | Blur | px / >= 0 / default `2` |
| `data-opacity` | Opacity | 0.00–1.00 / default `0.58` |
| `data-scale` | Scale | > 0 / default `1.12` |
| `data-rotate-angle` | Rotate | deg / default `8` |
| `data-shake-duration` | Shake | seconds / > 0 / default `0.62` |
| `data-shake-distance` | Shake | px / >= 0 / default `7` |
Do not use one ambiguous generic `intensity` Property. Configure the actual per-effect values explicitly.
## 6. Runtime defaults
- effect: `fade`
- shadowColor: `null`
- glowColor: `null`
- colorChangeColor: `null`
- fadeOpacity: `0.30`
- fadeSaturation: `0.55`
- glowBlur1: `6`
- glowBlur2: `14`
- shadowX: `4`
- shadowY: `4`
- shadowBlur: `7`
- blurRadius: `2`
- opacity: `0.58`
- scale: `1.12`
- rotateAngle: `8`
- shakeDuration: `0.62`
- shakeDistance: `7`
These values preserve the previous fixed visual appearance as the new configurable defaults. An effect that requires a color is rejected if that color is absent. Runtime defaults are separate from Demo Sample colors used on the test page for visibility.
## 7. Formal effect inventory
| Value | English | Japanese | Description |
|---|---|---|---|
| `fade` | Fade | フェード | Static faded visual state; separate from #118 ENTER/EXIT. |
| `glow` | Glow | 発光 | Adds a glow using a #040 solid Glow Color. |
| `shadow` | Shadow | 影 | Adds a shadow using a #040 solid Shadow Color. |
| `blur` | Blur | ぼかし | Blurs the target. |
| `opacity` | Opacity | 不透明度 | Lowers opacity as a fixed visual state. |
| `color-change` | Color Change | 色変更 | Changes Text color to a #040 solid color. |
| `scale` | Scale | 拡大 | Enlarges the target. |
| `rotate` | Rotate | 回転 | Rotates the target. |
| `shake` | Shake | シェイク | Shakes the target left/right. |
## 8. Fade
`fade` is a static effect state. `fadeOpacity` and `fadeSaturation` are configurable; defaults are `0.30 / 0.55`. State-A to state-B visual transition belongs to #118 Transition; #116 Fade is not a substitute for #118.
## 9. Glow
`glow` uses `glowBlur1` / `glowBlur2` / `glowColor`; defaults are `6px / 14px`. The color must be a #040 solid color.
## 10. Shadow
`shadow` uses `shadowX` / `shadowY` / `shadowBlur` / `shadowColor`; defaults are `4px / 4px / 7px`. The demo chooses a color that remains distinguishable from the demo background; that demo color is not the Runtime default.
## 11. Blur / Opacity
Blur exposes `blurRadius` (default `2px`); Opacity exposes `opacity` (default `0.58`). Use the actual values instead of a generic Intensity.
## 12. Color Change
Color Change replaces Text color with the selected solid color. CSS named colors and Gradient objects are rejected for Effect colors.
## 13. Scale / Rotate / Shake
Scale exposes `scale` (default `1.12`), Rotate exposes `rotateAngle` (default `8deg`), and Shake exposes `shakeDuration` (default `0.62s`) plus `shakeDistance` (default `7px`). #117 Animation Timeline/Job/Schedule responsibility is not added to #116.
## 14. #040 ColorPicker Caller
The test page does not use native ``. A Consumer-owned color button opens the canonical #040 Caller:
```js
BoneColorPicker.attachCaller(trigger, {
id: "effect-glow-color",
type: "COLORPICKER",
value: "#35F4FF"
}, {
allowedKinds: ["solid"],
onReturn(output) {
BoneEffect.setOptions(effectInstance, {
glowColor: output.value
});
}
});
```
Do not copy #040 internal chips, Overlay DOM, or CSS into #116.
## 15. #118 Transition
#118 Transition owns **one-time visual interpolation for ENTER / EXIT between semantic states**. Its responsibility is separate from the nine formal #116 Effects.
### Difference from #116 Effect
| Item | #116 Effect | #118 Transition |
|---|---|---|
| Main purpose | Apply / clear an Effect state on a target | One-time visual interpolation during ENTER / EXIT |
| State ownership | #116 owns Effect application state | Consumer owns semantic open / closed / hidden state |
| `fade` | Static faded Effect state | Fade In / Fade Out ENTER / EXIT |
| `scale` | Enlarged Effect state | Scale In / Scale Out ENTER / EXIT |
| HTML Functional Class | `bf-effect` | `bf-transition` |
| Direct #116 dependency | ― | **No direct dependency** |
Do not add `data-transition`, `data-direction`, or `data-speed` to `bf-effect`. Transition settings are not formal #116 Properties.
### #118 when #116 opens #040 ColorPicker
Shadow / Glow / Color Change color Properties use the canonical #040 ColorPicker Caller. The actual path is:
```text
#116 color Property button
-> BoneColorPicker.attachCaller(...)
-> #040 Picker Panel
-> #040 internal bf-transition
-> #118 ENTER / EXIT
-> select a solid color
-> RETURN
-> BoneEffect.setOptions(...)
```
#116 does not directly drive #118 in this path. **#040 owns Picker Panel open / closed semantic state and #118 owns only visual ENTER / EXIT**. #116 only consumes the color returned by #040.
### Using Transition on the Effect Target itself
If a Consumer also needs ENTER / EXIT on the Effect Target, configure #118 as a **separate Component** instead of adding a Transition Property to #116. One safe composition is a `bf-transition` Target Part wrapping the real `bf-text bf-effect` target.
```html
Effect Text
```
Mounting `bf-transition` does not automatically infer ENTER / EXIT. The Consumer obtains the mounted instance and invokes Runtime APIs.
```js
const host = document.querySelector('.bf-transition');
const transition = BoneTransitionFunctionalClass.getInstance(host);
async function enterTarget() {
host.hidden = false;
await BoneTransition.enter(transition);
}
async function exitTarget() {
await BoneTransition.exit(transition);
host.hidden = true;
}
```
Semantic state such as `hidden`, `open`, and `closed` remains Consumer responsibility.
### Formal #118 settings
`data-transition` accepts these 23 values:
`fade`, `slide`, `slide-fade`, `scale`, `scale-fade`, `zoom`, `zoom-fade`, `dissolve`, `wipe`, `reveal`, `expand`, `drop`, `pop`, `flip-x`, `flip-y`, `curtain-horizontal`, `curtain-vertical`, `shutter-horizontal`, `shutter-vertical`, `fold`, `rise`, `teleport-up`, `iris`
Other formal settings:
- `data-direction`: `up / down / left / right`
- `data-speed`: `slow / normal / fast`
- `data-respect-reduced-motion`: `true / false`
- `bf-transition` requires the three relation attributes `data-transition-ui-no`, `data-target-ui-no`, and `data-target-part`.
The completed #118 guide is the formal source for detailed behavior of all 23 transitions. #116 does not absorb those transitions into its own Effect inventory.
## 16. Demo Background / Text Color
Background and Text Color on the test page are Demo Sample values used only to make effects easy to see. They are not formal BoneEffect Properties. Shadow / Glow / Color Change colors are formal Effect colors and remain separate.
## 17. #002 Joint relation image
The relation image is not a decorative CSS line. Every case is evaluated with #002 Bone Joint v1.1.36 `BoneJoint.evaluate()` and drawn with real `BoneJoint.drawLine()` / error / compatibility markers. Diagnostics keep Source, Target, Field, Compatibility, Joint State, and Raw State separate.
The six formal cases are CONNECTED, missing Effect source, missing Text target, TYPE-MISMATCH, DISCONNECTED, and RECONNECT. TYPE-MISMATCH uses STRING → INT and therefore produces `JOINT_TYPE_INCOMPATIBLE`; numeric Source → STRING is coercible in #002 and is not used as the mismatch fixture. Missing endpoints do not animate. DISCONNECTED uses the #002 disconnected color, dashed line, and a `//` break. RECONNECT uses the #002 reconnecting color/animation without a #116 color override. Layer order is line → nodes → abnormal foreground marker.
## 18. WAIT / FIFO / BLOCKED
OUT uses an independent Delivery Sandbox and the real `BoneEffect.connectOutput()` → #002 `createDeliveryChannel()` path.
- WAIT keeps the Joint connected, shows the native `.bf-joint-waiting-spinner`, queues WAIT-A / WAIT-B / WAIT-C, returns Target to READY after three seconds, and verifies FIFO delivery in that exact order.
- BLOCKED keeps the Joint connected, shows `.bf-joint-blocked-ban` (`fa-ban`) with `data-animation="beat-fade"`, and does not deliver the blocked output.
- DISCONNECT and RECONNECT remain separate states.
The visual confirmation checkboxes are enabled only after the corresponding real cycle succeeds.
## 19. Security
Security is an independent **Source / Joint IN → #116 Security Gate → #116 Effect Sandbox (#017 Text)** flow. The sandbox uses real `BoneText.create()` plus `BoneEffect.create()/attach()/apply()`.
Valid Glow is accepted only in the sandbox. Unknown Effect, CSS named color, Gradient object, and accessor input are blocked. Accessor getter/setter is not evaluated. A blocked case keeps both the previous Security Sandbox options and the normal Preview and uses the #002 BLOCKED foreground marker.
## 20. Property Editor
The Property Editor has a real Japanese / English switch. The language switch changes labels only and does not mutate Runtime values. Selecting an Effect shows only that Effect's formal settings. Apply Property sends the actual values through `BoneEffect.setOptions()` and updates the real Preview CSS. Color Properties use the #040 Caller; native `input[type=color]` is not used.
## 21. Preview
The Preview target is a real #017 Text element created by `BoneText.create()` and attached through `BoneEffect.attach()`. No generic Target or invented `effectTarget` field is used.
## 22. Smoke Test
Smoke starts as NOT RUN and reports individual rows, start time, count, PASS, FAIL, and duration. It checks formal dependencies, all nine Effects, real `bf-effect` mount, #040 Caller, the six #002 relation cases, the actual mismatch fixture, Property language switching, Security sandbox, and Delivery channel.
## 23. Validation
Validation fixes the visual/runtime contracts: STRING → INT mismatch, non-animated missing endpoints, disconnected dashed + `//`, #002 reconnect animation, native WAIT spinner, native BLOCK fa-ban + beat-fade, Security preservation, report controls, and no native color input. Test expectations are not weakened to hide a visual mismatch.
## 24. Cumulative Regression
The cumulative page opens `bone-effect.html` in a fresh iframe and clicks the real Smoke / Validation controls. The #116 bundle, Smoke, Validation, and Runtime 1.0.14 rows are cumulative. A #116 failure makes #000 overall fail. No runtime DOM `cloneNode(true)` repair is used.
## 25. Completion
Completion requires Smoke ALL PASS, Validation ALL PASS, a successful three-second WAIT/FIFO cycle and manual WAIT confirmation, plus a successful BLOCK non-delivery cycle and manual BLOCK visual confirmation. The button calls the real `BoneEffect.complete()` persistence path. The package remains Development / Candidate until user localhost confirmation.
## 26. Public API
`normalizeEffect`, `normalizeOptions`, `inspectUntrustedOptions`, `create`, `attach`, `apply`, `clear`, `setOptions`, `getOptions`, `getState`, `buildOutput`, `connectOutput`, `disconnectOutput`, `setOutputTargetReady`, `clearOutputBlock`, `getOutputState`, `destroy`, `isInstance`, `getCompletionState`, `complete`, `reopen`.
## 27. Error / Troubleshooting
- `EFFECT_TYPE_INVALID`: value is outside the formal nine effects.
- `EFFECT_ACCESSOR_BLOCKED`: getter/setter rejected without evaluation.
- `EFFECT_COLOR_KIND_INVALID`: Effect color is not a solid color.
- `EFFECT_GLOW_COLOR_REQUIRED`: Glow color missing.
- `EFFECT_SHADOW_COLOR_REQUIRED`: Shadow color missing.
- `EFFECT_COLOR_CHANGE_COLOR_REQUIRED`: Color Change color missing.
- `EFFECT_TARGET_INVALID`: invalid target element.
- `EFFECT_OUTPUT_UNBOUND`: no delivery channel.
## 28. Version / Status
Runtime v1.0.14 Candidate. Status remains Development before user localhost confirmation. Assistant-generated v1.0.0-v1.0.12 are rejected and are not implementation baselines.