@marver-design/marver 0.25.1 → 0.26.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 (91) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/README.md +3 -1
  3. package/dist/{anchor-DVV732zR.mjs → anchor-5H1vnoLu.mjs} +6 -1
  4. package/dist/{anchor-check-DGZnYviN.mjs → anchor-check-Dg5xpNnU.mjs} +1 -1
  5. package/dist/audio-CmSRYFEs.mjs +429 -0
  6. package/dist/{auth-DdUKeVKt.mjs → auth-Dix8wrXV.mjs} +1 -1
  7. package/dist/{bake-BpxMZfij.mjs → bake-DtVlm0_F.mjs} +1 -1
  8. package/dist/{boards-Csxj2WJn.mjs → boards-DYG22tOe.mjs} +2 -2
  9. package/dist/{build-DKaGhoVN.mjs → build-C_gUgcdC.mjs} +16 -9
  10. package/dist/capture-CrqvU_jh.mjs +729 -0
  11. package/dist/cli.mjs +23 -17
  12. package/dist/{collab-gqNdScUE.mjs → collab-Dxg2trOK.mjs} +4 -3
  13. package/dist/{comments-Zoch254k.mjs → comments-0BSbb04K.mjs} +14 -3
  14. package/dist/{comments-pTLlhjh4.mjs → comments-BqXua-XL.mjs} +7 -7
  15. package/dist/{config-cKgZBRj0.mjs → config-Cf7EjAMf.mjs} +12 -1
  16. package/dist/{context-D2ugHqwO.mjs → context-HQ4Giw58.mjs} +1 -1
  17. package/dist/daemon-DZo6o3rU.mjs +2445 -0
  18. package/dist/{dev-Diqx1Rt8.mjs → dev-_Nlsc6v9.mjs} +189 -18
  19. package/dist/dev-lock-DWSpa6nj.mjs +179 -0
  20. package/dist/{events-DnK_AnrW.mjs → events-CLH4ijKP.mjs} +14 -4
  21. package/dist/{init-DO4DhUt_.mjs → init-D8DtrK_F.mjs} +2 -2
  22. package/dist/{ledger-BNXW14Xw.mjs → ledger-D54iROST.mjs} +17 -1
  23. package/dist/{link-C-qUIuKU.mjs → link-BNzLvdhI.mjs} +2 -2
  24. package/dist/live-Cgzsicwi.mjs +4 -0
  25. package/dist/{manifest-DnAte_fB.mjs → manifest-Nl3KSVOk.mjs} +1 -1
  26. package/dist/{marks-koRsbHfe.mjs → marks-CKgzucHZ.mjs} +2 -2
  27. package/dist/{marks-DFuintmJ.mjs → marks-NQi0wZJ4.mjs} +23 -5
  28. package/dist/{marver-id-gate-DGANtVyC.mjs → marver-id-gate-BjF6v4bT.mjs} +4 -4
  29. package/dist/{perf-QJIWtTw1.mjs → perf-D6VmmJ2q.mjs} +1 -1
  30. package/dist/{perf-CCisg-ny.mjs → perf-DPbLGhhO.mjs} +1 -1
  31. package/dist/{plugin-dTF5reck.mjs → plugin-CTD0rydA.mjs} +277 -37
  32. package/dist/{poster-D-zjYpgk.mjs → poster-ChjXGTS5.mjs} +1 -1
  33. package/dist/{profile-Do0nGkXO.mjs → profile-WU9qcbIo.mjs} +1 -1
  34. package/dist/{publish-bakes-C_9VZ-Mq.mjs → publish-bakes-CEP_2NRc.mjs} +3 -3
  35. package/dist/queue-BuiCKSX1.mjs +1319 -0
  36. package/dist/reserve-BURNQ2Y3.mjs +53 -0
  37. package/dist/{rolldown-runtime-D7D4PA-g.mjs → rolldown-runtime-8H4AJuhK.mjs} +1 -0
  38. package/dist/{serve-wv2QWdxB.mjs → serve-C8rVheYk.mjs} +12 -12
  39. package/dist/session-qZWKt_VA.mjs +191 -0
  40. package/dist/{share-ScamJcks.mjs → share--oFJ1bCI.mjs} +2 -2
  41. package/dist/{shot-jdO_B6Qw.mjs → shot-CNbHoZ6H.mjs} +1 -1
  42. package/dist/{shot-CUlmkqFX.mjs → shot-DqcxJibP.mjs} +4 -3
  43. package/dist/speech-models-DomiLQcY.mjs +299 -0
  44. package/dist/speech-worker.mjs +319 -0
  45. package/dist/{summary-CrW88e3q.mjs → summary-Y8MY1Wuc.mjs} +2 -2
  46. package/dist/{sync-C3035OnJ.mjs → sync-DKk-yT1V.mjs} +9 -8
  47. package/dist/{work-GE88wb_3.mjs → work-F5u-twpJ.mjs} +28 -5
  48. package/dist/{work-CpJn1gwY.mjs → work-VvX_JIgl.mjs} +2 -2
  49. package/docs/jam-session.md +177 -0
  50. package/docs/live-jam.md +21 -3
  51. package/package.json +7 -1
  52. package/src/client/frame-host/bridge.js +20 -2
  53. package/src/client/frame-host/inspect.d.ts +4 -0
  54. package/src/client/frame-host/inspect.js +88 -3
  55. package/src/client/frame-host/keys.d.ts +6 -0
  56. package/src/client/frame-host/keys.js +55 -0
  57. package/src/client/frame-host/trail.d.ts +7 -0
  58. package/src/client/frame-host/trail.js +204 -0
  59. package/src/client/shell/App.tsx +45 -5
  60. package/src/client/shell/Comments.tsx +20 -6
  61. package/src/client/shell/JamSurface.tsx +340 -0
  62. package/src/client/shell/Play.tsx +22 -3
  63. package/src/client/shell/Tip.tsx +8 -3
  64. package/src/client/shell/canvas/Canvas.tsx +12 -2
  65. package/src/client/shell/canvas/FrameNode.tsx +11 -2
  66. package/src/client/shell/comments-store.ts +23 -16
  67. package/src/client/shell/icons.tsx +15 -0
  68. package/src/client/shell/jam-capture.ts +939 -0
  69. package/src/client/shell/jam-keys.ts +329 -0
  70. package/src/client/shell/jam-lane.tsx +208 -0
  71. package/src/client/shell/jam-lines.ts +115 -0
  72. package/src/client/shell/jam-panel.tsx +506 -0
  73. package/src/client/shell/jam-queue.ts +126 -0
  74. package/src/client/shell/jam-session.tsx +389 -0
  75. package/src/client/shell/jam-state.ts +61 -0
  76. package/src/client/shell/jam-surface-parts.tsx +102 -0
  77. package/src/client/shell/jam-ui.tsx +104 -0
  78. package/src/client/shell/jam-voice.ts +479 -0
  79. package/src/client/shell/sound.ts +22 -0
  80. package/src/client/shell/stage-size.ts +11 -0
  81. package/src/client/shell/store.ts +34 -13
  82. package/src/client/shell/styles.css +544 -2
  83. package/src/client/stage/main.tsx +16 -2
  84. package/src/shared/capture-frames.ts +41 -0
  85. package/src/shared/events.ts +19 -4
  86. package/src/shared/speech.ts +16 -0
  87. package/templates/AGENTS-embedded.md +10 -2
  88. package/templates/AGENTS-studio.md +10 -2
  89. package/templates/instructions/iterate.md +8 -6
  90. package/templates/instructions/jam.md +129 -59
  91. package/dist/daemon-Cl8KXGW4.mjs +0 -1523
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marver-design/marver",
3
- "version": "0.25.1",
3
+ "version": "0.26.0",
4
4
  "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -50,11 +50,13 @@
50
50
  "cac": "^7.0.0",
51
51
  "echarts": "^6.1.0",
52
52
  "html-to-image": "^1.11.13",
53
+ "magic-string": "^0.30.21",
53
54
  "marked": "^16.0.0",
54
55
  "mermaid": "^11.6.0",
55
56
  "react-zoom-pan-pinch": "^3.6.1",
56
57
  "roughjs": "^4.6.6",
57
58
  "vite": "^8.0.0",
59
+ "ws": "^8.22.0",
58
60
  "zustand": "^5.0.0"
59
61
  },
60
62
  "peerDependencies": {
@@ -65,6 +67,7 @@
65
67
  "@types/node": "^22.0.0",
66
68
  "@types/react": "^19.0.0",
67
69
  "@types/react-dom": "^19.0.0",
70
+ "@types/ws": "^8.18.2",
68
71
  "tsdown": "^0.22.0",
69
72
  "typescript": "^5.7.0",
70
73
  "vitest": "^3.0.0"
@@ -80,5 +83,8 @@
80
83
  },
81
84
  "publishConfig": {
82
85
  "access": "public"
86
+ },
87
+ "optionalDependencies": {
88
+ "sherpa-onnx-node": "1.13.8"
83
89
  }
84
90
  }
@@ -3,8 +3,11 @@
3
3
  //
4
4
  // The laser / comment-pick / anchor / highlight machinery lives in ./inspect.js and is
5
5
  // shared with the prototype stage; this bridge owns the canvas-frame concerns around it:
6
- // theme, wheel ownership, the interaction lease, data-goto, and error reporting.
6
+ // theme, wheel ownership, the interaction lease, data-goto, and error reporting - and, for Jam
7
+ // captures, the keys the shell owns (keys.js) and the recorder (trail.js).
7
8
  import { createInspect } from './inspect.js'
9
+ import { createKeys } from './keys.js'
10
+ import { createRecorder } from './trail.js'
8
11
 
9
12
  const isHtmlFrame = new URL(import.meta.url).searchParams.get('html') === '1'
10
13
  // same-origin parent (the shell): a fixed target origin keeps posts (incl. picked anchor
@@ -34,9 +37,19 @@ let pointerInside = false
34
37
  let interactiveOn = false // B0.2: set by sh:interactive - the play/interact target owns its own wheel
35
38
  const reportInteraction = () => post({ type: 'sh:interaction', id, laser: pointerInside && inspect.isLaser(), comment: pointerInside && inspect.isPick() })
36
39
 
40
+ // commands come from the SHELL (parent) only - embedded app content must not drive them, and a
41
+ // navigated frame must not spoof them
42
+ const trusted = (e) => e.source === window.parent && window.parent !== window && (!e.origin || e.origin === location.origin)
43
+
44
+ // the capture recorder (trail.js): passive, and silent while no capture is open
45
+ const recorder = createRecorder({ post, getFrame: () => id, mode: 'interact', trusted })
46
+ // the keys the shell owns right now are consumed here and forwarded (keys.js) - ahead of the app
47
+ const keys = createKeys({ post, trusted })
48
+
37
49
  // laser / pick / anchor / highlight - one shared controller (see inspect.js). The id is
38
50
  // static here (one iframe per frame); onModeChange re-reports the lease when a mode flips.
39
- const inspect = createInspect({ post, getId: () => id, onModeChange: () => reportInteraction() })
51
+ // Inside a capture a laser click is the capture's pick, not a path copy.
52
+ const inspect = createInspect({ post, getId: () => id, onModeChange: () => reportInteraction(), onLaserPick: (el, e) => recorder.pick(el, e) })
40
53
 
41
54
  document.addEventListener('mouseover', () => { if (!pointerInside) { pointerInside = true; reportInteraction() } })
42
55
  document.addEventListener('mouseout', (e) => { if (!e.relatedTarget) { pointerInside = false; reportInteraction() } })
@@ -53,6 +66,8 @@ document.addEventListener('click', (e) => {
53
66
  if (target) post({ type: 'sh:go', target })
54
67
  }, true)
55
68
 
69
+ // Escape leaves interact mode - unless the shell owns it right now (a capture, a review): keys.js
70
+ // consumed and forwarded it already, so this never sees it
56
71
  document.addEventListener('keydown', (e) => { if (e.key === 'Escape') post({ type: 'sh:exit-interact' }) })
57
72
 
58
73
  window.addEventListener('error', (e) => post({ type: 'sh:error', id, message: String(e.message || e.error) }))
@@ -69,6 +84,9 @@ window.addEventListener('message', (e) => {
69
84
  // mirrored on the document so content primitives can observe it (Video disarms its
70
85
  // player when the human leaves interact mode - a playing clip must not outlive the mode)
71
86
  document.documentElement.toggleAttribute('data-sh-interactive', interactiveOn)
87
+ // leaving interact leaves the field you were typing in: the next key is a shortcut again, not a
88
+ // letter typed into a frame you are no longer using
89
+ if (!interactiveOn) { const a = document.activeElement; if (a && a !== document.body && typeof a.blur === 'function') a.blur() }
72
90
  }
73
91
  })
74
92
 
@@ -3,4 +3,8 @@ export function createInspect(opts: {
3
3
  post: (msg: Record<string, unknown>) => void
4
4
  getId: () => string
5
5
  onModeChange?: (laser: boolean, pick: boolean) => void
6
+ onLaserPick?: (el: Element, e: MouseEvent) => boolean
6
7
  }): { modeActive: () => boolean; isLaser: () => boolean; isPick: () => boolean; dispose: () => void }
8
+ export function safeBundle(el: Element, point?: { x: number; y: number }): Record<string, unknown>
9
+ export function fieldValue(f: Element): string
10
+ export function sensitiveField(f: Element): boolean
@@ -10,12 +10,14 @@
10
10
  // touches laser/pick/anchor/highlight. It self-installs the pointer + message
11
11
  // listeners and returns { modeActive } so the host can guard its own nav clicks.
12
12
  //
13
- // createInspect({ post, getId, onModeChange? })
13
+ // createInspect({ post, getId, onModeChange?, onLaserPick? })
14
14
  // post(msg) send a message up to the shell (parent)
15
15
  // getId() the frame id to stamp on posts (static on canvas, the
16
16
  // current stage frame in play - it swaps without reload)
17
17
  // onModeChange?() called after any laser/pick flip (the canvas bridge uses it
18
18
  // to report its interaction lease; the stage ignores it)
19
+ // onLaserPick?(el, e) a laser click; returning true means a capture took it as its pick
20
+ // (trail.js) - no sh:laser-copy then
19
21
  //
20
22
  // shell -> frame : sh:laser · sh:pick · sh:copy-ok · sh:resolve-anchors · sh:highlight-anchor
21
23
  // frame -> shell : sh:frame-down · sh:picked · sh:laser-copy · sh:anchor-rects
@@ -113,6 +115,84 @@ const elBundle = (el) => {
113
115
  }
114
116
  }
115
117
 
118
+ // ---- safeBundle: what a capture may carry out of a frame (spec 27, "Nothing secret leaves the frame")
119
+
120
+ const FIELD = 'input, textarea, select'
121
+ const EDITABLE = '[contenteditable]:not([contenteditable="false"])'
122
+ // matched on the words normalised: separators of every kind (spaces, underscores, dots, any Unicode dash)
123
+ // become one hyphen, so "One time code", "one_time", "One‑time code" (U+2011) and "onetime" all read alike
124
+ const SECRET = /pass|secret|token|card|cc-|cvv|cvc|one-?time|otp|security-?code|pin-?code/i
125
+ const secretWords = (s) => SECRET.test(String(s).toLowerCase().replace(/[\s_.\u2010-\u2015\u2212\uFE58\uFE63\uFF0D-]+/g, '-'))
126
+ const MASK = '•••'
127
+
128
+ /** The words a field is known by: its type, name, id, autocomplete, aria-label, labels. */
129
+ const fieldWords = (f) => {
130
+ const out = [f.getAttribute('type'), f.getAttribute('name'), f.id, f.getAttribute('autocomplete'), f.getAttribute('aria-label'), f.getAttribute('placeholder')]
131
+ for (const l of f.labels ?? []) out.push(l.textContent)
132
+ for (const ref of (f.getAttribute('aria-labelledby') ?? '').split(/\s+/)) if (ref) out.push(document.getElementById(ref)?.textContent)
133
+ return out.filter(Boolean).join(' ')
134
+ }
135
+ /** A field that holds a secret: a password, or one whose words say secret, token, card, cvv, one-time code. */
136
+ export const sensitiveField = (f) => f instanceof Element && f.matches(FIELD) && (f.getAttribute('type') === 'password' || secretWords(fieldWords(f)))
137
+
138
+ /** A sensitive context: the element is, contains, or sits inside a field or an editable region, or
139
+ * relates to a secret field (a label for it, an element naming it). Such a bundle keeps only its
140
+ * tag, its source and a css path without attribute values. */
141
+ const sensitive = (el) => {
142
+ if (el.isContentEditable || el.closest(`${FIELD}, ${EDITABLE}`) || el.querySelector(`${FIELD}, ${EDITABLE}`)) return true
143
+ const label = el.closest('label')
144
+ const control = label?.control ?? (el.id ? document.querySelector(`label[for="${CSS.escape(el.id)}"]`)?.control : null)
145
+ if (control && sensitiveField(control)) return true
146
+ for (const ref of [el.getAttribute('aria-controls'), el.getAttribute('aria-describedby')]) {
147
+ const f = ref && document.getElementById(ref)
148
+ if (f && sensitiveField(f)) return true
149
+ }
150
+ return false
151
+ }
152
+ /** The text a person reads in it - every field and editable subtree skipped, whatever it is called. */
153
+ const safeText = (el) => {
154
+ let t = ''
155
+ for (const n of el.childNodes) {
156
+ if (n.nodeType === 3) t += n.data
157
+ else if (n.nodeType === 1 && !n.matches(`${FIELD}, ${EDITABLE}, script, style, noscript, template`)) t += ' ' + safeText(n)
158
+ }
159
+ return t
160
+ }
161
+ /** A css path built from tags and positions only - no id, no attribute value. */
162
+ const plainPath = (el) => {
163
+ const seg = []
164
+ for (let cur = el; cur && cur !== document.body && cur.nodeType === 1; cur = cur.parentElement) {
165
+ const tag = cur.tagName.toLowerCase()
166
+ let n = 1
167
+ for (let sib = cur.previousElementSibling; sib; sib = sib.previousElementSibling) if (sib.tagName === cur.tagName) n++
168
+ seg.unshift(n > 1 ? `${tag}:nth-of-type(${n})` : tag)
169
+ }
170
+ return seg.join(' > ')
171
+ }
172
+
173
+ /** The element as a capture records it - a pick, a click, a hover, a probe answer, a field. Built
174
+ * on elBundle's shape; a sensitive context is masked. `point` (viewport px) adds where it was hit. */
175
+ export function safeBundle(el, point) {
176
+ const r = el.getBoundingClientRect()
177
+ const where = point ? { pos: { fx: r.width ? Math.min(1, Math.max(0, (point.x - r.left) / r.width)) : .5, fy: r.height ? Math.min(1, Math.max(0, (point.y - r.top) / r.height)) : .5 } } : {}
178
+ const rect = { rect: { x: r.left, y: r.top, w: r.width, h: r.height } }
179
+ if (sensitive(el)) {
180
+ return { el: { semantics: { tag: el.tagName.toLowerCase(), role: MASK, ariaLabel: MASK, testId: MASK, quote: MASK }, cssPath: plainPath(el), source: el.dataset?.mvLoc ?? undefined, sensitive: true }, ...where, ...rect }
181
+ }
182
+ const b = elBundle(el)
183
+ b.el.semantics.quote = norm(safeText(el)).slice(0, 200) || undefined
184
+ return { ...b, ...where, ...rect }
185
+ }
186
+
187
+ /** What a field change records: the value only for a text, search, number or select field that is
188
+ * not a secret one; anything else "changed (12 characters)". */
189
+ export function fieldValue(f) {
190
+ const v = typeof f.value === 'string' ? f.value : ''
191
+ const type = (f.getAttribute('type') ?? 'text').toLowerCase()
192
+ const plain = f.matches('select') || (f.matches('input') && ['text', 'search', 'number'].includes(type))
193
+ return plain && !sensitiveField(f) ? v : `changed (${v.length} characters)`
194
+ }
195
+
116
196
  const SKIP = 'script,style,noscript,template'
117
197
  /** The visible elements showing these words (case and spacing aside): the innermost element
118
198
  * whose SEEN text holds them - only text whose own element is shown, with a line break or a block
@@ -243,7 +323,7 @@ const checkTarget = ({ on, at, nth } = {}, others = []) => {
243
323
  }
244
324
  if (typeof window !== 'undefined') window.__mvAnchorCheck = checkTarget
245
325
 
246
- export function createInspect({ post, getId, onModeChange }) {
326
+ export function createInspect({ post, getId, onModeChange, onLaserPick }) {
247
327
  let laserOn = false, pickOn = false
248
328
  // quiet pick (⇧L laser comment off): clicks still anchor comments, but NO hover outline,
249
329
  // label, or lock lighting inside the artwork - the shell decides, the frame obeys
@@ -299,6 +379,9 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
299
379
  }
300
380
 
301
381
  const applyModes = () => {
382
+ // one mode flag for the whole frame: the capture recorder records no click while it is set,
383
+ // so a pick is recorded once (trail.js)
384
+ window.__mvPick = modeActive()
302
385
  const cur = document.getElementById(LASER_ID)
303
386
  if (!modeActive()) { if (cur) cur.remove(); clearHover(); return }
304
387
  const s = cur ?? document.createElement('style')
@@ -422,7 +505,8 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
422
505
  if (!pickQuiet) applyLock(el, hueOf(el))
423
506
  clearHover()
424
507
  post({ type: 'sh:picked', id: getId(), anchor: anchorBundle(el, e) })
425
- } else {
508
+ } else if (!onLaserPick?.(el, e)) {
509
+ // outside a capture a laser click copies the element's path; inside one it is the capture's pick
426
510
  copyEl = el
427
511
  post({ type: 'sh:laser-copy', id: getId(), seq: ++copySeq, path: cssPath(el), source: el.dataset.mvLoc ?? null })
428
512
  }
@@ -488,6 +572,7 @@ body [data-mv-hover] { outline: 2px solid hsl(var(--mv-hue) 95% 45%); outline-of
488
572
  clearHover(); clearLock()
489
573
  document.getElementById(LASER_ID)?.remove()
490
574
  document.getElementById(BASE_ID)?.remove()
575
+ window.__mvPick = false
491
576
  },
492
577
  }
493
578
  }
@@ -0,0 +1,6 @@
1
+ // Types for keys.js (plain JS: it serves into frames like bridge.js).
2
+ export function inField(t: EventTarget | null): boolean
3
+ export function composing(e: KeyboardEvent): boolean
4
+ export function keyAllowed(e: KeyboardEvent): boolean
5
+ export function keyDescriptor(e: KeyboardEvent): string
6
+ export function createKeys(opts: { post: (msg: Record<string, unknown>) => void; trusted: (e: MessageEvent) => boolean }): { owns: (e: KeyboardEvent) => boolean; dispose: () => void }
@@ -0,0 +1,55 @@
1
+ // The one key guard (spec 27, "The keys, everywhere") - shared by canvas frames (bridge.js), the
2
+ // play stage (stage/main.tsx) and the shell's own play handler (Play.tsx).
3
+ //
4
+ // A key typed into a field is the field's: never from an input, textarea, select, contenteditable
5
+ // element, or an IME composition. The shell mirrors which keys it owns right now into every frame
6
+ // (`sh:keys { owned }`); a frame consumes an owned key itself - preventDefault() before the browser
7
+ // presses a focused button on Enter, and no handler of the frame sees it - and forwards it up as
8
+ // `sh:key { key, shift, alt, meta, ctrl, code }`. A key not owned behaves as it always did.
9
+ //
10
+ // Key descriptors: `[Ctrl+][Meta+][Alt+][Shift+]key`, a single character lowercased ('e', 's'),
11
+ // any other key by its DOM name ('Enter', 'Escape', 'ArrowLeft', 'Backspace'):
12
+ // 'Shift+Enter', 'Meta+Enter', 'Alt+ArrowLeft'. 'Shift+s' is not 's'.
13
+
14
+ const FIELD = 'input, textarea, select, [contenteditable]:not([contenteditable="false"])'
15
+
16
+ /** Is this event's target a field, or inside one (a contenteditable region counts)? */
17
+ export const inField = (t) => t instanceof Element && (t.isContentEditable || !!t.closest(FIELD))
18
+
19
+ /** Mid-composition (an IME is building a character): every key is the composition's. */
20
+ export const composing = (e) => !!e.isComposing || e.keyCode === 229
21
+
22
+ /** May a shortcut take this key at all? Not from a field, not mid-composition. */
23
+ export const keyAllowed = (e) => !composing(e) && !inField(e.target)
24
+
25
+ /** The descriptor `sh:keys` speaks. */
26
+ export function keyDescriptor(e) {
27
+ const k = e.key && e.key.length === 1 ? e.key.toLowerCase() : e.key
28
+ return [e.ctrlKey && 'Ctrl', e.metaKey && 'Meta', e.altKey && 'Alt', e.shiftKey && 'Shift', k].filter(Boolean).join('+')
29
+ }
30
+
31
+ /** Listen for `sh:keys` from the shell and consume + forward the keys it owns. Installs a
32
+ * capture-phase keydown on the window - ahead of every handler the frame has - and returns
33
+ * { owns(e), dispose() }. `trusted(e)` checks a message really is the shell's. */
34
+ export function createKeys({ post, trusted }) {
35
+ let owned = new Set()
36
+ const onMessage = (e) => {
37
+ if (!trusted(e)) return
38
+ const m = e.data
39
+ if (m && m.type === 'sh:keys' && Array.isArray(m.owned)) owned = new Set(m.owned.filter((k) => typeof k === 'string'))
40
+ }
41
+ const owns = (e) => owned.size > 0 && keyAllowed(e) && owned.has(keyDescriptor(e))
42
+ const onKey = (e) => {
43
+ if (!owns(e)) return
44
+ e.preventDefault()
45
+ e.stopImmediatePropagation()
46
+ const key = e.key.length === 1 ? e.key.toLowerCase() : e.key
47
+ post({ type: 'sh:key', key, code: e.code, shift: e.shiftKey, alt: e.altKey, meta: e.metaKey, ctrl: e.ctrlKey })
48
+ }
49
+ window.addEventListener('message', onMessage)
50
+ window.addEventListener('keydown', onKey, true)
51
+ return {
52
+ owns,
53
+ dispose() { window.removeEventListener('message', onMessage); window.removeEventListener('keydown', onKey, true) },
54
+ }
55
+ }
@@ -0,0 +1,7 @@
1
+ // Types for trail.js (plain JS: it serves into frames like bridge.js).
2
+ export function createRecorder(opts: {
3
+ post: (msg: Record<string, unknown>) => void
4
+ getFrame: () => string
5
+ mode: 'interact' | 'play'
6
+ trusted: (e: MessageEvent) => boolean
7
+ }): { pick: (el: Element, e: MouseEvent) => boolean; screen: (to: string) => void; dispose: () => void }
@@ -0,0 +1,204 @@
1
+ // The capture recorder (spec 27, "One recorder, one clock") - one small module shared by canvas
2
+ // frames (bridge.js) and the play stage (stage/main.tsx). It does nothing while no capture is open.
3
+ //
4
+ // shell -> frame : sh:capture { id, on } · sh:capture-hello { nonce } · sh:probe { id, req, x, y }
5
+ // sh:focus-at { x, y }
6
+ // frame -> shell : sh:capture-hello { nonce, captureDoc } · sh:probe { id, req, captureDoc, bundle, field }
7
+ // sh:trail { id, captureDoc, frame, seq, at, event, mode, ...payload }
8
+ // sh:capture-flushed { id, captureDoc, seq }
9
+ //
10
+ // `captureDoc` is a nonce drawn once per document load - the shell's load-bound handshake learns it,
11
+ // and drops anything from a document it did not bind. `at` is when the thing happened, on the one
12
+ // clock every document on this machine shares (timeOrigin + now); `seq` numbers this document's
13
+ // messages; `frame` is the frame it happened in, taken WHEN it happened (the stage swaps frames in one
14
+ // document, so a field changed on screen A and blurred on B is A's). Every element goes out through
15
+ // safeBundle, a field's value through fieldValue - interact and play are no exception. The clipboard
16
+ // is never read, keys outside fields are never recorded.
17
+ import { fieldValue, safeBundle } from './inspect.js'
18
+ import { inField } from './keys.js'
19
+
20
+ const FIELD_IDLE_MS = 600
21
+ const HOVER_MS = 800
22
+ const HOVER_EVERY_MS = 2000
23
+ const HOVER_SLOP = 4
24
+ const SCROLL_SETTLE_MS = 400
25
+
26
+ const now = () => performance.timeOrigin + performance.now()
27
+ /** The element whose contenteditable makes `el` editable - the outermost editable ancestor. */
28
+ const editingHost = (el) => {
29
+ if (!el.isContentEditable) return null
30
+ let h = el
31
+ while (h.parentElement && h.parentElement.isContentEditable) h = h.parentElement
32
+ return h
33
+ }
34
+ const nonce = () => (crypto.randomUUID ? crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`)
35
+
36
+ /**
37
+ * createRecorder({ post, getFrame, mode, trusted })
38
+ * post(msg) send to the shell
39
+ * getFrame() the frame showing now (static on canvas, the current screen in play)
40
+ * mode 'interact' (a canvas frame - the shell's overlay keeps canvas-mode clicks, so a
41
+ * click that reaches the frame is interact) or 'play' (the stage)
42
+ * trusted(e) is this message the shell's?
43
+ * returns { pick(el, e) -> boolean, screen(to), dispose() }
44
+ */
45
+ /** One per document load (spec 27): a recorder created again in the same document keeps it, so the
46
+ * shell's binding to this document holds. */
47
+ const captureDoc = nonce()
48
+
49
+ export function createRecorder({ post, getFrame, mode, trusted }) {
50
+ let captureId = null
51
+ let seq = 0
52
+ // fields changed and not sent yet: element -> { id, frame, at, timer }
53
+ const pending = new Map()
54
+ const removers = []
55
+ const on = (target, type, fn, opts) => { target.addEventListener(type, fn, opts); removers.push(() => target.removeEventListener(type, fn, opts)) }
56
+ // the page's listeners go on with the first capture the shell opens here - a published canvas never
57
+ // opens one, so nothing listens there; every handler does nothing without a capture anyway
58
+ const armers = []
59
+ const onArmed = (...args) => { armers.push(() => on(...args)) }
60
+ let armed = false
61
+ const arm = () => { if (armed) return; armed = true; for (const a of armers) a() }
62
+
63
+ const send = (id, event, payload, frame = getFrame(), at = now()) => {
64
+ if (!id) return
65
+ post({ type: 'sh:trail', id, captureDoc, frame, seq: ++seq, at, event, mode, ...payload })
66
+ }
67
+ const record = (event, payload, frame, at) => send(captureId, event, payload, frame, at)
68
+
69
+ // ---- fields: sent when focus leaves the field, or after 600 ms idle --------------------------
70
+ const sendField = (el) => {
71
+ const p = pending.get(el)
72
+ if (!p) return
73
+ clearTimeout(p.timer)
74
+ pending.delete(el)
75
+ send(p.id, 'field', { bundle: safeBundle(el), value: fieldValue(el) }, p.frame, p.at)
76
+ }
77
+ const flushFields = (id) => { for (const [el, p] of [...pending]) if (!id || p.id === id) sendField(el) }
78
+ const onField = (e) => {
79
+ const el = e.target
80
+ if (!captureId || !(el instanceof Element) || !el.matches('input, textarea, select')) return
81
+ const was = pending.get(el)
82
+ if (was && was.id !== captureId) sendField(el) // a change from the capture before stays there
83
+ const p = pending.get(el) ?? { id: captureId, frame: getFrame(), at: now(), timer: 0 }
84
+ p.at = now()
85
+ clearTimeout(p.timer)
86
+ p.timer = setTimeout(() => sendField(el), FIELD_IDLE_MS)
87
+ pending.set(el, p)
88
+ }
89
+ onArmed(document, 'input', onField, true)
90
+ onArmed(document, 'change', onField, true)
91
+ onArmed(document, 'focusout', (e) => { if (e.target instanceof Element) sendField(e.target) }, true)
92
+
93
+ // ---- clicks: passive - the click still happens; never while a pick mode is on -----------------
94
+ let lastClickAt = 0
95
+ onArmed(window, 'click', (e) => {
96
+ lastClickAt = Date.now()
97
+ cancelHover()
98
+ if (!captureId || window.__mvPick) return
99
+ const el = e.target instanceof Element ? e.target : null
100
+ if (!el) return
101
+ record('click', { bundle: safeBundle(el, { x: e.clientX, y: e.clientY }), point: { x: e.clientX, y: e.clientY } })
102
+ }, { capture: true, passive: true })
103
+
104
+ // ---- hovers: held still 0.8 s without a click, at most one per 2 s ----------------------------
105
+ let hoverTimer = 0
106
+ let hoverFrom = null
107
+ let lastHoverAt = 0
108
+ const cancelHover = () => { clearTimeout(hoverTimer); hoverTimer = 0; hoverFrom = null }
109
+ onArmed(document, 'mousemove', (e) => {
110
+ if (!captureId || window.__mvPick) { cancelHover(); return }
111
+ if (hoverFrom && Math.hypot(e.clientX - hoverFrom.x, e.clientY - hoverFrom.y) <= HOVER_SLOP) return
112
+ cancelHover()
113
+ hoverFrom = { x: e.clientX, y: e.clientY }
114
+ const frame = getFrame()
115
+ hoverTimer = setTimeout(() => {
116
+ const from = hoverFrom
117
+ hoverTimer = 0
118
+ if (!captureId || !from || Date.now() - lastHoverAt < HOVER_EVERY_MS || Date.now() - lastClickAt < HOVER_MS) return
119
+ const el = document.elementFromPoint(from.x, from.y)
120
+ if (!el || el === document.documentElement || el === document.body) return
121
+ lastHoverAt = Date.now()
122
+ record('hover', { bundle: safeBundle(el, from), point: from }, frame)
123
+ }, HOVER_MS)
124
+ }, true)
125
+ onArmed(document, 'mousedown', cancelHover, true)
126
+ onArmed(document, 'mouseleave', cancelHover)
127
+
128
+ // ---- the final scroll ---------------------------------------------------------------------
129
+ // the settle wait keeps the capture, frame, time and position it began with: `E` (or `S` -> `S`)
130
+ // inside the wait sends it with the capture's flush, before `sh:capture-flushed` - never lost
131
+ let scrollTimer = 0
132
+ let pendingScroll = null
133
+ const sendScroll = (id) => {
134
+ if (!pendingScroll || (id && pendingScroll.id !== id)) return
135
+ const p = pendingScroll
136
+ pendingScroll = null
137
+ clearTimeout(scrollTimer)
138
+ send(p.id, 'scroll', { y: p.y }, p.frame, p.at)
139
+ }
140
+ onArmed(window, 'scroll', () => {
141
+ if (!captureId) return
142
+ clearTimeout(scrollTimer)
143
+ pendingScroll = { id: captureId, frame: getFrame(), at: performance.timeOrigin + performance.now(), y: Math.round(window.scrollY) }
144
+ scrollTimer = setTimeout(() => sendScroll(), SCROLL_SETTLE_MS)
145
+ }, { capture: true, passive: true })
146
+
147
+ // ---- the shell ------------------------------------------------------------------------------
148
+ on(window, 'message', (e) => {
149
+ if (!trusted(e)) return
150
+ const m = e.data
151
+ if (!m || typeof m !== 'object') return
152
+ if (m.type === 'sh:capture-hello' && typeof m.nonce === 'string') post({ type: 'sh:capture-hello', nonce: m.nonce, captureDoc })
153
+ else if (m.type === 'sh:capture' && typeof m.id === 'string') {
154
+ if (m.on) {
155
+ arm()
156
+ if (captureId && captureId !== m.id) { flushFields(captureId); sendScroll(captureId) } // `S` -> `S`: the first keeps its own
157
+ captureId = m.id
158
+ } else {
159
+ // `E`: what this capture holds goes first, then the last seq - the shell seals after
160
+ flushFields(m.id)
161
+ sendScroll(m.id)
162
+ if (captureId === m.id) { captureId = null; cancelHover() }
163
+ post({ type: 'sh:capture-flushed', id: m.id, captureDoc, seq })
164
+ }
165
+ }
166
+ else if (m.type === 'sh:probe' && typeof m.req !== 'undefined' && Number.isFinite(m.x) && Number.isFinite(m.y)) {
167
+ // what is at this point, as a canvas-mode click would have hit it - nothing is clicked
168
+ const el = document.elementFromPoint(m.x, m.y)
169
+ const hit = el && el !== document.documentElement ? el : null
170
+ // a field there: the shell makes the frame interactive and puts the caret in it, so what you type
171
+ // next is the field's - never a capture key
172
+ post({ type: 'sh:probe', id: m.id, req: m.req, captureDoc, bundle: hit ? safeBundle(hit, { x: m.x, y: m.y }) : null, field: !!hit && inField(hit) })
173
+ }
174
+ else if (m.type === 'sh:focus-at' && Number.isFinite(m.x) && Number.isFinite(m.y)) {
175
+ const el = document.elementFromPoint(m.x, m.y)
176
+ // the field itself - for rich text, its editing host (a span inside it is not focusable)
177
+ const f = el && (el.closest('input, textarea, select') ?? editingHost(el))
178
+ if (f && typeof f.focus === 'function') {
179
+ f.focus({ preventScroll: true })
180
+ // the caret at the end of what is there, as a click at the end of the text would leave it
181
+ try {
182
+ if (typeof f.value === 'string' && typeof f.setSelectionRange === 'function') f.setSelectionRange(f.value.length, f.value.length)
183
+ else if (f.isContentEditable) { const r = document.createRange(); r.selectNodeContents(f); r.collapse(false); const sel = getSelection(); sel?.removeAllRanges(); sel?.addRange(r) }
184
+ } catch { /* a type without a selection (email, number) */ }
185
+ }
186
+ }
187
+ })
188
+
189
+ return {
190
+ /** A laser click: inside a capture it is the capture's pick (true); outside, inspect copies the path. */
191
+ pick(el, e) {
192
+ if (!captureId) return false
193
+ record('pick', { bundle: safeBundle(el, { x: e.clientX, y: e.clientY }), point: { x: e.clientX, y: e.clientY } })
194
+ return true
195
+ },
196
+ /** The stage moved to another screen. */
197
+ screen(to) { record('screen', { to }, to) },
198
+ dispose() {
199
+ removers.forEach((f) => f())
200
+ for (const p of pending.values()) clearTimeout(p.timer)
201
+ pending.clear(); cancelHover(); clearTimeout(scrollTimer)
202
+ },
203
+ }
204
+ }