@svgrid/enterprise 3.1.17 → 3.1.18

package/dist/sources/introspect-supabase.js

@@ -1,4 +1,5 @@
 import { buildEntitySchema } from './schema-from-columns.js';
+import { hideBaseOrderColumn } from '../studio/introspect-db.js';
 const mapOpenApiType = (prop) => {
     if (Array.isArray(prop.enum))
         return 'enum';
@@ -98,28 +99,44 @@ 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. */
 export async function listSupabaseTables(url, key, fetchFn = globalThis.fetch) {
     const base = url.replace(/\/+$/, '');
+    const at = `${base}/rest/v1/`;
     let res;
     try {
-        res = await fetchFn(`${base}/rest/v1/`, { headers: { apikey: key, Authorization: `Bearer ${key}`, Accept: 'application/json' } });
+        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 { /* no body */ }
+        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 ?? {};
     // PostgREST also lists RPCs under `paths` as `/rpc/...`; `definitions` are the tables/views.
     return Object.keys(defs).sort((a, b) => a.localeCompare(b));
 }
@@ -133,5 +150,6 @@ export async function introspectSupabaseTable(options) {
     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)) };
 }

package/dist/sources/supabase.d.ts

@@ -38,5 +38,15 @@ export type SupabaseDataSourceConfig<TData extends RowData> = {
      * pivoted request is answered as plain grouping, with a warning once.
      */
     pivot?: (request: ServerRequest) => Promise<ServerResult<TData>>;
+    /**
+     * How rows come back when the request has no sort, e.g. creation order.
+     * Default: a `created_at` / `inserted_at` field when the schema has one.
+     * The primary key is appended to every leaf order as the tie-breaker, so
+     * paging with `range` is deterministic.
+     */
+    defaultOrder?: ReadonlyArray<{
+        field: string;
+        desc?: boolean;
+    }>;
 };
 export declare function createSupabaseDataSource<TData extends RowData>(config: SupabaseDataSourceConfig<TData>): WritableDataSource<TData>;

package/dist/sources/supabase.js

@@ -1,4 +1,5 @@
 import { resolveIdField } from '../schema.js';
+import { unsortedOrder } from '../sveltekit/sql-source.js';
 import { nudgeEnterpriseFor } from '../license.js';
 import { normalizeFilters } from './filters.js';
 const sanitize = (term) => term.replace(/[%,()]/g, '');
@@ -9,6 +10,8 @@ export function createSupabaseDataSource(config) {
     const searchColumns = config.searchColumns ??
         schema.fields.filter((f) => f.type === 'text' || f.type === 'enum').map((f) => String(f.field));
     let warnedPivot = false;
+    const key = schema.fields.some((f) => f.field === idField) ? idField : null;
+    const unsorted = unsortedOrder(schema, config.defaultOrder);
     return {
         async getRows(request) {
             // ---- Server-side pivot ----------------------------------------------
@@ -112,8 +115,14 @@ export function createSupabaseDataSource(config) {
                 }
             }
             else {
-                for (const s of request.sortModel)
-                    q = q.order(s.id, { ascending: !s.desc });
+                // Without an order PostgREST pages in no fixed order. Unsorted rows go
+                // in creation order where it is known; the key breaks ties.
+                const sorted = request.sortModel.map((s) => ({ field: s.id, desc: !!s.desc }));
+                const order = sorted.length ? sorted : unsorted;
+                for (const o of order)
+                    q = q.order(o.field, { ascending: !o.desc });
+                if (key && !order.some((o) => o.field === key))
+                    q = q.order(key, { ascending: true });
             }
             const { data, count, error } = await q.range(request.startRow, request.endRow - 1);
             if (error)

package/dist/studio/cli.d.ts

@@ -35,6 +35,8 @@ export type AddResult = {
     schema: EntitySchema;
     /** Paths written, in order. */
     written: string[];
+    /** Existing files without managed markers, left alone; the new version went to `parkedAs`. */
+    conflicts: ParkedFile[];
     verify: VerifyResult;
 };
 /** Resolve an EntitySchema from whichever input was provided. */
@@ -44,9 +46,16 @@ export declare function resolveSchema(options: AddOptions, io: StudioIO): Promis
  * --from` path), linked so foreign keys become working relation lookups.
  */
 export declare function resolveSchemas(from: string, io: StudioIO): Promise<EntitySchema[]>;
+/** A generated file that was not written over an existing one, and where it went instead. */
+export type ParkedFile = {
+    path: string;
+    parkedAs: string;
+};
 export declare function runStudioAdd(options: AddOptions, io: StudioIO): Promise<AddResult>;
 export type AddAppResult = {
     written: string[];
+    /** Existing files without managed markers, left alone; the new version went to `parkedAs`. */
+    conflicts: ParkedFile[];
     verify: VerifyResult;
 };
 /**

package/dist/studio/cli.js

@@ -1,6 +1,6 @@
 import { introspectDrizzle, introspectDrizzleAll, introspectJson } from './introspect.js';
 import { introspectPrisma, introspectPrismaAll } from './introspect-prisma.js';
-import { mergeManaged, scaffold, skipUserOwned } from './scaffold.js';
+import { MANAGED_START, mergeManaged, scaffold, skipUserOwned } from './scaffold.js';
 import { scaffoldApp } from './scaffold-app.js';
 import { verifyScaffold } from './verify.js';
 /** A `.prisma` file (by extension or a `model X {` block) parses as Prisma; otherwise Drizzle. */
@@ -34,9 +34,37 @@ export async function resolveSchemas(from, io) {
         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(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);
         // User-owned companions (a screen's `handlers.ts`) carry no managed markers -
@@ -45,18 +73,24 @@ async function writeAll(files, io) {
         // HANDLERS-DESIGN.md (the round-trip contract).
         if (skipUserOwned(file, existing != null))
             continue;
+        if (existing != null && !studioApp && existing !== file.contents && !existing.includes(MANAGED_START)) {
+            const parkedAs = await freeNewPath(file.path, file.contents, io);
+            await io.writeFile(parkedAs, file.contents);
+            conflicts.push({ path: file.path, parkedAs });
+            continue;
+        }
         // Regenerating? Replace only the managed region, keep the user's edits.
         await io.writeFile(file.path, mergeManaged(existing, file.contents));
         written.push(file.path);
     }
-    return written;
+    return { written, conflicts };
 }
 export async function runStudioAdd(options, io) {
     const schema = await resolveSchema(options, io);
     const { files } = scaffold(schema, options);
-    const written = await writeAll(files, io);
+    const { written, conflicts } = await writeAll(files, io);
     const verify = await verifyScaffold(files);
-    return { schema, written, verify };
+    return { schema, written, conflicts, verify };
 }
 /** The stylesheets an `init`-generated layout imports, in cascade order. */
 const APP_STYLESHEETS = ['app.css', 'custom.css'];
@@ -118,7 +152,7 @@ async function appShellDefaults(options, io) {
  */
 export async function runStudioAddApp(schemas, options, io) {
     const { files } = scaffoldApp(schemas, await appShellDefaults(options, io));
-    const written = await writeAll(files, io);
+    const { written, conflicts } = await writeAll(files, io);
     const verify = await verifyScaffold(files);
-    return { written, verify };
+    return { written, conflicts, verify };
 }

package/dist/studio/emit-project.d.ts

@@ -65,7 +65,9 @@ export declare function studioDeployInfo(project: StudioProject): {
 /** The runtime npm deps the generated source imports, keyed by package -> range.
  *  One source of truth for package.json AND the fragment-mode dependency report. */
 export declare function runtimeDeps(project: StudioProject, allSource: string): Record<string, string>;
-export declare function emitStudioAppBundle(project: StudioProject): GeneratedFile[];
+export declare function emitStudioAppBundle(project: StudioProject, opts?: {
+    databaseUrl?: string;
+}): GeneratedFile[];
 /**
  * Emit ONLY the app content (`src/routes` + `src/lib` + `db`) to drop into an
  * EXISTING SvelteKit app - not a whole new app. Everything emitStudioProject

package/dist/studio/emit-project.js

@@ -38,20 +38,31 @@ 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);
+    // The prepared schema hides a relation's FK from the grid and shows its label
+    // column instead (`customer_id` -> `customer`), so a configured FK column maps
+    // to the label column - unless that one is configured too.
+    const shownFields = new Set(shown.map((c) => c.field));
+    const seen = 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));
     // Only inline editing keeps cells editable; form / read-only grids are not editable in place.
     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 order = visible.map((v) => `'${v.col}'`);
     const ovEntries = visible
-        .map((c) => {
+        .map(({ c, col }) => {
         const parts = [];
         if (c.header)
             parts.push(`header: ${JSON.stringify(c.header)}`);
@@ -70,7 +81,7 @@ function gridColumnsExpr(schemaVar, block, 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(', ')} };` : '';
@@ -2151,7 +2162,7 @@ function screenPage(schema, rawSchema, screen, resolve, rawResolve, accessEnable
     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;
             // An "edit" action needs the form; drop it if this grid has no edit modal.
             const actions = (b.config.rowActions ?? []).filter((a) => a.kind !== 'edit' || wantsForm);
@@ -2532,7 +2543,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);
     // Routed (SQL, or in-memory rows held on the server): a same-origin client over
     // the entity's /api route. Otherwise REST, whose source is imported from
@@ -2561,24 +2572,35 @@ function emitSsrGridScreen(schema, screen, routed, accessEnabled, screenIds, byN
     const fieldTypesLit = `{ ${formFields.map((f) => `${jsStr(f.field)}: ${jsStr(normType(f.type))}`).join(', ')} }`;
     // Relation fields render as a native <select> whose options are prefetched in
     // load - from the related entity's /api route when it has one, else from its
-    // in-process source in $lib/data (see relSource below).
+    // in-process source in $lib/data (see relSourceOf below).
     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;
+    // The grid shows each relation as its label column (`customer_id` -> `customer`).
+    // The $lib/data sources fill it with withRelationLabels; rows read through the
+    // /api route come back without it, so load wraps that client the same way:
+    // one batched `id IN (...)` lookup per relation for the ids on this page only.
+    // Names come from the RAW schema, as everywhere else that has to match
+    // withRelationLabels.
+    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))} }) }`;
+    });
     // Source acquisition:
     //  - routed: build a same-origin client over the entity's /api/<entity> route
     //    with SvelteKit's event.fetch, so validation / RBAC / triggers / audit stay
@@ -2596,6 +2618,7 @@ function emitSsrGridScreen(schema, screen, routed, accessEnabled, screenIds, byN
         'validateAll',
         ...(conditional ? ['stripHiddenValues'] : []),
         ...(isSql || relRouted ? ['createKitDataSource'] : []),
+        ...(labelSpecs.length ? ['createRelationLookup', 'withRelationLabels'] : []),
     ].join(', ');
     const dataImports = [...new Set([...(isSql ? [] : [n.sourceVar]), ...relSourceVars])];
     const sourceImport = dataImports.length ? `import { ${dataImports.join(', ')} } from '$lib/data'\n` : '';
@@ -2637,7 +2660,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} }
 }
 
@@ -3050,7 +3073,7 @@ export function emitStudioProject(project) {
         // load-only server file, and the SAME page markup renders from data.*.
         if (isSsrScreen(project, screen)) {
             if (ssrScreenShape(project, screen) === 'grid') {
-                pages.push(...emitSsrGridScreen(schema, screen, routed, accessEnabled, screensByEntity.get(screen.entity) ?? [], byName));
+                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));
@@ -5005,7 +5028,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
@@ -5024,7 +5047,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
       - run: npm install
 ${steps}`;
 }
@@ -5097,7 +5120,7 @@ function deployPlan(project) {
                 adapterModule: '@sveltejs/adapter-node',
                 adapterDep: ['@sveltejs/adapter-node', '^5.2.0'],
                 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` },
+                    { path: 'Dockerfile', description: 'Container image (multi-stage: build then run `node build`).', 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.', contents: `node_modules\n.svelte-kit\nbuild\n.env\n.env.*\n.git\n.github\n` },
                 ],
                 cli: 'npm run build && node build',
@@ -5126,7 +5149,7 @@ export 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`
+        ? `## 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`
@@ -5134,16 +5157,22 @@ function deployDocs(project, plan, envKeys, hasMigrations, opts = {}) {
     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`
         : '';
+    // Letter the options that exist, so a target without a dashboard or a deploy
+    // workflow does not skip from A to C.
+    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 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`
+        ? `## 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 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`
+        ? `## 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). */
@@ -5190,15 +5219,23 @@ 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)
+    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}`);
     // The anon key is public / browser-safe; access is governed by RLS.
     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}`);
@@ -5296,8 +5333,11 @@ export function runtimeDeps(project, allSource) {
         dependencies['mysql2'] = '^3.9.0';
     if (allSource.includes("import mssql from 'mssql'"))
         dependencies['mssql'] = '^10.0.0';
+    // 11.x and 12.0.0 ship no Node 24 prebuild, so npm falls back to node-gyp and
+    // the install fails without a C++ toolchain. 12.1+ has one; 13.x bundles N-API
+    // prebuilds that load on any Node >= 22.
     if (allSource.includes("import Database from 'better-sqlite3'"))
-        dependencies['better-sqlite3'] = '^11.0.0';
+        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'"))
@@ -5415,12 +5455,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. */
+const BETTER_SQLITE3_RANGE = '^12.1.0 || ^13.0.0';
 const 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\\//] } } },
 })
 `;
 /**
@@ -5486,14 +5534,17 @@ jobs:
 ${steps}`,
         }];
 }
-export function emitStudioAppBundle(project) {
+export 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 hasConnections = generated.some((f) => f.path === 'src/lib/connections.ts');
+    const readmeConnections = `SQL entities read their connection from \`.env\` (\`DATABASE_URL\`)${hasConnections ? ';\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 scaffold = [
         { path: 'package.json', description: 'Dependencies + scripts (npm install, npm run dev).', contents: packageJson(project, allSource) },
         { path: 'svelte.config.js', description: `SvelteKit config (${plan.adapterModule}).`, contents: svelteConfig(plan) },
@@ -5504,7 +5555,7 @@ export function emitStudioAppBundle(project) {
         rootLayoutModule(project),
         ...SCAFFOLD_STATIC,
         ...(envExample(allSource) ? [{ path: '.env.example', description: 'Environment variables the app reads (copy to .env and fill in).', contents: envExample(allSource) }] : []),
-        ...(envDotFile(allSource, project) ? [{ 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) }] : []),
+        ...(dotEnv ? [{ path: '.env', 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', description: 'App theme tokens + page styles.', contents: appCss(project) },
         // Your styles: a dedicated CSS file the layout imports AFTER app.css, so its rules
         // win. Edited in the designer's Styles panel; regenerated from the model.

package/dist/studio/emit-schema.js

@@ -986,7 +986,11 @@ export 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)}
@@ -1201,5 +1205,8 @@ export function emitStudioApp(schemas) {
         const n = namesFor(s);
         return { href: `/${n.route}`, label: n.label };
     });
-    return [...files, ...prepared.map((s) => entityScreenPage(s)), layoutFile(nav), homeFile(nav)];
+    // The layout imports ../custom.css after app.css; emitStudioAppBundle writes it
+    // too, so an app built here needs its own copy or the build cannot resolve it.
+    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), customCss];
 }

package/dist/studio/index.d.ts

@@ -31,6 +31,6 @@ export { verifyScaffold, summarizeVerify, type VerifyResult, type VerifyIssue, t
 export { UI_COMPONENT_REGISTRY, uiComponentSpec, gridPropSurface, gridApiSettableProps, gridIconGroups, GRID_CURATED_PROPS, STANDARD_UI_EVENTS, type UiPropType, type UiPropGroup, type UiComponentEvent, type UiComponentProp, type UiComponentSpec, } from './ui-components.js';
 export { buildCopilotMessages, projectFromModelText, type CopilotMessages } from './copilot-core.js';
 export { resolveDeployTarget, deployCommands, missingEnvKeys, type DeployProvider, type DeployResolution, type DeployPlanCommands, } from './deploy-cli.js';
-export { runStudioAdd, runStudioAddApp, resolveSchema, resolveSchemas, type StudioIO, type AddOptions, type AddResult, type AddAppResult, } from './cli.js';
+export { runStudioAdd, runStudioAddApp, resolveSchema, resolveSchemas, type StudioIO, type AddOptions, type AddResult, type AddAppResult, type ParkedFile, } from './cli.js';
 export { resolveIdField, schemaToColumns, schemaToFormFields, isFieldHidden, linkRelationLabels, pickLabelField, type EntitySchema, type EntityField, type EntityFieldType, } from '../schema.js';
 export { checkLicenseKey, type LicenseInfo, type LicenseStatus } from '../license-core.js';

package/dist/studio/init-flow.d.ts

@@ -59,6 +59,13 @@ export type InitResult = {
 };
 /** Parse "all", "none", a comma list of names, or a list of 1-based numbers. */
 export declare function parseSelection(answer: string, items: string[]): string[];
+/**
+ * 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.
+ */
+export declare function fileFromApp(file: string, outDir: string): string;
 /**
  * The whole guided flow: ask, build, write. Returns the project and what was
  * written so the caller can print next steps (or assert them in a test).