create-questpie 2.0.0 → 2.0.1

package/dist/index.mjs

@@ -179,7 +179,7 @@ function isTextFile(filename) {
 	return TEXT_EXTENSIONS.has(ext);
 }
 async function replaceInFile(filePath, vars) {
-	const content = await readFile(filePath, "utf-8");
+	const content = (await readFile(filePath)).toString("utf-8");
 	const replaced = content.replace(TEMPLATE_VAR_REGEX, (match, key) => {
 		return key in vars ? vars[key] : match;
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-questpie",
-	"version": "2.0.0",
+	"version": "2.0.1",
 	"description": "Create a new QUESTPIE project",
 	"keywords": [
 		"create",

package/templates/tanstack-start/AGENTS.md

@@ -115,8 +115,8 @@ src/
 - **`src/questpie/server/questpie.config.ts`** — App config: `runtimeConfig({ db, app, ... })`.
 - **`src/questpie/server/modules.ts`** — Module dependencies: `export default [adminModule, openApiModule] as const`.
 - **`src/questpie/server/config/auth.ts`** — Auth config via `authConfig()` factory.
-- **`src/questpie/server/config/app.ts`** — App config (locale, access, hooks, context) via `appConfig()` factory.
 - **`src/questpie/server/config/admin.ts`** — Admin config (sidebar, dashboard, branding, locale) via `adminConfig()` factory.
+- **`src/questpie/server/config/app.ts`** — *(optional, not scaffolded)* App config (locale, access, hooks, context) via `appConfig()`. Create when needed.
 - **`src/questpie/server/config/openapi.ts`** — OpenAPI config via `openApiConfig()` factory.
 - **`src/questpie/server/.generated/index.ts`** — Codegen output. Exports typed `app` instance and `App` type. Run `bunx questpie generate` to regenerate.
 - **`src/questpie/admin/.generated/client.ts`** — Codegen output: pre-built admin client config. Run `bunx questpie generate` to regenerate.
@@ -132,7 +132,7 @@ Keep the entire builder chain in one file — single source of truth per entity:
 
 ```ts
 // src/questpie/server/collections/posts.ts
-import { collection } from "questpie";
+import { collection } from "#questpie/factories";
 
 export const posts = collection("posts")
 	.fields(({ f }) => ({
@@ -154,10 +154,13 @@ export const posts = collection("posts")
 		content: f.richText().label("Content"),
 		published: f.boolean().label("Published").default(false),
 		category: f
-			.select()
+			.select([
+				{ value: "news", label: "News" },
+				{ value: "blog", label: "Blog" },
+				{ value: "tutorial", label: "Tutorial" },
+			])
 			.label("Category")
-			.options(["news", "blog", "tutorial"]),
-		author: f.relation().label("Author").to("users"),
+		author: f.relation("users").label("Author"),
 		image: f.upload().label("Cover Image"),
 	}))
 	.title(({ f }) => f.title)
@@ -209,9 +212,9 @@ Collections are auto-discovered by codegen — no manual registration needed.
 
 ```ts
 // src/questpie/server/globals/site-settings.ts
-import { global } from "questpie";
+import { global } from "#questpie/factories";
 
-export const siteSettings = global("site_settings")
+export const siteSettings = global("siteSettings")
 	.fields(({ f }) => ({
 		siteName: f.text(255).label("Site Name").required(),
 		description: f.textarea().label("Description"),
@@ -390,10 +393,9 @@ All reactive handlers run **server-side** with access to `ctx.db`, `ctx.user`, `
 
 ```ts
 fields: ({ f }) => ({
-	country: f.relation().to("countries").label("Country"),
+	country: f.relation("countries").label("Country"),
 	city: f
-		.relation()
-		.to("cities")
+		.relation("cities")
 		.label("City")
 		.admin({
 			options: {
@@ -409,9 +411,12 @@ fields: ({ f }) => ({
 			},
 		}),
 	status: f
-		.select()
+		.select([
+			{ value: "draft", label: "Draft" },
+			{ value: "published", label: "Published" },
+			{ value: "archived", label: "Archived" },
+		])
 		.label("Status")
-		.options(["draft", "published", "archived"]),
 	publishedAt: f
 		.datetime()
 		.label("Published At")
@@ -458,7 +463,7 @@ import { app } from "#questpie";
 const handler = createFetchHandler(app, { basePath: "/api" });
 ```
 
-OpenAPI is registered as a module in `src/questpie/server/modules.ts` via `openApiModule()` — no wrapper needed in the route handler.
+OpenAPI is registered as a module in `src/questpie/server/modules.ts` via `openApiModule` — no wrapper needed in the route handler.
 
 ### Icons
 
@@ -525,15 +530,14 @@ Always use these exact versions — check `package.json` before upgrading:
 
 ## Live Preview
 
-QUESTPIE supports live preview with a split-screen editor. The preview architecture uses a direct `postMessage` patch bus for instant feedback — NOT save-driven iframe reloads.
+QUESTPIE supports live preview with a split-screen editor. The current implementation refreshes the preview iframe after save/autosave and uses `postMessage` for field/block focus sync.
 
 ### Key Principles
 
-- **Same-tab preview** = direct patch bus via `postMessage` (editor iframe and preview share the same browser tab)
-- **Save/autosave** = persistence only, NOT the live transport mechanism
-- **Realtime** = extension for detached/shared preview only (e.g., another browser tab or collaborator)
-- **Hybrid model**: local draft patches give instant response; server reconciles derived data (slugs, relations, computed fields)
-- **Preview wrappers must prevent accidental navigation** inside the iframe
+- **Same-tab preview** = iframe refresh after save/autosave plus `postMessage` focus events
+- **Frontend hook** = `useCollectionPreview({ initialData, onRefresh })`
+- **Field focus** = `PreviewProvider` + `PreviewField`
+- **Block field paths** = `BlockScopeProvider` + `PreviewField`
 
 ### Server Config
 
@@ -541,7 +545,7 @@ Add `.preview()` to a collection to enable the split-screen editor:
 
 ```ts
 // src/questpie/server/collections/pages.ts
-import { collection } from "questpie";
+import { collection } from "#questpie/factories";
 
 export const pages = collection("pages")
 	.fields(({ f }) => ({
@@ -550,62 +554,63 @@ export const pages = collection("pages")
 		content: f.blocks().label("Content"),
 	}))
 	.preview({
+		enabled: true,
+		position: "right",
+		defaultWidth: 50,
 		url: ({ record }) => {
 			const slug = record.slug as string;
 			return slug === "home" ? "/?preview=true" : `/${slug}?preview=true`;
 		},
-		watch: ["title", "slug", "content"],
-		strategy: "hybrid", // "instant" | "server" | "hybrid"
 	});
 ```
 
-| Strategy    | Behavior                                                                 |
-| ----------- | ------------------------------------------------------------------------ |
-| `"instant"` | Patches applied locally only — no server round-trip                      |
-| `"server"`  | Every change round-trips through the server before preview updates       |
-| `"hybrid"`  | Local patches for instant response + server reconcile for derived fields |
-
 ### Frontend Integration
 
-Use `useQuestpiePreview` in your frontend page components to receive live patches:
+Use `useCollectionPreview` in your frontend page components:
 
 ```tsx
 // src/routes/[slug].tsx
-import { useQuestpiePreview } from "@questpie/admin/client";
+import {
+	PreviewField,
+	PreviewProvider,
+	useCollectionPreview,
+} from "@questpie/admin/client";
 
 function PageComponent({ initialData }) {
 	const router = useRouter();
-	const { data } = useQuestpiePreview({
+	const preview = useCollectionPreview({
 		initialData,
-		reconcile: () => router.invalidate(), // called on COMMIT — refetch server data
+		onRefresh: () => router.invalidate(),
 	});
 
 	return (
-		<PreviewRoot>
-			<h1>
-				<PreviewField path="title">{data.title}</PreviewField>
-			</h1>
-			<PreviewBlock id="content">{/* block renderers */}</PreviewBlock>
-		</PreviewRoot>
+		<PreviewProvider
+			isPreviewMode={preview.isPreviewMode}
+			focusedField={preview.focusedField}
+			onFieldClick={preview.handleFieldClick}
+		>
+			<PreviewField field="title" as="h1">
+				{preview.data.title}
+			</PreviewField>
+		</PreviewProvider>
 	);
 }
 ```
 
 #### Protocol
 
-Each `postMessage` carries a structured envelope:
+The implemented preview messages are simple `postMessage` events:
 
-| Field             | Description                            |
-| ----------------- | -------------------------------------- |
-| `sessionId`       | Unique preview session identifier      |
-| `seq`             | Monotonic sequence number              |
-| `timestamp`       | `Date.now()` at send time (number)     |
-| `protocolVersion` | Protocol version for forward compat    |
-| `patches`         | Array of field path + value patch ops  |
+| Field             | Description                             |
+| ----------------- | --------------------------------------- |
+| `PREVIEW_READY`   | Preview iframe tells admin it is ready  |
+| `PREVIEW_REFRESH` | Admin asks iframe to refresh data       |
+| `FIELD_CLICKED`   | Preview asks admin to focus a field     |
+| `BLOCK_CLICKED`   | Preview asks admin to select a block    |
+| `FOCUS_FIELD`     | Admin asks preview to highlight a field |
+| `SELECT_BLOCK`    | Admin asks preview to highlight a block |
 
 ### Anti-Patterns (Preview)
 
-- **Using `router.invalidate()` as the core live-preview mechanism** — this causes full data refetches and visible flicker. Use the patch bus instead.
-- **Tying preview freshness to save/autosave** — save is for persistence. Preview updates flow through `postMessage` patches.
-- **Using realtime transport for same-tab preview** — realtime (SSE/WebSocket) is for detached or shared preview sessions, not the default same-tab flow.
-- **Allowing navigation inside the preview iframe** — preview wrappers must intercept link clicks and route changes to prevent the iframe from navigating away.
+- **Using V2-only APIs in this template** — `useQuestpiePreview`, `PreviewRoot`, and `PreviewBlock` are not exported yet.
+- **Importing `app` inside previewed collection/block files** — use handler `ctx` values to avoid generated-app cycles.

package/templates/tanstack-start/CLAUDE.md

@@ -4,18 +4,18 @@ This is a [QUESTPIE](https://questpie.com) project scaffolded with `create-quest
 
 ## Quick Reference
 
-| Command                              | Purpose                                  |
-| ------------------------------------ | ---------------------------------------- |
-| `bun dev`                            | Start dev server (port 3000)             |
-| `bun build`                          | Build for production                     |
-| `bun start`                          | Start production server                  |
-| `bun questpie add <type> <name>`     | Scaffold a new entity (collection, seed, etc.) |
-| `bun questpie add --list`            | List all available scaffold types        |
-| `bun questpie generate`              | Regenerate .generated/index.ts           |
-| `bun questpie migrate:create`        | Generate a migration from schema diff    |
-| `bun questpie migrate`               | Run pending migrations                   |
-| `bun questpie seed`                  | Run pending seeds                        |
-| `docker compose up -d`               | Start PostgreSQL                         |
+| Command                          | Purpose                                        |
+| -------------------------------- | ---------------------------------------------- |
+| `bun dev`                        | Start dev server (port 3000)                   |
+| `bun build`                      | Build for production                           |
+| `bun start`                      | Start production server                        |
+| `bun questpie add <type> <name>` | Scaffold a new entity (collection, seed, etc.) |
+| `bun questpie add --list`        | List all available scaffold types              |
+| `bun questpie generate`          | Regenerate .generated/index.ts                 |
+| `bun questpie migrate:create`    | Generate a migration from schema diff          |
+| `bun questpie migrate`           | Run pending migrations                         |
+| `bun questpie seed`              | Run pending seeds                              |
+| `docker compose up -d`           | Start PostgreSQL                               |
 
 ## Project Architecture
 
@@ -31,9 +31,9 @@ src/questpie/
     modules.ts         ← Module dependencies (adminModule, openApiModule, etc.)
     config/            ← Typed configuration files
       auth.ts          ← authConfig({...}) — Better Auth options
-      app.ts           ← appConfig({ locale, access, hooks, context })
       admin.ts         ← adminConfig({ sidebar, dashboard, branding, locale })
       openapi.ts       ← openApiConfig({ info, scalar })
+      app.ts           ← (optional) appConfig({ locale, access, hooks, context })
     .generated/        ← Codegen output (app instance + App type)
       index.ts
     collections/       ← One file per collection (auto-discovered)
@@ -52,8 +52,8 @@ src/questpie/
 - **`src/questpie/server/questpie.config.ts`** — App config: `runtimeConfig({ db, app, ... })`.
 - **`src/questpie/server/modules.ts`** — Module dependencies: `export default [adminModule, openApiModule] as const`.
 - **`src/questpie/server/config/auth.ts`** — Auth config via `authConfig()` factory.
-- **`src/questpie/server/config/app.ts`** — App config (locale, access, hooks, context) via `appConfig()` factory.
 - **`src/questpie/server/config/admin.ts`** — Admin config (sidebar, dashboard, branding, locale) via `adminConfig()` factory.
+- **`src/questpie/server/config/app.ts`** — *(optional, not scaffolded)* App config (locale, access, hooks, context) via `appConfig()`. Create when needed.
 - **`src/questpie/server/.generated/index.ts`** — Codegen output. Exports typed `app` instance and `App` type. Run `bunx questpie generate` to regenerate.
 - **`src/lib/env.ts`** — Type-safe env variables via `@t3-oss/env-core`. Add new env vars here with Zod schemas.
 - **`questpie.config.ts`** — CLI config (migration directory, app reference).
@@ -87,7 +87,7 @@ Manual workflow:
 
 1. Create `src/questpie/server/collections/my-thing.ts` with a named export:
    ```ts
-   import { collection } from "questpie";
+   import { collection } from "#questpie/factories";
    export const myThing = collection("my-thing").fields(({ f }) => ({ ... }));
    ```
 2. Run `bunx questpie generate` to regenerate `.generated/index.ts`

package/templates/tanstack-start/README.md

@@ -33,6 +33,10 @@ src/
     server/
       questpie.config.ts             # Runtime config
       modules.ts                     # Module list (admin/openapi/...)
+      config/
+        admin.ts                     # Admin sidebar/dashboard/branding
+        auth.ts                      # Auth config
+        openapi.ts                   # OpenAPI/Scalar config
       app.ts                         # Re-export of generated app
       .generated/                    # Codegen output (do not edit manually)
       collections/
@@ -41,6 +45,8 @@ src/
         site-settings.global.ts
     admin/
       admin.ts                       # Re-export of generated admin config
+      modules.ts                     # Admin client module defaults
+      .generated/                    # Admin client codegen output
   routes/
     api/$.ts                         # QUESTPIE fetch handler mount
     admin.tsx
@@ -55,16 +61,16 @@ migrations/
 
 ## Scripts
 
-| Command                       | Description                                   |
-| ----------------------------- | --------------------------------------------- |
-| `bun dev`                     | Start development server                      |
-| `bun build`                   | Build for production                          |
-| `bun start`                   | Start production server                       |
-| `bun check-types`             | Type check                                    |
-| `bun questpie add <type> <name>` | Scaffold entity files (auto-runs codegen) |
-| `bun questpie migrate`        | Run migrations                                |
-| `bun questpie migrate:create` | Create migration                              |
-| `bunx questpie generate`      | Regenerate `src/questpie/server/.generated/*` |
+| Command                          | Description                                   |
+| -------------------------------- | --------------------------------------------- |
+| `bun dev`                        | Start development server                      |
+| `bun build`                      | Build for production                          |
+| `bun start`                      | Start production server                       |
+| `bun check-types`                | Type check                                    |
+| `bun questpie add <type> <name>` | Scaffold entity files (auto-runs codegen)     |
+| `bun questpie migrate`           | Run migrations                                |
+| `bun questpie migrate:create`    | Create migration                              |
+| `bunx questpie generate`         | Regenerate `src/questpie/server/.generated/*` |
 
 ## Adding a Collection
 

package/templates/tanstack-start/src/lib/client.ts

@@ -1,8 +1,8 @@
 import { createClient } from "questpie/client";
 
-import type { AppConfig, AppRpc } from "@/questpie/server/app.js";
+import type { AppConfig } from "@/questpie/server/app.js";
 
-export const client = createClient<AppConfig, AppRpc>({
+export const client = createClient<AppConfig>({
 	baseURL:
 		typeof window !== "undefined"
 			? window.location.origin

package/templates/tanstack-start/src/questpie/admin/.generated/client.ts

@@ -0,0 +1,13 @@
+/**
+ * Admin Client Config
+ *
+ * Auto-generated by questpie codegen — do not edit.
+ *
+ * Pass this directly to <AdminLayoutProvider admin={admin} />
+ */
+
+import { default as _modules } from "../modules";
+
+const admin = _modules;
+
+export default admin;

package/templates/tanstack-start/src/questpie/admin/modules.ts

@@ -0,0 +1 @@
+export { default } from "@questpie/admin/client-module";

package/templates/tanstack-start/src/questpie/server/.generated/factories.ts

@@ -3,63 +3,51 @@
 // Typed factory functions with plugin extensions. Regenerate with: questpie generate
 
 // ── Core Imports ───────────────────────────────────────────
-import {
-	type CollectionAccess,
-	CollectionBuilder,
-	type ContextResolver,
-	createFieldNameProxy,
-	type EmptyCollectionState,
-	type EmptyGlobalState,
-	GlobalBuilder,
-	type GlobalHooksInput,
-	type LocaleConfig,
-	wrapBuilderWithExtensions,
-} from "questpie";
-import type { RegistryProp } from "questpie";
+import { CollectionBuilder, GlobalBuilder, wrapBuilderWithExtensions, builtinFields, type EmptyCollectionState, type EmptyGlobalState, type BuiltinFields, Field } from "questpie";
+
+// ── Runtime Field Imports ──────────────────────────────────
+import { adminFields } from "@questpie/admin/server";
+
+const _fieldExt: Record<string, { stateKey: string; resolve: (v: any) => any }> = {
+	admin: { stateKey: "admin", resolve: (v: any) => v },
+	form: {
+		stateKey: "form",
+		resolve(configOrFn: any) {
+			if (typeof configOrFn === 'function') return configOrFn({ f: createFieldNameProxy() });
+			return configOrFn;
+		},
+	},
+};
+
+// Merged field factories — builtins + module-contributed (e.g. richText, blocks) + user fields
+const _rawFieldDefs = { ...builtinFields, ...adminFields } as const;
+
+// Wrap field factories so returned Field instances have extension methods
+function _wrapFieldFactory(fn: (...args: any[]) => any): (...args: any[]) => any {
+	return (...args: any[]) => wrapBuilderWithExtensions(fn(...args), _fieldExt, Field);
+}
+
+const _allFieldDefs = Object.fromEntries(
+	Object.entries(_rawFieldDefs).map(([k, v]) => [k, _wrapFieldFactory(v as any)])
+) as unknown as typeof _rawFieldDefs;
 
 // ── Plugin Imports ─────────────────────────────────────────
-import {
-	type ActionsConfigContext,
-	type AdminCollectionConfig,
-	type AdminConfigContext,
-	type AdminGlobalConfig,
-	type AdminLocaleConfig,
-	createActionCallbackProxy,
-	createComponentCallbackProxy,
-	createViewCallbackProxy,
-	type DashboardContribution,
-	type FilterViewsByKind,
-	type FormViewConfig,
-	type FormViewConfigContext,
-	type ListViewConfig,
-	type ListViewConfigContext,
-	type PreviewConfig,
-	type ServerActionsConfig,
-	type ServerBrandingConfig,
-	type SidebarContribution,
-} from "@questpie/admin/server";
+import { type AdminCollectionConfig, type AdminConfigContext, type ListViewConfig, type ListViewConfigContext, type FilterViewsByKind, type FormViewConfig, type FormViewConfigContext, type PreviewConfig, type ServerActionsConfig, type ActionsConfigContext, type AdminGlobalConfig, type AdminConfigInput, createViewCallbackProxy, createComponentCallbackProxy, createActionCallbackProxy } from "@questpie/admin/server";
+import { type AppConfigInput, type AuthConfig, createFieldNameProxy } from "questpie";
+import { type OpenApiModuleConfig } from "@questpie/openapi";
+
 // ════════════════════════════════════════════════════════════
-// Type extraction from Registry — driven by CategoryDeclaration
+// Type extraction — driven by CategoryDeclaration
 // ════════════════════════════════════════════════════════════
 
-// ── Module import (for type extraction) ──
-import type _modulesArr from "../modules";
-
-type _ViewsNames = (keyof RegistryProp<"views"> & string) | (string & {});
-type _ViewsRecord = RegistryProp<"views">;
-type _ComponentsNames =
-	| (keyof RegistryProp<"components"> & string)
-	| (string & {});
-type _ComponentsNames_Strict = keyof RegistryProp<"components"> & string;
-type _ComponentsRecord = RegistryProp<"components">;
+type _ViewsNames = (keyof Questpie.ViewsRegistry & string) | (string & {});
+type _ViewsRecord = Questpie.ViewsRegistry;
+type _ComponentsNames = (keyof Questpie.ComponentsRegistry & string) | (string & {});
+type _ComponentsNames_Strict = keyof Questpie.ComponentsRegistry & string;
+type _ComponentsRecord = Questpie.ComponentsRegistry;
 
-// Field types — extracted from modules
-import type { ExtractModuleProp } from "questpie";
-
-type _AllFieldTypes = ExtractModuleProp<
-	{ modules: typeof _modulesArr },
-	"fields"
->;
+// Field types — populated by module codegen via Questpie.FieldTypesMap
+type _AllFieldTypes = Questpie.FieldTypesMap;
 
 // ════════════════════════════════════════════════════════════
 // Type augmentations — generated from plugin registries
@@ -67,67 +55,25 @@ type _AllFieldTypes = ExtractModuleProp<
 
 declare module "questpie" {
 	interface CollectionBuilder<TState> {
-		admin(
-			configFn:
-				| AdminCollectionConfig
-				| ((
-						ctx: AdminConfigContext<_ComponentsRecord>,
-				  ) => AdminCollectionConfig),
-		): CollectionBuilder<TState>;
-		list(
-			configFn: (
-				ctx: ListViewConfigContext<
-					TState extends {
-						fieldDefinitions: infer F extends Record<string, any>;
-					}
-						? F
-						: Record<string, any>,
-					FilterViewsByKind<_ViewsRecord, "list">
-				>,
-			) => ListViewConfig,
-		): CollectionBuilder<TState>;
-		form(
-			configFn: (
-				ctx: FormViewConfigContext<
-					TState extends {
-						fieldDefinitions: infer F extends Record<string, any>;
-					}
-						? F
-						: Record<string, any>,
-					FilterViewsByKind<_ViewsRecord, "form">
-				>,
-			) => FormViewConfig,
-		): CollectionBuilder<TState>;
+		admin(configFn: AdminCollectionConfig | ((ctx: AdminConfigContext<_ComponentsRecord>) => AdminCollectionConfig)): CollectionBuilder<TState>;
+		list(configFn: (ctx: ListViewConfigContext<TState extends { fieldDefinitions: infer F extends Record<string, any> } ? F : Record<string, any>, FilterViewsByKind<_ViewsRecord, "list">>) => ListViewConfig): CollectionBuilder<TState>;
+		form(configFn: (ctx: FormViewConfigContext<TState extends { fieldDefinitions: infer F extends Record<string, any> } ? F : Record<string, any>, FilterViewsByKind<_ViewsRecord, "form">>) => FormViewConfig): CollectionBuilder<TState>;
 		preview(config: PreviewConfig): CollectionBuilder<TState>;
-		actions(
-			configFn: (
-				ctx: ActionsConfigContext<Record<string, unknown>, _ComponentsRecord>,
-			) => ServerActionsConfig,
-		): CollectionBuilder<TState>;
+		actions(configFn: (ctx: ActionsConfigContext<Record<string, unknown>, _ComponentsRecord>) => ServerActionsConfig): CollectionBuilder<TState>;
 	}
 	interface GlobalBuilder<TState> {
-		admin(
-			configFn:
-				| AdminGlobalConfig
-				| ((ctx: AdminConfigContext<_ComponentsRecord>) => AdminGlobalConfig),
-		): GlobalBuilder<TState>;
-		form(
-			configFn: (
-				ctx: FormViewConfigContext<
-					TState extends {
-						fieldDefinitions: infer F extends Record<string, any>;
-					}
-						? F
-						: Record<string, any>,
-					FilterViewsByKind<_ViewsRecord, "form">
-				>,
-			) => FormViewConfig,
-		): GlobalBuilder<TState>;
+		admin(configFn: AdminGlobalConfig | ((ctx: AdminConfigContext<_ComponentsRecord>) => AdminGlobalConfig)): GlobalBuilder<TState>;
+		form(configFn: (ctx: FormViewConfigContext<TState extends { fieldDefinitions: infer F extends Record<string, any> } ? F : Record<string, any>, FilterViewsByKind<_ViewsRecord, "form">>) => FormViewConfig): GlobalBuilder<TState>;
+	}
+	interface Field<TState> {
+		admin(config: unknown): Field<TState>;
+		form(configFn: (ctx: { f: Record<string, string> }) => { fields: import('@questpie/admin/server').FieldLayoutItem[] }): Field<TState>;
 	}
 }
 
 declare global {
 	namespace Questpie {
+		interface FieldTypesMap extends BuiltinFields {}
 		interface FieldTypeRegistry extends Record<keyof _AllFieldTypes, {}> {}
 	}
 }
@@ -140,90 +86,54 @@ declare module "@questpie/admin/server" {
 // Extension registries
 // ════════════════════════════════════════════════════════════
 
-const _collExt: Record<string, { stateKey: string; resolve: (v: any) => any }> =
-	{
-		admin: {
-			stateKey: "admin",
-			resolve(configOrFn: any) {
-				if (typeof configOrFn === "function")
-					return configOrFn({ c: createComponentCallbackProxy() });
-				return configOrFn;
-			},
+const _collExt: Record<string, { stateKey: string; resolve: (v: any) => any }> = {
+	admin: {
+		stateKey: "admin",
+		resolve(configOrFn: any) {
+			if (typeof configOrFn === 'function') return configOrFn({ c: createComponentCallbackProxy() });
+			return configOrFn;
 		},
-		list: {
-			stateKey: "adminList",
-			resolve(configOrFn: any) {
-				const resolved =
-					typeof configOrFn === "function"
-						? configOrFn({
-								v: createViewCallbackProxy(),
-								f: createFieldNameProxy(),
-								a: createActionCallbackProxy(),
-							})
-						: configOrFn;
-				return {
-					...{
-						view: "collection-table",
-						showSearch: true,
-						showFilters: true,
-						showToolbar: true,
-					},
-					...resolved,
-				};
-			},
+	},
+	list: {
+		stateKey: "adminList",
+		resolve(configOrFn: any) {
+			const resolved = typeof configOrFn === 'function' ? configOrFn({ v: createViewCallbackProxy(), f: createFieldNameProxy(), a: createActionCallbackProxy() }) : configOrFn;
+			return { ...{"view":"collection-table","showSearch":true,"showFilters":true,"showToolbar":true}, ...resolved };
 		},
-		form: {
-			stateKey: "adminForm",
-			resolve(configOrFn: any) {
-				const resolved =
-					typeof configOrFn === "function"
-						? configOrFn({
-								v: createViewCallbackProxy(),
-								f: createFieldNameProxy(),
-							})
-						: configOrFn;
-				return { ...{ view: "collection-form", showMeta: true }, ...resolved };
-			},
+	},
+	form: {
+		stateKey: "adminForm",
+		resolve(configOrFn: any) {
+			const resolved = typeof configOrFn === 'function' ? configOrFn({ v: createViewCallbackProxy(), f: createFieldNameProxy() }) : configOrFn;
+			return { ...{"view":"collection-form","showMeta":true}, ...resolved };
 		},
-		preview: { stateKey: "adminPreview", resolve: (v: any) => v },
-		actions: {
-			stateKey: "adminActions",
-			resolve(configOrFn: any) {
-				if (typeof configOrFn === "function")
-					return configOrFn({
-						a: createActionCallbackProxy(),
-						c: createComponentCallbackProxy(),
-						f: createFieldNameProxy(),
-					});
-				return configOrFn;
-			},
+	},
+	preview: { stateKey: "adminPreview", resolve: (v: any) => v },
+	actions: {
+		stateKey: "adminActions",
+		resolve(configOrFn: any) {
+			if (typeof configOrFn === 'function') return configOrFn({ a: createActionCallbackProxy(), c: createComponentCallbackProxy(), f: createFieldNameProxy() });
+			return configOrFn;
 		},
-	};
-
-const _globExt: Record<string, { stateKey: string; resolve: (v: any) => any }> =
-	{
-		admin: {
-			stateKey: "admin",
-			resolve(configOrFn: any) {
-				if (typeof configOrFn === "function")
-					return configOrFn({ c: createComponentCallbackProxy() });
-				return configOrFn;
-			},
+	},
+};
+
+const _globExt: Record<string, { stateKey: string; resolve: (v: any) => any }> = {
+	admin: {
+		stateKey: "admin",
+		resolve(configOrFn: any) {
+			if (typeof configOrFn === 'function') return configOrFn({ c: createComponentCallbackProxy() });
+			return configOrFn;
 		},
-		form: {
-			stateKey: "adminForm",
-			resolve(configOrFn: any) {
-				const resolved =
-					typeof configOrFn === "function"
-						? configOrFn({
-								v: createViewCallbackProxy(),
-								f: createFieldNameProxy(),
-							})
-						: configOrFn;
-				return { ...{ view: "global-form", showMeta: true }, ...resolved };
-			},
+	},
+	form: {
+		stateKey: "adminForm",
+		resolve(configOrFn: any) {
+			const resolved = typeof configOrFn === 'function' ? configOrFn({ v: createViewCallbackProxy(), f: createFieldNameProxy() }) : configOrFn;
+			return { ...{"view":"global-form","showMeta":true}, ...resolved };
 		},
-	};
+	},
+};
 
 // ════════════════════════════════════════════════════════════
 // Factory functions
@@ -237,82 +147,48 @@ const _globExt: Record<string, { stateKey: string; resolve: (v: any) => any }> =
  * import { collection } from "#questpie/factories";
  *
  * export default collection("posts")
- *   .fields(({ f }) => ({ title: f.text({ required: true }) }))
+ *   .fields(({ f }) => ({ title: f.text(255).required() }))
  *   .admin(({ c }) => ({ icon: c.icon("ph:article") }))
  *   .list(({ v, f }) => v.collectionTable({ columns: [f.title] }))
  * ```
  */
-export function collection<TName extends string>(
-	name: TName,
-): CollectionBuilder<EmptyCollectionState<TName, undefined, _AllFieldTypes>> {
-	return wrapBuilderWithExtensions(
-		CollectionBuilder.create<TName, _AllFieldTypes>(name),
-		_collExt,
-		CollectionBuilder,
-	) as any;
+export function collection<TName extends string>(name: TName): CollectionBuilder<EmptyCollectionState<TName, undefined, _AllFieldTypes>> {
+	return wrapBuilderWithExtensions(CollectionBuilder.create<TName, _AllFieldTypes>(name, _allFieldDefs), _collExt, CollectionBuilder) as any;
 }
 
 /**
  * Create a typed global builder with plugin extensions.
  */
-export function global<TName extends string>(
-	name: TName,
-): GlobalBuilder<EmptyGlobalState<TName, undefined, _AllFieldTypes>> {
-	return wrapBuilderWithExtensions(
-		GlobalBuilder.create<TName, _AllFieldTypes>(name),
-		_globExt,
-		GlobalBuilder,
-	) as any;
+export function global<TName extends string>(name: TName): GlobalBuilder<EmptyGlobalState<TName, undefined, _AllFieldTypes>> {
+	return wrapBuilderWithExtensions(GlobalBuilder.create<TName, _AllFieldTypes>(name, _allFieldDefs), _globExt, GlobalBuilder) as any;
 }
 
 // ════════════════════════════════════════════════════════════
-// Singleton factory functions
+// Builder factory functions (plugin-contributed)
 // ════════════════════════════════════════════════════════════
 
-/** Typed factory for locale config. */
-export function locale<T extends LocaleConfig>(config: T): T {
-	return config;
-}
-
-/** Typed factory for hooks config. */
-export function hooks<T extends GlobalHooksInput>(config: T): T {
-	return config;
-}
-
-/** Typed factory for access config. */
-export function access<T extends CollectionAccess>(config: T): T {
-	return config;
+import { BlockBuilder } from "@questpie/admin/server";
+/**
+ * Create a typed block builder with wrapped field defs.
+ */
+export function block<TName extends string>(name: TName): import('@questpie/admin/server').BlockBuilder<{ name: TName }> {
+	return BlockBuilder.create(name, _allFieldDefs) as any;
 }
 
-/** Typed factory for context config. */
-export function context<T extends ContextResolver>(config: T): T {
-	return config;
-}
+// ════════════════════════════════════════════════════════════
+// Singleton factory functions
+// ════════════════════════════════════════════════════════════
 
-/** Typed factory for branding config. */
-export function branding<T extends ServerBrandingConfig>(config: T): T {
-	return config;
-}
+/** Typed factory for appConfig config. */
+export function appConfig<T extends AppConfigInput>(config: T): T { return config; }
 
-/** Typed factory for adminLocale config. */
-export function adminLocale<T extends AdminLocaleConfig>(config: T): T {
-	return config;
-}
+/** Typed factory for authConfig config. */
+export function authConfig<T extends AuthConfig>(config: T): T { return config; }
 
-/** Typed factory for sidebar config. Accepts plain config or callback. */
-export function sidebar<T extends SidebarContribution>(config: T): T;
-export function sidebar<T extends (...args: any[]) => SidebarContribution>(
-	cb: T,
-): T;
-export function sidebar(v: any): any {
-	return v;
-}
+/** Typed factory for adminConfig config. Accepts plain config or callback. */
+export function adminConfig<T extends AdminConfigInput>(config: T): T;
+export function adminConfig<T extends (...args: any[]) => AdminConfigInput>(cb: T): T;
+export function adminConfig(v: any): any { return v; }
 
-/** Typed factory for dashboard config. Accepts plain config or callback. */
-export function dashboard<T extends DashboardContribution>(config: T): T;
-export function dashboard<T extends (...args: any[]) => DashboardContribution>(
-	cb: T,
-): T;
-export function dashboard(v: any): any {
-	return v;
-}
+/** Typed factory for openapi config. */
+export function openapi<T extends OpenApiModuleConfig>(config: T): T { return config; }

package/templates/tanstack-start/src/questpie/server/.generated/index.ts

@@ -2,36 +2,34 @@
 // AUTO-GENERATED by questpie codegen — DO NOT EDIT
 // Regenerate with: questpie generate
 
-import {
-	type AppContext,
-	createApp,
-	createContextFactory,
-	type Questpie,
-	type QuestpieConfig,
-} from "questpie";
-// ── Module type extraction (inline, no recursive types) ───
-import type { UnionToIntersection } from "questpie";
+import { createApp, createContextFactory, extractAppServices, type AppDefinition, type ModuleDefinition, type AppContext, type Registry, type QueueClient, type CollectionAPI } from "questpie";
 
-// ── Plugin Singles ─────────────────────────────────────────
-import _branding from "../branding";
-// ── Collections ────────────────────────────────────────────
-import { posts as _coll_posts_collection } from "../collections/posts.collection";
-import _dashboard from "../dashboard";
-// ── Globals ────────────────────────────────────────────────
-import { siteSettings as _glob_siteSettings_global } from "../globals/site-settings.global";
-// ── Modules ────────────────────────────────────────────────
-import _modules from "../modules";
 // ── Runtime ────────────────────────────────────────────────
 import _runtime from "../questpie.config";
+
+// ── Modules ────────────────────────────────────────────────
+import _modules from "../modules";
+
+// ── Collections ────────────────────────────────────────────
+import { posts as _coll_posts } from "../collections/posts.collection";
+
+// ── Globals ────────────────────────────────────────────────
+import { siteSettings as _glob_siteSettings } from "../globals/site-settings.global";
+
+// ── Core Singles ───────────────────────────────────────────
+import _authConfig from "../config/auth";
+
+// ── Plugin Singles ─────────────────────────────────────────
+import _adminConfig from "../config/admin";
+import _openapi from "../config/openapi";
+
 // ════════════════════════════════════════════════════════════
 // TYPES — composed from typeof references (zero inference cost)
 // ════════════════════════════════════════════════════════════
-import _sidebar from "../sidebar";
 
+import type { ServiceCustomNamespaceInstances, ServiceInstanceOf, ServiceInstancesInNamespace, ServiceTopLevelInstances, UnionToIntersection } from "questpie";
 type _Module = (typeof _modules)[number];
-type _MPRaw<K extends string> = UnionToIntersection<
-	_Module extends infer M ? (M extends Record<K, infer V> ? V : never) : never
->;
+type _MPRaw<K extends string> = UnionToIntersection<_Module extends infer M ? M extends Record<K, infer V> ? V : never : never>;
 type _MP<K extends string> = [_MPRaw<K>] extends [never] ? {} : _MPRaw<K>;
 
 type _ModuleCollections = _MP<"collections">;
@@ -39,15 +37,35 @@ type _ModuleGlobals = _MP<"globals">;
 type _ModuleJobs = _MP<"jobs">;
 type _ModuleRoutes = _MP<"routes">;
 type _ModuleServices = _MP<"services">;
+type _ModuleFieldTypes = _MP<"fieldTypes">;
+type _ModuleViews = _MP<"views">;
+type _ModuleComponents = _MP<"components">;
+type _ModuleBlocks = _MP<"blocks">;
+// Registry category extraction from modules
+type _Registry_Collections = _MP<"collections">;
+type _Registry_Globals = _MP<"globals">;
+type _Registry_Jobs = _MP<"jobs">;
+type _Registry_Routes = _MP<"routes">;
+type _Registry_Services = _MP<"services">;
+type _Registry_Emails = _MP<"emails">;
+type _Registry_FieldTypes = _MP<"fieldTypes">;
+type _Registry_Views = _MP<"views">;
+type _Registry_Components = _MP<"components">;
+type _Registry_Blocks = _MP<"blocks">;
+
+// Recursive module property extraction (for fields contributed at each level)
+import type { ExtractModuleProp } from "questpie";
+
+type _AllModuleFields = ExtractModuleProp<{ modules: typeof _modules }, "fields">;
 
 /** All collections in the app (modules + user, user overrides) */
 export type AppCollections = _ModuleCollections & {
-	"posts.collection": typeof _coll_posts_collection;
+	posts: typeof _coll_posts;
 };
 
 /** All globals in the app (modules + user, user overrides) */
 export type AppGlobals = _ModuleGlobals & {
-	"siteSettings.global": typeof _glob_siteSettings_global;
+	siteSettings: typeof _glob_siteSettings;
 };
 
 /** All jobs in the app (modules + user, user overrides) */
@@ -56,51 +74,75 @@ export type AppJobs = _ModuleJobs;
 /** All routes in the app (modules + user, user overrides) */
 export type AppRoutes = _ModuleRoutes;
 
-/** All services in the app (modules + user, user overrides). Values are service instances. */
-export type AppServices = _ModuleServices;
+/** All service definitions in the app (modules + user, user overrides). */
+type _AppServiceDefinitions = _ModuleServices;
 
-/**
- * The fully-typed app instance type.
- * Use `typeof app` or this alias when you need to reference the app type.
- *
- * **Note:** Do NOT import `app` inside framework-defined files (collections,
- * globals, routes, hooks, blocks) — it creates circular dependencies with
- * the generated index. Use the context parameters provided to handlers instead.
- */
-export type App = Questpie<
-	QuestpieConfig & {
-		collections: AppCollections;
-		globals: AppGlobals;
-		jobs: AppJobs;
-		routes: AppRoutes;
-		services: AppServices;
-	}
->;
+/** All services in the app as resolved service instances. */
+export type AppServices = {
+	[K in keyof _AppServiceDefinitions]: ServiceInstanceOf<_AppServiceDefinitions[K]>;
+};
+type _AppDefaultServices = ServiceInstancesInNamespace<_AppServiceDefinitions, "services">;
+type _AppTopLevelServices = ServiceTopLevelInstances<_AppServiceDefinitions>;
+type _AppCustomServiceNamespaces = ServiceCustomNamespaceInstances<_AppServiceDefinitions>;
+
+/** All email templates in the app — use with email.sendTemplate() */
+export type AppEmailTemplates = Record<string, never>;
+
+/** All fieldtypes in the app (modules + user, user overrides) */
+export type AppFieldTypes = _ModuleFieldTypes;
+
+/** All views in the app (modules + user, user overrides) */
+export type AppViews = _ModuleViews;
+
+/** All components in the app (modules + user, user overrides) */
+export type AppComponents = _ModuleComponents;
+
+/** All blocks in the app (modules + user, user overrides) */
+export type AppBlocks = _ModuleBlocks;
+
+type _CollectionsAPI = { [K in keyof AppCollections]: CollectionAPI<AppCollections[K], AppCollections> };
 
 // ── AppContext augmentation — auto-types ALL handlers ──────
-declare module "questpie" {
-	interface AppContext {
-		// Infrastructure
-		db: App["db"];
-		email: App["email"];
-		queue: App["queue"];
-		storage: App["storage"];
-		kv: App["kv"];
-		logger: App["logger"];
-		search: App["search"];
-		realtime: App["realtime"];
-
-		// Entity APIs
-		collections: App["collections"];
-		globals: App["globals"];
-
-		// Request-scoped
-		session: Awaited<ReturnType<App["auth"]["api"]["getSession"]>> | null;
-		t: (
-			key: string,
-			params?: Record<string, unknown>,
-			locale?: string,
-		) => string;
+declare global {
+	namespace Questpie {
+		interface AppContext extends _AppTopLevelServices, _AppCustomServiceNamespaces {
+			// Infrastructure
+			db: (typeof app)['db'];
+			email: (typeof app)['email'];
+			queue: QueueClient<AppJobs>;
+			storage: (typeof app)['storage'];
+			kv: (typeof app)['kv'];
+			logger: (typeof app)['logger'];
+			search: (typeof app)['search'];
+			realtime: (typeof app)['realtime'];
+
+			// Entity APIs
+			collections: _CollectionsAPI;
+			globals: (typeof app)['globals'];
+			tables: (typeof app)['tables'];
+
+			// Request-scoped
+			session: (typeof app)['auth'] extends { api: { getSession: (...args: any[]) => Promise<infer TSession> } } ? NonNullable<TSession> | null : null;
+			t: (key: string, params?: Record<string, unknown>, locale?: string) => string;
+
+			// User services
+			services: _AppDefaultServices;
+		}
+
+		interface ServiceCreateContext extends AppContext {}
+
+		interface Registry {
+			collections: _Registry_Collections;
+			globals: _Registry_Globals;
+			jobs: _Registry_Jobs;
+			routes: _Registry_Routes;
+			services: _Registry_Services;
+			emails: _Registry_Emails;
+			"~fieldTypes": _Registry_FieldTypes & _AllModuleFields;
+			views: _Registry_Views;
+			components: _Registry_Components;
+			blocks: _Registry_Blocks;
+		}
 	}
 }
 
@@ -110,32 +152,36 @@ declare module "questpie" {
  * For handler context, use `AppContext` (auto-typed via module augmentation).
  */
 export type AppConfig = {
-	collections: AppCollections;
-	globals: AppGlobals;
+	collections: AppCollections & Record<string, any>;
+	globals: AppGlobals & Record<string, any>;
+	routes: AppRoutes;
+	auth: typeof _authConfig;
 };
 
 // ════════════════════════════════════════════════════════════
 // RUNTIME — create the app instance
 // ════════════════════════════════════════════════════════════
 
-export const app = (await createApp(
-	{
-		modules: _modules as any,
+export const app = await createApp(
+	({
+		modules: _modules as ModuleDefinition[],
 		collections: {
-			"posts.collection": _coll_posts_collection,
+			posts: _coll_posts,
 		},
 		globals: {
-			"siteSettings.global": _glob_siteSettings_global,
+			siteSettings: _glob_siteSettings,
+		},
+		config: {
+			auth: _authConfig as any,
+			admin: _adminConfig as any,
+			openapi: _openapi as any,
 		},
-		branding: _branding as any,
-		dashboard: _dashboard as any,
-		sidebar: _sidebar as any,
-	},
+	}) satisfies AppDefinition,
 	_runtime,
-)) as unknown as AppConfig & {
-	waitForInit(): Promise<void>;
-	destroy(): Promise<void>;
-};
+);
+
+/** Fully typed QUESTPIE app instance. */
+export type App = typeof app;
 
 // ── createContext — typed context for scripts ──────────────
 /**
@@ -151,3 +197,5 @@ export const app = (await createApp(
  * ```
  */
 export const createContext = createContextFactory(app);
+
+// Factories: import { collection, global, ... } from '#questpie/factories';

package/templates/tanstack-start/src/questpie/server/app.ts

@@ -7,4 +7,4 @@
  * If .generated/ does not exist yet, run: bun questpie generate
  */
 
-export { type App, app } from "./.generated/index";
+export { type App, type AppConfig, app } from "./.generated/index";

package/templates/tanstack-start/src/questpie/server/globals/site-settings.global.ts

@@ -1,6 +1,6 @@
 import { global } from "#questpie/factories";
 
-export const siteSettings = global("site_settings")
+export const siteSettings = global("siteSettings")
 	.fields(({ f }) => ({
 		siteName: f.text().label("Site Name").required().default("{{projectName}}"),
 		description: f

package/templates/tanstack-start/src/questpie/server/questpie.config.ts

@@ -3,7 +3,7 @@
  *
  * Runtime-only configuration: database, adapters, secrets.
  * Entity definitions (collections, globals, etc.) are codegen-generated.
- * Sidebar, dashboard, branding are file conventions.
+ * Admin sidebar, dashboard, and branding live in config/admin.ts.
  */
 
 import { ConsoleAdapter, runtimeConfig } from "questpie";