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.
Files changed (4) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/README.md +25 -11
  3. package/index.js +38 -8
  4. 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.0 is the topology protocol MVP.** Stage validates and records
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.0 reports `dpi` as metadata but does not rescale coordinates, so
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`. A zone needs positive `w`/`h` and must fit:
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. It
138
- marks that apply's history entry `undone: true`, appends an `undo` entry and
139
- returns a receipt:
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`. Error codes for
168
- apply are `no_topology`, `unknown_layout`, `unknown_display` and
169
- `invalid_layout` (bad name); history uses `invalid_limit`.
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.0 performs no native writes, undo is a ledger reversal only.
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.0 does **not** enumerate the real desktop, move or resize windows, request
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) this._history.splice(0, 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, undone: false,
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
- /** Mark the latest not-yet-undone apply as undone and return its receipt. */
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().find(item => item.type === 'apply' && item.undone !== true)
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
- entry.undone = true
242
- entry.undoneAt = now()
243
- this._record({ type: 'undo', applyId: entry.id, name: entry.name, displayId: entry.displayId })
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.0",
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 || >=0.2.2-0 <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
  }