Add Atlas Cropper documentation

REVIEWERS.md

@@ -4,7 +4,7 @@ This file is intended to used as **review guidance** for automated/agent code re
 
 ## CodeBlock component / shiki codeblock styling divergence
 
-The react codeblock component should avoid creating custom styles for itself, prefer styling shiki and it's elements from app/styles/shiki.css and and lib/shiki.ts
+The react codeblock component should avoid creating custom styles for itself, prefer styling shiki and it's elements from app/styles/shiki.css and and lib/mdx.ts
 
 ### Why
 

app/(registry)/[[...slug]]/page.tsx

@@ -35,6 +35,8 @@ import { cn } from '@/lib/utils'
 import { RegistryMetaProvider } from '@/components/registry-meta'
 import { PageGithubLinkButton } from '@/components/page-github-link-button'
 import { PageViews } from '@/components/layout/views'
+import { MDXContent } from '@/components/content'
+import { getLibraryReadme } from '@/lib/libraries'
 
 const getComponentSlug = (page: InferPageType<typeof source>) => {
   if (page.slugs[0] !== 'components') return undefined
@@ -91,17 +93,21 @@ export default async function Page(props: PageProps<'/[[...slug]]'>) {
   })()
 
   const componentSlug = getComponentSlug(page)
-  const [downloadStats, pageViews] = await Promise.all([
+  const isLibrary = page.data.type === 'library' && page.data.repo
+  const [downloadStats, pageViews, libraryReadme] = await Promise.all([
     componentSlug ? getComponentDownloadStats(componentSlug) : null,
     isLog ? getPageViews(`/logs/${page.slugs[page.slugs.length - 1]}`) : null,
+    isLibrary ? getLibraryReadme(page.data.repo!) : null,
   ])
   const componentSource = await getComponentSource(componentSlug)
   const docLinks = [...page.data.docLinks]
   const llmText = await getLLMText(page)
   const llmUrl = page.slugs.length === 0 ? null : `/${page.slugs.join('/')}.md`
   const relatedItems = getRelatedPages(page, 3)
 
-  const toc = page.data.toc
+  const toc = libraryReadme
+    ? [...page.data.toc, ...libraryReadme.toc]
+    : page.data.toc
   const hasToc = toc.length > 0
   const counts = getRegistryCounts()
 
@@ -187,6 +193,7 @@ export default async function Page(props: PageProps<'/[[...slug]]'>) {
                 a: createRelativeLink(source, page),
               })}
             />
+            {libraryReadme && <MDXContent content={libraryReadme.cleaned} />}
           </div>
           {!isTopCategoryPage && relatedItems.length > 0 && (
             <RelatedItems

app/(registry)/layout.tsx

@@ -1,10 +1,10 @@
 import type { CSSProperties } from 'react'
-import { cookies } from 'next/headers'
 import {
   source,
   getGameSlugs,
   getEffectSlugs,
   getCanvasSlugs,
+  getLibrarySlugs,
 } from '@/lib/source'
 import { TreeContextProvider } from 'fumadocs-ui/contexts/tree'
 import {
@@ -16,24 +16,24 @@ import { MobileNav } from '@/components/layout/mobile-nav'
 import { getExperiments } from '@/lib/lab'
 import { CommandPalette } from '@/components/layout/command-palette'
 
-export default async function Layout({ children }: LayoutProps<'/'>) {
-  const cookieStore = await cookies()
-  const isTeam = cookieStore.has('joyco-team')
-
-  const itemMeta: Record<
-    string,
-    {
-      badge?: 'new' | 'updated' | 'internal'
-      dot?: 'red' | 'blue' | 'green' | 'yellow'
-      hidden?: boolean
-    }
-  > = {
-    '/toolbox/skills': { badge: 'new' },
-    '/toolbox/ui': isTeam ? { badge: 'internal' } : { hidden: true },
+const itemMeta: Record<
+  string,
+  {
+    badge?: 'new' | 'updated' | 'internal'
+    dot?: 'red' | 'blue' | 'green' | 'yellow'
+    hidden?: boolean
   }
+> = {
+  '/toolbox/atlas-cropper': { badge: 'new' },
+  '/toolbox/skills': { badge: 'new' },
+  '/toolbox/ui': { hidden: true },
+}
+
+export default async function Layout({ children }: LayoutProps<'/'>) {
   const gameSlugs = getGameSlugs()
   const effectSlugs = getEffectSlugs()
   const canvasSlugs = getCanvasSlugs()
+  const librarySlugs = getLibrarySlugs()
   const { experiments } = await getExperiments()
 
   return (
@@ -58,6 +58,7 @@ export default async function Layout({ children }: LayoutProps<'/'>) {
             gameSlugs={gameSlugs}
             effectSlugs={effectSlugs}
             canvasSlugs={canvasSlugs}
+            librarySlugs={librarySlugs}
             experiments={experiments}
           />
           {children}

app/api/screenshot/route.ts

@@ -108,7 +108,7 @@ const getCachedExperimentScreenshot = unstable_cache(
     )
   },
   ['experiment-screenshot'],
-  { revalidate: 86400 }
+  { revalidate: 604800 }
 )
 
 export async function GET(request: NextRequest) {
@@ -139,7 +139,7 @@ export async function GET(request: NextRequest) {
     return new NextResponse(imageBuffer, {
       headers: {
         'Content-Type': 'image/png',
-        'Cache-Control': 'public, s-maxage=31536000',
+        'Cache-Control': 'public, max-age=604800, s-maxage=604800, stale-while-revalidate=86400',
       },
     })
   } catch (error) {

components/category-index.tsx

@@ -10,6 +10,24 @@ import { Badge } from './ui/badge'
 import { EyeIcon } from 'lucide-react'
 import { Fragment } from 'react'
 
+type PageTreeNode = {
+  type?: string
+  $id?: string
+  url?: string
+  children?: PageTreeNode[]
+}
+
+function getPageTreeOrder(category: string): string[] {
+  const children = source.pageTree.children as unknown as PageTreeNode[]
+  const folder = children.find(
+    (child) => child.type === 'folder' && child.$id?.split(':')[1] === category
+  )
+  if (!folder?.children) return []
+  return folder.children
+    .filter((child) => child.type === 'page' && child.url)
+    .map((child) => child.url!)
+}
+
 export async function CategoryIndex({
   category,
 }: {
@@ -18,6 +36,18 @@ export async function CategoryIndex({
   const pages = source
     .getPages()
     .filter((page) => page.slugs[0] === category && page.slugs.length > 1)
+
+  // Sort pages based on meta.json order (reflected in the page tree)
+  const pageTreeOrder = getPageTreeOrder(category)
+  if (pageTreeOrder.length > 0) {
+    const orderMap = new Map(pageTreeOrder.map((url, i) => [url, i]))
+    pages.sort((a, b) => {
+      const aIndex = orderMap.get(a.url) ?? Infinity
+      const bIndex = orderMap.get(b.url) ?? Infinity
+      return aIndex - bIndex
+    })
+  }
+
   if (category === 'logs') pages.reverse()
   const typeMap: Record<keyof RegistryCounts, ItemType> = {
     components: 'component',

components/code-source.tsx

@@ -4,7 +4,7 @@ import {
   highlightCode,
   getLanguageFromExtension,
   stripFrontmatter,
-} from '@/lib/shiki'
+} from '@/lib/mdx'
 import { CodeBlock } from '@/components/code-block'
 
 export async function FileCodeblock({

components/content.tsx

@@ -0,0 +1,15 @@
+import { Markdown } from 'fumadocs-core/content'
+import { getMDXComponents } from '@/mdx-components'
+import { rehypePlugins, remarkPlugins } from '@/lib/mdx'
+
+export function MDXContent({ content }: { content: string }) {
+  return (
+    <Markdown
+      remarkPlugins={remarkPlugins}
+      rehypePlugins={rehypePlugins}
+      components={getMDXComponents()}
+    >
+      {content}
+    </Markdown>
+  )
+}

components/layout/mobile-nav.tsx

@@ -16,6 +16,7 @@ import FileIcon from '@/components/icons/file'
 import FlaskIcon from '@/components/icons/flask'
 import type { SidebarItemMeta } from './sidebar/section'
 import type { Experiment } from '@/lib/lab'
+import { useIsTeam } from '@/hooks/use-team-cookie'
 import { MetaBadge } from '@/components/layout/meta-badge'
 import { SearchResults } from './sidebar/search-results'
 import { NoResults } from './sidebar/no-results'
@@ -52,9 +53,17 @@ const sectionIcons: Record<
 
 export function MobileNav({
   tree,
-  itemMeta = {},
+  itemMeta: itemMetaProp = {},
   experiments = [],
 }: MobileNavProps) {
+  const isTeam = useIsTeam()
+  const itemMeta = React.useMemo(
+    () =>
+      isTeam
+        ? { ...itemMetaProp, '/toolbox/ui': { badge: 'internal' as const } }
+        : itemMetaProp,
+    [isTeam, itemMetaProp]
+  )
   const pathname = usePathname()
   const router = useRouter()
   const inputRef = React.useRef<HTMLInputElement>(null)

components/layout/sidebar/index.tsx

@@ -13,6 +13,7 @@ import { LabSidebarSection } from './lab-section'
 import { SocialLinks } from './social-links'
 import { NavAside } from '../nav-aside'
 import { useSearch } from '@/hooks/use-search'
+import { useIsTeam } from '@/hooks/use-team-cookie'
 import type { Experiment } from '@/lib/lab'
 
 export type { SidebarItemMeta }
@@ -23,6 +24,7 @@ type RegistrySidebarProps = {
   gameSlugs?: string[]
   effectSlugs?: string[]
   canvasSlugs?: string[]
+  librarySlugs?: string[]
   experiments?: Experiment[]
 }
 
@@ -32,8 +34,17 @@ export function RegistrySidebar({
   gameSlugs = [],
   effectSlugs = [],
   canvasSlugs = [],
+  librarySlugs = [],
   experiments = [],
 }: RegistrySidebarProps) {
+  const isTeam = useIsTeam()
+  const resolvedMeta = React.useMemo(
+    () =>
+      isTeam
+        ? { ...itemMeta, '/toolbox/ui': { badge: 'internal' as const } }
+        : itemMeta,
+    [isTeam, itemMeta]
+  )
   const pathname = usePathname()
   const router = useRouter()
   const {
@@ -106,10 +117,11 @@ export function RegistrySidebar({
         <SidebarSection
           folder={folder}
           defaultOpen
-          meta={itemMeta}
+          meta={resolvedMeta}
           gameSlugs={gameSlugs}
           effectSlugs={effectSlugs}
           canvasSlugs={canvasSlugs}
+          librarySlugs={librarySlugs}
         />
       </nav>
     )

components/layout/sidebar/section.tsx

@@ -11,7 +11,7 @@ import FileIcon from '@/components/icons/file'
 import FlaskIcon from '@/components/icons/flask'
 import GamepadIcon from '@/components/icons/gamepad'
 import TextScanIcon from '@/components/icons/text-scan'
-import { Frame, Minus, Plus } from 'lucide-react'
+import { Frame, Library, Minus, Plus } from 'lucide-react'
 import { getLogNumber, stripLogPrefixFromTitle } from '@/lib/log-utils'
 import { MetaBadge } from '@/components/layout/meta-badge'
 
@@ -214,6 +214,7 @@ type SidebarSectionProps = {
   gameSlugs?: string[]
   effectSlugs?: string[]
   canvasSlugs?: string[]
+  librarySlugs?: string[]
 }
 
 /**
@@ -227,6 +228,7 @@ export function SidebarSection({
   gameSlugs = [],
   effectSlugs = [],
   canvasSlugs = [],
+  librarySlugs = [],
 }: SidebarSectionProps) {
   const [isOpen, setIsOpen] = React.useState(defaultOpen)
   const pathname = usePathname()
@@ -309,7 +311,44 @@ export function SidebarSection({
     )
   }
 
-  // For other sections (Toolbox, Logs), render with collapsible header
+  // For toolbox section, split into General and Libraries
+  if (sectionId === 'toolbox' && librarySlugs.length > 0) {
+    const isLibrary = (url: string) => {
+      const slug = url.split('/').pop() ?? ''
+      return librarySlugs.includes(slug)
+    }
+
+    const pages = folder.children.filter(
+      (child): child is PageTree.Item => child.type === 'page'
+    )
+    const generalPages = pages.filter((page) => !isLibrary(page.url))
+    const libraryPages = pages.filter((page) => isLibrary(page.url))
+
+    return (
+      <div className="flex flex-col">
+        <CollapsibleSubSection
+          name="General"
+          icon={TerminalWithCursorIcon}
+          pages={generalPages}
+          meta={meta}
+          defaultOpen
+          sectionId={sectionId}
+        />
+        {libraryPages.length > 0 && (
+          <CollapsibleSubSection
+            name="Libraries"
+            icon={Library}
+            pages={libraryPages}
+            meta={meta}
+            defaultOpen
+            sectionId={sectionId}
+          />
+        )}
+      </div>
+    )
+  }
+
+  // For other sections (Logs), render with collapsible header
   return (
     <div className="flex flex-col">
       <button

components/preview/component-source-code.tsx

@@ -3,7 +3,7 @@ import path from 'path'
 import { getRegistryExampleComponentFile } from '@/lib/registry-examples'
 import { CodeBlock } from '../code-block'
 import { CodeBlockTabs, type CodeTab } from '../code-block-tabs'
-import { highlightCode } from '@/lib/shiki'
+import { highlightCode } from '@/lib/mdx'
 
 function getLanguageFromPath(filePath: string): string {
   const ext = path.extname(filePath).slice(1)
@@ -24,7 +24,10 @@ export async function ComponentSource({
 }: {
   name?: string
   maxHeight?: number
-} & Omit<React.ComponentProps<typeof CodeBlock>, 'rawCode' | 'highlightedCode'>) {
+} & Omit<
+  React.ComponentProps<typeof CodeBlock>,
+  'rawCode' | 'highlightedCode'
+>) {
   if (!name) {
     return null
   }

content/components/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Components
-description: A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands. A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands.
+description: A collection of reusable UI components, canvas utilities, animation effects, and interactive games built for the web.
 ---
 
 import { CategoryIndex } from '@/components/category-index'