A calm place to write long-form, and publish it to the open social web.
skypress.blog/
Add implementation plan: reading-page author focus
author
Jeremy Herve
date
(Jun 9, 2026, 9:50 PM +0200)
commit
0563c848
0563c8480366f0fc97caafe3299add0912885a9e
parent
9689ef17
9689ef17b315b9f2899f011ec00b72c12c187802
+469
1 changed file
docs
superpowers
+469
docs/superpowers/plans/2026-06-09-reading-page-author-focus.md
+469
docs/superpowers/plans/2026-06-09-reading-page-author-focus.md
···
1
1
+
# Reading-page author focus — Implementation Plan
2
2
+
3
3
+
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
4
+
5
5
+
**Goal:** Refocus the reading pages on the publication and its author — drop SkyPress branding from the headers and render dates in a long English format.
6
6
+
7
7
+
**Architecture:** A new pure `formatLongDate` helper handles dates. The publication page loses its header; the single-post page swaps the SkyPress logo for the publication's logo+title (header) and the publication name for the author's avatar/name/handle (eyebrow). Page behaviour is pinned with source-level regex tests in the existing colocated `_*.meta.test.ts` files (page rendering isn't unit-testable in this jsdom suite).
8
8
+
9
9
+
**Tech Stack:** Astro (SSR pages), TypeScript, Vitest, `Intl.DateTimeFormat`.
10
10
+
11
11
+
Design: `docs/superpowers/specs/2026-06-09-reading-page-author-focus-design.md`
12
12
+
13
13
+
---
14
14
+
15
15
+
## File structure
16
16
+
17
17
+
- Create: `src/lib/reader/dates.ts` — pure `formatLongDate(iso)` long-English formatter.
18
18
+
- Create: `src/lib/reader/dates.test.ts` — unit tests for the formatter.
19
19
+
- Modify: `src/pages/[author]/[slug]/index.astro` — remove header, long dates.
20
20
+
- Modify: `src/pages/[author]/[slug]/_index.meta.test.ts` — pin header-removal + date.
21
21
+
- Modify: `src/pages/[author]/[slug]/[rkey].astro` — publication header, author eyebrow, long dates.
22
22
+
- Modify: `src/pages/[author]/[slug]/_[rkey].meta.test.ts` — pin new header + eyebrow + date.
23
23
+
24
24
+
---
25
25
+
26
26
+
## Task 1: Long-date helper
27
27
+
28
28
+
**Files:**
29
29
+
- Create: `src/lib/reader/dates.ts`
30
30
+
- Test: `src/lib/reader/dates.test.ts`
31
31
+
32
32
+
- [ ] **Step 1: Write the failing test**
33
33
+
34
34
+
Create `src/lib/reader/dates.test.ts`:
35
35
+
36
36
+
```ts
37
37
+
import { describe, expect, it } from 'vitest';
38
38
+
import { formatLongDate } from './dates';
39
39
+
40
40
+
describe( 'formatLongDate', () => {
41
41
+
it( 'formats an ISO datetime as a long English date', () => {
42
42
+
expect( formatLongDate( '2026-06-09T12:00:00Z' ) ).toBe( 'June 9, 2026' );
43
43
+
} );
44
44
+
45
45
+
it( 'pins the calendar day to UTC regardless of time-of-day', () => {
46
46
+
// Late-evening UTC must not roll forward to the 10th.
47
47
+
expect( formatLongDate( '2026-06-09T23:30:00Z' ) ).toBe( 'June 9, 2026' );
48
48
+
// Early-morning UTC must not roll back to the 8th.
49
49
+
expect( formatLongDate( '2026-06-09T00:30:00Z' ) ).toBe( 'June 9, 2026' );
50
50
+
} );
51
51
+
52
52
+
it( 'accepts a date-only string', () => {
53
53
+
expect( formatLongDate( '2026-12-25' ) ).toBe( 'December 25, 2026' );
54
54
+
} );
55
55
+
} );
56
56
+
```
57
57
+
58
58
+
- [ ] **Step 2: Run test to verify it fails**
59
59
+
60
60
+
Run: `npm run test -- src/lib/reader/dates.test.ts`
61
61
+
Expected: FAIL — cannot resolve `./dates` (module not found).
62
62
+
63
63
+
- [ ] **Step 3: Write minimal implementation**
64
64
+
65
65
+
Create `src/lib/reader/dates.ts`:
66
66
+
67
67
+
```ts
68
68
+
/**
69
69
+
* Format an ISO date/datetime as a long English date, e.g. "June 9, 2026".
70
70
+
*
71
71
+
* The reading pages are server-rendered and the UI is English, so we render a
72
72
+
* fixed `en-US` long format rather than negotiating the reader's locale (which
73
73
+
* would need client JS — disallowed on the read path). `timeZone: 'UTC'` pins
74
74
+
* the rendered calendar day so a late-evening UTC timestamp can't roll to the
75
75
+
* next day on a server in a western zone.
76
76
+
*/
77
77
+
const longDate = new Intl.DateTimeFormat( 'en-US', {
78
78
+
dateStyle: 'long',
79
79
+
timeZone: 'UTC',
80
80
+
} );
81
81
+
82
82
+
export function formatLongDate( iso: string ): string {
83
83
+
return longDate.format( new Date( iso ) );
84
84
+
}
85
85
+
```
86
86
+
87
87
+
- [ ] **Step 4: Run test to verify it passes**
88
88
+
89
89
+
Run: `npm run test -- src/lib/reader/dates.test.ts`
90
90
+
Expected: PASS (3 tests).
91
91
+
92
92
+
- [ ] **Step 5: Commit**
93
93
+
94
94
+
```bash
95
95
+
git add src/lib/reader/dates.ts src/lib/reader/dates.test.ts
96
96
+
git commit --no-gpg-sign -m "Add formatLongDate reader helper"
97
97
+
```
98
98
+
99
99
+
---
100
100
+
101
101
+
## Task 2: Publication page — remove header, long dates
102
102
+
103
103
+
**Files:**
104
104
+
- Modify: `src/pages/[author]/[slug]/index.astro`
105
105
+
- Test: `src/pages/[author]/[slug]/_index.meta.test.ts`
106
106
+
107
107
+
- [ ] **Step 1: Write the failing test**
108
108
+
109
109
+
Append these two `describe` blocks to `src/pages/[author]/[slug]/_index.meta.test.ts` (after the existing blocks, before the final newline):
110
110
+
111
111
+
```ts
112
112
+
describe( 'publication page focuses on the publication', () => {
113
113
+
it( 'no longer renders the SkyPress masthead/logo', () => {
114
114
+
expect( page ).not.toMatch( /class="masthead"/ );
115
115
+
expect( page ).not.toMatch( /import Logo from/ );
116
116
+
} );
117
117
+
118
118
+
it( 'renders article dates in long format via formatLongDate', () => {
119
119
+
expect( page ).toMatch(
120
120
+
/import\s*\{\s*formatLongDate\s*\}\s*from\s*'[^']*lib\/reader\/dates'/
121
121
+
);
122
122
+
expect( page ).toMatch( /formatLongDate\(/ );
123
123
+
// The old ISO-slice date format is gone.
124
124
+
expect( page ).not.toMatch( /publishedAt\?\.slice\(\s*0,\s*10\s*\)/ );
125
125
+
} );
126
126
+
} );
127
127
+
```
128
128
+
129
129
+
- [ ] **Step 2: Run test to verify it fails**
130
130
+
131
131
+
Run: `npm run test -- "src/pages/[author]/[slug]/_index.meta.test.ts"`
132
132
+
Expected: FAIL — masthead/Logo still present, `formatLongDate` not imported.
133
133
+
134
134
+
- [ ] **Step 3: Implement the changes**
135
135
+
136
136
+
In `src/pages/[author]/[slug]/index.astro`:
137
137
+
138
138
+
a) Remove the `Logo` import line:
139
139
+
140
140
+
```astro
141
141
+
import Logo from '../../../components/Logo.astro';
142
142
+
```
143
143
+
144
144
+
b) Add the `formatLongDate` import after the `fetchActorProfile` import:
145
145
+
146
146
+
```astro
147
147
+
import { formatLongDate } from '../../../lib/reader/dates';
148
148
+
```
149
149
+
150
150
+
c) Change the article date mapping. Replace:
151
151
+
152
152
+
```astro
153
153
+
publishedLabel: record.value.publishedAt?.slice( 0, 10 ) ?? null,
154
154
+
```
155
155
+
156
156
+
with:
157
157
+
158
158
+
```astro
159
159
+
publishedLabel: record.value.publishedAt
160
160
+
? formatLongDate( record.value.publishedAt )
161
161
+
: null,
162
162
+
```
163
163
+
164
164
+
d) Remove the entire header block:
165
165
+
166
166
+
```astro
167
167
+
<header class="masthead">
168
168
+
<a href="/"><Logo /></a>
169
169
+
</header>
170
170
+
171
171
+
```
172
172
+
173
173
+
e) Remove the now-unused masthead CSS rules from the `<style>` block:
174
174
+
175
175
+
```css
176
176
+
.masthead {
177
177
+
padding: 1.5rem clamp(1.25rem, 5vw, 4rem);
178
178
+
border-bottom: 1px solid var(--line);
179
179
+
}
180
180
+
.masthead a {
181
181
+
text-decoration: none;
182
182
+
}
183
183
+
```
184
184
+
185
185
+
- [ ] **Step 4: Run tests + check**
186
186
+
187
187
+
Run: `npm run test -- "src/pages/[author]/[slug]/_index.meta.test.ts"`
188
188
+
Expected: PASS (all blocks, including the two new ones).
189
189
+
190
190
+
Run: `npm run check`
191
191
+
Expected: no type/astro errors.
192
192
+
193
193
+
- [ ] **Step 5: Commit**
194
194
+
195
195
+
```bash
196
196
+
git add "src/pages/[author]/[slug]/index.astro" "src/pages/[author]/[slug]/_index.meta.test.ts"
197
197
+
git commit --no-gpg-sign -m "Drop SkyPress header and use long dates on publication page"
198
198
+
```
199
199
+
200
200
+
---
201
201
+
202
202
+
## Task 3: Single post page — publication header + author eyebrow + long dates
203
203
+
204
204
+
**Files:**
205
205
+
- Modify: `src/pages/[author]/[slug]/[rkey].astro`
206
206
+
- Test: `src/pages/[author]/[slug]/_[rkey].meta.test.ts`
207
207
+
208
208
+
- [ ] **Step 1: Write the failing test**
209
209
+
210
210
+
Append this `describe` block to `src/pages/[author]/[slug]/_[rkey].meta.test.ts` (after the existing block):
211
211
+
212
212
+
```ts
213
213
+
describe( 'document page focuses on publication + author', () => {
214
214
+
it( 'replaces the SkyPress logo header with the publication logo + title linking to the publication', () => {
215
215
+
expect( page ).not.toMatch( /import Logo from/ );
216
216
+
expect( page ).not.toMatch( /<a href="\/"><Logo \/><\/a>/ );
217
217
+
expect( page ).toMatch( /class="masthead__pub"\s+href=\{pubUrl\}/ );
218
218
+
expect( page ).toMatch( /class="masthead__title">\{publication!?\.name\}/ );
219
219
+
} );
220
220
+
221
221
+
it( 'fetches the author profile for the eyebrow', () => {
222
222
+
expect( page ).toMatch(
223
223
+
/import\s*\{\s*fetchActorProfile\s*\}\s*from\s*'[^']*lib\/reader\/profile'/
224
224
+
);
225
225
+
expect( page ).toMatch( /fetchActorProfile\(/ );
226
226
+
} );
227
227
+
228
228
+
it( 'shows the author (name, avatar, handle) in the eyebrow, linked to the profile', () => {
229
229
+
expect( page ).toMatch( /class="reader__author"\s+href=\{`\/@\$\{\s*handle\s*\}`\}/ );
230
230
+
expect( page ).toMatch( /reader__avatar/ );
231
231
+
expect( page ).toMatch( /authorName/ );
232
232
+
// The publication name no longer stands in for the byline in the eyebrow.
233
233
+
expect( page ).not.toMatch( /class="reader__author"\s+href=\{pubUrl\}/ );
234
234
+
} );
235
235
+
236
236
+
it( 'renders dates in long format via formatLongDate', () => {
237
237
+
expect( page ).toMatch(
238
238
+
/import\s*\{\s*formatLongDate\s*\}\s*from\s*'[^']*lib\/reader\/dates'/
239
239
+
);
240
240
+
expect( page ).toMatch( /formatLongDate\(/ );
241
241
+
expect( page ).not.toMatch( /\.slice\(\s*0,\s*10\s*\)/ );
242
242
+
} );
243
243
+
} );
244
244
+
```
245
245
+
246
246
+
- [ ] **Step 2: Run test to verify it fails**
247
247
+
248
248
+
Run: `npm run test -- "src/pages/[author]/[slug]/_[rkey].meta.test.ts"`
249
249
+
Expected: FAIL — Logo import present, no `masthead__pub`, no `fetchActorProfile`, no `formatLongDate`.
250
250
+
251
251
+
- [ ] **Step 3: Implement the changes**
252
252
+
253
253
+
In `src/pages/[author]/[slug]/[rkey].astro`:
254
254
+
255
255
+
a) Remove the `Logo` import line:
256
256
+
257
257
+
```astro
258
258
+
import Logo from '../../../components/Logo.astro';
259
259
+
```
260
260
+
261
261
+
b) Add these imports after the `resolveReaderPublication` import:
262
262
+
263
263
+
```astro
264
264
+
import { fetchActorProfile } from '../../../lib/reader/profile';
265
265
+
import { formatLongDate } from '../../../lib/reader/dates';
266
266
+
```
267
267
+
268
268
+
c) Add new top-level `let` declarations alongside the existing ones (after `let updatedLabel: string | null = null;`):
269
269
+
270
270
+
```astro
271
271
+
let authorName = '';
272
272
+
let authorHandle: string | null = null;
273
273
+
let authorAvatar: string | null = null;
274
274
+
let logoUrl: string | null = null;
275
275
+
let initial = '';
276
276
+
```
277
277
+
278
278
+
d) In the success branch (the `else` after `record.value` is validated), set the author + logo values. Add, right after `themeStyle = themeStyleBlock( publication.basicTheme );`:
279
279
+
280
280
+
```astro
281
281
+
const profile = await fetchActorProfile( pdsUrl, did );
282
282
+
authorName = profile.displayName ?? `@${ handle }`;
283
283
+
// Only show a separate @handle chip when there's a distinct display name.
284
284
+
authorHandle = profile.displayName ? `@${ handle }` : null;
285
285
+
authorAvatar = profile.avatar;
286
286
+
logoUrl = publication.icon
287
287
+
? buildGetBlobUrl( pdsUrl, did, publication.icon.ref.$link )
288
288
+
: null;
289
289
+
initial = publication.name.charAt( 0 ).toUpperCase();
290
290
+
```
291
291
+
292
292
+
e) Change the date labels. Replace:
293
293
+
294
294
+
```astro
295
295
+
publishedLabel = doc.publishedAt ? doc.publishedAt.slice( 0, 10 ) : null;
296
296
+
updatedLabel = doc.updatedAt ? doc.updatedAt.slice( 0, 10 ) : null;
297
297
+
```
298
298
+
299
299
+
with:
300
300
+
301
301
+
```astro
302
302
+
publishedLabel = doc.publishedAt ? formatLongDate( doc.publishedAt ) : null;
303
303
+
updatedLabel = doc.updatedAt ? formatLongDate( doc.updatedAt ) : null;
304
304
+
```
305
305
+
306
306
+
f) Replace the header block. Replace:
307
307
+
308
308
+
```astro
309
309
+
<header class="masthead">
310
310
+
<a href="/"><Logo /></a>
311
311
+
</header>
312
312
+
```
313
313
+
314
314
+
with:
315
315
+
316
316
+
```astro
317
317
+
<header class="masthead">
318
318
+
<a class="masthead__pub" href={pubUrl}>
319
319
+
{logoUrl ? (
320
320
+
<img class="masthead__logo" src={logoUrl} alt="" width="36" height="36" />
321
321
+
) : (
322
322
+
<span class="masthead__logo masthead__logo--fallback" aria-hidden="true">{initial}</span>
323
323
+
)}
324
324
+
<span class="masthead__title">{publication!.name}</span>
325
325
+
</a>
326
326
+
</header>
327
327
+
```
328
328
+
329
329
+
g) Replace the eyebrow block. Replace:
330
330
+
331
331
+
```astro
332
332
+
<p class="reader__meta eyebrow">
333
333
+
<a class="reader__author" href={pubUrl}>{publication!.name}</a>
334
334
+
{publishedLabel && <> · {publishedLabel}</>}
335
335
+
{updatedLabel && <> · updated {updatedLabel}</>}
336
336
+
· {readingMinutes} min read
337
337
+
</p>
338
338
+
```
339
339
+
340
340
+
with:
341
341
+
342
342
+
```astro
343
343
+
<p class="reader__meta eyebrow">
344
344
+
<a class="reader__author" href={`/@${ handle }`}>
345
345
+
{authorAvatar && (
346
346
+
<img class="reader__avatar" src={authorAvatar} alt="" width="22" height="22" />
347
347
+
)}
348
348
+
<span class="reader__authorname">{authorName}</span>
349
349
+
{authorHandle && <span class="reader__handle">{authorHandle}</span>}
350
350
+
</a>
351
351
+
{publishedLabel && <> · {publishedLabel}</>}
352
352
+
{updatedLabel && <> · updated {updatedLabel}</>}
353
353
+
· {readingMinutes} min read
354
354
+
</p>
355
355
+
```
356
356
+
357
357
+
h) Update the `<style>` block. Add the publication-header styles right after the existing `.masthead a { text-decoration: none; }` rule:
358
358
+
359
359
+
```css
360
360
+
.masthead__pub {
361
361
+
display: inline-flex;
362
362
+
align-items: center;
363
363
+
gap: 0.6rem;
364
364
+
color: var(--ink);
365
365
+
}
366
366
+
.masthead__logo {
367
367
+
width: 36px;
368
368
+
height: 36px;
369
369
+
border-radius: 9px;
370
370
+
object-fit: cover;
371
371
+
background: var(--paper-raised);
372
372
+
}
373
373
+
.masthead__logo--fallback {
374
374
+
display: inline-flex;
375
375
+
align-items: center;
376
376
+
justify-content: center;
377
377
+
font-family: var(--font-display);
378
378
+
font-weight: 700;
379
379
+
color: var(--sun);
380
380
+
background: var(--sun-tint);
381
381
+
}
382
382
+
.masthead__title {
383
383
+
font-family: var(--font-display);
384
384
+
font-weight: 700;
385
385
+
font-size: 1.18rem;
386
386
+
letter-spacing: -0.015em;
387
387
+
}
388
388
+
```
389
389
+
390
390
+
Then replace the existing `.reader__author` rule:
391
391
+
392
392
+
```css
393
393
+
.reader__author {
394
394
+
color: var(--sun);
395
395
+
text-decoration: none;
396
396
+
}
397
397
+
```
398
398
+
399
399
+
with:
400
400
+
401
401
+
```css
402
402
+
.reader__author {
403
403
+
display: inline-flex;
404
404
+
align-items: center;
405
405
+
gap: 0.4rem;
406
406
+
color: var(--ink-soft);
407
407
+
text-decoration: none;
408
408
+
}
409
409
+
.reader__author:hover {
410
410
+
color: var(--sun);
411
411
+
}
412
412
+
.reader__avatar {
413
413
+
width: 22px;
414
414
+
height: 22px;
415
415
+
border-radius: 50%;
416
416
+
object-fit: cover;
417
417
+
}
418
418
+
.reader__handle {
419
419
+
color: var(--muted);
420
420
+
}
421
421
+
```
422
422
+
423
423
+
- [ ] **Step 4: Run tests + check**
424
424
+
425
425
+
Run: `npm run test -- "src/pages/[author]/[slug]/_[rkey].meta.test.ts"`
426
426
+
Expected: PASS (existing OG/error blocks + the new focus block).
427
427
+
428
428
+
Run: `npm run check`
429
429
+
Expected: no type/astro errors. (In particular `Logo` must be gone with no remaining references.)
430
430
+
431
431
+
- [ ] **Step 5: Commit**
432
432
+
433
433
+
```bash
434
434
+
git add "src/pages/[author]/[slug]/[rkey].astro" "src/pages/[author]/[slug]/_[rkey].meta.test.ts"
435
435
+
git commit --no-gpg-sign -m "Show publication header and author byline on single post page"
436
436
+
```
437
437
+
438
438
+
---
439
439
+
440
440
+
## Task 4: Full verification
441
441
+
442
442
+
- [ ] **Step 1: Run the whole test suite**
443
443
+
444
444
+
Run: `npm run test`
445
445
+
Expected: all suites PASS (no regressions in render, sanitize, meta, etc.).
446
446
+
447
447
+
- [ ] **Step 2: Type/astro check**
448
448
+
449
449
+
Run: `npm run check`
450
450
+
Expected: clean.
451
451
+
452
452
+
- [ ] **Step 3: Build smoke**
453
453
+
454
454
+
Run: `npm run build`
455
455
+
Expected: build succeeds (the read pages are `prerender = false`, so this confirms no import-time breakage).
456
456
+
457
457
+
---
458
458
+
459
459
+
## Self-review notes
460
460
+
461
461
+
- **Spec coverage:** header removal (Task 2d/e), publication header swap (Task 3f/h),
462
462
+
author eyebrow (Task 3d/g/h), long dates both pages (Tasks 2c, 3e + helper Task 1).
463
463
+
All four design goals mapped.
464
464
+
- **No-JS constraint:** the date helper runs at SSR time; no client script added.
465
465
+
- **Profile degradation:** `fetchActorProfile` returns nulls (never throws) on failure,
466
466
+
so a missing profile yields `authorName = @handle`, no avatar, no separate handle chip —
467
467
+
the page still renders.
468
468
+
- **Type consistency:** `authorName`/`authorHandle`/`authorAvatar`/`logoUrl`/`initial`
469
469
+
declared in Task 3c, assigned in 3d, consumed in 3f/3g.