@questpie/admin 1.1.0 → 2.0.0

package/dist/server/block/block-builder.mjs

@@ -0,0 +1,217 @@
+//#region src/server/block/block-builder.ts
+/**
+* Create a component proxy for type-safe icon and UI element references.
+* Used in .admin() config functions.
+*/
+function createComponentProxy(registeredComponentNames = []) {
+	const registered = new Set(registeredComponentNames);
+	const hasRegistry = registered.size > 0;
+	return new Proxy({}, {
+		get: (_target, prop) => {
+			if (typeof prop !== "string") return;
+			if (prop === "then") return;
+			if (hasRegistry && !registered.has(prop)) throw new Error(`Unknown component "${prop}" for block admin config. Available components: ${[...registered].sort().join(", ")}`);
+			return (props) => {
+				if (prop === "icon" && typeof props === "string") return {
+					type: "icon",
+					props: { name: props }
+				};
+				if (typeof props === "object" && props !== null) return {
+					type: prop,
+					props
+				};
+				return {
+					type: prop,
+					props: { value: props }
+				};
+			};
+		},
+		has: (_target, prop) => {
+			if (typeof prop !== "string") return false;
+			return hasRegistry ? registered.has(prop) : true;
+		},
+		ownKeys: () => hasRegistry ? [...registered] : [],
+		getOwnPropertyDescriptor: (_target, prop) => {
+			if (typeof prop !== "string") return;
+			if (hasRegistry && !registered.has(prop)) return;
+			return {
+				configurable: true,
+				enumerable: hasRegistry,
+				writable: false,
+				value: (props) => {
+					if (prop === "icon" && typeof props === "string") return {
+						type: "icon",
+						props: { name: props }
+					};
+					if (typeof props === "object" && props !== null) return {
+						type: prop,
+						props
+					};
+					return {
+						type: prop,
+						props: { value: props }
+					};
+				}
+			};
+		}
+	});
+}
+/**
+* Builder class for defining block types.
+*
+* @template TState - Block builder state
+* @template TFieldMap - Field type map for typed field proxy (from builder's registered fields)
+* @template TData - Prefetch data type (set by .prefetch(), preserved through chain)
+*/
+var BlockBuilder = class BlockBuilder {
+	_state;
+	constructor(state) {
+		this._state = state;
+	}
+	/**
+	* Set admin metadata for the block.
+	* Follows the same pattern as collection .admin() method.
+	*
+	* @example
+	* ```ts
+	* block("hero")
+	*   .admin(({ c }) => ({
+	*     label: { en: "Hero Section", sk: "Hero sekcia" },
+	*     icon: c.icon("ph:image"),
+	*     description: { en: "Full-width hero with background image" },
+	*     category: {
+	*       label: { en: "Sections", sk: "Sekcie" },
+	*       icon: c.icon("ph:layout"),
+	*       order: 1,
+	*     },
+	*     order: 1,
+	*     hidden: false,
+	*   }))
+	* ```
+	*/
+	admin(configOrFn) {
+		const registeredComponents = this._state["~components"] ?? [];
+		const config = typeof configOrFn === "function" ? configOrFn({ c: createComponentProxy(registeredComponents) }) : configOrFn;
+		return new BlockBuilder({
+			...this._state,
+			admin: config
+		});
+	}
+	/**
+	* Define fields for the block.
+	* Uses the same field builder as collections.
+	*
+	* @example
+	* ```ts
+	* block("hero").fields((f) => ({
+	*   title: f.text({ required: true }),
+	*   subtitle: f.text(),
+	*   image: f.upload({ accept: "image/*" }),
+	* }))
+	* ```
+	*/
+	fields(factory) {
+		return new BlockBuilder({
+			...this._state,
+			_fieldsFactory: factory
+		});
+	}
+	/**
+	* Allow child blocks (for layout blocks).
+	*
+	* @example
+	* ```ts
+	* block("columns").allowChildren()
+	* block("columns").allowChildren(4) // max 4 children
+	* ```
+	*/
+	allowChildren(maxChildren) {
+		return new BlockBuilder({
+			...this._state,
+			allowChildren: true,
+			maxChildren
+		});
+	}
+	prefetch(fnOrConfig) {
+		if (typeof fnOrConfig === "function") return new BlockBuilder({
+			...this._state,
+			prefetch: fnOrConfig
+		});
+		const { with: withFields, loader } = fnOrConfig;
+		return new BlockBuilder({
+			...this._state,
+			prefetchWith: withFields,
+			_prefetchLoader: loader
+		});
+	}
+	/**
+	* Build the block definition.
+	* Called automatically when registering with .blocks().
+	*/
+	build() {
+		const state = this._state;
+		return {
+			name: state.name,
+			state,
+			getFieldMetadata() {
+				if (!state.fields) return {};
+				const fields = {};
+				for (const [name, fieldDef] of Object.entries(state.fields)) fields[name] = {
+					name,
+					metadata: fieldDef.getMetadata()
+				};
+				return fields;
+			},
+			async executePrefetch(values, ctx) {
+				if (!state.prefetch) return {};
+				return state.prefetch({
+					values,
+					ctx
+				});
+			}
+		};
+	}
+	/**
+	* Get the current state (for internal use).
+	*/
+	get state() {
+		return this._state;
+	}
+};
+/**
+* Create a new server-side block builder.
+*
+* Defines block types with fields, validation, and prefetch logic.
+* Blocks are server-only - the frontend handles rendering independently.
+*
+* @example
+* ```ts
+* import { block } from "@questpie/admin/server";
+*
+* const heroBlock = block("hero")
+*   .admin(({ c }) => ({
+*     label: { en: "Hero Section" },
+*     icon: c.icon("ph:image"),
+*     category: {
+*       label: { en: "Layout" },
+*     },
+*   }))
+*   .fields((f) => ({
+*     title: f.text({ required: true }),
+*     subtitle: f.text(),
+*   }));
+*
+* // Register blocks on CMS
+* const cms = q({ name: "my-app" })
+*   .use(adminModule)
+*   .blocks({ hero: heroBlock })
+*   .build({ ... });
+* ```
+*/
+function block(name) {
+	return new BlockBuilder({ name });
+}
+
+//#endregion
+export { BlockBuilder, block };
+//# sourceMappingURL=block-builder.mjs.map

package/dist/server/block/block-builder.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-builder.mjs","names":["fields: Record<string, FieldSchema>"],"sources":["../../../src/server/block/block-builder.ts"],"sourcesContent":["/**\n * Block Builder\n *\n * Defines block types for the visual block editor.\n * Blocks are registered on the CMS builder and can be used in blocks fields.\n *\n * Each block has:\n * - Admin metadata (label, description, icon, category) via .admin()\n * - Fields (using the same field system as collections)\n * - Optional prefetch function (runs on CRUD read to fetch related data)\n * - Optional children configuration (for nested blocks)\n *\n * @example\n * ```ts\n * import { block } from \"@questpie/admin/server\";\n *\n * const heroBlock = block(\"hero\")\n *   .admin(({ c }) => ({\n *     label: { en: \"Hero Section\", sk: \"Hero sekcia\" },\n *     icon: c.icon(\"ph:image\"),\n *     category: {\n *       label: { en: \"Sections\", sk: \"Sekcie\" },\n *       icon: c.icon(\"ph:layout\"),\n *     },\n *   }))\n *   .fields((f) => ({\n *     title: f.text({ required: true }),\n *     subtitle: f.text(),\n *     backgroundImage: f.upload({ accept: \"image/*\" }),\n *   }))\n *   .prefetch({ with: { backgroundImage: true } });\n * ```\n */\n\nimport type {\n\tFieldBuilderProxy,\n\tFieldDefinition,\n\tFieldDefinitionState,\n\tFieldSchema,\n\tRegisteredApp,\n} from \"questpie\";\nimport type { AdminBlockConfig, AdminConfigContext } from \"../augmentation.js\";\n\n// ============================================================================\n// Block Types\n// ============================================================================\n\n/**\n * Block prefetch context.\n * Provided to prefetch functions to fetch related data.\n *\n * When you register your app via `Register.app`, `ctx.app` is automatically typed.\n * For module-scoped typing, use `getApp<T>(ctx.app)`.\n *\n * @example\n * ```ts\n * // questpie.gen.ts - register your app for automatic typing\n * declare module \"questpie\" {\n *   interface Register {\n *     app: typeof import(\"./cms\").baseCms.$inferCms;\n *   }\n * }\n *\n * // blocks.ts - ctx.app is now typed\n * .prefetch(async ({ values, ctx }) => {\n *   const res = await ctx.app.api.collections.posts.find({ limit: 5 });\n *   return { posts: res.docs };\n * })\n * ```\n */\nexport interface BlockPrefetchContext {\n\t/** Block instance ID */\n\tblockId: string;\n\t/** Block type name */\n\tblockType: string;\n\t/** CMS app instance — typed via Register.app */\n\tapp: RegisteredApp;\n\t/** Current locale */\n\tlocale?: string;\n\t/** Database client */\n\tdb: unknown;\n}\n\n/**\n * Block prefetch function.\n * Runs during CRUD read to fetch related data for the block.\n * The returned data is attached to `_data[blockId]` in the response.\n */\nexport type BlockPrefetchFn<TValues = Record<string, unknown>> = (params: {\n\t/** Block field values */\n\tvalues: TValues;\n\t/** Prefetch context */\n\tctx: BlockPrefetchContext;\n}) => Promise<Record<string, unknown>> | Record<string, unknown>;\n\n/**\n * Expanded record from expansion of relation/upload fields.\n * Contains at minimum an `id` field plus any other fields from the referenced record.\n */\nexport type ExpandedRecord = Record<string, unknown> & { id: string };\n\n/**\n * Options for a single relation inside a block prefetch `with` clause.\n * Same syntax as find's `with`, but only nested `with` is supported —\n * query options (where, orderBy, limit, etc.) don't apply to block field expansion.\n *\n * Nested `with` is passed through to the collection's `find` call,\n * reusing the existing relation resolution machinery.\n */\nexport type BlockPrefetchWithOptions = {\n\twith?: Record<string, true | BlockPrefetchWithOptions>;\n};\n\n/**\n * Block prefetch `with` clause.\n * Same object syntax as `with` in find operations.\n *\n * Each key is a relation/upload field name. Value can be:\n * - `true` — expand the field to a full record\n * - `{ with: { ... } }` — expand with nested relation loading\n *\n * @example\n * ```ts\n * // Simple expansion\n * .prefetch({ with: { backgroundImage: true } })\n *\n * // Nested expansion (e.g., expand author and their avatar)\n * .prefetch({ with: { author: { with: { avatar: true } } } })\n * ```\n */\nexport type BlockPrefetchWith<TFields = Record<string, unknown>> = {\n\t[K in keyof TFields]?: true | BlockPrefetchWithOptions;\n};\n\n/**\n * Compute the expanded data type from a `with` config object.\n * Each key that is `true` or `{ with: ... }` produces `ExpandedRecord | null`.\n */\nexport type ExpandWithResult<TWith> = {\n\t[K in keyof TWith as TWith[K] extends false | undefined\n\t\t? never\n\t\t: K]: ExpandedRecord | null;\n};\n\n/**\n * Block builder state.\n */\nexport interface BlockBuilderState<\n\tTName extends string = string,\n\tTFields extends Record<\n\t\tstring,\n\t\tFieldDefinition<FieldDefinitionState>\n\t> = Record<string, FieldDefinition<FieldDefinitionState>>,\n> {\n\t/** Block type name */\n\tname: TName;\n\t/** Admin configuration (label, icon, description, category, etc.) */\n\tadmin?: AdminBlockConfig;\n\t/** Field definitions */\n\tfields?: TFields;\n\t/** Allow child blocks */\n\tallowChildren?: boolean;\n\t/** Maximum number of child blocks */\n\tmaxChildren?: number;\n\t/** Prefetch function (Shape 1: pure function) */\n\tprefetch?: BlockPrefetchFn<any>;\n\t/** Relation fields to expand via `.prefetch({ with: { ... } })` */\n\tprefetchWith?: BlockPrefetchWith;\n\t/** Loader function for `.prefetch({ with, loader })` (Shape 3) */\n\t_prefetchLoader?: (params: {\n\t\tvalues: any;\n\t\texpanded: Record<string, unknown>;\n\t\tctx: BlockPrefetchContext;\n\t}) => Promise<Record<string, unknown>> | Record<string, unknown>;\n\t/** Type-level marker for prefetch data type (not used at runtime) */\n\t\"~prefetchData\"?: unknown;\n\t/** Optional registered component names from Questpie builder registry */\n\t\"~components\"?: string[];\n}\n\n/**\n * Block definition - the built block ready for registration.\n */\nexport interface BlockDefinition<\n\tTState extends BlockBuilderState = BlockBuilderState,\n> {\n\t/** Block type name */\n\treadonly name: TState[\"name\"];\n\t/** Full state */\n\treadonly state: TState;\n\t/** Get field metadata for introspection */\n\tgetFieldMetadata(): Record<string, FieldSchema>;\n\t/** Execute prefetch if defined */\n\texecutePrefetch(\n\t\tvalues: Record<string, unknown>,\n\t\tctx: BlockPrefetchContext,\n\t): Promise<Record<string, unknown>>;\n}\n\n// ============================================================================\n// Component Proxy Factory (same pattern as collections)\n// ============================================================================\n\n/**\n * Create a component proxy for type-safe icon and UI element references.\n * Used in .admin() config functions.\n */\nfunction createComponentProxy(\n\tregisteredComponentNames: string[] = [],\n): AdminConfigContext[\"c\"] {\n\tconst registered = new Set(registeredComponentNames);\n\tconst hasRegistry = registered.size > 0;\n\n\treturn new Proxy(\n\t\t{} as Record<string, (props: Record<string, unknown> | string) => unknown>,\n\t\t{\n\t\t\tget: (_target, prop: string | symbol) => {\n\t\t\t\tif (typeof prop !== \"string\") {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\n\t\t\t\tif (prop === \"then\") {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\n\t\t\t\tif (hasRegistry && !registered.has(prop)) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`Unknown component \"${prop}\" for block admin config. ` +\n\t\t\t\t\t\t\t`Available components: ${[...registered].sort().join(\", \")}`,\n\t\t\t\t\t);\n\t\t\t\t}\n\n\t\t\t\treturn (props: Record<string, unknown> | string) => {\n\t\t\t\t\tif (prop === \"icon\" && typeof props === \"string\") {\n\t\t\t\t\t\treturn { type: \"icon\", props: { name: props } } as const;\n\t\t\t\t\t}\n\n\t\t\t\t\tif (typeof props === \"object\" && props !== null) {\n\t\t\t\t\t\treturn { type: prop, props } as const;\n\t\t\t\t\t}\n\n\t\t\t\t\treturn { type: prop, props: { value: props } } as const;\n\t\t\t\t};\n\t\t\t},\n\t\t\thas: (_target, prop: string | symbol) => {\n\t\t\t\tif (typeof prop !== \"string\") {\n\t\t\t\t\treturn false;\n\t\t\t\t}\n\t\t\t\treturn hasRegistry ? registered.has(prop) : true;\n\t\t\t},\n\t\t\townKeys: () => (hasRegistry ? [...registered] : []),\n\t\t\tgetOwnPropertyDescriptor: (_target, prop: string | symbol) => {\n\t\t\t\tif (typeof prop !== \"string\") {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\n\t\t\t\tif (hasRegistry && !registered.has(prop)) {\n\t\t\t\t\treturn undefined;\n\t\t\t\t}\n\n\t\t\t\treturn {\n\t\t\t\t\tconfigurable: true,\n\t\t\t\t\tenumerable: hasRegistry,\n\t\t\t\t\twritable: false,\n\t\t\t\t\tvalue: (props: Record<string, unknown> | string) => {\n\t\t\t\t\t\tif (prop === \"icon\" && typeof props === \"string\") {\n\t\t\t\t\t\t\treturn { type: \"icon\", props: { name: props } } as const;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tif (typeof props === \"object\" && props !== null) {\n\t\t\t\t\t\t\treturn { type: prop, props } as const;\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\treturn { type: prop, props: { value: props } } as const;\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t},\n\t\t},\n\t) as AdminConfigContext[\"c\"];\n}\n\n// ============================================================================\n// Block Builder Class\n// ============================================================================\n\n/**\n * Builder class for defining block types.\n *\n * @template TState - Block builder state\n * @template TFieldMap - Field type map for typed field proxy (from builder's registered fields)\n * @template TData - Prefetch data type (set by .prefetch(), preserved through chain)\n */\nexport class BlockBuilder<\n\tTState extends BlockBuilderState = BlockBuilderState,\n\tTFieldMap extends Record<string, any> = Record<string, any>,\n\tTData = Record<string, unknown>,\n> {\n\tprivate _state: TState;\n\n\tconstructor(state: TState) {\n\t\tthis._state = state;\n\t}\n\n\t/**\n\t * Set admin metadata for the block.\n\t * Follows the same pattern as collection .admin() method.\n\t *\n\t * @example\n\t * ```ts\n\t * block(\"hero\")\n\t *   .admin(({ c }) => ({\n\t *     label: { en: \"Hero Section\", sk: \"Hero sekcia\" },\n\t *     icon: c.icon(\"ph:image\"),\n\t *     description: { en: \"Full-width hero with background image\" },\n\t *     category: {\n\t *       label: { en: \"Sections\", sk: \"Sekcie\" },\n\t *       icon: c.icon(\"ph:layout\"),\n\t *       order: 1,\n\t *     },\n\t *     order: 1,\n\t *     hidden: false,\n\t *   }))\n\t * ```\n\t */\n\tadmin(\n\t\tconfigOrFn:\n\t\t\t| AdminBlockConfig\n\t\t\t| ((ctx: AdminConfigContext) => AdminBlockConfig),\n\t): BlockBuilder<TState & { admin: AdminBlockConfig }, TFieldMap, TData> {\n\t\tconst registeredComponents =\n\t\t\t(this._state as any)[\"~components\"] ?? ([] as string[]);\n\n\t\tconst config =\n\t\t\ttypeof configOrFn === \"function\"\n\t\t\t\t? configOrFn({ c: createComponentProxy(registeredComponents) })\n\t\t\t\t: configOrFn;\n\n\t\treturn new BlockBuilder<\n\t\t\tTState & { admin: AdminBlockConfig },\n\t\t\tTFieldMap,\n\t\t\tTData\n\t\t>({\n\t\t\t...this._state,\n\t\t\tadmin: config,\n\t\t} as TState & { admin: AdminBlockConfig });\n\t}\n\n\t/**\n\t * Define fields for the block.\n\t * Uses the same field builder as collections.\n\t *\n\t * @example\n\t * ```ts\n\t * block(\"hero\").fields((f) => ({\n\t *   title: f.text({ required: true }),\n\t *   subtitle: f.text(),\n\t *   image: f.upload({ accept: \"image/*\" }),\n\t * }))\n\t * ```\n\t */\n\tfields<\n\t\tTNewFields extends Record<string, FieldDefinition<FieldDefinitionState>>,\n\t>(\n\t\tfactory: (f: FieldBuilderProxy<TFieldMap>) => TNewFields,\n\t): BlockBuilder<\n\t\tOmit<TState, \"fields\"> & { fields: TNewFields },\n\t\tTFieldMap,\n\t\tTData\n\t> {\n\t\t// Store the factory for later resolution when CMS is built\n\t\t// The actual field definitions are created when block is registered\n\t\treturn new BlockBuilder({\n\t\t\t...this._state,\n\t\t\t_fieldsFactory: factory,\n\t\t} as any);\n\t}\n\n\t/**\n\t * Allow child blocks (for layout blocks).\n\t *\n\t * @example\n\t * ```ts\n\t * block(\"columns\").allowChildren()\n\t * block(\"columns\").allowChildren(4) // max 4 children\n\t * ```\n\t */\n\tallowChildren(\n\t\tmaxChildren?: number,\n\t): BlockBuilder<\n\t\tTState & { allowChildren: true; maxChildren?: number },\n\t\tTFieldMap,\n\t\tTData\n\t> {\n\t\treturn new BlockBuilder({\n\t\t\t...this._state,\n\t\t\tallowChildren: true,\n\t\t\tmaxChildren,\n\t\t} as TState & { allowChildren: true; maxChildren?: number });\n\t}\n\n\t/**\n\t * Add prefetch configuration for server-side data fetching.\n\t * Runs during CRUD read to fetch related data for the block.\n\t *\n\t * Supports three shapes:\n\t *\n\t * **Shape 1: Pure function** — return data directly, `TData` inferred from return type.\n\t * ```ts\n\t * .prefetch(async ({ values, ctx }) => {\n\t *   return { services: res.docs };\n\t * })\n\t * ```\n\t *\n\t * **Shape 2: Expand relation/upload fields** — same `with` syntax as find operations.\n\t * ```ts\n\t * .prefetch({ with: { backgroundImage: true } })\n\t *\n\t * // Nested expansion (passes through to collection find's `with`)\n\t * .prefetch({ with: { author: { with: { avatar: true } } } })\n\t * ```\n\t *\n\t * **Shape 3: Expand + custom loader** — expand fields, then run a loader with the expanded data.\n\t * ```ts\n\t * .prefetch({\n\t *   with: { backgroundImage: true },\n\t *   loader: async ({ values, expanded, ctx }) => {\n\t *     return { analytics: await getStats() };\n\t *   },\n\t * })\n\t * ```\n\t */\n\t// Overload 1: Pure function (Shape 1)\n\tprefetch<TNewData extends Record<string, unknown>>(\n\t\tfn: (params: {\n\t\t\tvalues: InferBlockValues<TState>;\n\t\t\tctx: BlockPrefetchContext;\n\t\t}) => Promise<TNewData> | TNewData,\n\t): BlockBuilder<\n\t\tOmit<TState, \"prefetch\" | \"~prefetchData\"> & {\n\t\t\tprefetch: typeof fn;\n\t\t\t\"~prefetchData\": TNewData;\n\t\t},\n\t\tTFieldMap,\n\t\tTNewData\n\t>;\n\t// Overload 2: Config object with `with` and optional `loader` (Shape 2 & 3)\n\tprefetch<\n\t\tconst TWith extends BlockPrefetchWith<InferBlockValues<TState>>,\n\t\tTLoaderData extends Record<string, unknown> = {},\n\t>(config: {\n\t\twith: TWith;\n\t\tloader?: (params: {\n\t\t\tvalues: InferBlockValues<TState>;\n\t\t\texpanded: ExpandWithResult<TWith>;\n\t\t\tctx: BlockPrefetchContext;\n\t\t}) => Promise<TLoaderData> | TLoaderData;\n\t}): BlockBuilder<\n\t\tOmit<\n\t\t\tTState,\n\t\t\t\"prefetch\" | \"prefetchWith\" | \"_prefetchLoader\" | \"~prefetchData\"\n\t\t> & {\n\t\t\tprefetchWith: TWith;\n\t\t\t\"~prefetchData\": ExpandWithResult<TWith> & TLoaderData;\n\t\t},\n\t\tTFieldMap,\n\t\tExpandWithResult<TWith> & TLoaderData\n\t>;\n\t// Implementation\n\tprefetch(fnOrConfig: any): any {\n\t\tif (typeof fnOrConfig === \"function\") {\n\t\t\treturn new BlockBuilder({\n\t\t\t\t...this._state,\n\t\t\t\tprefetch: fnOrConfig,\n\t\t\t} as any);\n\t\t}\n\n\t\tconst { with: withFields, loader } = fnOrConfig;\n\t\treturn new BlockBuilder({\n\t\t\t...this._state,\n\t\t\tprefetchWith: withFields,\n\t\t\t_prefetchLoader: loader,\n\t\t} as any);\n\t}\n\n\t/**\n\t * Build the block definition.\n\t * Called automatically when registering with .blocks().\n\t */\n\tbuild(): BlockDefinition<TState> {\n\t\tconst state = this._state;\n\n\t\treturn {\n\t\t\tname: state.name,\n\t\t\tstate,\n\t\t\tgetFieldMetadata() {\n\t\t\t\tif (!state.fields) return {};\n\t\t\t\tconst fields: Record<string, FieldSchema> = {};\n\t\t\t\tfor (const [name, fieldDef] of Object.entries(state.fields)) {\n\t\t\t\t\tfields[name] = {\n\t\t\t\t\t\tname,\n\t\t\t\t\t\tmetadata: fieldDef.getMetadata(),\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\treturn fields;\n\t\t\t},\n\t\t\tasync executePrefetch(values, ctx) {\n\t\t\t\tif (!state.prefetch) return {};\n\t\t\t\treturn state.prefetch({ values, ctx });\n\t\t\t},\n\t\t};\n\t}\n\n\t/**\n\t * Get the current state (for internal use).\n\t */\n\tget state(): TState {\n\t\treturn this._state;\n\t}\n}\n\n// ============================================================================\n// Factory Function\n// ============================================================================\n\n/**\n * Create a new server-side block builder.\n *\n * Defines block types with fields, validation, and prefetch logic.\n * Blocks are server-only - the frontend handles rendering independently.\n *\n * @example\n * ```ts\n * import { block } from \"@questpie/admin/server\";\n *\n * const heroBlock = block(\"hero\")\n *   .admin(({ c }) => ({\n *     label: { en: \"Hero Section\" },\n *     icon: c.icon(\"ph:image\"),\n *     category: {\n *       label: { en: \"Layout\" },\n *     },\n *   }))\n *   .fields((f) => ({\n *     title: f.text({ required: true }),\n *     subtitle: f.text(),\n *   }));\n *\n * // Register blocks on CMS\n * const cms = q({ name: \"my-app\" })\n *   .use(adminModule)\n *   .blocks({ hero: heroBlock })\n *   .build({ ... });\n * ```\n */\nexport function block<TName extends string>(\n\tname: TName,\n): BlockBuilder<{ name: TName }> {\n\treturn new BlockBuilder({ name });\n}\n\n// ============================================================================\n// Utility Types\n// ============================================================================\n\n/**\n * Extract field values type from block state.\n * Infers value type per-field to produce heterogeneous types\n * (e.g., { title: string, count: number, showPrices: boolean }).\n */\nexport type InferBlockValues<TState extends BlockBuilderState> =\n\tTState[\"fields\"] extends Record<string, FieldDefinition<FieldDefinitionState>>\n\t\t? {\n\t\t\t\t[K in keyof TState[\"fields\"]]: TState[\"fields\"][K] extends FieldDefinition<\n\t\t\t\t\tinfer TFieldState\n\t\t\t\t>\n\t\t\t\t\t? TFieldState[\"value\"]\n\t\t\t\t\t: unknown;\n\t\t\t}\n\t\t: Record<string, unknown>;\n\n/**\n * Extract prefetch data type from a block builder or block state.\n * Infers the `data` type based on `.prefetch()` configuration:\n * - Shape 1 (function): return type of the prefetch function\n * - Shape 2 (`{ with }` ): expanded fields as `{ [field]: ExpandedRecord | null }`\n * - Shape 3 (`{ with, loader }`): expanded fields merged with loader return type\n * - No prefetch: `Record<string, unknown>`\n *\n * Accepts either a `BlockBuilder` instance or a `BlockBuilderState`.\n * Prefer passing the builder — state-level extraction may fail when\n * `as any` casts are present in the builder chain.\n */\nexport type InferBlockData<T> =\n\tT extends BlockBuilder<any, any, infer TData>\n\t\t? TData\n\t\t: T extends BlockBuilderState\n\t\t\t? T[\"~prefetchData\"] extends Record<string, unknown>\n\t\t\t\t? T[\"~prefetchData\"]\n\t\t\t\t: Record<string, unknown>\n\t\t\t: Record<string, unknown>;\n\n/**\n * Any block builder (for generic usage).\n */\nexport type AnyBlockBuilder = BlockBuilder<BlockBuilderState, any, any>;\n\n/**\n * Any block definition (for generic usage).\n */\nexport type AnyBlockDefinition = BlockDefinition<BlockBuilderState>;\n"],"mappings":"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"}

package/dist/server/block/index.d.mts

@@ -0,0 +1,3 @@
+import { AnyBlockBuilder, AnyBlockDefinition, BlockBuilder, BlockBuilderState, BlockDefinition, BlockPrefetchContext, BlockPrefetchFn, BlockPrefetchWith, BlockPrefetchWithOptions, ExpandWithResult, ExpandedRecord, InferBlockData, InferBlockValues, block } from "./block-builder.mjs";
+import { BlockSchema, getBlocksByCategory, introspectBlock, introspectBlocks } from "./introspection.mjs";
+import { BlocksPrefetchContext, createBlocksPrefetchHook, processBlocksDocument, processDocumentBlocksPrefetch } from "./prefetch.mjs";

package/dist/server/block/introspection.d.mts

@@ -0,0 +1,84 @@
+import { AnyBlockDefinition } from "./block-builder.mjs";
+import { BlockCategoryConfig, ComponentReference } from "../augmentation.mjs";
+import { I18nText } from "questpie/shared";
+import { FieldSchema } from "questpie";
+
+//#region src/server/block/introspection.d.ts
+
+/**
+ * Introspected block schema for admin consumption.
+ * All admin metadata comes from the .admin() configuration.
+ */
+interface BlockSchema {
+  /** Block type name */
+  name: string;
+  /** Admin configuration */
+  admin?: {
+    /** Display label */
+    label?: I18nText;
+    /** Description */
+    description?: I18nText;
+    /** Icon reference */
+    icon?: ComponentReference;
+    /** Category for grouping in block picker */
+    category?: BlockCategoryConfig;
+    /** Order within category in block picker */
+    order?: number;
+    /** Hide from block picker */
+    hidden?: boolean;
+  };
+  /** Allow child blocks */
+  allowChildren?: boolean;
+  /** Maximum number of child blocks */
+  maxChildren?: number;
+  /** Has prefetch function */
+  hasPrefetch: boolean;
+  /** Field schemas - unified format using FieldSchema */
+  fields: Record<string, FieldSchema>;
+  /** Validation schemas */
+  validation?: {
+    insert?: unknown;
+    update?: unknown;
+  };
+}
+/**
+ * Category info extracted from blocks for UI rendering.
+ */
+interface CategoryInfo {
+  /** Category key (derived from label or auto-generated) */
+  key: string;
+  /** Category configuration */
+  config: BlockCategoryConfig;
+  /** Blocks in this category */
+  blocks: BlockSchema[];
+}
+/**
+ * Introspect a single block definition.
+ * Handles both server BlockBuilder definitions and client BlockDefinition objects
+ * that were converted via the `.blocks()` patch.
+ */
+declare function introspectBlock(blockDef: AnyBlockDefinition): BlockSchema;
+/**
+ * Introspect all registered blocks.
+ *
+ * @param blocks - Record of registered block definitions
+ * @returns Record of block schemas
+ *
+ * @example
+ * ```ts
+ * import { introspectBlocks } from "@questpie/admin/server";
+ *
+ * // In an API route
+ * const blocks = introspectBlocks(cms.state.blocks);
+ * return Response.json({ blocks });
+ * ```
+ */
+declare function introspectBlocks(blocks: Record<string, AnyBlockDefinition> | undefined): Record<string, BlockSchema>;
+/**
+ * Get blocks grouped by category with full category info.
+ * Useful for block picker UI.
+ */
+declare function getBlocksByCategory(blocks: Record<string, BlockSchema>): CategoryInfo[];
+//#endregion
+export { BlockSchema, getBlocksByCategory, introspectBlock, introspectBlocks };
+//# sourceMappingURL=introspection.d.mts.map

package/dist/server/block/introspection.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.mts","names":[],"sources":["../../../src/server/block/introspection.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAqDe,UA9BE,WAAA,CA8BF;EAYE;EAkBD,IAAA,EAAA,MAAA;EA4BA;EACQ,KAAA,CAAA,EAAA;IAAf;IACS,KAAA,CAAA,EAnFR,QAmFQ;IAAf;IAAM,WAAA,CAAA,EAjFO,QAiFP;IAwCO;IACQ,IAAA,CAAA,EAxHf,kBAwHe;IAAf;IACN,QAAA,CAAA,EAvHU,mBAuHV;IAAY;;;;;;;;;;;;UAtGN,eAAe;;;;;;;;;;UAYP,YAAA;;;;UAIR;;UAEA;;;;;;;iBAYO,eAAA,WAA0B,qBAAqB;;;;;;;;;;;;;;;;iBA4B/C,gBAAA,SACP,eAAe,kCACrB,eAAe;;;;;iBAwCF,mBAAA,SACP,eAAe,eACrB"}

package/dist/server/block/introspection.mjs

@@ -0,0 +1,89 @@
+import { isI18nLocaleMap } from "questpie/shared";
+
+//#region src/server/block/introspection.ts
+/**
+* Introspect a single block definition.
+* Handles both server BlockBuilder definitions and client BlockDefinition objects
+* that were converted via the `.blocks()` patch.
+*/
+function introspectBlock(blockDef) {
+	const state = blockDef.state;
+	return {
+		name: state.name ?? blockDef.name,
+		admin: state.admin,
+		allowChildren: state.allowChildren,
+		maxChildren: state.maxChildren,
+		hasPrefetch: typeof state.prefetch === "function",
+		fields: blockDef.getFieldMetadata()
+	};
+}
+/**
+* Introspect all registered blocks.
+*
+* @param blocks - Record of registered block definitions
+* @returns Record of block schemas
+*
+* @example
+* ```ts
+* import { introspectBlocks } from "@questpie/admin/server";
+*
+* // In an API route
+* const blocks = introspectBlocks(cms.state.blocks);
+* return Response.json({ blocks });
+* ```
+*/
+function introspectBlocks(blocks) {
+	if (!blocks) return {};
+	const schemas = {};
+	for (const [name, blockDef] of Object.entries(blocks)) schemas[name] = introspectBlock(blockDef);
+	return schemas;
+}
+/**
+* Generate a category key from category config.
+* Uses English label as key, falling back to first available label.
+*/
+function getCategoryKey(category) {
+	const { label } = category;
+	if (typeof label === "string") return label.toLowerCase().replace(/\s+/g, "-");
+	if (isI18nLocaleMap(label)) return (label.en ?? Object.values(label)[0] ?? "").toLowerCase().replace(/\s+/g, "-");
+	return label.key.toLowerCase().replace(/[.:]/g, "-");
+}
+/**
+* Get blocks grouped by category with full category info.
+* Useful for block picker UI.
+*/
+function getBlocksByCategory(blocks) {
+	const categoryMap = /* @__PURE__ */ new Map();
+	const uncategorizedKey = "uncategorized";
+	const uncategorizedConfig = {
+		label: { en: "Uncategorized" },
+		order: 999
+	};
+	for (const block of Object.values(blocks)) {
+		if (block.admin?.hidden) continue;
+		const categoryConfig = block.admin?.category;
+		let key;
+		let config;
+		if (categoryConfig) {
+			key = getCategoryKey(categoryConfig);
+			config = categoryConfig;
+		} else {
+			key = uncategorizedKey;
+			config = uncategorizedConfig;
+		}
+		if (!categoryMap.has(key)) categoryMap.set(key, {
+			key,
+			config,
+			blocks: []
+		});
+		categoryMap.get(key).blocks.push(block);
+	}
+	const categories = Array.from(categoryMap.values());
+	categories.sort((a, b) => (a.config.order ?? 999) - (b.config.order ?? 999));
+	for (const category of categories) category.blocks.sort((a, b) => (a.admin?.order ?? 999) - (b.admin?.order ?? 999));
+	return categories;
+}
+
+//#endregion
+export { getBlocksByCategory, introspectBlock, introspectBlocks };
+//# sourceMappingURL=introspection.mjs.map

package/dist/server/block/introspection.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.mjs","names":["schemas: Record<string, BlockSchema>","uncategorizedConfig: BlockCategoryConfig","key: string","config: BlockCategoryConfig"],"sources":["../../../src/server/block/introspection.ts"],"sourcesContent":["/**\n * Block Introspection\n *\n * Provides introspection of registered blocks for admin UI consumption.\n */\n\nimport type { FieldSchema } from \"questpie\";\nimport { type I18nText, isI18nLocaleMap } from \"questpie/shared\";\nimport type {\n\tAdminBlockConfig,\n\tBlockCategoryConfig,\n\tComponentReference,\n} from \"../augmentation.js\";\nimport type { AnyBlockDefinition, BlockBuilderState } from \"./block-builder.js\";\n\n// ============================================================================\n// Block Schema Types\n// ============================================================================\n\n/**\n * Introspected block schema for admin consumption.\n * All admin metadata comes from the .admin() configuration.\n */\nexport interface BlockSchema {\n\t/** Block type name */\n\tname: string;\n\n\t/** Admin configuration */\n\tadmin?: {\n\t\t/** Display label */\n\t\tlabel?: I18nText;\n\t\t/** Description */\n\t\tdescription?: I18nText;\n\t\t/** Icon reference */\n\t\ticon?: ComponentReference;\n\t\t/** Category for grouping in block picker */\n\t\tcategory?: BlockCategoryConfig;\n\t\t/** Order within category in block picker */\n\t\torder?: number;\n\t\t/** Hide from block picker */\n\t\thidden?: boolean;\n\t};\n\n\t/** Allow child blocks */\n\tallowChildren?: boolean;\n\n\t/** Maximum number of child blocks */\n\tmaxChildren?: number;\n\n\t/** Has prefetch function */\n\thasPrefetch: boolean;\n\n\t/** Field schemas - unified format using FieldSchema */\n\tfields: Record<string, FieldSchema>;\n\n\t/** Validation schemas */\n\tvalidation?: {\n\t\tinsert?: unknown;\n\t\tupdate?: unknown;\n\t};\n}\n\n/**\n * Category info extracted from blocks for UI rendering.\n */\nexport interface CategoryInfo {\n\t/** Category key (derived from label or auto-generated) */\n\tkey: string;\n\t/** Category configuration */\n\tconfig: BlockCategoryConfig;\n\t/** Blocks in this category */\n\tblocks: BlockSchema[];\n}\n\n// ============================================================================\n// Introspection Functions\n// ============================================================================\n\n/**\n * Introspect a single block definition.\n * Handles both server BlockBuilder definitions and client BlockDefinition objects\n * that were converted via the `.blocks()` patch.\n */\nexport function introspectBlock(blockDef: AnyBlockDefinition): BlockSchema {\n\tconst state = blockDef.state;\n\n\treturn {\n\t\tname: state.name ?? blockDef.name,\n\t\tadmin: state.admin,\n\t\tallowChildren: state.allowChildren,\n\t\tmaxChildren: state.maxChildren,\n\t\thasPrefetch: typeof state.prefetch === \"function\",\n\t\tfields: blockDef.getFieldMetadata(),\n\t};\n}\n\n/**\n * Introspect all registered blocks.\n *\n * @param blocks - Record of registered block definitions\n * @returns Record of block schemas\n *\n * @example\n * ```ts\n * import { introspectBlocks } from \"@questpie/admin/server\";\n *\n * // In an API route\n * const blocks = introspectBlocks(cms.state.blocks);\n * return Response.json({ blocks });\n * ```\n */\nexport function introspectBlocks(\n\tblocks: Record<string, AnyBlockDefinition> | undefined,\n): Record<string, BlockSchema> {\n\tif (!blocks) {\n\t\treturn {};\n\t}\n\n\tconst schemas: Record<string, BlockSchema> = {};\n\n\tfor (const [name, blockDef] of Object.entries(blocks)) {\n\t\tschemas[name] = introspectBlock(blockDef);\n\t}\n\n\treturn schemas;\n}\n\n/**\n * Generate a category key from category config.\n * Uses English label as key, falling back to first available label.\n */\nfunction getCategoryKey(category: BlockCategoryConfig): string {\n\tconst { label } = category;\n\n\tif (typeof label === \"string\") {\n\t\treturn label.toLowerCase().replace(/\\s+/g, \"-\");\n\t}\n\n\t// For locale map or translation key\n\tif (isI18nLocaleMap(label)) {\n\t\t// Use English label as key, or first available\n\t\tconst text = label.en ?? Object.values(label)[0] ?? \"\";\n\t\treturn text.toLowerCase().replace(/\\s+/g, \"-\");\n\t}\n\n\t// Translation key - use the key itself\n\treturn label.key.toLowerCase().replace(/[.:]/g, \"-\");\n}\n\n/**\n * Get blocks grouped by category with full category info.\n * Useful for block picker UI.\n */\nexport function getBlocksByCategory(\n\tblocks: Record<string, BlockSchema>,\n): CategoryInfo[] {\n\tconst categoryMap = new Map<string, CategoryInfo>();\n\n\t// Default uncategorized category\n\tconst uncategorizedKey = \"uncategorized\";\n\tconst uncategorizedConfig: BlockCategoryConfig = {\n\t\tlabel: { en: \"Uncategorized\" },\n\t\torder: 999,\n\t};\n\n\tfor (const block of Object.values(blocks)) {\n\t\t// Skip hidden blocks\n\t\tif (block.admin?.hidden) continue;\n\n\t\tconst categoryConfig = block.admin?.category;\n\t\tlet key: string;\n\t\tlet config: BlockCategoryConfig;\n\n\t\tif (categoryConfig) {\n\t\t\tkey = getCategoryKey(categoryConfig);\n\t\t\tconfig = categoryConfig;\n\t\t} else {\n\t\t\tkey = uncategorizedKey;\n\t\t\tconfig = uncategorizedConfig;\n\t\t}\n\n\t\tif (!categoryMap.has(key)) {\n\t\t\tcategoryMap.set(key, {\n\t\t\t\tkey,\n\t\t\t\tconfig,\n\t\t\t\tblocks: [],\n\t\t\t});\n\t\t}\n\n\t\tcategoryMap.get(key)!.blocks.push(block);\n\t}\n\n\t// Convert to array and sort\n\tconst categories = Array.from(categoryMap.values());\n\n\t// Sort categories by order\n\tcategories.sort((a, b) => (a.config.order ?? 999) - (b.config.order ?? 999));\n\n\t// Sort blocks within each category by order\n\tfor (const category of categories) {\n\t\tcategory.blocks.sort(\n\t\t\t(a, b) => (a.admin?.order ?? 999) - (b.admin?.order ?? 999),\n\t\t);\n\t}\n\n\treturn categories;\n}\n"],"mappings":";;;;;;;;AAmFA,SAAgB,gBAAgB,UAA2C;CAC1E,MAAM,QAAQ,SAAS;AAEvB,QAAO;EACN,MAAM,MAAM,QAAQ,SAAS;EAC7B,OAAO,MAAM;EACb,eAAe,MAAM;EACrB,aAAa,MAAM;EACnB,aAAa,OAAO,MAAM,aAAa;EACvC,QAAQ,SAAS,kBAAkB;EACnC;;;;;;;;;;;;;;;;;AAkBF,SAAgB,iBACf,QAC8B;AAC9B,KAAI,CAAC,OACJ,QAAO,EAAE;CAGV,MAAMA,UAAuC,EAAE;AAE/C,MAAK,MAAM,CAAC,MAAM,aAAa,OAAO,QAAQ,OAAO,CACpD,SAAQ,QAAQ,gBAAgB,SAAS;AAG1C,QAAO;;;;;;AAOR,SAAS,eAAe,UAAuC;CAC9D,MAAM,EAAE,UAAU;AAElB,KAAI,OAAO,UAAU,SACpB,QAAO,MAAM,aAAa,CAAC,QAAQ,QAAQ,IAAI;AAIhD,KAAI,gBAAgB,MAAM,CAGzB,SADa,MAAM,MAAM,OAAO,OAAO,MAAM,CAAC,MAAM,IACxC,aAAa,CAAC,QAAQ,QAAQ,IAAI;AAI/C,QAAO,MAAM,IAAI,aAAa,CAAC,QAAQ,SAAS,IAAI;;;;;;AAOrD,SAAgB,oBACf,QACiB;CACjB,MAAM,8BAAc,IAAI,KAA2B;CAGnD,MAAM,mBAAmB;CACzB,MAAMC,sBAA2C;EAChD,OAAO,EAAE,IAAI,iBAAiB;EAC9B,OAAO;EACP;AAED,MAAK,MAAM,SAAS,OAAO,OAAO,OAAO,EAAE;AAE1C,MAAI,MAAM,OAAO,OAAQ;EAEzB,MAAM,iBAAiB,MAAM,OAAO;EACpC,IAAIC;EACJ,IAAIC;AAEJ,MAAI,gBAAgB;AACnB,SAAM,eAAe,eAAe;AACpC,YAAS;SACH;AACN,SAAM;AACN,YAAS;;AAGV,MAAI,CAAC,YAAY,IAAI,IAAI,CACxB,aAAY,IAAI,KAAK;GACpB;GACA;GACA,QAAQ,EAAE;GACV,CAAC;AAGH,cAAY,IAAI,IAAI,CAAE,OAAO,KAAK,MAAM;;CAIzC,MAAM,aAAa,MAAM,KAAK,YAAY,QAAQ,CAAC;AAGnD,YAAW,MAAM,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,EAAE,OAAO,SAAS,KAAK;AAG5E,MAAK,MAAM,YAAY,WACtB,UAAS,OAAO,MACd,GAAG,OAAO,EAAE,OAAO,SAAS,QAAQ,EAAE,OAAO,SAAS,KACvD;AAGF,QAAO"}

package/dist/server/block/prefetch.d.mts

@@ -0,0 +1,78 @@
+import { AnyBlockDefinition } from "./block-builder.mjs";
+import { BlocksDocument } from "../fields/blocks.mjs";
+import { RegisteredApp } from "questpie";
+
+//#region src/server/block/prefetch.d.ts
+
+/**
+ * Context for blocks prefetch processing.
+ * Typed via Register.app when registered.
+ */
+interface BlocksPrefetchContext {
+  /** CMS app instance — typed via Register.app */
+  app: RegisteredApp;
+  /** Database client */
+  db: unknown;
+  /** Current locale */
+  locale?: string;
+}
+/**
+ * Process blocks data for a single blocks document.
+ *
+ * This function does two things:
+ * 1. **Expands declared fields** from `.prefetch({ with: [...] })` (batch-fetched)
+ * 2. **Executes prefetch functions/loaders** for blocks that have them
+ *
+ * The results are merged into `_data[blockId]`. Prefetch function / loader data
+ * takes precedence over expanded data on key conflicts.
+ *
+ * @param blocks - The blocks document to process
+ * @param blockDefinitions - Registered block definitions
+ * @param ctx - Prefetch context
+ * @returns The blocks document with `_data` populated
+ */
+declare function processBlocksDocument(blocks: BlocksDocument | null | undefined, blockDefinitions: Record<string, AnyBlockDefinition>, ctx: BlocksPrefetchContext): Promise<BlocksDocument | null | undefined>;
+/**
+ * Process blocks prefetch for a document.
+ * Finds all blocks fields in the document and processes them.
+ *
+ * @param doc - The document containing blocks fields
+ * @param fieldDefinitions - Field definitions to identify blocks fields
+ * @param blockDefinitions - Registered block definitions
+ * @param ctx - Prefetch context
+ * @returns The document with blocks prefetch data attached
+ */
+declare function processDocumentBlocksPrefetch<T extends Record<string, unknown>>(doc: T, fieldDefinitions: Record<string, {
+  state: {
+    config: {
+      type?: string;
+    };
+  };
+}>, blockDefinitions: Record<string, AnyBlockDefinition>, ctx: BlocksPrefetchContext): Promise<T>;
+/**
+ * Create an afterRead hook for processing blocks prefetch.
+ * This hook can be added to collections that have blocks fields.
+ *
+ * @example
+ * ```ts
+ * import { createBlocksPrefetchHook } from "@questpie/admin/server";
+ *
+ * const pages = q.collection("pages")
+ *   .fields((f) => ({
+ *     title: f.text({ required: true }),
+ *     content: f.blocks({ allowedBlocks: ["hero", "text"] }),
+ *   }))
+ *   .hooks({
+ *     afterRead: createBlocksPrefetchHook(),
+ *   });
+ * ```
+ */
+declare function createBlocksPrefetchHook(): (ctx: {
+  data: Record<string, unknown>;
+  app: any;
+  db: unknown;
+  locale?: string;
+}) => Promise<void>;
+//#endregion
+export { BlocksPrefetchContext, createBlocksPrefetchHook, processBlocksDocument, processDocumentBlocksPrefetch };
+//# sourceMappingURL=prefetch.d.mts.map

package/dist/server/block/prefetch.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefetch.d.mts","names":[],"sources":["../../../src/server/block/prefetch.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;UAiDiB,qBAAA;;OAEX;;;;;;;;;;;;;;;;;;;;;iBAoNgB,qBAAA,SACb,qDACU,eAAe,0BAC5B,wBACH,QAAQ;;;;;;;;;;;iBAuJW,wCACX,8BAEL,qBACa;;;;;;sBACA,eAAe,0BAC5B,wBACH,QAAQ;;;;;;;;;;;;;;;;;;;iBAyCK,wBAAA,CAAA;QAER;;;;MAIN"}