@soederpop/luca 0.0.19 → 0.0.21

package/src/commands/describe.ts

@@ -2,7 +2,10 @@ import { z } from 'zod'
 import { commands } from '../command.js'
 import { CommandOptionsSchema } from '../schemas/base.js'
 import type { ContainerContext } from '../container.js'
-import type { IntrospectionSection, MethodIntrospection, GetterIntrospection } from '../introspection/index.js'
+import type { IntrospectionSection, MethodIntrospection, GetterIntrospection, HelperIntrospection } from '../introspection/index.js'
+import { __INTROSPECTION__, __BROWSER_INTROSPECTION__ } from '../introspection/index.js'
+import { features } from '../feature.js'
+import { presentIntrospectionAsMarkdown } from '../helper.js'
 
 declare module '../command.js' {
 	interface AvailableCommands {
@@ -61,13 +64,18 @@ export const argsSchema = CommandOptionsSchema.extend({
 	'only-env-vars': z.boolean().default(false).describe('Show only the envVars section'),
 	'only-envvars': z.boolean().default(false).describe('Show only the envVars section'),
 	'only-examples': z.boolean().default(false).describe('Show only the examples section'),
+	platform: z.enum(['browser', 'web', 'server', 'node', 'all']).default('all').describe('Which platform features to show: browser/web, server/node, or all'),
 })
 
+type Platform = 'browser' | 'server' | 'node' | 'all'
+
 type ResolvedTarget =
 	| { kind: 'container' }
 	| { kind: 'registry'; name: RegistryName }
 	| { kind: 'helper'; registry: RegistryName; id: string }
 	| { kind: 'member'; registry: RegistryName; id: string; member: string; memberType: 'method' | 'getter' }
+	| { kind: 'browser-helper'; id: string }
+	| { kind: 'browser-member'; id: string; member: string; memberType: 'method' | 'getter' }
 
 class DescribeError extends Error {
 	constructor(message: string) {
@@ -76,6 +84,303 @@ class DescribeError extends Error {
 	}
 }
 
+// --- Browser feature loading ---
+
+const WEB_FEATURE_IDS = ['speech', 'voice', 'assetLoader', 'network', 'vault', 'vm', 'esbuild', 'helpers', 'containerLink']
+
+type BrowserFeatureData = {
+	introspection: Map<string, HelperIntrospection>
+	constructors: Map<string, any>
+	available: string[]
+	collidingIds: Set<string>
+}
+
+let _browserData: BrowserFeatureData | null = null
+
+/**
+ * Load web/browser feature introspection data into a separate map.
+ * Imports the web feature class files to get full Zod-derived data,
+ * then restores the node registry and introspection to their original state.
+ */
+async function loadBrowserFeatures(): Promise<BrowserFeatureData> {
+	if (_browserData) return _browserData
+
+	// Snapshot current node state
+	const nodeFeatureIds = new Set(features.available)
+	const nodeIntrospection = new Map<string, HelperIntrospection>()
+	const nodeConstructors = new Map<string, any>()
+
+	for (const id of nodeFeatureIds) {
+		const data = __INTROSPECTION__.get(`features.${id}`)
+		if (data) nodeIntrospection.set(`features.${id}`, structuredClone(data))
+		try { nodeConstructors.set(id, features.lookup(id)) } catch {}
+	}
+
+	// Import generated web build-time data (descriptions, methods, getters from AST)
+	await import('../introspection/generated.web.js')
+
+	// Import web feature class files (triggers Feature.register → interceptRegistration → Zod data)
+	await Promise.all([
+		import('../web/features/speech.js'),
+		import('../web/features/voice-recognition.js'),
+		import('../web/features/asset-loader.js'),
+		import('../web/features/network.js'),
+		import('../web/features/vault.js'),
+		import('../web/features/vm.js'),
+		import('../web/features/esbuild.js'),
+		import('../web/features/helpers.js'),
+		import('../web/features/container-link.js'),
+	])
+
+	// Capture browser introspection data and constructors
+	const browserIntrospection = new Map<string, HelperIntrospection>()
+	const browserConstructors = new Map<string, any>()
+	const collidingIds = new Set<string>()
+
+	for (const id of WEB_FEATURE_IDS) {
+		const key = `features.${id}`
+		const data = __INTROSPECTION__.get(key)
+		if (data) browserIntrospection.set(key, structuredClone(data))
+		try { browserConstructors.set(id, features.lookup(id)) } catch {}
+		if (nodeFeatureIds.has(id)) collidingIds.add(id)
+	}
+
+	// Restore node registry: re-register all node constructors
+	for (const [id, ctor] of nodeConstructors) {
+		features.register(id, ctor)
+	}
+
+	// Fully restore node introspection (overwrite whatever interceptRegistration did during re-register)
+	for (const [key, data] of nodeIntrospection) {
+		__INTROSPECTION__.set(key, data)
+	}
+
+	// Clean up: remove web-only entries from __INTROSPECTION__ and the registry
+	for (const id of WEB_FEATURE_IDS) {
+		const key = `features.${id}`
+		if (!nodeIntrospection.has(key)) {
+			__INTROSPECTION__.delete(key)
+		}
+		if (!nodeFeatureIds.has(id)) {
+			features.unregister(id)
+		}
+	}
+
+	// Store in __BROWSER_INTROSPECTION__ for other potential consumers
+	for (const [key, data] of browserIntrospection) {
+		__BROWSER_INTROSPECTION__.set(key, data)
+	}
+
+	_browserData = {
+		introspection: browserIntrospection,
+		constructors: browserConstructors,
+		available: WEB_FEATURE_IDS.filter(id => browserIntrospection.has(`features.${id}`)),
+		collidingIds,
+	}
+
+	return _browserData
+}
+
+/** Render a browser feature's introspection data directly (no Ctor needed). */
+function renderBrowserHelperText(data: HelperIntrospection, sections: (IntrospectionSection | 'description')[], noTitle = false, headingDepth = 1): string {
+	const h = '#'.repeat(headingDepth)
+	const className = data.className || data.id
+
+	if (sections.length === 0) {
+		const body = presentIntrospectionAsMarkdown(data, headingDepth)
+		if (noTitle) {
+			// Strip the title heading and return description + sections
+			const lines = body.split('\n')
+			const sectionHeading = '#'.repeat(headingDepth + 1) + ' '
+			const firstSectionIdx = lines.findIndex((l, i) => i > 0 && l.startsWith(sectionHeading))
+			const desc = data.description ? data.description + '\n\n' : ''
+			if (firstSectionIdx > 0) {
+				return desc + lines.slice(firstSectionIdx).join('\n')
+			}
+			// No subsections — just return the description
+			return desc.trim() || 'No introspection data available.'
+		}
+		return body
+	}
+
+	const parts: string[] = []
+	if (!noTitle) {
+		parts.push(`${h} ${className} (${data.id})`)
+		if (data.description) parts.push(data.description)
+	}
+
+	const introspectionSections = sections.filter((s): s is IntrospectionSection => s !== 'description')
+	for (const section of introspectionSections) {
+		const text = presentIntrospectionAsMarkdown(data, headingDepth, section)
+		if (text) parts.push(text)
+	}
+
+	return parts.join('\n\n') || `${noTitle ? '' : `${h} ${className}\n\n`}No introspection data available.`
+}
+
+function renderBrowserHelperJson(data: HelperIntrospection, sections: (IntrospectionSection | 'description')[], noTitle = false): any {
+	if (sections.length === 0) return data
+
+	const result: Record<string, any> = {}
+	if (!noTitle) {
+		result.id = data.id
+		if (data.className) result.className = data.className
+	}
+	for (const section of sections) {
+		if (section === 'description') {
+			result.id = data.id
+			if (data.className) result.className = data.className
+			result.description = data.description
+		} else if (section === 'usage') {
+			result.usage = { shortcut: data.shortcut, options: data.options }
+		} else {
+			result[section] = (data as any)[section]
+		}
+	}
+	return result
+}
+
+/** Build a concise summary for a browser feature from introspection data. */
+function buildBrowserHelperSummary(data: HelperIntrospection): string {
+	const ownMethods = Object.keys(data.methods || {}).sort()
+	const ownGetters = Object.keys(data.getters || {}).sort()
+	const lines: string[] = []
+	if (ownGetters.length) lines.push(`getters: ${ownGetters.join(', ')}`)
+	if (ownMethods.length) lines.push(`methods: ${ownMethods.map(m => m + '()').join(', ')}`)
+	return lines.join('\n')
+}
+
+function getBrowserHelperData(id: string, sections: (IntrospectionSection | 'description')[], noTitle = false, headingDepth = 1): { json: any; text: string } {
+	const data = _browserData!.introspection.get(`features.${id}`)
+	if (!data) return { json: {}, text: `No browser introspection data for ${id}` }
+
+	const text = renderBrowserHelperText(data, sections, noTitle, headingDepth)
+
+	// Inject summary after title for full renders
+	let finalText = text
+	if (sections.length === 0 && !noTitle) {
+		const summary = buildBrowserHelperSummary(data)
+		if (summary) {
+			const sectionHeading = '#'.repeat(headingDepth + 1) + ' '
+			const idx = text.indexOf('\n' + sectionHeading)
+			if (idx >= 0) {
+				finalText = text.slice(0, idx) + '\n\n' + summary + '\n' + text.slice(idx)
+			}
+		}
+	}
+
+	return {
+		json: renderBrowserHelperJson(data, sections, noTitle),
+		text: finalText,
+	}
+}
+
+function getBrowserMemberData(id: string, member: string, memberType: 'method' | 'getter', headingDepth = 1): { json: any; text: string } {
+	const data = _browserData!.introspection.get(`features.${id}`)
+	if (!data) return { json: {}, text: `No browser introspection data for ${id}` }
+
+	const h = '#'.repeat(headingDepth)
+	const hSub = '#'.repeat(headingDepth + 1)
+
+	if (memberType === 'method') {
+		const method = data.methods?.[member] as MethodIntrospection | undefined
+		if (!method) return { json: {}, text: `No introspection data for ${id}.${member}()` }
+
+		const parts: string[] = [`${h} ${id}.${member}() (browser)`]
+		parts.push(`> method on **${data.className || id}**`)
+		if (method.description) parts.push(method.description)
+
+		const paramEntries = Object.entries(method.parameters || {})
+		if (paramEntries.length > 0) {
+			const paramLines = [`${hSub} Parameters`, '']
+			for (const [name, info] of paramEntries) {
+				const req = (method.required || []).includes(name) ? ' *(required)*' : ''
+				paramLines.push(`- **${name}** \`${info.type}\`${req}${info.description ? ' — ' + info.description : ''}`)
+			}
+			parts.push(paramLines.join('\n'))
+		}
+
+		if (method.returns && method.returns !== 'void') {
+			parts.push(`${hSub} Returns\n\n\`${method.returns}\``)
+		}
+
+		return { json: { [member]: method, _helper: id, _type: 'method', _platform: 'browser' }, text: parts.join('\n\n') }
+	}
+
+	const getter = data.getters?.[member] as GetterIntrospection | undefined
+	if (!getter) return { json: {}, text: `No introspection data for ${id}.${member}` }
+
+	const parts: string[] = [`${h} ${id}.${member} (browser)`]
+	parts.push(`> getter on **${data.className || id}** — returns \`${getter.returns || 'unknown'}\``)
+	if (getter.description) parts.push(getter.description)
+
+	return { json: { [member]: getter, _helper: id, _type: 'getter', _platform: 'browser' }, text: parts.join('\n\n') }
+}
+
+function getBrowserRegistryData(sections: (IntrospectionSection | 'description')[], noTitle = false, headingDepth = 1): { json: any; text: string } {
+	const browserData = _browserData!
+	const available = browserData.available
+
+	if (available.length === 0) {
+		return { json: {}, text: 'No browser features are registered.' }
+	}
+
+	if (sections.length === 0) {
+		const h = '#'.repeat(headingDepth)
+		const hSub = '#'.repeat(headingDepth + 1)
+		const jsonResult: Record<string, any> = {}
+		const textParts: string[] = [`${h} Available browser features (${available.length})\n`]
+
+		for (const id of available.sort()) {
+			const data = browserData.introspection.get(`features.${id}`)
+			if (!data) continue
+
+			const summary = extractSummary(data.description || 'No description provided')
+			const featureGetters = Object.keys(data.getters || {}).sort()
+			const featureMethods = Object.keys(data.methods || {}).sort()
+
+			jsonResult[id] = { description: summary, methods: featureMethods, getters: featureGetters, platform: 'browser' }
+
+			const memberLines: string[] = []
+			if (featureGetters.length) memberLines.push(`  getters: ${featureGetters.join(', ')}`)
+			if (featureMethods.length) memberLines.push(`  methods: ${featureMethods.map(m => m + '()').join(', ')}`)
+			const memberBlock = memberLines.length ? '\n' + memberLines.join('\n') + '\n' : ''
+
+			textParts.push(`${hSub} ${id}\n${summary}\n${memberBlock}`)
+		}
+
+		return { json: jsonResult, text: textParts.join('\n') }
+	}
+
+	// Sections specified: render each helper in detail
+	const jsonResult: Record<string, any> = {}
+	const textParts: string[] = []
+	for (const id of available) {
+		const data = browserData.introspection.get(`features.${id}`)
+		if (!data) continue
+		jsonResult[id] = renderBrowserHelperJson(data, sections, noTitle)
+		textParts.push(renderBrowserHelperText(data, sections, noTitle, headingDepth))
+	}
+
+	return { json: jsonResult, text: textParts.join('\n\n---\n\n') }
+}
+
+function normalizePlatform(p: string): Platform {
+	if (p === 'node') return 'server'
+	if (p === 'web') return 'browser'
+	return p as Platform
+}
+
+function shouldIncludeNode(platform: Platform): boolean {
+	return platform === 'server' || platform === 'node' || platform === 'all'
+}
+
+function shouldIncludeBrowser(platform: Platform): boolean {
+	return platform === 'browser' || platform === 'all'
+}
+
+// --- End browser feature loading ---
+
 /**
  * Extract a short summary from a potentially long description string.
  * Takes text up to the first markdown heading, bullet list, or code block,
@@ -153,16 +458,50 @@ function resolveHelperMember(helperName: string, memberName: string, container:
 	return null
 }
 
+/** Find a browser feature by normalized name. */
+function fuzzyFindBrowser(input: string): string | undefined {
+	if (!_browserData) return undefined
+	const norm = normalize(input)
+	return _browserData.available.find(id => normalize(id) === norm)
+}
+
+/** Try to resolve "browserHelper.member" for browser features. */
+function resolveBrowserHelperMember(helperName: string, memberName: string): ResolvedTarget | null {
+	if (!_browserData) return null
+	const found = fuzzyFindBrowser(helperName)
+	if (!found) return null
+
+	const data = _browserData.introspection.get(`features.${found}`)
+	if (!data) return null
+
+	if (data.methods?.[memberName]) {
+		return { kind: 'browser-member', id: found, member: memberName, memberType: 'method' }
+	}
+	if (data.getters?.[memberName]) {
+		return { kind: 'browser-member', id: found, member: memberName, memberType: 'getter' }
+	}
+
+	const allMembers = [
+		...Object.keys(data.methods || {}).map((m: string) => m + '()'),
+		...Object.keys(data.getters || {}),
+	].sort()
+	throw new DescribeError(
+		`"${memberName}" is not a known method or getter on ${found} (browser).\n\nAvailable members:\n  ${allMembers.join(', ')}`
+	)
+}
+
 /**
  * Parse a single target string into a resolved target.
  * Accepts: "container", "features", "features.fs", "fs", "ui.banner", etc.
  */
-function resolveTarget(target: string, container: any): ResolvedTarget {
+function resolveTarget(target: string, container: any, platform: Platform): ResolvedTarget[] {
 	const lower = target.toLowerCase()
+	const includeNode = shouldIncludeNode(platform)
+	const includeBrowser = shouldIncludeBrowser(platform)
 
 	// "container" or "self"
 	if (lower === 'container' || lower === 'self') {
-		return { kind: 'container' }
+		return [{ kind: 'container' }]
 	}
 
 	// Registry name: "features", "clients", "servers", "commands", "endpoints"
@@ -170,7 +509,7 @@ function resolveTarget(target: string, container: any): ResolvedTarget {
 		(r) => r === lower || r === lower + 's' || r.replace(/s$/, '') === lower
 	)
 	if (registryMatch && !target.includes('.')) {
-		return { kind: 'registry', name: registryMatch }
+		return [{ kind: 'registry', name: registryMatch }]
 	}
 
 	// Qualified name: "features.fs", "clients.rest", etc.
@@ -182,53 +521,103 @@ function resolveTarget(target: string, container: any): ResolvedTarget {
 		)
 
 		if (registry) {
-			const reg = container[registry]
-			const resolved = fuzzyFind(reg, id)
-			if (!resolved) {
-				throw new DescribeError(`"${id}" is not registered in ${registry}. Available: ${reg.available.join(', ')}`)
+			const results: ResolvedTarget[] = []
+
+			if (includeNode) {
+				const reg = container[registry]
+				const resolved = fuzzyFind(reg, id)
+				if (resolved) results.push({ kind: 'helper', registry, id: resolved })
+			}
+
+			if (includeBrowser && registry === 'features') {
+				const browserFound = fuzzyFindBrowser(id)
+				if (browserFound) results.push({ kind: 'browser-helper', id: browserFound })
 			}
-			return { kind: 'helper', registry, id: resolved }
+
+			if (results.length === 0) {
+				const reg = container[registry]
+				const availableMsg = includeNode ? reg.available.join(', ') : ''
+				const browserMsg = includeBrowser && _browserData ? _browserData.available.join(', ') : ''
+				const combined = [availableMsg, browserMsg].filter(Boolean).join(', ')
+				throw new DescribeError(`"${id}" is not registered in ${registry}. Available: ${combined}`)
+			}
+
+			return results
 		}
 
 		// Not a registry prefix — try "helper.member" (e.g. "ui.banner", "fs.readFile")
 		const helperName = prefix!
 		const memberName = rest.join('.')
-		const memberResult = resolveHelperMember(helperName, memberName, container)
-		if (memberResult) return memberResult
+		const results: ResolvedTarget[] = []
+
+		if (includeNode) {
+			const memberResult = resolveHelperMember(helperName, memberName, container)
+			if (memberResult) results.push(memberResult)
+		}
+
+		if (includeBrowser) {
+			try {
+				const browserResult = resolveBrowserHelperMember(helperName, memberName)
+				if (browserResult) results.push(browserResult)
+			} catch (e) {
+				if (results.length === 0) throw e
+			}
+		}
+
+		if (results.length > 0) return results
 	}
 
-	// Unqualified name: search all registries (fuzzy)
-	const matches: { registry: RegistryName; id: string }[] = []
-	for (const registryName of REGISTRY_NAMES) {
-		const reg = container[registryName]
-		if (!reg) continue
-		const found = fuzzyFind(reg, target)
-		if (found) {
-			matches.push({ registry: registryName, id: found })
+	// Unqualified name: search all registries (fuzzy) + browser features
+	const matches: ResolvedTarget[] = []
+
+	if (includeNode) {
+		for (const registryName of REGISTRY_NAMES) {
+			const reg = container[registryName]
+			if (!reg) continue
+			const found = fuzzyFind(reg, target)
+			if (found) {
+				matches.push({ kind: 'helper', registry: registryName, id: found })
+			}
+		}
+	}
+
+	if (includeBrowser) {
+		const browserFound = fuzzyFindBrowser(target)
+		if (browserFound) {
+			// If there's already a node feature with the same id, include both
+			matches.push({ kind: 'browser-helper', id: browserFound })
 		}
 	}
 
 	if (matches.length === 0) {
 		const lines = [`"${target}" was not found in any registry.`, '', 'Available:']
-		for (const registryName of REGISTRY_NAMES) {
-			const reg = container[registryName]
-			if (reg && reg.available.length > 0) {
-				lines.push(`  ${registryName}: ${reg.available.join(', ')}`)
+		if (includeNode) {
+			for (const registryName of REGISTRY_NAMES) {
+				const reg = container[registryName]
+				if (reg && reg.available.length > 0) {
+					lines.push(`  ${registryName}: ${reg.available.join(', ')}`)
+				}
 			}
 		}
+		if (includeBrowser && _browserData && _browserData.available.length > 0) {
+			lines.push(`  browser features: ${_browserData.available.join(', ')}`)
+		}
 		throw new DescribeError(lines.join('\n'))
 	}
 
-	if (matches.length > 1) {
+	// For unqualified names with a single node match and no browser match (or vice versa), return as-is
+	// For ambiguous node matches (multiple registries), report ambiguity
+	const nodeMatches = matches.filter(m => m.kind === 'helper')
+	if (nodeMatches.length > 1) {
 		const lines = [`"${target}" is ambiguous — found in multiple registries:`]
-		for (const m of matches) {
-			lines.push(`  ${m.registry}.${m.id}`)
+		for (const m of nodeMatches) {
+			if (m.kind === 'helper') lines.push(`  ${m.registry}.${m.id}`)
 		}
-		lines.push('', `Please qualify it, e.g.: ${matches[0]!.registry}.${target}`)
+		lines.push('', `Please qualify it, e.g.: ${(nodeMatches[0] as any).registry}.${target}`)
 		throw new DescribeError(lines.join('\n'))
 	}
 
-	return { kind: 'helper', registry: matches[0]!.registry, id: matches[0]!.id }
+	return matches
 }
 
 /** Collect all requested sections from flags. Empty array = show everything. */
@@ -450,85 +839,135 @@ function findIntermediateParent(Ctor: any, baseClass: any): { name: string; meth
 	}
 }
 
-function getRegistryData(container: any, registryName: RegistryName, sections: (IntrospectionSection | 'description')[], noTitle = false, headingDepth = 1): { json: any; text: string } {
+function getRegistryData(container: any, registryName: RegistryName, sections: (IntrospectionSection | 'description')[], noTitle = false, headingDepth = 1, platform: Platform = 'all'): { json: any; text: string } {
+	const includeNode = shouldIncludeNode(platform)
+	const includeBrowser = shouldIncludeBrowser(platform) && registryName === 'features' && _browserData
+
 	const registry = container[registryName]
-	const available: string[] = registry.available
+	const nodeAvailable: string[] = includeNode ? registry.available : []
+	const browserAvailable: string[] = includeBrowser ? _browserData!.available : []
 
-	if (available.length === 0) {
+	// Deduplicate: for --platform all, colliding features appear in both lists
+	const collidingIds = includeBrowser ? _browserData!.collidingIds : new Set<string>()
+
+	const totalCount = nodeAvailable.length + browserAvailable.filter(id => !includeNode || !collidingIds.has(id)).length
+
+	if (totalCount === 0) {
 		return { json: {}, text: `No ${registryName} are registered.` }
 	}
 
-	// When no section filters are specified, render a concise index (like describeAll)
-	// rather than full introspection for every single helper
+	// When no section filters are specified, render a concise index
 	if (sections.length === 0) {
 		const h = '#'.repeat(headingDepth)
 		const hSub = '#'.repeat(headingDepth + 1)
 		const jsonResult: Record<string, any> = {}
-		const textParts: string[] = [`${h} Available ${registryName} (${available.length})\n`]
+		const textParts: string[] = [`${h} Available ${registryName} (${totalCount})\n`]
 
 		// Show shared methods/getters from the base class at the top
-		const baseClass = registry.baseClass
-		if (baseClass) {
-			const shared = collectSharedMembers(baseClass)
-			const label = registryName === 'features' ? 'Feature'
-				: registryName === 'clients' ? 'Client'
-				: registryName === 'servers' ? 'Server'
-				: registryName[0]!.toUpperCase() + registryName.slice(1).replace(/s$/, '')
-
-			if (shared.getters.length) {
-				textParts.push(`**Shared ${label} Getters:** ${shared.getters.join(', ')}\n`)
-			}
-			if (shared.methods.length) {
-				textParts.push(`**Shared ${label} Methods:** ${shared.methods.map(m => m + '()').join(', ')}\n`)
+		if (includeNode) {
+			const baseClass = registry.baseClass
+			if (baseClass) {
+				const shared = collectSharedMembers(baseClass)
+				const label = registryName === 'features' ? 'Feature'
+					: registryName === 'clients' ? 'Client'
+					: registryName === 'servers' ? 'Server'
+					: registryName[0]!.toUpperCase() + registryName.slice(1).replace(/s$/, '')
+
+				if (shared.getters.length) {
+					textParts.push(`**Shared ${label} Getters:** ${shared.getters.join(', ')}\n`)
+				}
+				if (shared.methods.length) {
+					textParts.push(`**Shared ${label} Methods:** ${shared.methods.map(m => m + '()').join(', ')}\n`)
+				}
+
+				jsonResult._shared = { methods: shared.methods, getters: shared.getters }
 			}
+		}
 
-			jsonResult._shared = { methods: shared.methods, getters: shared.getters }
+		// Render node features
+		if (includeNode) {
+			const baseClass = registry.baseClass
+			const sorted = [...nodeAvailable].sort((a, b) => {
+				const aCtor = registry.lookup(a)
+				const bCtor = registry.lookup(b)
+				const aIsDirect = !findIntermediateParent(aCtor, baseClass)
+				const bIsDirect = !findIntermediateParent(bCtor, baseClass)
+				if (aIsDirect && !bIsDirect) return -1
+				if (!aIsDirect && bIsDirect) return 1
+				return 0
+			})
+
+			for (const id of sorted) {
+				const Ctor = registry.lookup(id)
+				const introspection = Ctor.introspect?.()
+				const description = introspection?.description || Ctor.description || 'No description provided'
+				const summary = extractSummary(description)
+				const featureGetters = Object.keys(introspection?.getters || {}).sort()
+				const featureMethods = Object.keys(introspection?.methods || {}).sort()
+				const intermediate = findIntermediateParent(Ctor, baseClass)
+
+				// Tag colliding features with (node) when showing both platforms
+				const platformTag = includeBrowser && collidingIds.has(id) ? ' (node)' : ''
+
+				const entryJson: Record<string, any> = { description: summary, methods: featureMethods, getters: featureGetters }
+				if (intermediate) {
+					entryJson.extends = intermediate.name
+					entryJson.inheritedMethods = intermediate.methods
+					entryJson.inheritedGetters = intermediate.getters
+				}
+				if (platformTag) entryJson.platform = 'node'
+				jsonResult[id + (platformTag ? ':node' : '')] = entryJson
+
+				const extendsLine = intermediate ? `\n> extends ${intermediate.name}\n` : ''
+				const memberLines: string[] = []
+				if (featureGetters.length) memberLines.push(`  getters: ${featureGetters.join(', ')}`)
+				if (featureMethods.length) memberLines.push(`  methods: ${featureMethods.map(m => m + '()').join(', ')}`)
+				if (intermediate) {
+					if (intermediate.getters.length) memberLines.push(`  inherited getters: ${intermediate.getters.join(', ')}`)
+					if (intermediate.methods.length) memberLines.push(`  inherited methods: ${intermediate.methods.map(m => m + '()').join(', ')}`)
+				}
+				const memberBlock = memberLines.length ? '\n' + memberLines.join('\n') + '\n' : ''
+				textParts.push(`${hSub} ${id}${platformTag}${extendsLine}\n${summary}\n${memberBlock}`)
+			}
 		}
 
-		// Sort: core framework classes (direct children of baseClass) first, then the rest
-		const sorted = [...available].sort((a, b) => {
-			const aCtor = registry.lookup(a)
-			const bCtor = registry.lookup(b)
-			const aIsDirect = !findIntermediateParent(aCtor, baseClass)
-			const bIsDirect = !findIntermediateParent(bCtor, baseClass)
-			if (aIsDirect && !bIsDirect) return -1
-			if (!aIsDirect && bIsDirect) return 1
-			return 0
-		})
+		// Render browser features
+		if (includeBrowser) {
+			for (const id of browserAvailable.sort()) {
+				// Skip if already shown as a node feature and platform is not specifically browser
+				if (includeNode && collidingIds.has(id)) {
+					// Show the browser version too, tagged
+					const data = _browserData!.introspection.get(`features.${id}`)
+					if (!data) continue
+					const summary = extractSummary(data.description || 'No description provided')
+					const featureGetters = Object.keys(data.getters || {}).sort()
+					const featureMethods = Object.keys(data.methods || {}).sort()
+
+					jsonResult[id + ':browser'] = { description: summary, methods: featureMethods, getters: featureGetters, platform: 'browser' }
+
+					const memberLines: string[] = []
+					if (featureGetters.length) memberLines.push(`  getters: ${featureGetters.join(', ')}`)
+					if (featureMethods.length) memberLines.push(`  methods: ${featureMethods.map(m => m + '()').join(', ')}`)
+					const memberBlock = memberLines.length ? '\n' + memberLines.join('\n') + '\n' : ''
+					textParts.push(`${hSub} ${id} (browser)\n${summary}\n${memberBlock}`)
+					continue
+				}
 
-		for (const id of sorted) {
-			const Ctor = registry.lookup(id)
-			const introspection = Ctor.introspect?.()
-			const description = introspection?.description || Ctor.description || 'No description provided'
-			// Take only the first 1-2 sentences as the summary
-			const summary = extractSummary(description)
-
-			const featureGetters = Object.keys(introspection?.getters || {}).sort()
-			const featureMethods = Object.keys(introspection?.methods || {}).sort()
-
-			// Detect intermediate parent class (e.g. RestClient between ElevenLabsClient and Client)
-			const intermediate = findIntermediateParent(Ctor, baseClass)
-
-			const entryJson: Record<string, any> = { description: summary, methods: featureMethods, getters: featureGetters }
-			if (intermediate) {
-				entryJson.extends = intermediate.name
-				entryJson.inheritedMethods = intermediate.methods
-				entryJson.inheritedGetters = intermediate.getters
-			}
-			jsonResult[id] = entryJson
+				const data = _browserData!.introspection.get(`features.${id}`)
+				if (!data) continue
+				const summary = extractSummary(data.description || 'No description provided')
+				const featureGetters = Object.keys(data.getters || {}).sort()
+				const featureMethods = Object.keys(data.methods || {}).sort()
 
-			const extendsLine = intermediate ? `\n> extends ${intermediate.name}\n` : ''
+				const platformTag = !includeNode ? '' : ' (browser)'
+				jsonResult[id] = { description: summary, methods: featureMethods, getters: featureGetters, platform: 'browser' }
 
-			const memberLines: string[] = []
-			if (featureGetters.length) memberLines.push(`  getters: ${featureGetters.join(', ')}`)
-			if (featureMethods.length) memberLines.push(`  methods: ${featureMethods.map(m => m + '()').join(', ')}`)
-			if (intermediate) {
-				if (intermediate.getters.length) memberLines.push(`  inherited getters: ${intermediate.getters.join(', ')}`)
-				if (intermediate.methods.length) memberLines.push(`  inherited methods: ${intermediate.methods.map(m => m + '()').join(', ')}`)
+				const memberLines: string[] = []
+				if (featureGetters.length) memberLines.push(`  getters: ${featureGetters.join(', ')}`)
+				if (featureMethods.length) memberLines.push(`  methods: ${featureMethods.map(m => m + '()').join(', ')}`)
+				const memberBlock = memberLines.length ? '\n' + memberLines.join('\n') + '\n' : ''
+				textParts.push(`${hSub} ${id}${platformTag}\n${summary}\n${memberBlock}`)
 			}
-
-			const memberBlock = memberLines.length ? '\n' + memberLines.join('\n') + '\n' : ''
-			textParts.push(`${hSub} ${id}${extendsLine}\n${summary}\n${memberBlock}`)
 		}
 
 		return { json: jsonResult, text: textParts.join('\n') }
@@ -537,10 +976,23 @@ function getRegistryData(container: any, registryName: RegistryName, sections: (
 	// When specific sections are requested, render full detail for each helper
 	const jsonResult: Record<string, any> = {}
 	const textParts: string[] = []
-	for (const id of available) {
-		const Ctor = registry.lookup(id)
-		jsonResult[id] = renderHelperJson(Ctor, sections, noTitle)
-		textParts.push(renderHelperText(Ctor, sections, noTitle, headingDepth))
+
+	if (includeNode) {
+		for (const id of nodeAvailable) {
+			const Ctor = registry.lookup(id)
+			jsonResult[id] = renderHelperJson(Ctor, sections, noTitle)
+			textParts.push(renderHelperText(Ctor, sections, noTitle, headingDepth))
+		}
+	}
+
+	if (includeBrowser) {
+		for (const id of browserAvailable) {
+			if (includeNode && collidingIds.has(id)) continue // already shown
+			const data = _browserData!.introspection.get(`features.${id}`)
+			if (!data) continue
+			jsonResult[id] = renderBrowserHelperJson(data, sections, noTitle)
+			textParts.push(renderBrowserHelperText(data, sections, noTitle, headingDepth))
+		}
 	}
 
 	return { json: jsonResult, text: textParts.join('\n\n---\n\n') }
@@ -688,6 +1140,13 @@ export default async function describe(options: z.infer<typeof argsSchema>, cont
 
 	await container.helpers.discoverAll()
 
+	const platform = normalizePlatform(options.platform)
+
+	// Load browser features if needed
+	if (shouldIncludeBrowser(platform)) {
+		await loadBrowserFeatures()
+	}
+
 	const args = container.argv._ as string[]
 	// args[0] is "describe", the rest are targets
 	const targets = args.slice(1)
@@ -718,7 +1177,7 @@ export default async function describe(options: z.infer<typeof argsSchema>, cont
 
 	for (const target of targets) {
 		try {
-			resolved.push(resolveTarget(target, container))
+			resolved.push(...resolveTarget(target, container, platform))
 		} catch (err: any) {
 			if (err instanceof DescribeError) {
 				console.error(err.message)
@@ -737,11 +1196,15 @@ export default async function describe(options: z.infer<typeof argsSchema>, cont
 			case 'container':
 				return getContainerData(container, sections, noTitle, headingDepth)
 			case 'registry':
-				return getRegistryData(container, item.name, sections, noTitle, headingDepth)
+				return getRegistryData(container, item.name, sections, noTitle, headingDepth, platform)
 			case 'helper':
 				return getHelperData(container, item.registry, item.id, sections, noTitle, headingDepth)
 			case 'member':
 				return getMemberData(container, item.registry, item.id, item.member, item.memberType, headingDepth)
+			case 'browser-helper':
+				return getBrowserHelperData(item.id, sections, noTitle, headingDepth)
+			case 'browser-member':
+				return getBrowserMemberData(item.id, item.member, item.memberType, headingDepth)
 		}
 	}