Add a Featured Writing section to the home page, hand-ordered from Notion

[ooloth]

Why

A first-time visitor's impression of the writing is set by whatever happened to be published last, not by the posts that best represent the site. The home page has no way to promote a post, so a strong older piece is buried under whatever is newest.

Current state

app/(home)/page.tsx renders <Summary /> followed by <RecentWriting /> and nothing else. ui/sections/home-recent-writing.tsx renders <PostList limit={5} />, and ui/sections/blog-post-list.tsx:30 fetches all posts sorted by First published descending, then slices the first 5. Of the 37 published blog posts, the home page therefore shows the 5 newest and offers no mechanism to surface anything else.

The Notion Writing data source now has a Featured order number property, populated on three posts:

Featured order	First published	Title
1	2024-07-29	Why unknown types are useful
2	2021-05-31	Using Slack to report data entry errors to content editors
3	2024-12-27	Converting a list of JS objects into a parent-child tree

Every other page reports number: null for the property. No code reads it yet.

Ideal state

• A Featured Writing section renders above Recent Writing on the home page, using the same h2 treatment and the same date-above-title row markup, so the two sections differ only in their headings.
• The section lists every published blog post whose Featured order is set, in ascending order of that number.
• Featured order behaves as a sort key rather than a position: gaps between values, sets that do not start at 1, and values in any numeric range all render in ascending order with no warning and no error.
• Two posts sharing the same Featured order render most-recently-published first relative to each other, so the rendered order is deterministic.
• Recent Writing shows the 5 most recent published posts that are not already featured above, so no post appears twice on the page.
• The Featured Writing section, heading included, is absent from the page when no post has a Featured order.
• /blog lists every published post, featured ones included, exactly as it does today.
• Changing which posts are featured, or the order they appear in, requires a Notion edit and a redeploy and no code change.

Out of scope

• A scheduled rebuild so Notion edits reach production without running npm run deploy:production. Reordering will still need a deploy.
• Any visual difference between featured rows and recent rows: no descriptions, images, badges, or alternate typography. Matching them is the point.
• Any change to /blog, the RSS feed, the sitemap, or prev/next post navigation.
• Any cap on how many posts can be featured at once. That is controlled in Notion.
• Moving the getPosts call out of ui/layout/header.tsx, tracked in Move getPosts call out of ui/layout/header into the page entry point #59 and Header layout fetches Notion posts directly instead of receiving them as props #155.

Starting points

• ui/sections/home-recent-writing.tsx — the section whose markup and typography the new section matches
• io/notion/schemas/post.ts — PostPropertiesSchema and PostListItemSchema, where the new property is parsed at the boundary
• app/(home)/page.tsx — where the single getPosts call and the split between featured and recent belong

QA plan

1. Run npm run cache:clear:notion, then npm run dev, and open http://localhost:3000. Expect a Featured Writing heading above Recent Writing, indistinguishable from it in size, weight, colour, and spacing.
2. Read the featured rows. Expect exactly three, in this order: Why unknown types are useful, Using Slack to report data entry errors to content editors, Converting a list of JS objects into a parent-child tree. Note that this is deliberately not date order.
3. Read the recent rows. Expect Converting a list of JS objects into a parent-child tree to be absent, since it is featured above and was previously the second row. Expect 5 rows still, with It's tricky to statically type a "pipe" function in Python now the last of them.
4. In Notion, set Why unknown types are useful to 3 and Converting a list of JS objects into a parent-child tree to 1. Run npm run cache:clear:notion and reload. Expect the featured order to follow the new numbers.
5. In Notion, change the three values to 10, 20, and 30. Clear the cache and reload. Expect the same three posts in the same relative order, with no warning in the terminal and no error on the page.
6. In Notion, give two featured posts the same number. Clear the cache and reload. Expect both to render, the more recently published one first, and the build to keep working.
7. In Notion, clear Featured order on all three posts. Clear the cache and reload. Expect no Featured Writing heading anywhere on the page, and Recent Writing to show the 5 newest posts including Converting a list of JS objects into a parent-child tree.
8. Restore the original values 1, 2, 3 and run npm run build. Expect a clean build, and out/index.html to contain both headings.
9. Narrow the browser to 390px. Expect featured rows to stack date above title exactly as the recent rows do.

Done when

The home page renders a Featured Writing section ordered by the Notion Featured order property, and Recent Writing shows only posts not already featured above it.

Depends on

• Move getPosts call out of ui/sections/blog-post-list into the page entry point #60 — PostList has to accept an already-fetched posts prop before the home page can render two different lists from a single getPosts call.

[ooloth]

Agreed design

Recorded after /discuss and /design. Approved by @ooloth before implementation.

Type story

unknown[]                                       Notion API pages
  ↓ PostPropertiesSchema.safeParse()
PostProperties { 'Featured order': number | null, ... }
  ↓ PostListItemSchema.safeParse()
PostListItem { featuredOrder: number | null, ... }
  ↓ partitionPostsByFeatured()
{ featured: readonly FeaturedPost[], unfeatured: readonly PostListItem[] }
  ↓ app/(home)/page.tsx applies the recent limit
<FeaturedWriting posts={featured} /> + <RecentWriting posts={unfeatured.slice(0, 5)} />

FeaturedPost = Omit<PostListItem, 'featuredOrder'> & { featuredOrder: number }. The non-null field is not decoration: it makes the sort comparator total, so no null branch and no non-null assertion.

Rejected: making PostListItem a discriminated union of featured and unfeatured. The discriminant would be a second representation of a fact featuredOrder already carries, and it would force the sitemap, RSS route, header nav, prev/next navigation, and getPost to discriminate on a field none of them read.

partitionPostsByFeatured

Lives in io/notion/, alongside schemas/post.ts, since it is a pure operation on Notion post data.

Sorts featured ascending by featuredOrder, ties broken by firstPublished descending. Both keys are compared explicitly rather than relying on Array.prototype.sort stability plus the caller's fetch order, so the function stays correct if the page ever fetches ascending.

Duplicate featuredOrder values are legal and produce a console.warn in the build log. They do not abort the build: a duplicate yields two featured posts in an unchosen order, which is cosmetic rather than wrong, and keeping the function total is what makes the property tests below meaningful across the whole input space.

Assertions

Post-conditions asserted with the existing invariant() helper, so they run against all real posts on every production build rather than only against synthetic fixtures. io/cache/filesystem.ts:34 disables the cache outside development, so npm run build always refetches from Notion and always executes these paths.

• Every post lands in exactly one of featured or unfeatured
• featured is sorted by ascending featuredOrder

One condition per assertion, per ~/.agents/standards/correctness.md. The Notion property existing and being a number is not asserted: that is external data a human can legitimately get wrong, so it stays with Zod at the boundary and the existing INVALID_POST_PROPERTIES_ERROR.

Tests

Adding fast-check as a devDependency. Properties over arbitrary post lists with arbitrary featuredOrder, including nulls, duplicates, negatives and non-contiguous runs:

1. The outputs are a permutation of the input by id
2. Every featured element has a non-null featuredOrder; every unfeatured element has null
3. featured is non-decreasing by featuredOrder
4. Within an equal-order run, firstPublished is non-increasing
5. Output is independent of input order

Example tests cover the boundary parse in getPosts and getPost, the missing-property abort, and FeaturedWriting rendering nothing when given an empty array.

Slices

• A. Parse Featured order into featuredOrder in both schemas and both call sites. No visible change. Verified by reading the values back out of .local-cache/notion/posts-list-descending.json.
• B. The Move getPosts call out of ui/sections/blog-post-list into the page entry point #60 refactor. PostList takes posts and drops limit and the unused skipCache; home and blog pages fetch and pass. No behaviour change, so the bar is an identical rendered page.
• C. partitionPostsByFeatured, home-featured-writing.tsx, home page wiring.

Closes

This work closes #60 (slice B) and #115, whose PostList mock seam at app/(home)/page.test.tsx:21-30 disappears once PostList takes a prop.