Public: anyone can read this; the crew can change it.

/explore shows each app's latest picture as a fixed-size thumbnail beside its name #14731

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/14560-explore-shows-each-app-s-latest-picture → main 4 commits fork 5 threads · 5 unresolved

  • Merged. scout/14560-explore-shows-each-app-s-latest-picture was merged into main as 71710b3.

Review

Sign in to review this change.
7 files changed +224 −4
docs/design/areas/explore.md +4
@@ -14,3 +14,7 @@ A row is its name, what it does, and one signal (the phrase `whyOf` gives), with
1414 A fork whose parent is listed folds under the parent's row: `.row-forks` is a `<details>` in the row's
1515 `after` slot, its summary the count ("2 forks"), its body the same `list` of rows, ranked as the page is.
1616 It needs no script, and the summary keeps the 44px tap height and has the same focus-visible outline as `.sort-toggle`. The nested list is indented 8px, so a row keeps its width at 360px; each nested row keeps its own "Make it yours". It is a part of the row (`rowOf`'s `after` slot), not a new component. The how-to is in docs/features/explore.md.
17
18 ## A picture beside each app (#14560)
19
20 An app's row leads with `.ex-pic`, a fixed 48px box (`row-lead` slot, no new component): the newest public production look of its home page (`looks/explore_pictures.ts`, one query for the whole page, forks included), an `<img>` lazy-loaded with the app's name as alt text; or, with no look, a private app or a picture taken as the owner, a `<span>` with the name's initial. Both are the same size, so a row never shifts. People and forges have no box.
docs/features/explore.md +4
@@ -116,3 +116,7 @@ answer `invalid` naming the argument; a page searches the first 200 characters,
116116 keeps them in the box and says so in one line. No link a page builds back to
117117 itself (the sign-in and sign-up `next`, the palette's Sign in) carries more
118118 than that, so a 5,000-character paste does not bloat the page.
119
120 ## A picture beside each app
121
122 Each app row leads with a small picture of its newest public look, so you see what it is before you read about it. An app with no look, or a private one, shows a box with its initial. The terminal's explore list has no pictures.
src/looks/explore_pictures.ts added +77
@@ -0,0 +1,77 @@
1 /**
2 * The picture /explore shows beside an app: its newest public look at the home page, for many
3 * apps in one read. Only what a stranger may see: the app is public and the picture was taken as
4 * nobody, so the answer is the same for every viewer and a private app never has one.
5 */
6
7 import type { Database } from "bun:sqlite";
8 import { existsSync } from "node:fs";
9 import { join } from "node:path";
10 import { DEFAULT_THEME, lookUrl, type Look, type LookKind } from "../core/looks.ts";
11 import { keepLook } from "./service.ts";
12
13 interface Found {
14 readonly repo_id: string;
15 readonly env: string;
16 readonly commit_oid: string;
17 readonly kind: LookKind;
18 readonly created_at: string;
19 readonly path: string;
20 }
21
22 const CHUNK = 400;
23
24 /**
25 * Repository id to the URL of that app's newest production thumb (the phone shot when there is no
26 * thumb). One query per 400 repositories; an app with none is absent from the map. `paths` maps
27 * each repository id to its `/owner/name` path.
28 */
29 export function exploreThumbs(
30 db: Pick<Database, "query">,
31 dataDir: string,
32 paths: ReadonlyMap<string, string>,
33 ): Map<string, string> {
34 const out = new Map<string, string>();
35 const unique = [...paths.keys()];
36 for (let i = 0; i < unique.length; i += CHUNK) {
37 const batch = unique.slice(i, i + CHUNK);
38 // Light, home page, no error, not attached by a person: `page = '/'` leaves out the dark and
39 // 360 px rows, which are filed under a prefixed page (`core/looks.ts`).
40 const rows = db
41 .query<Found, string[]>(
42 `SELECT a.repo_id, l.env, l.commit_oid, l.kind, l.created_at, l.path
43 FROM app a JOIN look l ON l.app_id = a.id
44 WHERE a.repo_id IN (${batch.map((_, n) => `?${n + 1}`).join(",")})
45 AND a.access = 'public' AND l.env = 'production' AND l.page = '/'
46 AND l.theme = 'light' AND l.kind IN ('thumb','phone')
47 AND l.error IS NULL AND l.attached_by IS NULL AND l.taken_as = 'nobody'
48 ORDER BY l.created_at DESC`,
49 )
50 .all(...batch);
51 // Newest first; a thumb is preferred to a phone shot, and a picture is taken only when its
52 // file is there and the image route would serve it to anyone (`keepLook`).
53 const byRepo = new Map<string, Found[]>();
54 for (const row of rows) byRepo.set(row.repo_id, [...(byRepo.get(row.repo_id) ?? []), row]);
55 for (const [repoId, list] of byRepo) {
56 const base = paths.get(repoId);
57 if (base === undefined) continue;
58 const ranked = [...list.filter((r) => r.kind === "thumb"), ...list.filter((r) => r.kind !== "thumb")];
59 for (const row of ranked) {
60 const look = {
61 env: row.env,
62 commitOid: row.commit_oid,
63 page: "/",
64 kind: row.kind,
65 theme: DEFAULT_THEME,
66 createdAt: row.created_at,
67 path: row.path,
68 error: null,
69 } as Look;
70 if (!existsSync(join(dataDir, row.path)) || !keepLook(dataDir, look)) continue;
71 out.set(repoId, lookUrl(base, look));
72 break;
73 }
74 }
75 }
76 return out;
77 }
src/web/studio/explore.ts +31 −3
@@ -27,6 +27,7 @@ import {
2727 type ExploreQuery,
2828 type ExploreRow,
2929 } from "../../actions/explore.ts";
30 import { exploreThumbs } from "../../looks/explore_pictures.ts";
3031 import { frontWeights, type FrontWeights } from "../../core/front.ts";
3132 import { notePhase, takeSessionTime } from "../../core/route_timing.ts";
3233 import type { Ctx } from "../../http/context.ts";
@@ -44,8 +45,32 @@ const href = (query: ExploreQuery, page = 1): string => {
4445 return text === "" ? "/explore" : `/explore?${text}`;
4546 };
4647
47 function rowHtml(row: ExploreRow, query: ExploreQuery, now: number, weights: FrontWeights): Html {
48 /** Repository id to `/owner/name` for every app on the page, forks folded under a row included. */
49 function pathsOf(rows: readonly ExploreRow[], into = new Map<string, string>()): Map<string, string> {
50 for (const r of rows) {
51 if (r.repo !== undefined) into.set(r.repo.id, `/${r.repo.owner}/${r.repo.name}`);
52 pathsOf(r.forked ?? [], into);
53 }
54 return into;
55 }
56
57 /**
58 * The fixed box beside an app's name: its newest public picture, lazy-loaded with the app's name
59 * as alt text, or a neutral box with its initial. Same size either way, so a row never shifts.
60 */
outdated

The initial is taken from row.name (owner/name), so every app of one owner gets the same letter. Use the app's own name.

61 function pictureOf(row: ExploreRow, pictures: ReadonlyMap<string, string>): Html | undefined {
62 if (row.kind !== "app") return undefined;
63 const src = row.repo === undefined ? undefined : pictures.get(row.repo.id);
64 if (src !== undefined) return html`<img class="ex-pic" width="48" height="48" src="${src}" alt="${row.name}" loading="lazy" />`;
65 // The app's own name, not `owner/name`: every app of one owner would share a letter.
66 const own = row.repo?.name ?? row.name.slice(row.name.lastIndexOf("/") + 1);
67 const initial = [...own.trim()][0]?.toUpperCase() ?? "?";
68 return html`<span class="ex-pic" aria-hidden="true">${initial}</span>`;
69 }
70
71 function rowHtml(row: ExploreRow, query: ExploreQuery, now: number, weights: FrontWeights, pictures: ReadonlyMap<string, string>): Html {
4872 const why = whyOf(row, query.sort, now, weights);
73 const picture = pictureOf(row, pictures);
4974 // One row: what it does in plain words, then the one signal that explains its place.
5075 // Apps say their counts and keep the dated `<time>`: the absolute date stays in its title.
5176 const parts0 = figureParts(row, query.sort);
@@ -70,9 +95,10 @@ function rowHtml(row: ExploreRow, query: ExploreQuery, now: number, weights: Fro
7095 : {
7196 after: html`<details class="row-forks" data-forks>
7297 <summary class="muted small">${forked.length} fork${forked.length === 1 ? "" : "s"}</summary>
73 <ul class="list">${forked.map((f) => rowHtml(f, query, now, weights))}</ul>
98 <ul class="list">${forked.map((f) => rowHtml(f, query, now, weights, pictures))}</ul>
7499 </details>`,
75100 }),
101 ...(picture === undefined ? {} : { lead: picture }),
76102 title: html`<a href="${row.url}">${row.name}</a>${nameMark(row.mark)}`,
77103 ...(parts.length === 0 ? {} : { meta: metaHtml }),
78104 ...(row.copyable === true && row.repo !== undefined
@@ -244,6 +270,8 @@ export async function explorePage(ctx: Ctx): Promise<Response> {
244270 // Old `?cursor=` links were published; they cannot name a page now, so say so.
245271 const oldLink = ctx.url.searchParams.has("cursor");
246272 const weights = frontWeights(ctx.app.db);
273 // Every thumbnail in one read, for the rows and the forks folded under them.
274 const pictures = exploreThumbs(ctx.app.db, ctx.app.config.dataDir, pathsOf(rows));
247275 notePhase(ctx.request, "read", performance.now() - ranking);
248276 const rendering = performance.now();
249277 const now = Date.now();
@@ -342,7 +370,7 @@ export async function explorePage(ctx: Ctx): Promise<Response> {
342370 <p class="mb small">${countLine(query, shown.total, ctx.auth.user?.isAdmin === true)}</p>
343371 ${rows.length === 0
344372 ? emptyState(ctx, query)
345 : card(html`<ul class="list">${rows.map((r) => rowHtml(r, query, now, weights))}</ul>`, {
373 : card(html`<ul class="list">${rows.map((r) => rowHtml(r, query, now, weights, pictures))}</ul>`, {
346374 pad: false,
347375 extra: "bare",
348376 })}${pager(query, shown.page, shown.pages)}</div>`;
src/web/style/components.ts +3
@@ -564,6 +564,9 @@ a.row:hover .row-title { color: var(--accent); }
564564 .row-facts .row-links a { display: inline-flex; align-items: center; min-height: 44px; }
565565 .row-meta .avatar { width: 16px; height: 16px; font-size: var(--fs-min); vertical-align: -0.28em; }
566566 .row-meta .byline-name { margin-left: 4px; }
567 /* /explore: an app's picture, a fixed 48px box either way, so a row never shifts. */
568 .ex-pic { width: 48px; height: 48px; border-radius: 6px; object-fit: cover; object-position: top; background: var(--muted); }
outdated

Principle 6 and tokens: --surface-2 and --border do not exist, so this renders a currentColor border and no fill. Use real tokens (see docs/DESIGN.md) or drop the border.

569 span.ex-pic { display: inline-flex; align-items: center; justify-content: center; font-weight: 600; color: var(--muted-fg); }
567570 .row-lead { color: var(--faint); display: inline-flex; flex: none; }
568571 /* A control beside a link row, outside the link: the row takes the width, the control keeps its own. */
569572 .list > li.has-after { display: flex; align-items: center; flex-wrap: wrap; }
test/explore-first-view.test.ts +1 −1
@@ -62,7 +62,7 @@ describe("/explore first view", () => {
6262 const from = html.indexOf('class="list"');
6363 const list = html.slice(from, html.indexOf("</ul>", from));
6464 expect((list.match(/class="row"/g) ?? []).length).toBe(12);
65 expect(list.length / 12).toBeLessThan(520); // the figures line adds ~35 bytes a row (#13483)
65 expect(list.length / 12).toBeLessThan(580); // figures line ~35 bytes a row (#13483); the picture box is its lead slot plus a 47-byte span, 76 in all (#14560), not looser than that
outdated

Raising the per-row byte budget by 100 weakens the guard for every row. Keep the box smaller (shorter markup) or justify the number.

6666 });
6767
6868 test("the rows come in the ranking's order", () => {
test/explore-picture.test.ts added +104
@@ -0,0 +1,104 @@
1 /**
2 * /explore shows each app's newest public look in a fixed 48px box beside its name, lazy-loaded
3 * with the app's name as alt text; an app with no look, or a private one, gets a neutral box with
4 * its initial. All pictures are read in one query.
5 */
6 import { afterAll, beforeAll, expect, test } from "bun:test";
7 import { mkdirSync, writeFileSync } from "node:fs";
8 import { mkdtemp, rm } from "node:fs/promises";
9 import { tmpdir } from "node:os";
10 import { join } from "node:path";
11 import { createApp, type App } from "../src/app.ts";
12 import { newApp } from "../src/actions/apps.ts";
13 import { recordLook } from "../src/core/looks.ts";
14 import { getAppByRepo } from "../src/core/apps.ts";
15 import { getRepo } from "../src/core/repos.ts";
16 import { createUser } from "../src/core/users.ts";
17 import { exploreThumbs } from "../src/looks/explore_pictures.ts";
18 import { serve, type Servers } from "../src/http/server.ts";
19 import { quietLogs } from "./helpers/globals.ts";
20
21 quietLogs();
22
23 let dir: string;
24 let app: App;
25 let servers: Servers;
26 const oid = (c: string) => c.repeat(40);
27
28 function look(repoName: string, o: { kind?: "thumb" | "phone"; takenAs?: "owner" | "nobody"; commit: string; env?: string }) {
29 const rec = getAppByRepo(app.db, getRepo(app.db, "alice", repoName)!.id)!;
30 const path = `looks/${repoName}-${o.commit}.png`;
31 mkdirSync(join(dir, "looks"), { recursive: true });
32 writeFileSync(join(dir, path), "png");
33 recordLook(app.db, { appId: rec.id, env: o.env ?? "production", commitOid: oid(o.commit), kind: o.kind ?? "thumb", path, takenAs: o.takenAs ?? "nobody" });
34 }
35
36 beforeAll(async () => {
37 dir = await mkdtemp(join(tmpdir(), "forge-explore-picture-"));
38 app = createApp({ dataDir: dir, port: 0 });
39 servers = await serve(app);
40 const made = await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
41 if (!made.ok) throw new Error(String(made.error));
42 for (const [name, visibility] of [["pictured", "public"], ["bare", "public"], ["hidden", "private"], ["ownershot", "public"], ["tricky", "public"]] as const) {
43 const r = await newApp(app, made.value, { name, description: name, visibility });
44 if (!r.ok) throw new Error(String(r.error));
45 }
46 look("pictured", { commit: "a" });
47 look("pictured", { commit: "b" });
48 // A newer picture whose file is gone is passed over for the one behind it.
49 recordLook(app.db, { appId: getAppByRepo(app.db, getRepo(app.db, "alice", "bare")!.id)!.id, env: "production", commitOid: oid("f"), kind: "thumb", path: "looks/gone.png", takenAs: "nobody" });
50 look("hidden", { commit: "c" });
51 look("ownerShot".toLowerCase(), { commit: "d", takenAs: "owner" });
52 look("tricky", { commit: "e" });
53 // A name that would break out of an attribute if it were not escaped.
54 app.db.query("UPDATE repo SET name = ?1 WHERE name = 'tricky'").run('t"><b>x');
55 }, 60_000);
56 afterAll(async () => {
57 servers.stop();
58 app.close();
59 await rm(dir, { recursive: true, force: true });
60 });
61
62 const page = () => fetch(`${servers.url}/explore?q=${encodeURIComponent("kind:app")}`).then((r) => r.text());
63 const rowOf = (html: string, name: string) => html.split("<li").find((r) => r.includes(`>alice/${name}<`)) ?? "";
64
65 test("an app with a look shows its newest public picture, fixed size and lazy, alt naming the app", async () => {
66 const row = rowOf(await page(), "pictured");
67 expect(row).toMatch(/<img class="ex-pic" width="48" height="48" src="\/alice\/pictured\/looks\/production\/[0-9a-f]{40}\/thumb\.png\?v=\d+" alt="alice\/pictured" loading="lazy"/);
68 });
69
70 test("no look, a private app and an owner-only look show the neutral box with the initial", async () => {
71 const html = await page();
72 expect(rowOf(html, "bare")).toContain('<span class="ex-pic" aria-hidden="true">B</span>');
73 // The initial is the app's own name, not the owner's.
74 expect(rowOf(html, "ownershot")).not.toContain("<img");
75 expect(rowOf(html, "ownershot")).toContain('<span class="ex-pic"');
76 expect(html).not.toContain("alice/hidden");
77 });
78
79 test("the alt text is escaped", async () => {
80 const html = await page();
81 expect(html).not.toContain('alt="alice/t"><b>');
82 expect(html).toContain('alt="alice/t&quot;&gt;&lt;b&gt;x"');
83 });
84
85 test("a signed-out viewer fetches the picture the row names and gets 200", async () => {
86 const src = /<img class="ex-pic" width="48" height="48" src="([^"]+)"/.exec(rowOf(await page(), "pictured"))?.[1];
87 expect(src).toBeDefined();
88 const res = await fetch(`${servers.url}${src}`);
89 expect(res.status).toBe(200);
90 expect(res.headers.get("content-type")).toBe("image/png");
91 await res.arrayBuffer();
92 });
93
94 test("every thumbnail is one query, and a private app has none", () => {
95 const rows = app.db.query<{ id: string; name: string }, []>("SELECT id, name FROM repo").all();
96 const seen: string[] = [];
97 const counting = { query: ((sql: string) => (seen.push(sql), app.db.query(sql))) as typeof app.db.query };
98 const found = exploreThumbs(counting, dir, new Map(rows.map((r) => [r.id, `/o/${r.id}`])));
99 expect(seen.filter((s) => /JOIN look/i.test(s)).length).toBe(1);
100 const byName = new Map(rows.map((r) => [r.name, r.id]));
101 expect(found.has(byName.get("pictured")!)).toBe(true);
102 expect(found.has(byName.get("hidden")!)).toBe(false);
103 expect(found.has(byName.get("bare")!)).toBe(false);
104 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs