Favorites in My Documents, then a later list UX pass

[HMarzban]

Goal

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 still a maintainer decision. Staff recommendation: Favorite / Favorites. 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 is unused in product UI today. It names a per-user list preference, not a saved message.

If the maintainer picks Bookmark or Starred instead, say so on this issue before implementation. Code, UI copy, and API must then use that one word only.

Facts (2026-08-21)

• The panel is Settings → Documents. Owner-scoped GET /documents. Live fields: title, slug, dates, Private, Read-only, member cluster, ⋮ menu. No favorite flag exists.
• Chat bookmarks live in Supabase (message_bookmarks, toggle_message_bookmark). Do not reuse those tables.
• Prisma DocumentMetadata has no per-user preference column. A favorite is a user preference, not a document property.
• 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)

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 HITL on this issue (comment before coding). Does not depend on Bun 1.4 or Next 16.