@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.
- package/CHANGELOG.md +15 -0
- package/LICENSE +4 -0
- package/README.md +163 -0
- package/dist/diagnostic-overlay.js +574 -0
- package/dist/lib/block-definitions.json +58 -0
- package/dist/lib/composition.d.ts +22 -0
- package/dist/lib/composition.d.ts.map +1 -0
- package/dist/lib/composition.js +20 -0
- package/dist/lib/composition.js.map +1 -0
- package/dist/lib/config.d.ts +10 -0
- package/dist/lib/config.d.ts.map +1 -0
- package/dist/lib/config.js +10 -0
- package/dist/lib/config.js.map +1 -0
- package/dist/lib/diagnostic.d.ts +30 -0
- package/dist/lib/diagnostic.d.ts.map +1 -0
- package/dist/lib/diagnostic.js +120 -0
- package/dist/lib/diagnostic.js.map +1 -0
- package/dist/lib/extension.d.ts +24 -0
- package/dist/lib/extension.d.ts.map +1 -0
- package/dist/lib/extension.js +94 -0
- package/dist/lib/extension.js.map +1 -0
- package/dist/lib/index.d.ts +2 -0
- package/dist/lib/index.d.ts.map +1 -0
- package/dist/lib/index.js +8 -0
- package/dist/lib/index.js.map +1 -0
- package/dist/lib/overlay.d.ts +39 -0
- package/dist/lib/overlay.d.ts.map +1 -0
- package/dist/lib/overlay.js +140 -0
- package/dist/lib/overlay.js.map +1 -0
- package/dist/lib/scratch.d.ts +32 -0
- package/dist/lib/scratch.d.ts.map +1 -0
- package/dist/lib/scratch.js +2 -0
- package/dist/lib/scratch.js.map +1 -0
- package/dist/lib/svg-renderer.d.ts +12 -0
- package/dist/lib/svg-renderer.d.ts.map +1 -0
- package/dist/lib/svg-renderer.js +180 -0
- package/dist/lib/svg-renderer.js.map +1 -0
- package/docs/specification.md +67 -0
- 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
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
|