feat(files): let the user set a file's type from the header dropdown - #6373

Summary

handleCreateFile was hardcoded to markdown, and there was no way to say "actually this is a CSV" afterwards. The only escape hatch was Rename - which never touched contentType, so untitled.md renamed to data.csv stayed text/markdown and kept opening in the rich markdown editor.

Feature

• The filename breadcrumb dropdown gains a Type submenu (Document › / Code ›). Picking a type swaps the file's extension and its stored contentType in one write. Bytes are never touched, so it's a metadata edit, not a conversion - only text-editable types are offered, and the entry is absent entirely on a PDF or an image.
• New registry at apps/sim/lib/uploads/utils/text-file-types.ts: 9 document types plus 20 code types. Every MIME is taken from the existing EXTENSION_TO_MIME rather than invented. It's framework-free, so the contract, route, hook, and component all consume one list. Two invariant tests keep it honest - every entry must round-trip through getMimeTypeFromExtension, and every entry must resolve to text-editable in resolveFileCategory, so nobody can add a type the viewer refuses to open.
• The rename contract gained an optional contentType, allowlisted and cross-checked against the name's extension. The check derives extension → MIME (extension is the registry's unique key; several types share a MIME), and the server re-derives it rather than trusting the client.

Correctness fixes found while building it

• updateWorkspaceFileContent read the row before taking the FOR UPDATE lock, then wrote that read's contentType back inside it. A content save overlapping a retype therefore resurrected the pre-retype type, leaving a file named .txt still stored as text/markdown. It now writes the column only when a caller actually declares one. This was latent before this PR too - a save racing a plain rename hit the same path.
• Both type groups are nested behind their own submenu. A flat document list plus a Code › entry overflows the 240px menu cap, which pushed the entry gating every code type out of sight on open.

Realtime flush (partially verified - see Verification Results)

• Changing a collaborative markdown file's type unmounts its editor and mounts one that reads the file's durable bytes. The relay owns durability for that document and persists on a 5s debounce, so the read raced the write and returned pre-edit content. The client cannot close this itself: its save path is disabled for a collaborative doc by design, and isDirty is pinned false.
• Adds a FLUSH / FLUSH_COMPLETE round trip. flushPersist grows a mode and returns an outcome: only a debounced flush may be coalesced away by the cross-task dedup window, because a deduped no-op acked as success would ship exactly the staleness this closes. The client wait is bounded well under the persist budget, and a lapsed wait proceeds with the rename rather than blocking the user.
• The published flush is stable and resolves the provider at call time. Binding it to provider identity republished on every socket churn, and a churn ending on null silently left the header with nothing to call.
• Found in review: the persist path is a versioned object swap - every content write mints a new storage key and deletes the previous blob. So a confirmed flush left the cached list record pointing at a key that 404s, and the retype swapped editors onto it. The retype now awaits a list refetch between a persisted flush and the rename (useRefreshWorkspaceFiles, refetchType: 'all' - the default active resolves instantly against an unobserved list). The refresh rejects on a failed refetch rather than reporting success on the stale cache; the caller logs and proceeds, since the edits are already durable and aborting would lose an explicit user action over a transient fetch.

Test Coverage

CODE PATHS                                              TESTS
[+] lib/uploads/utils/text-file-types.ts                text-file-types.test.ts (80)
  ├── [★★★] withFileTypeExtension                       multi-dot, no-ext, .gitignore, trailing dot, case
  ├── [★★★] resolveTextFileType                         extension-first over shared MIME, stale MIME, null
  └── [★★★] registry invariants                         ext↔MIME round-trip, all text-editable, unique keys
[+] lib/api/contracts/workspace-files.ts                route.test.ts (9)
  └── [★★★] contentType allowlist + ext/MIME agreement  .exe rejected, mismatch rejected, .yml alias rejected
[+] lib/uploads/.../workspace-file-manager.ts           workspace-file-retype.test.ts (7)
  ├── [★★★] retype writes both columns                  + never touches contentUpdatedAt
  ├── [★★★] conflict probe skipped when name unchanged
  └── [★★★] no-op when neither name nor type changes
[+] updateWorkspaceFileContent contentType race         workspace-file-storage-accounting.test.ts (+2)
[+] app/api/.../[fileId]/route.ts PATCH                 route.test.ts - 401, 403, 409, event split
[+] hooks/queries/workspace-files.ts                    workspace-files.test.tsx (+7) - optimistic patch, rollback,
                                                          refresh awaits refetch / rejects on failure
[+] files/untitled-title.ts                             untitled-title.test.ts (25)
[+] realtime/handlers/file-doc.ts FLUSH                 file-doc.test.ts (+10) - persisted/unchanged/conflict,
                                                          debounce cancel, unjoined file, dedup bound
[+] collaboration/file-doc-provider.ts flush()          file-doc-provider.test.ts (+6) - ack, timeout, destroy
[+] collaboration/file-doc-room-context.tsx             file-doc-room-context.test.tsx (5) - churn regression

GAPS
  [GAP] files.tsx handleChangeFileType / formatFileType - no test harness for a 2.2k-line client component
  [GAP] resource-header.tsx submenu rendering          - untested; covered indirectly by browser QA
  [GAP] orchestration audit-description branch         - mocked at the boundary in route.test.ts

COVERAGE: 13/16 paths tested (81%)   QUALITY: ★★★ 13

Tests: 4 new test files, 6 extended. apps/sim 20,545 passed / 0 failed. apps/realtime 283 passed / 0 failed.

Pre-Landing Review

2 issues (1 critical, 1 informational).

• [FIXED] [P2] (confidence 9/10) apps/realtime/src/handlers/file-doc.ts - a client-requested flush was unbounded. requested deliberately bypasses the dedup window, but room.edited is set on the first edit and never cleared, so every repeat performed a full projection: a Yjs→markdown conversion, a fresh blob upload, and a delete of the previous key. Fixed by pairing a monotonic edit counter with the sequence the last successful persist covered; a flush with nothing new to write now acks unchanged. The sequence is captured before the projection and stored only on success, so an edit arriving mid-write stays pending and a conflict is never mistaken for a completed write.
• [SKIPPED] [INFO] (confidence 7/10) file-doc-room-context.tsx - fileId: '' sentinel on the no-provider fallback. The only consumer branches on status, so it is harmless today.

Specialist subagents were not dispatched; this is the checklist pass run inline.

Design Review

Frontend files changed. Reviewed inline against the emcn consumer rules: the Type entry is props-driven through the existing BreadcrumbItem.dropdownItems contract, the new DropdownSubmenuOption is a discriminated sibling so every existing consumer compiles unchanged, and no className overrides chrome. DropdownMenuSubTrigger supplies its own chevron and DropdownMenuRadioItem reserves its own indicator gutter, so neither is re-specified.

No full /design-review visual audit was run.

Eval Results

No prompt-related files changed - evals skipped.

Scope Drift

Scope Check: DRIFT DETECTED (minor)
Intent:    Let the user change a file's type from the filename dropdown after creating it.
Delivered: That, plus a contentType race fix and a realtime flush.

• The contentType race fix is not optional - without it the relay's persist reverts the type you just picked.
• The realtime flush was a directed follow-up after the stale-first-paint bug surfaced.

No unrelated files remain. A stray .gitignore line (.gstack/, a local tooling artifact from QA) was swept in by a broad stage and has been removed in e278ae38 - .gitignore now matches staging exactly.

Plan Completion

12 DONE, 3 CHANGED, 1 PARTIAL, 0 NOT DONE.

The three CHANGED items: both type groups nested rather than one inline (the 240px menu cap); manager coverage landed in a new workspace-file-retype.test.ts rather than extending workspace-file-manager.test.ts (no DB harness there); and the registry↔viewer invariant lives in text-file-types.test.ts rather than file-category.test.ts, which mocks the dependencies that invariant needs real.

Verification Results

Browser QA against local dev - 8 of 11 cases verified:

• New file → untitled.md, rich editor, Type column "Markdown"
• Type submenu present, current type checked, Document › / Code › groups
• Markdown → JSON: name, editor swap to Monaco, Type column, icon
• Code → Python → untitled.py
• Back to Markdown restores the rich editor
• Collision → (1) suffix, no 409
• PDF correctly has no Type entry
• Name and content_type agree in the database after every change

The stale first paint had a root cause, and it is fixed. It was not only the flush budget: a confirmed persisted flush rotates the storage key and deletes the old blob, so the viewer that mounted next read a dead key. Surfaced by Cursor in review and fixed in e1775025 / 2c1518ed (see the flush section above). Durability was already measurably improved before that - a fresh file's stored bytes went from size 0 to the typed content as part of the retype - and the relay logged Requested flush … persisted { edited: true }, so the round trip works end to end. The happy path has still not been re-run in a browser since the fix; the reviewer should treat that as the one open verification item.

/api/internal/file-doc/persist costs 3.6s cold vs 8ms warm in dev, so in a dev session the first retype after a server start will reliably lapse that budget. Worth a second look at whether 2s is the right number.

Also not verified: multi-collaborator retype, read-only member gating, and realtime propagation to a second session.

Notes for the reviewer

• Pre-existing on staging: apps/realtime/src/handlers/file-doc.test.ts has 3 failing seed assertions on a clean origin/staging checkout (expected '' to contain '# Seeded'). They pass on this branch. Worth a look from whoever owns that file - a test that flips based on what else is in the file is fragile.
• Pre-existing, out of scope: downloads serve the original upload filename and MIME. app/api/files/serve/[...path]/route.ts derives both from the storage key, which is frozen at upload and never rewritten by renameWorkspaceFile; the client then lets that Content-Disposition win over the DB record. Renaming already breaks this today. Retyping to a non-markdown type moves files onto that path, so it becomes more visible.
• Docs: apps/docs/content/docs/en/files/ has an editor.mdx that covers the markdown editor. This feature likely warrants a mention there, but the docs carry a specific voice and screenshots, so that is left to the docs owner rather than done as a side effect.

Test plan

• apps/sim - 20,544 passed, 0 failed, 25 skipped
• apps/realtime - 283 passed, 0 failed
• packages/realtime-protocol - 14 passed
• bun run check:api-validation passes
• bunx tsc --noEmit clean in apps/sim and apps/realtime
• Biome clean on every changed file
• Flush first-paint on a quiet machine
• Multi-collaborator retype
• Read-only member sees no Type entry

🤖 Generated with Claude Code