@growth-labs/cms 0.5.4 → 0.5.6

package/src/surveys/access.ts

@@ -0,0 +1,11 @@
+import type { CmsRole } from '../schema/types.js'
+
+export const SURVEY_RESPONSE_ROLES: ReadonlySet<CmsRole> = new Set([
+	'owner',
+	'senior_editor',
+	'editor',
+])
+
+export function canViewSurveyResponses(role: CmsRole | null | undefined): boolean {
+	return role != null && SURVEY_RESPONSE_ROLES.has(role)
+}

package/src/surveys/errors.ts

@@ -0,0 +1,51 @@
+export const SURVEY_ERROR_CODE_HEADER = 'X-Growth-Labs-Survey-Error-Code'
+
+export const SURVEY_ERROR_DEFINITIONS = {
+	survey_invalid_request: {
+		status: 400,
+		error: 'Invalid survey request.',
+	},
+	survey_forbidden: {
+		status: 403,
+		error: 'You do not have permission to view survey responses.',
+	},
+	survey_not_found: {
+		status: 404,
+		error: 'Survey not found.',
+	},
+	survey_provider_unavailable: {
+		status: 503,
+		error: 'Survey reporting is not configured for this site.',
+	},
+	survey_provider_malformed: {
+		status: 502,
+		error: 'Survey provider returned invalid data.',
+	},
+	survey_upstream_unavailable: {
+		status: 503,
+		error: 'Survey reporting is temporarily unavailable.',
+	},
+	survey_upstream_failure: {
+		status: 502,
+		error: 'Survey reporting could not be loaded.',
+	},
+	survey_internal_failure: {
+		status: 500,
+		error: 'Survey reporting could not be loaded.',
+	},
+} as const
+
+export type SurveyErrorCode = keyof typeof SURVEY_ERROR_DEFINITIONS
+
+export interface SurveyErrorBody {
+	error: string
+	code: SurveyErrorCode
+}
+
+export function isSurveyErrorCode(value: unknown): value is SurveyErrorCode {
+	return typeof value === 'string' && Object.hasOwn(SURVEY_ERROR_DEFINITIONS, value)
+}
+
+export function surveyErrorBody(code: SurveyErrorCode): SurveyErrorBody {
+	return { error: SURVEY_ERROR_DEFINITIONS[code].error, code }
+}

package/src/surveys/schema.ts

@@ -0,0 +1,435 @@
+import { z } from 'zod'
+
+export const SURVEY_ID_MAX_LENGTH = 200
+const MAX_TITLE_LENGTH = 300
+const MAX_PROMPT_LENGTH = 1_000
+const MAX_QUESTIONS = 100
+const MAX_RESPONSES = 500
+const MAX_FREE_TEXT_ENTRIES = 500
+const MAX_FREE_TEXT_LENGTH = 20_000
+const MAX_CHOICE_OPTIONS = 100
+const MAX_OPTION_LENGTH = 256
+const MAX_SCALE_POINTS = 100
+const MAX_COUNT = 1_000_000_000
+const MAX_CSV_FILENAME_LENGTH = 200
+const MAX_CSV_CONTENT_LENGTH = 10_000_000
+const MAX_CSV_COLUMNS = 256
+const MAX_CSV_HEADER_LENGTH = 256
+
+export const SurveyIdSchema = z
+	.string()
+	.min(1)
+	.max(SURVEY_ID_MAX_LENGTH)
+	.regex(/^[A-Za-z0-9_-]+$/)
+export const SurveyQuestionIdSchema = SurveyIdSchema
+const BoundedRecordIdSchema = z
+	.string()
+	.min(1)
+	.max(SURVEY_ID_MAX_LENGTH)
+	.regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/)
+const IsoTimestampSchema = z.string().datetime({ offset: true })
+const CountSchema = z.number().int().nonnegative().max(MAX_COUNT)
+const NonemptyBoundedStringSchema = z
+	.string()
+	.min(1)
+	.max(MAX_OPTION_LENGTH)
+	.refine((value) => value.trim().length > 0)
+
+export const SurveyAudienceSchema = z.enum(['all', 'member', 'non_member'])
+export const SurveyRespondentSegmentSchema = z.enum(['member', 'non_member', 'unknown'])
+
+const ChoiceOptionsSchema = z
+	.array(NonemptyBoundedStringSchema)
+	.min(1)
+	.max(MAX_CHOICE_OPTIONS)
+	.refine((options) => new Set(options).size === options.length)
+
+const CountsSchema = z
+	.record(CountSchema)
+	.refine((counts) => Object.keys(counts).length <= MAX_CHOICE_OPTIONS)
+
+const QuestionBase = {
+	id: SurveyQuestionIdSchema,
+	position: z
+		.number()
+		.int()
+		.nonnegative()
+		.max(MAX_QUESTIONS - 1),
+	prompt: z
+		.string()
+		.min(1)
+		.max(MAX_PROMPT_LENGTH)
+		.refine((value) => value.trim().length > 0),
+	audience: SurveyAudienceSchema,
+	answerCount: CountSchema,
+}
+
+const SingleChoiceQuestionSchema = z
+	.object({
+		...QuestionBase,
+		kind: z.literal('single_choice'),
+		options: ChoiceOptionsSchema,
+		counts: CountsSchema,
+		average: z.null(),
+		distribution: z.null(),
+		responseCount: z.null(),
+	})
+	.strict()
+
+const MultiChoiceQuestionSchema = z
+	.object({
+		...QuestionBase,
+		kind: z.literal('multi_choice'),
+		options: ChoiceOptionsSchema,
+		counts: CountsSchema,
+		average: z.null(),
+		distribution: z.null(),
+		responseCount: z.null(),
+	})
+	.strict()
+
+const ScaleOptionsSchema = z
+	.object({
+		min: z.number().int(),
+		max: z.number().int(),
+	})
+	.strict()
+	.refine(
+		(options) => options.max >= options.min && options.max - options.min + 1 <= MAX_SCALE_POINTS,
+	)
+
+const ScaleQuestionSchema = z
+	.object({
+		...QuestionBase,
+		kind: z.literal('scale'),
+		options: ScaleOptionsSchema,
+		counts: z.null(),
+		average: z.number().finite().nullable(),
+		distribution: z.record(CountSchema),
+		responseCount: z.null(),
+	})
+	.strict()
+
+const TextQuestionSchema = z
+	.object({
+		...QuestionBase,
+		kind: z.literal('text'),
+		options: z
+			.object({ max_length: z.number().int().positive().max(MAX_FREE_TEXT_LENGTH) })
+			.strict(),
+		counts: z.null(),
+		average: z.null(),
+		distribution: z.null(),
+		responseCount: CountSchema,
+	})
+	.strict()
+
+export const SurveyQuestionSchema = z
+	.discriminatedUnion('kind', [
+		SingleChoiceQuestionSchema,
+		MultiChoiceQuestionSchema,
+		ScaleQuestionSchema,
+		TextQuestionSchema,
+	])
+	.superRefine((question, ctx) => {
+		if (question.kind === 'single_choice' || question.kind === 'multi_choice') {
+			if (!hasExactKeys(question.counts, question.options)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: 'Counts must match configured options',
+				})
+			}
+			const total = Object.values(question.counts).reduce((sum, count) => sum + count, 0)
+			if (question.kind === 'single_choice' && total !== question.answerCount) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Choice total is incoherent' })
+			}
+			if (
+				question.kind === 'multi_choice' &&
+				Object.values(question.counts).some((count) => count > question.answerCount)
+			) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Multi-choice total is incoherent' })
+			}
+			return
+		}
+
+		if (question.kind === 'scale') {
+			const keys = Array.from(
+				{ length: question.options.max - question.options.min + 1 },
+				(_, index) => String(question.options.min + index),
+			)
+			if (!hasExactKeys(question.distribution, keys)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: 'Scale distribution must include every configured value',
+				})
+			}
+			const total = Object.values(question.distribution).reduce((sum, count) => sum + count, 0)
+			if (total !== question.answerCount) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Scale total is incoherent' })
+			}
+			if (
+				(question.answerCount === 0 && question.average !== null) ||
+				(question.answerCount > 0 &&
+					(question.average === null ||
+						question.average < question.options.min ||
+						question.average > question.options.max))
+			) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Scale average is incoherent' })
+			}
+			return
+		}
+
+		if (question.responseCount !== question.answerCount) {
+			ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Text response total is incoherent' })
+		}
+	})
+
+export const SurveyResultsSchema = z
+	.object({
+		survey: z
+			.object({
+				id: SurveyIdSchema,
+				title: z
+					.string()
+					.min(1)
+					.max(MAX_TITLE_LENGTH)
+					.refine((value) => value.trim().length > 0),
+				status: z.enum(['draft', 'active', 'closed']),
+				responseCount: CountSchema,
+			})
+			.strict(),
+		questions: z.array(SurveyQuestionSchema).max(MAX_QUESTIONS),
+		responses: z
+			.array(
+				z
+					.object({
+						id: BoundedRecordIdSchema,
+						channel: z.enum(['email', 'site', 'direct']),
+						submittedAt: IsoTimestampSchema,
+						respondentSegment: SurveyRespondentSegmentSchema,
+						anonymous: z.boolean(),
+					})
+					.strict(),
+			)
+			.max(MAX_RESPONSES),
+		freeText: z
+			.array(
+				z
+					.object({
+						questionId: SurveyQuestionIdSchema,
+						responseId: BoundedRecordIdSchema,
+						submittedAt: IsoTimestampSchema,
+						value: z.string().min(1).max(MAX_FREE_TEXT_LENGTH),
+					})
+					.strict(),
+			)
+			.max(MAX_FREE_TEXT_ENTRIES),
+	})
+	.strict()
+	.superRefine((results, ctx) => {
+		const questionIds = new Set<string>()
+		for (const [index, question] of results.questions.entries()) {
+			if (question.position !== index) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['questions', index, 'position'],
+					message: 'Question positions must be ordered',
+				})
+			}
+			if (questionIds.has(question.id)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['questions', index, 'id'],
+					message: 'Question IDs must be unique',
+				})
+			}
+			questionIds.add(question.id)
+			if (question.answerCount > results.survey.responseCount) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['questions', index, 'answerCount'],
+					message: 'Question total exceeds survey total',
+				})
+			}
+		}
+
+		if (results.responses.length > results.survey.responseCount) {
+			ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Response rows exceed survey total' })
+		}
+		const responses = new Map<string, (typeof results.responses)[number]>()
+		for (const [index, response] of results.responses.entries()) {
+			if (responses.has(response.id)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['responses', index, 'id'],
+					message: 'Response IDs must be unique',
+				})
+			}
+			responses.set(response.id, response)
+		}
+
+		const textQuestions = new Map(
+			results.questions
+				.filter(
+					(question): question is z.infer<typeof TextQuestionSchema> => question.kind === 'text',
+				)
+				.map((question) => [question.id, question]),
+		)
+		const freeTextCounts = new Map<string, number>()
+		for (const [index, entry] of results.freeText.entries()) {
+			const question = textQuestions.get(entry.questionId)
+			const response = responses.get(entry.responseId)
+			if (!question || (response && response.submittedAt !== entry.submittedAt)) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['freeText', index],
+					message: 'Free-text references must be coherent',
+				})
+				continue
+			}
+			if (entry.value.length > question.options.max_length) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['freeText', index, 'value'],
+					message: 'Free-text value exceeds its question limit',
+				})
+			}
+			freeTextCounts.set(entry.questionId, (freeTextCounts.get(entry.questionId) ?? 0) + 1)
+		}
+		for (const question of textQuestions.values()) {
+			if ((freeTextCounts.get(question.id) ?? 0) > question.responseCount) {
+				ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Free-text entries exceed total' })
+			}
+		}
+	})
+
+export const SurveyCsvResultSchema = z
+	.object({
+		filename: z.string().min(1).max(MAX_CSV_FILENAME_LENGTH),
+		content: z.string().min(1).max(MAX_CSV_CONTENT_LENGTH),
+	})
+	.strict()
+	.superRefine((result, ctx) => {
+		const header = parseCsvHeader(result.content)
+		if (!header) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['content'],
+				message: 'Invalid CSV header',
+			})
+			return
+		}
+		if (
+			header.length > MAX_CSV_COLUMNS ||
+			header.some(
+				(column) =>
+					column.length === 0 ||
+					column.length > MAX_CSV_HEADER_LENGTH ||
+					column.trim().length === 0,
+			)
+		) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['content'],
+				message: 'CSV header is too large',
+			})
+			return
+		}
+		if (header.some((column) => !isSafeCsvColumn(column))) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['content'],
+				message: 'CSV header contains a non-allowlisted column',
+			})
+		}
+	})
+
+const SafeCsvMetadataColumns = new Set([
+	'response_id',
+	'submitted_at',
+	'channel',
+	'respondent_segment',
+	'anonymous',
+])
+
+function isSafeCsvColumn(value: string): boolean {
+	if (SafeCsvMetadataColumns.has(value)) return true
+	const prefix = 'answer:'
+	return (
+		value.startsWith(prefix) && SurveyQuestionIdSchema.safeParse(value.slice(prefix.length)).success
+	)
+}
+
+function parseCsvHeader(content: string): string[] | null {
+	const fields: string[] = []
+	let field = ''
+	let inQuotes = false
+	let closedQuote = false
+	let atFieldStart = true
+	const source = content.startsWith('\uFEFF') ? content.slice(1) : content
+
+	for (let index = 0; index < source.length; index += 1) {
+		const char = source[index]
+		if (inQuotes) {
+			if (char !== '"') {
+				field += char
+				continue
+			}
+			if (source[index + 1] === '"') {
+				field += '"'
+				index += 1
+				continue
+			}
+			inQuotes = false
+			closedQuote = true
+			continue
+		}
+
+		if (closedQuote) {
+			if (char === ',') {
+				fields.push(field)
+				field = ''
+				closedQuote = false
+				atFieldStart = true
+				continue
+			}
+			if (char === '\r' || char === '\n') {
+				fields.push(field)
+				return fields
+			}
+			return null
+		}
+
+		if (atFieldStart && char === '"') {
+			inQuotes = true
+			atFieldStart = false
+			continue
+		}
+		if (char === '"') return null
+		if (char === ',') {
+			fields.push(field)
+			field = ''
+			atFieldStart = true
+			continue
+		}
+		if (char === '\r' || char === '\n') {
+			fields.push(field)
+			return fields
+		}
+		field += char
+		atFieldStart = false
+	}
+
+	if (inQuotes) return null
+	fields.push(field)
+	return fields
+}
+
+function hasExactKeys(record: Record<string, number>, expected: readonly string[]): boolean {
+	const actual = Object.keys(record)
+	return actual.length === expected.length && expected.every((key) => Object.hasOwn(record, key))
+}
+
+export type SurveyQuestion = z.infer<typeof SurveyQuestionSchema>
+export type SurveyResults = z.infer<typeof SurveyResultsSchema>
+export type SurveyCsvResult = z.infer<typeof SurveyCsvResultSchema>

package/src/ui/api/surveys/[surveyId]/responses.csv.ts

@@ -0,0 +1,23 @@
+import type { APIContext } from 'astro'
+import type { CmsProviders } from '../../../../providers/types.js'
+import type { RouteContext } from '../../../../routes/context.js'
+import { createSurveyRoutes, type SurveyRouteConfig } from '../../../../routes/surveys.js'
+import { buildSiteAuthz } from '../../_authz.js'
+
+function toCtx(context: APIContext): RouteContext {
+	const env = (context.locals as { cmsEnv?: Record<string, unknown> }).cmsEnv ?? {}
+	return {
+		request: context.request,
+		params: { surveyId: context.params.surveyId },
+		db: env.SITE_DB as RouteContext['db'],
+		env,
+	}
+}
+
+function routeConfig(context: APIContext): SurveyRouteConfig {
+	const locals = context.locals as { cmsProviders?: Partial<CmsProviders> }
+	return { authz: buildSiteAuthz(context), providers: locals.cmsProviders }
+}
+
+export const GET = (context: APIContext) =>
+	createSurveyRoutes(routeConfig(context)).csv(toCtx(context))

package/src/ui/api/surveys/[surveyId].ts

@@ -0,0 +1,23 @@
+import type { APIContext } from 'astro'
+import type { CmsProviders } from '../../../providers/types.js'
+import type { RouteContext } from '../../../routes/context.js'
+import { createSurveyRoutes, type SurveyRouteConfig } from '../../../routes/surveys.js'
+import { buildSiteAuthz } from '../_authz.js'
+
+function toCtx(context: APIContext): RouteContext {
+	const env = (context.locals as { cmsEnv?: Record<string, unknown> }).cmsEnv ?? {}
+	return {
+		request: context.request,
+		params: { surveyId: context.params.surveyId },
+		db: env.SITE_DB as RouteContext['db'],
+		env,
+	}
+}
+
+function routeConfig(context: APIContext): SurveyRouteConfig {
+	const locals = context.locals as { cmsProviders?: Partial<CmsProviders> }
+	return { authz: buildSiteAuthz(context), providers: locals.cmsProviders }
+}
+
+export const GET = (context: APIContext) =>
+	createSurveyRoutes(routeConfig(context)).results(toCtx(context))

package/src/ui/client/mount.tsx

@@ -2,7 +2,7 @@ import { config } from 'virtual:growth-labs/cms/config'
 import { createRoot } from 'react-dom/client'
 import type { CmsUser } from '../../routes/context.js'
 import { CmsApp } from '../components/CmsApp.js'
-import { cmsScreens } from '../screens/registry.js'
+import { createCmsScreens } from '../screens/registry.js'
 import { initialWorkspaceState } from '../workspace-context.js'
 import { type MeResponseSummary, resolveBootState } from './boot-state.js'
 import '../styles/broadsheet.css'
@@ -35,7 +35,11 @@ export async function mount(elementId = 'masthead-root') {
 			: null
 
 	const initial = initialWorkspaceState(config.workspaces, config.activeWorkspaceId, user)
-	createRoot(el).render(<CmsApp initial={initial} screens={cmsScreens} boot={boot} />)
+	const screens = createCmsScreens({
+		allowInlineAuthorCreation: config.socialSharing.allowInlineAuthorCreation,
+		surveyId: config.surveyResults?.surveyId,
+	})
+	createRoot(el).render(<CmsApp initial={initial} screens={screens} boot={boot} />)
 }
 
 void mount()

package/src/ui/commands.ts

@@ -1,6 +1,7 @@
 // src/ui/commands.ts — the ⌘K command set + the pure filter. "create"/"jump"
 // are static; "doc" entries are fed in from the /admin/api/search results.
-import type { ContentType } from '../schema/types.js'
+import type { CmsRole, ContentType } from '../schema/types.js'
+import { canViewSurveyResponses } from '../surveys/access.js'
 import { ROUTES, type Route } from './hash-router.js'
 
 export type Command =
@@ -24,6 +25,7 @@ const JUMP_LABELS: Record<Route, string> = {
 	topics: 'Topics & tags',
 	'content-insights': 'Content Insights',
 	subscriptions: 'Subscriptions',
+	'survey-responses': 'Survey responses',
 	'social-share': 'Social Share',
 	settings: 'Settings',
 }
@@ -37,6 +39,7 @@ const JUMP_ICONS: Record<Route, string> = {
 	topics: 'tag',
 	'content-insights': 'sparkle',
 	subscriptions: 'inbox',
+	'survey-responses': 'chart',
 	'social-share': 'share',
 	settings: 'settings',
 }
@@ -57,6 +60,16 @@ export const baseCommands: Command[] = [
 	),
 ]
 
+export function commandsForAccess(options: {
+	surveyResultsEnabled: boolean
+	role: CmsRole | null
+}): Command[] {
+	const canViewSurvey = options.surveyResultsEnabled && canViewSurveyResponses(options.role)
+	return baseCommands.filter(
+		(command) => command.kind !== 'jump' || command.route !== 'survey-responses' || canViewSurvey,
+	)
+}
+
 export function filterCommands(query: string, all: Command[]): Command[] {
 	const q = query.trim().toLowerCase()
 	if (!q) return all.slice(0, 9)

package/src/ui/components/CmsApp.tsx

@@ -1,9 +1,12 @@
 import { Component, type ReactNode, useEffect, useState } from 'react'
+import type { CmsRole } from '../../schema/types.js'
+import { canViewSurveyResponses } from '../../surveys/access.js'
 import type { BootState } from '../client/boot-state.js'
+import { commandsForAccess } from '../commands.js'
 import type { Route } from '../hash-router.js'
 import { useHashRouter } from '../use-hash-router.js'
 import { useTweaks } from '../use-tweaks.js'
-import { WorkspaceProvider, type WorkspaceState } from '../workspace-context.js'
+import { useWorkspace, WorkspaceProvider, type WorkspaceState } from '../workspace-context.js'
 import { CommandPalette } from './CommandPalette.js'
 import { NoAccessScreen } from './NoAccessScreen.js'
 import { Sidebar } from './Sidebar.js'
@@ -33,6 +36,7 @@ export function CmsApp(props: {
 
 function Shell({ screens }: { screens: ScreenRegistry }) {
 	const { route, navigate } = useHashRouter()
+	const { state } = useWorkspace()
 	const { t, setTweak } = useTweaks()
 	const [cmd, setCmd] = useState(false)
 	const [collapsed, setCollapsed] = useState(false)
@@ -47,10 +51,15 @@ function Shell({ screens }: { screens: ScreenRegistry }) {
 		window.addEventListener('keydown', h)
 		return () => window.removeEventListener('keydown', h)
 	}, [])
-	const screen = screens[route]
+	const screen = resolveScreenForAccess(screens, route, state.user?.role ?? null)
 	return (
 		<div className="app" data-collapsed={collapsed}>
-			<Sidebar route={route} navigate={navigate} collapsed={collapsed} />
+			<Sidebar
+				route={route}
+				navigate={navigate}
+				collapsed={collapsed}
+				surveyResultsEnabled={Boolean(screens['survey-responses'])}
+			/>
 			<div className="main">
 				<Topbar
 					collapsed={collapsed}
@@ -70,12 +79,25 @@ function Shell({ screens }: { screens: ScreenRegistry }) {
 					onClose={() => setCmd(false)}
 					navigate={navigate}
 					openDoc={() => setCmd(false)}
+					commands={commandsForAccess({
+						surveyResultsEnabled: Boolean(screens['survey-responses']),
+						role: state.user?.role ?? null,
+					})}
 				/>
 			)}
 		</div>
 	)
 }
 
+export function resolveScreenForAccess(
+	screens: ScreenRegistry,
+	route: Route,
+	role: CmsRole | null,
+): (() => ReactNode) | undefined {
+	if (route === 'survey-responses' && !canViewSurveyResponses(role)) return undefined
+	return screens[route]
+}
+
 function EmptyRoute({ route }: { route: Route }) {
 	return (
 		<div className="page" style={{ padding: 40, color: 'var(--ink-muted)' }}>

package/src/ui/components/CommandPalette.tsx

@@ -12,6 +12,7 @@ export function CommandPalette(props: {
 	onClose: () => void
 	navigate: (r: Route) => void
 	openDoc: (id: string | null, type?: string) => void
+	commands?: Command[]
 }) {
 	const [q, setQ] = useState('')
 	const [docs, setDocs] = useState<Command[]>([])
@@ -35,7 +36,7 @@ export function CommandPalette(props: {
 			.catch(() => {})
 		return () => ctrl.abort()
 	}, [q])
-	const all = [...baseCommands, ...docs]
+	const all = [...(props.commands ?? baseCommands), ...docs]
 	const filtered = filterCommands(q, all)
 	function run(c: Command) {
 		if (c.kind === 'jump') props.navigate(c.route)