@svgrid/enterprise 3.1.17 → 3.1.18

package/dist/node/studio.js

@@ -1151,7 +1151,7 @@ function mapSqlType(raw) {
 	if (/json/.test(t)) return "json";
 	return "text";
 }
-function fieldFrom(name, rawType, pk, notNull) {
+function fieldFrom(name, rawType, pk, notNull, generated = false) {
 	const field = {
 		field: name,
 		type: mapSqlType(rawType)
@@ -1159,12 +1159,26 @@ function fieldFrom(name, rawType, pk, notNull) {
 	if (pk) {
 		field.primaryKey = true;
 		field.readonly = true;
-	} else if (notNull) field.required = true;
+	} else if (generated) field.readonly = true;
+	else if (notNull) field.required = true;
 	return field;
 }
-/** Map catalog rows (aliased name/type/nullable/pk) from information_schema dialects. */
+/**
+* A Base table's order column stays in the schema (base-connect finds it there
+* and reads in its order) but is never shown or written by a generated app.
+*/
+function hideBaseOrderColumn(field) {
+	if (field.field !== "svgrid_order") return field;
+	const { required: _required, ...rest } = field;
+	return {
+		...rest,
+		readonly: true,
+		hidden: true
+	};
+}
+/** Map catalog rows (aliased name/type/nullable/pk/generated) from information_schema dialects. */
 function infoSchemaFields(rows) {
-	return rows.map((r) => fieldFrom(String(r.name), String(r.type ?? ""), truthy(r.pk), !truthy(r.nullable)));
+	return rows.map((r) => hideBaseOrderColumn(fieldFrom(String(r.name), String(r.type ?? ""), truthy(r.pk), !truthy(r.nullable), truthy(r.generated))));
 }
 /** Map SQLite `PRAGMA table_info` rows (name/type/notnull/pk-as-index). */
 function sqliteFields(rows) {
@@ -1191,7 +1205,8 @@ var DIALECTS$1 = {
 		columns: (table) => ({
 			sql: `SELECT c.column_name AS name, c.data_type AS type,
        CASE WHEN c.is_nullable = 'YES' THEN 1 ELSE 0 END AS nullable,
-       CASE WHEN pk.column_name IS NOT NULL THEN 1 ELSE 0 END AS pk
+       CASE WHEN pk.column_name IS NOT NULL THEN 1 ELSE 0 END AS pk,
+       CASE WHEN (c.is_identity = 'YES' AND c.identity_generation = 'ALWAYS') OR c.is_generated = 'ALWAYS' THEN 1 ELSE 0 END AS generated
 FROM information_schema.columns c
 LEFT JOIN (
   SELECT kcu.column_name
@@ -1226,7 +1241,8 @@ WHERE tc.constraint_type = 'FOREIGN KEY' AND tc.table_name = $1`,
 		columns: (table) => ({
 			sql: `SELECT COLUMN_NAME AS name, DATA_TYPE AS type,
        CASE WHEN IS_NULLABLE = 'YES' THEN 1 ELSE 0 END AS nullable,
-       CASE WHEN COLUMN_KEY = 'PRI' THEN 1 ELSE 0 END AS pk
+       CASE WHEN COLUMN_KEY = 'PRI' THEN 1 ELSE 0 END AS pk,
+       CASE WHEN EXTRA LIKE '%GENERATED%' THEN 1 ELSE 0 END AS generated
 FROM information_schema.columns
 WHERE TABLE_NAME = ? AND TABLE_SCHEMA = DATABASE()
 ORDER BY ORDINAL_POSITION`,
@@ -16215,7 +16231,11 @@ function layoutFile(nav, opts = {}) {
 		contents: `<script lang="ts">
   import '../app.css'
   import '../custom.css'
-  import { page } from '$app/state'${opts.access ? `\n  import { currentRole, canScreen } from '$lib/access'` : ""}${opts.i18n ? `\n  import { t, currentLocale, locales } from '$lib/i18n'` : ""}${opts.auth ? `\n  import type { LayoutData } from './$types'` : ""}${opts.supabaseAuth ? `\n  import { SvAuthGate, type SupabaseAuthClientLike } from '@svgrid/enterprise'\n  import { supabaseClient } from '$lib/connections'` : ""}
+  import { page } from '$app/state'
+  import { setLicenseKey } from '@svgrid/enterprise'${opts.access ? `\n  import { currentRole, canScreen } from '$lib/access'` : ""}${opts.i18n ? `\n  import { t, currentLocale, locales } from '$lib/i18n'` : ""}${opts.auth ? `\n  import type { LayoutData } from './$types'` : ""}${opts.supabaseAuth ? `\n  import { SvAuthGate, type SupabaseAuthClientLike } from '@svgrid/enterprise'\n  import { supabaseClient } from '$lib/connections'` : ""}
+
+  // VITE_SVPRO_KEY in .env is your SvGrid license key; it removes the unlicensed watermark.
+  if (import.meta.env.VITE_SVPRO_KEY) setLicenseKey(import.meta.env.VITE_SVPRO_KEY)
 
   let { children${opts.auth ? ", data" : ""} }${opts.auth ? ": { children: import('svelte').Snippet; data: LayoutData }" : ""} = $props()
   const nav = ${JSON.stringify(links)}
@@ -16430,11 +16450,18 @@ function emitStudioApp(schemas) {
 			label: n.label
 		};
 	});
+	const customCss = {
+		path: "src/custom.css",
+		description: "Your custom styles (imported after app.css so it overrides).",
+		userOwned: true,
+		contents: "/* Your custom styles. Imported after app.css, so these rules override the defaults. */\n"
+	};
 	return [
 		...files,
 		...prepared.map((s) => entityScreenPage(s)),
 		layoutFile(nav),
-		homeFile(nav)
+		homeFile(nav),
+		customCss
 	];
 }
 //#endregion
@@ -16457,7 +16484,7 @@ function hasFieldConditions(schema) {
 *
 * `version.test.ts` asserts this matches `package.json`, so the two cannot drift.
 */
-var SVGRID_VERSION = "3.1.17";
+var SVGRID_VERSION = "3.1.18";
 /**
 * The version of `@svgrid/grid`, which releases on its own line: enterprise is
 * on 3.1.x while the grid is on 3.0.x.
@@ -16470,7 +16497,7 @@ var SVGRID_VERSION = "3.1.17";
 *
 * `version.test.ts` asserts this matches packages/grid/package.json.
 */
-var GRID_VERSION = "3.0.18";
+var GRID_VERSION = "3.0.19";
 //#endregion
 //#region src/studio/emit-project.ts
 var has = (blocks, kind) => blocks.some((b) => b.config.kind === kind);
@@ -16501,15 +16528,24 @@ function columnFormatExpr(fmt) {
 	}
 }
 /** The visible grid columns: configured order, per-column header/width/align overrides, editability per mode. */
-function gridColumnsExpr(schemaVar, block, typeName) {
+function gridColumnsExpr(schemaVar, block, typeName, relDisplay) {
 	if (block.config.kind !== "grid") return `schemaToColumns(${schemaVar})`;
 	const cfg = block.config;
 	const idSafe = block.id.replace(/-/g, "_");
-	const visible = cfg.columns.filter((c) => c.show);
+	const shown = cfg.columns.filter((c) => c.show);
+	const shownFields = new Set(shown.map((c) => c.field));
+	const seen = /* @__PURE__ */ new Set();
+	const visible = shown.map((c) => {
+		const d = relDisplay?.get(c.field);
+		return {
+			c,
+			col: d && !shownFields.has(d) ? d : c.field
+		};
+	}).filter((v) => !seen.has(v.col) && !!seen.add(v.col));
 	const editablePart = cfg.editing === "inline" ? "" : ", editable: false";
 	if (visible.length === 0) return editablePart ? `schemaToColumns(${schemaVar}).map((c) => ({ ...c${editablePart} }))` : `schemaToColumns(${schemaVar})`;
-	const order = visible.map((c) => `'${c.field}'`);
-	const ovEntries = visible.map((c) => {
+	const order = visible.map((v) => `'${v.col}'`);
+	const ovEntries = visible.map(({ c, col }) => {
 		const parts = [];
 		if (c.header) parts.push(`header: ${JSON.stringify(c.header)}`);
 		if (c.width != null) parts.push(`width: ${c.width}`);
@@ -16518,7 +16554,7 @@ function gridColumnsExpr(schemaVar, block, typeName) {
 		if (cfg.treeData && c.field === cfg.treeData.labelField && typeName) parts.push(`cell: (ctx: CellContext<${typeName}>) => renderSnippet(treeCell_${idSafe}, { value: ctx.getValue(), row: ctx.row.original })`);
 		else if (c.cellType && typeName) parts.push(`cell: (ctx: CellContext<${typeName}>) => renderSnippet(${cellSnippetName(idSafe, c.field)}, { value: ctx.getValue() })`);
 		else if (c.format) parts.push(`format: ${columnFormatExpr(c.format)}`);
-		return parts.length ? `'${c.field}': { ${parts.join(", ")} }` : null;
+		return parts.length ? `'${col}': { ${parts.join(", ")} }` : null;
 	}).filter((x) => !!x);
 	const ovDecl = ovEntries.length ? ` const ov: Record<string, Partial<(typeof all)[number]>> = { ${ovEntries.join(", ")} };` : "";
 	const ovPart = ovEntries.length ? ", ...(ov[String(c.field)] ?? {})" : "";
@@ -18240,7 +18276,7 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
 	if (blocks.some((b) => b.config.kind === "grid" && !!b.config.export?.print)) parts.push(PRINT_HELPER);
 	for (const b of blocks) if (b.config.kind === "grid") {
 		const idSafe = b.id.replace(/-/g, "_");
-		const colExpr = gridColumnsExpr(n.schemaVar, b, n.type);
+		const colExpr = gridColumnsExpr(n.schemaVar, b, n.type, relationDisplayFields(rawSchema, resolve));
 		let colValue = i18nEnabled ? `localizeCols(${colExpr}, ${JSON.stringify(schema.name)}, $t)` : colExpr;
 		const actions = (b.config.rowActions ?? []).filter((a) => a.kind !== "edit" || wantsForm);
 		if (actions.length) {
@@ -18550,7 +18586,7 @@ function attrs(f) {
 	return out.length ? " " + out.join(" ") : "";
 }
 /** The `+page.server.ts` + SSR `+page.svelte` for a single-grid CRUD screen. */
-function emitSsrGridScreen(schema, screen, routed, accessEnabled, screenIds, byName) {
+function emitSsrGridScreen(schema, screen, routed, accessEnabled, screenIds, byName, rawSchema = schema) {
 	const n = namesFor(schema);
 	const isSql = routed(schema.name);
 	const relSchemaOf = (f) => byName.get(f.relation.entity);
@@ -18567,18 +18603,23 @@ function emitSsrGridScreen(schema, screen, routed, accessEnabled, screenIds, byN
 	const normType = (t) => t === "number" ? "number" : t === "boolean" ? "boolean" : "text";
 	const fieldTypesLit = `{ ${formFields.map((f) => `${jsStr(f.field)}: ${jsStr(normType(f.type))}`).join(", ")} }`;
 	const isRel = (f) => f.type === "relation" && !!f.relation && byName.has(f.relation.entity);
+	const relSourceOf = (rs) => routed(rs.name) ? `createKitDataSource<Record<string, unknown>>({ endpoint: ${jsStr("/api/" + namesFor(rs).route)}, fetch })` : namesFor(rs).sourceVar;
+	const relDisplay = relationDisplayFields(rawSchema, (name) => byName.get(name));
+	const labelFields = isSql ? schema.fields.filter((f) => isRel(f) && schema.fields.some((x) => x.field === relDisplay.get(f.field))) : [];
 	const relFields = formFields.filter(isRel);
 	const relRouted = relFields.some((f) => routed(relSchemaOf(f).name));
-	const relSourceVars = [...new Set(relFields.filter((f) => !routed(relSchemaOf(f).name)).map((f) => namesFor(relSchemaOf(f)).sourceVar))];
+	const relSourceVars = [...new Set([...relFields, ...labelFields].filter((f) => !routed(relSchemaOf(f).name)).map((f) => namesFor(relSchemaOf(f)).sourceVar))];
 	const relPrefetch = relFields.map((f) => {
 		const rs = relSchemaOf(f);
-		const rel = namesFor(rs);
 		const relId = relIdOf(rs);
 		const labelF = f.relation.labelField ?? relId;
-		const relSource = routed(rs.name) ? `createKitDataSource<Record<string, unknown>>({ endpoint: ${jsStr("/api/" + rel.route)}, fetch })` : rel.sourceVar;
-		return `  const ${f.field}Options = (await ${relSource}.getRows({ startRow: 0, endRow: 100, pageIndex: 0, pageSize: 100, sortModel: [], filterModel: {} })).rows.map((r: Record<string, unknown>) => ({ value: String(r[${jsStr(relId)}] ?? ''), label: String(r[${jsStr(labelF)}] ?? '') }))`;
+		return `  const ${f.field}Options = (await ${relSourceOf(rs)}.getRows({ startRow: 0, endRow: 100, pageIndex: 0, pageSize: 100, sortModel: [], filterModel: {} })).rows.map((r: Record<string, unknown>) => ({ value: String(r[${jsStr(relId)}] ?? ''), label: String(r[${jsStr(labelF)}] ?? '') }))`;
 	}).join("\n");
 	const relReturn = relFields.map((f) => `, ${f.field}Options`).join("");
+	const labelSpecs = labelFields.map((f) => {
+		const rs = relSchemaOf(f);
+		return `{ fk: ${jsStr(f.field)}, as: ${jsStr(relDisplay.get(f.field))}, lookup: createRelationLookup({ source: ${relSourceOf(rs)}, valueField: ${jsStr(relIdOf(rs))}, labelField: ${jsStr(f.relation.labelField ?? relIdOf(rs))} }) }`;
+	});
 	const src = isSql ? "source(fetch)" : n.sourceVar;
 	const fetchArg = isSql ? ", fetch" : "";
 	const loadFetchArg = isSql || relRouted ? ", fetch" : "";
@@ -18587,7 +18628,8 @@ function emitSsrGridScreen(schema, screen, routed, accessEnabled, screenIds, byN
 	const enterpriseImports = [
 		"validateAll",
 		...conditional ? ["stripHiddenValues"] : [],
-		...isSql || relRouted ? ["createKitDataSource"] : []
+		...isSql || relRouted ? ["createKitDataSource"] : [],
+		...labelSpecs.length ? ["createRelationLookup", "withRelationLabels"] : []
 	].join(", ");
 	const dataImports = [.../* @__PURE__ */ new Set([...isSql ? [] : [n.sourceVar], ...relSourceVars])];
 	const sourceImport = dataImports.length ? `import { ${dataImports.join(", ")} } from '$lib/data'\n` : "";
@@ -18625,7 +18667,7 @@ function formToValues(fd: FormData): Record<string, unknown> {
 
 export const load: PageServerLoad = async ({ url${loadFetchArg}${localsArg} }) => {
 ${readGuard}  const plan = planFromSearchParams(url, ${pageSize})
-  const { rows, rowCount } = await ${src}.getRows(plan)
+  const { rows, rowCount } = await ${labelSpecs.length ? `withRelationLabels(${src}, [\n    ${labelSpecs.join(",\n    ")},\n  ])` : src}.getRows(plan)
 ${relPrefetch ? relPrefetch + "\n" : ""}  return { rows, total: rowCount, page: plan.pageIndex, size: plan.pageSize, sort: plan.sortModel${relReturn} }
 }
 
@@ -18981,7 +19023,7 @@ function emitStudioProject(project) {
 		const schema = byName.get(screen.entity);
 		if (!schema) throw new Error(`emitStudioProject: screen "${screen.title}" references missing entity "${screen.entity}"`);
 		if (isSsrScreen(project, screen)) {
-			if (ssrScreenShape(project, screen) === "grid") pages.push(...emitSsrGridScreen(schema, screen, routed, accessEnabled, screensByEntity.get(screen.entity) ?? [], byName));
+			if (ssrScreenShape(project, screen) === "grid") pages.push(...emitSsrGridScreen(schema, screen, routed, accessEnabled, screensByEntity.get(screen.entity) ?? [], byName, rawByName.get(screen.entity) ?? schema));
 			else pages.push(ssrReadServerFile(schema, screen, routed, accessEnabled, screensByEntity.get(screen.entity) ?? [], resolve), screenPage(schema, rawByName.get(screen.entity) ?? schema, screen, resolve, (name) => rawByName.get(name), accessEnabled, i18nEnabled, routeById, drillEnabled, true));
 			continue;
 		}
@@ -21106,7 +21148,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
       - run: npm install
       - run: npm run build
       - run: npm test
@@ -21125,7 +21167,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
       - run: npm install
 ${steps}`;
 }
@@ -21207,7 +21249,7 @@ function deployPlan(project) {
 			files: [{
 				path: "Dockerfile",
 				description: "Container image (multi-stage: build then run `node build`).",
-				contents: `# Build stage\nFROM node:20-alpine AS build\nWORKDIR /app\nCOPY package*.json ./\nRUN npm install\nCOPY . .\nRUN npm run build\nRUN npm prune --omit=dev\n\n# Run stage\nFROM node:20-alpine\nWORKDIR /app\nENV NODE_ENV=production\nCOPY --from=build /app/build ./build\nCOPY --from=build /app/node_modules ./node_modules\nCOPY --from=build /app/package.json ./package.json\nEXPOSE 3000\nCMD ["node", "build"]\n`
+				contents: `# Build stage\nFROM node:22-alpine AS build\nWORKDIR /app\nCOPY package*.json ./\nRUN npm install\nCOPY . .\nRUN npm run build\nRUN npm prune --omit=dev\n\n# Run stage\nFROM node:22-alpine\nWORKDIR /app\nENV NODE_ENV=production\nCOPY --from=build /app/build ./build\nCOPY --from=build /app/node_modules ./node_modules\nCOPY --from=build /app/package.json ./package.json\nEXPOSE 3000\nCMD ["node", "build"]\n`
 			}, {
 				path: ".dockerignore",
 				description: "Files kept out of the image.",
@@ -21243,13 +21285,21 @@ function studioDeployInfo(project) {
 }
 /** DEPLOY.md - the runbook: required env vars, then Git-integration / CI / CLI paths. */
 function deployDocs(project, plan, envKeys, hasMigrations, opts = {}) {
-	const envBlock = envKeys.length ? `## Environment variables\n\nSet these on your host (and locally in \`.env\` - copy \`.env.example\`):\n\n${envKeys.map((k) => `- \`${k}\``).join("\n")}\n\nOptional: \`VITE_SVPRO_KEY\` (your SvGrid license key) removes the unlicensed watermark - call \`setLicenseKey(import.meta.env.VITE_SVPRO_KEY)\` once at startup (see the docs).\n\n` : "";
+	const envBlock = envKeys.length ? `## Environment variables\n\nSet these on your host (and locally in \`.env\` - copy \`.env.example\`):\n\n${envKeys.map((k) => `- \`${k}\``).join("\n")}\n\nOptional: \`VITE_SVPRO_KEY\` (your SvGrid license key) removes the unlicensed watermark - the root layout passes it to \`setLicenseKey\`. It is read at build time, so set it before \`npm run build\`.\n\n` : "";
 	const migrations = hasMigrations ? `## Database migrations\n\nThis app has a typed Drizzle schema (\`src/lib/server/db/schema.ts\`). Create + apply the tables:\n\n\`\`\`bash\nnpm run db:generate   # SQL migrations from the schema\nnpm run db:migrate    # apply them to DATABASE_URL\n${opts.hasSeedScript ? "npm run db:seed       # optional: insert the sample rows\n" : ""}\`\`\`\n\n(Run these against your production database as part of your release step.)\n\n` : "";
 	const ddl = opts.hasDdl ? `## Database tables\n\nThis app's SQL entities expect their tables to exist. Run \`db/schema.sql\` against the database your \`DATABASE_URL\` points at (psql / mysql / sqlite3 / sqlcmd, or your provider's SQL console) before first use - and optionally \`db/seed.sql\` for sample rows. Tip: enable the Drizzle data layer in Studio for real, versioned migrations instead.\n\n` : "";
-	const gitIntegration = plan.dashboard ? `## Option A - Git integration (simplest, no secrets)\n\n1. Push this repo to GitHub.\n2. Import it at <${plan.dashboard}> - the SvelteKit build is auto-detected.\n3. Add the environment variables above in the host's dashboard.\n\nEvery push to \`main\` then redeploys automatically.\n\n` : "";
-	const ci = plan.deployWorkflow ? `## Option B - GitHub Actions (included)\n\n\`.github/workflows/deploy.yml\` deploys on every push to \`main\`. Add these repository secrets to enable it (Settings -> Secrets and variables -> Actions):\n\n${plan.secrets.map((s) => `- \`${s}\``).join("\n")}\n\nUntil the secrets are set the deploy step is skipped, so CI stays green. Prefer Option A? Delete \`deploy.yml\`.\n\n` : "";
+	const letters = [
+		"A",
+		"B",
+		"C"
+	];
+	const gitLetter = plan.dashboard ? letters.shift() : "";
+	const ciLetter = plan.deployWorkflow ? letters.shift() : "";
+	const cliLetter = letters.shift();
+	const gitIntegration = plan.dashboard ? `## Option ${gitLetter} - Git integration (simplest, no CI secrets)\n\n1. Push this repo to GitHub.\n2. Import it at <${plan.dashboard}> - the SvelteKit build is auto-detected.\n${envKeys.length ? "3. Add the environment variables above in the host's dashboard.\n" : ""}\nEvery push to \`main\` then redeploys automatically.\n\n` : "";
+	const ci = plan.deployWorkflow ? `## Option ${ciLetter} - GitHub Actions (included)\n\n\`.github/workflows/deploy.yml\` deploys on every push to \`main\`. Add these repository secrets to enable it (Settings -> Secrets and variables -> Actions):\n\n${plan.secrets.map((s) => `- \`${s}\``).join("\n")}\n\nUntil the secrets are set the deploy step is skipped, so CI stays green.${gitLetter ? ` Prefer Option ${gitLetter}? Delete \`deploy.yml\`.` : ""}\n\n` : "";
 	const dockerNote = project.deploy === "node" ? `## Container\n\nA \`Dockerfile\` is included:\n\n\`\`\`bash\ndocker build -t ${appSlug(project.title)} .\ndocker run -p 3000:3000 --env-file .env ${appSlug(project.title)}\n\`\`\`\n\nThe server listens on \`PORT\` (default 3000).\n\n` : "";
-	const cli = `## Option C - Deploy from your machine\n\n\`\`\`bash\nnpm run deploy\n\`\`\`\n\n(runs \`${plan.deployScript}\`)\n`;
+	const cli = `## Option ${cliLetter} - Deploy from your machine\n\n\`\`\`bash\nnpm run deploy\n\`\`\`\n\n(runs \`${plan.deployScript}\`)\n`;
 	return `# Deploying ${project.title}\n\nConfigured for **${plan.label}** (SvelteKit \`${plan.adapterModule}\`). A CI workflow (\`.github/workflows/ci.yml\`) builds + tests every push.\n\n${envBlock}${ddl}${migrations}${gitIntegration}${ci}${dockerNote}${cli}`;
 }
 /** The env-var keys the generated app reads (for DEPLOY.md). */
@@ -21288,13 +21338,20 @@ function supabaseConnOf(project) {
 *  random `SESSION_SECRET` filled in, so the app is secure out of the box (no
 *  hardcoded dev secret), and the Supabase URL + anon key the model already
 *  holds, so a Supabase app runs as generated instead of failing on an empty
-*  URL. Only emitted when there is something to fill in. */
-function envDotFile(allSource, project) {
+*  URL. Only emitted when there is something to fill in.
+*
+*  `databaseUrl` is the connection the app was built from (`studio init --db
+*  sqlite --url ./shop.db`). Only a SQLite file path is written: it is not a
+*  secret, and without it the app opens an empty data.db. Server URLs carry a
+*  password, so those stay for the user to paste. */
+function envDotFile(allSource, project, databaseUrl) {
 	const example = envExample(allSource);
 	if (!example) return null;
 	const supa = allSource.includes("PUBLIC_SUPABASE_URL") ? supabaseConnOf(project) : null;
-	if (!allSource.includes("SESSION_SECRET") && !supa) return null;
+	const sqliteFile = databaseUrl && allSource.includes("import Database from 'better-sqlite3'") && /^DATABASE_URL=$/m.test(example) ? databaseUrl : null;
+	if (!allSource.includes("SESSION_SECRET") && !supa && !sqliteFile) return null;
 	let env = example.replace("SESSION_SECRET=change-me-to-a-long-random-string", `SESSION_SECRET=${randomSecret()}`);
+	if (sqliteFile) env = env.replace(/^DATABASE_URL=$/m, `DATABASE_URL=${sqliteFile}`);
 	if (supa) env = env.replace(/^PUBLIC_SUPABASE_URL=$/m, `PUBLIC_SUPABASE_URL=${supa.url}`).replace(/^PUBLIC_SUPABASE_ANON_KEY=$/m, `PUBLIC_SUPABASE_ANON_KEY=${supa.key}`);
 	return env;
 }
@@ -21376,7 +21433,7 @@ function runtimeDeps(project, allSource) {
 	if (allSource.includes("import pg from 'pg'")) dependencies["pg"] = "^8.11.0";
 	if (allSource.includes("from 'mysql2/promise'")) dependencies["mysql2"] = "^3.9.0";
 	if (allSource.includes("import mssql from 'mssql'")) dependencies["mssql"] = "^10.0.0";
-	if (allSource.includes("import Database from 'better-sqlite3'")) dependencies["better-sqlite3"] = "^11.0.0";
+	if (allSource.includes("import Database from 'better-sqlite3'")) dependencies["better-sqlite3"] = BETTER_SQLITE3_RANGE;
 	if (allSource.includes("from '@libsql/client'")) dependencies["@libsql/client"] = "^0.14.0";
 	if (allSource.includes("from '@electric-sql/pglite'")) dependencies["@electric-sql/pglite"] = "^0.5.0";
 	if (/from ['"]hyperformula['"]/.test(allSource)) dependencies["hyperformula"] = "^3.3.0";
@@ -21476,12 +21533,20 @@ import { ${imports.join(", ")} } from './schemas'
 ${blocks.join("\n\n")}
 `;
 }
+/** The better-sqlite3 range a generated app installs. Mirrored in the studio
+*  package's designer-server.ts RUNTIME_DEPS. */
+var BETTER_SQLITE3_RANGE = "^12.1.0 || ^13.0.0";
 var VITEST_CONFIG = `import { defineConfig } from 'vitest/config'
+import { svelte } from '@sveltejs/vite-plugin-svelte'
 
-// Node-only test runner for the generated smoke tests (no Svelte/DOM needed).
-// Kept separate from vite.config so the SvelteKit plugin doesn't load here.
+// Test runner for the generated smoke tests, in Node (no DOM). Kept separate from
+// vite.config so the SvelteKit plugin doesn't load here. The tests import the
+// @svgrid/enterprise root, which re-exports .svelte components: the svelte plugin
+// compiles them, and inlining @svgrid/* routes them through it instead of Node's
+// own loader (which rejects the .svelte extension).
 export default defineConfig({
-  test: { environment: 'node', include: ['src/**/*.test.ts'] },
+  plugins: [svelte()],
+  test: { environment: 'node', include: ['src/**/*.test.ts'], server: { deps: { inline: [/@svgrid\\//] } } },
 })
 `;
 /**
@@ -21546,12 +21611,14 @@ jobs:
 ${steps}`
 	}];
 }
-function emitStudioAppBundle(project) {
+function emitStudioAppBundle(project, opts = {}) {
 	const generated = emitStudioProject(project);
 	const allSource = generated.map((f) => f.contents).join("\n");
+	const dotEnv = envDotFile(allSource, project, opts.databaseUrl);
+	const readmeConnections = `SQL entities read their connection from \`.env\` (\`DATABASE_URL\`)${generated.some((f) => f.path === "src/lib/connections.ts") ? ";\nSupabase entities use the shared client in `src/lib/connections.ts`, which reads\n`PUBLIC_SUPABASE_URL` and `PUBLIC_SUPABASE_ANON_KEY` from `.env`" : ""}.\n`;
 	const plan = deployPlan(project);
 	const deploySteps = plan.dashboard ? `1. Push this folder to a Git repo (GitHub / GitLab / Bitbucket).\n2. Import it at <${plan.dashboard}> - build settings are detected automatically.\n\nOr deploy straight from your machine with the CLI:\n\n\`\`\`bash\n${plan.cli}\n\`\`\`` : `Build and run the server:\n\n\`\`\`bash\n${plan.cli}\n\`\`\``;
-	const readme = `# ${project.title}\n\nGenerated with SvGrid Studio.\n\n\`\`\`bash\nnpm install\nnpm run dev\n\`\`\`\n\nSQL / Supabase entities read their connection from \`.env\` (\`DATABASE_URL\`) or\n\`src/lib/connections.ts\`. Everything else runs on seeded in-memory data.\n\n## Deploy (${plan.label})\n\nThis app is configured for **${plan.label}** (SvelteKit \`${plan.adapterModule}\`).\n\n${deploySteps}\n\nTo target a different host, pick another **Deploy target** in the designer and\nre-generate, or swap the adapter in \`svelte.config.js\`. Entities on **Local\ndatabase** (PGlite) or **In-memory** need no server env; SQL / Supabase entities\nneed their connection set in the host's environment variables.\n\n## Round-tripping back into the designer\n\nThis app ships its own design model in \`studio.config.json\`. To keep editing\nvisually, open the SvGrid Studio designer and **Load** that file - your entities,\nscreens, blocks, theme, RBAC, i18n, etc. come back exactly as generated, and you\ncan re-generate from there.\n\nThe designer regenerates the files under \`src/routes\` and \`src/lib\` from the\nmodel, so **keep your own custom code in new files/modules and import it**, rather\nthan editing the generated screens in place - that way a re-generate never\nclobbers your work. (The CLI workflow, \`npx @svgrid/studio add\`, is the\nalternative: it wraps generated code in \`svgrid:managed\` markers and preserves\nanything you write outside them.)\n`;
+	const readme = `# ${project.title}\n\nGenerated with SvGrid Studio.\n\n\`\`\`bash\nnpm install\nnpm run dev\n\`\`\`\n\n${readmeConnections}Everything else runs on seeded in-memory data.\n\n## Deploy (${plan.label})\n\nThis app is configured for **${plan.label}** (SvelteKit \`${plan.adapterModule}\`).\n\n${deploySteps}\n\nTo target a different host, pick another **Deploy target** in the designer and\nre-generate, or swap the adapter in \`svelte.config.js\`. Entities on **Local\ndatabase** (PGlite) or **In-memory** need no server env; SQL / Supabase entities\nneed their connection set in the host's environment variables.\n\n## Round-tripping back into the designer\n\nThis app ships its own design model in \`studio.config.json\`. To keep editing\nvisually, open the SvGrid Studio designer and **Load** that file - your entities,\nscreens, blocks, theme, RBAC, i18n, etc. come back exactly as generated, and you\ncan re-generate from there.\n\nThe designer regenerates the files under \`src/routes\` and \`src/lib\` from the\nmodel, so **keep your own custom code in new files/modules and import it**, rather\nthan editing the generated screens in place - that way a re-generate never\nclobbers your work. (The CLI workflow, \`npx @svgrid/studio add\`, is the\nalternative: it wraps generated code in \`svgrid:managed\` markers and preserves\nanything you write outside them.)\n`;
 	const bundle = [...[
 		{
 			path: "package.json",
@@ -21582,10 +21649,10 @@ function emitStudioAppBundle(project) {
 			description: "Environment variables the app reads (copy to .env and fill in).",
 			contents: envExample(allSource)
 		}] : [],
-		...envDotFile(allSource, project) ? [{
+		...dotEnv ? [{
 			path: ".env",
-			description: "Local env (git-ignored): a real random SESSION_SECRET and the Supabase connection the design holds are pre-filled, so the app runs as generated; fill in the rest.",
-			contents: envDotFile(allSource, project)
+			description: "Local env (git-ignored): a real random SESSION_SECRET, the Supabase connection the design holds and a SQLite file path are pre-filled, so the app runs as generated; fill in the rest.",
+			contents: dotEnv
 		}] : [],
 		{
 			path: "src/app.css",
@@ -41261,23 +41328,64 @@ async function resolveSchemas(from, io) {
 	if (src == null) throw new Error(`runStudioAddApp: schema file not found: ${from}`);
 	return isPrismaSource(from, src) ? introspectPrismaAll(src) : introspectDrizzleAll(src);
 }
-/** Merge-write a set of generated files, preserving user edits outside managed regions. */
+/**
+* Where to park a generated file next to `path`: `<path>.new`, unless that holds
+* something else (an earlier run's copy the user may be merging), then the first
+* free `<path>.new.1`, `.new.2`, ... A slot already holding these exact contents
+* is reused, so re-running does not pile up copies.
+*/
+async function freeNewPath(path, contents, io) {
+	for (let i = 0;; i++) {
+		const candidate = i === 0 ? `${path}.new` : `${path}.new.${i}`;
+		const there = await io.readFile(candidate);
+		if (there == null || there === contents) return candidate;
+	}
+}
+/**
+* Merge-write a set of generated files, preserving user edits outside managed
+* regions.
+*
+* A file already on disk with no managed markers is somebody's own code (the
+* create-studio starter's nav layout, a hand-written page), and a merge would
+* replace it whole. Those get the new version beside them as `<file>.new`, the
+* same convention the designer uses for a hand-edited file, and come back in
+* `conflicts`. Unlike the designer, an existing `.new` with other contents is
+* kept: the copy goes to `.new.1` and up (see freeNewPath). A folder `init` generated (it has studio.config.json) is the
+* exception: its files are Studio's own output, and regenerating them is the
+* point.
+*/
 async function writeAll$1(files, io) {
 	const written = [];
+	const conflicts = [];
+	const studioApp = await io.readFile("studio.config.json") != null;
 	for (const file of files) {
 		const existing = await io.readFile(file.path);
 		if (skipUserOwned(file, existing != null)) continue;
+		if (existing != null && !studioApp && existing !== file.contents && !existing.includes("// svgrid:managed:start")) {
+			const parkedAs = await freeNewPath(file.path, file.contents, io);
+			await io.writeFile(parkedAs, file.contents);
+			conflicts.push({
+				path: file.path,
+				parkedAs
+			});
+			continue;
+		}
 		await io.writeFile(file.path, mergeManaged(existing, file.contents));
 		written.push(file.path);
 	}
-	return written;
+	return {
+		written,
+		conflicts
+	};
 }
 async function runStudioAdd(options, io) {
 	const schema = await resolveSchema(options, io);
 	const { files } = scaffold(schema, options);
+	const { written, conflicts } = await writeAll$1(files, io);
 	return {
 		schema,
-		written: await writeAll$1(files, io),
+		written,
+		conflicts,
 		verify: await verifyScaffold(files)
 	};
 }
@@ -41326,8 +41434,10 @@ async function appShellDefaults(options, io) {
 */
 async function runStudioAddApp(schemas, options, io) {
 	const { files } = scaffoldApp(schemas, await appShellDefaults(options, io));
+	const { written, conflicts } = await writeAll$1(files, io);
 	return {
-		written: await writeAll$1(files, io),
+		written,
+		conflicts,
 		verify: await verifyScaffold(files)
 	};
 }
@@ -41423,29 +41533,41 @@ async function viaSample(o, base) {
 	}));
 }
 /** List a Supabase project's tables from its PostgREST OpenAPI doc (URL + anon key).
-*  Returns the exposed table names (sorted), or `[]` when the doc can't be read
-*  (CORS-blocked, bad key). Lets the Studio wizard offer a table picker instead of
-*  making the user hand-type the table name. */
+*  Returns the exposed table names (sorted). `[]` means the project answered and
+*  lists none, or answered 401/403 without naming the key as invalid (the doc is
+*  restricted for this key; each table can still be introspected by name).
+*  Throws, naming the URL, when the project cannot be reached (wrong URL, CORS),
+*  answers with another error status, says the key is invalid, or sends something
+*  that is not an API description. */
 async function listSupabaseTables(url, key, fetchFn = globalThis.fetch) {
-	const base = url.replace(/\/+$/, "");
+	const at = `${url.replace(/\/+$/, "")}/rest/v1/`;
 	let res;
 	try {
-		res = await fetchFn(`${base}/rest/v1/`, { headers: {
+		res = await fetchFn(at, { headers: {
 			apikey: key,
 			Authorization: `Bearer ${key}`,
 			Accept: "application/json"
 		} });
-	} catch {
-		return [];
+	} catch (e) {
+		throw new Error(`Could not reach ${at} (${e instanceof Error ? e.message : String(e)})`, { cause: e });
+	}
+	if (!res.ok) {
+		let body = "";
+		try {
+			body = await res.text();
+		} catch {}
+		const badKey = /invalid api key/i.test(body);
+		if ((res.status === 401 || res.status === 403) && !badKey) return [];
+		throw new Error(`${at} answered ${res.status}${badKey ? " (invalid API key)" : ""}`);
 	}
-	if (!res.ok) return [];
 	let spec;
 	try {
 		spec = await res.json();
 	} catch {
-		return [];
+		spec = null;
 	}
-	const defs = spec?.definitions ?? spec?.components?.schemas ?? {};
+	if (!spec || typeof spec !== "object" || !(spec.definitions || spec.components || spec.paths)) throw new Error(`${at} did not answer with an API description: is this a Supabase project URL?`);
+	const defs = spec.definitions ?? spec.components?.schemas ?? {};
 	return Object.keys(defs).sort((a, b) => a.localeCompare(b));
 }
 /** Introspect a Supabase/PostgREST table into an EntitySchema, or null. */
@@ -41457,7 +41579,11 @@ async function introspectSupabaseTable(options) {
 	const base = o.url.replace(/\/+$/, "");
 	const columns = await viaOpenApi(o, base) ?? await viaSample(o, base) ?? await viaCsv(o, base);
 	if (!columns || !columns.length) return null;
-	return buildEntitySchema(o.table, columns);
+	const schema = buildEntitySchema(o.table, columns);
+	return {
+		...schema,
+		fields: schema.fields.map((f) => hideBaseOrderColumn(f))
+	};
 }
 //#endregion
 //#region src/studio/user-error.ts
@@ -41719,7 +41845,8 @@ async function gatherFromDatabase(flags, prompts, db) {
 		schemas,
 		sources,
 		seed: {},
-		kind: "sql"
+		kind: "sql",
+		...isFileDialect(dialect) ? { sqliteFile: url } : {}
 	};
 }
 /**
@@ -41896,6 +42023,24 @@ async function askTheme(flags, prompts) {
 }
 /** Prefix a path with the output folder (`.` writes into the current one). */
 var inDir = (outDir, path) => (!outDir || outDir === "." ? "" : outDir.replace(/[\\/]+$/, "") + "/") + path;
+/**
+* A file path given relative to where init ran, re-expressed relative to the
+* app folder, which is where the app runs (`npm run dev` in `outDir`). Absolute
+* paths pass through. An absolute or `..` out dir has no relative answer without
+* the cwd, so the path is made absolute when the runtime has one.
+*/
+function fileFromApp(file, outDir) {
+	const fileUrl = /^file:(?![\\/])(.+)$/.exec(file);
+	if (fileUrl) return `file:${fileFromApp(fileUrl[1], outDir)}`;
+	if (!outDir || outDir === "." || file === ":memory:" || /^([a-zA-Z]:[\\/]|[\\/]|file:)/.test(file)) return file;
+	const rel = file.replace(/^\.[\\/]/, "");
+	const segments = outDir.split(/[\\/]+/).filter((s) => s && s !== ".");
+	if (/^([a-zA-Z]:[\\/]|[\\/])/.test(outDir) || segments.includes("..")) {
+		const cwd = globalThis.process?.cwd?.();
+		return cwd ? `${cwd.replace(/\\/g, "/").replace(/\/+$/, "")}/${rel.replace(/\\/g, "/")}` : file;
+	}
+	return "../".repeat(segments.length) + rel;
+}
 /** Which marker files are present in `outDir` right now. */
 async function markersIn(outDir, io) {
 	const found = /* @__PURE__ */ new Set();
@@ -41965,7 +42110,7 @@ async function runStudioInit(flags, prompts, db, io, fetchText = null) {
 		...theme ? { theme } : {}
 	});
 	const project = flags.kit === 3 ? setKitVersion(built, 3) : built;
-	const written = await writeAll(emitStudioAppBundle(project), outDir, io);
+	const written = await writeAll(emitStudioAppBundle(project, data.sqliteFile ? { databaseUrl: fileFromApp(data.sqliteFile, outDir) } : {}), outDir, io);
 	const configPath = inDir(outDir, "studio.config.json");
 	await io.writeFile(configPath, serializeProject(project));
 	written.push(configPath);

package/dist/sheet-enable.d.ts

@@ -1,6 +1,12 @@
+/**
+ * Register the keymap and the formula-aware fill, without the spreadsheet
+ * nudge. {@link installEnterprise} calls this: an app that wires the Pro API
+ * for export or pivot has not opened a spreadsheet, and must not get a card
+ * naming one.
+ */
+export declare function registerSheetKeymap(): void;
 /**
  * Register the Excel keymap. Idempotent - safe to call from every component
- * that wants it, or once at app start. Also invoked by {@link installEnterprise}
- * so wiring the Pro API turns the shortcuts on too.
+ * that wants it, or once at app start.
  */
 export declare function enableSheet(): void;

package/dist/sheet-enable.js

@@ -7,8 +7,8 @@
  * The grid ships the `registerGridShortcuts` seam for free and interprets a key
  * itself only when nothing claims it; the commands are here. Evaluated like
  * the rest of Enterprise, and part of the Suite edition: it works without a
- * license key, and under a Grid-edition key, but the grid shows the unlicensed
- * watermark and a one-time console nudge in both cases.
+ * license key, but the grid shows the unlicensed watermark and a one-time
+ * console nudge.
  *
  * ```ts
  * import { setLicenseKey, enableSheet } from '@svgrid/enterprise'
@@ -24,16 +24,17 @@ import { nudgeEnterpriseFor } from './license.js';
 import { handleSheetKey } from './sheet/shortcuts.js';
 import { setFillTranslator } from './sheet/commands.js';
 import { translateFormula } from './sheet/refs.js';
-let enabled = false;
+let registered = false;
 /**
- * Register the Excel keymap. Idempotent - safe to call from every component
- * that wants it, or once at app start. Also invoked by {@link installEnterprise}
- * so wiring the Pro API turns the shortcuts on too.
+ * Register the keymap and the formula-aware fill, without the spreadsheet
+ * nudge. {@link installEnterprise} calls this: an app that wires the Pro API
+ * for export or pivot has not opened a spreadsheet, and must not get a card
+ * naming one.
  */
-export function enableSheet() {
-    if (enabled)
+export function registerSheetKeymap() {
+    if (registered)
         return;
-    enabled = true;
+    registered = true;
     // Priority 100 so the sheet keymap sits above anything an app registers of
     // its own without asking for a priority.
     registerGridShortcuts(handleSheetKey, { id: 'svgrid-sheet', priority: 100 });
@@ -41,5 +42,16 @@ export function enableSheet() {
     // literal text into every row; with it the relative half of each reference
     // shifts and the absolute half does not, the way Excel fills.
     setFillTranslator((value, delta) => translateFormula(value, delta.rows, delta.cols));
+}
+let enabled = false;
+/**
+ * Register the Excel keymap. Idempotent - safe to call from every component
+ * that wants it, or once at app start.
+ */
+export function enableSheet() {
+    registerSheetKeymap();
+    if (enabled)
+        return;
+    enabled = true;
     nudgeEnterpriseFor('spreadsheet', 'Spreadsheet');
 }

package/dist/sources/introspect-supabase.d.ts

@@ -22,9 +22,12 @@ export type IntrospectSupabaseOptions = {
     fetch?: typeof fetch;
 };
 /** List a Supabase project's tables from its PostgREST OpenAPI doc (URL + anon key).
- *  Returns the exposed table names (sorted), or `[]` when the doc can't be read
- *  (CORS-blocked, bad key). Lets the Studio wizard offer a table picker instead of
- *  making the user hand-type the table name. */
+ *  Returns the exposed table names (sorted). `[]` means the project answered and
+ *  lists none, or answered 401/403 without naming the key as invalid (the doc is
+ *  restricted for this key; each table can still be introspected by name).
+ *  Throws, naming the URL, when the project cannot be reached (wrong URL, CORS),
+ *  answers with another error status, says the key is invalid, or sends something
+ *  that is not an API description. */
 export declare function listSupabaseTables(url: string, key: string, fetchFn?: typeof fetch): Promise<string[]>;
 /** Introspect a Supabase/PostgREST table into an EntitySchema, or null. */
 export declare function introspectSupabaseTable<TData extends RowData = RowData>(options: IntrospectSupabaseOptions): Promise<EntitySchema<TData> | null>;