diff --git a/openspec/changes/add-explore-page/.openspec.yaml b/openspec/changes/add-explore-page/.openspec.yaml new file mode 100644 index 0000000..3f1f00e --- /dev/null +++ b/openspec/changes/add-explore-page/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-26 diff --git a/openspec/changes/add-explore-page/design.md b/openspec/changes/add-explore-page/design.md new file mode 100644 index 0000000..3895e4f --- /dev/null +++ b/openspec/changes/add-explore-page/design.md @@ -0,0 +1,108 @@ +## Context + +The Journal has no in-app discovery surface today. A signed-in user who wants to follow someone has to come in with a username from outside the app or notice a profile in the public activity feed on logged-out `/`. The four current prod users are all known to the operator, so this hasn't pinched yet — but the gap will become real as the user count grows, and worse once federation lands and remote actor discovery is also on the table. + +The IA review (`docs/information-architecture.md`, Stream F) called this out as the highest-value missing surface. This design is the local-only v1: a paginated directory of public local users, ordered by recency of activity, plus a small "Active recently" sub-section to give the page some texture when the directory is small. + +Existing infrastructure this builds on: + +- `users` table has `profile_visibility` (`public` | `private`) — the directory's primary opt-out. +- `activities` table has `created_at` and `visibility` — used for ordering by recency and for the "Active recently" filter. +- `apps/journal/app/lib/follow.server.ts` already provides `countFollowers` and `getFollowState` per user — directly reusable for the per-row data. +- `apps/journal/app/components/FollowButton.tsx` already renders the right Follow / Requested / Unfollow state — directly reusable. +- The locked-account access rule (`social-follows`) already excludes private profiles from public listings; we follow the same pattern. + +## Goals / Non-Goals + +**Goals:** + +- A signed-in user who lands on `/explore` can browse local public users and tap Follow / Request to follow without leaving the page. +- An anonymous visitor can browse the same directory (the data is public anyway), so first-visit discovery doesn't require sign-up. +- The page is paginated and sortable by a stable rule (recency of activity, descending) so it works at 4 users today and at 4,000 users later without a rewrite. +- Private profiles, banned/suspended users (when those statuses exist), and the demo persona are excluded. +- The capability lives in its own spec file; the directory query lives in its own server lib file. No bleed into `social-follows` or `activity-feed`. + +**Non-Goals:** + +- Search. Deferred to v2. With four prod users, a paginated list is enough; users with known handles can already reach `/users/` directly. +- Algorithmic curation. No "people you might know" recommendations, no graph traversal, no engagement-based ranking. Recency-of-activity is the only signal. +- Remote actor discovery. Federation is `social-federation`'s problem when that lands; v1 is local-only. +- A dedicated user-detail card on `/explore`. Each row is a compact summary; deep dive is `/users/:username`. +- Activity content on `/explore`. The directory is *people*, not *posts*. The Public view of `/feed` (Stream A) is the content discovery surface. + +## Decisions + +### Anonymous access is allowed + +`/explore` is reachable to logged-out visitors. Why: + +- The data shown — public profiles only — is already reachable without auth (`/users/` is anonymously reachable for public profiles), so there's no privacy concern. +- It's a stronger first-visit experience than the current logged-out home, which is hero + marketing + public *activity* feed. A visitor can see who's on the instance and decide to sign up to follow them. +- It mirrors how `/users/` and the public activity feed treat anonymous visitors. + +The Follow button on each row only renders for signed-in viewers; anonymous viewers see the row content but no action button. + +**Alternative considered:** require auth, redirect anonymous to `/auth/login`. Rejected because it makes the discovery surface less valuable for the population it most needs to convert (first-time visitors). + +### Directory is ordered by `MAX(activities.created_at)` descending + +The most-recent-activity ordering keeps the directory feeling alive without algorithmic complexity. Users with no activities yet sort to the end (by `users.created_at` descending as a tiebreaker, so newer users appear ahead of older inactive ones). + +**Alternatives considered:** + +- **Alphabetical by username.** Predictable but boring; surfaces inactive accounts to the top half. +- **Random shuffle.** Fair to small users but not bookmarkable, breaks pagination. +- **Follower count.** Reasonable but has a Matthew-effect tilt; one or two heavy users would dominate page 1. + +Recency-by-activity is the simplest signal that meaningfully reflects "who's active here right now." + +### "Active recently" sub-section is the same query, sliced + +The page renders an "Active recently" strip at the top (top 5 users with at least one public activity in the last 30 days). It's the same join as the main directory; the strip is just a different `WHERE` and `LIMIT`. We don't denormalize anything, don't precompute anything, don't cache anything. Below it is the full paginated directory. + +**Why:** at 4 users this strip is the *whole* directory. At 4,000 users it's a useful signal-of-life. We can revisit when there's data to revisit on. + +### Paginate via offset, not cursor (yet) + +The directory uses standard `?page=N&perPage=20` offset pagination, capped at 100 per page. Why: + +- The data is small (single-digit users today, low hundreds soon). +- Recency-of-activity is unstable enough as a sort key that cursor pagination would need to break ties on `users.id` anyway, and the win over offset is marginal at this scale. +- Offset pagination is the simplest thing that works. + +When the directory hits ~10K users we'll revisit. Cursor pagination's the right answer there; not now. + +**Alternative considered:** keyset cursor pagination like `/notifications`. Rejected as premature. + +### Navbar entry for signed-in users only + +Adding "Explore" to the navbar for signed-in users keeps the discovery surface visible from any page. For anonymous visitors, the navbar stays minimal (Login / Register CTAs) and `/explore` is reached via a link on the visitor home (`/`). The navbar redesign (Stream C) will work out the visual treatment; this proposal just specifies that the entry exists for signed-in users. + +**Alternative considered:** put "Explore" in the navbar for everyone. Rejected because the anonymous navbar is intentionally minimal — anything other than auth CTAs dilutes the conversion goal of the visitor home. + +### Privacy filter is `profile_visibility = 'public'` AND not in an exclusion set + +The directory query filters: + +1. `profile_visibility = 'public'` — Mastodon-style locked accounts opt out by their visibility setting, same as `/users/:username/followers` already enforces. +2. **Banned/suspended users** — when those statuses exist (they don't yet; this is a forward-compat scaffold). The query should be written so adding a `status` column or similar is a one-line filter change, not a query rewrite. +3. **Demo persona** — `apps/journal/app/lib/demo-bot.server.ts` exposes the persona username; exclude it from the directory so the demo bot doesn't appear in real discovery. + +The query lives in `apps/journal/app/lib/explore.server.ts`. Tests cover each exclusion as a separate scenario. + +## Risks / Trade-offs + +- **Cold-start UX at 4 users.** The directory will be tiny. → Acceptable; the "Active recently" strip handles the "looks empty" feeling, and the public activity feed on logged-out `/` already does the same job from the content angle. +- **Recency ordering tilts toward power users.** A user who posts daily will perpetually outrank a quieter user. → Acceptable for v1; if it becomes a fairness issue we add a tiebreaker (e.g., bucket by week, randomize within bucket). Don't optimize speculatively. +- **No search.** A user looking for a specific handle can't search. → Mitigated by `/users/` working directly. Search is a v2 follow-up. +- **Federation collision.** Once federation lands, the directory will need a "local" / "remote" distinction. → The capability spec says "local users" explicitly; remote-actor discovery is a `social-federation` add-on that can introduce its own surface or extend `/explore` later. + +## Migration Plan + +No data migration. The directory is a JOIN of existing `users` and `activities` rows. Deploy is a normal app rollout. Rollback is reverting the route registration in `routes.ts`. + +## Open Questions + +- **Bio in the directory row?** The user table has a `bio` column. Showing the first ~120 chars per row gives the directory more character but pads the layout. Default plan: include a truncated bio. Easy to drop if it's noisy. +- **Follower count visible in the directory?** Default plan: yes (mirrors how `/users/:username` shows it). A dissenter could argue this creates social-pressure metric-anxiety; counter-argument is that Mastodon, the comparable, shows it. +- **Does `/explore` deserve its own SSE event for follow-state changes?** The Follow button on a row should reflect "you just followed this person" without a hard reload. Today the FollowButton component handles this via local state on `/users/`; the same pattern works on `/explore` with the same component. No new SSE channel needed. diff --git a/openspec/changes/add-explore-page/proposal.md b/openspec/changes/add-explore-page/proposal.md new file mode 100644 index 0000000..3bafddb --- /dev/null +++ b/openspec/changes/add-explore-page/proposal.md @@ -0,0 +1,34 @@ +## Why + +A user who wants to follow someone on this instance has no in-app path to discover them — they need a username from outside the app, type it into `/users/` directly, or stumble onto a profile via the public activity feed on logged-out `/`. With four prod users today this is just a friction; with federation in Phase 2 it becomes a real gap. Add `/explore` as the in-app discovery surface so finding people to follow is a first-class action, not a workaround. + +## What Changes + +- Add a new `/explore` route to the Journal app, reachable to both signed-in users and anonymous visitors. +- Render a paginated directory of local users with `profile_visibility = 'public'`, ordered by most-recent activity (`MAX(activities.created_at)` per user, descending; users with no activities sort to the end by `users.created_at`). +- Within the directory page, surface a small "Active recently" section at the top — the top N (5 by default) public users who posted a public activity in the last 30 days. Same data set, just sliced and surfaced. +- Exclude private (locked) profiles, banned/suspended users (when those statuses exist), and the demo persona from the directory — they have explicit opt-outs from public discovery. +- Each directory row shows: display name, handle (`@username`), short bio (truncated), follower count (accepted only), and a Follow / Requested / Unfollow button (locked-account semantics from `social-follows` apply, so a public-target row shows Follow, etc.). The button only renders for signed-in viewers. +- Add an "Explore" entry to the navbar for signed-in users (visible alongside Feed / Routes / Activities). Anonymous visitors reach `/explore` via a link on the visitor home page, not via the navbar. +- No search in v1. With four prod users a paginated list is enough; search is deferred — typing `/users/` already partially solves it for known handles. + +## Capabilities + +### New Capabilities + +- `explore`: discovery directory of local users for follow recommendations. Owns the `/explore` route, the directory query rules, the "Active recently" sub-list, the access model (anonymous + signed-in), and the navbar entry. + +### Modified Capabilities + +- `social-follows`: the directory needs a count of accepted followers per public user, which is already available via `countFollowers`. No new requirement; cross-reference only. +- `journal-landing`: the navbar entries grow by one ("Explore" for signed-in users). The visitor home gains a link to `/explore` so anonymous visitors have an in-app path to the directory. + +## Impact + +- **New code:** `apps/journal/app/routes/explore.tsx`, `apps/journal/app/lib/explore.server.ts` (the directory query and "Active recently" slice), navbar entry in `apps/journal/app/root.tsx`, link from the visitor home in `apps/journal/app/routes/home.tsx`, i18n keys in `packages/i18n/src/locales/{en,de}.ts`. +- **Modified code:** none — the existing helpers (`countFollowers`, `getFollowState`) cover the per-row data; the new query is additive in `explore.server.ts`. +- **No DB migrations:** the directory query is a JOIN of existing tables (`users`, `activities`); no new columns or tables. +- **No new dependencies.** +- **Privacy:** the directory is public-by-default and respects the profile-visibility opt-out. No private profile leaks. +- **Federation:** out of scope for v1. Remote-actor discovery is `social-federation`'s problem when that lands. +- **OpenSpec index:** `openspec/CAPABILITIES.md` gains an entry under the "Social" section. diff --git a/openspec/changes/add-explore-page/specs/explore/spec.md b/openspec/changes/add-explore-page/specs/explore/spec.md new file mode 100644 index 0000000..050e5b1 --- /dev/null +++ b/openspec/changes/add-explore-page/specs/explore/spec.md @@ -0,0 +1,101 @@ +## ADDED Requirements + +### Requirement: Local user directory at `/explore` +The Journal SHALL expose a route at `/explore` that renders a paginated directory of local users with `profile_visibility = 'public'`. The directory SHALL be reachable to both signed-in users and anonymous visitors. Each row SHALL display the user's display name, handle (`@username`), follower count (accepted only — see `social-follows` spec), and a short truncated bio when present. For signed-in viewers each row SHALL also render a Follow / Requested / Unfollow button reflecting the viewer's current relationship to that user (using the same locked-account semantics as the profile page); for anonymous viewers the button SHALL NOT render. + +#### Scenario: Signed-in user loads /explore +- **WHEN** a signed-in user requests `/explore` +- **THEN** the page renders a list of public local users with display name, handle, follower count, truncated bio, and a Follow / Requested / Unfollow button per row + +#### Scenario: Anonymous visitor loads /explore +- **WHEN** an unauthenticated visitor requests `/explore` +- **THEN** the page renders the same list of public local users (display name, handle, follower count, truncated bio), but no Follow / Requested / Unfollow button is rendered on any row + +#### Scenario: Truncated bio +- **WHEN** a user with a bio longer than 120 characters appears in the directory +- **THEN** the row shows the first 120 characters followed by an ellipsis + +#### Scenario: User with no bio +- **WHEN** a user with no bio (`bio IS NULL` or empty string) appears in the directory +- **THEN** the row simply omits the bio area; the row remains valid + +### Requirement: Directory is ordered by most-recent public activity +The directory SHALL be ordered by `MAX(activities.created_at) DESC` per user, considering only activities with `visibility = 'public'`. Users with no public activities SHALL sort to the end of the list, ordered among themselves by `users.created_at DESC` (newer registrations first). The ordering SHALL be deterministic — ties on the primary sort key SHALL be broken by `users.id` (descending) so pagination doesn't omit or duplicate rows. + +#### Scenario: Active user appears before inactive user +- **WHEN** user A has a public activity from yesterday and user B has no public activities +- **THEN** A appears before B in the directory listing + +#### Scenario: More-recently-active user appears first +- **WHEN** user A's most recent public activity is from today and user B's is from last week +- **THEN** A appears before B in the directory listing + +#### Scenario: Tied recency falls back to user id +- **WHEN** users A and B share the same `MAX(activities.created_at)` (or both have no public activities) +- **THEN** the ordering between them is determined by `users.id` descending (deterministic), so neither is omitted nor duplicated when paginating + +### Requirement: Excluded users +The directory SHALL exclude: + +1. Users with `profile_visibility = 'private'` — they have explicitly opted out of public discovery (Mastodon-style locked accounts). +2. The instance's demo persona, identified by the username returned by `loadPersona()` — the demo bot is not a real user and should not appear in real discovery. +3. (Forward-compat) Users in any future banned/suspended state — when such a status column exists, it SHALL be added to the exclusion filter. + +Excluded users SHALL NOT appear on `/explore` even if they have public activities and would otherwise sort to the top of the directory. + +#### Scenario: Private profile is excluded from the directory +- **WHEN** user A has `profile_visibility = 'private'` and any activity history +- **THEN** A does not appear in the `/explore` directory regardless of which page is requested + +#### Scenario: Demo persona is excluded +- **WHEN** the demo persona username (per `loadPersona()`) matches a row that would otherwise appear +- **THEN** that row is filtered out of the directory + +#### Scenario: Public user with no activities is included +- **WHEN** user A has `profile_visibility = 'public'` but has never created an activity +- **THEN** A still appears in the directory (sorted toward the end by the recency rule) + +### Requirement: "Active recently" sub-section +The `/explore` page SHALL render an "Active recently" sub-section at the top of the directory, listing up to N (default 5) public users who have created at least one public activity in the last 30 days, ordered by `MAX(activities.created_at) DESC`. The sub-section SHALL apply the same exclusion rules as the main directory (private profiles, demo persona, future banned/suspended users). When fewer than 1 user qualifies, the sub-section SHALL be omitted entirely (no empty header). + +#### Scenario: Active-recently strip rendered with qualifying users +- **WHEN** at least one public local user (excluding private/demo) has a public activity within the last 30 days +- **THEN** the page renders the "Active recently" sub-section above the main directory, with up to 5 such users + +#### Scenario: No qualifying users hides the strip +- **WHEN** no public local user (excluding private/demo) has any public activity within the last 30 days +- **THEN** the "Active recently" sub-section is not rendered at all; the main directory is the only listing on the page + +#### Scenario: Strip respects exclusion rules +- **WHEN** a private profile or the demo persona has a recent public activity +- **THEN** they are not included in the "Active recently" strip — the same exclusion rules apply as for the main directory + +### Requirement: Pagination +The directory SHALL paginate via `?page=N` (1-indexed) and `?perPage=K` query parameters. Page size SHALL default to 20 per page and SHALL be capped at 100; `perPage` values outside `[1, 100]` SHALL be clamped to that range without raising an error. The response SHALL surface a "Next page" link when more rows exist past the current page, and a "Previous page" link when `page > 1`. + +#### Scenario: Default pagination +- **WHEN** a visitor loads `/explore` with no query params +- **THEN** the page renders the first 20 users in the directory ordering + +#### Scenario: Subsequent page +- **WHEN** a visitor loads `/explore?page=2` +- **THEN** the page renders rows 21–40 in the directory ordering, with a "Previous page" link to `?page=1` and (if more rows exist) a "Next page" link to `?page=3` + +#### Scenario: Out-of-range perPage is clamped +- **WHEN** a visitor loads `/explore?perPage=10000` or `/explore?perPage=0` +- **THEN** the loader clamps `perPage` to `[1, 100]` and renders normally — no 400 response + +#### Scenario: Page beyond the last +- **WHEN** a visitor loads `/explore?page=N` where N is past the last populated page +- **THEN** the response renders the empty list and a "Previous page" link; no 404 + +### Requirement: Navbar entry for signed-in users +The Journal navbar SHALL include an "Explore" entry for signed-in users, linking to `/explore`. Anonymous visitors SHALL NOT see this entry in the navbar — they reach `/explore` via the visitor home (see `journal-landing` spec). The visual treatment of the entry is governed by the navbar redesign (Stream C in `docs/information-architecture.md`); this requirement only mandates that the entry exists. + +#### Scenario: Signed-in user sees the Explore entry +- **WHEN** a signed-in user loads any page +- **THEN** the navbar includes an "Explore" link to `/explore` + +#### Scenario: Anonymous user does not see the Explore entry in the navbar +- **WHEN** an unauthenticated visitor loads any page +- **THEN** the navbar does not include an Explore entry; the visitor home provides the in-app path to `/explore` instead diff --git a/openspec/changes/add-explore-page/specs/journal-landing/spec.md b/openspec/changes/add-explore-page/specs/journal-landing/spec.md new file mode 100644 index 0000000..afafdbb --- /dev/null +++ b/openspec/changes/add-explore-page/specs/journal-landing/spec.md @@ -0,0 +1,12 @@ +## ADDED Requirements + +### Requirement: Visitor home links to /explore +For signed-out visitors on the flagship instance and self-hosted instances alike, the visitor home (`/`) SHALL include a link to `/explore` so anonymous visitors have an in-app path to browse the local user directory before signing up. The link SHALL be visually secondary to the auth CTAs (it does not compete with Register / Sign In as the conversion goal) but reachable on the same first-fold page section. + +#### Scenario: Visitor home renders the Explore link +- **WHEN** a signed-out visitor loads `/` +- **THEN** the page includes a link to `/explore` somewhere within the hero / CTAs section, visually secondary to Register and Sign In + +#### Scenario: Signed-in user does not see the visitor-home Explore link +- **WHEN** a signed-in user loads `/` +- **THEN** the visitor-home layout is not rendered (the personal dashboard takes its place); the navbar's Explore entry is the signed-in user's path to `/explore` diff --git a/openspec/changes/add-explore-page/tasks.md b/openspec/changes/add-explore-page/tasks.md new file mode 100644 index 0000000..2727875 --- /dev/null +++ b/openspec/changes/add-explore-page/tasks.md @@ -0,0 +1,54 @@ +## 1. Server-side directory query + +- [ ] 1.1 Create `apps/journal/app/lib/explore.server.ts` with `listDirectory({ page, perPage })` returning `{ rows, totalCount }`. Rows include `id`, `username`, `displayName`, `bio`, `latestActivityAt` (nullable), and the user's `profileVisibility`. Filters: `profile_visibility = 'public'`, exclude demo persona, exclude future banned/suspended (placeholder filter — leave a TODO for when the column exists). +- [ ] 1.2 Order: `LEFT JOIN activities ON activities.owner_id = users.id AND activities.visibility = 'public'`, then `MAX(activities.created_at) DESC NULLS LAST`, tiebreaker `users.id DESC`. +- [ ] 1.3 Add `listActiveRecently(limit = 5)` returning the same row shape, filtered to users with at least one public activity in the last 30 days, capped at `limit`. +- [ ] 1.4 Add `countDirectory()` returning the total number of users that match the directory's filter, for pagination math. +- [ ] 1.5 Add a follower-count batch helper (`countFollowersBatch(userIds)`) so the page doesn't fan out N+1 queries — one query per page load. +- [ ] 1.6 Add `apps/journal/app/lib/explore.integration.test.ts` covering: public user appears, private user excluded, demo persona excluded, ordering by recency, tiebreaker by id, "Active recently" 30-day filter, "Active recently" cap. + +## 2. Route + UI + +- [ ] 2.1 Register `/explore` in `apps/journal/app/routes.ts`. +- [ ] 2.2 Create `apps/journal/app/routes/explore.tsx`: + - Loader reads `?page=` (default 1) and `?perPage=` (default 20, clamp `[1, 100]`); fetches `listActiveRecently(5)`, `listDirectory({ page, perPage })`, `countDirectory()`, and (for signed-in viewers) per-row follow state via existing `getFollowState` batched. + - Component renders the "Active recently" strip (if non-empty), then the main directory list, then "Previous" / "Next" links. +- [ ] 2.3 Reuse `` for the per-row action; render only when the loader returns a signed-in viewer. +- [ ] 2.4 Bio truncation utility — first 120 characters + ellipsis, plain string slice (no markdown rendering yet). +- [ ] 2.5 Empty-state copy when the directory itself is empty (no public users at all). +- [ ] 2.6 Page-beyond-last empty state — render the empty list with a "Previous page" link, no 404. + +## 3. Navbar + visitor home links + +- [ ] 3.1 Add the "Explore" entry to the signed-in navbar in `apps/journal/app/root.tsx`, positioned alongside Feed / Routes / Activities. Visual treatment is plain for now; the navbar redesign (Stream C) refines it later. +- [ ] 3.2 Add a link to `/explore` on the visitor home (`apps/journal/app/routes/home.tsx`, signed-out branch) — secondary to the Register / Sign In CTAs but on the same fold. Wording: e.g. "Browse who's here →". +- [ ] 3.3 No new link on the signed-in home — the navbar entry covers it. + +## 4. i18n + +- [ ] 4.1 Add to `packages/i18n/src/locales/en.ts` and `de.ts`: + - `explore.title`, `explore.heading`, `explore.empty`, `explore.activeRecently.heading` + - `nav.explore` + - `home.exploreLink` (visitor-home wording) +- [ ] 4.2 No i18n changes needed for FollowButton — it already uses the `social.*` keys. + +## 5. Spec promotion + index + +- [ ] 5.1 At archive time, promote `openspec/changes/add-explore-page/specs/explore/spec.md` to `openspec/specs/explore/spec.md` (no purpose section needed yet — the `## ADDED Requirements` content becomes the spec body). +- [ ] 5.2 At archive time, merge the `journal-landing` delta into `openspec/specs/journal-landing/spec.md`. +- [ ] 5.3 Add an entry for `explore` in `openspec/CAPABILITIES.md` under the Social section. + +## 6. Tests + +- [ ] 6.1 Integration tests for the directory query (covered in 1.6). +- [ ] 6.2 Add an e2e test in `e2e/explore.test.ts`: + - Anonymous loads `/explore` and sees the directory but no Follow buttons. + - Signed-in loads `/explore` and sees Follow buttons; clicking Follow on a public profile transitions the row to Unfollow without a hard reload. + - A private profile does not appear in the directory regardless of which user is viewing. +- [ ] 6.3 Run `pnpm typecheck && pnpm lint && pnpm test && pnpm test:e2e` before opening the PR. + +## 7. PR + rollout + +- [ ] 7.1 Open a PR with the change, link to `openspec/changes/add-explore-page/`, enable auto-merge. +- [ ] 7.2 After merge, archive the change (`/opsx:archive add-explore-page`) so the deltas promote into top-level specs. +- [ ] 7.3 Update `docs/information-architecture.md` to flip Stream F to ✅ Shipped and refresh the navbar diagram to include "Explore".