@marver-design/marver 0.31.0 → 0.32.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 (36) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +2 -2
  3. package/dist/{anchor-check-B92s9tVv.mjs → anchor-check-DZtX13ly.mjs} +1 -1
  4. package/dist/{boards-OlAhZ87x.mjs → boards-jHmEPLV7.mjs} +1 -1
  5. package/dist/{build-BNssmbqd.mjs → build-D2dHEWX-.mjs} +3 -3
  6. package/dist/cli.mjs +12 -12
  7. package/dist/{comments-BakJQwaf.mjs → comments-ocvsnt2j.mjs} +2 -2
  8. package/dist/{daemon-MxoEQajX.mjs → daemon-D6TrdgMi.mjs} +49 -8
  9. package/dist/{dev-BBZe_brH.mjs → dev-DMQYbw-2.mjs} +9 -9
  10. package/dist/{link-Cmt9Xy4X.mjs → link-aZq5cExV.mjs} +1 -1
  11. package/dist/{pdf-CZENT6t3.mjs → pdf-Cf9GIoIM.mjs} +3 -3
  12. package/dist/{pdf-0m721FFn.mjs → pdf-HB0prF75.mjs} +1 -1
  13. package/dist/{perf-CIMijND6.mjs → perf-9ZEF5KLO.mjs} +2 -2
  14. package/dist/{perf-BB0XNt1M.mjs → perf-BA_NDarr.mjs} +1 -0
  15. package/dist/{plugin-CL8_wL7a.mjs → plugin-DesQP9L5.mjs} +127 -46
  16. package/dist/{poster-B7uSjlEP.mjs → poster-Bb6WraCA.mjs} +1 -1
  17. package/dist/{publish-bakes-BjgDNeyS.mjs → publish-bakes-EjMmukJB.mjs} +2 -2
  18. package/dist/{recover-ByuFQOF9.mjs → recover-B3dmatx4.mjs} +1 -1
  19. package/dist/{shot-BqwkdtKn.mjs → shot-Bjt2MQe3.mjs} +3 -3
  20. package/dist/{shot-D2TQGo2V.mjs → shot-BuUCG46-.mjs} +1 -1
  21. package/dist/{show-B1u3DiJw.mjs → show-DhmiUu01.mjs} +2 -2
  22. package/dist/{work-Nv-n2_Un.mjs → work-B4tydWnf.mjs} +37 -1
  23. package/dist/{work-DRdzXPvg.mjs → work-CzIXp7n1.mjs} +3 -3
  24. package/docs/app.md +109 -21
  25. package/docs/boards-and-folders.md +6 -3
  26. package/docs/slides.md +2 -1
  27. package/package.json +1 -1
  28. package/src/client/shell/Play.tsx +80 -5
  29. package/src/client/shell/app-bridge.ts +8 -0
  30. package/src/client/shell/immersive.ts +123 -0
  31. package/src/client/shell/inset.ts +29 -3
  32. package/src/client/shell/recorder-signals.ts +5 -2
  33. package/src/client/shell/styles.css +25 -6
  34. package/src/shared/app-api.ts +41 -0
  35. package/src/shared/immersive.ts +13 -0
  36. package/src/shared/perf-records.ts +1 -1
package/docs/app.md CHANGED
@@ -17,6 +17,8 @@ what changed, are in [TNEP4/marver-app](https://github.com/TNEP4/marver-app/rele
17
17
  - **Canvases on Marver 0.27 or later.** They show in the app, a tab each, and closing, reloading or quitting asks
18
18
  before losing their unsaved work. Marks, notices and live pictures need **0.29 or later**, the version to use with
19
19
  the app. A canvas on 0.26 or older does not appear: update it with `npm i -D @marver-design/marver@latest`.
20
+ - **Marver 0.32 or later, with app 1.2,** for Home to name the board an agent works on and for how long, and for Hide
21
+ UI to take the whole window in play ([Hide UI in play](#hide-ui-in-play)).
20
22
 
21
23
  ## Install
22
24
 
@@ -67,10 +69,11 @@ Your settings and tabs stay: every version keeps them in the same folders ([Unin
67
69
 
68
70
  ## First launch
69
71
 
70
- Marver opens on Home. With no canvas running, Home says how to start one: `npx marver dev` in a repo with Marver ("It
71
- appears here, with its own tab, a second after it starts."), and for a repo without Marver yet, `npm i -D
72
- @marver-design/marver && npx marver init` first. Each command has a button that copies it. Every canvas running on
73
- this Mac gets its own tab; `⌘L`, or Home's field, opens a link - a local canvas's, or a shared canvas's.
72
+ Marver opens on Home. With no canvas yet, Home is the welcome: "No canvas running yet", and three ways in. In a repo
73
+ with Marver, run `npx marver dev`. In a repo without Marver yet, run `npm i -D @marver-design/marver && npx marver
74
+ init` first. Each command has a Copy button. For a canvas someone shared with you, paste its link in the field there
75
+ and press Return. A canvas you start appears a second later, on Home and in its own tab. The ? button in the corner
76
+ is How Marver runs ([Help](#help-how-marver-runs)).
74
77
 
75
78
  A canvas's tab and Home card wear its name and its logo: `name` in its `design/config.ts` (else `share.name`, else
76
79
  the folder's name) and `logo` (else `share.logo`, else the first of `design/logo.svg|png`, `public/logo.svg|png`,
@@ -87,29 +90,114 @@ on that board, the frames selected and in view:
87
90
  `marver show` does - and if you were typing a comment or a Jam edit there, it stays put and says "Your agent wants
88
91
  to show you <the frame> · Go" instead, so nothing you typed is lost.
89
92
  - **It has no tab yet:** a tab opens on that place.
90
- - **The canvas is not running:** Home opens with its card first, highlighted, and its start command ready to copy.
93
+ - **The canvas is not running:** Home opens with its card first under Not running, highlighted, and its menu open on
94
+ Copy start command. When that canvas's tab is still open but stopped, its tab's card is the one.
91
95
 
92
96
  A link names its canvas by its folder, and only a canvas running from that same folder opens it - never another canvas
93
97
  that took the same port later. A link that names no place Marver understands opens the canvas on its board.
94
98
  `marver link` gives the `marver://` link only while Marver is in use (it keeps `~/.marver/state/app-live.json` fresh
95
- every 30 seconds) with that canvas open in a tab; otherwise, and with `--web`, the localhost link.
99
+ every 30 seconds) with that canvas open in a tab; otherwise, and with `--web`, the localhost link. Home's field opens a
100
+ `marver://` link too ([The link field](#the-link-field)).
96
101
 
97
- ## A tab's badge and menu
102
+ ## Home
98
103
 
99
- Each canvas's tab shows an orange count of what needs you (Marver's questions, captures to review, runs that failed or
100
- stalled), else a blue dot when frames are new since you looked (no number, from 1.1), else a shimmer while an agent
101
- works. Right-click the tab of a canvas on this Mac for **Mark All as Seen** and, with Marver 0.31 or later, **Resolve
102
- All Comments**: every open conversation on that canvas, never what Jam is working on, with Undo. [What the marks
103
- mean](boards-and-folders.md#what-is-new-what-needs-you).
104
+ Home shows your canvases as cards. **View** (the sliders button at the top) switches between two views, and Home
105
+ keeps your choice; it starts on Board.
104
106
 
105
- ## Home
107
+ - **Board**: a column per state - Needs you, Agent working, Ready to review, Running, Not running - and the shared
108
+ canvases as chips along the foot, under Shared with you. A full column scrolls.
109
+ - **Grid**: three sections, Running, Not running and Shared with you, four cards a row. Running holds the cards of the
110
+ board's first four columns, in that order. A section with no card is left out.
111
+
112
+ Each canvas has a card (one per tab, so a canvas open twice has two), in the first column that fits, in that order. Each card's line says what is going on:
113
+
114
+ | Column | The line |
115
+ |---|---|
116
+ | Needs you | "2 questions on Checkout", "Agent run failed on Checkout", "Agent stalled on Checkout", "Agent run to review on Checkout" (the board is named when all of them are on one board), or "Stopped unexpectedly": its process ended while you were not looking at it |
117
+ | Agent working | "Agent working on Checkout · 4 min", from an hour "2 h". The board and the minutes need a canvas on Marver 0.32 or later; an older one reads "Agent working" |
118
+ | Ready to review | "3 new frames to look at" |
119
+ | Running | "Running", "Starting…", "Not responding", "Can't reach", "Crashed" or "Unloaded", then " · tab closed" when its tab is closed and it still runs. A port that does not answer as a Marver canvas reads "Not a Marver canvas", named by its host |
120
+ | Not running | "Stopped" while its tab is open, "Ran 2 hours ago" ("Ran Oct 27" after two weeks), or "Not running" for a canvas a link named that never ran here |
121
+ | Shared with you | "Open" (or "Opening…", "Can't reach", "Crashed") for a shared canvas in a tab, "Opened 3 days ago" for one opened before |
122
+
123
+ "Agent working" counts from when the agent began: a `marver work start` hold, or a Jam run once it has started, never
124
+ while it waits for its turn, a session or a free slot. Not running lists the canvases that ran before, not those in a
125
+ temporary folder (`/tmp`, `/private/tmp`, `/var/folders`), which are tests and scratch copies. A shared canvas shows its
126
+ name and logo once Marver has opened it once (read from the canvas's own `meta.json`, through that tab's sign-in).
127
+
128
+ **Clicking a card.** A running or shared card opens its tab; Return or Space does the same from the keyboard. A card
129
+ that is not running opens its menu.
130
+
131
+ **A card's menu.** Right-click a card, or press its more button (it shows on hover), for its menu. A shared chip on the
132
+ board has the same menu on a right-click.
133
+
134
+ | Card | Its menu |
135
+ |---|---|
136
+ | running | Open; Update to 0.32.0, in blue, when its Marver has a newer release; Copy link (its localhost link); Copy path; Reveal in Finder |
137
+ | not running | Copy start command; Copy link (its `marver://` link); Copy path; Reveal in Finder |
138
+ | shared | Open; Copy link |
139
+ | not a Marver canvas | Open |
140
+
141
+ Update to copies the command that updates that canvas, in its own folder; nothing is updated in the app. Copy start
142
+ command copies the command that starts it in its folder. A copy row says "Copied" for a moment, then the menu closes.
143
+
144
+ ### The link field
145
+
146
+ The field at the top of Home opens a canvas link: a local canvas's, a shared canvas's https link, or a `marver://`
147
+ link. ⌘L (File > Open Link…) takes you there from any tab. Before you press Return, the line under it says where the
148
+ link goes ("↩ opens in Checkout's tab"), or why it can't ("Nothing is running on localhost:5173"). Escape takes you
149
+ back to the tab you came from.
150
+
151
+ ### Help: How Marver runs
152
+
153
+ The ? button opens How Marver runs: how to open a canvas (`npx marver dev` in its repo), add Marver to a repo (`npm i
154
+ -D @marver-design/marver && npx marver init`) and update a canvas (`npm i -D @marver-design/marver@latest`), each with
155
+ a Copy button. Its foot shows where Marver keeps its settings and agent notes (`~/.marver/`), with Show the files. A
156
+ click outside it, or Escape, closes it.
157
+
158
+ ## The tab strip
159
+
160
+ Each canvas you run has a tab, with its round logo and its name. The tabs share the strip's width, and the open one
161
+ stands out in glass. On a narrow window, or with many tabs, a tab shrinks to its logo and its badge, and » at the end
162
+ lists the tabs that do not fit, with a word for any that is not running as it should ("stopped", "can't reach"). Pick
163
+ one to open it. Home has its own button, at the left (⌘T). Hover a tab to see its key: ⌘1 to ⌘8, and ⌘9 for the last
164
+ canvas.
165
+
166
+ **Its badge.** Each canvas's tab shows an orange count of what needs you (Marver's questions, captures to review, runs
167
+ that failed or stalled), else a blue dot when frames are new since you looked, else a shimmer while an agent works,
168
+ and a teal dot while a Jam session runs. While Home is open the tabs drop their counts, dots and shimmer: Home already
169
+ shows them. [What the marks mean](boards-and-folders.md#what-is-new-what-needs-you).
170
+
171
+ **Its menu.** Right-click a tab for its Marver menu, with icons like the sidebar's:
172
+
173
+ - a canvas on this Mac: Open in browser, Reveal in Finder, Copy local link, Mark all as seen and, with Marver 0.31 or
174
+ later, Resolve all comments (every open conversation on that canvas, never what Jam is working on, with Undo);
175
+ - a shared canvas: Open in browser, Copy link, Reload, Force reload;
176
+ - every tab: Close tab.
177
+
178
+ The ContextMenu key or ⇧F10 opens it from the keyboard. » opens the same kind of menu, one row per hidden tab.
179
+
180
+ **Moving the window.** Drag the strip where it is empty. However many tabs you have, the strip keeps at least 40 px
181
+ empty before its right end, or before a message showing there, so there is always somewhere to grab: the tabs shrink
182
+ and move behind » a little sooner instead.
183
+
184
+ The strip and Home follow Reduce Transparency and Increase Contrast, and show a clear focus ring when you use the
185
+ keyboard.
186
+
187
+ ## Hide UI in play
188
+
189
+ In play, prototype, slides or focus mode, `h` (Hide UI) takes the whole window: the tab strip and the window's buttons
190
+ go with Marver's own controls, and the stage grows into the room they leave. A thin band along the top, 16 px and
191
+ invisible, still drags the window. Everything comes back with:
192
+
193
+ - `h` again;
194
+ - Escape, which leaves play (it first cancels a comment you are writing or the laser);
195
+ - leaving play any other way: the strip comes back, and the canvas keeps its controls hidden until you press `h`;
196
+ - switching tabs (⌘1 to ⌘9, say): coming back, everything shows.
106
197
 
107
- - **Running canvases** each have a card; one whose Marver has a newer release says "0.31.0 available" with the command
108
- that updates it, in its own folder, ready to copy.
109
- - **Recently here** lists the canvases that ran before, with their logo and start command - not those in a temporary
110
- folder (`/tmp`, `/private/tmp`, `/var/folders`), which are tests and scratch copies.
111
- - **Shared canvases** show their name and logo once Marver has opened them once (read from the canvas's own
112
- `meta.json`, through that tab's sign-in).
198
+ On a board locked to play, Escape shows everything again. On the canvas, Hide UI hides Marver's controls and keeps the
199
+ strip, which is how you move between canvases; a shared canvas's tab keeps the strip too. This needs app 1.2 and a
200
+ canvas on Marver 0.32 or later. In a browser, or with an older app or canvas, Hide UI works as before: the strip stays.
113
201
 
114
202
  ## What it asks, and when
115
203
 
@@ -140,7 +228,7 @@ of what changed), and the Marver menu reads Restart to Install Update. Two ways
140
228
 
141
229
  **After an update, Marver opens as it does after a quit.** With Settings' "Reopen tabs at launch" on (the default),
142
230
  each running canvas gets its tab back on the board it showed, and Settings if it was open; with it off, Marver starts
143
- on Home and every running canvas still gets its tab. Shared canvases do not come back in tabs (Home's Shared canvases
231
+ on Home and every running canvas still gets its tab. Shared canvases do not come back in tabs (Home's Shared with you
144
232
  reopens them), and a canvas that is not running gets no tab. What a page held only in memory, such as an open panel or
145
233
  a scroll position, does not come back. The first launch after says "Updated to 1.0.1", once.
146
234
 
@@ -211,7 +299,7 @@ and roughly when, and attach the file.
211
299
  Marver keeps its settings and its state in `~/.marver/`, beside the files `marver dev` keeps there. At every launch
212
300
  the app writes a `README.md` in it, for you and your coding agent: every file, every setting, and the rules for
213
301
  changing them (edits to the README itself are lost). Settings (Marver > Settings…) writes `config.json` and
214
- `theme.json`. Home's Show the Files opens the folder; Help > Show Performance Files opens the app's performance records.
302
+ `theme.json`. Show the files, in Home's How Marver runs (the ? button), opens the folder; Help > Show Performance Files opens the app's performance records.
215
303
 
216
304
  ## Uninstalling
217
305
 
@@ -118,8 +118,10 @@ them, and the open conversations per board - for you, or for your agent at the s
118
118
  **In the Mac app** (0.3, with Marver 0.29), each canvas's tab sums this up, even while it is hidden: an
119
119
  orange count of what needs you - Marver's questions, captures to review, runs that failed or stalled -
120
120
  else a blue dot for new frames (no number, from app 1.1), else a shimmer while an agent works, and a teal
121
- dot while a Jam session runs. Its right-click menu holds **Resolve All Comments** beside **Mark All as
122
- Seen** for a canvas on Marver 0.31 or later. Turn notices on and a canvas you are not looking at sends one when something new needs you, and the
121
+ dot while a Jam session runs; while Home is open the tabs drop them: Home shows them. Its right-click menu holds
122
+ **Resolve all comments** beside **Mark all as seen** for a canvas on Marver 0.31 or later. Home's card says the same
123
+ in words ("2 questions on Checkout", "3 new frames to look at"), and with Marver 0.32 (app 1.2) which board an agent
124
+ works on and for how long ([Home](app.md#home)). Turn notices on and a canvas you are not looking at sends one when something new needs you, and the
123
125
  Dock counts them all. Clicking a notice opens what it names where you can see it, on its board: a question
124
126
  in its thread on the frame (Play left and hidden pins shown for it), or in a panel with a field to answer
125
127
  when no frame on the board holds it; a review in its review; a failed run with Retry in view, a stalled
@@ -256,7 +258,8 @@ confirmed.
256
258
  **An agent at work.** While an agent works on a board's frames (`marver work start`, or a Live Jam
257
259
  job), that board's icon in the sidebar turns accent blue with a highlight sweeping across it - the
258
260
  frames' working shimmer, in miniature - and so does a closed folder holding it. It lasts exactly as
259
- long as the work, so nobody sets it.
261
+ long as the work, so nobody sets it. In the Mac app (1.2, with Marver 0.32), the canvas's Home card reads "Agent
262
+ working on <board> · N min", counted from when the work began: a Jam run waiting for its turn does not count.
260
263
 
261
264
  ## Starting points
262
265
 
package/docs/slides.md CHANGED
@@ -59,7 +59,8 @@ Press `p` on a board whose publish row says slides and you get slides mode:
59
59
  the stage scaled to the window, the standard prototype toolbars (with
60
60
  `chrome: full`, the default), arrows / Space / click to advance, `d` cycles
61
61
  the theme, and two views of the stage: Slide (fit to the window, room for
62
- the chrome) and Fill window (edge to edge). Publish it with:
62
+ the chrome) and Fill window (edge to edge). `h` hides the chrome; in the Mac app (1.2) it hides the tab
63
+ strip too and the stage grows into the window ([Hide UI in play](app.md#hide-ui-in-play)). Publish it with:
63
64
 
64
65
  ```json
65
66
  { "boards": { "pitch": { "max": "comment", "type": "slides",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@marver-design/marver",
3
- "version": "0.31.0",
3
+ "version": "0.32.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,
@@ -11,12 +11,14 @@
11
11
  * next) stays prototype-only.
12
12
  */
13
13
  import { setStageSize } from './stage-size.ts'
14
- import { usable } from './inset.ts'
14
+ import { onTopChange, usable } from './inset.ts'
15
+ import { onImmersiveChange, tight as tightNow } from './immersive.ts'
16
+ import { MOTION } from '../../shared/immersive.ts'
15
17
  import { frameLoaded, frameReady, onFrameMessage, stageNavigated } from './jam-capture.ts'
16
18
  import { jamKey } from './jam-keys.ts'
17
19
  import { letGoOfTile } from './jam-state.ts'
18
20
  import { JamButton } from './jam-session.tsx'
19
- import { useEffect, useRef, useState } from 'react'
21
+ import { useEffect, useLayoutEffect, useRef, useState } from 'react'
20
22
  import { useStore, BOARD_POLICY, BRANDING, CONFIG, PUBLISHED, SOURCE_REVEALED, boardLabel, boardLocked, cap, fetchBoardNames, modeAllowed, playsAsSlides, SLIDE_INTRINSIC, stoppedFor, type Node } from './store.ts'
21
23
  import { deckOrder } from './play-order.ts'
22
24
  import { boardOrder, presentDevice } from '../../shared/export-plan.ts'
@@ -312,6 +314,15 @@ function PlayInner() {
312
314
  const src = useRef(play ? withWs(`${ROUTE}/stage/?at=${encodeURIComponent(play.at)}&theme=${encodeURIComponent(play.theme)}${slParams(play)}`) : '')
313
315
  // the view below the Mac app's strip when the shell took the inset (inset.ts): fill, the doc preset and every fit
314
316
  const [win, setWin] = useState(() => { const u = usable(); return { w: u.width, h: u.height } })
317
+ // spec 32 C4: play's 24 px margins - Hide UI on in play (immersive.ts `tight`: in the app, at main's answer)
318
+ const [tight, setTight] = useState(tightNow)
319
+ // spec 32 C5.2: the stage's FLIP on a re-fit C4 causes - its rect before the re-fit, read as it changes
320
+ const rootRef = useRef<HTMLDivElement>(null)
321
+ const stageRef = useRef<HTMLDivElement>(null)
322
+ const flipFrom = useRef<{ width: number; height: number } | null>(null)
323
+ const flipping = useRef<{ end: () => void } | null>(null)
324
+ const fixedRef = useRef(false)
325
+ const sizeRef = useRef({ w: 0, h: 0 })
315
326
  const [pillOpen, setPillOpen] = useState(true) // collapse (pill -> re-open fab), like the canvas
316
327
  const [stageReady, setStageReady] = useState(0) // bumps on each sh:stage-ready (reload) - re-drives the highlight
317
328
  const [away, setAway] = useState(false) // the stage shows another project's "another canvas" page (A1.11)
@@ -329,6 +340,9 @@ function PlayInner() {
329
340
  // a frame deep link is presentation, not access (01-sharing §3.5) - on a PUBLISHED canvas. In dev
330
341
  // the visitor is the owner, who followed an agent's link: the way back to the canvas stays.
331
342
  const noDoor = locked || (!!play?.deep && PUBLISHED)
343
+ // read by the key handler, which is bound once (spec 32 C7)
344
+ const noDoorRef = useRef(noDoor)
345
+ noDoorRef.current = noDoor
332
346
 
333
347
  // the stage is same-origin (/__mv/stage/); a fixed target origin keeps anchor bundles
334
348
  // from leaking if a link ever navigates the iframe cross-origin
@@ -572,6 +586,8 @@ function PlayInner() {
572
586
  c.setMode(false); c.setActive(null); c.setDraft(null); s.setLaser(false)
573
587
  endAfterFrames(h)
574
588
  }
589
+ // spec 32 C7: a board with no way out (locked, a published deep link) - Escape with nothing live shows the UI again
590
+ else if (noDoorRef.current && isHideUI()) { cmd('hide-ui', how); toggleHideUI() }
575
591
  else exitFrom(how)
576
592
  return
577
593
  }
@@ -629,9 +645,60 @@ function PlayInner() {
629
645
  useEffect(() => {
630
646
  const onResize = () => { const u = usable(); setWin({ w: u.width, h: u.height }) }
631
647
  window.addEventListener('resize', onResize)
632
- return () => window.removeEventListener('resize', onResize)
648
+ // spec 32 C4: `win` follows the play inset (onTopChange) and the margins `tight` - one refit for main's one answer
649
+ // (the two land in one turn and render once). A fixed stage's rect is read first, for its FLIP (C5.2): mid-FLIP it
650
+ // is the size it shows now, so a reversal starts from there
651
+ const refit = () => {
652
+ if (fixedRef.current && stageRef.current) { const r = stageRef.current.getBoundingClientRect(); flipFrom.current = { width: r.width, height: r.height } }
653
+ onResize()
654
+ setTight(tightNow())
655
+ }
656
+ const offTop = onTopChange(refit)
657
+ const offTight = onImmersiveChange(refit)
658
+ return () => { window.removeEventListener('resize', onResize); offTop(); offTight(); flipping.current?.end() }
633
659
  }, [])
634
660
 
661
+ // spec 32 C5.2: a fixed stage re-fit by C4 (the play inset, the margins) animates as a FLIP - it starts at
662
+ // scale(prev/next) at its new whole-pixel size and runs to none over the stage's time; `.flip` holds the inner .dev's
663
+ // own size transition off, so one animation resizes it. Ended by the transform's transitionend, or the time + 50 ms;
664
+ // a newer re-fit mid-FLIP starts again from the rect it shows (read before the re-fit); leaving play drops it at once;
665
+ // a stage that is no longer fixed (responsive fill, the doc preset - picked mid-FLIP) drops it at once too: it never FLIPs
666
+ useLayoutEffect(() => {
667
+ if (!fixedRef.current) flipping.current?.end()
668
+ const from = flipFrom.current
669
+ flipFrom.current = null
670
+ const el = stageRef.current, root = rootRef.current
671
+ const { w, h } = sizeRef.current
672
+ if (!from || !el || !root || !w || !h || (Math.abs(from.width - w) < 0.5 && Math.abs(from.height - h) < 0.5)) return
673
+ flipping.current?.end()
674
+ if (matchMedia('(prefers-reduced-motion: reduce)').matches) return // C5.4: instant
675
+ const m = tightNow() ? MOTION.out : MOTION.back
676
+ root.classList.add('flip')
677
+ el.style.transition = 'none'
678
+ el.style.transform = `scale(${from.width / w}, ${from.height / h})`
679
+ void el.getBoundingClientRect()
680
+ el.style.transition = `transform ${m.stage}ms ${m.stageEase}`
681
+ el.style.transform = 'none'
682
+ let timer: ReturnType<typeof setTimeout> | undefined
683
+ const onEnd = (e: TransitionEvent) => { if (e.target === el && e.propertyName === 'transform') f.end() }
684
+ const f = {
685
+ end: () => {
686
+ clearTimeout(timer)
687
+ el.removeEventListener('transitionend', onEnd)
688
+ root.classList.remove('flip')
689
+ // cancelled, not only cleared: under the default `all 0s` a running transform transition whose end is unchanged
690
+ // runs on, so `none` is flushed first - an end mid-FLIP (fill picked, play left) leaves no scale behind
691
+ el.style.transition = 'none'; el.style.transform = 'none'
692
+ void el.getBoundingClientRect()
693
+ el.style.transition = ''; el.style.transform = ''
694
+ if (flipping.current === f) { flipping.current = null; setStageReady((n) => n + 1) } // the comments overlay re-measures
695
+ },
696
+ }
697
+ el.addEventListener('transitionend', onEnd)
698
+ timer = setTimeout(f.end, m.stage + 50)
699
+ flipping.current = f
700
+ })
701
+
635
702
  if (!play) return null // parent gates on play; belt to its braces
636
703
 
637
704
  // doc preset: reading width, natural document scrolling - the iframe takes the
@@ -651,11 +718,18 @@ function PlayInner() {
651
718
  // (no hook here - this is past the early return: a microtask, right after this layout)
652
719
  const stageAt = play.at, stageW = Math.round(vp.width), stageH = Math.round(vp.height)
653
720
  queueMicrotask(() => setStageSize(stageAt, stageW, stageH))
721
+ // spec 32 C4: shown, today's margins; Hide UI on (`tight`), 24 px in both axes in every host - fill and the doc preset
722
+ // have none either way, and grow with `win`
654
723
  const scale = stage ? Math.max(0.05, fill ? Math.min(win.w / vp.width, win.h / vp.height)
724
+ : tight ? Math.min((win.w - 24) / vp.width, (win.h - 24) / vp.height)
655
725
  : slides ? Math.min((win.w - 48) / vp.width, (win.h - (deckChrome === 'none' ? 48 : 88)) / vp.height)
656
726
  : Math.min((win.w - 96) / vp.width, (win.h - 128) / vp.height))
657
727
  : docPreset || fill ? 1
728
+ : tight ? Math.min(1, (win.w - 24) / vp.width, (win.h - 24) / vp.height)
658
729
  : Math.min(1, (win.w - 96) / vp.width, (win.h - 128) / vp.height)
730
+ // the stages whose width and height scale together get the FLIP (C5.2): a slide stage (under fill too) and a device;
731
+ // responsive fill and the doc preset only grow in height while the iframe reflows - a FLIP would squash the live frame
732
+ fixedRef.current = !!stage || !(docPreset || fill)
659
733
  const names = Object.keys(CONFIG.viewports)
660
734
  const list = focus ? [play.at] : slides ? currentDeck() : playList()
661
735
  const pos = list.indexOf(play.at)
@@ -666,14 +740,15 @@ function PlayInner() {
666
740
  // fractional sizes left subpixel seams glowing at the corners on dark frames
667
741
  const dw = Math.round(vp.width * scale)
668
742
  const dh = Math.round(vp.height * scale)
743
+ sizeRef.current = { w: dw, h: dh }
669
744
  const deviceHint = stage ? `${vp.width} × ${vp.height} stage · ${fill ? 'edge to edge' : 'fit to the window'}`
670
745
  : fill ? 'Fill window' : `${CONFIG.viewports[play.device] ? `${deviceLabel(play.device)} · ` : ''}${vp.width} × ${vp.height} · keys 1-${names.length + 1}`
671
746
 
672
747
  return (
673
- <div className={`sh-play${fill || docPreset ? ' fill' : ''}${docPreset ? ` doc t-${play.theme}` : ''}`}>
748
+ <div ref={rootRef} className={`sh-play${fill || docPreset ? ' fill' : ''}${docPreset ? ` doc t-${play.theme}` : ''}`}>
674
749
  {/* device + comment overlay share ONE flex-centered box; the overlay is inset:0 over
675
750
  it (a sibling of the clipping .dev, so a thread card is never eaten by overflow) */}
676
- <div className="sh-play-stage" style={{ width: dw, height: dh }}
751
+ <div ref={stageRef} className="sh-play-stage" style={{ width: dw, height: dh }}
677
752
  onClick={slides ? (e) => {
678
753
  // background advance: never on controls, links, media, comments, or goto targets
679
754
  const t = e.target as Element
@@ -24,6 +24,9 @@
24
24
  * - `mv:show` (app 1.1, spec 31 D1): a `marver://` link into this tab, shown by show.ts as `marver show` is; and
25
25
  * show.ts asks `front()` once it showed a `marver show`.
26
26
  *
27
+ * - `mv:immersive` (app 1.2, spec 32 C1, C2): immersive play's wish, and main's answer - immersive.ts; a `hidden` or
28
+ * `untrusted` app state ends it with Hide UI off (C6.4, C6.5).
29
+ *
27
30
  * The one ground (0.27.2, A3.8 #27, #31): `mv:hello` says the inset the shell applied (inset.ts's `TOP`: 44 only when
28
31
  * the app said so and gave the whole presentation contract), and each `mv:present { epoch, w, h, frames }` is answered
29
32
  * once the viewport has that size (500 ms at most) and `frames` animation frames have passed, with the size it was
@@ -52,6 +55,7 @@ import { useJamVoice, voiceUntrusted } from './jam-voice.ts'
52
55
  import { endOpen, openLiveItem } from './open-item.ts'
53
56
  import { showTarget } from './show.ts'
54
57
  import { navigatedByHand } from './goto.ts'
58
+ import { appStateEnds, startImmersive } from './immersive.ts'
55
59
 
56
60
  /** The ground under the strip (A2.14 #26): the shell's own - never a frame's pinned theme. */
57
61
  export const shellDark = (): boolean => { const s = useStore.getState(); return !!s.play || s.viewTheme === 'dark' }
@@ -210,6 +214,8 @@ function onAppState(s: AppState): void {
210
214
  if (s === 'shown') { void resumeReconcile(); return }
211
215
  // a notice's click still reading or waiting moves nothing more once the tab is hidden or its trust is gone
212
216
  endOpen()
217
+ // spec 32 C6.4, C6.5: immersive play ends with Hide UI off, so coming back shows the chrome
218
+ appStateEnds()
213
219
  if (s === 'untrusted') voiceUntrusted()
214
220
  }
215
221
 
@@ -237,6 +243,8 @@ export function startAppBridge(): void {
237
243
  // the one ground's presentation requests (0.27.2): answered only when the shell took the inset - a shell that did
238
244
  // not is placed below the strip and never asked (A3.8 #31)
239
245
  if (TOP) call(() => { answerPresents(app, call) })
246
+ // spec 32 C1: immersive play's wish, sent on every change, and main's answers (an app without `immersive` gets none)
247
+ call(() => startImmersive())
240
248
 
241
249
  // 1. hello, first (A2.14 #9)
242
250
  call(() => app.hello(helloNow()))
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Immersive play (spec 32 C1, C2, C6): in play - prototype, slides or focus - Hide UI takes the whole window in the Mac
3
+ * app: the strip leaves with the shell's pills and the stage grows into the room they gave back. Canvas mode never is.
4
+ *
5
+ * The rule is derived, never latched. The wish:
6
+ *
7
+ * wants = TOP === 44 && typeof APP?.immersive === 'function' && isHideUI() && !!play && !useLink.shown
8
+ *
9
+ * read from its three sources - `onHideUI`, the store's `play`, and `useLink`'s `shown` (the stopped state, which changes
10
+ * on its own while the connection is probed) - and sent as `APP.immersive({ on })` on every change of it. Main is the
11
+ * authority (app/src/main/immersive-gate.ts): what the shell shows follows main's answer, never the wish. `granted` is
12
+ * true only after main's `{on: true}` for this document; the inset (C3, `setImmersiveTop`) and the recorder (C11) read
13
+ * it from here. `tight` - play's 24 px margins (C4) - is `granted || (isHideUI() && refused)` where the app speaks
14
+ * immersive, `refused` being main's latest answer a `{on: false}` with no `end` to a wish `on`; elsewhere (Chrome, app
15
+ * 1.1) it is `isHideUI()`, as before. So in the app nothing moves between the H press and main's answer, and the answer
16
+ * moves the margins and the inset in one refit. A wish `off` main has not answered within 1 s is taken as answered
17
+ * `{on: false}`.
18
+ *
19
+ * The ways back the shell owns (C6): an answer `{on: false, end: true}` - main took immersive away while the wish stood -
20
+ * restores the inset and turns Hide UI off while play is still on (never a blind toggle); a `hidden` or `untrusted` app
21
+ * state does the same while immersive (`appStateEnds`). Every exit the shell's own wish drops (H, play left, stopped) is
22
+ * answered with no `end`, so Hide UI stays exactly as that exit left it (C1.2).
23
+ */
24
+ import { APP } from './marver-app.ts'
25
+ import { TOP, setImmersiveTop } from './inset.ts'
26
+ import { isHideUI, onHideUI, toggleHideUI } from './Toolbar.tsx'
27
+ import { useStore } from './store.ts'
28
+ import { useLink } from './api.ts'
29
+
30
+ /** How long a wish `off` waits for main's answer before it is taken as answered `{on: false}` (C1). */
31
+ export const OFF_WAIT_MS = 1000
32
+
33
+ /** The app speaks immersive play: the inset is the strip's, and the preload has the method (C1.4: no FEATURE name). */
34
+ const speaks = (): boolean => TOP === 44 && typeof APP?.immersive === 'function'
35
+
36
+ let wish = false // the wish last sent (none is sent before the first `on`)
37
+ let granted = false // main's `{on: true}` for the wish now standing
38
+ let refused = false // main's latest answer a `{on: false}` with no `end` to a wish `on`
39
+ let offTimer: ReturnType<typeof setTimeout> | undefined
40
+ let started = false
41
+ let shown = { granted: false, tight: false }
42
+ const listeners = new Set<() => void>()
43
+
44
+ /** The wish now, from its three sources (C1). */
45
+ export function wants(): boolean {
46
+ return speaks() && isHideUI() && !!useStore.getState().play && !useLink.getState().shown
47
+ }
48
+ /** Main granted immersive play for this document: the strip is hidden, the play inset is 0 (C3). */
49
+ export const isGranted = (): boolean => granted
50
+ /** Play's 24 px margins (C4): where the app speaks immersive, at main's answer; elsewhere, Hide UI alone. */
51
+ export function tight(): boolean {
52
+ return speaks() ? granted || (isHideUI() && refused) : isHideUI()
53
+ }
54
+
55
+ /** The inset follows `granted`, then whoever listens is told once - one refit for one answer. */
56
+ function emit(): void {
57
+ setImmersiveTop(granted)
58
+ const now = { granted, tight: tight() }
59
+ if (now.granted === shown.granted && now.tight === shown.tight) return
60
+ shown = now
61
+ for (const f of [...listeners]) { try { f() } catch (err) { console.error(err) } }
62
+ }
63
+
64
+ /** One of the three sources changed: send the wish when it changed, and re-read `tight` (Hide UI alone moves it in Chrome). */
65
+ function sync(): void {
66
+ const w = wants()
67
+ if (w !== wish) {
68
+ wish = w
69
+ clearTimeout(offTimer); offTimer = undefined
70
+ try { APP?.immersive?.({ on: w }) } catch { /* the app went away under the page */ }
71
+ // a wish off main never answers is taken as answered: the inset comes back
72
+ if (!w) offTimer = setTimeout(() => answered({ on: false }), OFF_WAIT_MS)
73
+ }
74
+ emit()
75
+ }
76
+
77
+ /** Main's answer to the latest wish (the preload drops one to an older wish and one for another document, C2). */
78
+ function answered(s: { on: boolean; end?: boolean }): void {
79
+ if (!s || typeof s.on !== 'boolean') return
80
+ clearTimeout(offTimer); offTimer = undefined
81
+ if (s.on) {
82
+ // an `on` can only answer an `on`; one that outran a newer `off` grants nothing
83
+ if (wish) { granted = true; refused = false }
84
+ } else {
85
+ granted = false
86
+ refused = !s.end && wish
87
+ }
88
+ emit()
89
+ // C6.6: main took it away while the wish stood - and play is still on: Hide UI goes, so the chrome comes back
90
+ if (s.on === false && s.end === true && useStore.getState().play && isHideUI()) toggleHideUI()
91
+ }
92
+
93
+ /** C6.4, C6.5: the tab was hidden or lost its trust - immersive play ends with Hide UI off, so coming back shows the chrome. */
94
+ export function appStateEnds(): void {
95
+ if (granted && isHideUI()) toggleHideUI()
96
+ }
97
+
98
+ /** Subscribes to the three sources and to main's answers; idempotent. app-bridge.ts starts it in the app; the first
99
+ * `onImmersiveChange` listener starts it anywhere else (Chrome needs `tight` to follow Hide UI). */
100
+ export function startImmersive(): void {
101
+ if (started) return
102
+ started = true
103
+ onHideUI(sync)
104
+ useStore.subscribe((s, p) => { if (!!s.play !== !!p.play) sync() })
105
+ useLink.subscribe((s, p) => { if (s.shown !== p.shown) sync() })
106
+ if (speaks() && typeof APP?.onImmersive === 'function') {
107
+ try { APP.onImmersive((s) => answered(s)) } catch { /* no answers: nothing is ever granted */ }
108
+ }
109
+ shown = { granted, tight: tight() }
110
+ sync()
111
+ }
112
+
113
+ /** Told when `granted` or `tight` changes (after the inset moved). Returns the unsubscribe. */
114
+ export function onImmersiveChange(f: () => void): () => void {
115
+ startImmersive()
116
+ listeners.add(f)
117
+ return () => { listeners.delete(f) }
118
+ }
119
+
120
+ // dev-only inspection hook for tests (never installed in published builds)
121
+ if (typeof window !== 'undefined' && (import.meta as { env?: { DEV?: boolean } }).env?.DEV) {
122
+ (window as unknown as { __mvImmersive: unknown }).__mvImmersive = { wants, tight, granted: isGranted }
123
+ }
@@ -10,6 +10,12 @@
10
10
  * FROZEN before the A3 streams split (A3.8 #53): `TOP`, `VISIBLE_TOP`, `usable()`, `onScreen()` and `applyInset()`.
11
11
  * Consumers: the top-anchored layers, the selection bar, tips and menus (`TOP + 8`), insets(), focus, play sizes
12
12
  * and Jam's fill use `usable()`; seen marks, visibleNodes(), A3.3's probes and A4.3's full-view test use `onScreen()`.
13
+ *
14
+ * Amended in writing for spec 32 (C3, F3; Nic, gaps.md 3, 29): `TOP`, `VISIBLE_TOP`, `onScreen()` and `applyInset()`
15
+ * keep their contract, and so does `--mv-top`. Only `usable()` is dynamic, and only in immersive play: once main grants
16
+ * it, `setImmersiveTop(true)` drops the play inset to 0, which `usable()`, `onTopChange` listeners and `--mv-play-top`
17
+ * (read by `.sh-play` alone) follow; every other `var(--mv-top)` consumer keeps 44. Until immersive play is wired
18
+ * (spec 32 W4) nothing calls it, so `usable()` answers `TOP` as before.
13
19
  */
14
20
  import { EDGE_FADE, TOP_INSET, type Inset } from '../../shared/app-api.ts'
15
21
  import { APP } from './marver-app.ts'
@@ -23,12 +29,32 @@ export const VISIBLE_TOP = TOP ? TOP + EDGE_FADE : 0
23
29
  export function applyInset(): void {
24
30
  if (!TOP) return
25
31
  document.documentElement.style.setProperty('--mv-top', `${TOP}px`)
32
+ // spec 32 C3: the play inset, `TOP` until immersive play drops it (`setImmersiveTop`)
33
+ document.documentElement.style.setProperty('--mv-play-top', `${TOP}px`)
26
34
  document.documentElement.classList.add('mv-inset')
27
35
  }
28
36
 
29
- /** The view below the strip, in client px. */
37
+ /** spec 32 C3: the play inset now - `TOP`, or 0 while main has granted immersive play. */
38
+ let topNow: Inset = TOP
39
+ const topListeners = new Set<() => void>()
40
+ /**
41
+ * spec 32 C3: immersive play (granted by main) drops the play inset to 0; only `usable()` and `--mv-play-top` follow it.
42
+ * A no-op without the inset (`TOP` 0: Chrome, a published canvas, app 0.1): both values are then 0.
43
+ */
44
+ export function setImmersiveTop(on: boolean): void {
45
+ const next: Inset = on ? 0 : TOP
46
+ if (next === topNow) return
47
+ topNow = next
48
+ document.documentElement.style.setProperty('--mv-play-top', `${next}px`)
49
+ document.documentElement.classList.toggle('mv-immersive', on)
50
+ for (const f of [...topListeners]) { try { f() } catch (err) { console.error(err) } }
51
+ }
52
+ /** spec 32 C3: told when `setImmersiveTop` changes the play inset; answers what unsubscribes. */
53
+ export const onTopChange = (f: () => void): (() => void) => { topListeners.add(f); return () => { topListeners.delete(f) } }
54
+
55
+ /** The view below the strip, in client px: below `TOP`, or the whole view while immersive (spec 32 C3). */
30
56
  export function usable(): { top: number; left: number; width: number; height: number } {
31
- return { top: TOP, left: 0, width: innerWidth, height: Math.max(0, innerHeight - TOP) }
57
+ return { top: topNow, left: 0, width: innerWidth, height: Math.max(0, innerHeight - topNow) }
32
58
  }
33
59
 
34
60
  /** The part of a client rect on screen below the scroll edge, or null when none is. */
@@ -41,4 +67,4 @@ export function onScreen(r: DOMRectReadOnly): DOMRect | null {
41
67
  }
42
68
 
43
69
  // dev-only inspection hook for tests (never installed in published builds)
44
- if (typeof window !== 'undefined' && (import.meta as { env?: { DEV?: boolean } }).env?.DEV) (window as unknown as { __mvInset: unknown }).__mvInset = { TOP, VISIBLE_TOP, usable, onScreen }
70
+ if (typeof window !== 'undefined' && (import.meta as { env?: { DEV?: boolean } }).env?.DEV) (window as unknown as { __mvInset: unknown }).__mvInset = { TOP, VISIBLE_TOP, usable, onScreen, setImmersiveTop, onTopChange }
@@ -27,6 +27,7 @@ import { hooked, perfSeams, type Answered } from './recorder-seams.ts'
27
27
  import { addRow, createRate, foldRows, nodesIn, normRoute, p50, topWarnings } from './recorder-signals-core.ts'
28
28
  import { useStore } from './store.ts'
29
29
  import { isHideUI, onHideUI } from './Toolbar.tsx'
30
+ import { isGranted, onImmersiveChange } from './immersive.ts'
30
31
 
31
32
  type State = ReturnType<typeof useStore.getState>
32
33
 
@@ -158,7 +159,7 @@ type Shown = 'cohort' | 'first-frame' | 'two-frames'
158
159
  const SHOWN: Record<ModeName, Shown> = {
159
160
  laser: 'cohort', inspect: 'cohort', comments: 'cohort',
160
161
  play: 'first-frame', slides: 'first-frame',
161
- interact: 'two-frames', 'hide-ui': 'two-frames', 'jam-session': 'two-frames', 'jam-capture': 'two-frames', 'jam-review': 'two-frames', 'jam-lane': 'two-frames',
162
+ interact: 'two-frames', 'hide-ui': 'two-frames', immersive: 'two-frames', 'jam-session': 'two-frames', 'jam-capture': 'two-frames', 'jam-review': 'two-frames', 'jam-lane': 'two-frames',
162
163
  }
163
164
  /** The first frame of a stage is a cold boot: the command's own deadline (`play`, `slides`: 30 s), not a toggle's 5 s - a
164
165
  * slow first frame is the answer that record exists for. */
@@ -455,7 +456,7 @@ export function startSignals(): void {
455
456
 
456
457
  // what is on already counts from here, with no enter record of its own
457
458
  const s0 = useStore.getState()
458
- const held = { ...canvasModes(s0), comments: useComments.getState().commentMode, 'hide-ui': isHideUI(), 'jam-session': !!useJamQueue.getState().session, 'jam-capture': !!useJamCapture.getState().current, ...reviewModes() }
459
+ const held = { ...canvasModes(s0), comments: useComments.getState().commentMode, 'hide-ui': isHideUI(), immersive: isGranted(), 'jam-session': !!useJamQueue.getState().session, 'jam-capture': !!useJamCapture.getState().current, ...reviewModes() }
459
460
  for (const k of Object.keys(held) as ModeName[]) if (held[k]) modes.set(k, { since: now(), errors: 0 })
460
461
 
461
462
  // #21, #26: the `t` a message to a document carries
@@ -471,6 +472,8 @@ export function startSignals(): void {
471
472
  useJamCapture.subscribe(hooked('mode', (s: { current: string | null }, p: { current: string | null }) => { if (s.current !== p.current) setModes({ 'jam-capture': !!s.current }) }))
472
473
  useJamUi.subscribe(hooked('mode', () => setModes(reviewModes())))
473
474
  onHideUI(hooked('mode', () => setModes({ 'hide-ui': isHideUI() })))
475
+ // spec 32 C11: immersive play, held while main's grant stands (immersive.ts `granted`)
476
+ onImmersiveChange(hooked('mode', () => setModes({ immersive: isGranted() })))
474
477
 
475
478
  perfSeams.frameMessage.on(hooked(null, onFrameMessage))
476
479
  perfSeams.stageMessage.on(hooked(null, onStageMessage))