# Bone Flow #023 - Bone Flow Syntax

Version: 1.0.79  
Status: Release Ready Candidate

## Source 原則

`.bflow` Source は UTF-8、改行は LF に正規化します。Parser/SourceMap offset は JavaScript string と同じ UTF-16 code unit 基準です。

## Directive

```text
@id sample-flow
@title "Sample Flow"
@version 1.0.0
@flow direction=LR
@theme light
@shape scale=1
@joint line=straight
@joint animate=false
@joint speed=normal
@joint intersection=jump
@layout mode=auto
@layout gap=120
@layout branch-gap=80
```

v1.0 global Joint style/width は Canonical で `solid / 4` 固定です。Source directive として別値へ変更しません。

## Node

代表形:

```text
(start:開始)
[work:処理]
<decision:判定>
{io:入出力}
[[sub:サブ処理]]
((end:終了))
[custom:TYPE:表示名]
```

Node option:

```text
[node:PROCESS:処理] {manual,x:120,y:240,theme:dark,scale:1.2,comment:"説明",tooltip:"詳細"}
```

`comment:""` / `tooltip:""` は Source では受理して semantic `null` へ正規化します。Canonical JSON の string は非空のみです。

## TABLE_DETAIL Field

```text
[customers:TABLE_DETAIL:顧客]
{
    customer_id : 顧客ID : INT {pk}
    name : 顧客名 : VARCHAR(255) {required}
}
```

Field selector:

```text
[customers].customer_id.OUT -> [orders].customer_id.IN
```

source は OUT、target は IN が必須です。

## Joint

### Joint quick visual options (v1.0.34)

Joint option block supports the following additional per-Joint visual settings.

- `color:"#RRGGBB"` — line color. `#` must remain inside the quoted value so it is not parsed as an inline comment.
- `clearance:0..120` — straight Port clearance before the route turns. Default resolved value is `40`.

Example: `[a].BOTTOM =>{color:"#55aaff",clearance:40,animate:true} [b].TOP`

The existing label connector remains the formal line comment mechanism. Example: `[a] ="確認"=> [b]` renders `確認` on the Joint through #002 Joint Label.


```text
[a] -- [b]
[a] -> [b]
[a] ~> [b]
[a] => [b]
```

Label 付き Joint の label は grammar 上常に double quote で囲みます。

```text
[check] ="承認"=>{key:YES,dashed,width:6} [ok]
```

Options:

- `key:YES` / `key:NO`
- `animate:true|false`
- `speed:slow|normal|fast`
- `solid|dashed|dotted|dash-dot`
- `width:1..12`
- `jump|nojump`

## Multi-line continuation

Joint operator が次行にある continuation を正式対応します。空行・directive・comment境界では chain を継続しません。1つの chain は隣接 endpoint ごとに Joint へ展開します。

## SourceMap

Duplicate Node/Field を保持できるよう declaration は `SourceRef[]` です。Node reference は rename transaction 用に whole token SourceRef を保持し、validation用の node/field/selector exact ref は runtime internal metadata に分離しています。

`error-flow.bflow` CASE 3 の正式値:

- Joint source: UTF-16 `422..481`
- `SIDEWAYS`: UTF-16 `446..454`
- `SIDEWAYS` column: `25`

`SIDEWAYS` は parser failure ではなく invalid Working selector となり、Validation が `INVALID_FIELD_PORT` を生成します。


## RETURN Port（v1.0.34）

Shape の物理Port位置は #002 Bone Joint v1.1.29 の実効Roleへ解決されます。TB方向の通常Shapeは `TOP=IN / RIGHT=RETURN / BOTTOM=OUT / LEFT=RETURN` です。通常接続は `OUT -> IN`、差戻しは `OUT -> RETURN` または `RETURN -> RETURN` が有効です。

RETURNは `.RETURN` というRole suffixではなく、物理位置 selector で記述します。TB方向の例：

```text
[ng].LEFT => [request].LEFT
```

この例は `LEFT RETURN -> LEFT RETURN` として検証されます。`OUT -> RETURN` も正式に有効です。`RETURN -> IN` と `OUT -> OUT` は `JOINT_PORT_ROLE_INCOMPATIBLE` です。Decisionは正式分岐仕様を優先し、TB方向で `TOP=IN / RIGHT=第1 branch OUT / BOTTOM=第2 branch OUT / LEFT=RETURN` として扱います。branch key の文字列自体は固定しません。

## v1.0.34 フロー設定ミニメニュー

`@id`, `@title`, `@version`, `@flow direction`, `@theme`, `@joint line`, `@joint animate`, `@layout mode`, `@layout gap` はSourceの正式directiveのまま保持し、日本語UIから編集できます。UI独自設定へ変換せず、適用時にSourceへ同期します。

## v1.0.35 Error Flow描画補正

Syntax grammarの追加・変更はありません。`@flow direction`、`@joint line`、`@joint animate`、Field selector等の既存Syntaxをそのまま使用し、Error Flow PreviewのEndpoint→#002 Joint Adapter接続のみを補正します。


## v1.0.36 Error Flow direction display rule

`@flow direction=TB` / `BT` changes the CASE-group arrangement to vertical. TABLE_DETAIL FIELD endpoints themselves are not rotated: FIELD IN remains left and FIELD OUT remains right.


## v1.0.37 FIELD direction invariant

For `TABLE_DETAIL`, `[node].field.IN` always resolves to the actual LEFT FIELD Port and `[node].field.OUT` always resolves to the actual RIGHT FIELD Port. `@flow direction` never rotates FIELD Port semantics.


## v1.0.40 rendering note

Syntax and FIELD semantics are unchanged. FIELD IN remains LEFT and FIELD OUT remains RIGHT. The change is limited to the adapter conversion between #023 logical workspace coordinates and #002 pixel-mode SVG drawing under zoom.


## v1.0.48 Error marker rendering note

No syntax change. Error codes keep the same meaning. The preview now renders the diagnostic × with #002 `BoneJoint.drawError()` in the same SVG as the #002 Joint path.


## v1.0.48 Curve Side

Per-Joint Curve direction can be requested with `{curve-side:auto}`, `{curve-side:left}`, or `{curve-side:right}`. It affects Curve routing only and is delegated to #002 Bone Joint v1.1.29.


## v1.0.51 RETURN display note

Physical RETURN selectors remain part of the canonical Joint syntax. The word `RETURN` is not displayed in Preview. When a RETURN position is the active send position during a return flow, that position is displayed as `OUT`; the original OUT position is treated as RETURN and its RETURN text remains hidden.

## v1.0.52 RETURN re-output display

Syntax remains physical-position based. For `[ng].LEFT => [request].LEFT`, both selectors remain physical LEFT RETURN. Preview only changes presentation: `ng.LEFT` shows `OUT`, the former OUT position has no OUT text, and `RETURN` text is not displayed.


## v1.0.55 Decision branch display

`{key:...}` is the visible Decision branch identifier and is not limited to YES / NO. The first source-defined Decision branch is displayed at RIGHT and the second at BOTTOM; examples include `はい / いいえ`, `営業日 / 休日`, or any other unique key text. A quoted connector label such as `="承認"=>{key:はい}` remains a separate Joint comment. Branch-key labels are offset away from the outgoing path so the path does not run through the text.


## v1.0.65 Input Guide

Syntax自体の変更はありません。Source Editorの「入力ガイド」から、#021 Registry実Shape画像、Node / Joint / Port / RETURN / TABLE_DETAIL / Directiveの説明と挿入可能なコード例を参照できます。正式利用ガイドは `023-Input-Guide.md` です。