Favorites in My Documents, then a later list UX pass #173

Goal

First slice is committed locally as 083acad3f (not pushed). Name is Favorite.

Let a signed-in owner pin a few owned documents to the top of Settings → Documents. After that ships, run a later UI/UX pass on the same panel (empty preview band, crowding, keyboard parity).

Name is Favorite / Favorites / Unfavorite. Do not reuse Bookmark or Pin.

Why that name

Bookmark already means saved chat messages. The toolbar, Bookmark panel, message menu, toasts (Bookmark added), and the hyperlink picker (Browse headings & bookmarks) all use that word.

Pin already means a pinned chat message (PinnedMessagesBar).

Starred is free of those collisions, but the action reads as an icon, not a product word.

Favorite names a per-user list preference, not a saved message. The name is settled. Do not reopen Bookmark, Pin, or Starred.

Facts (2026-08-21)

• The panel is Settings → Documents. Owner-scoped GET /documents. Live fields: title, slug, dates, Private, Read-only, member cluster, ⋮ menu. The owner live list now sends isFavorite.
• Chat bookmarks live in Supabase (message_bookmarks, toggle_message_bookmark). Do not reuse those tables.
• Prisma DocumentFavorite (userId + documentId) stores the owner mark. Soft-delete keeps the join. Purge cascade-drops it.
• Catalog already lists as not v1: time-bucket headers, screenshot thumbnails, “Last opened by me” sort. Those stay later. Favorites are the first new slice.
• The panel is an L2 settings modal. List + grid already share one ⋮ menu (popover on desktop, action sheet on mobile). Private ON still clears and disables Read-only.
• Design-system accent is the gold highlight token. Use it for the resting favorite mark. Keep primary for focus, the active view toggle, and links.

What to build (first slice)

A complete Favorite path on My Documents only. Owned, not-deleted documents. Not a second toolbar.

1. Persist per user (userId + documentId) next to Prisma DocumentMetadata. Token subject only. Purge must drop that user’s rows for a purged document.
2. List API keeps today’s sort values. Favorites sit first. The chosen sort still applies inside favorites and inside the rest. Server-side only — client re-sort breaks Load more.
3. ⋮ menu (and the mobile action sheet) gains Favorite / Unfavorite. No always-on star on the toolbar.
4. A quiet accent mark on the row and on the grid tile so the state is visible while the menu is closed. List: next to the title or file icon. Grid: a small corner mark, not fighting lock/eye.
5. Search still searches the whole owned list. A favorite that matches the query stays in the favorite block. Trash stays a separate view; favorites do not appear in Trash.
6. Verify light and dark, desktop list + grid, and the mobile action sheet (44px hits).

Later UX pass (same panel, not this slice)

Follow-up: #221.

Do not block Favorites on these. File follow-ups if they survive the first walk:

• Grid preview is a generic file icon on a large base-200 band. Low signal. Thumbnails stay not-v1 unless the maintainer reopens that.
• Grid footer (avatars + date + ⋮) crowds on narrow cards.
• List hides the date on small screens; grid always shows it.
• Grid has no arrow-key roving; list does.
• Create document is empty-state only.
• Lock/eye at /50 ink — check contrast on light and dark.

Out of scope

• Reusing chat Bookmark tables, RPCs, or the Bookmark panel.
• Favoriting a document the user does not own (join table should allow it later; this slice does not show those rows).
• A new sort option named Favorite.
• Time buckets, Last opened, or screenshot thumbnails.
• Changing Private / Read-only / delete-undo behaviour.

Acceptance criteria

• Maintainer has named the feature (Favorite, Starred, or Bookmark). Copy, API, and code use that one word.
• Owner can favorite and unfavorite from the ⋮ menu (desktop popover and mobile sheet). The choice survives reload.
• Favorited owned documents sit at the top of list and grid. Current sort still orders inside each group.
• A quiet accent mark shows the state on the row/tile with the menu closed. No extra toolbar control.
• Chat Bookmarks, message Pin, and the hyperlink bookmark section are unchanged.
• Soft-delete still removes the row from My Documents. Purge does not leave an orphan favorite row.
• Light + dark, desktop list + grid, mobile sheet: walked.

Blocked by

None. Naming is settled. First slice waits on a push of 083acad3f (Closes #173). Later UX is #221.