PanelConfig フォーマット

PanelConfig は、エディタがパネルの注文成果物としてダウンロードする、バージョン付きの JSON エンベロープです。serializePanelConfig() によって生成され、 parsePanelConfig() によって読み込まれます。どちらも @zpd/core からエクスポートされています（ソース: packages/core/src/serialize.ts）。

エンベロープの形

{
  "version": 5,
  "app": "zpd",
  "panel": { "hp": 12, "widthMm": 60.6, "heightMm": 128.5 },
  "palette": ["black", "gold", "white"],
  "layers": [
    { "kind": "pcb-layer", "id": "pcb-layer-copper", "role": "copper", "children": [] },
    { "kind": "pcb-layer", "id": "pcb-layer-solder-mask", "role": "solder-mask", "children": [] },
    { "kind": "pcb-layer", "id": "pcb-layer-silkscreen", "role": "silkscreen", "children": [] }
  ],
  "guides": []
}

Field	Type	備考
`version`	`5`	`PANEL_CONFIG_VERSION`。下記のバージョニングを参照。
`app`	`"zpd"`	生成元のアプリを識別する固定のリテラル。
`panel.hp`	`number`	Eurorack HP でのパネル幅。ライブドキュメント（`doc.panelHp`）から取得。
`panel.widthMm`	`number`	`panelWidthMm()` を介して `hp` から導出される——参考用の出力であり、インポート時には再び信頼されない（下記参照）。
`panel.heightMm`	`number`	`PANEL_HEIGHT_MM`、固定の 3U Eurorack パネル高さ（128.5mm）。
`palette`	`string[]`	固定の 3 色の名前を、インデックス順に並べたもの: `["black", "gold", "white"]`。
`layers`	`PcbLayerContainer[]`	Copper、Solder mask、Silkscreen の固定コンテナを物理的な下から上の順で保持します。
`guides`	`Guide[]`	ドキュメントのルーラーガイド。v2 で追加（バージョニングを参照）。ガイドのフィールドを参照。

Note

panel.widthMm、panel.heightMm、palette は、人間や注文システムの読み手のための派生的・参考用の出力です——これらは、人や下流の製造ツールが hp から寸法を再計算しなくてもファイルを読めるように存在します。読み込み時には、parsePanelConfig は手編集された値を信頼せず、hp からこれらを再計算します。panel.hp と layers が正式なソースデータです。

固定マテリアルコンテナ

v5 は Copper、Solder mask、Silkscreen の 3 つの固定ルートを物理的な下から上の順で保存します。各ルートは kind: "pcb-layer"、固定 id、role、任意の hidden、通常の children を持ちます。UI は逆順に表示します。コンテナ所属が gold/HASL の銅、黒のソルダーマスク、白のシルクスクリーンという実効マテリアルを決めます。Solder mask の子は被覆ではなく開口で、マスクを抜く位置を表します。そのため Solder mask ルートに hidden: true が保存されていればマスクはどこにもなく、逆に空のまま表示されていれば全面がマスクで覆われた状態になります。

これらのルートは通常グループではないため、名前変更、削除、選択、グループ化、並べ替えはできません。通常グループは各ルート内で使え、アートワークをルート間で移動できます。

レイヤーのフィールド

5 つのレイヤータイプはすべて、共通のベース構造に加えてタイプ固有のフィールドを持ちます。

すべてのレイヤーに共通

Field	Type	備考
`id`	`string`	安定したレイヤー id。インポート時に欠落/空なら type/group に基づく決定的なフォールバックを使い、衝突には安定した数字サフィックスを付ける。
`name`	`string`	表示名。欠落している場合は `""` がデフォルト。
`hidden`	`boolean`（任意）	レイヤーが一度も非表示にされていない間は省略される。表示状態が一度でも切り替えられると、このフィールドは明示的に書き込まれる——偶数回切り替えた後の `false` も含めて——トグル操作は既にある値を反転させるため。
`type`	`'shape' \| 'pattern' \| 'path' \| 'text' \| 'image'`	以下のフィールドを判別する。

`shape`

Field	Type	備考
`shape`	`'rect' \| 'ellipse'`
`x`, `y`, `width`, `height`	`number`	ミリメートル、ドキュメント空間。
`rotation`	`number`（任意）	bbox の中心を軸にした時計回りの度数。未設定のときは省略される。
`color`	`0 \| 1 \| 2`	ColorIndex を参照。

`pattern`

Field	Type	備考
`patternType`	`string`	自由形式の識別子（例: `"dot-grid"`）。認識できなくてもそのまま保持される——core は、それを検証するパターンレジストリに依存していない。
`params`	`Record<string, number>`	パターン固有の数値パラメータ（例: `pitch`、`radius`）。
`x`, `y`, `size`	`number`	移動可能な正方形の位置と辺長（ミリメートル）。
`color`	`0 \| 1 \| 2`

`path`

Field	Type	備考
`points`	`PathPoint[]`	プライマリのサブパス——ペンツールが編集するもの。PathPoint を参照。
`extraSubpaths`	`PathPoint[][]`（任意）	追加の閉じたサブパス。例えば画像トレースで生成される穴や島。存在・非存在（空配列であっても）はラウンドトリップのために正確に保持される。
`closed`	`boolean`
`fill`	`0 \| 1 \| 2 \| null`	`null` は塗りなしを意味する。
`stroke`	`0 \| 1 \| 2 \| null`	`null` は線なしを意味する。
`strokeWidth`	`number`	ミリメートル。

PathPoint

Field	Type	備考
`x`, `y`	`number`	アンカー点、ミリメートル。
`hin`	`{ x: number, y: number }`（任意）	絶対座標のベジェ handle-in。
`hout`	`{ x: number, y: number }`（任意）	絶対座標のベジェ handle-out。

`text`

Field	Type	備考
`content`	`string`	改行を含んでもよい。
`fontFamily`	`string`
`sizeMm`	`number`	ミリメートル単位のフォントサイズ（キャンバスのフォント px は、ドキュメント空間では mm に等しい）。
`x`, `y`	`number`	バウンディングボックスの左上、ミリメートル。
`rotation`	`number`（任意）	時計回りの度数。未設定のときは省略される。
`color`	`0 \| 1 \| 2`

`image`

Field	Type	備考
`src`	`string`	データ URL。設計時の参照のみ——ラスターは製造できず、最終的なパネルはそこからトレースされたベクターレイヤーを使う。
`x`, `y`, `width`, `height`	`number`	ミリメートル。
`rotation`	`number`（任意）	bbox の中心を軸にした時計回りの度数。

ガイドのフィールド

guides 配列の各エントリはルーラーガイド——レイヤーではなく基準線——です（ドキュメントの状態とレイヤー → ガイドを参照）。

Field	Type	備考
`id`	`string`	安定したガイド id。インポート時に欠落または重複していれば決定的に生成・衝突修復される。
`orientation`	`'horizontal' \| 'vertical'`	必須。`horizontal` ガイドは直線 `y = position`、`vertical` ガイドは `x = position`。それ以外の値のエントリはインポート時に破棄される（有効な軸を持たないガイドは線を引けない）。
`position`	`number`	線の座標（ミリメートル）。必須かつ有限。`position` が欠落・非有限のエントリは、`0` にデフォルト化されるのではなく破棄される。
`hidden`	`boolean`（任意）	設定されていなければ省略される。hidden なガイドは薄く描画され、決してスナップしない。

ColorIndex + パレット

すべてのレイヤーの互換用 color（および path レイヤーの fill／stroke 有効状態）は ColorIndex（0、1、2 のいずれか）を使います。v5 では所属する固定コンテナが正式な値であり、null でない各 paint フィールドはそのマテリアルのインデックスへ正規化されます。対応は packages/core/src/palette.ts で一度だけ定義されます。

Index	Name	意味
`0`	`black`	ソルダーマスク
`1`	`gold`	製品の HASL 仕上げによる露出銅
`2`	`white`	シルクスクリーン

エンベロープ内の palette 配列（["black", "gold", "white"]）は、これらの名前をインデックス順に並べたものです——JSON の読み手が、インデックスと名前の対応を暗記していなくても済むように存在します。パレットは固定であり、ドキュメントごとにユーザーが設定できるものではありません。

バージョニング

PANEL_CONFIG_VERSION は現在 5 で、PanelConfig 型は version: 5 に固定されています。v1–v4 の自由なルートレイヤーはインポート時に固定マテリアルスタックへ決定的に移行されます。v5 入力も固定ルートの欠落、重複、順序違いを防御的に修復します。これはバージョン付き JSON の移行であり、Gerber 出力形式ではありません。Gerber ファイルは別系統の、アートワークのみの .zip エクスポートが書き出します（PCB マテリアルレイヤーとサイズを参照）。