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.
@@ -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
+ }