dsh-stage 0.1.0 → 0.1.1
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 +17 -0
- package/README.md +25 -11
- package/index.js +38 -8
- package/package.json +23 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,22 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.1
|
|
4
|
+
|
|
5
|
+
- Make `undo()` topology-aware: every apply already records the `topologyHash`
|
|
6
|
+
it was computed against, and undo now compares it with the current topology.
|
|
7
|
+
If the topology changed, undo refuses with
|
|
8
|
+
`{ ok: false, code: 'stale_topology' }` (including `applyId`,
|
|
9
|
+
`recordedTopologyHash` and the current `topologyHash`) and records/marks
|
|
10
|
+
nothing; re-apply the layout and undo the new record instead.
|
|
11
|
+
- Make history append-only: undo state lives in a side table, so past history
|
|
12
|
+
entries are never mutated in place. `history()` still reports `undone` and
|
|
13
|
+
`undoneAt` for apply entries.
|
|
14
|
+
- Return `ok: true` on a successful undo and keep all returned history/receipt
|
|
15
|
+
values as defensive copies.
|
|
16
|
+
- Lock in zone validation with tests: `NaN`, `Infinity`, `-Infinity`,
|
|
17
|
+
negative values and values above `1` are rejected with `invalid_zone` (the
|
|
18
|
+
guard already used `Number.isFinite` plus a `0..1` range check).
|
|
19
|
+
|
|
3
20
|
## 0.1.0
|
|
4
21
|
|
|
5
22
|
- Add the topology protocol MVP: `ctx.stage` with `setTopology()` / `topology()`
|
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
> **Topology before action.** Read displays, windows and spaces, describe layouts
|
|
4
4
|
> as display-relative zones, and apply them as recorded, undoable intent.
|
|
5
5
|
|
|
6
|
-
**Status: 0.1.
|
|
6
|
+
**Status: 0.1.1 is the topology protocol MVP.** Stage validates and records
|
|
7
7
|
topology and layout intent only. It never calls a native window API and cannot
|
|
8
8
|
move a window yet. The **macOS AX adapter and Windows Win32 adapter are planned
|
|
9
9
|
for 0.2.0**. Until an adapter ships, a host integration supplies observations
|
|
@@ -68,7 +68,7 @@ stage.setTopology({
|
|
|
68
68
|
Before the first `setTopology()` the collections are empty and both
|
|
69
69
|
`topologyHash` and `observedAt` are `null`.
|
|
70
70
|
- Bounds and zone results stay in the adapter's native/global coordinate
|
|
71
|
-
units. 0.1.
|
|
71
|
+
units. 0.1.x reports `dpi` as metadata but does not rescale coordinates, so
|
|
72
72
|
mixed-DPI setups never get an implicit conversion.
|
|
73
73
|
|
|
74
74
|
Errors carry a stable `code`: `invalid_topology`, `invalid_display`,
|
|
@@ -80,7 +80,9 @@ Errors carry a stable `code`: `invalid_topology`, `invalid_display`,
|
|
|
80
80
|
|
|
81
81
|
`setLayout(name, { displayId, zones })` creates or replaces a named layout.
|
|
82
82
|
Each zone is `{ x, y, w, h }` normalized to `0..1` relative to the display's
|
|
83
|
-
`workArea`.
|
|
83
|
+
`workArea`. Every coordinate must be a finite number within `0..1` — `NaN`,
|
|
84
|
+
`±Infinity`, negatives and values above `1` are rejected with `invalid_zone`.
|
|
85
|
+
A zone needs positive `w`/`h` and must fit:
|
|
84
86
|
`x + w <= 1` and `y + h <= 1`. A layout holds 1 to 20 zones.
|
|
85
87
|
|
|
86
88
|
```js
|
|
@@ -134,12 +136,22 @@ decimal places. No OS call is made: the record is intent for a future adapter.
|
|
|
134
136
|
an ISO `at` and a `type` of `topology`, `layout`, `apply` or `undo`; `limit`
|
|
135
137
|
must be an integer from 1 to 200, and history keeps at most 200 entries.
|
|
136
138
|
|
|
137
|
-
`undo()` reverses the most recent apply that has not already been undone.
|
|
138
|
-
|
|
139
|
-
|
|
139
|
+
`undo()` reverses the most recent apply that has not already been undone. Every
|
|
140
|
+
apply records the `topologyHash` it was computed against; undo compares that
|
|
141
|
+
hash with the current topology before doing anything:
|
|
142
|
+
|
|
143
|
+
- **Same topology** — the apply's history entry is reported with `undone: true`
|
|
144
|
+
(history itself is append-only), an `undo` entry is appended, and the call
|
|
145
|
+
returns `ok: true` plus the receipt below.
|
|
146
|
+
- **Topology changed** — the recorded rectangles are stale, so undo does not
|
|
147
|
+
execute. It returns `{ ok: false, code: 'stale_topology', applyId,
|
|
148
|
+
recordedTopologyHash, topologyHash }`, records no `undo` entry and leaves the
|
|
149
|
+
apply un-undone. Re-apply the layout on the current topology and undo that
|
|
150
|
+
new record instead; raising a new layout definition is not required.
|
|
140
151
|
|
|
141
152
|
```json
|
|
142
153
|
{
|
|
154
|
+
"ok": true,
|
|
143
155
|
"schema": "dsh.stage.undo/v1",
|
|
144
156
|
"undone": {
|
|
145
157
|
"id": "h3",
|
|
@@ -164,11 +176,13 @@ returns a receipt:
|
|
|
164
176
|
}
|
|
165
177
|
```
|
|
166
178
|
|
|
167
|
-
With no undoable apply, `undo()` throws `nothing_to_undo`.
|
|
168
|
-
|
|
169
|
-
`
|
|
179
|
+
With no undoable apply, `undo()` throws `nothing_to_undo`. A stale apply stays
|
|
180
|
+
undoable in principle (it will succeed if the topology returns to the recorded
|
|
181
|
+
hash), but until then it returns `stale_topology` rather than a rectangle.
|
|
182
|
+
Error codes for apply are `no_topology`, `unknown_layout`, `unknown_display`
|
|
183
|
+
and `invalid_layout` (bad name); history uses `invalid_limit`.
|
|
170
184
|
|
|
171
|
-
Because 0.1.
|
|
185
|
+
Because 0.1.x performs no native writes, undo is a ledger reversal only.
|
|
172
186
|
Restoring window rectangles, verifying placement and handling user-moved
|
|
173
187
|
windows are adapter concerns for 0.2.0.
|
|
174
188
|
|
|
@@ -189,7 +203,7 @@ future adapters exercise the protocol.
|
|
|
189
203
|
|
|
190
204
|
## Scope
|
|
191
205
|
|
|
192
|
-
0.1.
|
|
206
|
+
0.1.x does **not** enumerate the real desktop, move or resize windows, request
|
|
193
207
|
accessibility or screen-recording permissions, read Spaces through private
|
|
194
208
|
APIs, persist layouts or emit events. Those belong to the macOS AX and Windows
|
|
195
209
|
Win32 adapters, verification and storage work scheduled for 0.2.0.
|
package/index.js
CHANGED
|
@@ -124,13 +124,18 @@ export class StageService {
|
|
|
124
124
|
this._topology = null
|
|
125
125
|
this._layouts = new Map()
|
|
126
126
|
this._history = []
|
|
127
|
+
this._undone = new Map()
|
|
127
128
|
this._sequence = 0
|
|
128
129
|
}
|
|
129
130
|
|
|
130
131
|
_record(entry) {
|
|
131
132
|
const record = { id: `h${++this._sequence}`, at: now(), ...entry }
|
|
132
133
|
this._history.push(record)
|
|
133
|
-
if (this._history.length > MAX_HISTORY)
|
|
134
|
+
if (this._history.length > MAX_HISTORY) {
|
|
135
|
+
for (const dropped of this._history.splice(0, this._history.length - MAX_HISTORY)) {
|
|
136
|
+
this._undone.delete(dropped.id)
|
|
137
|
+
}
|
|
138
|
+
}
|
|
134
139
|
return record
|
|
135
140
|
}
|
|
136
141
|
|
|
@@ -221,7 +226,7 @@ export class StageService {
|
|
|
221
226
|
}))
|
|
222
227
|
this._record({
|
|
223
228
|
type: 'apply', name: layout.name, displayId: display.id, layout: clone(layout),
|
|
224
|
-
assignments: clone(assignments), topologyHash: this._topology.topologyHash,
|
|
229
|
+
assignments: clone(assignments), topologyHash: this._topology.topologyHash,
|
|
225
230
|
})
|
|
226
231
|
return { layout: clone(layout), assignments: clone(assignments) }
|
|
227
232
|
}
|
|
@@ -231,17 +236,42 @@ export class StageService {
|
|
|
231
236
|
if (!Number.isInteger(limit) || limit < 1 || limit > MAX_HISTORY) {
|
|
232
237
|
throw fail('invalid_limit', `history limit must be an integer from 1 to ${MAX_HISTORY}`)
|
|
233
238
|
}
|
|
234
|
-
return clone(this._history.slice(-limit).reverse()
|
|
239
|
+
return clone(this._history.slice(-limit).reverse().map(entry => (
|
|
240
|
+
entry.type === 'apply' && this._undone.has(entry.id)
|
|
241
|
+
? { ...entry, undone: true, undoneAt: this._undone.get(entry.id) }
|
|
242
|
+
: entry.type === 'apply' ? { ...entry, undone: false } : entry
|
|
243
|
+
)))
|
|
235
244
|
}
|
|
236
245
|
|
|
237
|
-
/**
|
|
246
|
+
/**
|
|
247
|
+
* Mark the latest not-yet-undone apply as undone and return its receipt.
|
|
248
|
+
*
|
|
249
|
+
* The apply records the topology hash it was computed against. If the
|
|
250
|
+
* topology has changed since, the recorded rectangles are stale, so undo
|
|
251
|
+
* refuses with `{ ok: false, code: 'stale_topology' }` and changes nothing;
|
|
252
|
+
* re-apply the layout on the current topology and undo that record instead.
|
|
253
|
+
*/
|
|
238
254
|
undo() {
|
|
239
|
-
const entry = [...this._history].reverse()
|
|
255
|
+
const entry = [...this._history].reverse()
|
|
256
|
+
.find(item => item.type === 'apply' && !this._undone.has(item.id))
|
|
240
257
|
if (entry === undefined) throw fail('nothing_to_undo', 'no applied layout is available to undo')
|
|
241
|
-
|
|
242
|
-
entry.
|
|
243
|
-
|
|
258
|
+
const topologyHash = this._topology === null ? null : this._topology.topologyHash
|
|
259
|
+
if (entry.topologyHash !== topologyHash) {
|
|
260
|
+
return {
|
|
261
|
+
ok: false,
|
|
262
|
+
code: 'stale_topology',
|
|
263
|
+
message: 'the topology changed after this layout was applied; re-apply the layout and undo the new record',
|
|
264
|
+
applyId: entry.id,
|
|
265
|
+
recordedTopologyHash: entry.topologyHash,
|
|
266
|
+
topologyHash,
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
this._undone.set(entry.id, now())
|
|
270
|
+
this._record({
|
|
271
|
+
type: 'undo', applyId: entry.id, name: entry.name, displayId: entry.displayId, topologyHash,
|
|
272
|
+
})
|
|
244
273
|
return {
|
|
274
|
+
ok: true,
|
|
245
275
|
schema: SCHEMAS.undo,
|
|
246
276
|
undone: { id: entry.id, at: entry.at, layout: clone(entry.layout), assignments: clone(entry.assignments) },
|
|
247
277
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-stage",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Display, window and space topology protocol for DeepSeek Harness agents, with normalized, reversible layouts.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "index.js",
|
|
@@ -34,18 +34,38 @@
|
|
|
34
34
|
},
|
|
35
35
|
"engines": {
|
|
36
36
|
"node": "^22.19.0 || >=24.9.0",
|
|
37
|
-
"dsh": ">=0.2.1-rc.2 <0.3.0
|
|
37
|
+
"dsh": ">=0.2.1-rc.2 <0.3.0-0"
|
|
38
38
|
},
|
|
39
39
|
"dsh": {
|
|
40
40
|
"manifestVersion": 1,
|
|
41
41
|
"bundle": {
|
|
42
42
|
"patch": "./cordis.patch.yml"
|
|
43
|
+
},
|
|
44
|
+
"os": {
|
|
45
|
+
"service": "stage",
|
|
46
|
+
"provides": [
|
|
47
|
+
"stage"
|
|
48
|
+
],
|
|
49
|
+
"capabilities": [
|
|
50
|
+
"ui"
|
|
51
|
+
],
|
|
52
|
+
"tools": [
|
|
53
|
+
"stage_topology",
|
|
54
|
+
"stage_layout_set",
|
|
55
|
+
"stage_layout_apply",
|
|
56
|
+
"stage_layout_list",
|
|
57
|
+
"stage_undo"
|
|
58
|
+
],
|
|
59
|
+
"ui": null,
|
|
60
|
+
"stability": "experimental",
|
|
61
|
+
"since": "0.1.0"
|
|
43
62
|
}
|
|
44
63
|
},
|
|
45
64
|
"scripts": {
|
|
46
65
|
"test": "node --test"
|
|
47
66
|
},
|
|
48
67
|
"publishConfig": {
|
|
49
|
-
"access": "public"
|
|
68
|
+
"access": "public",
|
|
69
|
+
"registry": "https://registry.npmjs.org/"
|
|
50
70
|
}
|
|
51
71
|
}
|