authoravatarclover caruso<git@paperclover.net>2026-10-29 21:00:30-07:00
committeravatarclover caruso<git@paperclover.net>2026-11-12 19:05:57-08:00
log59e44af2f97fccde89fcc27f745b91a5f844c78d
tree8755c9982f3af76f2f55ccec719c3760c1b6dcbe
parent9b54dbca4dc7dadba7b476734ab405b75aa3ba36
signature Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU

feat: seo, meta, etc


14 files changed, 1631 insertions(+), 37 deletions(-)

lib/examples/meta-cards.ts created+561
......@@ -0,0 +1,561 @@
1// fixture pages for the `meta` tab of the debugger: every card that a link can
2// become, so that the tab can be checked against what it should draw.
3//
4// node --experimental-vm-modules lib/examples/meta-cards.ts serve
5// node --experimental-vm-modules lib/examples/meta-cards.ts shots [name...]
6// node --experimental-vm-modules lib/examples/meta-cards.ts discord [name...]
7// node --experimental-vm-modules lib/examples/meta-cards.ts compare name...
8//
9// `serve` lists the pages at http://localhost:3456. `shots` drives chrome (the
10// repo's playwright) over them and writes the `meta` tab of each to
11// `.clover/meta-cards/<name>.png`. `discord` posts the component embeds as
12// messages to the webhook in `TEST_DISCORD_WEBHOOK`, to see them in real Discord,
13// and captures the chrome window that has Discord open after each (macOS, with
14// screen recording). `compare` lays that capture beside the tab, for a
15// `shots --width=620 --scale=2` of the same names.
16const port = 3456;
17const base = new URL(`http://localhost:${port}/`);
18const template: meta.Template = { base };
19const outDir = ".clover/meta-cards";
20
21// -- images: solid, striped, with a circle that shows how it was cropped --
22
23const hues = [[59, 130, 246], [239, 68, 68], [34, 197, 94], [234, 179, 8], [168, 85, 247], [236, 72, 153]] as const;
24
25function png(width: number, height: number, [r, g, b]: readonly [number, number, number]): Buffer {
26 const stride = 1 + width * 3;
27 const raw = Buffer.alloc(stride * height);
28 const radius = Math.min(width, height) / 3;
29 for (let y = 0; y < height; y++) {
30 for (let x = 0; x < width; x++) {
31 const inside = Math.hypot(x - width / 2, y - height / 2) < radius;
32 const shade = inside ? 255 : ((x + y) >> 5) & 1 ? 0.75 : 1;
33 raw.set(inside ? [255, 255, 255] : [r * shade, g * shade, b * shade], y * stride + 1 + x * 3);
34 }
35 }
36 const chunk = (type: string, data: Buffer) => {
37 const out = Buffer.alloc(12 + data.length);
38 out.writeUInt32BE(data.length, 0);
39 out.write(type, 4, "latin1");
40 data.copy(out, 8);
41 out.writeUInt32BE(zlib.crc32(out.subarray(4, 8 + data.length)), 8 + data.length);
42 return out;
43 };
44 const header = Buffer.alloc(13);
45 header.writeUInt32BE(width, 0);
46 header.writeUInt32BE(height, 4);
47 header.set([8, 2, 0, 0, 0], 8);
48 return Buffer.concat([
49 Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
50 chunk("IHDR", header),
51 chunk("IDAT", zlib.deflateSync(raw)),
52 chunk("IEND", Buffer.alloc(0)),
53 ]);
54}
55
56/** `/img/1200x630-2.png`: the size, and which color of the six */
57const image = (width: number, height: number, hue = 0) => `/img/${width}x${height}-${hue % hues.length}.png`;
58
59// -- fixtures --
60
61const section = (text: string, accessory: meta.DiscordComponent): meta.DiscordComponent => ({
62 type: "section",
63 components: [{ type: "text", content: text }],
64 accessory,
65});
66const container = (...components: meta.DiscordComponent[]): meta.DiscordComponent => ({
67 type: "container",
68 components,
69});
70const text = (content: string): meta.DiscordComponent => ({ type: "text", content });
71const gallery = (count: number, size: readonly [number, number] = [600, 400]): meta.DiscordComponent => ({
72 type: "gallery",
73 items: Array.from(
74 { length: count },
75 (_, i) => ({ media: { url: image(size[0], size[1], i) }, description: `item ${i + 1}` }),
76 ),
77});
78const link = (label: string, extra: object = {}): meta.DiscordComponent => ({
79 type: "button",
80 url: "/somewhere",
81 label,
82 ...extra,
83});
84
85/** a page that has the component embed, and the Open Graph tags that it falls back to */
86const embed = (discord: meta.DiscordComponent): meta.Meta => ({
87 title: "Component embed",
88 description: "falls back to this",
89 embed: { thumbnail: image(1200, 630), siteTitle: "fixtures" },
90 discord,
91});
92
93/** what `c-linked` links to, rather than holds */
94const linked = container(text("linked json"));
95
96const cards: Record<string, meta.Meta> = {
97 "c-markdown": embed(container(text([
98 "# Heading one",
99 "## Heading two",
100 "### Heading three",
101 "-# subtext",
102 "**bold** *italic* __underline__ ~~strike~~ ***both*** ||spoiler|| `code`",
103 "[a masked link](https://example.com) and https://example.com/bare",
104 "> a quote",
105 "- one",
106 "- two",
107 "1. first",
108 "```",
109 "code block",
110 " indented",
111 "```",
112 "the end",
113 ].join("\n")))),
114 "c-section-thumbnail": embed(container(section(
115 "# Patch notes\nTwo lines beside a thumbnail.",
116 { type: "thumbnail", media: { url: image(400, 400) }, description: "alt text" },
117 ))),
118 "c-section-button": embed(container(section("Text beside a button.", link("Open")))),
119 "c-section-spoiler": embed(container(
120 section("The thumbnail is a spoiler.", { type: "thumbnail", media: { url: image(400, 400, 1) }, spoiler: true }),
121 )),
122 ...Object.fromEntries(
123 Array.from(
124 { length: 10 },
125 (_, i) => [`c-gallery-${i + 1}`, embed(container(text(`${i + 1} items`), gallery(i + 1)))],
126 ),
127 ),
128 "c-gallery-tall": embed(container(gallery(3, [400, 800]))),
129 "c-gallery-wide": embed(container(gallery(2, [1600, 400]))),
130 "c-separators": embed(container(
131 text("small"),
132 { type: "separator" },
133 text("large"),
134 { type: "separator", spacing: 2 },
135 text("no divider"),
136 { type: "separator", divider: false },
137 text("end"),
138 )),
139 "c-buttons": embed(container(
140 text("A row of buttons"),
141 {
142 type: "row",
143 components: [
144 link("Store"),
145 link("Community", { emoji: { name: "🎮" } }),
146 link("", { emoji: { name: "⭐" } }),
147 link("Disabled", { disabled: true }),
148 link("A button with a label that is quite long indeed"),
149 ],
150 },
151 )),
152 "c-spoiler": embed({ type: "container", spoiler: true, components: [text("a spoiler container"), gallery(2)] }),
153 "c-accent-none": embed(container(text("no accent"))),
154 "c-accent-red": embed({ type: "container", accent_color: 0xff0000, components: [text("red")] }),
155 "c-accent-black": embed({ type: "container", accent_color: 0, components: [text("black")] }),
156 "c-docs": embed({
157 type: "container",
158 accent_color: 1752220,
159 components: [
160 section("# **[New version out!](https://example.com/v2)**\nThe dungeon is deceptively tougher.", link("Open")),
161 gallery(3),
162 text("*Screenshots of new content*"),
163 { type: "separator", spacing: 1 },
164 { type: "row", components: [link("Store"), link("Community"), link("Patch Notes")] },
165 { type: "separator" },
166 section("## **[??????](https://example.com/me)**\nWho could this be?", {
167 type: "thumbnail",
168 media: { url: image(400, 400, 4) },
169 spoiler: true,
170 }),
171 ],
172 }),
173 "c-long": embed(container(text("a long line without any breaks ".repeat(70)))),
174 "c-linked": { ...embed(linked), discord: "/embeds/linked.json" },
175
176 // what Discord leaves out, and falls back from
177 "bad-nested-container": embed(container({ type: "container", components: [text("inner")] })),
178 "bad-button-key": embed(container({ type: "row", components: [link("x", { custom_id: "nope" })] })),
179 "bad-forty-one": embed(container(...Array.from({ length: 40 }, () => text("x")))),
180 "bad-gallery-11": embed(container(gallery(6), gallery(5))),
181 "bad-section-four": embed(container({
182 type: "section",
183 components: [text("1"), text("2"), text("3"), text("4")],
184 accessory: link("x"),
185 })),
186 "bad-thumbnail-alone": embed(container({ type: "thumbnail", media: { url: image(400, 400) } })),
187 "bad-linked-missing": { ...embed(container(text("x"))), discord: "/embeds/missing.json" },
188
189 // open graph and twitter
190 "og-title-only": { openGraph: { title: "A title and nothing else" } },
191 "og-pair": { title: "Title", description: "the title and description tags" },
192 "og-pair-lonely": { title: "Title without a description" },
193 "og-nothing": {},
194 "og-small": {
195 title: "Small",
196 description: "A thumbnail beside the text.",
197 embed: { thumbnail: image(600, 600), thumbnailSize: "icon" },
198 },
199 "og-large": {
200 title: "Large",
201 description: "An image under the text.",
202 embed: { thumbnail: image(1200, 630) },
203 themeColor: "#5865F2",
204 },
205 "og-site-name": {
206 title: "Site",
207 description: "With a site name.",
208 embed: { siteTitle: "Paper Clover", thumbnail: image(1200, 630) },
209 },
210 "og-gallery-2": {
211 title: "Gallery",
212 description: "Two images.",
213 openGraph: { image: [image(800, 600), image(800, 600, 1)] },
214 },
215 "og-gallery-3": {
216 title: "Gallery",
217 description: "Three images.",
218 openGraph: { image: [image(800, 600), image(800, 600, 1), image(800, 600, 2)] },
219 },
220 "og-gallery-4": {
221 title: "Gallery",
222 description: "Four images.",
223 openGraph: { image: [0, 1, 2, 3].map((i) => image(800, 600, i)) },
224 },
225 "og-photo": {
226 title: "Photo",
227 twitter: { card: "photo", image: image(1200, 630) },
228 openGraph: { image: image(1200, 630) },
229 },
230 "og-instapp": { title: "Instapp", openGraph: { type: "instapp:photo", image: image(1200, 630) } },
231 "og-video": {
232 title: "Video",
233 openGraph: { type: "video.other", video: "/video.mp4", image: image(1280, 720) },
234 twitter: { card: "player", title: "Video", image: image(1280, 720) },
235 },
236 "og-rich": {
237 title: "Rich",
238 description: "**bold** and a [link](https://example.com)\n- list",
239 openGraph: { type: "rich" },
240 embed: { thumbnail: image(400, 400), thumbnailSize: "icon" },
241 },
242 "og-long": {
243 title: "A title that runs on well past the seventy bytes that Discord leaves of it",
244 description: "A description that runs on. ".repeat(20),
245 embed: { thumbnail: image(1200, 630) },
246 },
247 "og-color-bad": { title: "Color", description: "not a hex color", themeColor: "red" },
248 "og-oembed": { title: "oEmbed", embed: {}, oEmbed: "/oembed.json" },
249 "og-too-long-url": {
250 title: "Url",
251 description: "long image url",
252 openGraph: { image: "/" + "a".repeat(2100) + ".png" },
253 },
254 "tw-summary": {
255 title: "Summary",
256 description: "A summary card.",
257 embed: { thumbnail: image(600, 600), thumbnailSize: "icon" },
258 },
259 "tw-large": { title: "Large image", description: "Not shown on this card.", embed: { thumbnail: image(1200, 630) } },
260 "tw-no-image": { title: "No image", description: "A summary card without an image.", embed: {} },
261 "tw-no-card": { openGraph: { title: "OG", description: "only Open Graph tags" } },
262 "tw-title-only": { twitter: { card: "summary", title: "Only a title" } },
263 "tw-app": { title: "App", twitter: { card: "app" }, openGraph: { title: "App" } },
264};
265
266/** pages that are not a `Meta`, for what a crawler is refused or finds malformed */
267const raw: Record<string, () => Response> = {
268 "http-403": () => new Response("<title>no</title>", { status: 403, headers: { "content-type": "text/html" } }),
269 "bad-json": () => rawPage(`{nope`),
270 "bad-oversize": () =>
271 rawPage(JSON.stringify({ component: { type: 17, components: [{ type: 10, content: "x".repeat(3100) }] } })),
272};
273
274function rawPage(script: string) {
275 const html = `<!doctype html><title>Raw</title><meta property=og:title content=Raw>`
276 + `<meta property=og:description content="the fallback">`
277 + `<script id="discord:component-embed" type="application/json">${script}</script>`;
278 return new Response(html, { headers: { "content-type": "text/html" } });
279}
280
281const names = [...Object.keys(cards), ...Object.keys(raw)];
282
283// -- the server --
284
285async function serve() {
286 const graph = new incremental.Graph({ db: null });
287 const debug = new incremental.Debugger(graph);
288 debug.update({
289 ok: true,
290 value: null,
291 changed: [],
292 stats: { duration: 12, ran: 1, reused: 2, written: 3, cacheBytes: 4, outputBytes: 5 },
293 watching: { file: 1 },
294 statusLine: "Watching 1 file",
295 } as never);
296
297 return http.serve({
298 port,
299 respond: debug.respond(async (request) => {
300 const { pathname } = new URL(request.url);
301 const picture = /^\/img\/(\d+)x(\d+)-(\d)\.png$/.exec(pathname);
302 if (picture) {
303 const [, width, height, hue] = picture;
304 return new Response(new Uint8Array(png(Number(width), Number(height), hues[Number(hue)]!)), {
305 headers: { "content-type": "image/png" },
306 });
307 }
308 if (pathname === "/embeds/linked.json") return Response.json(payloadOf(linked));
309 if (pathname === "/oembed.json") {
310 return Response.json({
311 version: "1.0",
312 type: "link",
313 author_name: "Anthony Tešija",
314 provider_name: "Dungeon Delvers",
315 thumbnail_url: image(1200, 630, 4),
316 thumbnail_width: 1200,
317 thumbnail_height: 630,
318 });
319 }
320 const name = pathname.slice(1);
321 if (name === "") {
322 const items = names.map((name) => `<li><a href="/${name}">${name}</a>`).join("");
323 return new Response(`<!doctype html><title>meta cards</title><ul>${items}</ul>`, {
324 headers: { "content-type": "text/html" },
325 });
326 }
327 if (raw[name]) return raw[name]();
328 if (!cards[name]) return new Response("not a fixture", { status: 404 });
329 const html = `<!doctype html><html><head>${
330 meta.toHtml(template, cards[name])
331 }</head><body><h1>${name}</h1></body></html>`;
332 return new Response(html, { headers: { "content-type": "text/html" } });
333 }),
334 upgrade: debug.upgrade,
335 shouldUpgrade: debug.shouldUpgrade,
336 });
337}
338
339/** what discord reads of a component embed, which `toTags` makes of it */
340function payloadOf(discord: meta.DiscordComponent): meta.DiscordPayload {
341 const children = meta.toTags(template, { discord }).scripts[0]!.children;
342 return JSON.parse(children as string);
343}
344
345// -- screenshots --
346
347/** `--width=560 --scale=2` and the names of fixtures, which is all of them if there are none */
348function parse(args: string[]) {
349 const flags = Object.fromEntries(args.filter((arg) => arg.startsWith("--")).map((arg) => arg.slice(2).split("=")));
350 return { flags: flags as Record<string, string | undefined>, only: args.filter((arg) => !arg.startsWith("--")) };
351}
352
353async function shots(args: string[]) {
354 const { flags, only } = parse(args);
355 const { chromium } = await import("playwright");
356 const server = await serve();
357 // a page that reports itself automated gets no visualization
358 const browser = await chromium.launch({ channel: "chrome", args: ["--disable-blink-features=AutomationControlled"] });
359 fs.mkdirSync(outDir, { recursive: true });
360 try {
361 for (const name of only.length > 0 ? only : names) {
362 const context = await browser.newContext({
363 viewport: { width: 900, height: 1200 },
364 deviceScaleFactor: Number(flags.scale ?? 1),
365 });
366 const page = await context.newPage();
367 const problems: string[] = [];
368 page.on("pageerror", (error) => problems.push(error.message));
369 await page.goto(`${base.href}${name}`);
370 await page.locator(".clover").click();
371 await page.locator("#tab-meta").click();
372 // the panel is as wide as the message that a card is checked against
373 if (flags.width) {
374 await page.evaluate(
375 (width) =>
376 (document.querySelector("clover-debugger") as HTMLElement).style.setProperty("--width", `${width}px`),
377 flags.width,
378 );
379 }
380 await page.locator(".cards > .preview").first().waitFor();
381 // images that are published somewhere else fall back to this server's, and then they are done
382 await page.waitForFunction(
383 () => {
384 const images = document.querySelector("clover-debugger")!.shadowRoot!.querySelectorAll("img");
385 return Array.from(images).every((img) => img.complete);
386 },
387 undefined,
388 { polling: 100 },
389 );
390 await page.locator(".cards").screenshot({ path: `${outDir}/${name}.png` });
391 const chat = page.locator(".chat").first();
392 const box = await page.locator(".chat .d-container, .chat .discord").first().boundingBox().catch(() => null);
393 if (await chat.count()) await chat.screenshot({ path: `${outDir}/${name}.chat.png` });
394 const size = box ? ` ${Math.round(box.width)}x${Math.round(box.height)}` : "";
395 console.log(`${name}${size}${problems.length > 0 ? ` errors: ${problems.join("; ")}` : ""}`);
396 await context.close();
397 }
398 } finally {
399 await browser.close();
400 await server.close();
401 }
402}
403
404// -- real discord --
405
406/** the window of chrome that has discord open, as an image. macOS only, and it needs screen recording */
407function capture(file: string) {
408 const find = `ObjC.import("CoreGraphics");
409 const windows = ObjC.deepUnwrap(ObjC.castRefToObject($.CGWindowListCopyWindowInfo(
410 $.kCGWindowListOptionOnScreenOnly | $.kCGWindowListExcludeDesktopElements, $.kCGNullWindowID)));
411 windows.find((w) => w.kCGWindowOwnerName === "Google Chrome" && /Discord/.test(w.kCGWindowName ?? "")).kCGWindowNumber`;
412 const id = child_process.execFileSync("osascript", ["-l", "JavaScript", "-e", find]).toString().trim();
413 child_process.execFileSync("screencapture", ["-x", "-o", `-l${id}`, file]);
414}
415
416/**
417 * what to post for a fixture: a component embed as a message of components, and
418 * what a link to the rest would unfurl to as embeds, which Discord draws as it
419 * draws that unfurl, but for the provider's name
420 */
421function message(name: string): object | null {
422 const page = cards[name]!;
423 if (page.discord && typeof page.discord === "object") {
424 return { flags: 1 << 15, components: [payloadOf(page.discord).component] };
425 }
426 const { title, description, themeColor, openGraph: og, twitter } = meta.scrape(meta.toTags(template, page));
427 const text = {
428 url: `${base.href}${name}`,
429 title: og.title?.[0] ?? title ?? undefined,
430 description: og.description?.[0] ?? description ?? undefined,
431 color: themeColor && /^#[0-9a-f]{6}$/i.test(themeColor) ? parseInt(themeColor.slice(1), 16) : undefined,
432 };
433 if (!text.title && !text.description) return null;
434 const images = (og.image ?? []).map((url) => new URL(url, base).href);
435 // embeds that share a link are one card with a gallery
436 if (images.length > 1 || (images.length === 1 && twitter.card?.at(-1) === "summary_large_image")) {
437 return {
438 embeds: images.slice(0, 4).map((url, i) => ({ ...(i === 0 ? text : { url: text.url }), image: { url } })),
439 };
440 }
441 return { embeds: [{ ...text, ...(images[0] && { thumbnail: { url: images[0] } }) }] };
442}
443
444async function discord(only: string[]) {
445 const webhook = process.env.TEST_DISCORD_WEBHOOK;
446 if (!webhook) throw new Error("TEST_DISCORD_WEBHOOK is not set");
447 const server = await serve();
448 try {
449 for (const name of only.length > 0 ? only : Object.keys(cards).filter((name) => name.startsWith("c-"))) {
450 const body = message(name);
451 if (!body) continue;
452 // media on this machine goes along as attachments, which discord can read
453 const files = new Map<string, Buffer>();
454 const json = JSON.stringify(body, (key, value) => {
455 if (key !== "url" || typeof value !== "string" || !value.startsWith(`${base.href}img/`)) return value;
456 const file = new URL(value).pathname.slice("/img/".length);
457 const [, width, height, hue] = /^(\d+)x(\d+)-(\d)\.png$/.exec(file)!;
458 files.set(file, png(Number(width), Number(height), hues[Number(hue)]!));
459 return `attachment://${file}`;
460 });
461 const form = new FormData();
462 form.set("payload_json", json);
463 Array.from(files).forEach(([file, bytes], i) => form.set(`files[${i}]`, new Blob([new Uint8Array(bytes)]), file));
464 const response = await fetch(`${webhook}?wait=true&with_components=true`, { method: "POST", body: form });
465 console.log(`${name} ${response.status}${response.ok ? "" : " " + (await response.text())}`);
466 // the message is drawn, and its images are fetched, before the window is taken
467 await async.delay(3000);
468 fs.mkdirSync(`${outDir}/discord`, { recursive: true });
469 capture(`${outDir}/discord/${name}.png`);
470 }
471 } finally {
472 await server.close();
473 }
474}
475
476/**
477 * the capture of discord and the `meta` tab side by side, as high as the card and
478 * bottom aligned, in `.clover/meta-cards/compare`. `shots --width=620 --scale=2`
479 * makes the one half, and `discord` the other. The message pane is assumed to
480 * start at `paneX` device pixels, and the card to be the last thing in it.
481 */
482async function compare(args: string[]) {
483 const { only } = parse(args);
484 const { chromium } = await import("playwright");
485 const browser = await chromium.launch({ channel: "chrome" });
486 const page = await browser.newPage();
487 fs.mkdirSync(`${outDir}/compare`, { recursive: true });
488 const read = (file: string) => `data:image/png;base64,${fs.readFileSync(file).toString("base64")}`;
489 try {
490 for (const name of only) {
491 const url = await page.evaluate(async ([real, mine]) => {
492 const paneX = 760, width = 1040;
493 const load = async (src: string) => {
494 const img = new Image();
495 img.src = src;
496 await img.decode();
497 return img;
498 };
499 const [capture, ours] = await Promise.all([load(real!), load(mine!)]);
500 // the bottom border of the last card, which is the last long run of its color
501 const canvas = document.createElement("canvas");
502 canvas.width = capture.width;
503 canvas.height = capture.height;
504 const context = canvas.getContext("2d")!;
505 context.drawImage(capture, 0, 0);
506 const pixels = context.getImageData(0, 0, capture.width, capture.height).data;
507 let bottom = 0;
508 for (let y = 0; y < capture.height; y++) {
509 let run = 0;
510 for (let x = paneX; x < capture.width && run < 40; x++) {
511 const i = (y * capture.width + x) * 4;
512 run = Math.abs(pixels[i]! - 0x43) + Math.abs(pixels[i + 1]! - 0x45) + Math.abs(pixels[i + 2]! - 0x4c) < 6
513 ? run + 1
514 : 0;
515 }
516 if (run >= 40) bottom = y;
517 }
518 // the chat of the tab has 12 pixels of padding below the card, which is 24 device pixels
519 const height = Math.min(ours.height - 24, 1100);
520 const out = document.createElement("canvas");
521 out.width = 2 * width + 8;
522 out.height = height + 24;
523 const draw = out.getContext("2d")!;
524 draw.fillStyle = "#000";
525 draw.fillRect(0, 0, out.width, out.height);
526 draw.drawImage(capture, paneX, bottom + 2 - height, width, height + 24, 0, 0, width, height + 24);
527 draw.drawImage(ours, 0, ours.height - 24 - height, width, height + 24, width + 8, 0, width, height + 24);
528 return out.toDataURL("image/png");
529 }, [read(`${outDir}/discord/${name}.png`), read(`${outDir}/${name}.chat.png`)]);
530 fs.writeFileSync(`${outDir}/compare/${name}.png`, Buffer.from(url.split(",")[1]!, "base64"));
531 console.log(`${outDir}/compare/${name}.png`);
532 }
533 } finally {
534 await browser.close();
535 }
536}
537
538if (existsSync(".env")) process.loadEnvFile(".env");
539const [command, ...rest] = process.argv.slice(2);
540if (command === "serve") {
541 const server = await serve();
542 console.log(`up: ${base.href} (${names.length} pages)`);
543 process.on("SIGINT", () => void server.close().then(() => process.exit(0)));
544} else if (command === "shots") {
545 await shots(rest);
546} else if (command === "discord") {
547 await discord(rest);
548} else if (command === "compare") {
549 await compare(rest);
550} else {
551 console.log("usage: meta-cards.ts serve | shots [name...] | discord [name...] | compare name...");
552}
553
554import * as child_process from "node:child_process";
555import { existsSync } from "node:fs";
556import * as fs from "node:fs";
557import * as zlib from "node:zlib";
558import * as async from "../async.ts";
559import * as http from "../http.ts";
560import * as incremental from "../incremental.ts";
561import * as meta from "../meta.ts";
lib/incremental/visualization.ts+457-3
......@@ -38,6 +38,8 @@ let saved = JSON.parse(sessionStorage.getItem(savedKey) ?? "null") as Saved | nu
3838/** the panel stays open */
3939let open = home || (saved?.open ?? false);
4040let maximized = home || (saved?.maximized ?? false);
41/** how wide the panel is dragged to, in pixels */
42let width = saved?.width ?? null;
4143let tab: (typeof tabs)[number] = home ? "graph" : saved?.tab ?? "status";
4244/** a build changed this page, which still shows what it was */
4345let stale = false;
......@@ -53,11 +55,12 @@ let timer: ReturnType<typeof setTimeout> | undefined;
5355let ticking: ReturnType<typeof setTimeout> | undefined;
5456let retry = 100;
5557
56const tabs = ["status", "problems", "graph"] as const;
58const tabs = ["status", "problems", "meta", "graph"] as const;
5759interface Saved {
5860 /** what the debugger's own page shows is not carried to the page after it */
5961 open?: boolean;
6062 maximized?: boolean;
63 width?: number;
6164 tab?: (typeof tabs)[number];
6265 folded: boolean;
6366 view: typeof view;
......@@ -137,6 +140,7 @@ shadow.innerHTML = `<style>${css()}</style>
137140 aria-controls=panel>${clover()}<div class=spinner></div></button>
138141<div class=live role=status></div>
139142<section id=panel class=panel aria-label="build status" hidden>
143 <div class=grip role=separator aria-orientation=vertical aria-label="panel width" tabindex=0></div>
140144 <div class=tabs>
141145 <div role=tablist>${tabButtons}</div>
142146 <button type=button class=maximize aria-label=maximize aria-pressed=false>
......@@ -155,6 +159,9 @@ shadow.innerHTML = `<style>${css()}</style>
155159 <div id=view-problems class=view role=tabpanel aria-labelledby=tab-problems>
156160 <div class=problems></div><p class=empty>no problems</p>
157161 </div>
162 <div id=view-meta class=view role=tabpanel aria-labelledby=tab-meta>
163 <div class=cards></div>
164 </div>
158165 <div id=view-graph class=view role=tabpanel aria-labelledby=tab-graph>
159166 <canvas role=img aria-label="the steps of the build, and what they read"></canvas>
160167 <div class=legend>${legend()}</div>
......@@ -174,6 +181,8 @@ const button = find<HTMLButtonElement>(".clover");
174181const live = find(".live");
175182const panel = find(".panel");
176183const maximize = find(".maximize");
184const grip = find(".grip");
185if (width) host.style.setProperty("--width", `${width}px`);
177186const dialog = find<HTMLDialogElement>("dialog");
178187const tree = document.createElement("div");
179188
......@@ -218,8 +227,10 @@ function render() {
218227 // during a build, its progress is its status
219228 find("#view-status").hidden = tab !== "status" || (building !== null && !stale);
220229 find("#view-problems").hidden = tab !== "problems";
230 find("#view-meta").hidden = tab !== "meta";
221231 find("#view-graph").hidden = tab !== "graph";
222232 if (visible && tab === "graph") showGraph();
233 if (visible && tab === "meta") showMeta();
223234
224235 const slot = UNWRAP((cover ? dialog : panel).querySelector<HTMLElement>(".slot"));
225236 if (tree.parentElement !== slot) slot.append(tree);
......@@ -604,6 +615,329 @@ const gravity = 0.05;
604615const theta = 0.9;
605616const jiggle = () => (Math.random() - 0.5) * 1e-6;
606617
618// -- meta: the cards that a shared link becomes --
619
620/** the page as the server sends it, which is all that a crawler sees, as none of them run its scripts */
621let reading: Promise<void> | null = null;
622
623function showMeta() {
624 reading ??= readMeta().catch(() => {
625 reading = null;
626 find(".cards").innerHTML = "<p class=empty>this page could not be read</p>";
627 });
628}
629
630async function readMeta() {
631 const page = await fetch(location.href, { headers: { accept: "text/html" }, cache: "no-store" });
632 const html = await page.text();
633 const scraped = meta.scrape(meta.readTags(new DOMParser().parseFromString(html, "text/html")));
634 const [embed, oEmbed] = await Promise.all([loadEmbed(scraped.discord), loadOEmbed(scraped.oEmbed)]);
635 const refused = refusal(page);
636 find(".cards").innerHTML = discordCard(scraped, embed, oEmbed, refused) + twitterCard(scraped, refused);
637}
638
639/** why a crawler reads nothing from a page that is served like this */
640function refusal(page: Response): string | null {
641 const type = page.headers.get("content-type") ?? "";
642 if (!page.ok) return `the page responds ${page.status}`;
643 if (!/^(text\/html|application\/xhtml\+xml)\b/i.test(type)) {
644 return `the page is served as ${type || "nothing"}, not html`;
645 }
646 if (/^attachment/i.test(page.headers.get("content-disposition") ?? "")) return "the page is served as a download";
647 return null;
648}
649
650/** a file that the page names on the host that it is published to, as the dev server has it at that path */
651async function fetchLocal(href: string): Promise<string | null> {
652 const url = new URL(href, location.href);
653 const response = await fetch(url.pathname + url.search, { cache: "no-store" }).catch(() => null);
654 return response?.ok ? response.text() : null;
655}
656
657type Embed = { component: Wire } | { problems: string[] };
658
659/** the component embed that the page holds or links to, or why Discord would not show it */
660async function loadEmbed(source: meta.Scraped["discord"]): Promise<Embed | null> {
661 if (!source) return null;
662 let text: string;
663 if ("text" in source) {
664 text = source.text;
665 } else {
666 const fetched = await fetchLocal(source.href);
667 if (fetched === null) return { problems: [`${source.href} could not be read`] };
668 text = fetched;
669 }
670 const problems: string[] = [];
671 const bytes = string.encodeUtf8(text).length;
672 if (bytes > 3000) problems.push(`the component embed is ${bytes} bytes, at most 3000`);
673 try {
674 const embed = JSON.parse(text) as meta.DiscordPayload;
675 problems.push(...meta.discordProblems(embed));
676 // a payload with no problems has the shapes of `Wire`
677 return problems.length > 0 ? { problems } : { component: embed.component as unknown as Wire };
678 } catch {
679 return { problems: ["the component embed is not json"] };
680 }
681}
682
683interface OEmbed {
684 title?: string;
685 thumbnail_url?: string;
686 thumbnail_width?: number;
687 thumbnail_height?: number;
688 author_name?: string;
689 provider_name?: string;
690}
691
692/** the fields of oEmbed json that Discord reads. it ignores a file that it can't read, too */
693async function loadOEmbed(href: string | null): Promise<OEmbed | null> {
694 const text = href && await fetchLocal(href);
695 try {
696 return text ? JSON.parse(text) as OEmbed : null;
697 } catch {
698 return null;
699 }
700}
701
702const hexColor = /^#[0-9a-f]{6}([0-9a-f]{2})?$/i;
703const esc = string.escapeHtmlContent;
704const attr = string.escapeHtmlAttr;
705
706/** an image of the page. a url that is published to may not have it yet, so the dev server's copy of its path is the fallback */
707function img(src: string, alt = "", cls = "") {
708 const url = new URL(src, location.href);
709 return `<img class="${cls}" src="${attr(url.href)}" data-local="${attr(location.origin + url.pathname + url.search)}"`
710 + ` alt="${attr(alt)}">`;
711}
712
713/** cut to a number of bytes, as Discord cuts a title and a description */
714function clip(text: string, bytes: number) {
715 const encoded = string.encodeUtf8(text);
716 if (encoded.length <= bytes) return text;
717 return string.decodeUtf8(encoded.subarray(0, bytes - 3)).replace(/\uFFFD$/, "") + "…";
718}
719
720/** the names of the tags that hold a url that Discord reads */
721const urlKey = /^(image|video|url)(:(url|secure_url))?$|^(image:src|player:stream)$/;
722
723/** what makes Discord drop a link's preview entirely, rather than trim it */
724function discordRefusal({ openGraph: og, twitter: tw }: meta.Scraped): string | null {
725 if ((og.site_name?.[0]?.length ?? 0) > 256) return "og:site_name is over 256 characters";
726 if ([og, tw].some((tags) => tags["image:alt"]?.some((alt) => alt.length > 4096))) {
727 return "image alt text is over 4096 characters";
728 }
729 const long = [og, tw].some((tags) =>
730 Object.entries(tags).some(([key, values]) => urlKey.test(key) && values.some((value) => value.length > 2048))
731 );
732 return long ? "a url is over 2048 characters" : null;
733}
734
735function discordCard(s: meta.Scraped, loaded: Embed | null, oEmbed: OEmbed | null, refused: string | null): string {
736 const { openGraph: og, twitter: tw } = s;
737 const notes: string[] = [];
738 const last = (values: string[] | undefined) => values?.at(-1);
739 const message = (card: string) =>
740 `<section class=preview>${card && `<div class=chat>${card}</div>`}`
741 + `${noteList(notes)}</section>`;
742
743 const stop = refused ?? discordRefusal(s);
744 if (stop) return notes.push(`${stop}, so Discord shows no preview`), message("");
745
746 if (loaded && "problems" in loaded) {
747 notes.push("the component embed has problems, so Discord shows the Open Graph card", ...loaded.problems);
748 } else if (loaded) {
749 // a component embed is a card of its own, rather than something in the Open Graph card
750 if (!og.title) notes.push("no og:title for Discord to fall back on");
751 return message(component(loaded.component));
752 }
753
754 let heading = og.title?.[0] ?? tw.title?.[0];
755 let text = og.description?.[0] ?? tw.description?.[0];
756 // the title and description tags are used together or not at all, and when the others have neither
757 if (!heading && !text) {
758 if (s.title && s.description) [heading, text] = [s.title, s.description];
759 else if (s.title || s.description) notes.push("<title> and <meta name=description> are used only as a pair");
760 }
761 heading ??= oEmbed?.title;
762 const images = [og.image, og["image:url"], og["image:secure_url"], tw.image, tw["image:src"]]
763 .find((values) => values?.length) ?? (oEmbed?.thumbnail_url && oEmbed.thumbnail_width && oEmbed.thumbnail_height
764 ? [oEmbed.thumbnail_url]
765 : []);
766 if (!heading && !text && images.length === 0) {
767 return notes.push("no og:title or og:description, so Discord shows no preview"), message("");
768 }
769
770 const color = s.themeColor && hexColor.test(s.themeColor) ? s.themeColor : null;
771 if (s.themeColor && !color) notes.push(`theme-color ${s.themeColor} is not #RRGGBB, so Discord leaves it out`);
772 const alt = og["image:alt"]?.[0] ?? tw["image:alt"]?.[0];
773 const kind = last(og.type);
774 const layout = last(tw.card);
775 const video = [og.video, og["video:url"], og["video:secure_url"], tw["player:stream"]]
776 .find((values) => values?.length)?.[0];
777 const site = oEmbed?.provider_name ?? og.site_name?.[0];
778
779 const first = images[0];
780 const lead = (site ? `<div class=d-site>${esc(site)}</div>` : "")
781 + (oEmbed?.author_name ? `<div class=d-site>${esc(oEmbed.author_name)}</div>` : "")
782 + (heading ? `<div class=d-title>${esc(clip(heading, 70))}</div>` : "");
783 const words = text ? `<div class=d-desc>${kind === "rich" ? markdown(text) : esc(clip(text, 350))}</div>` : "";
784 let card: string;
785 if (first && video && (kind?.startsWith("video") || layout === "player")) {
786 card = lead + `<div class="d-frame d-big">${img(first, alt)}<i class=play></i></div>`;
787 } else if (first && (layout === "photo" || kind === "instapp:photo")) {
788 card = lead + img(first, alt, "d-big");
789 } else if (first && images.length > 1) {
790 card = lead + words + gallery(images.slice(0, 4).map((src) => ({ media: { url: src }, description: alt })));
791 } else if (first && layout === "summary_large_image") {
792 card = lead + words + img(first, alt, "d-big");
793 } else {
794 card = `<div class=d-split><div>${lead}${words}</div>${first ? img(first, alt, "d-small") : ""}</div>`;
795 }
796 const style = color ? ` style="--accent:${attr(color)}"` : "";
797 return message(`<div class=discord${style}>${card}</div>`);
798}
799
800function twitterCard(s: meta.Scraped, refused: string | null): string {
801 const { openGraph: og, twitter: tw } = s;
802 const notes: string[] = [];
803 const shared = new URL(s.canonical ?? og.url?.[0] ?? location.href, location.href);
804 const tweet = (card: string) =>
805 `<section class=preview>${card && `<div class=tweet>${card}</div>`}`
806 + `${noteList(notes)}</section>`;
807
808 // twitter takes what a tag leaves out from the Open Graph tags, but not from <title>
809 const title = tw.title?.[0] ?? og.title?.[0];
810 const description = tw.description?.[0] ?? og.description?.[0];
811 const image = (tw.image ?? tw["image:src"] ?? og.image)?.[0];
812 const alt = tw["image:alt"]?.[0] ?? og["image:alt"]?.[0];
813 const layout = tw.card?.at(-1);
814 const stop = refused ?? (layout
815 ? title ? null : "there is no title"
816 : title && description
817 ? null
818 : "there is no twitter:card, nor an og:title and og:description to make a summary of");
819 if (stop) return notes.push(`${stop}, so twitter shows no card`), tweet("");
820 if (!layout) notes.push("no twitter:card, so twitter may show a summary");
821 else if (layout !== "summary" && layout !== "summary_large_image") {
822 notes.push(`twitter shows a ${layout} card as a summary here`);
823 }
824
825 // a summary without an image keeps its place, with a newspaper
826 const picture = image ? img(image, alt) : `<div class=x-blank>${newspaper}</div>`;
827 const card = layout === "summary_large_image" && image
828 ? `<div class=x-card><div class=x-image>${picture}<span class=x-over>${esc(title!)}</span></div></div>`
829 + `<div class=x-domain>From ${esc(shared.hostname)}</div>`
830 : `<div class="x-card x-summary">${picture}<div class=x-text><div class=x-domain>${esc(shared.hostname)}</div>`
831 + `<div class=x-title>${esc(title!)}</div>`
832 + (description ? `<div class=x-desc>${esc(description)}</div>` : "") + `</div></div>`;
833 return tweet(card);
834}
835
836const newspaper =
837 `<svg viewBox="0 0 24 24" aria-hidden=true><path d="M3 4h18v16H3zM6.5 8h5v4h-5zM14 8.5h3.5M14 11.5h3.5M6.5 16h11"/></svg>`;
838
839const noteList = (notes: string[]) =>
840 notes.length > 0 ? `<ul class=notes>${notes.map((note) => `<li>${esc(note)}</li>`).join("")}</ul>` : "";
841
842/** a component of a payload that `meta.discordProblems` found no problem with */
843type Wire =
844 | { type: 1; components: Wire[] }
845 | { type: 2; url: string; label?: string; emoji?: { id?: string; name?: string }; disabled?: boolean }
846 | { type: 9; components: Wire[]; accessory: Wire }
847 | { type: 10; content: string }
848 | ({ type: 11 } & WireMedia)
849 | { type: 12; items: WireMedia[] }
850 | { type: 14; spacing?: number | null; divider?: boolean | null }
851 | { type: 17; components: Wire[]; accent_color?: number | null; spoiler?: boolean };
852interface WireMedia {
853 media: { url: string };
854 description?: string | null;
855 spoiler?: boolean;
856}
857
858function gallery(items: WireMedia[]): string {
859 const cells = items.map(({ media, description, spoiler }) =>
860 `<div class="d-cell${spoiler ? " spoiler" : ""}">${img(media.url, description ?? "")}</div>`
861 );
862 return `<div class="d-gallery n${items.length}">${cells.join("")}</div>`;
863}
864
865/** a component of an embed, which is laid out as the app lays out a message */
866function component(c: Wire): string {
867 const spoiler = (of: { spoiler?: boolean }) => of.spoiler ? " spoiler" : "";
868 switch (c.type) {
869 case 1:
870 return `<div class=d-row>${c.components.map(component).join("")}</div>`;
871 case 2: {
872 const emoji = c.emoji?.id ? "" : c.emoji?.name;
873 return `<span class="d-button${c.disabled ? " disabled" : ""}">${
874 emoji ? `<span class=emoji>${esc(emoji)}</span>` : ""
875 }`
876 + `${esc(c.label ?? "")}${external}</span>`;
877 }
878 case 9:
879 return `<div class=d-section><div>${c.components.map(component).join("")}</div>${component(c.accessory)}</div>`;
880 case 10:
881 return `<div class=d-text>${markdown(c.content)}</div>`;
882 case 11:
883 return `<div class="d-thumb${spoiler(c)}">${img(c.media.url, c.description ?? "")}</div>`;
884 case 12:
885 return gallery(c.items);
886 case 14:
887 return `<hr class="d-sep${c.spacing === 2 ? " large" : ""}${c.divider === false ? " blank" : ""}">`;
888 case 17: {
889 const accent = c.accent_color == null
890 ? ""
891 : ` accent" style="--accent:#${c.accent_color.toString(16).padStart(6, "0")}`;
892 return `<div class="d-container${spoiler(c)}${accent}">${c.components.map(component).join("")}</div>`;
893 }
894 }
895}
896
897/** the arrow of a button that opens a link */
898const external = `<svg viewBox="0 0 24 24" aria-hidden=true><path d="M14 4h6v6M20 4l-9 9M18 14v6H4V6h6"/></svg>`;
899
900/** Discord markdown, in the parts that text in an embed uses */
901function markdown(text: string): string {
902 const inline = (raw: string) => {
903 // code is set aside so that nothing inside it is formatted
904 const codes: string[] = [];
905 const html = esc(raw).replace(/`([^`]+)`/g, (_, code) => `\0${codes.push(`<code>${code}</code>`) - 1}\0`)
906 .replace(/\[([^\]]+)\]\(https?:\/\/[^\s)]+\)/g, "<span class=link>$1</span>")
907 .replace(/(?<![\w>])https?:\/\/[^\s<]+/g, (url) => `<span class=link>${url}</span>`)
908 .replace(/\*\*\*(.+?)\*\*\*/g, "<b><i>$1</i></b>")
909 .replace(/\*\*(.+?)\*\*/g, "<b>$1</b>")
910 .replace(/__(.+?)__/g, "<u>$1</u>")
911 .replace(/~~(.+?)~~/g, "<s>$1</s>")
912 .replace(/\|\|(.+?)\|\|/g, "<span class=hidden>$1</span>")
913 .replace(/(?<![*\w])[*_](.+?)[*_](?![*\w])/g, "<i>$1</i>");
914 return html.replace(/\0(\d+)\0/g, (_, i) => codes[Number(i)]!);
915 };
916 return text.split(/```\w*\n?([\s\S]*?)```/).map((part, i) => {
917 if (i % 2 === 1) return `<pre>${esc(part.replace(/\n$/, ""))}</pre>`;
918 // a list goes on as the kind that it began as
919 let list: "bullet" | "number" | null = null;
920 return part.split("\n").map((line, n, lines) => {
921 // the line break that ends a block, or sits beside a code block, is not an empty line
922 if (!line && (n === 0 || n === lines.length - 1) && lines.length > 1) return "";
923 const item = /^\s*(?:([-*])|(\d+)\.) (.*)/.exec(line);
924 const was = list;
925 list = item ? list ?? (item[1] ? "bullet" : "number") : null;
926 if (item) {
927 const marker = list === "number" && item[2] ? ` data-n="${item[2]}."` : "";
928 return `<div class="li${marker ? " number" : ""}"${marker}>${inline(item[3]!)}</div>`;
929 }
930 const heading = /^(#{1,3}) (.*)/.exec(line);
931 if (heading) return `<div class=h${heading[1]!.length}>${inline(heading[2]!)}</div>`;
932 const sub = /^-# (.*)/.exec(line);
933 if (sub) return `<div class=sub>${inline(sub[1]!)}</div>`;
934 const quote = /^> ?(.*)/.exec(line);
935 if (quote) return `<div class=quote>${inline(quote[1]!)}</div>`;
936 return `<div>${inline(line) || "<br>"}</div>`;
937 }).join("");
938 }).join("");
939}
940
607941// -- the graph: steps, the code that they run, and the inputs that they read --
608942
609943const canvas = find<HTMLCanvasElement>("canvas");
......@@ -654,6 +988,7 @@ addEventListener("pagehide", () => {
654988 JSON.stringify(
655989 {
656990 ...(!home && { open, maximized, tab }),
991 ...(width && { width }),
657992 folded,
658993 view,
659994 alpha: simulation.alpha,
......@@ -1223,7 +1558,7 @@ function connect() {
12231558 } else {
12241559 status = message[1];
12251560 if (building !== null) live.textContent = title(status.state);
1226 loading = null;
1561 loading = reading = null;
12271562 for (const file of status.changed) {
12281563 const point = points.get(new URL(file, projectUrl || location.href).href);
12291564 if (point) point.state = "changed", point.changed = performance.now();
......@@ -1285,6 +1620,21 @@ function tick() {
12851620button.addEventListener("pointerenter", tick);
12861621button.addEventListener("focus", tick);
12871622// choosing a view keeps the panel open, even one that a build opened
1623// the left edge of the panel is dragged, or moved by the arrow keys, to the width a card is checked at
1624function resize(to: number) {
1625 width = Math.round(Math.min(Math.max(to, 320), innerWidth - 16));
1626 host.style.setProperty("--width", `${width}px`);
1627}
1628grip.addEventListener("pointerdown", (event) => grip.setPointerCapture(event.pointerId));
1629grip.addEventListener("pointermove", (event) => {
1630 if (grip.hasPointerCapture(event.pointerId)) resize(innerWidth - 8 - event.clientX);
1631});
1632grip.addEventListener("keydown", (event) => {
1633 const step = { ArrowLeft: 16, ArrowRight: -16 }[event.key];
1634 if (!step) return;
1635 event.preventDefault();
1636 resize(panel.offsetWidth + (event.shiftKey ? 4 * step : step));
1637});
12881638maximize.addEventListener("click", () => {
12891639 maximized = !maximized;
12901640 open = true;
......@@ -1336,6 +1686,12 @@ shadow.addEventListener("click", (event) => {
13361686});
13371687// a problem folded by hand can change what the button does
13381688shadow.addEventListener("toggle", showFold, true);
1689// an image does not bubble its error, which the shadow root takes in the capture phase
1690shadow.addEventListener("error", ({ target }) => {
1691 if (target instanceof HTMLImageElement && target.dataset.local && target.src !== target.dataset.local) {
1692 target.src = target.dataset.local;
1693 }
1694}, true);
13391695shadow.addEventListener("keydown", (event) => {
13401696 if ((event as KeyboardEvent).key !== "Escape" || panel.hidden) return;
13411697 open = false;
......@@ -1392,9 +1748,12 @@ button:focus-visible{outline:2px solid #0cff10;outline-offset:1px}
13921748.clover[aria-expanded=false]:is(:hover,:focus-visible)~.tip{display:block}
13931749.tip>span{display:block}
13941750
1395.panel{top:8px;right:8px;display:flex;flex-direction:column;width:min(460px,calc(100vw - 16px));
1751.panel{top:8px;right:8px;display:flex;flex-direction:column;width:min(var(--width,460px),calc(100vw - 16px));
13961752 max-height:calc(100vh - 16px)}
13971753.panel.max{left:8px;bottom:8px;width:auto;max-height:none}
1754.grip{position:absolute;left:-3px;top:30px;bottom:0;width:7px;z-index:1;cursor:ew-resize;touch-action:none;pointer-events:auto}
1755.grip:hover,.grip:focus-visible{background:#fff6;outline:0}
1756.panel.max .grip{display:none}
13981757/* the tabs end at the clover, which is the last of them */
13991758.tabs{display:flex;justify-content:flex-end;padding-right:34px}
14001759/* the clover lies under the panel's box, and under the room the tabs leave it */
......@@ -1508,6 +1867,100 @@ canvas{display:block;width:100%;height:min(60vh,480px);cursor:grab;touch-action:
15081867.panel[data-tab=graph] .slot{position:absolute;top:10px;left:10px;right:10px;z-index:1;max-height:45%;
15091868 overflow:hidden;padding:8px 10px;background:#000c;border:2px solid #999}
15101869
1870.cards{display:flex;flex-direction:column;gap:14px}
1871.preview img{display:block;background:#0003}
1872.notes{margin:6px 0 0;padding-left:18px;font-size:12px;line-height:1.45;color:#fcd330}
1873/* the colors of a message in Discord's dark theme, sampled from what it draws */
1874.chat{--text:#f3f3f4;--link:#76aff6;--card:#383a41;--line:#43454c;--bar:#4b4d54;display:grid;gap:4px;padding:12px 16px;
1875 background:#31333a;color:var(--text);font:14px/1.375 "gg sans vf","gg sans","Noto Sans","Helvetica Neue",Helvetica,Arial,sans-serif;
1876 overflow-wrap:anywhere}
1877.discord{--accent:var(--bar);display:grid;gap:8px;width:fit-content;max-width:432px;padding:8px 16px 16px 12px;
1878 border:1px solid var(--line);border-left:4px solid var(--accent);border-radius:4px;background:var(--card)}
1879.d-site{font-size:12px;color:#b5bac1}
1880.d-title{font-size:16px;font-weight:600;line-height:24px;color:var(--link)}
1881.d-desc{line-height:1.25;white-space:pre-wrap}
1882.d-split{display:flex;justify-content:space-between;gap:16px}
1883.d-split>div{display:grid;gap:8px;align-content:start;min-width:0}
1884.d-small{width:80px;height:80px;flex:none;margin-top:2px;border-radius:4px;object-fit:cover}
1885.d-big{width:100%;max-height:300px;border-radius:4px;object-fit:cover}
1886.d-frame{position:relative}
1887.d-frame img{width:100%;max-height:300px;border-radius:4px;object-fit:cover}
1888.play{position:absolute;inset:0;margin:auto;width:48px;height:48px;border-radius:50%;background:#000a}
1889.play::after{content:"";position:absolute;left:19px;top:14px;border:10px solid transparent;border-left:16px solid #fff}
1890.d-gallery{display:grid;grid-template-columns:repeat(6,1fr);gap:4px;width:448px;max-width:100%;overflow:hidden;border-radius:8px}
1891.d-cell{position:relative;grid-column:span 2;aspect-ratio:1;min-height:0;overflow:hidden;border-radius:4px}
1892.d-cell img{position:absolute;inset:0;width:100%;height:100%;object-fit:cover}
1893.n1>.d-cell{grid-column:span 6;aspect-ratio:auto}
1894.n1 img{position:static;height:auto;max-height:350px}
1895.n2>.d-cell,.n5>.d-cell:nth-child(-n+2),.n8>.d-cell:nth-child(-n+2){grid-column:span 3}
1896.n7>.d-cell:first-child,.n10>.d-cell:first-child{grid-column:span 6;aspect-ratio:1.69}
1897.n3,.n4{aspect-ratio:1.71;grid-template-columns:repeat(2,1fr);grid-template-rows:repeat(2,1fr)}
1898.n3>.d-cell,.n4>.d-cell{grid-column:auto;aspect-ratio:auto}
1899.n3{grid-template-columns:2fr 1fr}
1900.n3>:first-child{grid-row:span 2}
1901/* the images of a link are as wide as its card, and lay out differently from a gallery of components */
1902.discord .d-gallery{width:398px}
1903.discord>.d-big,.discord>.d-gallery,.discord>.d-frame{margin-top:8px}
1904.discord .n3,.discord .n4{aspect-ratio:1.33;grid-template-columns:repeat(2,1fr)}
1905.d-container{--accent:var(--bar);position:relative;display:grid;gap:8px;justify-self:start;width:fit-content;max-width:min(100%,482px);
1906 box-sizing:border-box;padding:16px;border:1px solid var(--line);border-radius:8px;background:var(--card)}
1907.d-container.accent::before{content:"";position:absolute;left:-1px;top:-1px;bottom:-1px;width:4px;border-radius:8px 0 0 8px;
1908 background:var(--accent)}
1909.d-section{display:flex;justify-content:space-between;gap:16px}
1910.d-section>:first-child{display:flex;flex-direction:column;justify-content:center;min-width:0}
1911.d-section:has(.d-thumb)>:first-child{justify-content:flex-start}
1912.d-section>:not(:first-child){align-self:flex-start}
1913.d-thumb{width:85px;height:85px;flex:none;border-radius:8px}
1914.d-thumb img{width:100%;height:100%;border-radius:8px;object-fit:cover}
1915.d-row{display:flex;flex-wrap:wrap;gap:8px}
1916.d-button{display:inline-flex;align-items:center;gap:7px;box-sizing:border-box;height:32px;padding:0 12px;border:1px solid #46484f;
1917 border-radius:8px;background:#43454c;color:#fff;font-size:14px;font-weight:500;white-space:nowrap}
1918.d-button.disabled{opacity:.5}
1919.d-button svg{width:18px;height:18px;margin-right:-2px;fill:none;stroke:currentColor;stroke-width:1.8}
1920.emoji{font-size:18px;line-height:1;margin-right:-1px}
1921.d-sep{width:100%;margin:0;border:0;border-top:1px solid #4b4d54}
1922.d-sep.large{margin:8px 0}
1923.d-sep.blank{border-color:transparent}
1924.spoiler{position:relative}
1925.spoiler::before{content:"";position:absolute;inset:0;z-index:1;border-radius:inherit;backdrop-filter:blur(24px) saturate(.5);
1926 background:#80808c8c;pointer-events:none}
1927.spoiler::after{content:"SPOILER";z-index:2;white-space:nowrap;position:absolute;left:50%;top:50%;translate:-50% -50%;padding:7px 12px;border-radius:999px;
1928 background:#282026d1;color:#e4e4e6;font:700 15px/1 "gg sans vf","gg sans",Arial,sans-serif;letter-spacing:.05em;pointer-events:none}
1929.d-text{font-size:14px;line-height:1.375}
1930.d-text>*{min-height:1.375em}
1931.h1,.h2,.h3{margin:16px 0 8px;font-weight:700}
1932.h1{font-size:24px}
1933.h2{font-size:20px}
1934.h3{font-size:16px}
1935.d-text>:first-child{margin-top:0}
1936.link{color:var(--link)}
1937.sub{font-size:12px;color:#b5bac1}
1938.d-text>div:not(.li,.quote)+:is(.li,.quote){margin-top:2px}
1939.li,.quote{position:relative;padding:2px 0 2px 16px}
1940.li::before{content:"";position:absolute;left:3px;top:.62em;width:5px;height:5px;border-radius:50%;background:currentColor}
1941.li.number::before{content:attr(data-n);top:2px;left:0;width:auto;height:auto;border-radius:0;background:none}
1942.quote::before{content:"";position:absolute;left:0;top:2px;bottom:2px;width:4px;border-radius:2px;background:#585a63}
1943.d-text code{padding:0 3px;border:1px solid #4e505e;border-radius:4px;background:#3b3d4e;font:85% ui-monospace,Menlo,Consolas,monospace}
1944.d-text pre{margin:2px 0 19px;padding:7px 8px;border:1px solid #4e505e;border-radius:4px;background:#3d3d4e;
1945 font:14px/18px ui-monospace,Menlo,Consolas,monospace;overflow:auto}
1946.hidden{border-radius:3px;background:#7c7e87;color:transparent}
1947/* a tweet in the dark theme, sampled from what Twitter draws */
1948.tweet{display:grid;gap:4px;padding:12px 16px;background:#000;color:#e7e9ea;font:15px/1.3 system-ui,Arial,sans-serif;
1949 overflow-wrap:anywhere}
1950.x-card{overflow:hidden;border:1px solid #2f3336;border-radius:16px}
1951.x-summary{display:flex}
1952.x-summary>img,.x-blank{width:130px;height:130px;flex:none;border-right:1px solid #2f3336}
1953.x-summary>img{object-fit:cover}
1954.x-blank{display:grid;place-items:center;background:#17181c;color:#71767b}
1955.x-blank svg{width:26px;height:26px;fill:none;stroke:currentColor;stroke-width:2}
1956.x-text{display:grid;gap:2px;align-content:center;min-width:0;padding:12px}
1957.x-domain{font-size:15px;color:#71767b}
1958.x-desc{display:-webkit-box;overflow:hidden;color:#71767b;-webkit-box-orient:vertical;-webkit-line-clamp:2}
1959.x-image{position:relative}
1960.x-image img{width:100%;aspect-ratio:1.91;object-fit:cover}
1961.x-over{position:absolute;left:12px;bottom:12px;max-width:calc(100% - 24px);padding:1px 6px;border-radius:4px;
1962 background:#000c;color:#fff;font-size:13px}
1963
15111964@media (prefers-reduced-motion:reduce){.clover.stale svg{animation:none}.chevron svg{transition:none}}
15121965`;
15131966}
......@@ -1527,5 +1980,6 @@ function clover() {
15271980import { UNWRAP } from "../assert.ts";
15281981import type * as incremental from "../incremental.ts";
15291982import type * as stack from "../log/stack.ts";
1983import * as meta from "../meta.ts";
15301984import * as progress from "../progress.ts";
15311985import * as string from "../string.ts";
lib/meta.test.ts+260
......@@ -446,6 +446,266 @@ describe("extra", () => {
446446 });
447447});
448448
449const component: meta.DiscordComponent = {
450 type: "container",
451 accent_color: 5793266,
452 components: [
453 {
454 type: "section",
455 components: [{ type: "text", content: "# Hi" }],
456 accessory: { type: "thumbnail", media: { url: "/thumb.png" } },
457 },
458 { type: "row", components: [{ type: "button", url: "/store", label: "Store" }] },
459 ],
460};
461
462describe("discord", () => {
463 const payload = (embed: meta.DiscordComponent) => {
464 const { scripts } = meta.toTags(T, { title: "T", discord: embed });
465 assert.equal(scripts.length, 1);
466 assert.equal(scripts[0]!.id, "discord:component-embed");
467 assert.equal(scripts[0]!.type, "application/json");
468 return JSON.parse(scripts[0]!.children as string) as meta.DiscordPayload;
469 };
470
471 test("type names become the numbers that discord reads, and urls are resolved", () => {
472 assert.deepEqual(payload(component), {
473 component: {
474 type: 17,
475 accent_color: 5793266,
476 components: [
477 {
478 type: 9,
479 components: [{ type: 10, content: "# Hi" }],
480 accessory: { type: 11, media: { url: "https://example.com/thumb.png" } },
481 },
482 { type: 1, components: [{ type: 2, style: 5, url: "https://example.com/store", label: "Store" }] },
483 ],
484 },
485 });
486 });
487
488 test("every named type", () => {
489 const { component } = payload({
490 type: "container",
491 components: [
492 { type: "gallery", items: [{ media: { url: "/a.png" } }] },
493 { type: "separator", spacing: 2 },
494 ],
495 });
496 assert.deepEqual(component.components.map((c) => c.type), [12, 14]);
497 });
498
499 test("a number is kept as it is, with its urls resolved", () => {
500 const { component } = payload({
501 type: "container",
502 components: [{ type: 13, file: { url: "/a.pdf" }, name: "x" }],
503 });
504 assert.deepEqual(component.components, [{ type: 13, file: { url: "https://example.com/a.pdf" }, name: "x" }]);
505 });
506
507 test("a container can be written as its number", () => {
508 const { component } = payload({ type: 17, components: [{ type: "text", content: "hi" }] });
509 assert.deepEqual(component, { type: 17, components: [{ type: 10, content: "hi" }] });
510 });
511
512 test("a name discord does not have throws", () => {
513 const embed: meta.DiscordComponent = {
514 type: "container",
515 components: [{ type: "paragraph" as never, content: "x" }],
516 };
517 assert.throws(() => meta.toTags(T, { title: "T", discord: embed }), /no component type "paragraph"/);
518 });
519
520 test("something other than a container at the top throws", () => {
521 assert.throws(
522 () => meta.toTags(T, { title: "T", discord: { type: "text", content: "x" } }),
523 /needs a container/,
524 );
525 });
526
527 test("a string links to the payload", () => {
528 const { links, scripts } = meta.toTags(T, { title: "T", discord: "/embeds/a.json" });
529 assert.ok(
530 links.some((l) =>
531 l.rel === "discord:component-embed" && l.type === "application/json"
532 && l.href === "https://example.com/embeds/a.json"
533 ),
534 );
535 assert.equal(scripts.length, 0);
536 });
537
538 test("the payload cannot close its own script", () => {
539 const out = meta.toHtml(T, {
540 discord: { type: "container", components: [{ type: "text", content: "</script><b>" }] },
541 });
542 assert.equal(out.match(/<\/script>/g)?.length, 1);
543 assert.ok(out.includes(`<script id=discord:component-embed type="application/json">{`));
544 });
545
546 test("a payload over the limit throws, since discord shows nothing for it", () => {
547 const big: meta.DiscordComponent = { type: "container", components: [{ type: "text", content: "x".repeat(3000) }] };
548 assert.throws(() => meta.toTags(T, { title: "T", discord: big }), /over the 3000 limit/);
549 });
550
551 test("null unsets the template's payload", () => {
552 const tags = meta.toTags({ ...T, discord: component }, { title: "T", discord: null });
553 assert.equal(tags.scripts.length, 0);
554 });
555});
556
557describe("discordProblems", () => {
558 const problems = (embed: meta.DiscordComponent) => {
559 const { scripts } = meta.toTags(T, { title: "T", discord: embed });
560 return meta.discordProblems(JSON.parse(scripts[0]!.children as string));
561 };
562
563 test("a payload that toTags wrote is fine", () => {
564 assert.deepEqual(problems(component), []);
565 });
566
567 test("counts components, and gallery items across the embed", () => {
568 const text = { type: "text", content: "x" } as const;
569 assert.match(problems({ type: "container", components: Array(40).fill(text) }).join(), /41 components/);
570 const media = { media: { url: "/a.png" } };
571 const gallery = { type: "gallery", items: Array(6).fill(media) } as const;
572 assert.match(problems({ type: "container", components: [gallery, gallery] }).join(), /12 gallery items/);
573 });
574
575 test("what cannot go where", () => {
576 const text = { type: "text", content: "x" } as const;
577 const nested: meta.DiscordComponent = {
578 type: "container",
579 components: [{ type: "container", components: [text] }],
580 };
581 assert.match(problems(nested).join(), /a container cannot go in a container/);
582 const thumbnail: meta.DiscordComponent = {
583 type: "container",
584 components: [{ type: "thumbnail", media: { url: "/a.png" } }],
585 };
586 assert.match(problems(thumbnail).join(), /a thumbnail cannot go in a container/);
587 const file: meta.DiscordComponent = { type: "container", components: [{ type: 13, file: { url: "/a.pdf" } }] };
588 assert.match(problems(file).join(), /type 13 cannot go in a container/);
589 });
590
591 test("a section holds one to three texts and an accessory", () => {
592 const text = { type: "text", content: "x" } as const;
593 const section = (components: meta.DiscordComponent[], accessory?: meta.DiscordComponent) =>
594 problems({
595 type: "container",
596 components: [{ type: "section", components, accessory: accessory as meta.DiscordComponent }],
597 });
598 const button = { type: "button", url: "/a", label: "A" } as const;
599 assert.deepEqual(section([text], button), []);
600 assert.match(section([text, text, text, text], button).join(), /needs 1 to 3 components/);
601 assert.match(section([text], undefined).join(), /accessory is not a component/);
602 assert.match(section([text], text).join(), /a text cannot go in a accessory/);
603 });
604
605 test("a button is a link with a label or an emoji, and no other keys", () => {
606 const row = (button: Record<string, unknown>) =>
607 problems({ type: "container", components: [{ type: "row", components: [{ type: 2, ...button }] }] });
608 assert.deepEqual(row({ style: 5, url: "https://a.com", label: "A" }), []);
609 assert.deepEqual(row({ style: 5, url: "https://a.com", emoji: { name: "x" } }), []);
610 assert.match(row({ style: 1, url: "https://a.com", label: "A" }).join(), /style must be 5/);
611 assert.match(row({ style: 5, url: "https://a.com" }).join(), /needs a label or an emoji/);
612 assert.match(row({ style: 5, url: "https://a.com", label: "A", custom_id: "x" }).join(), /has custom_id/);
613 assert.match(row({ style: 5, url: "ftp://a.com", label: "A" }).join(), /http\(s\) url/);
614 assert.match(row({ style: 5, url: "https://a.com", label: "A".repeat(81) }).join(), /over 80/);
615 });
616
617 test("values out of range", () => {
618 const text = { type: "text", content: "x" } as const;
619 assert.match(problems({ type: "container", accent_color: 0x1000000, components: [text] }).join(), /accent_color/);
620 assert.match(
621 problems({ type: "container", components: [{ type: "separator", spacing: 3 as 1 }] }).join(),
622 /spacing/,
623 );
624 assert.match(problems({ type: "container", components: [] }).join(), /needs 1 to 40/);
625 });
626
627 test("a payload that is not the shape of one", () => {
628 assert.match(meta.discordProblems({} as meta.DiscordPayload).join(), /is not a component/);
629 assert.match(meta.discordProblems({ component: { type: 17, components: "x" } } as never).join(), /needs 1 to 40/);
630 });
631});
632
633describe("scrape", () => {
634 test("reads back what toTags wrote", () => {
635 const scraped = meta.scrape(meta.toTags(T, {
636 title: "Page",
637 description: "about",
638 canonical: "/page",
639 oEmbed: "/oembed.json",
640 themeColor: "#112233",
641 embed: { thumbnail: "/img.png", thumbnailAlt: "a cat", siteTitle: "Site" },
642 discord: component,
643 }));
644 assert.equal(scraped.title, "Page");
645 assert.equal(scraped.description, "about");
646 assert.equal(scraped.canonical, "https://example.com/page");
647 assert.equal(scraped.oEmbed, "https://example.com/oembed.json");
648 assert.equal(scraped.themeColor, "#112233");
649 assert.deepEqual(scraped.openGraph.image, ["https://example.com/img.png"]);
650 assert.deepEqual(scraped.openGraph["image:alt"], ["a cat"]);
651 assert.deepEqual(scraped.openGraph.site_name, ["Site"]);
652 assert.deepEqual(scraped.twitter.card, ["summary_large_image"]);
653 assert.deepEqual(scraped.twitter.title, ["Page"]);
654 assert.ok(scraped.discord && "text" in scraped.discord);
655 assert.deepEqual(JSON.parse(scraped.discord.text).component.type, 17);
656 });
657
658 test("repeated tags keep their order, empty ones are skipped", () => {
659 const scraped = meta.scrape({
660 meta: [
661 { property: "og:image", content: "a" },
662 { property: "og:image", content: "" },
663 { property: "og:image", content: "b" },
664 { name: "description", content: "first" },
665 { name: "description", content: "second" },
666 { name: "theme-color", content: "#111111" },
667 { name: "theme-color", content: "#222222" },
668 ],
669 links: [],
670 scripts: [],
671 styles: [],
672 });
673 assert.deepEqual(scraped.openGraph.image, ["a", "b"]);
674 assert.equal(scraped.description, "first");
675 assert.equal(scraped.themeColor, "#222222");
676 });
677
678 test("key falls back from name to property, value from content to value", () => {
679 const scraped = meta.scrape({
680 meta: [{ property: "og:title", value: "T" }, { name: "twitter:title", property: "og:title", content: "W" }],
681 links: [],
682 scripts: [],
683 styles: [],
684 });
685 assert.deepEqual(scraped.openGraph.title, ["T"]);
686 assert.deepEqual(scraped.twitter.title, ["W"]);
687 });
688
689 test("a linked payload is the url", () => {
690 const scraped = meta.scrape(meta.toTags(T, { title: "T", discord: "/a.json" }));
691 assert.deepEqual(scraped.discord, { href: "https://example.com/a.json" });
692 });
693
694 test("a page without tags has nothing", () => {
695 const scraped = meta.scrape({ meta: [], links: [], scripts: [], styles: [] });
696 assert.deepEqual(scraped, {
697 title: null,
698 description: null,
699 canonical: null,
700 themeColor: null,
701 oEmbed: null,
702 discord: null,
703 openGraph: {},
704 twitter: {},
705 });
706 });
707});
708
449709// Typescript test for TanStack router compatibility.
450710interface HtmlAttributes {
451711 id?: string;
lib/meta.ts+268-7
......@@ -20,6 +20,12 @@ export interface Meta {
2020 twitter?: Twitter | null;
2121 /** refer to an oEmbed file. See https://oembed.com */
2222 oEmbed?: string | null;
23 /**
24 * replace Discord's link preview with a layout of components, in a `container`.
25 * A string is the url of a JSON file holding it, for what does not fit the inline limit.
26 * Discord falls back to the Open Graph tags, so set `embed` too.
27 */
28 discord?: DiscordComponent | string | null;
2329 /** add arbitrary scripts to the document head */
2430 scripts?: Array<{ content: string } | ExternalScript> | null;
2531 /** add arbitrary styles to the document head */
......@@ -122,6 +128,45 @@ type OpenGraphField =
122128 | { [field: string]: OpenGraphField }
123129 | Array<OpenGraphField>
124130 | (null | undefined);
131/**
132 * A component of a Discord embed, as in
133 * https://docs.discord.com/developers/link-previews/component-embeds. Fields
134 * are Discord's own, and only `type` has names: a number is the component
135 * as Discord has it, for those that are not named here. Relative `url`s are
136 * resolved against `Template.base`.
137 */
138export type DiscordComponent =
139 /** the top level component, and at most 40 components in all */
140 | { type: "container"; components: DiscordComponent[]; accent_color?: number; spoiler?: boolean }
141 /** one to three `text`, and a `thumbnail` or `button` beside them */
142 | { type: "section"; components: DiscordComponent[]; accessory: DiscordComponent }
143 /** Discord markdown */
144 | { type: "text"; content: string }
145 | ({ type: "thumbnail" } & DiscordMedia)
146 /** one to ten items, and at most ten across the whole embed */
147 | { type: "gallery"; items: DiscordMedia[] }
148 | { type: "separator"; divider?: boolean; spacing?: 1 | 2 }
149 /** up to five buttons */
150 | { type: "row"; components: DiscordComponent[] }
151 /** an embed only has link buttons */
152 | {
153 type: "button";
154 url: string;
155 label?: string;
156 emoji?: { id?: string; name?: string; animated?: boolean };
157 disabled?: boolean;
158 }
159 | { type: number; [field: string]: unknown };
160export interface DiscordMedia {
161 media: { url: string };
162 description?: string | null;
163 spoiler?: boolean;
164}
165/** what Discord reads: the container of a `DiscordComponent`, with numbers for types */
166export interface DiscordPayload {
167 component: { type: 17; components: Array<{ type: number; [field: string]: unknown }>; [field: string]: unknown };
168}
169
125170/** Twitter uses various OpenGraph fields if these are not specified. */
126171export interface Twitter {
127172 card: string;
......@@ -180,6 +225,7 @@ export function toTags(template: Template, meta: Meta): Tags {
180225
181226 const alternates = pick(meta.alternates, template.alternates);
182227 const oEmbed = pick(meta.oEmbed, template.oEmbed);
228 const discord = pick(meta.discord, template.discord);
183229 const embed = pick(meta.embed, template.embed);
184230 let openGraph = pick(meta.openGraph, template.openGraph);
185231 let twitter = pick(meta.twitter, template.twitter);
......@@ -241,6 +287,9 @@ export function toTags(template: Template, meta: Meta): Tags {
241287 if (canonical) links.push({ rel: "canonical", href: canonical });
242288 if (manifest) links.push({ rel: "manifest", href: manifest });
243289 if (oEmbed) links.push({ rel: "alternate", type: "application/json+oembed", href: resolve(oEmbed) });
290 if (typeof discord === "string") {
291 links.push({ rel: discordRel, type: "application/json", href: resolve(discord) });
292 }
244293 if (alternates) {
245294 const items = Array.isArray(alternates)
246295 ? alternates
......@@ -259,6 +308,18 @@ export function toTags(template: Template, meta: Meta): Tags {
259308 const scriptTags: Array<Record<string, string | boolean>> = [];
260309 const styleTags: Array<Record<string, string>> = [];
261310
311 if (discord && typeof discord === "object") {
312 const component = discordWire(discord, resolve) as DiscordPayload["component"];
313 if (component.type !== 17) throw new Error("discord needs a container as its top level component");
314 // `<` is escaped so that the payload cannot close its own script, and still counts toward the limit in full
315 const children = JSON.stringify({ component }).replaceAll("<", "\\u003c");
316 const bytes = new TextEncoder().encode(children).length;
317 if (bytes > discordLimit) {
318 throw new Error(`discord component embed is ${bytes} bytes, over the ${discordLimit} limit`);
319 }
320 scriptTags.push({ id: discordRel, type: "application/json", children });
321 }
322
262323 for (const entry of pick(meta.scripts, template.scripts) ?? []) {
263324 if ("content" in entry) {
264325 scriptTags.push({ children: String(entry.content) });
......@@ -306,7 +367,7 @@ export function toHtml(template: Template, meta: Meta): string {
306367 const tags = toTags(template, meta);
307368 let out = "";
308369 for (const attrs of tags.meta) {
309 if (Object.keys(attrs).length === 1 && "title" in attrs) {
370 if (isTitle(attrs)) {
310371 out += `<title>${esc(attrs.title!)}</title>`;
311372 } else {
312373 out += `<meta` + Object.entries(attrs).map(([k, v]) => ` ${k}=${attr(v)}`).join("") + `>`;
......@@ -315,12 +376,8 @@ export function toHtml(template: Template, meta: Meta): string {
315376 for (const attrs of tags.links) {
316377 out += `<link` + Object.entries(attrs).map(([k, v]) => ` ${k}=${attr(v)}`).join("") + `>`;
317378 }
318 for (const entry of tags.scripts) {
319 if ("children" in entry) {
320 out += `<script>${entry.children}</script>`;
321 } else {
322 out += `<script` + serializeAttrs(entry) + `></script>`;
323 }
379 for (const { children = "", ...rest } of tags.scripts) {
380 out += `<script` + serializeAttrs(rest) + `>${children}</script>`;
324381 }
325382 for (const entry of tags.styles) {
326383 if ("children" in entry) {
......@@ -331,6 +388,210 @@ export function toHtml(template: Template, meta: Meta): string {
331388 return out;
332389}
333390
391/**
392 * the inverse of `toTags`: the tags of a parsed document. Give it a document
393 * from `DOMParser` to see the page as a crawler does, since none of them run
394 * scripts. Only the bodies of inline json scripts and styles are read.
395 */
396export function readTags(root: ParentNode): Tags {
397 const attrs = (element: Element) => Object.fromEntries(Array.from(element.attributes, (a) => [a.name, a.value]));
398 const withText = (element: Element) => ({ ...attrs(element), children: element.textContent ?? "" });
399 const meta = Array.from(root.querySelectorAll("meta"), attrs);
400 const title = root.querySelector("title");
401 if (title) meta.unshift({ title: title.textContent ?? "" });
402 return {
403 meta,
404 links: Array.from(root.querySelectorAll("link"), attrs),
405 scripts: Array.from(root.querySelectorAll("script"), (element) => {
406 return element.src === "" && /json/.test(element.type) ? withText(element) : attrs(element);
407 }),
408 styles: Array.from(root.querySelectorAll("style"), withText),
409 };
410}
411
412/** what the tags of a document say, by the names that crawlers look for them under */
413export interface Scraped {
414 title: string | null;
415 description: string | null;
416 canonical: string | null;
417 /** the last one, as Discord reads it */
418 themeColor: string | null;
419 /** the url of the oEmbed json */
420 oEmbed: string | null;
421 /** the payload of a component embed, as inline text or the url that holds it */
422 discord: { text: string } | { href: string } | null;
423 /** the values of `og:*` tags, by the rest of the name, in document order */
424 openGraph: Record<string, string[]>;
425 /** the values of `twitter:*` tags, the same way */
426 twitter: Record<string, string[]>;
427}
428
429/** the inverse of toTags */
430export function scrape(tags: Tags): Scraped {
431 const scraped: Scraped = {
432 title: null,
433 description: null,
434 canonical: null,
435 themeColor: null,
436 oEmbed: null,
437 discord: null,
438 openGraph: {},
439 twitter: {},
440 };
441 for (const attrs of tags.meta) {
442 if (isTitle(attrs)) {
443 scraped.title ??= attrs.title!;
444 continue;
445 }
446 const key = attrs.name ?? attrs.property;
447 const value = attrs.content ?? attrs.value;
448 if (!key || !value) continue;
449 if (key === "description") scraped.description ??= value;
450 else if (key === "theme-color") scraped.themeColor = value;
451 else if (key.startsWith("og:")) (scraped.openGraph[key.slice(3)] ??= []).push(value);
452 else if (key.startsWith("twitter:")) (scraped.twitter[key.slice(8)] ??= []).push(value);
453 }
454 for (const link of tags.links) {
455 if (link.rel === "canonical") scraped.canonical = link.href ?? null;
456 else if (link.type === "application/json+oembed") scraped.oEmbed ??= link.href ?? null;
457 else if (link.rel === discordRel && link.href) scraped.discord = { href: link.href };
458 }
459 for (const script of tags.scripts) {
460 if (script.id === discordRel && typeof script.children === "string") scraped.discord = { text: script.children };
461 }
462 return scraped;
463}
464
465/** `toTags` puts the title among the meta tags as an entry of nothing else */
466function isTitle(attrs: Record<string, string>): boolean {
467 return Object.keys(attrs).length === 1 && "title" in attrs;
468}
469
470const discordRel = "discord:component-embed";
471/** bytes of an inline payload, which Discord drops the embed over */
472const discordLimit = 3000;
473
474const discordTypes = {
475 row: 1,
476 button: 2,
477 section: 9,
478 text: 10,
479 thumbnail: 11,
480 gallery: 12,
481 separator: 14,
482 container: 17,
483};
484
485/** a component as Discord reads it: type names are numbers, a button is a link, and every `url` is resolved */
486function discordWire(value: unknown, resolve: (url: string) => string): unknown {
487 if (Array.isArray(value)) return value.map((item) => discordWire(item, resolve));
488 if (value === null || typeof value !== "object") return value;
489 const { type, ...fields } = value as Record<string, unknown>;
490 const wire = Object.fromEntries(
491 Object.entries(fields).map((
492 [k, v],
493 ) => [k, k === "url" && typeof v === "string" ? resolve(v) : discordWire(v, resolve)]),
494 );
495 if (typeof type !== "string") return type === undefined ? wire : { type, ...wire };
496 if (!Object.hasOwn(discordTypes, type)) throw new Error(`discord has no component type "${type}"`);
497 return { type: discordTypes[type as keyof typeof discordTypes], ...(type === "button" && { style: 5 }), ...wire };
498}
499
500const buttonKeys = new Set(["id", "type", "url", "style", "label", "emoji", "disabled"]);
501/** what a component of each kind may hold, by where it is */
502const discordChildren = { top: [17], container: [1, 9, 10, 12, 14], section: [10], accessory: [2, 11], row: [2] };
503
504/**
505 * how a payload breaks the rules of component embeds, which make Discord
506 * leave the embed out. It reads what a page holds, so it trusts nothing about
507 * its shape.
508 */
509export function discordProblems({ component }: DiscordPayload): string[] {
510 const problems: string[] = [];
511 let components = 0;
512 let items = 0;
513 const name = (type: number) => Object.entries(discordTypes).find(([, n]) => n === type)?.[0] ?? `type ${type}`;
514
515 const media = (m: any, at: string) => {
516 const url = m?.media?.url;
517 if (typeof url !== "string" || !/^https?:\/\//.test(url) || url.length > 2048) {
518 problems.push(`${at}.media.url must be an http(s) url of at most 2048 characters`);
519 }
520 if (typeof m?.description === "string" && m.description.length > 1024) {
521 problems.push(`${at}.description is over 1024 characters`);
522 }
523 };
524
525 const visit = (c: any, at: string, within: keyof typeof discordChildren) => {
526 if (typeof c?.type !== "number") return void problems.push(`${at} is not a component`);
527 components++;
528 if (!discordChildren[within].includes(c.type)) {
529 problems.push(`${at}: a ${name(c.type)} cannot go ${within === "top" ? "at the top" : `in a ${within}`}`);
530 }
531 const list = (key: string, min: number, max: number, child: keyof typeof discordChildren) => {
532 const children = c[key];
533 if (!Array.isArray(children) || children.length < min || children.length > max) {
534 return void problems.push(`${at}.${key} needs ${min} to ${max} components`);
535 }
536 children.forEach((item, i) => visit(item, `${at}.${key}[${i}]`, child));
537 };
538 switch (c.type) {
539 case 17:
540 list("components", 1, 40, "container");
541 if (
542 c.accent_color != null
543 && !(c.accent_color >= 0 && c.accent_color <= 0xffffff && Number.isInteger(c.accent_color))
544 ) {
545 problems.push(`${at}.accent_color must be an integer from 0 to 16777215`);
546 }
547 break;
548 case 9:
549 list("components", 1, 3, "section");
550 visit(c.accessory, `${at}.accessory`, "accessory");
551 break;
552 case 1:
553 list("components", 1, 5, "row");
554 break;
555 case 2: {
556 const extra = Object.keys(c).filter((key) => !buttonKeys.has(key));
557 if (extra.length > 0) {
558 problems.push(`${at} has ${extra.join(", ")}, and any key but ${[...buttonKeys].join(", ")} voids the embed`);
559 }
560 if (c.style !== 5) problems.push(`${at}.style must be 5, a link`);
561 if (typeof c.url !== "string" || !/^https?:\/\//.test(c.url) || c.url.length > 512) {
562 problems.push(`${at}.url must be an http(s) url of at most 512 characters`);
563 }
564 if (!c.label && !c.emoji) problems.push(`${at} needs a label or an emoji`);
565 if (typeof c.label === "string" && c.label.length > 80) problems.push(`${at}.label is over 80 characters`);
566 break;
567 }
568 case 10:
569 if (typeof c.content !== "string") problems.push(`${at}.content must be a string`);
570 break;
571 case 11:
572 media(c, at);
573 break;
574 case 12:
575 if (!Array.isArray(c.items) || c.items.length < 1 || c.items.length > 10) {
576 problems.push(`${at}.items needs 1 to 10 items`);
577 } else {
578 items += c.items.length;
579 c.items.forEach((item: unknown, i: number) => media(item, `${at}.items[${i}]`));
580 }
581 break;
582 case 14:
583 if (c.spacing != null && c.spacing !== 1 && c.spacing !== 2) problems.push(`${at}.spacing must be 1 or 2`);
584 if (c.divider != null && typeof c.divider !== "boolean") problems.push(`${at}.divider must be a boolean`);
585 break;
586 }
587 };
588
589 visit(component, "component", "top");
590 if (components > 40) problems.push(`${components} components, at most 40`);
591 if (items > 10) problems.push(`${items} gallery items, at most 10 across the embed`);
592 return problems;
593}
594
334595function serializeAttrs(attrs: Record<string, string | boolean>): string {
335596 let out = "";
336597 for (const [k, v] of Object.entries(attrs)) {
lib/progress.ts+4-4
......@@ -1558,7 +1558,7 @@ class Encoder<
15581558 k,
15591559 v: node.value !== 0 ? node.value : undefined,
15601560 e: node.total !== 0 ? node.total : undefined,
1561 t: node.text.length > 0 ? node.text : undefined,
1561 t: node.text,
15621562 l: node.logs.length > 0
15631563 ? (this.logsLength.set(node, node.logs.length), this.redactLogsIfNeeded(node.logs.slice()))
15641564 : undefined,
......@@ -1676,9 +1676,9 @@ class Decoder<
16761676 updateChildren.push({ key, children });
16771677 }
16781678 if (node) {
1679 if (text) node.text = text;
1680 if (value) node.value = value;
1681 if (total) node.total = total;
1679 if (text != null) node.text = text;
1680 if (value != null) node.value = value;
1681 if (total != null) node.total = total;
16821682 if (showTotal != null) node.showTotal = showTotal;
16831683 if (passive != null) node.passive = passive;
16841684 if (hidden != null) node.hidden = hidden;
lib/readme.changes.md+7
......@@ -31,6 +31,13 @@
3131 - finally fixes resize corruptions for long running widgets
3232- `string/ansi`: add `inverse`, `resetInverse`, and `cursorHome`.
3333- `meta` auto-embed will now set `twitter:url`.
34- `meta.discord` adds a Discord component embed, inline or as a link to its
35 json. Components are Discord's own json with `type` named (`"container"`,
36 `"section"`, `"text"`, ...), or a number for any other. `meta.discordProblems`
37 checks a payload against the rules that make Discord leave an embed out.
38 `meta.readTags` reads the tags of a parsed document and `meta.scrape` reads
39 them back into what they say, which the `incremental/visualization` `meta` tab
40 uses to draw the Discord and Twitter cards of a page.
3441- `progress.attachToDocument` draws progress in the browser, and
3542 `progress.formatHtml` renders the same markup for server rendering.
3643- `ts.DeepReadonly`
lib/readme.md+1
......@@ -25,6 +25,7 @@ depend on each other. there are no external dependencies; code is easy to audit.
2525- `log/stack` - stack trace parse and formatter
2626- `Lru` - least recently used cache
2727- `math` - trivial helpers
28- `meta` - head tags from a page's metadata, and back from a parsed document
2829- `mime` - trimmed database of ext -> mime types
2930- `node` - tree-shakable loaders for Node.js builtins
3031- `progress` - cli and dom progress bars, nesting status indication
lib/string.ts+2-2
......@@ -73,7 +73,7 @@ export function formatByteSize(bytes: number): string {
7373 do {
7474 bytes /= 1000;
7575 unit += 1;
76 } while (bytes >= 1000);
76 } while (bytes >= 1000 && unit < byteUnits.length);
7777 return prefix + (unit === 1
7878 ? String(+bytes.toFixed(bytes > 100 ? 1 : 2))
7979 : bytes.toFixed(
......@@ -90,7 +90,7 @@ export function formatBinaryByteSize(bytes: number): string {
9090 do {
9191 bytes /= 1024;
9292 unit += 1;
93 } while (bytes >= 1024);
93 } while (bytes >= 1024 && unit < byteUnits.length);
9494 return prefix + (Math.round(bytes * 100) / 100)
9595 + byteUnits.charAt(unit - 1) + "iB";
9696}
src/pages/index.marko+22-6
......@@ -1,14 +1,31 @@
1import type { Meta } from "#meta";
1import type { Meta } from "@clo/lib/meta";
22import "./index.css";
33
44export const theme = { bg: "#fff0fb", fg: "#558", primary: "#7947c9" };
5/* first on google for "clover caruso" and "paper clover" */
56export const meta = {
67 title: "paper clover / clover caruso",
78 author: "clover caruso",
8 description:
9 "and then we knew, just like paper airplanes: that we could fly...",
9 description: "clover caruso's museum. the home of her music, videos, rest of life, etc.",
1010 embed: {
11 /* Default embed */
11 description: "and then we knew, just like paper airplanes: that we could fly...",
12 },
13 discord: {
14 type: "container",
15 accent_color: 0xabebe2, // theme.primary
16 components: [
17 {
18 type: "text",
19 content: "## paper clover\nand then we knew, just like paper airplanes: that we could fly... <:lex_aw:1169487238216822814>\n",
20 },
21 {
22 type: "row",
23 components: [
24 { type: "button", label: "questions and answers", url: "/q+a", emoji: { name: "❓" } },
25 { type: "button", label: "in the summer", url: "/in-the-summer", emoji: { name: "🌴" } },
26 ],
27 },
28 ],
1229 },
1330 alternates: {
1431 "application/rss+xml": "rss.xml",
......@@ -60,7 +77,6 @@ export const meta = {
6077 </ul>
6178 </nav>
6279
63 <p>website run by clover caruso. alive since '04.</p>
64 // <p>was run by clover caruso. alive from '04 to '??.</p>
80 <p style="font-size:90%">&copy; 2026. no other site hosting my content is official except bandcamp/kofi.</p>
6581 </div>
6682</main>
src/pages/resume.marko+10-4
......@@ -4,14 +4,20 @@ export const meta = { title: "clover's resume" };
44
55<main>
66 <h1>clover's resume</h1>
7 <div>last updated: 2025</div>
7 <div>last updated: 2026</div>
88
99 <article.job>
1010 <header>
11 <h2>web/backend engineer</h2>
11 <h2>web/application engineer</h2>
1212 <em>2025-now</em>
13 <p>research lab</p>
1314 </header>
14 <ul><i>(more details added as time goes on...)</i></ul>
15 <ul>
16 <li>quality assurance / adding "aura" to products</li>
17 <li>tuning ai systems to actually work (why doesn't anyone else do this?)</li>
18 <li>as hardcore as typescript engineering can get</li>
19 <li>also helping pop the bubble by burning 4B tokens per day</li>
20 </ul>
1521 </article>
1622
1723 <article.job>
......@@ -23,7 +29,7 @@ export const meta = { title: "clover's resume" };
2329 <ul>
2430 <li>hardcore engineering, elegant solutions</li>
2531 <li>platform compatibility & stability</li>
26 <li>debugging and profiling across platforms</li>
32 <li>debugging and profiling across stacks and platforms</li>
2733 </ul>
2834 </article>
2935
src/q+a/backend.ts+20-9
......@@ -105,7 +105,7 @@ app.post("/q+a", async (c) => {
105105
106106 if (ipAddr && PROXYCHECK_API_KEY) {
107107 const proxyCheck = await fetch(
108 `https://proxycheck.io/v2/?key=${PROXYCHECK_API_KEY}&risk=1&vpn=1`,
108 `https://proxycheck.io/v3/?key=${PROXYCHECK_API_KEY}`,
109109 {
110110 method: "POST",
111111 body: "ips=" + ipAddr,
......@@ -116,17 +116,28 @@ app.post("/q+a", async (c) => {
116116 ).then((res) => res.json());
117117
118118 if (ipAddr && proxyCheck[ipAddr]) {
119 trace.proxy = proxyCheck[ipAddr].proxy;
120 trace.risk = proxyCheck[ipAddr].risk;
121 const risk = Number(proxyCheck[ipAddr].risk);
119 const { detections, network, operator } = proxyCheck[ipAddr];
120 trace.detections = detections;
121 trace.risk = detections?.risk;
122
123 const risk = Number(detections?.risk);
122124 if (Number.isFinite(risk)) input.sourceRisk = risk;
123 if (proxyCheck[ipAddr].proxy === "yes") {
124 input.sourceVPN = proxyCheck[ipAddr].operator?.name
125 ?? proxyCheck[ipAddr].organisation
126 ?? proxyCheck[ipAddr].provider ?? "unknown";
125 // hosting is any datacenter address, which no person is browsing from at home
126 if (detections?.proxy || detections?.vpn || detections?.tor || detections?.hosting) {
127 input.sourceVPN = operator?.name ?? network?.organisation ?? network?.provider ?? "unknown";
127128 trace.sourceVPN = input.sourceVPN;
128129 }
129 if (Number(proxyCheck[ipAddr].risk) > 78) {
130
131 if (detections?.hosting && c.req.header("x-discord-user-id")) {
132 trace.discordId = c.req.header("x-discord-user-id");
133 input.sourceName = uniqueNamesGenerator({
134 dictionaries: [adjectives, colors, animals],
135 separator: "-",
136 seed: String(trace.discordId),
137 });
138 input.sourceVPN = "Discord"
139 trace.sourceVPN = input.sourceVPN;
140 } else if (risk > 78) {
130141 return respond(
131142 "high-risk",
132143 await questionFailure(
src/q+a/models/questions.ts+1-1
......@@ -31,8 +31,8 @@ export type PendingData = {
3131 prompt: string;
3232 sourceName: string | "unknown";
3333 sourceLocation: string | "unknown";
34 /** proxy/provider/host/vpn name */
3435 sourceVPN: string | null;
35 /** proxycheck risk score, 0-100. absent before 2026-10-24, and when proxycheck is not configured */
3636 sourceRisk?: number | null;
3737 /** value of the "i am a robot" honeypot checkbox, null when not sent. absent before 2026-10-24 */
3838 robot?: string | null;
src/q+a/views/backend-inbox.marko+1-1
......@@ -21,7 +21,7 @@ export const meta = { title: "question answer inbox" };
2121 <div style="color: dodgerblue; margin-bottom: 0.25rem">
2222 ${q.sourceName}${
2323 q.sourceLocation !== "unknown" ? `from ${q.sourceLocation}` : ""
24 }${q.sourceVPN ? `(VPN: ${q.sourceVPN})` : ""}${
24 }${q.sourceVPN ? `(${q.sourceVPN})` : ""}${
2525 q.sourceRisk ? ` (risk: ${q.sourceRisk})` : ""
2626 }
2727 </div>
src/static/sitemap.xml created+17
......@@ -0,0 +1,17 @@
1<?xml version="1.0" encoding="UTF-8"?>
2<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
3 <url><loc>https://paperclover.net/</loc></url>
4 <url><loc>https://paperclover.net/dream</loc></url>
5 <url><loc>https://paperclover.net/history-of-japan-reanimated</loc></url>
6 <url><loc>https://paperclover.net/in-the-summer</loc></url>
7 <url><loc>https://paperclover.net/license</loc></url>
8 <url><loc>https://paperclover.net/log</loc></url>
9 <url><loc>https://paperclover.net/q+a</loc></url>
10 <url><loc>https://paperclover.net/resume</loc></url>
11 <url><loc>https://paperclover.net/subscribe</loc></url>
12 <url><loc>https://paperclover.net/waterfalls</loc></url>
13 <url><loc>https://paperclover.net/blog/community-translations</loc></url>
14 <url><loc>https://paperclover.net/blog/webdev/one-year-next-app-router/en</loc></url>
15 <url><loc>https://paperclover.net/blog/webdev/one-year-next-app-router/es</loc></url>
16 <url><loc>https://paperclover.net/blog/webdev/one-year-next-app-router/ko</loc></url>
17</urlset>