dsh-marker 0.0.0-stage → 0.1.2
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/README.md +44 -2
- package/client.js +609 -0
- package/cordis.patch.yml +5 -0
- package/docs/DETAIL.md +45 -0
- package/icon.svg +8 -0
- package/index.js +204 -0
- package/locale/en.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +59 -4
- package/src/bridge.js +494 -0
- package/src/discovery.js +428 -0
- package/src/endpoint.js +166 -0
- package/src/focus.js +204 -0
- package/src/locator.js +317 -0
- package/src/mentions.js +120 -0
- package/src/paths.js +52 -0
- package/src/presentation.js +255 -0
- package/src/protocol.js +610 -0
- package/src/queue.js +278 -0
- package/src/sessions.js +240 -0
- package/src/store.js +267 -0
- package/src/tools.js +392 -0
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What one annotation looks like to a human.
|
|
3
|
+
*
|
|
4
|
+
* The overlay and the model already read annotations; the Web Client's chip
|
|
5
|
+
* hover card is the third reader, and it needs less than the model does — no
|
|
6
|
+
* selectors to re-find anything, no page text to reason about, just what the
|
|
7
|
+
* user marked and the crop they saw. This module owns that projection so the
|
|
8
|
+
* route stays a transport and the shapes stay testable without a webserver.
|
|
9
|
+
*
|
|
10
|
+
* Everything here is the click-time snapshot: the anchor and `snapshot` were
|
|
11
|
+
* frozen when the user clicked, and nothing in this file re-reads a page.
|
|
12
|
+
*
|
|
13
|
+
* @module dsh-marker/presentation
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
import { IMAGE_PATH, ITEM_PATH, describeAnchor, truncate } from './protocol.js'
|
|
17
|
+
|
|
18
|
+
/** A card is a glance; every string is bounded by what a card can show. */
|
|
19
|
+
const CARD = {
|
|
20
|
+
urlChars: 300,
|
|
21
|
+
quoteChars: 400,
|
|
22
|
+
textChars: 240,
|
|
23
|
+
commentChars: 1_200,
|
|
24
|
+
selectorChars: 120,
|
|
25
|
+
styleChars: 8,
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Project one record for display.
|
|
30
|
+
*
|
|
31
|
+
* @param {any} record stored annotation
|
|
32
|
+
* @param {{ image?: any }} [options] the attachment reference the store holds
|
|
33
|
+
* @returns {Record<string, any>}
|
|
34
|
+
*/
|
|
35
|
+
export function describeAnnotation(record, options = {}) {
|
|
36
|
+
const anchor = record?.anchor ?? {}
|
|
37
|
+
const image = options.image ?? record?.host?.image
|
|
38
|
+
const snapshot = record?.snapshot
|
|
39
|
+
return {
|
|
40
|
+
id: String(record?.id ?? ''),
|
|
41
|
+
kind: String(anchor.kind ?? 'unknown'),
|
|
42
|
+
state: String(record?.state ?? 'open'),
|
|
43
|
+
...(typeof record?.intent === 'string' && record.intent !== '' ? { intent: record.intent } : {}),
|
|
44
|
+
comment: truncate(String(record?.comment ?? ''), CARD.commentChars),
|
|
45
|
+
createdAt: String(record?.createdAt ?? ''),
|
|
46
|
+
updatedAt: String(record?.updatedAt ?? ''),
|
|
47
|
+
url: truncate(String(record?.url ?? ''), CARD.urlChars),
|
|
48
|
+
title: truncate(String(record?.title ?? ''), CARD.textChars),
|
|
49
|
+
summary: describeAnchor(record ?? {}),
|
|
50
|
+
anchor: describeAnchorDetail(anchor),
|
|
51
|
+
...(snapshot === undefined || snapshot === null ? {} : { snapshot: describeSnapshot(snapshot) }),
|
|
52
|
+
...(image === undefined || image === null
|
|
53
|
+
? {}
|
|
54
|
+
: {
|
|
55
|
+
image: {
|
|
56
|
+
href: `${IMAGE_PATH}?id=${encodeURIComponent(String(record?.id ?? ''))}`,
|
|
57
|
+
width: numberOr(image.width, 0),
|
|
58
|
+
height: numberOr(image.height, 0),
|
|
59
|
+
bytes: numberOr(image.bytes, 0),
|
|
60
|
+
mediaType: typeof image.mediaType === 'string' ? image.mediaType : 'image/png',
|
|
61
|
+
},
|
|
62
|
+
}),
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** @param {any} anchor */
|
|
67
|
+
function describeAnchorDetail(anchor) {
|
|
68
|
+
if (anchor.kind === 'selection') {
|
|
69
|
+
return {
|
|
70
|
+
kind: 'selection',
|
|
71
|
+
quote: truncate(String(anchor.quote?.exact ?? ''), CARD.quoteChars),
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
if (anchor.kind === 'element') {
|
|
75
|
+
const fingerprint = anchor.fingerprint ?? {}
|
|
76
|
+
const diagnostics = anchor.diagnostics ?? {}
|
|
77
|
+
return {
|
|
78
|
+
kind: 'element',
|
|
79
|
+
tag: String(fingerprint.tag ?? 'element'),
|
|
80
|
+
...(fingerprint.textExcerpt ? { text: truncate(String(fingerprint.textExcerpt), CARD.textChars) } : {}),
|
|
81
|
+
...(fingerprint.outerHtmlPreview ? { html: truncate(String(fingerprint.outerHtmlPreview), CARD.textChars) } : {}),
|
|
82
|
+
...(anchor.selectors?.stable ? { selector: truncate(String(anchor.selectors.stable), CARD.selectorChars) } : {}),
|
|
83
|
+
...(diagnostics.a11yRole ? { role: String(diagnostics.a11yRole) } : {}),
|
|
84
|
+
...(diagnostics.a11yName ? { name: truncate(String(diagnostics.a11yName), CARD.textChars) } : {}),
|
|
85
|
+
...styleEntries(diagnostics.computedStyles),
|
|
86
|
+
rect: rectOf(anchor.rect),
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
return {
|
|
90
|
+
kind: 'region',
|
|
91
|
+
rect: rectOf(anchor.pageRect),
|
|
92
|
+
...(anchor.viewportRect === undefined ? {} : { viewportRect: rectOf(anchor.viewportRect) }),
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* A few computed styles, in the order they explain an element rather than the
|
|
98
|
+
* order the page happened to declare them.
|
|
99
|
+
* @param {any} styles
|
|
100
|
+
*/
|
|
101
|
+
function styleEntries(styles) {
|
|
102
|
+
if (styles === null || typeof styles !== 'object') return {}
|
|
103
|
+
const wanted = ['display', 'position', 'font-size', 'font-weight', 'color', 'background-color']
|
|
104
|
+
/** @type {Record<string, string>} */
|
|
105
|
+
const out = {}
|
|
106
|
+
let taken = 0
|
|
107
|
+
for (const key of wanted) {
|
|
108
|
+
const value = styles[key]
|
|
109
|
+
if (typeof value !== 'string' || value === '') continue
|
|
110
|
+
out[key] = truncate(value, CARD.styleChars * 10)
|
|
111
|
+
taken += 1
|
|
112
|
+
if (taken >= CARD.styleChars) break
|
|
113
|
+
}
|
|
114
|
+
return Object.keys(out).length === 0 ? {} : { styles: out }
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** @param {any} snapshot */
|
|
118
|
+
function describeSnapshot(snapshot) {
|
|
119
|
+
const viewport = snapshot.viewport ?? {}
|
|
120
|
+
return {
|
|
121
|
+
at: String(snapshot.at ?? ''),
|
|
122
|
+
rect: rectOf(snapshot.rect),
|
|
123
|
+
viewport: {
|
|
124
|
+
width: numberOr(viewport.width, 0),
|
|
125
|
+
height: numberOr(viewport.height, 0),
|
|
126
|
+
dpr: numberOr(viewport.dpr, 0),
|
|
127
|
+
scrollX: numberOr(viewport.scrollX, 0),
|
|
128
|
+
scrollY: numberOr(viewport.scrollY, 0),
|
|
129
|
+
},
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** @param {any} value @param {number} fallback */
|
|
134
|
+
function numberOr(value, fallback) {
|
|
135
|
+
return typeof value === 'number' && Number.isFinite(value) ? value : fallback
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/** @param {any} value */
|
|
139
|
+
function rectOf(value) {
|
|
140
|
+
return {
|
|
141
|
+
x: numberOr(value?.x, 0),
|
|
142
|
+
y: numberOr(value?.y, 0),
|
|
143
|
+
w: numberOr(value?.w, 0),
|
|
144
|
+
h: numberOr(value?.h, 0),
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Serve one annotation, and its crop, to the page this Host serves.
|
|
150
|
+
*
|
|
151
|
+
* Same-origin only, like the queue and the focus report: the GUI is the page the
|
|
152
|
+
* Host serves, and what the user marked is not a cross-site resource.
|
|
153
|
+
*
|
|
154
|
+
* @param {any} webServer
|
|
155
|
+
* @param {object} options
|
|
156
|
+
* @param {{ get: (id: string) => any, image: (id: string) => any }} options.store
|
|
157
|
+
* @param {(ref: any) => Promise<{ data: Uint8Array }>} [options.readImage] attachment reader
|
|
158
|
+
* @param {string} [options.path]
|
|
159
|
+
* @param {string} [options.imagePath]
|
|
160
|
+
* @returns {() => void} disposer
|
|
161
|
+
*/
|
|
162
|
+
export function registerPresentationRoutes(webServer, { store, readImage, path = ITEM_PATH, imagePath = IMAGE_PATH }) {
|
|
163
|
+
const jsonHeaders = {
|
|
164
|
+
'content-type': 'application/json; charset=utf-8',
|
|
165
|
+
'cache-control': 'no-store',
|
|
166
|
+
vary: 'sec-fetch-site',
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
const disposeItem = webServer.register({
|
|
170
|
+
kind: 'exact',
|
|
171
|
+
path,
|
|
172
|
+
auth: 'anonymous',
|
|
173
|
+
handler: (request, response) => {
|
|
174
|
+
/** @param {number} status @param {any} payload */
|
|
175
|
+
const send = (status, payload) => {
|
|
176
|
+
response.writeHead(status, jsonHeaders)
|
|
177
|
+
response.end(request.method === 'HEAD' ? undefined : JSON.stringify(payload))
|
|
178
|
+
}
|
|
179
|
+
if (!sameOrigin(request)) {
|
|
180
|
+
send(403, { ok: false, error: 'origin' })
|
|
181
|
+
return
|
|
182
|
+
}
|
|
183
|
+
if (request.method !== 'GET' && request.method !== 'HEAD') {
|
|
184
|
+
send(405, { ok: false, error: 'method' })
|
|
185
|
+
return
|
|
186
|
+
}
|
|
187
|
+
const id = new URL(request.url ?? path, 'http://127.0.0.1').searchParams.get('id') ?? ''
|
|
188
|
+
const record = id === '' ? undefined : store.get(id)
|
|
189
|
+
if (record === undefined) {
|
|
190
|
+
send(404, { ok: false, error: 'missing' })
|
|
191
|
+
return
|
|
192
|
+
}
|
|
193
|
+
send(200, { ok: true, item: describeAnnotation(record, { image: record.host?.image ?? store.image(id) }) })
|
|
194
|
+
},
|
|
195
|
+
})
|
|
196
|
+
|
|
197
|
+
const disposeImage = webServer.register({
|
|
198
|
+
kind: 'exact',
|
|
199
|
+
path: imagePath,
|
|
200
|
+
auth: 'anonymous',
|
|
201
|
+
handler: (request, response) => {
|
|
202
|
+
/** @param {number} status @param {any} payload */
|
|
203
|
+
const send = (status, payload) => {
|
|
204
|
+
response.writeHead(status, jsonHeaders)
|
|
205
|
+
response.end(JSON.stringify(payload))
|
|
206
|
+
}
|
|
207
|
+
if (!sameOrigin(request)) {
|
|
208
|
+
send(403, { ok: false, error: 'origin' })
|
|
209
|
+
return
|
|
210
|
+
}
|
|
211
|
+
if (request.method !== 'GET' && request.method !== 'HEAD') {
|
|
212
|
+
send(405, { ok: false, error: 'method' })
|
|
213
|
+
return
|
|
214
|
+
}
|
|
215
|
+
const id = new URL(request.url ?? imagePath, 'http://127.0.0.1').searchParams.get('id') ?? ''
|
|
216
|
+
const record = id === '' ? undefined : store.get(id)
|
|
217
|
+
const ref = record?.host?.image ?? (id === '' ? undefined : store.image(id))
|
|
218
|
+
if (ref === undefined) {
|
|
219
|
+
send(404, { ok: false, error: 'missing' })
|
|
220
|
+
return
|
|
221
|
+
}
|
|
222
|
+
if (readImage === undefined) {
|
|
223
|
+
send(503, { ok: false, error: 'attachments' })
|
|
224
|
+
return
|
|
225
|
+
}
|
|
226
|
+
readImage(ref)
|
|
227
|
+
.then((stored) => {
|
|
228
|
+
response.writeHead(200, {
|
|
229
|
+
'content-type': typeof ref.mediaType === 'string' ? ref.mediaType : 'image/png',
|
|
230
|
+
'content-length': stored.data.byteLength,
|
|
231
|
+
'cache-control': 'private, max-age=300',
|
|
232
|
+
'x-content-type-options': 'nosniff',
|
|
233
|
+
})
|
|
234
|
+
response.end(request.method === 'HEAD' ? undefined : Buffer.from(stored.data))
|
|
235
|
+
})
|
|
236
|
+
.catch(() => {
|
|
237
|
+
send(404, { ok: false, error: 'missing' })
|
|
238
|
+
})
|
|
239
|
+
},
|
|
240
|
+
})
|
|
241
|
+
|
|
242
|
+
return () => {
|
|
243
|
+
disposeItem()
|
|
244
|
+
disposeImage()
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/**
|
|
249
|
+
* The GUI is served by this Host, so the browser marks its own requests
|
|
250
|
+
* `same-origin`. A request without the header is not the page.
|
|
251
|
+
* @param {any} request
|
|
252
|
+
*/
|
|
253
|
+
function sameOrigin(request) {
|
|
254
|
+
return request.headers?.['sec-fetch-site'] === 'same-origin'
|
|
255
|
+
}
|