@kubohiroya/turbowarp-diagnostic-overlay 0.1.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.
Files changed (39) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/LICENSE +4 -0
  3. package/README.md +163 -0
  4. package/dist/diagnostic-overlay.js +574 -0
  5. package/dist/lib/block-definitions.json +58 -0
  6. package/dist/lib/composition.d.ts +22 -0
  7. package/dist/lib/composition.d.ts.map +1 -0
  8. package/dist/lib/composition.js +20 -0
  9. package/dist/lib/composition.js.map +1 -0
  10. package/dist/lib/config.d.ts +10 -0
  11. package/dist/lib/config.d.ts.map +1 -0
  12. package/dist/lib/config.js +10 -0
  13. package/dist/lib/config.js.map +1 -0
  14. package/dist/lib/diagnostic.d.ts +30 -0
  15. package/dist/lib/diagnostic.d.ts.map +1 -0
  16. package/dist/lib/diagnostic.js +120 -0
  17. package/dist/lib/diagnostic.js.map +1 -0
  18. package/dist/lib/extension.d.ts +24 -0
  19. package/dist/lib/extension.d.ts.map +1 -0
  20. package/dist/lib/extension.js +94 -0
  21. package/dist/lib/extension.js.map +1 -0
  22. package/dist/lib/index.d.ts +2 -0
  23. package/dist/lib/index.d.ts.map +1 -0
  24. package/dist/lib/index.js +8 -0
  25. package/dist/lib/index.js.map +1 -0
  26. package/dist/lib/overlay.d.ts +39 -0
  27. package/dist/lib/overlay.d.ts.map +1 -0
  28. package/dist/lib/overlay.js +140 -0
  29. package/dist/lib/overlay.js.map +1 -0
  30. package/dist/lib/scratch.d.ts +32 -0
  31. package/dist/lib/scratch.d.ts.map +1 -0
  32. package/dist/lib/scratch.js +2 -0
  33. package/dist/lib/scratch.js.map +1 -0
  34. package/dist/lib/svg-renderer.d.ts +12 -0
  35. package/dist/lib/svg-renderer.d.ts.map +1 -0
  36. package/dist/lib/svg-renderer.js +180 -0
  37. package/dist/lib/svg-renderer.js.map +1 -0
  38. package/docs/specification.md +67 -0
  39. package/package.json +90 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,15 @@
1
+ # Changelog
2
+
3
+ このプロジェクトの注目すべき変更を記録します。形式は[Keep a Changelog](https://keepachangelog.com/ja/1.1.0/)に基づき、[Semantic Versioning](https://semver.org/lang/ja/)に従います。
4
+
5
+ ## [0.1.0] - 2026-08-03
6
+
7
+ ### Added
8
+
9
+ - 汎用`Diagnostic`データモデルとJSON validator
10
+ - XMLエスケープ済みの純粋SVG renderer
11
+ - TurboWarpステージに追従する非操作型DOM overlay
12
+ - 表示、JSON表示、消去、表示中判定、SVG生成、最後の診断JSONブロック
13
+ - 副作用のない`composition`、`diagnostic`、`svg-renderer` package exports
14
+
15
+ [0.1.0]: https://github.com/kubohiroya/turbowarp-diagnostic-overlay/releases/tag/v0.1.0
package/LICENSE ADDED
@@ -0,0 +1,4 @@
1
+ Mozilla Public License Version 2.0
2
+
3
+ This project is licensed under the Mozilla Public License, version 2.0.
4
+ The full license text is available at https://www.mozilla.org/MPL/2.0/.
package/README.md ADDED
@@ -0,0 +1,163 @@
1
+ # TurboWarp Diagnostic Overlay
2
+
3
+ 構造化された診断データを安全なSVGテキストへ変換し、TurboWarpステージ上に表示する汎用機能拡張です。紙芝居DSLなど特定のアプリケーションには依存しません。
4
+
5
+ ## 責務の境界
6
+
7
+ このパッケージが担当するのは、診断データの検証、SVG生成、表示、更新、消去です。診断の発見、プロジェクトやScratchスレッドの停止、ログの永続化は利用側が担当します。
8
+
9
+ 外部からSVGやHTMLを受け取らず、すべての入力文字列をXMLエスケープします。オーバーレイは`pointer-events: none`であり、ステージのマウス・タッチ入力を妨げません。
10
+
11
+ ## インストール
12
+
13
+ TurboWarp Desktopで[`dist/diagnostic-overlay.js`](dist/diagnostic-overlay.js)をローカル機能拡張として読み込み、**サンドボックスなしで実行**を許可します。
14
+
15
+ npmから利用する場合はバージョンを固定してください。
16
+
17
+ ```bash
18
+ pnpm add --save-exact @kubohiroya/turbowarp-diagnostic-overlay@0.1.0
19
+ ```
20
+
21
+ CDN上の単独機能拡張は次のURLです。
22
+
23
+ ```text
24
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-diagnostic-overlay@0.1.0/dist/diagnostic-overlay.js
25
+ ```
26
+
27
+ ## 診断JSON
28
+
29
+ 必須フィールドは`severity`、`code`、`message`です。`severity`は`info`、`warning`、`error`、`fatal`のいずれかです。
30
+
31
+ ```json
32
+ {
33
+ "severity": "error",
34
+ "code": "DSL401",
35
+ "message": "未定義のステージです",
36
+ "detail": "stage2 は登録されていません。",
37
+ "source": {
38
+ "name": "story.kamishibai",
39
+ "line": 18,
40
+ "column": 7,
41
+ "excerpt": "goto: stage2"
42
+ }
43
+ }
44
+ ```
45
+
46
+ 行と列は1から始まる正の整数です。空の省略可能文字列は未指定として扱います。未知のフィールドは将来互換性のため無視します。
47
+
48
+ ## Blocks
49
+
50
+ <!-- BEGIN GENERATED BLOCKS -->
51
+
52
+ ### `show [SEVERITY] diagnostic [CODE]: [MESSAGE]`
53
+
54
+ Displays a simple diagnostic on the TurboWarp stage.
55
+
56
+ | Property | Value |
57
+ |---|---|
58
+ | Type | Command |
59
+ | Opcode | `showDiagnostic` |
60
+ | `SEVERITY` | String, default: `error`, menu: `severityMenu` |
61
+ | `CODE` | String, default: `APP001` |
62
+ | `MESSAGE` | String, default: `Something went wrong.` |
63
+
64
+ ### `show diagnostic JSON [DIAGNOSTIC]`
65
+
66
+ Validates and displays one structured diagnostic JSON object.
67
+
68
+ | Property | Value |
69
+ |---|---|
70
+ | Type | Command |
71
+ | Opcode | `showDiagnosticJson` |
72
+ | `DIAGNOSTIC` | String, default: `{"severity":"error","code":"APP001","message":"Something went wrong."}` |
73
+
74
+ ### `clear diagnostic overlay`
75
+
76
+ Removes the current diagnostic overlay without stopping the project.
77
+
78
+ | Property | Value |
79
+ |---|---|
80
+ | Type | Command |
81
+ | Opcode | `clearDiagnosticOverlay` |
82
+
83
+ ### `diagnostic overlay is visible?`
84
+
85
+ Returns whether a diagnostic overlay is currently visible.
86
+
87
+ | Property | Value |
88
+ |---|---|
89
+ | Type | Boolean |
90
+ | Opcode | `diagnosticOverlayVisible` |
91
+ | Monitor | Disabled |
92
+
93
+ ### `diagnostic SVG for JSON [DIAGNOSTIC]`
94
+
95
+ Returns safe SVG text for one diagnostic without displaying it.
96
+
97
+ | Property | Value |
98
+ |---|---|
99
+ | Type | Reporter |
100
+ | Opcode | `diagnosticSvg` |
101
+ | Monitor | Disabled |
102
+ | `DIAGNOSTIC` | String, default: `{"severity":"warning","code":"APP002","message":"Please check the input."}` |
103
+
104
+ ### `last diagnostic JSON`
105
+
106
+ Returns the last displayed normalized diagnostic as JSON, or an empty string.
107
+
108
+ | Property | Value |
109
+ |---|---|
110
+ | Type | Reporter |
111
+ | Opcode | `lastDiagnosticJson` |
112
+ | Monitor | Disabled |
113
+
114
+ <!-- END GENERATED BLOCKS -->
115
+
116
+ ## Composition API
117
+
118
+ パッケージのルートまたは`/composition`は、TurboWarpへの自動登録を行わない副作用のないES moduleです。
119
+
120
+ ```ts
121
+ import {
122
+ createDiagnosticOverlayComposition,
123
+ renderDiagnosticSvg
124
+ } from '@kubohiroya/turbowarp-diagnostic-overlay/composition';
125
+
126
+ const {extension, controller} = createDiagnosticOverlayComposition(Scratch);
127
+
128
+ // 集約側が一度だけ登録する。
129
+ Scratch.extensions.register(extension);
130
+
131
+ controller.show({
132
+ severity: 'error',
133
+ code: 'APP001',
134
+ message: '入力を確認してください。'
135
+ });
136
+
137
+ const svg = renderDiagnosticSvg({
138
+ severity: 'warning',
139
+ code: 'APP002',
140
+ message: 'この値は非推奨です。'
141
+ });
142
+ ```
143
+
144
+ 純粋なrendererだけを利用する場合は`@kubohiroya/turbowarp-diagnostic-overlay/svg-renderer`からimportできます。
145
+
146
+ 詳しい契約は[`docs/specification.md`](docs/specification.md)を参照してください。
147
+
148
+ ## 開発
149
+
150
+ Node.js 22.12以降とCorepackを使用します。
151
+
152
+ ```bash
153
+ corepack enable
154
+ pnpm install --frozen-lockfile
155
+ pnpm run check
156
+ pnpm run release:check
157
+ ```
158
+
159
+ `dist/diagnostic-overlay.js`はレビュー可能な単一ファイルとしてGitに含めます。ブロック定義を変更した場合は`pnpm run docs`でREADMEを更新します。
160
+
161
+ ## ライセンス
162
+
163
+ MPL-2.0