documentation notes, feedback and npm caching

Author: tannerlinsley

AGENTS.md

@@ -161,3 +161,25 @@ Since `listRoles` is wrapped in `createServerFn`, TanStack Start will properly h
 **The `dev` command does not end - it runs indefinitely in watch mode.**
 
 When agents need to test build output or verify that the project builds successfully, use the `build` command instead of `dev`. The `build` command will complete and exit, making it suitable for automated testing and verification.
+
+### Testing Limitations
+
+**Agents cannot run end-to-end tests without a headless browser.**
+
+This is a TanStack Start application that requires a browser environment to fully test. Agents can:
+
+- ✅ Run TypeScript compilation (`pnpm tsc --noEmit`) to check for type errors
+- ✅ Run the build command (`pnpm build`) to verify the project builds successfully
+- ✅ Inspect build output and generated files
+
+Agents cannot:
+
+- ❌ Start the dev server and interact with the application (no headless browser)
+- ❌ Test UI functionality or user interactions
+- ❌ Verify runtime behavior in the browser
+- ❌ Test API endpoints that require browser context
+
+For runtime testing and verification, developers should:
+1. Review the code changes
+2. Start the dev server manually (`pnpm dev`)
+3. Test the functionality in a browser

src/components/BlockWithFeedback.tsx

@@ -0,0 +1,123 @@
+import * as React from 'react'
+import { twMerge } from 'tailwind-merge'
+import { DocFeedbackFloatingButton } from './DocFeedbackFloatingButton'
+import { DocFeedbackNote } from './DocFeedbackNote'
+import { useDocFeedbackRequired } from './DocFeedbackContext'
+import { getBlockIdentifier } from '~/utils/docFeedback.client'
+
+interface BlockWithFeedbackProps {
+  children: React.ReactNode
+  className?: string
+}
+
+export function BlockWithFeedback({
+  children,
+  className,
+}: BlockWithFeedbackProps) {
+  const blockRef = React.useRef<HTMLDivElement>(null)
+  const [isHovered, setIsHovered] = React.useState(false)
+  const [blockSelector, setBlockSelector] = React.useState<string | null>(null)
+  const [contentHash, setContentHash] = React.useState<string | undefined>()
+
+  const feedback = useDocFeedbackRequired()
+
+  // Generate block selector on mount
+  React.useEffect(() => {
+    if (blockRef.current) {
+      // Get the first child element (the actual content block, not our wrapper)
+      const contentElement = blockRef.current.firstElementChild as HTMLElement
+      if (contentElement) {
+        getBlockIdentifier(contentElement).then((identifier) => {
+          setBlockSelector(identifier.selector)
+          setContentHash(identifier.contentHash)
+        })
+      }
+    }
+  }, [])
+
+  // Find note for this block
+  const note = React.useMemo(() => {
+    if (!blockSelector) return null
+    return feedback.userNotes.find((n) => n.blockSelector === blockSelector)
+  }, [feedback.userNotes, blockSelector])
+
+  const isCollapsed = note ? feedback.collapsedNotes.has(note.id) : false
+  const hasNote = !!note
+
+  const handleAddNote = React.useCallback(() => {
+    if (blockSelector) {
+      feedback.onAddFeedback(blockSelector, contentHash, 'note')
+    }
+  }, [blockSelector, contentHash, feedback])
+
+  const handleAddFeedback = React.useCallback(() => {
+    if (blockSelector) {
+      feedback.onAddFeedback(blockSelector, contentHash, 'improvement')
+    }
+  }, [blockSelector, contentHash, feedback])
+
+  const handleShowNote = React.useCallback(() => {
+    if (note) {
+      feedback.onShowNote(note.id)
+    }
+  }, [note, feedback])
+
+  const handleMouseEnter = React.useCallback(() => {
+    setIsHovered(true)
+  }, [])
+
+  const handleMouseLeave = React.useCallback(() => {
+    setIsHovered(false)
+  }, [])
+
+  return (
+    <>
+      <div
+        ref={blockRef}
+        className={twMerge(
+          'relative doc-feedback-block',
+          isHovered && 'doc-feedback-block-highlighted',
+          className,
+        )}
+        onMouseEnter={handleMouseEnter}
+        onMouseLeave={handleMouseLeave}
+        data-feedback-wrapper="true"
+        style={{
+          anchorName: blockSelector ? `--feedback-${blockSelector.replace(/[^a-zA-Z0-9]/g, '-')}` : undefined,
+        }}
+      >
+        {children}
+
+        {/* Floating button */}
+        {blockSelector && (
+          <div
+            className={twMerge(
+              'absolute top-0 right-0 -translate-y-full z-50 transition-opacity duration-200',
+              hasNote || isHovered ? 'opacity-100' : 'opacity-0',
+            )}
+          >
+            <DocFeedbackFloatingButton
+              onAddNote={handleAddNote}
+              onAddFeedback={handleAddFeedback}
+              onMouseEnter={handleMouseEnter}
+              onMouseLeave={handleMouseLeave}
+              hasNote={hasNote}
+              onShowNote={handleShowNote}
+            />
+          </div>
+        )}
+      </div>
+
+      {/* Note display - inline in document flow */}
+      {note && blockSelector && (
+        <div className="my-4">
+          <DocFeedbackNote
+            note={note}
+            anchorName=""
+            inline={true}
+          />
+        </div>
+      )}
+    </>
+  )
+}

src/components/ClientAuth.tsx

@@ -1,6 +1,6 @@
 import { ErrorComponent } from '@tanstack/react-router'
 import React from 'react'
-import { FaSpinner } from 'react-icons/fa'
+import { Spinner } from '~/components/Spinner'
 import { SignInForm } from '~/routes/_libraries/login'
 import { useCurrentUserQuery } from '~/hooks/useCurrentUser'
 
@@ -18,7 +18,7 @@ export function ClientAuth({
   if (userQuery.isLoading) {
     return (
       <div className={baseClasses}>
-        <FaSpinner className="animate-spin" />
+        <Spinner />
       </div>
     )
   }
@@ -49,7 +49,7 @@ export function ClientAdminAuth({ children }: { children: React.ReactNode }) {
   if (userQuery.isLoading) {
     return (
       <div className={baseClasses}>
-        <FaSpinner className="animate-spin" />
+        <Spinner />
       </div>
     )
   }

src/components/Doc.tsx

@@ -17,6 +17,7 @@ import { CopyMarkdownButton } from './CopyMarkdownButton'
 import { GamHeader } from './Gam'
 import { Toc } from './Toc'
 import { TocMobile } from './TocMobile'
+import { DocFeedbackProvider } from './DocFeedbackProvider'
 
 type DocProps = {
   title: string
@@ -27,6 +28,10 @@ type DocProps = {
   shouldRenderToc?: boolean
   colorFrom?: string
   colorTo?: string
+  // Feedback props (optional)
+  libraryId?: string
+  libraryVersion?: string
+  pagePath?: string
 }
 
 function DocContent({
@@ -38,6 +43,9 @@ function DocContent({
   shouldRenderToc = false,
   colorFrom,
   colorTo,
+  libraryId,
+  libraryVersion,
+  pagePath,
 }: DocProps) {
   const { headings } = useMarkdownHeadings()
 
@@ -159,7 +167,17 @@ function DocContent({
               'styled-markdown-content',
             )}
           >
-            <Markdown rawContent={content} />
+            {libraryId && libraryVersion && pagePath ? (
+              <DocFeedbackProvider
+                pagePath={pagePath}
+                libraryId={libraryId}
+                libraryVersion={libraryVersion}
+              >
+                <Markdown rawContent={content} />
+              </DocFeedbackProvider>
+            ) : (
+              <Markdown rawContent={content} />
+            )}
           </div>
           <div className="h-12" />
           <div className="w-full h-px bg-gray-500 opacity-30" />

src/components/DocFeedbackContext.tsx

@@ -0,0 +1,38 @@
+import * as React from 'react'
+import type { DocFeedback } from '~/db/schema'
+
+interface DocFeedbackContextValue {
+  // User feedback for the current page
+  userNotes: DocFeedback[]
+
+  // Collapsed state
+  collapsedNotes: Set<string>
+  toggleNote: (noteId: string) => void
+
+  // Actions
+  onAddFeedback: (blockSelector: string, blockContentHash: string | undefined, type: 'note' | 'improvement') => void
+  onEditNote: (note: DocFeedback) => void
+  onShowNote: (noteId: string) => void
+
+  // Page info
+  pagePath: string
+  libraryId: string
+  libraryVersion: string
+}
+
+const DocFeedbackContext = React.createContext<DocFeedbackContextValue | null>(null)
+
+export function useDocFeedback() {
+  const context = React.useContext(DocFeedbackContext)
+  return context
+}
+
+export function useDocFeedbackRequired() {
+  const context = useDocFeedback()
+  if (!context) {
+    throw new Error('useDocFeedback must be used within DocFeedbackProvider')
+  }
+  return context
+}
+
+export const DocFeedbackContextProvider = DocFeedbackContext.Provider