@marver-design/marver 0.30.1 → 0.31.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.
- package/CHANGELOG.md +58 -0
- package/README.md +11 -7
- package/dist/{anchor-check-Bv4o-R2T.mjs → anchor-check-B92s9tVv.mjs} +1 -1
- package/dist/{board-tree-BXR8dw4b.mjs → board-tree-DGj0HhEE.mjs} +6 -2
- package/dist/{boards-EH2onUXM.mjs → boards-Cim1GTKc.mjs} +32 -2
- package/dist/{boards-BeWtjGUM.mjs → boards-OlAhZ87x.mjs} +7 -7
- package/dist/{build-zWGXSzly.mjs → build-BNssmbqd.mjs} +14 -17
- package/dist/{capture-DEtM4qm5.mjs → capture-HaS-1or8.mjs} +1 -1
- package/dist/cli.mjs +38 -20
- package/dist/{collab-BEAcXrBb.mjs → collab-D2NcrOB8.mjs} +53 -14
- package/dist/comment-actions-Bxf9Ld4g.mjs +351 -0
- package/dist/{comments-XNhMmSSu.mjs → comments-BakJQwaf.mjs} +85 -10
- package/dist/config-B0YcFtqS.mjs +510 -0
- package/dist/{context-BUnFiyA3.mjs → context-Cj2TcC0H.mjs} +3 -3
- package/dist/{daemon-CChgWJNq.mjs → daemon-MxoEQajX.mjs} +222 -23
- package/dist/deep-link-DYtuT740.mjs +163 -0
- package/dist/{dev-DOgIITpT.mjs → dev-BBZe_brH.mjs} +23 -16
- package/dist/devices-uJZ2inMq.mjs +155 -0
- package/dist/{events-CLH4ijKP.mjs → events-Dieo1482.mjs} +49 -4
- package/dist/{init-CYlFaRzG.mjs → init-BgusplYn.mjs} +40 -10
- package/dist/{jam-Cj5gBvwD.mjs → jam-CkuLL8A8.mjs} +1 -1
- package/dist/{link-BFFRgrMt.mjs → link-Cmt9Xy4X.mjs} +54 -7
- package/dist/{logo-CXY-1yrn.mjs → logo-C9s7-Cy9.mjs} +89 -66
- package/dist/{ls-NqmePKOf.mjs → ls-DGVIW-Io.mjs} +1 -1
- package/dist/{manifest-DPZ3WNg_.mjs → manifest-CK8Qh4Nq.mjs} +255 -13
- package/dist/{marks-BnNANic9.mjs → marks-C8oX8kbE.mjs} +3 -3
- package/dist/{marks-DBp3h1Mc.mjs → marks-Dt-5JXCp.mjs} +18 -5
- package/dist/{marver-id-gate-vBLb_Icb.mjs → marver-id-gate-BAeuMeaU.mjs} +11 -7
- package/dist/md-B9_13Q0R.mjs +105 -0
- package/dist/notes-CRAX4wgk.mjs +148 -0
- package/dist/own-C8Mq0Hnf.mjs +128 -0
- package/dist/pdf-0m721FFn.mjs +117 -0
- package/dist/pdf-CZENT6t3.mjs +2299 -0
- package/dist/{perf-BCxAo0IS.mjs → perf-BB0XNt1M.mjs} +1 -1
- package/dist/{perf-6MOTHxay.mjs → perf-CIMijND6.mjs} +5 -5
- package/dist/{plugin-CFWBcAba.mjs → plugin-CL8_wL7a.mjs} +460 -83
- package/dist/{poster-DPPpQiva.mjs → poster-B7uSjlEP.mjs} +1 -1
- package/dist/{profile-B1FKOM1e.mjs → profile-cdmSer1k.mjs} +1 -1
- package/dist/{publish-bakes-_Zx8crP3.mjs → publish-bakes-BjgDNeyS.mjs} +3 -3
- package/dist/{queue-DeSQm24g.mjs → queue-BLLfdlDw.mjs} +156 -11
- package/dist/{recover-mDUVsnPd.mjs → recover-ByuFQOF9.mjs} +2 -2
- package/dist/{serve-DQv3Ti6X.mjs → serve-kcF6-H8V.mjs} +4 -4
- package/dist/{session-VDJfXEEm.mjs → session-DBF-nQvq.mjs} +29 -3
- package/dist/{share-Bu_kuOKL.mjs → share-CS2mg27O.mjs} +1 -1
- package/dist/{shot-d4h_hJi9.mjs → shot-BqwkdtKn.mjs} +4 -4
- package/dist/{shot-DBWN8hPP.mjs → shot-D2TQGo2V.mjs} +1 -1
- package/dist/show-B1u3DiJw.mjs +101 -0
- package/dist/{sizes-wjXDev3b.mjs → sizes-BckcL4Zz.mjs} +1 -1
- package/dist/{slots-Dn4Onb0V.mjs → slots-BOcfIqxy.mjs} +15 -3
- package/dist/{summary-Y8MY1Wuc.mjs → summary-cPmRDGpX.mjs} +1 -1
- package/dist/{sync-CMozOwZ0.mjs → sync-BNWwh8OF.mjs} +205 -7
- package/dist/{work-BYWD_1Zf.mjs → work-DRdzXPvg.mjs} +3 -3
- package/dist/{work-DJxH7cCX.mjs → work-Nv-n2_Un.mjs} +1 -1
- package/docs/app.md +49 -0
- package/docs/boards-and-folders.md +37 -6
- package/docs/jam-session.md +5 -0
- package/docs/live-jam.md +9 -0
- package/docs/pdf.md +108 -0
- package/docs/publish.md +9 -9
- package/docs/sharing.md +11 -0
- package/docs/slides.md +9 -0
- package/package.json +3 -1
- package/src/client/content/index.tsx +4 -2
- package/src/client/frame-host/main.tsx +3 -0
- package/src/client/shell/App.tsx +71 -24
- package/src/client/shell/BoardList.tsx +16 -7
- package/src/client/shell/Comments.tsx +77 -16
- package/src/client/shell/Play.tsx +24 -22
- package/src/client/shell/Toolbar.tsx +4 -3
- package/src/client/shell/app-bridge.ts +32 -5
- package/src/client/shell/canvas/Canvas.tsx +30 -8
- package/src/client/shell/canvas/FrameNode.tsx +3 -1
- package/src/client/shell/canvas/ctl.ts +16 -0
- package/src/client/shell/commands.ts +20 -0
- package/src/client/shell/comments-store.ts +81 -2
- package/src/client/shell/devices.tsx +42 -0
- package/src/client/shell/goto.ts +56 -9
- package/src/client/shell/icons.tsx +11 -4
- package/src/client/shell/jam-lines.ts +5 -3
- package/src/client/shell/jam-panel.tsx +17 -5
- package/src/client/shell/marks-ui.tsx +54 -0
- package/src/client/shell/notes.ts +21 -0
- package/src/client/shell/pdf-export.tsx +154 -0
- package/src/client/shell/pdf-notes.ts +20 -0
- package/src/client/shell/show.ts +250 -0
- package/src/client/shell/store.ts +23 -38
- package/src/client/shell/styles.css +43 -0
- package/src/shared/app-api.ts +49 -4
- package/src/shared/auto-place.ts +32 -0
- package/src/shared/board-tree.ts +3 -0
- package/src/shared/board-types.ts +6 -2
- package/src/shared/deep-link.ts +212 -0
- package/src/shared/devices.ts +89 -0
- package/src/shared/events.ts +48 -5
- package/src/shared/export-plan.ts +98 -0
- package/templates/AGENTS-embedded.md +76 -12
- package/templates/AGENTS-studio.md +76 -12
- package/templates/instructions/boards.md +6 -5
- package/templates/instructions/configure.md +32 -2
- package/templates/instructions/iterate.md +8 -0
- package/templates/instructions/jam.md +9 -0
- package/templates/instructions/publish.md +14 -4
- package/templates/instructions/review.md +4 -0
- package/templates/instructions/slides.md +67 -1
- package/templates/instructions/welcome.md +9 -5
- package/templates/playbooks/publish-canvas/PLAYBOOK.md +1 -1
- package/dist/config-BezZTiov.mjs +0 -182
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Spec 31 Part D: the one contract for showing the human a place on a canvas - pure, no DOM, no Node, so the CLI,
|
|
3
|
+
* the dev server, the shell and the Mac app read it with one rule.
|
|
4
|
+
*
|
|
5
|
+
* - **A show target** (`ShowTarget`) is the hash's own targets on one board: `n` node keys, `f` frame ids, `s` scenes,
|
|
6
|
+
* `c` one comment thread. Node keys stay node keys (selecting one copy of a frame never selects every copy), and
|
|
7
|
+
* every value is checked against the hash grammar's characters - never a raw hash, never a URL, never script.
|
|
8
|
+
* - **The link hash** a target travels as: `#/b/<board>` and only the `f`, `s`, `n`, `c` query keys, each once, each
|
|
9
|
+
* value of the allowed characters (`targetFromHash` refuses anything else whole; `hashOfTarget` writes it back).
|
|
10
|
+
* - **A deep link** into the Mac app: `marver://open?ws=<folder>&to=<hash>[&port=<p>]`, both values written with
|
|
11
|
+
* `URLSearchParams` (so the hash's own `#`, `?` and `&` are percent-encoded inside `to`), 2 KB at most. `ws` is the
|
|
12
|
+
* canvas's folder (the app realpaths it and binds it to a running canvas); `port` is a hint the app uses only when
|
|
13
|
+
* that port's canvas has the same folder; a `to` that is not the grammar is dropped (the canvas opens on its default
|
|
14
|
+
* board), never the link.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
export const DEEP_LINK_SCHEME = 'marver'
|
|
18
|
+
/** The longest deep link either side takes. */
|
|
19
|
+
export const DEEP_LINK_MAX = 2048
|
|
20
|
+
/** The most values one key carries. */
|
|
21
|
+
export const TARGET_LIST_MAX = 64
|
|
22
|
+
|
|
23
|
+
export interface ShowTarget {
|
|
24
|
+
board: string
|
|
25
|
+
/** node keys: exactly those nodes */
|
|
26
|
+
n?: string[]
|
|
27
|
+
/** frame ids: every node showing them */
|
|
28
|
+
f?: string[]
|
|
29
|
+
/** scenes: every frame of them */
|
|
30
|
+
s?: string[]
|
|
31
|
+
/** one comment thread, opened */
|
|
32
|
+
c?: string
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** The board-name grammar (shared/board-tree.ts BOARD_NAME, bounded) and the Not on a board view. */
|
|
36
|
+
const BOARD = /^[a-z0-9][a-z0-9-]{0,63}$/
|
|
37
|
+
export const UNPLACED_BOARD = '~unplaced'
|
|
38
|
+
const FRAME = /^[\w./-]{1,200}$/
|
|
39
|
+
const SCENE = /^[\w.-]{1,120}$/
|
|
40
|
+
/** a node key is the shell's: `<frame id>@<width>`, or a board file's own (`n-one`) */
|
|
41
|
+
const NODE = /^[\w./@:-]{1,200}$/
|
|
42
|
+
const THREAD = /^[\w-]{1,128}$/
|
|
43
|
+
|
|
44
|
+
const okBoard = (b: unknown): b is string => typeof b === 'string' && (BOARD.test(b) || b === UNPLACED_BOARD)
|
|
45
|
+
const okIn = (re: RegExp) => (v: unknown): v is string => typeof v === 'string' && re.test(v) && !v.includes('..')
|
|
46
|
+
const okFrame = okIn(FRAME), okScene = okIn(SCENE), okNode = okIn(NODE), okThread = okIn(THREAD)
|
|
47
|
+
const KEYS = { n: okNode, f: okFrame, s: okScene } as const
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* A show target off the wire (pure): `board` a board name, `n`/`f`/`s` arrays of their grammar's values (at most
|
|
51
|
+
* `TARGET_LIST_MAX`, de-duplicated, empty ones left out), `c` a thread id. Unknown fields are stripped; a known one of
|
|
52
|
+
* the wrong type or any value off its grammar refuses the whole (null).
|
|
53
|
+
*/
|
|
54
|
+
export function checkShowTarget(v: unknown): ShowTarget | null {
|
|
55
|
+
if (!v || typeof v !== 'object' || Array.isArray(v)) return null
|
|
56
|
+
const r = v as Record<string, unknown>
|
|
57
|
+
if (!okBoard(r.board)) return null
|
|
58
|
+
const out: ShowTarget = { board: r.board }
|
|
59
|
+
for (const k of ['n', 'f', 's'] as const) {
|
|
60
|
+
if (r[k] === undefined) continue
|
|
61
|
+
const list = r[k]
|
|
62
|
+
if (!Array.isArray(list) || list.length > TARGET_LIST_MAX || !list.every(KEYS[k])) return null
|
|
63
|
+
const uniq = [...new Set(list as string[])]
|
|
64
|
+
if (uniq.length) out[k] = uniq
|
|
65
|
+
}
|
|
66
|
+
if (r.c !== undefined) {
|
|
67
|
+
if (!okThread(r.c)) return null
|
|
68
|
+
out.c = r.c
|
|
69
|
+
}
|
|
70
|
+
return out
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* The link hash's target (pure): `#/b/<board>` with only `f`, `s`, `n`, `c`, each at most once, every value of its
|
|
75
|
+
* grammar; anything else - another route, another key, a repeated key, a bad value, more than 2 KB - is null.
|
|
76
|
+
*/
|
|
77
|
+
export function targetFromHash(hash: unknown): ShowTarget | null {
|
|
78
|
+
if (typeof hash !== 'string' || hash.length > DEEP_LINK_MAX) return null
|
|
79
|
+
const m = /^#\/b\/([^?#/]+)(?:\?([^#]*))?$/.exec(hash)
|
|
80
|
+
if (!m) return null
|
|
81
|
+
let board: string
|
|
82
|
+
try { board = decodeURIComponent(m[1]!) } catch { return null }
|
|
83
|
+
if (!okBoard(board)) return null
|
|
84
|
+
const raw: Record<string, unknown> = { board }
|
|
85
|
+
if (m[2] !== undefined && m[2] !== '') {
|
|
86
|
+
let params: URLSearchParams
|
|
87
|
+
try { params = new URLSearchParams(m[2]) } catch { return null }
|
|
88
|
+
const seen = new Set<string>()
|
|
89
|
+
for (const [k, v] of params) {
|
|
90
|
+
if (seen.has(k) || !['n', 'f', 's', 'c'].includes(k)) return null
|
|
91
|
+
seen.add(k)
|
|
92
|
+
if (k === 'c') raw.c = v
|
|
93
|
+
else raw[k] = v.split(',').map((x) => x.trim()).filter(Boolean)
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
return checkShowTarget(raw)
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** The target as the link hash (pure): the board, then `n`, `f`, `s`, `c` - every value already of URL-safe characters. */
|
|
100
|
+
export function hashOfTarget(t: ShowTarget): string {
|
|
101
|
+
const q = [
|
|
102
|
+
t.n?.length ? `n=${t.n.join(',')}` : '',
|
|
103
|
+
t.f?.length ? `f=${t.f.join(',')}` : '',
|
|
104
|
+
t.s?.length ? `s=${t.s.join(',')}` : '',
|
|
105
|
+
t.c ? `c=${t.c}` : '',
|
|
106
|
+
].filter(Boolean).join('&')
|
|
107
|
+
return `#/b/${t.board}${q ? `?${q}` : ''}`
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
export interface DeepLink {
|
|
111
|
+
/** the canvas's folder, as the link wrote it (absolute; the app realpaths it) */
|
|
112
|
+
ws: string
|
|
113
|
+
/** the place, checked; null when the link named none or one off the grammar (the canvas's default board) */
|
|
114
|
+
to: ShowTarget | null
|
|
115
|
+
/** a hint: used only when that port's canvas has the same folder */
|
|
116
|
+
port?: number
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
const CONTROL = /[\u0000-\u001f\u007f]/
|
|
120
|
+
|
|
121
|
+
/** `marver://open?ws=<folder>&to=<hash>[&port=<p>]`, written with URLSearchParams; null past 2 KB or with a bad folder. */
|
|
122
|
+
export function buildDeepLink(o: { ws: string; to?: string; port?: number }): string | null {
|
|
123
|
+
if (!o.ws.startsWith('/') || CONTROL.test(o.ws)) return null
|
|
124
|
+
const p = new URLSearchParams({ ws: o.ws })
|
|
125
|
+
if (o.to) p.set('to', o.to)
|
|
126
|
+
if (o.port !== undefined && Number.isInteger(o.port) && o.port > 0 && o.port < 65536) p.set('port', String(o.port))
|
|
127
|
+
const link = `${DEEP_LINK_SCHEME}://open?${p}`
|
|
128
|
+
return link.length <= DEEP_LINK_MAX ? link : null
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* A deep link as the app hears it (pure): `marver://open` and nothing else on its path, at most 2 KB, only `ws`, `to`
|
|
133
|
+
* and `port` (each once), `ws` an absolute path with no control character (1 KB at most). A `to` off the grammar is
|
|
134
|
+
* dropped to null; a `port` that is not a port is ignored. Anything else is null: nothing opens.
|
|
135
|
+
*/
|
|
136
|
+
export function parseDeepLink(raw: unknown): DeepLink | null {
|
|
137
|
+
if (typeof raw !== 'string' || raw.length > DEEP_LINK_MAX) return null
|
|
138
|
+
let u: URL
|
|
139
|
+
try { u = new URL(raw) } catch { return null }
|
|
140
|
+
if (u.protocol !== `${DEEP_LINK_SCHEME}:` || u.host !== 'open' || (u.pathname !== '' && u.pathname !== '/') || u.username || u.password || u.hash) return null
|
|
141
|
+
const seen = new Set<string>()
|
|
142
|
+
for (const k of u.searchParams.keys()) {
|
|
143
|
+
if (seen.has(k) || !['ws', 'to', 'port'].includes(k)) return null
|
|
144
|
+
seen.add(k)
|
|
145
|
+
}
|
|
146
|
+
const ws = u.searchParams.get('ws')
|
|
147
|
+
if (!ws || !ws.startsWith('/') || ws.length > 1024 || CONTROL.test(ws)) return null
|
|
148
|
+
const to = u.searchParams.has('to') ? targetFromHash(u.searchParams.get('to')) : null
|
|
149
|
+
const ps = u.searchParams.get('port')
|
|
150
|
+
const port = ps !== null && /^\d{1,5}$/.test(ps) && Number(ps) > 0 && Number(ps) < 65536 ? Number(ps) : undefined
|
|
151
|
+
return { ws, to, ...(port !== undefined ? { port } : {}) }
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/** The first `marver://` argument of a command line (a second instance's argv), or null. */
|
|
155
|
+
export function deepLinkArg(argv: readonly unknown[]): string | null {
|
|
156
|
+
for (const a of argv) if (typeof a === 'string' && a.toLowerCase().startsWith(`${DEEP_LINK_SCHEME}://`)) return a
|
|
157
|
+
return null
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** Strictly newer x.y.z (pure): anything not three numbers compares false. */
|
|
161
|
+
export function newerVersion(a: unknown, b: unknown): boolean {
|
|
162
|
+
if (typeof a !== 'string' || typeof b !== 'string') return false
|
|
163
|
+
const pa = /^(\d+)\.(\d+)\.(\d+)$/.exec(a), pb = /^(\d+)\.(\d+)\.(\d+)$/.exec(b)
|
|
164
|
+
if (!pa || !pb) return false
|
|
165
|
+
for (let i = 1; i <= 3; i++) {
|
|
166
|
+
const x = Number(pa[i]), y = Number(pb[i])
|
|
167
|
+
if (x !== y) return x > y
|
|
168
|
+
}
|
|
169
|
+
return false
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
// ---- app-live.json: knowing when the app is in use (Part D2) ---------------------------------------------------
|
|
173
|
+
|
|
174
|
+
/** `<MARVER_HOME>/state/app-live.json`: the Mac app's word that it runs, rewritten every `APP_LIVE_EVERY_MS`. */
|
|
175
|
+
export const APP_LIVE_FILE = 'app-live.json'
|
|
176
|
+
export const APP_LIVE_EVERY_MS = 30_000
|
|
177
|
+
/** Older than this, the file is stale: the app is not in use (it quit without removing it, it hangs). */
|
|
178
|
+
export const APP_LIVE_FRESH_MS = 90_000
|
|
179
|
+
|
|
180
|
+
export interface AppLiveFile {
|
|
181
|
+
v: 1
|
|
182
|
+
pid: number
|
|
183
|
+
version: string
|
|
184
|
+
/** 1 when this app takes `marver://` links (an app that registered the scheme); absent otherwise */
|
|
185
|
+
scheme?: 1
|
|
186
|
+
/** when it was written, ms */
|
|
187
|
+
at: number
|
|
188
|
+
/** the real folders of the canvases open in its tabs */
|
|
189
|
+
workspaces: string[]
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** The file's shape (pure), or null. */
|
|
193
|
+
export function checkAppLive(v: unknown): AppLiveFile | null {
|
|
194
|
+
const r = v as Partial<AppLiveFile> | null
|
|
195
|
+
if (!r || typeof r !== 'object' || r.v !== 1) return null
|
|
196
|
+
if (!Number.isInteger(r.pid) || (r.pid as number) < 1 || typeof r.version !== 'string' || r.version.length > 32) return null
|
|
197
|
+
if (typeof r.at !== 'number' || !Number.isFinite(r.at)) return null
|
|
198
|
+
if (!Array.isArray(r.workspaces) || r.workspaces.length > 256 || !r.workspaces.every((w) => typeof w === 'string' && w.startsWith('/') && w.length <= 4096)) return null
|
|
199
|
+
return { v: 1, pid: r.pid as number, version: r.version, at: r.at, workspaces: [...r.workspaces], ...(r.scheme === 1 ? { scheme: 1 as const } : {}) }
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* Whether `marver link` gives the app's link for the canvas in `root` (pure): the file names a pid that runs, was
|
|
204
|
+
* written under 90 s ago (a stamp from the future is stale too), takes the scheme, and has this canvas's folder open.
|
|
205
|
+
* Anything else - no file, an older app, a stale file, the canvas not open in a tab - is the localhost link.
|
|
206
|
+
*/
|
|
207
|
+
export function appTakesLink(file: AppLiveFile | null, root: string, now: number, alive: (pid: number) => boolean): boolean {
|
|
208
|
+
if (!file || file.scheme !== 1) return false
|
|
209
|
+
if (file.at > now + 5_000 || now - file.at > APP_LIVE_FRESH_MS) return false
|
|
210
|
+
if (!file.workspaces.includes(root)) return false
|
|
211
|
+
return alive(file.pid)
|
|
212
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Your own breakpoints (spec 31 Part F): what a device shows as - its glyph and its label. Pure, shared by the
|
|
3
|
+
* server (which resolves design/config.ts's `viewports.<name>.icon` and `.label` once, at load) and the shell (which
|
|
4
|
+
* falls back to the same rules for a device name it has no resolved look for, e.g. a Jam step recorded earlier).
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
/** The built-in device glyphs, as `viewports.<name>.icon` may name them (a `-landscape` suffix rotates one). */
|
|
8
|
+
export const DEVICE_GLYPHS = ['mobile', 'tablet', 'laptop', 'monitor', 'tv', 'watch', 'desktop', 'ereader'] as const
|
|
9
|
+
export type DeviceGlyph = typeof DEVICE_GLYPHS[number]
|
|
10
|
+
|
|
11
|
+
/** How a device shows: its label, and a built-in glyph (null: the generic devices glyph) turned a quarter for a
|
|
12
|
+
* landscape device - or `mask`, a sanitized SVG as a `data:image/svg+xml;base64,` URI drawn as a CSS mask in the
|
|
13
|
+
* ink (never inline DOM). */
|
|
14
|
+
export interface DeviceLook { label: string; glyph: DeviceGlyph | null; rotate: boolean; mask?: string }
|
|
15
|
+
|
|
16
|
+
/** The longest label a device carries. */
|
|
17
|
+
export const DEVICE_LABEL_MAX = 40
|
|
18
|
+
|
|
19
|
+
const words = (name: string): string[] => name.split(/[^A-Za-z0-9]+/).filter(Boolean)
|
|
20
|
+
const tokens = (name: string): string[] => words(name).map((w) => w.toLowerCase())
|
|
21
|
+
|
|
22
|
+
/** A `-landscape` device: the name says so (a word of its own). */
|
|
23
|
+
export const isLandscape = (name: string): boolean => tokens(name).includes('landscape')
|
|
24
|
+
|
|
25
|
+
/** The glyph a device's NAME suggests, or null (the generic devices glyph). Class words first (`pixel-tablet` is a
|
|
26
|
+
* tablet), then the brands. */
|
|
27
|
+
export function glyphFromName(name: string): DeviceGlyph | null {
|
|
28
|
+
const t = tokens(name)
|
|
29
|
+
const has = (...w: string[]) => t.some((x) => w.includes(x))
|
|
30
|
+
const starts = (p: string) => t.some((x) => x.startsWith(p))
|
|
31
|
+
// the class words: what a device IS beats whose it is
|
|
32
|
+
if (has('tablet')) return 'tablet'
|
|
33
|
+
if (has('laptop')) return 'laptop'
|
|
34
|
+
if (has('phone', 'mobile', 'smartphone')) return 'mobile'
|
|
35
|
+
if (has('monitor', 'desktop')) return 'monitor'
|
|
36
|
+
if (has('tv')) return 'tv'
|
|
37
|
+
if (has('watch')) return 'watch'
|
|
38
|
+
if (has('ereader')) return 'ereader'
|
|
39
|
+
// the brands and the models
|
|
40
|
+
if (starts('iphone') || has('android', 'pixel')) return 'mobile'
|
|
41
|
+
if (starts('ipad') || has('boox', 'kindle')) return 'tablet'
|
|
42
|
+
if (starts('macbook')) return 'laptop'
|
|
43
|
+
if (has('imac', 'studio')) return 'monitor'
|
|
44
|
+
return null
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Brand casing, by word: "ipad" -> "iPad", "tv" -> "TV". */
|
|
48
|
+
const BRAND: Record<string, string> = {
|
|
49
|
+
iphone: 'iPhone', ipad: 'iPad', imac: 'iMac', ipod: 'iPod', macbook: 'MacBook', mac: 'Mac', ios: 'iOS', ipados: 'iPadOS',
|
|
50
|
+
macos: 'macOS', watchos: 'watchOS', tvos: 'tvOS', visionos: 'visionOS', tv: 'TV', appletv: 'Apple TV', android: 'Android', pixel: 'Pixel',
|
|
51
|
+
galaxy: 'Galaxy', samsung: 'Samsung', kindle: 'Kindle', boox: 'Boox', kobo: 'Kobo', remarkable: 'reMarkable', surface: 'Surface',
|
|
52
|
+
chromebook: 'Chromebook', apple: 'Apple', google: 'Google', oneplus: 'OnePlus', xl: 'XL', hd: 'HD', uhd: 'UHD', fhd: 'FHD',
|
|
53
|
+
qhd: 'QHD', '4k': '4K', '5k': '5K', '6k': '6K', '8k': '8K', xdr: 'XDR', oled: 'OLED', se: 'SE', xr: 'XR', xs: 'XS', ui: 'UI',
|
|
54
|
+
}
|
|
55
|
+
/** A model's suffix words, capitalised after a brand: "iphone-15-pro-max" -> "iPhone 15 Pro Max". */
|
|
56
|
+
const MODEL = new Set(['pro', 'max', 'plus', 'mini', 'air', 'ultra', 'fold', 'flip', 'lite', 'studio', 'display', 'note'])
|
|
57
|
+
/** Brands that start a model name, so the words after them are its model words. */
|
|
58
|
+
const BRANDED = new Set(['iphone', 'ipad', 'imac', 'ipod', 'macbook', 'mac', 'pixel', 'galaxy', 'kindle', 'boox', 'kobo', 'remarkable', 'surface', 'chromebook', 'apple', 'google', 'samsung', 'oneplus', 'studio'])
|
|
59
|
+
|
|
60
|
+
/** A device's label from its NAME: the words humanized, brand casing kept ("ipad-landscape" -> "iPad landscape",
|
|
61
|
+
* "boox-full" -> "Boox full", "iphone-15-pro" -> "iPhone 15 Pro"). The first word starts capitalised, the rest stay
|
|
62
|
+
* as written; a word already carrying capitals keeps them ("myDevice" stays "myDevice"). */
|
|
63
|
+
export function labelFromName(name: string): string {
|
|
64
|
+
const ws = words(name)
|
|
65
|
+
if (!ws.length) return name
|
|
66
|
+
let branded = false
|
|
67
|
+
return ws.map((w, i) => {
|
|
68
|
+
const low = w.toLowerCase()
|
|
69
|
+
// a brand word with a model number glued on: "iphone15" -> "iPhone15", "ipad13" -> "iPad13"
|
|
70
|
+
const glued = /^([a-z]+)(\d+)$/.exec(low)
|
|
71
|
+
const brand = BRAND[low] ?? (glued && BRANDED.has(glued[1]) && BRAND[glued[1]] ? BRAND[glued[1]] + glued[2] : undefined)
|
|
72
|
+
const isBrand = BRANDED.has(low) || (!!glued && BRANDED.has(glued[1]))
|
|
73
|
+
const out = brand ?? (/[A-Z]/.test(w) ? w
|
|
74
|
+
: branded && MODEL.has(low) ? low[0].toUpperCase() + low.slice(1)
|
|
75
|
+
: i === 0 ? low[0].toUpperCase() + low.slice(1)
|
|
76
|
+
: low)
|
|
77
|
+
if (isBrand) branded = true
|
|
78
|
+
return out
|
|
79
|
+
}).join(' ')
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** A built-in glyph as `viewports.<name>.icon` names it, with its rotation - or null when the value is no glyph. */
|
|
83
|
+
export function parseGlyph(v: string): { glyph: DeviceGlyph; rotate: boolean } | null {
|
|
84
|
+
const m = /^([a-z]+)(-landscape)?$/.exec(v)
|
|
85
|
+
return m && (DEVICE_GLYPHS as readonly string[]).includes(m[1]) ? { glyph: m[1] as DeviceGlyph, rotate: !!m[2] } : null
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** A device's look from its name alone - the shell's fallback, and the server's for a device with no `icon`/`label`. */
|
|
89
|
+
export const lookFromName = (name: string): DeviceLook => ({ label: labelFromName(name), glyph: glyphFromName(name), rotate: isLandscape(name) })
|
package/src/shared/events.ts
CHANGED
|
@@ -5,7 +5,8 @@
|
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
7
|
// 'reanchor' (Live Jam): re-pin a thread to a new element after the agent moved it.
|
|
8
|
-
|
|
8
|
+
// 'delete' (0.31, spec 31 C.4): a terminal tombstone on one message - its author's only.
|
|
9
|
+
export type EventType = 'create' | 'reply' | 'edit' | 'resolve' | 'reopen' | 'react' | 'profile' | 'reanchor' | 'delete'
|
|
9
10
|
|
|
10
11
|
// Live Jam: provenance stamped by the daemon on agent-authored events (who orchestrated the change).
|
|
11
12
|
export interface AgentMeta { devUser?: string; harness?: string; model?: string; effort?: string; /** who ran it (spec 29b): the owner's session, a copy of it, or a fresh agent */ runner?: 'session' | 'fork' | 'fresh' }
|
|
@@ -49,6 +50,8 @@ export interface CommentEvent {
|
|
|
49
50
|
capture?: string
|
|
50
51
|
facts?: string
|
|
51
52
|
origin?: string // server-stamped 'local' on dev-owner writes; the daemon's owner-trigger key
|
|
53
|
+
/** resolve and reopen events (0.31, spec 31 B.3): the resolve-all operation that wrote it - what its Undo matches */
|
|
54
|
+
op?: string
|
|
52
55
|
}
|
|
53
56
|
|
|
54
57
|
export interface Thread {
|
|
@@ -66,7 +69,11 @@ export interface Thread {
|
|
|
66
69
|
asks?: boolean
|
|
67
70
|
capture?: string // a capture's comment (0.26)
|
|
68
71
|
facts?: string
|
|
69
|
-
|
|
72
|
+
/** the first comment was deleted (0.31): its replies stay under a "Comment deleted" placeholder - no body, author or mentions */
|
|
73
|
+
deleted?: true
|
|
74
|
+
/** when its words were last edited (0.31: "edited" is shown) - an edit that changes only a flag does not count */
|
|
75
|
+
edited?: number
|
|
76
|
+
replies: { id: string; author?: CommentEvent['author']; body?: string; ts: number; agent?: boolean; agentMeta?: AgentMeta; mentions?: Mention[]; asks?: boolean; alsoChanged?: string[]; edited?: number }[]
|
|
70
77
|
reactions: Record<string, string[]> // emoji -> author emails (toggle semantics)
|
|
71
78
|
}
|
|
72
79
|
|
|
@@ -82,10 +89,31 @@ export function diffEvents(mine: CommentEvent[], theirIds: Iterable<string>): Co
|
|
|
82
89
|
return mine.filter((e) => !have.has(e.id))
|
|
83
90
|
}
|
|
84
91
|
|
|
92
|
+
/** The messages (create or reply comment ids) a log's tombstones name (spec 31 C.4): terminal, whatever came
|
|
93
|
+
* before or after them. Every reader that turns a request into agent input filters by it, per message. */
|
|
94
|
+
export function deletedMessages(events: readonly CommentEvent[]): Set<string> {
|
|
95
|
+
const out = new Set<string>()
|
|
96
|
+
for (const e of events) if (e.type === 'delete' && typeof e.commentId === 'string' && e.commentId) out.add(e.commentId)
|
|
97
|
+
return out
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** An event as a browser may see it (spec 31 C.4): a create, reply or edit of a deleted message carries no words or
|
|
101
|
+
* mentions - the log keeps them (sync is by id), no transport to a page does. `gone`: deletedMessages of the log. */
|
|
102
|
+
export const withoutDeletedWords = (e: CommentEvent, gone: ReadonlySet<string>): CommentEvent =>
|
|
103
|
+
gone.size && (e.type === 'create' || e.type === 'reply' || e.type === 'edit') && !!e.commentId && gone.has(e.commentId) ? { ...e, body: '', mentions: undefined } : e
|
|
104
|
+
|
|
105
|
+
/** The copy a published page keeps of what it just sent (spec 31 C.2): its author wears the viewer's own opaque id, as
|
|
106
|
+
* the server's projection of it will - the echo is a duplicate by id and dropped, so without it a message just written
|
|
107
|
+
* would not be "mine" (no Edit, no Delete) until a reload. Never sent: the server assigns ids. */
|
|
108
|
+
export const asSentBy = (events: CommentEvent[], myId: string | undefined): CommentEvent[] =>
|
|
109
|
+
!myId ? events : events.map((e) => (e.author && !e.author.id ? { ...e, author: { ...e.author, id: myId } } : e))
|
|
110
|
+
|
|
85
111
|
/** Replay a board's events into current thread state. Deterministic: replay order is
|
|
86
112
|
* (ts, id) so two stores holding the same event SET always derive the same state.
|
|
87
113
|
* TWO passes - creates first, then everything else - so a reply whose author's clock
|
|
88
|
-
* ran ahead of the creator's still lands instead of being dropped forever.
|
|
114
|
+
* ran ahead of the creator's still lands instead of being dropped forever. Deletes (0.31)
|
|
115
|
+
* apply after both, whatever their time: a deleted reply is gone; a deleted first comment
|
|
116
|
+
* keeps its surviving replies under a placeholder, and with none the thread is gone. */
|
|
89
117
|
export function replay(events: CommentEvent[]): Thread[] {
|
|
90
118
|
const ordered = [...events].sort((a, b) => a.ts - b.ts || (a.id < b.id ? -1 : 1))
|
|
91
119
|
const threads = new Map<string, Thread>()
|
|
@@ -112,7 +140,7 @@ export function replay(events: CommentEvent[]): Thread[] {
|
|
|
112
140
|
if (!ev.commentId || (ev.body === undefined && ev.asks === undefined && ev.alsoChanged === undefined)) break
|
|
113
141
|
const m = threads.get(ev.commentId) ?? [...threads.values()].flatMap((th) => th.replies).find((r) => r.id === ev.commentId)
|
|
114
142
|
if (!m) break
|
|
115
|
-
if (ev.body !== undefined) m.body = ev.body
|
|
143
|
+
if (ev.body !== undefined) { if (ev.body !== m.body) m.edited = ev.ts; m.body = ev.body }
|
|
116
144
|
if (ev.asks !== undefined) m.asks = ev.asks
|
|
117
145
|
if (ev.alsoChanged !== undefined && !('replies' in m)) (m as { alsoChanged?: string[] }).alsoChanged = ev.alsoChanged // a reply's
|
|
118
146
|
break
|
|
@@ -152,7 +180,22 @@ export function replay(events: CommentEvent[]): Thread[] {
|
|
|
152
180
|
break
|
|
153
181
|
}
|
|
154
182
|
// 'profile' events update author snapshots at write time on the client - replay ignores them
|
|
183
|
+
// 'delete' events are applied below, after everything else
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
const gone = deletedMessages(ordered)
|
|
187
|
+
if (!gone.size) return [...threads.values()]
|
|
188
|
+
const out: Thread[] = []
|
|
189
|
+
for (const t of threads.values()) {
|
|
190
|
+
t.replies = t.replies.filter((r) => !gone.has(r.id))
|
|
191
|
+
if (gone.has(t.id)) {
|
|
192
|
+
if (!t.replies.length) continue
|
|
193
|
+
// the placeholder carries nothing of what was said, nor who said it
|
|
194
|
+
t.deleted = true
|
|
195
|
+
t.body = undefined; t.author = undefined; t.mentions = undefined; t.asks = undefined; t.edited = undefined
|
|
196
|
+
delete t.capture; delete t.facts
|
|
155
197
|
}
|
|
198
|
+
out.push(t)
|
|
156
199
|
}
|
|
157
|
-
return
|
|
200
|
+
return out
|
|
158
201
|
}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The export plan (spec 31 Part A #2): which frames a board prints, in which order, at which size and theme. One
|
|
3
|
+
* definition, read by the PDF (src/server/pdf.ts) and by Play (src/client/shell/Play.tsx), so a deck's pages and the
|
|
4
|
+
* stage never disagree.
|
|
5
|
+
*
|
|
6
|
+
* - a *slides* board (it plays as slides: its publish policy says `type: slides` or `open: slides`) prints its deck:
|
|
7
|
+
* slide frames in reading order (y, then x), deduped - `deckOrder`, the order slides mode plays;
|
|
8
|
+
* - any other board prints its nodes in the board's own order (Play's order), deduped, html frames included (Play
|
|
9
|
+
* cannot mount them on its stage; the PDF prints them from their own document);
|
|
10
|
+
* - a page is the size the stage shows: a `slide: true` frame's stage (`slideSize`) on any board, else the device Play
|
|
11
|
+
* picks for the node - the viewport whose width is the node's, else the frame's declared viewport, else the first -
|
|
12
|
+
* at that viewport's height;
|
|
13
|
+
* - its theme: the export's own when one is asked, else the node's, else the frame's, else light;
|
|
14
|
+
* - a node whose frame the manifest does not list is skipped, and named.
|
|
15
|
+
*
|
|
16
|
+
* Pure and dependency-free (beyond the two shared rules it composes), so the server, the shell and the tests import it.
|
|
17
|
+
*/
|
|
18
|
+
import { deckOrder, type OrderFrame, type OrderNode } from '../client/shell/play-order.ts'
|
|
19
|
+
import { slideSize } from '../client/const.ts'
|
|
20
|
+
|
|
21
|
+
export type Viewports = Record<string, { width: number; height: number }>
|
|
22
|
+
export interface PlanFrame extends OrderFrame { viewport?: string; theme?: string; title?: string; file?: string }
|
|
23
|
+
export interface PlanNode extends OrderNode {
|
|
24
|
+
/** the node's width on the board, when it has one - names the device Play shows it at */
|
|
25
|
+
w?: number
|
|
26
|
+
/** the node's own theme, as the person pinned it (`themeUser`), when there is one */
|
|
27
|
+
theme?: string
|
|
28
|
+
}
|
|
29
|
+
export interface PlanPage {
|
|
30
|
+
frame: string
|
|
31
|
+
kind: 'tsx' | 'html'
|
|
32
|
+
width: number
|
|
33
|
+
height: number
|
|
34
|
+
theme: string
|
|
35
|
+
/** the frame's title, else its id's last part made readable - a bookmark's name */
|
|
36
|
+
title: string
|
|
37
|
+
/** the viewport the page is printed at, for a non-slide frame */
|
|
38
|
+
device?: string
|
|
39
|
+
}
|
|
40
|
+
export interface Plan { pages: PlanPage[]; skipped: { frame: string; why: 'missing' | 'not a slide' }[] }
|
|
41
|
+
|
|
42
|
+
/** The device Play shows a node at (spec 31 #2): the viewport whose width is the node's, else the frame's declared
|
|
43
|
+
* viewport, else the first. Undefined only when the project has no viewport at all. */
|
|
44
|
+
export function presentDevice(node: { w?: number } | undefined, frame: { viewport?: string } | undefined, viewports: Viewports): string | undefined {
|
|
45
|
+
const names = Object.keys(viewports)
|
|
46
|
+
return (node?.w !== undefined ? names.find((v) => viewports[v].width === node.w) : undefined)
|
|
47
|
+
?? (frame?.viewport && viewports[frame.viewport] ? frame.viewport : names[0])
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** A board's frames in its own order, deduped, its missing ones skipped - Play's list (`html: false`, what its stage can
|
|
51
|
+
* mount) and the PDF's (`html: true`). */
|
|
52
|
+
export function boardOrder<N extends { frame: string; missing?: boolean }>(nodes: N[], frameOf: (n: N) => OrderFrame | undefined, o: { html: boolean }): N[] {
|
|
53
|
+
const seen = new Set<string>()
|
|
54
|
+
const out: N[] = []
|
|
55
|
+
for (const n of nodes) {
|
|
56
|
+
if (n.missing || seen.has(n.frame)) continue
|
|
57
|
+
const f = frameOf(n)
|
|
58
|
+
if (!f || (!o.html && f.kind !== 'tsx')) continue
|
|
59
|
+
seen.add(n.frame)
|
|
60
|
+
out.push(n)
|
|
61
|
+
}
|
|
62
|
+
return out
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** A frame's title, else its id's last part with spaces for dashes (as Play's pill names a frame). */
|
|
66
|
+
export const titleOf = (f: { id: string; title?: string }): string => f.title?.trim() || (f.id.split('/').pop() ?? f.id).replace(/-/g, ' ')
|
|
67
|
+
|
|
68
|
+
/** The plan for one board (spec 31 #2). `theme` is the export's own (`--theme`), when one was asked. */
|
|
69
|
+
export function exportPlan(o: { slides: boolean; nodes: PlanNode[]; frames: PlanFrame[]; viewports: Viewports; theme?: string }): Plan {
|
|
70
|
+
const byId = new Map(o.frames.map((f) => [f.id, f]))
|
|
71
|
+
const skipped: Plan['skipped'] = []
|
|
72
|
+
const seenMissing = new Set<string>()
|
|
73
|
+
for (const n of o.nodes) if (!byId.has(n.frame) && !seenMissing.has(n.frame)) { seenMissing.add(n.frame); skipped.push({ frame: n.frame, why: 'missing' }) }
|
|
74
|
+
const page = (f: PlanFrame, node: PlanNode | undefined): PlanPage | null => {
|
|
75
|
+
const theme = o.theme ?? node?.theme ?? f.theme ?? 'light'
|
|
76
|
+
const sl = slideSize(f, o.viewports)
|
|
77
|
+
if (sl) return { frame: f.id, kind: f.kind, width: sl.width, height: sl.height, theme, title: titleOf(f) }
|
|
78
|
+
const device = presentDevice(node, f, o.viewports)
|
|
79
|
+
const vp = device ? o.viewports[device] : undefined
|
|
80
|
+
if (!vp) return null
|
|
81
|
+
return { frame: f.id, kind: f.kind, width: vp.width, height: vp.height, theme, title: titleOf(f), device }
|
|
82
|
+
}
|
|
83
|
+
const pages: PlanPage[] = []
|
|
84
|
+
if (o.slides) {
|
|
85
|
+
const { deck, excluded } = deckOrder(o.nodes.map((n) => ({ ...n, missing: n.missing || !byId.has(n.frame) })), byId)
|
|
86
|
+
for (const id of excluded) skipped.push({ frame: id, why: 'not a slide' })
|
|
87
|
+
for (const id of deck) {
|
|
88
|
+
const p = page(byId.get(id)!, o.nodes.find((n) => n.frame === id))
|
|
89
|
+
if (p) pages.push(p)
|
|
90
|
+
}
|
|
91
|
+
} else {
|
|
92
|
+
for (const n of boardOrder(o.nodes, (x) => byId.get(x.frame), { html: true })) {
|
|
93
|
+
const p = page(byId.get(n.frame)!, n)
|
|
94
|
+
if (p) pages.push(p)
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
return { pages, skipped }
|
|
98
|
+
}
|
|
@@ -34,7 +34,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
|
|
|
34
34
|
| Phase | When | Read |
|
|
35
35
|
|---|---|---|
|
|
36
36
|
| Welcome | the human's FIRST session, or "what is this?" | instructions/welcome.md |
|
|
37
|
-
| Configure | first session in a repo,
|
|
37
|
+
| Configure | first session in a repo, frames render unstyled, or the canvas does not wear the product's name and logo: `marver dev`'s boot line says "this canvas still shows ...", `name` in design/config.ts is missing or still init's guess from package.json ("My repo" for `my-repo`), or the logo is the Marver mark - do step 6, identity | instructions/configure.md |
|
|
38
38
|
| Discover | any new surface, feature, or flow | instructions/discover.md |
|
|
39
39
|
| Shape | thinking a feature through on canvas (specs, diagrams, mood boards) - never the first session | instructions/shape.md |
|
|
40
40
|
| Wireframe | new work: nail structure + copy in throwaway lo-fi | instructions/wireframe.md |
|
|
@@ -44,7 +44,7 @@ file in design/instructions/ - they are short, strict, and part of this contract
|
|
|
44
44
|
| Review | before presenting anything | instructions/review.md |
|
|
45
45
|
| Boards | creating a board, choosing what ships | instructions/boards.md |
|
|
46
46
|
| Context | any question about what the product does or what is live; a behaviour change; a deploy; no `context/` yet | instructions/context.md |
|
|
47
|
-
| Slides | a deck is asked for, or `slide: true` frames exist | instructions/slides.md + design/slides.md |
|
|
47
|
+
| Slides | a deck is asked for; a PDF of a deck or of any board, a flow too (`npx marver pdf <board>`, then give back the path it prints); or `slide: true` frames exist | instructions/slides.md + design/slides.md |
|
|
48
48
|
| Publish | deploying the canvas: gate, volume, accounts, invites | instructions/publish.md |
|
|
49
49
|
| Live Jam | responding to an `@marver` comment (a spawned job), or a "Live Jam: ... new request" message (below) - run `npx marver jam next`; on by default - confirm it names YOUR tool | instructions/jam.md |
|
|
50
50
|
|
|
@@ -160,13 +160,35 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
|
|
|
160
160
|
|
|
161
161
|
- **Every reply in which you created or changed frames ends with their canvas link**, on its
|
|
162
162
|
own line: the `on the canvas:` line `work done` printed, or `npx marver link <scene/frame |
|
|
163
|
-
scene ...>` for any set
|
|
164
|
-
on several
|
|
165
|
-
the human finds the work at once on a board of fifty frames.
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
163
|
+
scene ...>` for any set (`checkout/cart`, or `checkout` for a whole scene). Each opens a board
|
|
164
|
+
they sit on (one link per board when they sit on several; `--board <b>` picks one) with them
|
|
165
|
+
selected and in view - the human finds the work at once on a board of fifty frames. **Give
|
|
166
|
+
exactly what those commands print** - a `marver://...` link (the Mac app has this canvas
|
|
167
|
+
open) or a localhost one - never a link you wrote yourself or rewrote. `link` reads a bare
|
|
168
|
+
name as a scene (`checkout`), never as a board: for a whole board, link the scenes it shows
|
|
169
|
+
with `--board <board>` (each node's `frame` in design/boards/<board>.json starts with its
|
|
170
|
+
scene; an `auto: true` board shows every scene), or its frames when it shows only some of a
|
|
171
|
+
scene's. Never a full-screen focus link unless they ask for full screen - then
|
|
172
|
+
`#/f/<scene/frame>` after the localhost link `npx marver ls` prints, the one link you write
|
|
173
|
+
yourself. **`link` and `show` need `marver dev` running for this folder** - the link carries
|
|
174
|
+
its port. `npx marver ls` lists the canvases running on this Mac and their links; none for
|
|
175
|
+
this folder? End by asking the person to run `npx marver dev` in their own terminal (or start
|
|
176
|
+
it detached: "Keeping the canvas up").
|
|
177
|
+
- **Show, only when they ask.** "Show me", "take me there", "open it for me": run `npx marver
|
|
178
|
+
show <target>` - `checkout/cart` (a frame), `checkout/cart checkout/pay` (several),
|
|
179
|
+
`checkout` (a scene), `launch-plan` (a board, fitted whole). A bare name is a frame or a
|
|
180
|
+
scene first, and a board only when no frame or scene has that name: a board whose name a
|
|
181
|
+
scene also has cannot be shown whole - show the scenes it shows with `--board <board>`, as
|
|
182
|
+
for `link`. `--thread <id>` opens that comment thread there too, with its frame or board
|
|
183
|
+
still named (`show checkout/cart --thread <id>`). Every open tab of this canvas goes
|
|
184
|
+
there, selected and fitted, and the Mac app comes forward. It waits 3 seconds, prints one
|
|
185
|
+
line, then the link:
|
|
186
|
+
- `shown in 2 tabs` - say it is on their screen, and end with the link;
|
|
187
|
+
- `1 tab holds words not yet sent - ...` - they were typing, so that tab did not move: it
|
|
188
|
+
shows "Your agent wants to show you ... · Go". Say so, and give the link;
|
|
189
|
+
- `not shown - no open tab took it ...` or `not shown: ...` - nothing moved: give the link.
|
|
190
|
+
Frames on two boards are refused: show one board at a time (`--board <board>`). Never show on
|
|
191
|
+
your own to hand work back - that is the link, above.
|
|
170
192
|
- **Answer each comment thread you addressed, in the thread**: `npx marver comments reply
|
|
171
193
|
<thread> --body "<what changed>"` - one line, no longer than their comment. On a thread
|
|
172
194
|
the human started it posts as Marver and pings them on the frame. A reply that asks them
|
|
@@ -183,7 +205,7 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
|
|
|
183
205
|
new --thread <id>` on your own note), never a second note on the same subject. A note in the
|
|
184
206
|
wrong place: `npx marver comments move <thread> --on "..."`, never a second copy. The chat keeps
|
|
185
207
|
the summary and can say "question on the form". Never resolve your own notes: the human
|
|
186
|
-
resolves them as they review.
|
|
208
|
+
resolves them as they review (one at a time, or all at once - below).
|
|
187
209
|
- **A plain reply in a Marver thread starts no job - only an `@marver` tag does.** The human
|
|
188
210
|
answers your notes and questions on the canvas, then tags the threads they want acted on, or
|
|
189
211
|
says "go through my replies": then run `npx marver marks` - its **answered by you** list is
|
|
@@ -201,6 +223,17 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
|
|
|
201
223
|
// tv available commented-out). Pick the one the screen is designed for - the human can
|
|
202
224
|
// flip the whole board to any device (Devices menu; digit keys - 0 restores each
|
|
203
225
|
// frame's own size, 1..n per configured device) to check responsiveness.
|
|
226
|
+
// Add the product's own devices there too: `"boox-full": { width: 1240, height: 1860 }`.
|
|
227
|
+
// Each shows as its name reads ("ipad-landscape" -> "iPad landscape", the tablet glyph
|
|
228
|
+
// turned) unless it sets `label` (40 chars) and `icon`: a glyph (mobile, tablet, laptop,
|
|
229
|
+
// monitor, tv, watch, desktop, ereader; "-landscape" turns it) or a repo .svg - paths and
|
|
230
|
+
// shapes only (no style, script, href, text), 32 KB at most, drawn in the toolbar's ink:
|
|
231
|
+
// it is a mask, so colours do not matter, only what is painted - `fill`/`stroke` attributes
|
|
232
|
+
// are fine (any colour, or none); a line icon needs fill="none" or its shapes fill solid.
|
|
233
|
+
// An `icon` replaces the name's turn: a landscape device names `tablet-landscape`,
|
|
234
|
+
// not `tablet`. An .svg is never turned - draw it the way the device stands. A bad
|
|
235
|
+
// label or icon falls back to the name's, with one line in `marver dev`'s terminal;
|
|
236
|
+
// both are read when `marver dev` starts (instructions/configure.md, step 6).
|
|
204
237
|
- States are sibling frames: empty.tsx, filled.tsx, error.tsx, success.tsx.
|
|
205
238
|
- VERSIONS are sibling frames with letter prefixes, and the canvas understands them:
|
|
206
239
|
design/scenes/landing/a-terminal.tsx + b-editorial.tsx form a VARIANT GROUP - kept
|
|
@@ -261,9 +294,40 @@ The human reviews on the canvas, not in the chat - so the reply puts them there:
|
|
|
261
294
|
Read it before exploring; `marver dev` keeps it fresh. `npx marver boards` prints the
|
|
262
295
|
boards part as a tree.
|
|
263
296
|
- **What the human has not reviewed.** At the start of a session, `npx marver marks`: the frames
|
|
264
|
-
waiting on them (your notes and replies they have not resolved - the ones that ask first)
|
|
265
|
-
|
|
297
|
+
waiting on them (your notes and replies they have not resolved - the ones that ask first), the
|
|
298
|
+
frames new since they last looked, and the open conversations per board. When it bears on the work, say so in your first message
|
|
266
299
|
("you have not looked at the checkout frames since I changed them").
|
|
300
|
+
- **The sidebar's marks, as the human names them.** Orange is Marver waiting on them: an
|
|
301
|
+
orange bubble on a frame, scene, board or closed folder counts your open notes and replies
|
|
302
|
+
there (a hollow one on a frame: they answered, and it waits on you - `marks`' answered by
|
|
303
|
+
you list). Blue is new: frames new or changed since they last looked - a blue dot, a blue
|
|
304
|
+
title. A board's status glyph takes the same slot when no question does (Building is blue),
|
|
305
|
+
and a board icon that shimmers blue is an agent at work on it. The human's own threads wear
|
|
306
|
+
no mark. Orange goes as the threads are resolved (resolve-all, below, only on their yes);
|
|
307
|
+
blue goes as they look at the frames, or with "Mark all as seen" in a board, folder or scene
|
|
308
|
+
menu - theirs to click, never yours.
|
|
309
|
+
- **Many open conversations: offer, never decide.** When `npx marver marks` shows more than 10
|
|
310
|
+
open (its `open` line; `--json` has `open.total` and `open.boards`), or the human says the
|
|
311
|
+
badges are noisy, ask - with the count per board it prints ("38 open: launch-plan 22,
|
|
312
|
+
checkout-compare 16 - resolve them?"). A frame on two boards counts on both. Only on a yes, and only for what
|
|
313
|
+
they said yes to: one board is `npx marver comments resolve --all --board <b>`, a folder
|
|
314
|
+
`--folder <f>`, a scene `--scene <s>`, everything `--canvas` (the only scope that also takes
|
|
315
|
+
threads with no frame or on a frame that is gone; `--scene` takes its frames whether or not a board shows them). `--dry-run` counts first. Give them the `--undo` line it
|
|
316
|
+
prints. It never touches what Jam is working on, and the human has the same in every board,
|
|
317
|
+
folder and scene menu ("Resolve all comments") and on the Mac app's tab. Never on your own.
|
|
318
|
+
- **Undo a resolve-all later.** The canvas's Undo notice lasts 10 seconds. After that, each run
|
|
319
|
+
is kept as `design/.local/comment-ops/<op>.json` (its `scope` and `at` say which; skip the
|
|
320
|
+
`.undo.json` files): `npx marver comments resolve --undo <op>` reopens each thread nothing
|
|
321
|
+
happened in since.
|
|
322
|
+
- **Edit and delete are the author's, on the canvas.** People edit and delete their own
|
|
323
|
+
messages there. Marver's notes and replies have no Edit or Delete, for anyone, and the CLI
|
|
324
|
+
edits and deletes nothing. A note of yours that is wrong: correct it in its thread (`comments
|
|
325
|
+
new --thread <id>` on your own note); a misplaced one: `comments move`. Say so in the chat;
|
|
326
|
+
the human resolves it. A person's message only they can change: never post it again reworded.
|
|
327
|
+
- **A deleted comment is gone.** A deleted reply
|
|
328
|
+
disappears; a deleted first comment whose replies stay is listed as "(comment deleted)"
|
|
329
|
+
(`"deleted": true` in `--json`, no body or author). Its words never reach you, in
|
|
330
|
+
`comments list` or in Jam. Never quote one back, and never write one again.
|
|
267
331
|
- **Performance.** `npx marver perf --loads --json` says what each board load did - time to
|
|
268
332
|
settled, how many moves and why, the slowest frames, errors. To make a board faster, name
|
|
269
333
|
the lever, change it, compare the next load. A slow frame's `admittedMs` is when its turn to
|