@marver-design/marver 0.31.0 → 0.33.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 (39) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +2 -2
  3. package/dist/{anchor-check-B92s9tVv.mjs → anchor-check-KCe6WeRA.mjs} +1 -1
  4. package/dist/{boards-OlAhZ87x.mjs → boards-jHmEPLV7.mjs} +1 -1
  5. package/dist/{build-BNssmbqd.mjs → build-4-k2XhhX.mjs} +3 -3
  6. package/dist/cli.mjs +12 -12
  7. package/dist/{comment-actions-Bxf9Ld4g.mjs → comment-actions-BCBcd-Wq.mjs} +12 -5
  8. package/dist/{comments-BakJQwaf.mjs → comments-C2SN1QdM.mjs} +4 -4
  9. package/dist/{daemon-MxoEQajX.mjs → daemon-CCDgagw2.mjs} +49 -8
  10. package/dist/{dev-BBZe_brH.mjs → dev-CJf5upVK.mjs} +9 -9
  11. package/dist/{link-Cmt9Xy4X.mjs → link-aZq5cExV.mjs} +1 -1
  12. package/dist/{pdf-CZENT6t3.mjs → pdf-GGya_nI6.mjs} +3 -3
  13. package/dist/{pdf-0m721FFn.mjs → pdf-HB0prF75.mjs} +1 -1
  14. package/dist/{perf-CIMijND6.mjs → perf-9ZEF5KLO.mjs} +2 -2
  15. package/dist/{perf-BB0XNt1M.mjs → perf-BA_NDarr.mjs} +1 -0
  16. package/dist/{plugin-CL8_wL7a.mjs → plugin-Cm74UDfp.mjs} +128 -47
  17. package/dist/{poster-B7uSjlEP.mjs → poster-BnuT9UyW.mjs} +1 -1
  18. package/dist/{publish-bakes-BjgDNeyS.mjs → publish-bakes-zHmPEOB5.mjs} +2 -2
  19. package/dist/{recover-ByuFQOF9.mjs → recover-BpRQxBA7.mjs} +1 -1
  20. package/dist/{shot-D2TQGo2V.mjs → shot-BuUCG46-.mjs} +1 -1
  21. package/dist/{shot-BqwkdtKn.mjs → shot-HZtclbOT.mjs} +3 -3
  22. package/dist/{show-B1u3DiJw.mjs → show-DhmiUu01.mjs} +2 -2
  23. package/dist/{work-Nv-n2_Un.mjs → work-B4tydWnf.mjs} +37 -1
  24. package/dist/{work-DRdzXPvg.mjs → work-CzIXp7n1.mjs} +3 -3
  25. package/docs/app.md +120 -21
  26. package/docs/boards-and-folders.md +10 -5
  27. package/docs/slides.md +2 -1
  28. package/package.json +1 -1
  29. package/src/client/shell/App.tsx +5 -1
  30. package/src/client/shell/Play.tsx +80 -5
  31. package/src/client/shell/app-bridge.ts +8 -0
  32. package/src/client/shell/immersive.ts +123 -0
  33. package/src/client/shell/inset.ts +29 -3
  34. package/src/client/shell/marks-ui.tsx +2 -2
  35. package/src/client/shell/recorder-signals.ts +5 -2
  36. package/src/client/shell/styles.css +25 -6
  37. package/src/shared/app-api.ts +41 -0
  38. package/src/shared/immersive.ts +13 -0
  39. 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,117 @@ 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
+ **D** switches Home, Settings and the strip over them between light and dark, the opposite of what shows (not while
113
+ you type in the link field or a menu is open). Canvases keep their own theme.
114
+
115
+ 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:
116
+
117
+ | Column | The line |
118
+ |---|---|
119
+ | 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 |
120
+ | 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" |
121
+ | Ready to review | "3 new frames to look at" |
122
+ | 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 |
123
+ | 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 |
124
+ | 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 |
125
+
126
+ "Agent working" counts from when the agent began: a `marver work start` hold, or a Jam run once it has started, never
127
+ while it waits for its turn, a session or a free slot. Not running lists the canvases that ran before, not those in a
128
+ temporary folder (`/tmp`, `/private/tmp`, `/var/folders`), which are tests and scratch copies. A shared canvas shows its
129
+ name and logo once Marver has opened it once (read from the canvas's own `meta.json`, through that tab's sign-in).
130
+
131
+ **Clicking a card.** A running or shared card opens its tab; Return or Space does the same from the keyboard. A card
132
+ that is not running opens its menu.
133
+
134
+ **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
135
+ board has the same menu on a right-click.
136
+
137
+ | Card | Its menu |
138
+ |---|---|
139
+ | 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 |
140
+ | not running | Copy start command; Copy link (its `marver://` link); Copy path; Reveal in Finder |
141
+ | shared | Open; Copy link |
142
+ | not a Marver canvas | Open |
143
+
144
+ Update to copies the command that updates that canvas, in its own folder; nothing is updated in the app. Copy start
145
+ command copies the command that starts it in its folder. A copy row says "Copied" for a moment, then the menu closes.
146
+
147
+ ### The link field
148
+
149
+ The field at the top of Home opens a canvas link: a local canvas's, a shared canvas's https link, or a `marver://`
150
+ link. ⌘L (File > Open Link…) takes you there from any tab. Before you press Return, the line under it says where the
151
+ link goes ("↩ opens in Checkout's tab"), or why it can't ("Nothing is running on localhost:5173"). Escape takes you
152
+ back to the tab you came from.
106
153
 
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).
154
+ ### Help: How Marver runs
155
+
156
+ The ? button opens How Marver runs: how to open a canvas (`npx marver dev` in its repo), add Marver to a repo (`npm i
157
+ -D @marver-design/marver && npx marver init`) and update a canvas (`npm i -D @marver-design/marver@latest`), each with
158
+ a Copy button. Its foot shows where Marver keeps its settings and agent notes (`~/.marver/`), with Show the files. A
159
+ click outside it, or Escape, closes it.
160
+
161
+ ## The tab strip
162
+
163
+ 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
164
+ 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
165
+ lists the tabs that do not fit, with a word for any that is not running as it should ("stopped", "can't reach"). Pick
166
+ 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
167
+ canvas.
168
+
169
+ **Its badge.** Each canvas's tab shows an orange count of what needs you (Marver's questions, captures to review, runs
170
+ that failed or stalled), else a blue dot when frames are new since you looked, else a shimmer while an agent works,
171
+ and a teal dot while a Jam session runs. While Home is open the tabs drop their counts, dots and shimmer: Home already
172
+ shows them. [What the marks mean](boards-and-folders.md#what-is-new-what-needs-you).
173
+
174
+ **Its menu.** Right-click a tab for its Marver menu, with icons like the sidebar's:
175
+
176
+ - a canvas on this Mac: Open in browser, Reveal in Finder, Copy local link, Mark all as seen and, with Marver 0.31 or
177
+ later, Resolve all comments (every open conversation on that canvas, never what Jam is working on, with Undo);
178
+ - a shared canvas: Open in browser, Copy link, Reload, Force reload;
179
+ - every tab: Close tab.
180
+
181
+ The ContextMenu key or ⇧F10 opens it from the keyboard. » opens the same kind of menu, one row per hidden tab.
182
+
183
+ **Moving the window.** Drag the strip where it is empty. However many tabs you have, the strip keeps at least 40 px
184
+ empty before its right end, or before a message showing there, so there is always somewhere to grab: the tabs shrink
185
+ and move behind » a little sooner instead.
186
+
187
+ The strip and Home follow Reduce Transparency and Increase Contrast, and show a clear focus ring when you use the
188
+ keyboard.
189
+
190
+ ## Hide UI in play
191
+
192
+ In play, prototype, slides or focus mode, `h` (Hide UI) takes the whole window: the tab strip and the window's buttons
193
+ go with Marver's own controls, and the stage grows into the room they leave. A thin band along the top, 16 px and
194
+ invisible, still drags the window. Everything comes back with:
195
+
196
+ - `h` again;
197
+ - Escape, which leaves play (it first cancels a comment you are writing or the laser);
198
+ - leaving play any other way: the strip comes back, and the canvas keeps its controls hidden until you press `h`;
199
+ - switching tabs (⌘1 to ⌘9, say): coming back, everything shows.
200
+
201
+ On a board locked to play, Escape shows everything again. On the canvas, Hide UI hides Marver's controls and keeps the
202
+ strip, which is how you move between canvases; a shared canvas's tab keeps the strip too. This needs app 1.2 and a
203
+ 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
204
 
114
205
  ## What it asks, and when
115
206
 
@@ -127,6 +218,12 @@ Updates…** checks now and answers in the strip: "Marver 1.0.0 is up to date",
127
218
  offline" or "Couldn't check for updates · Try again later". While it works, the item reads Checking for Updates… or
128
219
  Downloading Update….
129
220
 
221
+ **Settings shows it too** (Marver > Settings…, its Updates group): Marver and its version, whether it is up to date and
222
+ when it last checked, with Check for updates; "Checking for updates…" and "Downloading the update…" while it works
223
+ (Marver's updater gives no sizes); once one is ready, "What's new in 1.2.1" with its highlights, Release notes and
224
+ Restart to update. **Download updates automatically** (on by default; `autoUpdate` in `config.json`) turned off,
225
+ Marver checks only when you ask.
226
+
130
227
  **When an update is ready**, the strip says "1.0.1 is ready" with **Restart to Update** (its tooltip is the first line
131
228
  of what changed), and the Marver menu reads Restart to Install Update. Two ways to install it:
132
229
 
@@ -140,7 +237,7 @@ of what changed), and the Marver menu reads Restart to Install Update. Two ways
140
237
 
141
238
  **After an update, Marver opens as it does after a quit.** With Settings' "Reopen tabs at launch" on (the default),
142
239
  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
240
+ on Home and every running canvas still gets its tab. Shared canvases do not come back in tabs (Home's Shared with you
144
241
  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
242
  a scroll position, does not come back. The first launch after says "Updated to 1.0.1", once.
146
243
 
@@ -211,7 +308,9 @@ and roughly when, and attach the file.
211
308
  Marver keeps its settings and its state in `~/.marver/`, beside the files `marver dev` keeps there. At every launch
212
309
  the app writes a `README.md` in it, for you and your coding agent: every file, every setting, and the rules for
213
310
  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.
311
+ `theme.json`: Updates, Appearance (System, Light or Dark; D switches light and dark there and on Home), Tabs, Notices
312
+ and Performance, each row with its key's name. A file that does not apply shows at the top of Settings, with what is
313
+ wrong and the file's text; the app keeps the last good one meanwhile. 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
314
 
216
315
  ## Uninstalling
217
316
 
@@ -91,14 +91,16 @@ every frame reads lights every frame; **Mark all as seen** on the board clears t
91
91
 
92
92
  "Looked at" means you selected it, opened it from the sidebar or a link, opened it in focus or play,
93
93
  kept it on screen at a readable zoom (50 % or more) for two seconds, or chose **Mark all as seen** on
94
- a scene, board or folder - for the version on screen: a change still loading (or behind **Update** in
94
+ a scene, board or folder (**Mark as seen** on one frame's row, 0.33) - for the version on screen: a change still loading (or behind **Update** in
95
95
  focus or play) stays new until its new version shows, and a look you made while it loaded counts as
96
96
  soon as it does.
97
97
 
98
98
  **Resolve all comments** sits beside every **Mark all as seen** - a board's, a folder's, a scene's,
99
99
  and the Mac app's tab menu - for when the bubbles are noise (0.31). It resolves what that row shows,
100
100
  never a log: a board's every open thread on the frames it shows, a folder's over all its boards and
101
- sub-folders, a scene's on its frames, the tab's every open thread on the canvas. It is the same as
101
+ sub-folders, a scene's on its frames, the tab's every open thread on the canvas. A frame's own row in
102
+ the sidebar has the pair too (0.33), each only when there is something to do: **Mark as seen** while it
103
+ is new, **Resolve comments** while a conversation on it is open. It is the same as
102
104
  resolving each one by hand - Jam's questions, reviews and failed runs on them are finished - except
103
105
  live work: a thread Jam is queued or working on is left open and counted ("2 left open: work in
104
106
  progress"). The notice says how many, with **Undo**: it reopens each thread nothing happened in since - no
@@ -118,8 +120,10 @@ them, and the open conversations per board - for you, or for your agent at the s
118
120
  **In the Mac app** (0.3, with Marver 0.29), each canvas's tab sums this up, even while it is hidden: an
119
121
  orange count of what needs you - Marver's questions, captures to review, runs that failed or stalled -
120
122
  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
123
+ dot while a Jam session runs; while Home is open the tabs drop them: Home shows them. Its right-click menu holds
124
+ **Resolve all comments** beside **Mark all as seen** for a canvas on Marver 0.31 or later. Home's card says the same
125
+ in words ("2 questions on Checkout", "3 new frames to look at"), and with Marver 0.32 (app 1.2) which board an agent
126
+ 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
127
  Dock counts them all. Clicking a notice opens what it names where you can see it, on its board: a question
124
128
  in its thread on the frame (Play left and hidden pins shown for it), or in a panel with a field to answer
125
129
  when no frame on the board holds it; a review in its review; a failed run with Retry in view, a stalled
@@ -256,7 +260,8 @@ confirmed.
256
260
  **An agent at work.** While an agent works on a board's frames (`marver work start`, or a Live Jam
257
261
  job), that board's icon in the sidebar turns accent blue with a highlight sweeping across it - the
258
262
  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.
263
+ 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
264
+ working on <board> · N min", counted from when the work began: a Jam run waiting for its turn does not count.
260
265
 
261
266
  ## Starting points
262
267
 
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.33.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,
@@ -37,7 +37,7 @@ import { bootSettled, dismissShow, goNow, showTarget, useShowNotice } from './sh
37
37
  import { newerVersion } from '../../shared/deep-link.ts'
38
38
  import { useNotes } from './notes.ts'
39
39
  import { contentOnly } from '../../shared/frames.ts'
40
- import { nextToLook } from '../../shared/marks.ts'
40
+ import { isNew, nextToLook } from '../../shared/marks.ts'
41
41
  import { asksNow, Bubble, MarkedRow, markSeenFrom, resolveAllFrom, useRollup, useSeenOnScreen } from './marks-ui.tsx'
42
42
  import { CommentButton, DevicePicker, HideUIButton, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
43
43
 
@@ -1104,6 +1104,10 @@ export function App() {
1104
1104
  { label: 'Copy path', icon: <SignpostIcon size={15} />, onClick: () => { recordCopy('path', fr.id); copyToClipboard(framePath(useStore.getState().board, fr), 'path copied', cmd('copy-path', { via: 'context', in: 'shell', frame: fr.id })) } },
1105
1105
  // the Not on a board view (spec 26): put the frame where it belongs
1106
1106
  ...(useStore.getState().board === UNPLACED ? [{ label: 'Add to board…', icon: <PlusIcon size={15} />, panel: (close: () => void) => <AddToBoard frame={fr.id} close={close} /> }] : []),
1107
+ // the scene row's two, for one frame (0.33) - shown only when there is something to do: its blue dot,
1108
+ // or an open thread on it (one whose first comment was deleted counts: replay keeps it only while replies survive)
1109
+ ...(!PUBLISHED && isNew(useStore.getState().marks, fr.id) ? [{ label: 'Mark as seen', icon: <CheckIcon size={15} />, onClick: () => markSeenFrom({ via: 'context', in: 'shell', frame: fr.id }, [fr.id]) }] : []),
1110
+ ...(!PUBLISHED && useComments.getState().threads.some((t) => t.frame === fr.id && !t.resolved) ? [{ label: 'Resolve comments', icon: <CheckSquareOffsetIcon size={15} />, onClick: () => void resolveAllFrom({ via: 'context', in: 'shell', frame: fr.id }, { frame: fr.id }) }] : []),
1107
1111
  ]
1108
1112
  const seen = new Set<string>()
1109
1113
  const rows: ReactNode[] = []
@@ -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
+ }