feat(files): sync an untitled file's name with its leading heading

While a file is still named untitled(.md), typing a leading heading auto-renames
the file after it (debounced), and renaming the file first seeds a leading H1
from the new name. One-shot: coupling stops once the file has a real name, and
the heading seed always prepends so existing content is never clobbered.

Author: mzxchandra

apps/sim/app/workspace/[workspaceId]/files/components/file-viewer/file-viewer.tsx

@@ -116,6 +116,11 @@ interface FileViewerProps {
    * never target one editor. See {@link RichMarkdownEditorProps.collaborative}.
    */
   collaborative?: boolean
+  /**
+   * Called (debounced) with the markdown document's leading-heading text while the file is still
+   * untitled, so the caller can name the file after it. Only wired for the editable markdown editor.
+   */
+  onDeriveTitleFromHeading?: (headingText: string) => void
 }
 
 export function FileViewer(props: FileViewerProps) {
@@ -148,6 +153,7 @@ function FileViewerContent({
   disableStreamingAutoScroll = false,
   previewContextKey,
   collaborative,
+  onDeriveTitleFromHeading,
 }: FileViewerProps) {
   const category = resolveFileCategory(file.type, file.name)
 
@@ -193,6 +199,7 @@ function FileViewerContent({
           disableStreamingAutoScroll={disableStreamingAutoScroll}
           previewContextKey={previewContextKey}
           collaborative={collaborative}
+          onDeriveTitleFromHeading={onDeriveTitleFromHeading}
         />
       )
     }

apps/sim/app/workspace/[workspaceId]/files/components/file-viewer/rich-markdown-editor/rich-markdown-editor.tsx

@@ -13,6 +13,10 @@ import { useRouter } from 'next/navigation'
 import { useSession } from '@/lib/auth/auth-client'
 import type { WorkspaceFileRecord } from '@/lib/uploads/contexts/workspace'
 import { extractEmbeddedFileRef } from '@/lib/uploads/utils/embedded-image-ref'
+import {
+  headingTextFromName,
+  isUntitledName,
+} from '@/app/workspace/[workspaceId]/files/untitled-title'
 import { useUploadWorkspaceFile } from '@/hooks/queries/workspace-files'
 import type { SaveStatus } from '@/hooks/use-autosave'
 import { useFileContentSource } from '@/hooks/use-file-content-source'
@@ -41,6 +45,7 @@ import { LinkHoverCard } from './menus/link-hover-card'
 import { TableBubbleMenu } from './menus/table-menu'
 import { normalizeMarkdownContent } from './normalize-content'
 import { isRoundTripSafe } from './round-trip-safety'
+import { firstHeadingTitle, titleHeadingNode } from './title-heading'
 import '@sim/emcn/components/code/code.css'
 import './rich-markdown-editor.css'
 
@@ -55,6 +60,9 @@ const EXTENSIONS = createMarkdownEditorExtensions({
 const STREAM_REPARSE_THROTTLE_THRESHOLD = 40_000
 const STREAM_REPARSE_THROTTLE_MS = 120
 
+/** Debounce before naming a still-untitled file after its leading heading, so it fires once typing settles. */
+const DERIVE_TITLE_DEBOUNCE_MS = 600
+
 interface RichMarkdownEditorProps {
   file: WorkspaceFileRecord
   workspaceId: string
@@ -83,6 +91,12 @@ interface RichMarkdownEditorProps {
    * construction (they cannot both drive one editor and corrupt the shared doc).
    */
   collaborative?: boolean
+  /**
+   * Called (debounced) with the document's leading-heading text while the file is still untitled, so the
+   * caller can name the file after it. Omitted on read-only/non-editable surfaces. See
+   * {@link isUntitledName}.
+   */
+  onDeriveTitleFromHeading?: (headingText: string) => void
 }
 
 /** Inline WYSIWYG markdown editor: agent output streams in read-only, then the same instance becomes editable on settle. */
@@ -102,6 +116,7 @@ export const RichMarkdownEditor = memo(function RichMarkdownEditor({
   previewContextKey,
   disableTagging,
   collaborative = false,
+  onDeriveTitleFromHeading,
 }: RichMarkdownEditorProps) {
   const { data: session, isPending: isSessionPending } = useSession()
   const userId = session?.user?.id ?? ''
@@ -168,6 +183,7 @@ export const RichMarkdownEditor = memo(function RichMarkdownEditor({
       onChange={setDraftContent}
       onSaveShortcut={saveImmediately}
       onCollabReadyChange={setCollabReady}
+      onDeriveTitleFromHeading={onDeriveTitleFromHeading}
     />
   )
 })
@@ -194,6 +210,8 @@ interface LoadedRichMarkdownEditorProps {
   onSaveShortcut: () => Promise<void>
   /** Reports whether the collaborative document is synced+seeded (autosave gate). */
   onCollabReadyChange: (ready: boolean) => void
+  /** See {@link RichMarkdownEditorProps.onDeriveTitleFromHeading}. */
+  onDeriveTitleFromHeading?: (headingText: string) => void
 }
 
 interface SettledContent {
@@ -223,6 +241,7 @@ export function LoadedRichMarkdownEditor({
   onChange,
   onSaveShortcut,
   onCollabReadyChange,
+  onDeriveTitleFromHeading,
 }: LoadedRichMarkdownEditorProps) {
   /** Whether this editor mounted mid-stream — if so it starts empty and syncs streamed chunks until settle. */
   const streamingAtMountRef = useRef(isStreaming)
@@ -288,6 +307,19 @@ export function LoadedRichMarkdownEditor({
   onChangeRef.current = onChange
   const onSaveShortcutRef = useRef(onSaveShortcut)
   onSaveShortcutRef.current = onSaveShortcut
+
+  /**
+   * Untitled ⇄ heading coupling, active only while the file is unnamed. `onDeriveTitleFromHeading` is
+   * called (debounced) so the caller can name the file after its leading heading; `fileNameRef` lets the
+   * onUpdate handler read the current name without re-subscribing, and `prevFileNameRef` lets the
+   * name→heading seed detect the untitled→named transition. See {@link isUntitledName}.
+   */
+  const onDeriveTitleFromHeadingRef = useRef(onDeriveTitleFromHeading)
+  onDeriveTitleFromHeadingRef.current = onDeriveTitleFromHeading
+  const fileNameRef = useRef(file.name)
+  fileNameRef.current = file.name
+  const prevFileNameRef = useRef(file.name)
+  const deriveTitleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
   /**
    * Read in the RAF tick so an already-scheduled tick still sees the latest edit kind (it can change
    * between sessions within one turn, e.g. an append followed by a rewrite).
@@ -546,10 +578,52 @@ export function LoadedRichMarkdownEditor({
       const md = postProcessSerializedMarkdown(editor.getMarkdown())
       lastSyncedBodyRef.current = md
       onChangeRef.current(applyFrontmatter(settledRef.current?.frontmatter ?? '', md))
+      // While the file is still untitled, name it after its leading heading once typing settles. Always
+      // clear any pending timer first, so deleting/rewriting the heading before it fires cancels the
+      // stale rename; the timer re-derives the title from the live doc rather than a value captured at
+      // schedule time, so it can never name the file after a heading the user has since changed or removed.
+      if (deriveTitleTimerRef.current) clearTimeout(deriveTitleTimerRef.current)
+      if (!isUntitledName(fileNameRef.current) || firstHeadingTitle(editor.state.doc) === null)
+        return
+      deriveTitleTimerRef.current = setTimeout(() => {
+        const liveEditor = editorInstanceRef.current
+        if (!liveEditor || !isUntitledName(fileNameRef.current)) return
+        const title = firstHeadingTitle(liveEditor.state.doc)
+        if (title) onDeriveTitleFromHeadingRef.current?.(title)
+      }, DERIVE_TITLE_DEBOUNCE_MS)
     },
   })
   editorInstanceRef.current = editor
 
+  useEffect(
+    () => () => {
+      if (deriveTitleTimerRef.current) clearTimeout(deriveTitleTimerRef.current)
+    },
+    []
+  )
+
+  /**
+   * Name→heading seed: when a still-untitled file is given a real name, seed the document's leading
+   * heading from that name — but only into a document with no heading of its own yet, so existing
+   * content is never clobbered. One-shot by construction: it fires only on the untitled→named transition.
+   */
+  useEffect(() => {
+    // Wait for a render with a live, editable editor before consuming the transition — advancing
+    // prevFileNameRef while editor is still null would record the untitled→named change as "seen" and
+    // silently skip the seed on the later render when the editor is ready.
+    if (!editor || !isEditable) return
+    const prevName = prevFileNameRef.current
+    prevFileNameRef.current = file.name
+    if (!isUntitledName(prevName) || isUntitledName(file.name)) return
+    if (firstHeadingTitle(editor.state.doc) !== null) return
+    const title = headingTextFromName(file.name)
+    if (!title) return
+    // Always prepend, never replace: an empty doc becomes `# Title` + a body line, while any existing
+    // content — including structure-only scaffold (an empty list/blockquote/code block that carries no
+    // text) — is preserved above rather than clobbered.
+    editor.commands.insertContentAt(0, titleHeadingNode(title))
+  }, [file.name, editor, isEditable])
+
   /**
    * The loaded markdown to seed the shared doc from, held by pointer so the parse
    * runs once at seed time rather than every render.

apps/sim/app/workspace/[workspaceId]/files/components/file-viewer/rich-markdown-editor/title-heading.test.ts

@@ -0,0 +1,117 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { Editor } from '@tiptap/core'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { createMarkdownEditorExtensions } from './editor-extensions'
+import { firstHeadingTitle, titleHeadingNode } from './title-heading'
+
+function editorWith(markdown: string): Editor {
+  const editor = new Editor({ extensions: createMarkdownEditorExtensions({ placeholder: '' }) })
+  if (markdown) editor.commands.setContent(markdown, { contentType: 'markdown' })
+  return editor
+}
+
+describe('firstHeadingTitle', () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      'ResizeObserver',
+      class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      }
+    )
+    Element.prototype.scrollIntoView = vi.fn()
+    document.elementFromPoint = vi.fn(() => null)
+  })
+
+  it('returns the leading H1 text', () => {
+    const editor = editorWith('# Q3 Planning\n\nbody')
+    expect(firstHeadingTitle(editor.state.doc)).toBe('Q3 Planning')
+    editor.destroy()
+  })
+
+  it('returns the text of any leading heading level', () => {
+    const editor = editorWith('## Sub title')
+    expect(firstHeadingTitle(editor.state.doc)).toBe('Sub title')
+    editor.destroy()
+  })
+
+  it('returns null when the first block is a paragraph, not a heading', () => {
+    const editor = editorWith('just text\n\n# later heading')
+    expect(firstHeadingTitle(editor.state.doc)).toBeNull()
+    editor.destroy()
+  })
+
+  it('returns null for an empty leading heading', () => {
+    const editor = editorWith('')
+    editor.commands.setContent({ type: 'doc', content: [{ type: 'heading', attrs: { level: 1 } }] })
+    expect(firstHeadingTitle(editor.state.doc)).toBeNull()
+    editor.destroy()
+  })
+
+  it('returns null for a whitespace-only leading heading (trim boundary)', () => {
+    const editor = editorWith('')
+    editor.commands.setContent({
+      type: 'doc',
+      content: [{ type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: '   ' }] }],
+    })
+    expect(firstHeadingTitle(editor.state.doc)).toBeNull()
+    editor.destroy()
+  })
+})
+
+describe('title-heading seed (Trigger B action — always prepend, never replace)', () => {
+  beforeEach(() => {
+    vi.stubGlobal(
+      'ResizeObserver',
+      class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      }
+    )
+    Element.prototype.scrollIntoView = vi.fn()
+    document.elementFromPoint = vi.fn(() => null)
+  })
+
+  it('seeds an empty doc with a leading H1 (+ a body line)', () => {
+    const editor = editorWith('')
+    editor.commands.insertContentAt(0, titleHeadingNode('Q3 Planning'))
+
+    expect(editor.state.doc.firstChild?.type.name).toBe('heading')
+    expect(firstHeadingTitle(editor.state.doc)).toBe('Q3 Planning')
+    expect(editor.getMarkdown().trim()).toBe('# Q3 Planning')
+    editor.destroy()
+  })
+
+  it('prepends an H1 to existing body without a heading, keeping the body', () => {
+    const editor = editorWith('some body text')
+    editor.commands.insertContentAt(0, titleHeadingNode('My Notes'))
+
+    expect(editor.state.doc.firstChild?.type.name).toBe('heading')
+    expect(firstHeadingTitle(editor.state.doc)).toBe('My Notes')
+    expect(editor.getMarkdown()).toContain('some body text')
+    editor.destroy()
+  })
+
+  it('preserves structure-only scaffold (empty bullet list) instead of clobbering it', () => {
+    // Regression: an empty bullet list carries no text, so a replace-based seed would drop it. The
+    // prepend keeps it below the seeded H1.
+    const editor = editorWith('')
+    editor.commands.setContent({
+      type: 'doc',
+      content: [
+        { type: 'bulletList', content: [{ type: 'listItem', content: [{ type: 'paragraph' }] }] },
+      ],
+    })
+    editor.commands.insertContentAt(0, titleHeadingNode('Kept'))
+
+    const shape: string[] = []
+    editor.state.doc.forEach((n) => shape.push(n.type.name))
+    expect(shape).toEqual(['heading', 'bulletList', 'paragraph'])
+    expect(firstHeadingTitle(editor.state.doc)).toBe('Kept')
+    editor.destroy()
+  })
+})

apps/sim/app/workspace/[workspaceId]/files/components/file-viewer/rich-markdown-editor/title-heading.ts

@@ -0,0 +1,15 @@
+import type { JSONContent } from '@tiptap/core'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+
+/** The text of the document's leading heading (any level), or null when the first block isn't a heading. */
+export function firstHeadingTitle(doc: ProseMirrorNode): string | null {
+  const first = doc.firstChild
+  if (!first || first.type.name !== 'heading') return null
+  const text = first.textContent.trim()
+  return text.length > 0 ? text : null
+}
+
+/** A level-1 heading node carrying `title`, used to seed a document's title from the file name. */
+export function titleHeadingNode(title: string): JSONContent {
+  return { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: title }] }
+}

apps/sim/app/workspace/[workspaceId]/files/files.tsx

@@ -85,6 +85,12 @@ import {
   filesSortParams,
   filesUrlKeys,
 } from '@/app/workspace/[workspaceId]/files/search-params'
+import {
+  DEFAULT_UNTITLED_NAME,
+  deriveMarkdownFileName,
+  isUntitledName,
+  uniqueMarkdownName,
+} from '@/app/workspace/[workspaceId]/files/untitled-title'
 import { useUserPermissionsContext } from '@/app/workspace/[workspaceId]/providers/workspace-permissions-provider'
 import { useContextMenu } from '@/app/workspace/[workspaceId]/w/components/sidebar/hooks'
 import { useWorkspaceMembersQuery, type WorkspaceMember } from '@/hooks/queries/workspace'
@@ -356,6 +362,34 @@ export function Files() {
   const selectedFileRef = useRef(selectedFile)
   selectedFileRef.current = selectedFile
 
+  /**
+   * While a file is still untitled, name it after the leading heading the user types in its editor. The
+   * editor reports the heading text (debounced); here we re-check the file is still untitled, derive a
+   * unique `.md` name among its folder siblings, and rename. A no-op once the file has a real name.
+   */
+  const handleDeriveTitleFromHeading = useCallback(
+    (headingText: string) => {
+      const currentFile = selectedFileRef.current
+      if (!currentFile || !isUntitledName(currentFile.name)) return
+      const derived = deriveMarkdownFileName(headingText)
+      if (!derived) return
+      const siblingNames = new Set(
+        filesRef.current
+          .filter(
+            (f) =>
+              (f.folderId ?? null) === (currentFile.folderId ?? null) && f.id !== currentFile.id
+          )
+          .map((f) => f.name)
+      )
+      const name = uniqueMarkdownName(derived, siblingNames)
+      if (name === currentFile.name) return
+      renameFile
+        .mutateAsync({ workspaceId, fileId: currentFile.id, name })
+        .catch((err) => logger.error('Failed to auto-name file from heading:', err))
+    },
+    [workspaceId]
+  )
+
   const shareFile = shareFileId ? (files.find((f) => f.id === shareFileId) ?? null) : null
   const shareModal = shareFile ? (
     <ShareModal
@@ -1189,12 +1223,7 @@ export function Files() {
       const existingNames = new Set(
         filesRef.current.filter((f) => (f.folderId ?? null) === currentFolderId).map((f) => f.name)
       )
-      let name = 'untitled.md'
-      let counter = 1
-      while (existingNames.has(name)) {
-        name = `untitled (${counter}).md`
-        counter++
-      }
+      const name = uniqueMarkdownName(DEFAULT_UNTITLED_NAME, existingNames)
 
       const mimeType = getMimeTypeFromExtension('md')
       const blob = new Blob([''], { type: mimeType })
@@ -1931,6 +1960,7 @@ export function Files() {
               saveRef={saveRef}
               discardRef={discardRef}
               collaborative
+              onDeriveTitleFromHeading={handleDeriveTitleFromHeading}
             />
 
             <ChipConfirmModal