aihand 0.0.1 → 0.1.0

package/src/read/render.ts

@@ -0,0 +1,1118 @@
+import type { Tree } from 'web-tree-sitter'
+import type { Config, FileBlock, FileDetailLevel } from './types.js'
+import { existsSync, readFileSync } from 'node:fs'
+import ignore from 'ignore'
+import { fromMarkdown } from 'mdast-util-from-markdown'
+import { parse as parseHtml } from 'node-html-parser'
+import postcss from 'postcss'
+import postcssLess from 'postcss-less'
+import postcssScss from 'postcss-scss'
+import { Parser } from 'web-tree-sitter'
+import { parse as parseYaml } from 'yaml'
+import { compact, extractImports, getLang } from './compact.js'
+
+// ── D2: Classify ────────────────────────────────────────
+
+/** Pre-compile fileDetailLevel patterns into a fast per-path classifier. */
+export function buildClassifier(
+    detail: Record<string, FileDetailLevel>,
+    defaultLevel: FileDetailLevel = 'compact',
+): (path: string) => FileDetailLevel {
+    const matchers: Array<{ level: FileDetailLevel, ig: ReturnType<typeof ignore> }> = []
+    for (const level of ['tree', 'full', 'compact'] as const) {
+        const globs = Object.keys(detail).filter(p => detail[p] === level)
+        if (globs.length)
+            matchers.push({ level, ig: ignore().add(globs) })
+    }
+    return path => matchers.find(m => m.ig.ignores(path))?.level ?? defaultLevel
+}
+
+// ── D3: Transform ───────────────────────────────────────
+
+// ── Tech stack detection ─────────────────────────────────
+
+/** Known skeleton-defining packages (whitelist). Only these appear in stack line. */
+const STACK_INCLUDE: Set<string> = new Set([
+    // Platform
+    'electron',
+    'react-native',
+    '@tauri-apps/api',
+    '@capacitor/core',
+    // Meta-framework
+    'next',
+    'nuxt',
+    '@remix-run/react',
+    'astro',
+    'gatsby',
+    '@sveltejs/kit',
+    // UI framework
+    'react',
+    'vue',
+    'svelte',
+    'solid-js',
+    '@angular/core',
+    // Build
+    'vite',
+    'webpack',
+    'esbuild',
+    '@rspack/core',
+    'turbopack',
+    // Monorepo
+    'turbo',
+    'nx',
+    // Language
+    'typescript',
+    // Styling
+    'tailwindcss',
+    'unocss',
+    'styled-components',
+    '@emotion/css',
+    '@emotion/react',
+    '@vanilla-extract/css',
+    // Component lib
+    'class-variance-authority',
+    '@mui/material',
+    'antd',
+    '@chakra-ui/react',
+    '@mantine/core',
+    '@headlessui/react',
+    'element-plus',
+    '@arco-design/web-react',
+    '@arco-design/mobile-react',
+    'naive-ui',
+    'vuetify',
+    // Icons
+    'lucide-react',
+    '@heroicons/react',
+    // Routing
+    'react-router-dom',
+    '@tanstack/react-router',
+    'vue-router',
+    // State
+    'mobx',
+    'zustand',
+    'redux',
+    '@reduxjs/toolkit',
+    '@tanstack/react-query',
+    'jotai',
+    'pinia',
+    'valtio',
+    'xstate',
+    'swr',
+    '@apollo/client',
+    // Forms
+    'react-hook-form',
+    // Animation
+    'framer-motion',
+    '@react-spring/web',
+    // Rich text / Editor
+    '@tiptap/react',
+    '@monaco-editor/react',
+    // DnD
+    '@dnd-kit/core',
+    // Virtualization
+    '@tanstack/react-virtual',
+    // Charts
+    'recharts',
+    '@nivo/core',
+    'd3',
+    // Canvas / Visual
+    '@xyflow/react',
+    'three',
+    '@react-three/fiber',
+    // Testing
+    'vitest',
+    'jest',
+    '@playwright/test',
+    'cypress',
+    // Backend
+    'express',
+    'fastify',
+    'hono',
+    '@nestjs/core',
+    // ORM / DB
+    'drizzle-orm',
+    'prisma',
+    '@prisma/client',
+    'mongoose',
+    // BaaS
+    '@supabase/supabase-js',
+    'firebase',
+    // AI
+    'ai',
+    '@langchain/core',
+    // API
+    '@trpc/server',
+    'graphql',
+    // Storage
+    'dexie',
+])
+
+/** Scoped packages → collapsed label (first prefix match wins, avoids duplicates) */
+const STACK_COLLAPSE: Array<{ prefix: string, label: string }> = [
+    { prefix: '@dnd-kit/', label: 'dnd-kit' },
+    { prefix: '@tiptap/', label: 'tiptap' },
+    { prefix: '@tanstack/react-query', label: 'tanstack-query' },
+    { prefix: '@tanstack/react-router', label: 'tanstack-router' },
+    { prefix: '@tanstack/react-virtual', label: 'tanstack-virtual' },
+    { prefix: '@emotion/', label: 'emotion' },
+    { prefix: '@mui/', label: 'mui' },
+    { prefix: '@chakra-ui/', label: 'chakra' },
+    { prefix: '@mantine/', label: 'mantine' },
+    { prefix: '@headlessui/', label: 'headless-ui' },
+    { prefix: '@heroicons/', label: 'heroicons' },
+    { prefix: '@arco-design/', label: 'arco-design' },
+    { prefix: '@nestjs/', label: 'nestjs' },
+    { prefix: '@supabase/', label: 'supabase' },
+    { prefix: '@langchain/', label: 'langchain' },
+    { prefix: '@trpc/', label: 'trpc' },
+    { prefix: '@prisma/', label: 'prisma' },
+    { prefix: '@remix-run/', label: 'remix' },
+    { prefix: '@sveltejs/kit', label: 'sveltekit' },
+    { prefix: '@angular/', label: 'angular' },
+    { prefix: '@tauri-apps/', label: 'tauri' },
+    { prefix: '@capacitor/', label: 'capacitor' },
+    { prefix: '@xyflow/', label: 'react-flow' },
+    { prefix: '@react-three/', label: 'r3f' },
+    { prefix: '@react-spring/', label: 'react-spring' },
+    { prefix: '@reduxjs/', label: 'redux' },
+    { prefix: '@playwright/', label: 'playwright' },
+    { prefix: '@rspack/', label: 'rspack' },
+    { prefix: '@monaco-editor/', label: 'monaco' },
+    { prefix: '@apollo/', label: 'apollo' },
+    { prefix: '@nivo/', label: 'nivo' },
+    { prefix: '@vanilla-extract/', label: 'vanilla-extract' },
+]
+
+/** Rename map — only for deps whose package name != concept name */
+const STACK_RENAME: Record<string, string> = {
+    'typescript': 'ts',
+    'tailwindcss': 'tailwind',
+    'class-variance-authority': 'shadcn/ui',
+    'ai': 'vercel-ai',
+    'solid-js': 'solid',
+    'drizzle-orm': 'drizzle',
+    'lucide-react': 'lucide',
+}
+
+// Priority tiers for stack display order (lower = more important)
+const STACK_PRIORITY: Record<string, number> = {
+    // Platform / runtime
+    "electron": 0,
+    'react-native': 0,
+    "tauri": 0,
+    "capacitor": 0,
+    // Meta-framework
+    "next": 1,
+    "nuxt": 1,
+    "remix": 1,
+    "astro": 1,
+    "gatsby": 1,
+    "sveltekit": 1,
+    // UI framework
+    "react": 2,
+    "vue": 2,
+    "svelte": 2,
+    "solid": 2,
+    "angular": 2,
+    // Bundler + lang
+    "vite": 3,
+    "webpack": 3,
+    "esbuild": 3,
+    "rspack": 3,
+    "turbopack": 3,
+    "ts": 3,
+    // Monorepo
+    "turbo": 4,
+    "nx": 4,
+    // State
+    "mobx": 5,
+    "zustand": 5,
+    "redux": 5,
+    "jotai": 5,
+    "pinia": 5,
+    "valtio": 5,
+    "xstate": 5,
+    // Styling
+    "tailwind": 5,
+    "unocss": 5,
+    'styled-components': 5,
+    "emotion": 5,
+    'vanilla-extract': 5,
+    // Component library
+    'shadcn/ui': 6,
+    "mui": 6,
+    "antd": 6,
+    "chakra": 6,
+    "mantine": 6,
+    'headless-ui': 6,
+    'element-plus': 6,
+    'arco-design': 6,
+    'naive-ui': 6,
+    "vuetify": 6,
+    // Data / network
+    'vercel-ai': 7,
+    "langchain": 7,
+    'tanstack-query': 7,
+    "swr": 7,
+    "apollo": 7,
+    "trpc": 7,
+    "graphql": 7,
+    "drizzle": 7,
+    "prisma": 7,
+    "mongoose": 7,
+    "supabase": 7,
+    "firebase": 7,
+    "dexie": 7,
+    // Testing
+    "vitest": 8,
+    "jest": 8,
+    "playwright": 8,
+    "cypress": 8,
+    // Package manager (detected separately, always first)
+    "bun": -1,
+    "pnpm": -1,
+    "yarn": -1,
+}
+
+function detectStack(pkg: any, packageManager: string): string[] {
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies }
+    const keys = Object.keys(allDeps)
+    const result: string[] = []
+
+    if (packageManager)
+        result.push(packageManager)
+
+    for (const dep of keys) {
+        if (!STACK_INCLUDE.has(dep))
+            continue
+        const collapse = STACK_COLLAPSE.find(c => dep.startsWith(c.prefix))
+        const label = collapse ? collapse.label : (STACK_RENAME[dep] ?? dep)
+        if (!result.includes(label))
+            result.push(label)
+    }
+
+    return result.sort((a, b) => (STACK_PRIORITY[a] ?? 7) - (STACK_PRIORITY[b] ?? 7))
+}
+
+// ── Non-code compressors ─────────────────────────────────
+
+/** Probe lock files next to package.json to name the package manager. */
+function detectPackageManager(filePath: string): string {
+    const dir = filePath.includes('/') ? filePath.slice(0, filePath.lastIndexOf('/') + 1) : './'
+    if (existsSync(`${dir}bun.lock`))
+        return 'bun'
+    if (existsSync(`${dir}pnpm-lock.yaml`))
+        return 'pnpm'
+    if (existsSync(`${dir}yarn.lock`))
+        return 'yarn'
+    return ''
+}
+
+export function compactPackageJson(content: string, filePath: string, packageManager = detectPackageManager(filePath)): string {
+    try {
+        const pkg = JSON.parse(content)
+        const parts: string[] = []
+        const stack = detectStack(pkg, packageManager)
+        if (stack.length)
+            parts.push(`stack: ${stack.join(', ')}`)
+        if (pkg.scripts)
+            parts.push(`scripts: ${Object.keys(pkg.scripts).join(', ')}`)
+        // Structural metadata
+        const meta: string[] = []
+        if (pkg.type)
+            meta.push(`type: ${pkg.type}`)
+        if (pkg.main)
+            meta.push(`main: ${pkg.main}`)
+        if (pkg.workspaces) {
+            const ws = Array.isArray(pkg.workspaces) ? pkg.workspaces : pkg.workspaces.packages ?? []
+            if (ws.length)
+                meta.push(`workspaces: ${ws.join(', ')}`)
+        }
+        if (meta.length)
+            parts.splice(1, 0, meta.join(', '))
+        return parts.join('\n') || ''
+    }
+    catch { return '' }
+}
+
+/** Strip // line comments and block comments from JSONC. */
+export function stripJsonComments(src: string): string {
+    let out = ''
+    for (let i = 0; i < src.length; i++) {
+        if (src[i] === '/' && src[i + 1] === '/') {
+            i += 2
+            while (i < src.length && src[i] !== '\n') i++
+            i-- // keep the newline (loop's i++ re-adds it)
+        }
+        else if (src[i] === '/' && src[i + 1] === '*') {
+            i += 2
+            while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++
+            i++ // skip the closing '/'
+        }
+        else {
+            out += src[i]
+        }
+    }
+    return out
+}
+
+export function compactTsconfig(content: string): string {
+    try {
+        // strip comments (// and /* */) before parsing
+        const stripped = stripJsonComments(content)
+        const cfg = JSON.parse(stripped)
+        const co = cfg.compilerOptions ?? {}
+        const parts: string[] = []
+        if (co.target)
+            parts.push(`target: ${co.target}`)
+        if (co.jsx)
+            parts.push(`jsx: ${co.jsx}`)
+        if (co.paths) {
+            const aliases = Object.entries(co.paths as Record<string, string[]>)
+                .map(([k, v]) => `"${k}": "${v[0] ?? ''}"`)
+                .join(', ')
+            parts.push(`paths: { ${aliases} }`)
+        }
+        if (cfg.extends)
+            parts.push(`extends: ${cfg.extends}`)
+        if (cfg.include)
+            parts.push(`include: ${cfg.include.join(', ')}`)
+        return parts.join(', ') || ''
+    }
+    catch { return '' }
+}
+
+/** YAML: extract top-level keys and first-level sub-keys (jobs, services, on, …) */
+export function compactYaml(content: string): string {
+    let doc: unknown
+    try {
+        doc = parseYaml(content)
+    }
+    catch { return '' }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        return ''
+    const result: string[] = []
+    for (const [key, val] of Object.entries(doc as Record<string, unknown>)) {
+        if (val && typeof val === 'object' && !Array.isArray(val)) {
+            const sub = Object.keys(val).slice(0, 12).join(', ')
+            result.push(sub ? `${key}: ${sub}` : key)
+        }
+        else if (Array.isArray(val)) {
+            result.push(`${key}: ${(val as unknown[]).slice(0, 8).join(', ')}`)
+        }
+        else if (val != null) {
+            result.push(`${key}: ${val}`)
+        }
+        else {
+            result.push(key)
+        }
+    }
+    return result.join('\n')
+}
+
+/** Dockerfile: extract FROM / WORKDIR / EXPOSE / ARG / CMD / ENTRYPOINT */
+export function compactDockerfile(content: string): string {
+    const KEEP = new Set(['FROM', 'WORKDIR', 'EXPOSE', 'CMD', 'ENTRYPOINT', 'ARG'])
+    const parts: string[] = []
+    let buf = ''
+    for (const raw of content.split('\n')) {
+        const line = raw.trim()
+        if (!line || line.startsWith('#'))
+            continue
+        if (line.endsWith('\\')) {
+            buf += `${line.slice(0, -1)} `
+            continue
+        }
+        const full = (buf + line).trim()
+        buf = ''
+        const spaceIdx = full.indexOf(' ')
+        if (spaceIdx === -1)
+            continue
+        const cmd = full.slice(0, spaceIdx).toUpperCase()
+        const arg = full.slice(spaceIdx + 1).trim()
+        if (!KEEP.has(cmd))
+            continue
+        const val = cmd === 'ARG' ? arg.slice(0, arg.includes('=') ? arg.indexOf('=') : undefined) : arg
+        parts.push(`${cmd} ${val}`)
+    }
+    return parts.join('\n')
+}
+
+/** CSS/SCSS/LESS: extract CSS custom property names via PostCSS AST */
+export function compactCss(content: string, filename: string): string {
+    const syntax = filename.endsWith('.scss')
+        ? postcssScss
+        : filename.endsWith('.less')
+            ? postcssLess
+            : undefined
+    try {
+        const root = syntax
+            ? postcss().process(content, { syntax }).root
+            : postcss.parse(content)
+        const seen = new Set<string>()
+        root.walkDecls((decl) => {
+            if (decl.prop.startsWith('--'))
+                seen.add(decl.prop)
+        })
+        return [...seen].join(', ')
+    }
+    catch { return '' }
+}
+
+/** .env: keep variable names, strip values */
+export function compactEnv(content: string): string {
+    const keys = content.split('\n')
+        .map(l => l.trim())
+        .filter(l => l && !l.startsWith('#') && l.includes('='))
+        .map(l => l.slice(0, l.indexOf('=')))
+    return keys.length ? keys.join(', ') : ''
+}
+
+/** HTML: extract title and entry script, skip boilerplate (favicon, viewport, …) */
+export function compactHtml(content: string): string {
+    const root = parseHtml(content)
+    const parts: string[] = []
+    const title = root.querySelector('title')
+    if (title?.text.trim())
+        parts.push(`title: ${title.text.trim()}`)
+    const SCRIPT_EXTS = ['.tsx', '.ts', '.jsx', '.js', '.mjs']
+    const entry = root.querySelectorAll('script[src]')
+        .map(n => n.getAttribute('src')!)
+        .find(src => SCRIPT_EXTS.some(ext => src.endsWith(ext)))
+    if (entry)
+        parts.push(`entry: ${entry}`)
+    return parts.join(', ') || ''
+}
+
+/** Markdown: extract h1/h2/h3 headings as structural outline (AST-based, ignores code blocks) */
+export function compactMarkdown(content: string): string {
+    const tree = fromMarkdown(content)
+    return tree.children
+        .filter(n => n.type === 'heading' && n.depth <= 3)
+        .map((n) => {
+            const text = (n as import('mdast').Heading).children.map(c => ('value' in c ? c.value : '')).join('')
+            return `${'#'.repeat((n as import('mdast').Heading).depth)} ${text}`
+        })
+        .join('\n')
+}
+
+const NON_CODE_COMPRESSORS: Array<{ match: (filename: string) => boolean, compress: (content: string, path: string) => string }> = [
+    { match: f => f === 'package.json', compress: compactPackageJson },
+    { match: f => f.startsWith('tsconfig') && f.endsWith('.json'), compress: c => compactTsconfig(c) },
+    { match: f => f === '.env' || f.startsWith('.env.'), compress: c => compactEnv(c) },
+    { match: f => f.endsWith('.html'), compress: c => compactHtml(c) },
+    { match: f => f.endsWith('.yml') || f.endsWith('.yaml'), compress: c => compactYaml(c) },
+    { match: f => f === 'Dockerfile' || f.startsWith('Dockerfile.'), compress: c => compactDockerfile(c) },
+    { match: f => f.endsWith('.css') || f.endsWith('.scss') || f.endsWith('.less'), compress: (c, p) => compactCss(c, p.slice(p.lastIndexOf('/') + 1)) },
+    { match: f => f.endsWith('.md'), compress: c => compactMarkdown(c) },
+]
+
+const isWs = (c: string) => c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f' || c === '\v'
+const isDigit = (c: string) => c >= '0' && c <= '9'
+
+/** Find first `port:` (optional whitespace) followed by digits. */
+export function extractPort(src: string): string {
+    let from = 0
+    for (;;) {
+        const idx = src.indexOf('port', from)
+        if (idx === -1)
+            return ''
+        from = idx + 4
+        let i = from
+        while (i < src.length && isWs(src[i])) i++
+        if (src[i] !== ':')
+            continue
+        i++
+        while (i < src.length && isWs(src[i])) i++
+        let n = 0
+        while (i + n < src.length && isDigit(src[i + n])) n++
+        if (n)
+            return src.slice(i, i + n)
+    }
+}
+
+/** Find `alias:` `{...}` block, return quoted keys (text before each `:`). */
+export function extractAliasKeys(src: string): string[] {
+    let from = 0
+    for (;;) {
+        const idx = src.indexOf('alias', from)
+        if (idx === -1)
+            return []
+        from = idx + 5
+        let i = from
+        while (i < src.length && isWs(src[i])) i++
+        if (src[i] !== ':')
+            continue
+        i++
+        while (i < src.length && isWs(src[i])) i++
+        if (src[i] !== '{')
+            continue
+        const close = src.indexOf('}', i)
+        if (close === -1)
+            continue
+        return extractQuotedKeys(src.slice(i + 1, close))
+    }
+}
+
+/** Inside a block body, collect quoted strings immediately followed by `:`. */
+function extractQuotedKeys(body: string): string[] {
+    const keys: string[] = []
+    for (let i = 0; i < body.length; i++) {
+        const q = body[i]
+        if (q !== '\'' && q !== '"')
+            continue
+        const end = body.indexOf(q, i + 1)
+        if (end === -1)
+            break
+        const key = body.slice(i + 1, end)
+        let j = end + 1
+        while (j < body.length && isWs(body[j])) j++
+        if (body[j] === ':')
+            keys.push(key)
+        i = end
+    }
+    return keys
+}
+
+export async function buildBlocks(
+    paths: string[],
+    config: Config,
+    wasmDir?: string,
+    classifyFn?: (path: string) => FileDetailLevel,
+    contents?: Map<string, string>,
+): Promise<FileBlock[]> {
+    await Parser.init()
+    const parser = new Parser()
+    const classifyPath = classifyFn ?? buildClassifier(config.read.fileDetailLevel)
+    const blocks: FileBlock[] = []
+    let currentLang: Awaited<ReturnType<typeof getLang>> = null
+
+    for (const path of paths) {
+        const level = classifyPath(path)
+
+        if (level === 'tree') {
+            blocks.push({ path, level, content: '' })
+            continue
+        }
+
+        const raw = contents?.get(path) ?? readFileSync(path, 'utf-8')
+        if (!raw.trim())
+            continue
+
+        if (level === 'full') {
+            blocks.push({ path, level, content: raw })
+            continue
+        }
+
+        // compact: load language once per extension, parse once, reuse tree
+        const ext = path.slice(path.lastIndexOf('.'))
+        const lang = await getLang(ext, wasmDir)
+        if (lang && lang !== currentLang) {
+            parser.setLanguage(lang)
+            currentLang = lang
+        }
+        let tree: Tree | undefined
+        if (lang) {
+            tree = parser.parse(raw) ?? undefined
+        }
+        const imports = lang ? extractImports(raw, parser, lang, tree) : undefined
+
+        // inline compact content
+        const filename = path.slice(path.lastIndexOf('/') + 1)
+        let content: string
+
+        if (filename.startsWith('vite.config.') && lang) {
+            const plugins = (imports ?? [])
+                .filter(p => !p.startsWith('node:') && !p.startsWith('.')
+                    && (p.includes('plugin') || p.startsWith('@vitejs/')))
+            const info: string[] = []
+            if (plugins.length)
+                info.push(`plugins: ${plugins.join(', ')}`)
+            // Extract server.port
+            const port = extractPort(raw)
+            if (port)
+                info.push(`port: ${port}`)
+            // Extract resolve.alias keys
+            const aliasKeys = extractAliasKeys(raw)
+            if (aliasKeys.length)
+                info.push(`alias: ${aliasKeys.join(', ')}`)
+            content = info.join(', ')
+        }
+        else if (lang) {
+            content = compact(raw, parser, lang, {
+                skipNoParamFn: !config.read.showNoParamFn,
+            }, tree)
+        }
+        else {
+            const c = NON_CODE_COMPRESSORS.find(c => c.match(filename))
+            content = c ? c.compress(raw, path) : ''
+        }
+
+        tree?.delete()
+
+        if (content.trim())
+            blocks.push({ path, level, content, imports })
+    }
+
+    parser.delete()
+    return blocks
+}
+
+// ── D4: Format ──────────────────────────────────────────
+
+const CODE_EXTS = new Set([
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+    '.vue',
+    '.svelte',
+    '.py',
+    '.rb',
+    '.go',
+    '.rs',
+    '.java',
+    '.c',
+    '.cpp',
+    '.cs',
+    '.swift',
+    '.kt',
+])
+
+function getExt(name: string): string {
+    return name.includes('.') ? name.slice(name.lastIndexOf('.')) : '(no ext)'
+}
+
+const isHex = (c: string) => (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f') || (c >= 'A' && c <= 'F')
+const isAlpha = (c: string) => (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z')
+
+/**
+ * Char-class signature of a filename stem (extension stripped), run-length compressed.
+ * Used to fold machine-generated names (hash/uuid/serial/timestamp) into one pattern.
+ * Digit and hex collapse to one class H — for id-folding their distinction is noise
+ * (a3f9 vs c8e1 must share a signature). Classes: H=hex/digit, A=alpha, S=separator(-_.).
+ */
+function classSeq(stem: string): string {
+    let out = ''
+    let prev = ''
+    for (const c of stem) {
+        const cls = isHex(c) ? 'H' : isAlpha(c) ? 'A' : (c === '-' || c === '_' || c === '.') ? 'S' : 'X'
+        if (cls !== prev) {
+            out += cls
+            prev = cls
+        }
+    }
+    return out
+}
+
+/** Min siblings/files before a same-shape fold triggers. Below this, list individually. */
+const HOMOGENEOUS_FOLD_MIN = 3
+
+export interface TreeOptions {
+    /** When a Signatures section already lists every path, drop filenames here — show dir + count. */
+    skeletonOnly?: boolean
+    /** Files/dir headers that fit the token budget and stay expanded. Empty/undefined = expand all. */
+    kept?: Set<string>
+    /** Dir prefixes whose whole subtree collapsed to a `name/ (N files, M dirs)` summary line. */
+    collapsedDirs?: Set<string>
+    /** Paths the control panel references (knob/state filePaths) → marked ★ "关键" and never folded away. */
+    starred?: Set<string>
+}
+
+export function formatTree(paths: string[], foldThreshold = 8, opts: TreeOptions = {}): string {
+    const { skeletonOnly = false, kept, collapsedDirs, starred } = opts
+    const star = (fullPath: string) => (starred?.has(fullPath) ? ' ★' : '')
+
+    // count=1: name tracks the filename so single files show by name instead of "ext ×1"
+    interface ExtEntry { count: number, name?: string }
+
+    interface TreeNode {
+        children: Map<string, TreeNode>
+        file?: true
+        hasCode?: boolean
+        subtreeExts?: Map<string, ExtEntry>
+        subtreeCount?: number
+        subtreeDirCount?: number
+    }
+
+    const root: TreeNode = { children: new Map() }
+    for (const path of paths) {
+        const parts = path.split('/')
+        let node = root
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (!node.children.has(parts[i]))
+                node.children.set(parts[i], { children: new Map() })
+            node = node.children.get(parts[i])!
+        }
+        node.children.set(parts[parts.length - 1], { children: new Map(), file: true })
+    }
+
+    function mergeExt(exts: Map<string, ExtEntry>, ext: string, incoming: ExtEntry): void {
+        const existing = exts.get(ext)
+        if (!existing) {
+            exts.set(ext, { ...incoming })
+            return
+        }
+        const count = existing.count + incoming.count
+        // name only kept when exactly one file total — drop it once count > 1
+        exts.set(ext, { count })
+    }
+
+    // Pre-pass: annotate each dir node
+    function annotate(node: TreeNode): void {
+        const exts = new Map<string, ExtEntry>()
+        let count = 0
+        let dirCount = 0
+        let hasCode = false
+        for (const [name, child] of node.children) {
+            if (child.file) {
+                const ext = getExt(name)
+                mergeExt(exts, ext, { count: 1, name })
+                count++
+                if (CODE_EXTS.has(ext))
+                    hasCode = true
+            }
+            else {
+                annotate(child)
+                count += child.subtreeCount ?? 0
+                dirCount += 1 + (child.subtreeDirCount ?? 0)
+                if (child.hasCode)
+                    hasCode = true
+                for (const [ext, entry] of child.subtreeExts ?? [])
+                    mergeExt(exts, ext, entry)
+            }
+        }
+        node.hasCode = hasCode
+        node.subtreeExts = exts
+        node.subtreeCount = count
+        node.subtreeDirCount = dirCount
+    }
+
+    annotate(root)
+
+    const lines: string[] = []
+    const FOLD_DIRS = new Set(['ui', 'icons'])
+
+    /** A leaf dir holds only files (no nested dirs). Its name-set is its structural signature. */
+    const leafFileNames = (n: TreeNode): string[] | null => {
+        const names: string[] = []
+        for (const [name, c] of n.children) {
+            if (!c.file)
+                return null
+            names.push(name)
+        }
+        return names
+    }
+
+    type Entry = [string, TreeNode]
+
+    // Fold B: among sibling leaf dirs, group by name-set (or ext-multiset) signature.
+    // A group of ≥3 isomorphic dirs collapses to one `[name]/(<files>) ×N` line.
+    function foldSiblingDirs(dirEntries: Entry[]): { folded: string[], rest: Entry[] } {
+        interface Item { entry: Entry, names: string[] }
+        const groups = new Map<string, Item[]>()
+        const rest: Entry[] = []
+        for (const [name, c] of dirEntries) {
+            const names = leafFileNames(c)
+            if (!names || !names.length) {
+                rest.push([name, c])
+                continue
+            }
+            const sorted = [...names].sort()
+            const sig = `N:${sorted.join('|')}` // exact filename set → identical [name]/index.md dirs collapse
+            groups.set(sig, [...(groups.get(sig) ?? []), { entry: [name, c], names: sorted }])
+        }
+        // Below-threshold name groups get a second chance: fold by ext-multiset (names differ, shape same).
+        const extGroups = new Map<string, Item[]>()
+        for (const [sig, arr] of [...groups]) {
+            if (arr.length >= HOMOGENEOUS_FOLD_MIN)
+                continue
+            groups.delete(sig)
+            for (const item of arr) {
+                const extSig = `E:${item.names.map(getExt).sort().join('|')}`
+                extGroups.set(extSig, [...(extGroups.get(extSig) ?? []), item])
+            }
+        }
+        const folded: string[] = []
+        const emit = (arr: Item[], byName: boolean) => {
+            const sample = arr[0].names
+            const body = byName
+                ? sample.join(', ')
+                : [...new Set(sample.map(getExt))].map((e) => {
+                        const n = sample.filter(name => getExt(name) === e).length
+                        return n > 1 ? `${e} ×${n}` : e
+                    }).join(', ')
+            folded.push(`[name]/ (${body}) ×${arr.length}`)
+        }
+        for (const arr of groups.values()) {
+            if (arr.length >= HOMOGENEOUS_FOLD_MIN)
+                emit(arr, true)
+            else arr.forEach(i => rest.push(i.entry))
+        }
+        for (const arr of extGroups.values()) {
+            if (arr.length >= HOMOGENEOUS_FOLD_MIN)
+                emit(arr, false)
+            else arr.forEach(i => rest.push(i.entry))
+        }
+        return { folded, rest }
+    }
+
+    // Fold C: within one dir, fold ≥3 same-shape *machine-generated* filenames → `[id].ext ×N`.
+    // Only pure-id stems (hex/digit/sep, no alpha word) fold — `data0.json`/`fn1.ts` keep their
+    // names since the alpha prefix is a real navigational word. Hashes/uuids/serials lose nothing.
+    function foldHomogeneousFiles(fileEntries: Entry[]): { folded: string[], rest: Entry[] } {
+        const stemOf = (name: string) => {
+            const ext = getExt(name)
+            return ext === '(no ext)' ? name : name.slice(0, name.length - ext.length)
+        }
+        const isPureId = (stem: string) => stem.length > 0
+            && [...stem].every(c => isHex(c) || c === '-' || c === '_')
+        const groups = new Map<string, Entry[]>()
+        const rest: Entry[] = []
+        for (const [name, c] of fileEntries) {
+            const stem = stemOf(name)
+            if (!isPureId(stem)) {
+                rest.push([name, c])
+                continue
+            }
+            const key = `${classSeq(stem)}|${getExt(name)}` // a3f9.json & c8e1.json fold; log.txt stays separate
+            groups.set(key, [...(groups.get(key) ?? []), [name, c]])
+        }
+        const folded: string[] = []
+        for (const entries of groups.values()) {
+            if (entries.length >= HOMOGENEOUS_FOLD_MIN) {
+                const ext = getExt(entries[0][0])
+                folded.push(`[id]${ext === '(no ext)' ? '' : ext} ×${entries.length}`)
+            }
+            else {
+                rest.push(...entries)
+            }
+        }
+        return { folded, rest }
+    }
+
+    function walk(node: TreeNode, prefix: string, dirName?: string, dirPath = '') {
+        let rawEntries = Array.from(node.children.entries())
+
+        // Budget collapse: when `kept` is set, un-kept files in this (kept) dir don't list
+        // individually — they fold into a single `.ext ×N` summary. Dirs are untouched here;
+        // a fully-collapsed dir is summarized by emitItems via `collapsedDirs`.
+        const unkeptExtLines: string[] = []
+        if (kept?.size) {
+            const unkept = rawEntries.filter(([name, c]) => c.file && !kept.has(dirPath ? `${dirPath}/${name}` : name))
+            if (unkept.length) {
+                rawEntries = rawEntries.filter(([name, c]) => !(c.file && !kept.has(dirPath ? `${dirPath}/${name}` : name)))
+                const extCounts = new Map<string, number>()
+                for (const [name] of unkept) extCounts.set(getExt(name), (extCounts.get(getExt(name)) ?? 0) + 1)
+                for (const [ext, n] of [...extCounts.entries()].sort((a, b) => b[1] - a[1]))
+                    unkeptExtLines.push(`${ext} ×${n}`)
+            }
+        }
+
+        // Code items: code files + dirs that contain any code (shown individually)
+        // Non-code items: data files + data-only dirs (folded when count exceeds threshold)
+        const codeItems = rawEntries.filter(([name, c]) => c.file ? CODE_EXTS.has(getExt(name)) : !!c.hasCode)
+        const nonCodeItems = rawEntries.filter(([name, c]) => c.file ? !CODE_EXTS.has(getExt(name)) : !c.hasCode)
+
+        // Count non-code items: each item = 1 (dirs count as 1, not their subtreeCount)
+        // This preserves dir names at the parent level — a dir only folds inside itself
+        const nonCodeItemCount = nonCodeItems.length
+
+        const items: Item[] = []
+
+        // Fold E: a Signatures section already lists every file path, so the tree only needs the
+        // dir skeleton + a file count. Recurse into subdirs; collapse direct files to "N files".
+        // A leaf dir (only files, no subdirs) renders inline as "Name/  N files".
+        if (skeletonOnly) {
+            const dirs = rawEntries.filter(([, c]) => !c.file)
+            const fileCount = rawEntries.length - dirs.length
+            const branchDirs = dirs.filter(([, c]) => [...c.children.values()].some(ch => !ch.file))
+            const leafDirs = dirs.filter(([, c]) => ![...c.children.values()].some(ch => !ch.file))
+            const { folded, rest } = foldSiblingDirs(leafDirs)
+            for (const [name, c] of rest)
+                items.push({ display: `${name}/  ${c.children.size} file${c.children.size > 1 ? 's' : ''}` })
+            for (const d of folded) items.push({ display: d })
+            for (const [name, c] of branchDirs) items.push({ display: name, child: c })
+            if (fileCount > 0)
+                items.push({ display: `${fileCount} file${fileCount > 1 ? 's' : ''}` })
+            return emitItems(items, prefix)
+        }
+
+        // Fold code files in well-known homogeneous directories (e.g. shadcn ui/, icons/)
+        const codeFiles = codeItems.filter(([, c]) => c.file)
+        const codeDirs = codeItems.filter(([, c]) => !c.file)
+        if (dirName && FOLD_DIRS.has(dirName) && codeFiles.length > 1 && codeDirs.length === 0) {
+            const ext = getExt(codeFiles[0][0])
+            const allSameExt = codeFiles.every(([name]) => getExt(name) === ext)
+            if (allSameExt) {
+                items.push({ display: `${ext} ×${codeFiles.length}` })
+            }
+            else {
+                const extCounts = new Map<string, number>()
+                for (const [name] of codeFiles) {
+                    const e = getExt(name)
+                    extCounts.set(e, (extCounts.get(e) ?? 0) + 1)
+                }
+                for (const [ext, count] of [...extCounts.entries()].sort((a, b) => b[1] - a[1]))
+                    items.push({ display: `${ext} ×${count}` })
+            }
+        }
+        else {
+            // Fold B: collapse ≥3 isomorphic sibling code dirs into one [name]/ pattern line.
+            const { folded: foldedDirs, rest: restDirs } = foldSiblingDirs(codeDirs)
+            // Fold C: collapse ≥3 same-shape code filenames (hash/serial names) into [id].ext.
+            const { folded: foldedFiles, rest: restFiles } = foldHomogeneousFiles(codeFiles)
+            for (const [name] of restFiles)
+                items.push({ display: name, child: undefined })
+            for (const [name, c] of restDirs)
+                items.push({ display: name, child: c })
+            for (const d of foldedFiles) items.push({ display: d })
+            for (const d of foldedDirs) items.push({ display: d })
+        }
+
+        if (nonCodeItemCount > foldThreshold) {
+            // Absorb all non-code items into extension summary
+            const extCounts = new Map<string, ExtEntry>()
+            for (const [name, c] of nonCodeItems) {
+                if (c.file) {
+                    mergeExt(extCounts, getExt(name), { count: 1, name })
+                }
+                else {
+                    for (const [ext, entry] of c.subtreeExts ?? []) mergeExt(extCounts, ext, entry)
+                }
+            }
+            // count=1 with known name → show filename; count≥2 → show "ext ×N"
+            for (const [ext, entry] of [...extCounts.entries()].sort((a, b) => b[1].count - a[1].count))
+                items.push({ display: entry.count === 1 && entry.name ? entry.name : `${ext} ×${entry.count}` })
+        }
+        else {
+            // Fold B/C also apply to non-code dirs/files (e.g. knowledge/[name]/index.md, Logs/[id].json).
+            const ncDirs = nonCodeItems.filter(([, c]) => !c.file)
+            const ncFiles = nonCodeItems.filter(([, c]) => c.file)
+            const { folded: foldedDirs, rest: restDirs } = foldSiblingDirs(ncDirs)
+            const { folded: foldedFiles, rest: restFiles } = foldHomogeneousFiles(ncFiles)
+            for (const [name] of restFiles)
+                items.push({ display: name, child: undefined })
+            for (const [name, c] of restDirs)
+                items.push({ display: name, child: c })
+            for (const d of foldedFiles) items.push({ display: d })
+            for (const d of foldedDirs) items.push({ display: d })
+        }
+
+        for (const line of unkeptExtLines)
+            items.push({ display: line })
+
+        return emitItems(items, prefix, dirPath)
+    }
+
+    interface Item { display: string, child?: TreeNode }
+    function emitItems(items: Item[], prefix: string, dirPath = ''): void {
+        for (const { display, child } of items) {
+            if (child) {
+                // Budget collapse: a dir whose whole subtree didn't fit renders as a one-line
+                // `name/ (N files, M dirs)` summary and is not recursed into.
+                const childPath = dirPath ? `${dirPath}/${display}` : display
+                if (collapsedDirs?.has(childPath)) {
+                    const files = child.subtreeCount ?? 0
+                    const dirs = child.subtreeDirCount ?? 0
+                    lines.push(`${prefix}${display}/ (${files} file${files === 1 ? '' : 's'}, ${dirs} dir${dirs === 1 ? '' : 's'})`)
+                    continue
+                }
+                // Fold A: collapse single-child dir chains — a/ → b/ → file becomes a/b/file.
+                let label = display
+                let cur = child
+                let fileLeaf = false
+                while (cur.children.size === 1) {
+                    const [onlyName, onlyChild] = [...cur.children][0]
+                    label += `/${onlyName}`
+                    if (onlyChild.file) {
+                        lines.push(`${prefix}${label}${star(dirPath ? `${dirPath}/${label}` : label)}`)
+                        fileLeaf = true
+                        break
+                    }
+                    cur = onlyChild
+                }
+                if (fileLeaf)
+                    continue
+                lines.push(`${prefix}${label}/`)
+                walk(cur, `${prefix}  `, label.slice(label.lastIndexOf('/') + 1), dirPath ? `${dirPath}/${label}` : label)
+            }
+            else {
+                lines.push(`${prefix}${display}${star(dirPath ? `${dirPath}/${display}` : display)}`)
+            }
+        }
+    }
+
+    walk(root, '')
+    return lines.join('\n')
+}
+
+// 关键文件版图：tree 只显示 starred（控制面触碰的）文件 + 它们所在的目录骨架。
+// 非 ★ 的叶子/子树整块折成 `… N more`，让 ★ 不再被全量噪音稀释。与 formatTree 的全量折叠
+// 模式正交（一个答"全部物理布局"，一个答"哪些文件被控制面触碰"），故独立函数不耦合进 walk。
+export function formatStarredTree(paths: string[], starred: Set<string>): string {
+    interface Node { children: Map<string, Node>, file?: true, fullPath?: string }
+    const root: Node = { children: new Map() }
+    for (const path of paths) {
+        const parts = path.split('/')
+        let node = root
+        for (let i = 0; i < parts.length; i++) {
+            const isLeaf = i === parts.length - 1
+            if (!node.children.has(parts[i]))
+                node.children.set(parts[i], { children: new Map() })
+            node = node.children.get(parts[i])!
+            if (isLeaf) { node.file = true; node.fullPath = path }
+        }
+    }
+
+    // 子树是否含 ★（决定是否展开此目录）。
+    const hasStar = (n: Node): boolean => {
+        if (n.file) return !!(n.fullPath && starred.has(n.fullPath))
+        for (const c of n.children.values()) if (hasStar(c)) return true
+        return false
+    }
+    // 子树里非 ★ 的文件总数（折成 `… N more` 的计数，全子树深算，诚实）。
+    const countNonStar = (n: Node): number => {
+        if (n.file) return n.fullPath && starred.has(n.fullPath) ? 0 : 1
+        let s = 0
+        for (const c of n.children.values()) s += countNonStar(c)
+        return s
+    }
+
+    const lines: string[] = []
+    const walk = (node: Node, prefix: string) => {
+        const entries = [...node.children.entries()]
+        const starDirs = entries.filter(([, c]) => !c.file && hasStar(c))
+        const starFiles = entries.filter(([, c]) => c.file && hasStar(c))
+        // 此目录下被折叠掉的非★文件：直属非★文件 + 不含★的整个子目录里的文件。
+        let hidden = 0
+        for (const [, c] of entries)
+            if (!hasStar(c)) hidden += countNonStar(c)
+
+        for (const [name, c] of starFiles)
+            lines.push(`${prefix}${name} ★`)
+        for (const [name, c] of starDirs) {
+            lines.push(`${prefix}${name}/`)
+            walk(c, `${prefix}  `)
+        }
+        if (hidden > 0)
+            lines.push(`${prefix}… ${hidden} more`)
+    }
+    walk(root, '')
+    return lines.join('\n')
+}
+
+export function formatXml(blocks: FileBlock[], levels?: Map<string, FileDetailLevel>): string {
+    return blocks
+        .filter((b) => {
+            if (levels && !levels.has(b.path))
+                return false
+            const level = levels?.get(b.path) ?? b.level
+            return level !== 'tree' && b.content.trim()
+        })
+        .map(b => `<file path="${b.path}">\n${b.content}\n</file>`)
+        .join('\n\n')
+}