@kubohiroya/turbowarp-diagnostic-overlay 0.5.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,25 @@
2
2
 
3
3
  このプロジェクトの注目すべき変更を記録します。形式は[Keep a Changelog](https://keepachangelog.com/ja/1.1.0/)に基づき、[Semantic Versioning](https://semver.org/lang/ja/)に従います。
4
4
 
5
+ ## [0.7.0] - 2026-10-27
6
+
7
+ ### Changed
8
+
9
+ - 共通data-editorとmanifest 0.4.0、vite-plugin 0.9.0へ追従し、版・lockfile・配布物・利用例を更新します。
10
+ - 診断オーバーレイのruntime APIと拡張ブロックの契約を維持します。
11
+ - 切り戻しは`@kubohiroya/turbowarp-diagnostic-overlay@0.6.0`への固定です。
12
+
13
+ ## [0.6.0] - 2026-10-26
14
+
15
+ ### Changed
16
+
17
+ - 共通エディター0.3.4、ビルドプラグイン0.8.0へ追従し、配布物を再生成しました。
18
+ - 既存API・保存形式・既定OFFの機能フラグを維持します。
19
+
20
+ ### Compatibility
21
+
22
+ - 移行は不要です。問題がある場合は0.5.1へ固定して切り戻せます。
23
+
5
24
  ## [0.5.1] - 2026-10-19
6
25
 
7
26
  ### Changed
package/README.ja.md ADDED
@@ -0,0 +1,154 @@
1
+ # TurboWarp-Diagnostic-Overlay
2
+
3
+ <img src="assets/block-icon.svg" alt="" width="48" height="48">
4
+
5
+ [English](README.md) | 日本語
6
+
7
+ 構造化された診断データを検証し、安全なSVGテキストとして描画して、ステージ上に表示する
8
+ アプリケーション非依存のTurboWarp拡張機能です。特定のアプリケーションやDSLに依存しません。
9
+
10
+ 導入手順、Composition API、安全性、lifecycleの挙動は
11
+ [English guide](https://kubohiroya.github.io/turbowarp-diagnostic-overlay/)および
12
+ [日本語ガイド](https://kubohiroya.github.io/turbowarp-diagnostic-overlay/ja/)で扱っています。
13
+
14
+ ## 責務の境界
15
+
16
+ このpackageが行うのは、診断データの検証、SVGの生成、現在のoverlayの表示・更新・消去です。診断の検出、
17
+ 必要に応じたプロジェクトやScratch threadの停止、ログの永続化は呼び出し側の責務です。
18
+
19
+ rendererは外部のSVGやHTMLを受け付けず、入力文字列をすべてXMLエスケープします。overlayは
20
+ `pointer-events: none`を使うため、ステージ上のマウスやタッチの入力を妨げません。
21
+
22
+ ## インストール
23
+
24
+ [`dist/diagnostic-overlay.js`](dist/diagnostic-overlay.js)をTurboWarp Desktopでローカルの
25
+ カスタム拡張機能として読み込み、**サンドボックス化せずに実行**を許可します。
26
+
27
+ npmから導入する場合は、レビュー済みのversionを固定します。
28
+
29
+ ```bash
30
+ pnpm add --save-exact @kubohiroya/turbowarp-diagnostic-overlay@0.7.0
31
+ ```
32
+
33
+ standaloneの拡張機能は、version固定の次のCDN URLからも取得できます。
34
+
35
+ ```text
36
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-diagnostic-overlay@0.7.0/dist/diagnostic-overlay.js
37
+ ```
38
+
39
+ 機械可読なblock API manifestは、ビルド時に`src/block-definitions.json`から生成します。利用側は
40
+ 実行時bundleを評価することなく、拡張機能ID、opcode、block種別、引数のIDと型、menu参照を固定して
41
+ 検証できます。
42
+
43
+ ```text
44
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-diagnostic-overlay@0.7.0/dist/extension-manifest.json
45
+ ```
46
+
47
+ ## 診断JSON
48
+
49
+ 必須フィールドは`severity`、`code`、`message`です。`severity`の値は`info`、`warning`、`error`、
50
+ `fatal`のいずれかでなければなりません。
51
+
52
+ ```json
53
+ {
54
+ "severity": "error",
55
+ "code": "DSL401",
56
+ "message": "Stage is not defined",
57
+ "detail": "stage2 has not been registered.",
58
+ "source": {
59
+ "name": "story.kamishibai",
60
+ "line": 18,
61
+ "column": 7,
62
+ "excerpt": "goto: stage2"
63
+ }
64
+ }
65
+ ```
66
+
67
+ 行番号と列番号は1始まりの正の整数です。空文字列の任意フィールドは省略として扱います。未知の
68
+ フィールドは前方互換のため無視します。
69
+
70
+ ## ブロック
71
+
72
+ | block | 種別 | opcode | 動作 |
73
+ |---|---|---|---|
74
+ | `show [SEVERITY] diagnostic [CODE]: [MESSAGE]` | Command | `showDiagnostic` | 単純な診断をTurboWarpのステージへ表示します。 |
75
+ | `show diagnostic JSON [DIAGNOSTIC]` | Command | `showDiagnosticJson` | 構造化された診断JSONを1件検証して表示します。 |
76
+ | `clear diagnostic overlay` | Command | `clearDiagnosticOverlay` | プロジェクトを停止せずに現在のoverlayを消します。 |
77
+ | `diagnostic overlay is visible?` | Boolean | `diagnosticOverlayVisible` | 診断overlayが表示中かどうかを返します。 |
78
+ | `diagnostic SVG for JSON [DIAGNOSTIC]` | Reporter | `diagnosticSvg` | 表示せずに、診断1件分の安全なSVGテキストを返します。 |
79
+ | `last diagnostic JSON` | Reporter | `lastDiagnosticJson` | 最後に表示した正規化済みの診断をJSONで返します。無ければ空文字列です。 |
80
+
81
+ `SEVERITY`は`severityMenu`から選び既定は`error`、`CODE`の既定は`APP001`です。reporter系と
82
+ `diagnostic overlay is visible?`はmonitorを無効にしています。
83
+
84
+ ## Composition API
85
+
86
+ packageのrootと`/composition`はside effectのないESmoduleで、TurboWarpへ拡張機能を自動登録しません。
87
+
88
+ ```ts
89
+ import {
90
+ createDiagnosticOverlayComposition,
91
+ renderDiagnosticSvg
92
+ } from '@kubohiroya/turbowarp-diagnostic-overlay/composition';
93
+
94
+ const {extension, controller} = createDiagnosticOverlayComposition(Scratch);
95
+
96
+ // Register once at the composition root.
97
+ Scratch.extensions.register(extension);
98
+
99
+ controller.show({
100
+ severity: 'error',
101
+ code: 'APP001',
102
+ message: 'Check the input.'
103
+ });
104
+
105
+ const svg = renderDiagnosticSvg({
106
+ severity: 'warning',
107
+ code: 'APP002',
108
+ message: 'This value is deprecated.'
109
+ });
110
+ ```
111
+
112
+ 拡張機能もoverlay controllerも不要な場合は、純粋なrendererを
113
+ `@kubohiroya/turbowarp-diagnostic-overlay/svg-renderer`からimportしてください。
114
+
115
+ 完全な契約は[日本語仕様](docs/ja/specification.md)または[English specification](docs/specification.md)を
116
+ 参照してください。
117
+
118
+ ## 開発
119
+
120
+ Node.js 24以降とCorepackを使います。
121
+
122
+ ```bash
123
+ npm install --global corepack@latest
124
+ corepack enable
125
+ pnpm install --frozen-lockfile
126
+ pnpm run check
127
+ pnpm run release:check
128
+ ```
129
+
130
+ `dist/diagnostic-overlay.js`と`dist/extension-manifest.json`は、レビュー可能な生成成果物として
131
+ commitしてあります。block定義を変更したら`pnpm run docs`を実行してREADMEを更新してください。
132
+
133
+ ## リリース
134
+
135
+ `package.json`、このREADME、公開ガイド、`CHANGELOG.md`の固定versionは、リリースのPRごとに揃えて
136
+ ください。`main`でCIとPagesのデプロイが成功したら、そのmerge commitに`v<version>`タグを作成します。
137
+ タグをpushするとGitHub Releaseとstandalone拡張機能の成果物が作られます。同じversionをnpmへ
138
+ ちょうど1回公開します。利用側は直前のversionを固定することで切り戻せます。
139
+
140
+ ## ライセンス
141
+
142
+ SPDX-License-Identifier: MPL-2.0
143
+
144
+ ## 固定引数の編集フォーム(S3-4)
145
+
146
+ 共通エディターの起動時フラグ `blockEditorFixedInputs` とDialogsがONのGUIでは、`showDiagnostic` の `SEVERITY` だけを固定フォームとして登録します。旧GUI・フラグOFFでは追加登録を行いません。Schemaの正本は `schemas/block-editor-fixed-inputs.schema.json#/$defs/showDiagnostic/properties/SEVERITY`、codecと登録は `src/fixed-input-editors.ts` です。既存raw値・未変更alias・未知enumは無操作保存で書き換えず、reporterを評価しません。明示変更だけを検査し、他の引数やブロック宣言、保存形式を変更しません。
147
+
148
+ SEVERITYの候補はinfo/warning/error/fatalです。既存runtimeのtrim/lowercaseを投影へ適用し、未変更の原文は保持します。CODE/MESSAGEは今回のbindingに追加しません。
149
+
150
+ 登録はoptional API(apiVersion:1)に限定し、RUNTIME_DISPOSED/明示disposeで解除します。起動フラグOFF+再読込で従来経路へ切り戻せます。依存を戻す場合はmanifest/lock/実解決を一組で復旧します。npm公開や後続段階の動的候補は含みません。
151
+
152
+ Schemaが記述する契約の根拠は実getInfoの宣言と既存の純粋なruntime変換です。SchemaBundleのretrievalUriはこのローカル文書の識別子であり、URL配信済み・HTTP取得によるref解決を意味しません。Schemaは同梱文書だけでcompileします。
153
+
154
+ 登録には、拡張機能のinstanceを構築した時点で利用できる任意のeditor APIを使います。そのAPIを後から追加・差し替えしても自動では追従しません。起動時の設定を変更したら、GUIを再読み込みして拡張機能のinstanceを作り直してください。
package/README.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # TurboWarp-Diagnostic-Overlay
2
2
 
3
+ <img src="assets/block-icon.svg" alt="" width="48" height="48">
4
+
5
+ English | [日本語](README.ja.md)
6
+
3
7
  An application-neutral TurboWarp extension that validates structured diagnostics, renders them as
4
8
  safe SVG text, and displays them over the stage. It does not depend on a particular application or
5
9
  DSL.
@@ -25,13 +29,13 @@ TurboWarp Desktop and allow it to **run without the sandbox**.
25
29
  When installing from npm, pin the reviewed version:
26
30
 
27
31
  ```bash
28
- pnpm add --save-exact @kubohiroya/turbowarp-diagnostic-overlay@0.5.1
32
+ pnpm add --save-exact @kubohiroya/turbowarp-diagnostic-overlay@0.7.0
29
33
  ```
30
34
 
31
35
  The standalone extension is also available from this version-pinned CDN URL:
32
36
 
33
37
  ```text
34
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-diagnostic-overlay@0.5.1/dist/diagnostic-overlay.js
38
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-diagnostic-overlay@0.7.0/dist/diagnostic-overlay.js
35
39
  ```
36
40
 
37
41
  The machine-readable block API manifest is generated from `src/block-definitions.json` during the
@@ -39,7 +43,7 @@ build. Consumers can pin and verify the extension ID, opcodes, block types, argu
39
43
  and menu references without evaluating the runtime bundle:
40
44
 
41
45
  ```text
42
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-diagnostic-overlay@0.5.1/dist/extension-manifest.json
46
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-diagnostic-overlay@0.7.0/dist/extension-manifest.json
43
47
  ```
44
48
 
45
49
  ## Diagnostic JSON
@@ -170,9 +174,10 @@ See the [English specification](docs/specification.md) or
170
174
 
171
175
  ## Development
172
176
 
173
- Use Node.js 22.12 or later with Corepack.
177
+ Use Node.js 24 or later with Corepack.
174
178
 
175
179
  ```bash
180
+ npm install --global corepack@latest
176
181
  corepack enable
177
182
  pnpm install --frozen-lockfile
178
183
  pnpm run check
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48"><rect x="6" y="12" width="32" height="24" rx="4" fill="none" stroke="#4C97FF" stroke-width="3"/><path d="M30 16l11 20H19z" fill="#FFAB19"/><path d="M30 24v5" fill="none" stroke="#fff" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/><circle cx="30" cy="33" r="1.7" fill="#fff"/></svg>