rimecms 0.30.2 → 0.31.0

package/dist/core/dev/vite/index.server.js

@@ -1,30 +1,108 @@
 import dotenv from 'dotenv';
-import { existsSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { RIME_DEV_CACHE_DIR } from '../../constant.server.js';
 import { ensureHasInit } from '../../ensure.server.js';
 import { logger } from '../../logger/index.server.js';
-import { INPUT_DIR, OUTPUT_DIR } from '../constants.js';
+import { getPackageInfoByKey } from '../cli/util/package.server.js';
+import { INPUT_DIR, isInstalledDependency, OUTPUT_DIR, schemaPath } from '../constants.js';
+import { findInstalledPackageRoot, findModulePair, scanModulePairs } from '../generate/runtime/index.server.js';
+import { parseExportNames } from '../generate/runtime/parse-exports.server.js';
 import { sanitize } from '../generate/sanitize/index.server.js';
 dotenv.config({ override: true });
 const dev = process.env.NODE_ENV === 'development';
+/** Picks the client or server side of a module.(server.)ts pair. When the requested side
+ *  wasn't authored (e.g. a collection's $url/$hooks, real only server-side, imported anyway by
+ *  the isomorphic index.ts a client build also needs for its field definitions), stubs each of
+ *  the *other* side's export names to `undefined` instead of returning nothing — ESM does
+ *  static named-export binding, so an empty module isn't enough, `import { x } from ...` throws
+ *  a SyntaxError at link time if `x` isn't actually exported, it doesn't lazily become
+ *  `undefined`. Harmless: server-only exports are already stripped from client-side types, so
+ *  nothing client-side ever reads the stubbed value — it only has to exist. */
+function exportFrom(entry, isServer) {
+    const target = isServer ? entry.server : entry.client;
+    if (target)
+        return `export * from '${target.replace(/\.ts$/, '.js')}';`;
+    const other = isServer ? entry.client : entry.server;
+    if (!other)
+        return '';
+    return parseExportNames(other)
+        .map((name) => name === 'default' ? 'export default undefined;' : `export const ${name} = undefined;`)
+        .join('\n');
+}
+/** Splits `<pkg>/<subpath>` or `@scope/<pkg>/<subpath>` into its package name and the rest —
+ *  a scoped name is two path segments, a plain one is one. */
+function splitPackageSpecifier(rest) {
+    const segments = rest.split('/');
+    const pkgName = rest.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
+    const subpath = segments.slice(pkgName.split('/').length).join('/');
+    return { pkgName, subpath };
+}
 export function rime() {
+    /** Two reserved names, always resolved to *the currently running app's* generated
+     *  config/schema, independent of who's asking — a third-party plugin importing
+     *  `$rime/config` gets the host app's config, never its own. Unrelated to the modules
+     *  mechanism below (a package's own client/server split): different problem, same `$rime/`
+     *  namespace only by convention. */
     const VCoreId = '$rime/config';
     const VSchemaId = '$rime/schema';
-    /** General-purpose server/browser split, usable anywhere in the app (not just rime's own
-     *  field code — see relation/index.ts for the first user). `import { x } from '$rime/runtime'`
-     *  resolves to a sibling `server.ts` (server builds) or `browser.ts` (browser builds) next
-     *  to whichever file does the importing — the importer's path travels encoded in the
-     *  resolved id since `load()` only receives the id, not the importer. */
-    const VRuntimeId = '$rime/runtime';
-    const VRuntimeMarker = `\0${VRuntimeId}::`;
+    /** `$rime/modules` — a package's own client/server split, resolved relative to *whoever's
+     *  asking*, always self-contained. Two forms:
+     *
+     *  - The bare barrel, `$rime/modules`, addressed by *export name* rather than path — dev
+     *    only, live-scans this project's own `src/lib` for every `module.(server.)ts` pair (see
+     *    `regenerateModulesDeclaration` below for the matching local-dev `.d.ts`). Never ships:
+     *    a prepack step (the `generate-manifest` CLI command) AST-rewrites every `$rime/modules`
+     *    import into the qualified form below before publish, so a consumer never sees the
+     *    barrel at all.
+     *  - The qualified form, `$rime/modules/<pkg>/<path>`, always package-qualified — even for a
+     *    package's own internal references to itself. Two ways it resolves, both in `resolveId`
+     *    (not `load`, which never receives `importer`): `<pkg>` equals this project's own
+     *    `package.json` name → self-reference, resolved directly off this project's own
+     *    `src/lib`. Otherwise → an installed dependency, its root found by walking up
+     *    `node_modules/<pkg>` from the importer's own directory (`findInstalledPackageRoot` —
+     *    pure directory existence, no `exports`-conditions matching, since a package whose
+     *    `exports` map declares only conditions neither `require.resolve` nor
+     *    `import.meta.resolve` use fails to resolve through either) and its shipped
+     *    `dist/.rime-modules.json` read directly — no directory-convention guessing beyond that,
+     *    immune to Vite's dep-optimizer flattening a package (reading a known filename off disk
+     *    never touches the import graph the optimizer rewrites). Full design:
+     *    docs/plans/imports.md. */
+    const VModulesId = '$rime/modules';
+    const VModulesPrefix = '$rime/modules/';
+    const ownPackageName = getPackageInfoByKey('name');
+    // Separates a resolved root from the original specifier inside one virtual module id — never
+    // appears in a real path or a JS specifier, so it's an unambiguous split point. Only the
+    // third-party qualified-form case needs it (the root has to travel with the id since load()
+    // doesn't receive importer); the barrel and self-reference cases carry no baked-in root.
+    const ROOT_SEP = '\x01';
     const resolvedVModule = (name) => '\0' + name;
+    // Local-dev types for the $rime/modules barrel — declares every module.(server.)ts pair
+    // currently under this project's own src/lib, live. Regenerated on startup and whenever a
+    // module file appears/changes/disappears (see the watcher below) — never ships, gitignored,
+    // same treatment as app.generated.d.ts/rime.generated.d.ts.
+    //
+    // $lib/-aliased paths, not bare relative/absolute ones — verified directly (a plain relative
+    // or absolute `export * from` inside a `declare module` block silently resolves to no
+    // exports at all; TS only picks up the re-exported names through a real configured alias).
+    function regenerateModulesDeclaration() {
+        const libDir = path.resolve(process.cwd(), 'src/lib');
+        const pairs = scanModulePairs(libDir);
+        const exports = Array.from(pairs.values())
+            .map((entry) => entry.server || entry.client)
+            .filter(Boolean)
+            .map((file) => `$lib/${path.relative(libDir, file).split(path.sep).join('/')}`.replace(/\.ts$/, '.js'))
+            .map((aliased) => `  export * from '${aliased}';`)
+            .join('\n');
+        writeFileSync(path.resolve(process.cwd(), 'src/rime.modules.generated.d.ts'), `declare module '$rime/modules' {\n${exports}\n}\n`);
+    }
     return {
         name: 'virtual-rime',
         configureServer(server) {
             // Add a listener for when the server starts
             server.httpServer?.once('listening', () => {
                 dev && ensureHasInit();
+                regenerateModulesDeclaration();
                 // Check if we need to rebuild
                 const shouldRebuild = process.argv.includes('--rebuild');
                 if (shouldRebuild && existsSync(RIME_DEV_CACHE_DIR)) {
@@ -32,11 +110,30 @@ export function rime() {
                     logger.info('--rebuild : node_modules/.rime folder deleted');
                 }
             });
-            // Add a watcher for sanitizing config changes
-            // and trigger schema/routes/types generation
-            server.watcher.on('change', async (modulePath) => {
-                if (modulePath.includes(`src/lib/${INPUT_DIR}`) &&
-                    !modulePath.includes(`src/lib/${OUTPUT_DIR}`)) {
+            // module.ts/module.server.ts appearing, changing, or disappearing under this project's
+            // own src/lib — regenerate the $rime/modules declaration above so the IDE picks up the
+            // new/changed/removed split immediately. Listens on add/unlink too, unlike the config
+            // watcher below (change-only) — a new split is exactly as likely to be a brand new file
+            // as an edit to an existing one.
+            const isModuleFile = (p) => /[/\\]module(\.server)?\.ts$/.test(p) &&
+                p.includes(`${path.sep}src${path.sep}lib${path.sep}`);
+            server.watcher.on('add', (p) => isModuleFile(p) && regenerateModulesDeclaration());
+            server.watcher.on('unlink', (p) => isModuleFile(p) && regenerateModulesDeclaration());
+            server.watcher.on('change', (p) => isModuleFile(p) && regenerateModulesDeclaration());
+            // Add a watcher for sanitizing config changes and triggering schema/routes/types
+            // generation. Debounced + single-flight: a config change is rarely one file (e.g. a
+            // plugin swap copying several files under +rime/ at once) — without this, each file
+            // fires its own overlapping sanitize()+generate()+migrate() run against the same db/
+            // and sqlite file, racing each other.
+            let reloadTimer = null;
+            let reloadInFlight = null;
+            let reloadQueued = false;
+            async function runConfigReload() {
+                if (reloadInFlight) {
+                    reloadQueued = true;
+                    return;
+                }
+                reloadInFlight = (async () => {
                     // Sanitize the config client/server
                     try {
                         await sanitize();
@@ -47,7 +144,11 @@ export function rime() {
                     }
                     // Trigger generation
                     try {
-                        const mod = await server.ssrLoadModule(`src/lib/${OUTPUT_DIR}/rime.config.server.ts`);
+                        // ssrLoadModule wants the real .ts file path, not a $lib/*.js-style import
+                        // specifier — different consumer than configImportPaths() (used for generated
+                        // source code), so computed directly here.
+                        const serverConfigPath = `src/lib/${OUTPUT_DIR}/rime.config.server.ts`;
+                        const mod = await server.ssrLoadModule(serverConfigPath);
                         // The config's default export is the createRime() promise; ssrLoadModule
                         // only awaits the module's synchronous evaluation, so we must await it
                         // directly to observe init errors (e.g. invalid config) here instead of
@@ -57,7 +158,25 @@ export function rime() {
                     catch (error) {
                         logger.error('Failed to reload the config', error.message);
                     }
+                })();
+                await reloadInFlight;
+                reloadInFlight = null;
+                if (reloadQueued) {
+                    reloadQueued = false;
+                    await runConfigReload();
                 }
+            }
+            server.watcher.on('change', (modulePath) => {
+                const isConfigChange = modulePath.includes(`src/lib/${INPUT_DIR}`) &&
+                    !modulePath.includes(`src/lib/${OUTPUT_DIR}`);
+                if (!isConfigChange)
+                    return;
+                if (reloadTimer)
+                    clearTimeout(reloadTimer);
+                reloadTimer = setTimeout(() => {
+                    reloadTimer = null;
+                    runConfigReload();
+                }, 150);
             });
         },
         config() {
@@ -66,12 +185,7 @@ export function rime() {
                     external: ['sharp']
                 },
                 optimizeDeps: {
-                    // rimecms/fields and rimecms/panel must not be pre-bundled: esbuild flattens
-                    // their source files into one chunk, which erases the per-file identity that
-                    // the $rime/runtime virtual module (see resolveId/load below) relies on to find
-                    // each field's sibling runtime.ts/runtime.server.ts — pre-bundling makes the
-                    // "importer" resolve to the chunk itself instead of the real source file.
-                    exclude: ['sharp', 'rimecms', 'rimecms/fields', 'rimecms/panel'],
+                    exclude: ['sharp'],
                     include: ['@lucide/svelte']
                 },
                 build: {
@@ -79,6 +193,14 @@ export function rime() {
                         external: ['sharp']
                     },
                     target: 'es2022'
+                },
+                server: {
+                    watch: {
+                        // db/*.sqlite (+ its -wal/-shm sidecars) and logs/ are runtime data, not source —
+                        // every write (e.g. saving a document) touches them, and without this Vite's default
+                        // whole-project-root watch treats that churn as a source change and force-reloads.
+                        ignored: ['**/db/**', '**/logs/**']
+                    }
                 }
             };
         },
@@ -91,12 +213,18 @@ export function rime() {
                 }
                 return null;
             }
-            if (process.env.IS_PACKAGE_DEV && file.includes('src/lib/core/config')) {
+            if (!isInstalledDependency(import.meta.url) && file.includes('src/lib/core/config')) {
                 logger.info('reload core config');
                 const module = invalidateVModule(VCoreId);
                 if (module)
                     return [module];
             }
+            if (/[/\\]module(\.server)?\.ts$/.test(file) &&
+                file.includes(`${path.sep}src${path.sep}lib${path.sep}`)) {
+                const module = invalidateVModule(VModulesId);
+                if (module)
+                    return [module];
+            }
         },
         resolveId(id, importer) {
             if (id === VCoreId) {
@@ -105,29 +233,95 @@ export function rime() {
             if (id === VSchemaId) {
                 return resolvedVModule(id);
             }
-            if (id === VRuntimeId && importer) {
-                return `${VRuntimeMarker}${importer}`;
+            if (id === VModulesId) {
+                return resolvedVModule(id); // barrel, no root to bake in — load() always scans this project's own src/lib
+            }
+            if (id.startsWith(VModulesPrefix)) {
+                const { pkgName } = splitPackageSpecifier(id.slice(VModulesPrefix.length));
+                if (pkgName === ownPackageName) {
+                    return resolvedVModule(id); // self-reference: load() scans this project's own src/lib too
+                }
+                if (!importer) {
+                    throw new Error(`$rime/modules: '${id}' has no importer to resolve '${pkgName}' from`);
+                }
+                // Third-party dependency: find its installed root now, while `importer` is still
+                // available (load() doesn't receive it) — baked into the id via ROOT_SEP. Walks up
+                // node_modules directly (see findInstalledPackageRoot) rather than resolving through
+                // the package's own `exports` map — confirmed in practice that both `require.resolve`
+                // and `import.meta.resolve` gate on a condition set matching, and a package whose
+                // exports only declare conditions neither uses (rime's own included: `types`/`svelte`/
+                // `import`, no `require`/`default`) fails to resolve at all through either.
+                const pkgRoot = findInstalledPackageRoot(pkgName, path.dirname(importer));
+                return resolvedVModule(`${pkgRoot}${ROOT_SEP}${id}`);
             }
             return null;
         },
-        load(id) {
+        async load(id) {
             const isServer = this.environment?.config?.consumer === 'server';
             if (id === resolvedVModule(VCoreId)) {
                 const corePath = isServer ? 'rimecms/config/server' : 'rimecms/config';
                 return `export * from '${corePath}';`;
             }
             if (id === resolvedVModule(VSchemaId) && isServer) {
-                const schemaPath = path.resolve(process.cwd(), `src/lib/${OUTPUT_DIR}/schema.server.ts`);
-                if (existsSync(schemaPath)) {
-                    const modulePath = schemaPath.replace('.ts', '.js');
+                // Mirrors write.server.ts (adapter-sqlite/generate-schema) — the adapter itself never
+                // needed to change for this, it already goes through this virtual module instead of a
+                // hardcoded path.
+                const schemaFilePath = schemaPath();
+                if (existsSync(schemaFilePath)) {
+                    const modulePath = schemaFilePath.replace('.ts', '.js');
                     return `export * from '${modulePath}'; export { default } from '${modulePath}';`;
                 }
             }
-            if (id.startsWith(VRuntimeMarker)) {
-                const importer = id.slice(VRuntimeMarker.length);
-                const dir = path.dirname(importer);
-                const target = path.join(dir, isServer ? 'runtime.server.ts' : 'runtime.ts');
-                return `export * from '${target.replace(/\.ts$/, '.js')}';`;
+            if (id === resolvedVModule(VModulesId)) {
+                // Dev-mode barrel — re-exports every module.(server.)ts pair found under this
+                // project's own src/lib, live. Never ships: prepack rewrites every '$rime/modules'
+                // import into a qualified one before publish, so this only ever runs during dev.
+                const pairs = scanModulePairs(path.resolve(process.cwd(), 'src/lib'));
+                return Array.from(pairs.values())
+                    .map((entry) => exportFrom(entry, isServer))
+                    .filter(Boolean)
+                    .join('\n');
+            }
+            // Self-reference qualified form — resolveId returned this bare, no root baked in
+            // (matches VModulesId's shape above): resolve directly off this project's own src/lib.
+            if (id.startsWith(resolvedVModule(VModulesPrefix))) {
+                const subpath = splitPackageSpecifier(id.slice(resolvedVModule(VModulesPrefix).length)).subpath;
+                const pair = findModulePair(path.resolve(process.cwd(), 'src/lib'), subpath);
+                if (!pair)
+                    throw new Error(`${id.slice(1)}: doesn't resolve under this project's own src/lib`);
+                return exportFrom(pair, isServer);
+            }
+            // Third-party qualified form — resolveId baked the resolved package root in via
+            // ROOT_SEP: read what it shipped at prepack, don't guess.
+            {
+                const modulesSepIndex = id.indexOf(ROOT_SEP);
+                const modulesSpecifier = modulesSepIndex === -1 ? '' : id.slice(modulesSepIndex + 1);
+                if (modulesSpecifier.startsWith(VModulesPrefix)) {
+                    const pkgRoot = id.slice(1, modulesSepIndex);
+                    const rest = modulesSpecifier.slice(VModulesPrefix.length);
+                    const { pkgName, subpath } = splitPackageSpecifier(rest);
+                    const distDir = path.join(pkgRoot, 'dist');
+                    const manifestPath = path.join(distDir, '.rime-modules.json');
+                    if (!existsSync(manifestPath)) {
+                        throw new Error(`$rime/modules/${pkgName}: no manifest at ${manifestPath} — does ${pkgName} run 'rime generate-manifest' at prepack?`);
+                    }
+                    const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+                    const pair = manifest[subpath];
+                    if (!pair) {
+                        throw new Error(`$rime/modules/${pkgName}/${subpath}: not found in ${pkgName}'s manifest`);
+                    }
+                    // Manifest entries are stored relative to *that package's own* dist/ (written by
+                    // generate-manifest on whatever machine packed it) - re-rooted onto distDir (this
+                    // installed copy's real, resolved location) here, not trusted as absolute. An
+                    // absolute path baked in at pack time would silently read the package author's own
+                    // working-copy dist/ instead of what's actually installed here whenever both
+                    // happen to exist on the same machine (exactly what authoring rime itself hit).
+                    const resolvedPair = {
+                        client: pair.client ? path.join(distDir, pair.client) : '',
+                        server: pair.server ? path.join(distDir, pair.server) : ''
+                    };
+                    return exportFrom(resolvedPair, isServer);
+                }
             }
             return null;
         }

package/dist/core/ensure.server.d.ts

@@ -1,14 +1,15 @@
 import type { BuiltCollection } from '../types.js';
 /**
- * Ensure sanitize config exists
+ * Ensure sanitize config exists — the generated server config inside rime.generated/.
  */
 export declare function ensureGeneratedConfig(): string;
 /**
- * Ensure user config exists
+ * Ensure user config exists — the src/lib/+rime/ folder convention.
  */
 export declare function ensureUserConfigExist(): void;
 /**
- * Ensure schema exists
+ * Ensure schema exists (see adapter-sqlite/generate-schema/write.server.ts, which writes to
+ * the same path).
  */
 export declare function ensureSchema(): void;
 /**

package/dist/core/ensure.server.js

@@ -1,9 +1,9 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
-import { INPUT_DIR, OUTPUT_DIR } from './dev/constants.js';
+import { INPUT_DIR, OUTPUT_DIR, schemaPath } from './dev/constants.js';
 const projectRoot = process.cwd();
 /**
- * Ensure sanitize config exists
+ * Ensure sanitize config exists — the generated server config inside rime.generated/.
  */
 export function ensureGeneratedConfig() {
     const configGeneratedPath = path.resolve(projectRoot, 'src/lib', OUTPUT_DIR, 'rime.config.server.ts');
@@ -13,20 +13,20 @@ export function ensureGeneratedConfig() {
     return path.join('$lib', OUTPUT_DIR, 'rime.config.server.js');
 }
 /**
- * Ensure user config exists
+ * Ensure user config exists — the src/lib/+rime/ folder convention.
  */
 export function ensureUserConfigExist() {
-    const configPath = path.resolve(projectRoot, 'src/lib', INPUT_DIR, 'rime.config.ts');
-    if (!existsSync(configPath)) {
+    const folderConfig = path.resolve(projectRoot, 'src/lib', INPUT_DIR, 'rime.config.server.ts');
+    if (!existsSync(folderConfig)) {
         throw new Error('Unable to find config, did you run rime init');
     }
 }
 /**
- * Ensure schema exists
+ * Ensure schema exists (see adapter-sqlite/generate-schema/write.server.ts, which writes to
+ * the same path).
  */
 export function ensureSchema() {
-    const schemaPath = path.resolve(projectRoot, 'src/lib', OUTPUT_DIR, 'schema.server.ts');
-    if (!existsSync(schemaPath)) {
+    if (!existsSync(schemaPath(projectRoot))) {
         throw new Error('Unable to find schema, did you run rime init');
     }
 }

package/dist/core/fields/builders/boolean-builder.d.ts

@@ -1,5 +1,4 @@
 import type { DefaultValueFn, FieldValidationFunc, FormField } from '../../../fields/types.js';
-import type { DataType } from './form-field-builder.js';
 import { FormFieldBuilder } from './form-field-builder.js';
 type BooleanField = FormField & {
     type: any;
@@ -10,7 +9,7 @@ type BooleanField = FormField & {
 export declare class BooleanFieldBuilder<T extends BooleanField = BooleanField> extends FormFieldBuilder<T> {
     constructor(name: string, type: string);
     defaultValue(value: boolean | DefaultValueFn<boolean>): this;
-    get dataType(): DataType;
+    get dataType(): 'boolean';
     compile(): import("../../../util/types.js").WithoutBuilders<T> & {
         component: import("svelte").Component<any>;
         cell?: import("svelte").Component<{

package/dist/core/fields/builders/field-builder.d.ts

@@ -7,14 +7,14 @@ import type { Field, FieldAccess } from '../../../fields/types.js';
  *  generically-typed prop — stay bivariant on their params, exactly like the
  *  class methods this replaced. Property syntax would make TS check those
  *  params strictly/contravariantly and break that assignability. */
-export type FieldRun = {
-    canRead(...args: Parameters<FieldAccess>): boolean;
-    canCreate(...args: Parameters<FieldAccess>): boolean;
-    canUpdate(...args: Parameters<FieldAccess>): boolean;
+export type FieldUse = {
+    accessRead(...args: Parameters<FieldAccess>): boolean;
+    accessCreate(...args: Parameters<FieldAccess>): boolean;
+    accessUpdate(...args: Parameters<FieldAccess>): boolean;
+    generateType(): string;
 };
 export declare class FieldBuilder<T extends Field = Field> {
     field: T;
-    _metaUrl?: string;
     constructor(type: string);
     get name(): string;
     className(str: string): this;
@@ -47,9 +47,14 @@ export declare class FieldBuilder<T extends Field = Field> {
      *  (`T extends FieldBuilder<any>`) strictly, not with the bivariant
      *  leniency normal overrides get, so a param-less base signature breaks
      *  assignability everywhere. */
-    get run(): FieldRun;
+    get use(): FieldUse;
     get component(): Component<any> | null;
     get cell(): Component<{
         value: any;
     }> | null;
+    /** The type-generation script's only entry point (via `.use.generateType()`) — `protected`
+     *  so it never surfaces on the fluent chain (`text('title').generateType()` would be a
+     *  compile error), while staying a real overridable method so every concrete field can
+     *  provide its own, unlike a private `#field` which can't be polymorphically overridden. */
+    protected generateType(): string;
 }

package/dist/core/fields/builders/field-builder.js

@@ -1,6 +1,5 @@
 export class FieldBuilder {
     field;
-    _metaUrl;
     constructor(type) {
         this.field = {
             name: '',
@@ -49,14 +48,15 @@ export class FieldBuilder {
      *  (`T extends FieldBuilder<any>`) strictly, not with the bivariant
      *  leniency normal overrides get, so a param-less base signature breaks
      *  assignability everywhere. */
-    get run() {
+    get use() {
         return {
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
-            canRead: (..._args) => true,
+            accessRead: (..._args) => true,
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
-            canCreate: (..._args) => true,
+            accessCreate: (..._args) => true,
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
-            canUpdate: (..._args) => true
+            accessUpdate: (..._args) => true,
+            generateType: () => this.generateType()
         };
     }
     get component() {
@@ -65,4 +65,11 @@ export class FieldBuilder {
     get cell() {
         return null;
     }
+    /** The type-generation script's only entry point (via `.use.generateType()`) — `protected`
+     *  so it never surfaces on the fluent chain (`text('title').generateType()` would be a
+     *  compile error), while staying a real overridable method so every concrete field can
+     *  provide its own, unlike a private `#field` which can't be polymorphically overridden. */
+    generateType() {
+        return '';
+    }
 }

package/dist/core/fields/builders/form-field-builder.d.ts

@@ -2,16 +2,16 @@ import type { FieldPanelTableConfig } from '../../../types.js';
 import type { Dic } from '../../../util/types.js';
 import type { RequestEvent } from '@sveltejs/kit';
 import type { FieldAccess, FieldHook, FieldHookClient, FieldHookContext, FieldHookShared, FieldValidationFunc, FieldWidth, FormField } from '../../../fields/types.js';
-import { FieldBuilder, type FieldRun } from './field-builder.js';
+import { FieldBuilder, type FieldUse } from './field-builder.js';
 /** Adapter-agnostic storage primitive — column syntax only, not default-value semantics. */
 export type DataType = 'text' | 'boolean' | 'number' | 'timestamp' | 'json';
-/** Method-syntax, same reasoning as `FieldRun` — keeps `run`'s params
+/** Method-syntax, same reasoning as `FieldUse` — keeps `run`'s params
  *  bivariant across concrete field types so e.g. `SlugFieldBuilder` still
  *  satisfies a prop typed `FormFieldBuilder<FormField>`. */
-export type FormFieldRun<T extends FormField> = FieldRun & {
+export type FormFieldUse<T extends FormField> = FieldUse & {
     isEmpty(value: unknown): boolean;
     validate(value: unknown, context: Parameters<FieldValidationFunc<T>>[1]): true | string;
-    condition(doc: Dic, siblings: Dic): boolean;
+    isVisible(doc: Dic, siblings: Dic): boolean;
     onChange(value: unknown, context: Parameters<FieldHookClient>[1]): void;
     beforeRead(value: unknown, context: Omit<FieldHookContext<T>, 'config'>): Promise<any>;
     beforeSave(value: unknown, context: FieldHookContext<T>): Promise<any>;
@@ -38,15 +38,9 @@ export type FieldReference = FieldReferenceOptions & {
     table: string;
 };
 export declare class FormFieldBuilder<T extends FormField = FormField> extends FieldBuilder<T> {
-    /** Every concrete leaf field builder is expected to implement a
-     *  `get dataType(): DataType` accessor (see e.g. `$lib/fields/text/index.ts`).
-     *  Not declared here — TS doesn't allow `declare` on accessors in this
-     *  project's config, and a plain base field would conflict with subclasses
-     *  that need a computed getter (e.g. `select`, whose dataType depends on
-     *  `many`). Container builders (Group/Tabs/Blocks/Tree) never get asked,
-     *  since the adapter's tree-walker special-cases them before reaching the
-     *  generic column-rendering branch; `column.server.ts` reads `.dataType`
-     *  via a narrow cast for the same reason it already casts `unique`. */
+    /** Column storage type, used to generate the DB schema. Every field
+     *  builder that stores data must define its own. */
+    get dataType(): DataType;
     _references: FieldReference | null;
     constructor(name: string, type: string);
     label(label: string): this;
@@ -83,7 +77,7 @@ export declare class FormFieldBuilder<T extends FormField = FormField> extends F
     onChange(hook: FieldHookClient): this;
     /** Behavior the builder runs on your behalf — invoking a stored function or
      *  hook list, not a data read (see `.get` for that). */
-    get run(): FormFieldRun<T>;
+    get use(): FormFieldUse<T>;
     hint(hint: string): this;
     clone(): typeof this;
     /** Server-side schema concern, same family as $beforeRead/$beforeSave. */
@@ -91,4 +85,7 @@ export declare class FormFieldBuilder<T extends FormField = FormField> extends F
     $beforeRead(hook: FieldHook<T>): this;
     $beforeSave(hook: FieldHook<T>): this;
     beforeValidate(hook: FieldHookShared): this;
+    /** Fallback for a data-bearing field that doesn't override this: still shows up in the
+     *  generated document type (as `any`) instead of silently vanishing from it. */
+    protected generateType(): string;
 }

package/dist/core/fields/builders/form-field-builder.js

@@ -2,15 +2,11 @@ import { capitalize } from '../../../util/string.js';
 import cloneDeep from 'clone-deep';
 import { FieldBuilder } from './field-builder.js';
 export class FormFieldBuilder extends FieldBuilder {
-    /** Every concrete leaf field builder is expected to implement a
-     *  `get dataType(): DataType` accessor (see e.g. `$lib/fields/text/index.ts`).
-     *  Not declared here — TS doesn't allow `declare` on accessors in this
-     *  project's config, and a plain base field would conflict with subclasses
-     *  that need a computed getter (e.g. `select`, whose dataType depends on
-     *  `many`). Container builders (Group/Tabs/Blocks/Tree) never get asked,
-     *  since the adapter's tree-walker special-cases them before reaching the
-     *  generic column-rendering branch; `column.server.ts` reads `.dataType`
-     *  via a narrow cast for the same reason it already casts `unique`. */
+    /** Column storage type, used to generate the DB schema. Every field
+     *  builder that stores data must define its own. */
+    get dataType() {
+        throw new Error(`${this.constructor.name} does not implement dataType`);
+    }
     _references = null;
     constructor(name, type) {
         super(type);
@@ -100,7 +96,7 @@ export class FormFieldBuilder extends FieldBuilder {
     }
     /** Behavior the builder runs on your behalf — invoking a stored function or
      *  hook list, not a data read (see `.get` for that). */
-    get run() {
+    get use() {
         return {
             isEmpty: (value) => this.field.isEmpty(value),
             validate: (value, context) => {
@@ -109,7 +105,7 @@ export class FormFieldBuilder extends FieldBuilder {
                 }
                 return true;
             },
-            condition: (doc, siblings) => {
+            isVisible: (doc, siblings) => {
                 if (this.field.condition) {
                     try {
                         return this.field.condition(doc, siblings);
@@ -121,9 +117,9 @@ export class FormFieldBuilder extends FieldBuilder {
                 }
                 return true;
             },
-            canRead: (...args) => !!this.field.access?.read?.(...args),
-            canCreate: (...args) => !!this.field.access?.create?.(...args),
-            canUpdate: (...args) => !!this.field.access?.update?.(...args),
+            accessRead: (...args) => !!this.field.access?.read?.(...args),
+            accessCreate: (...args) => !!this.field.access?.create?.(...args),
+            accessUpdate: (...args) => !!this.field.access?.update?.(...args),
             onChange: (value, context) => {
                 for (const hook of this.field.hooks?.onChange ?? []) {
                     hook(value, context);
@@ -153,7 +149,8 @@ export class FormFieldBuilder extends FieldBuilder {
             defaultValue: (context = {}) => {
                 const value = this.field.defaultValue;
                 return typeof value === 'function' ? value(context) : value;
-            }
+            },
+            generateType: () => this.generateType()
         };
     }
     hint(hint) {
@@ -192,4 +189,9 @@ export class FormFieldBuilder extends FieldBuilder {
         this.field.hooks.beforeValidate.push(hook);
         return this;
     }
+    /** Fallback for a data-bearing field that doesn't override this: still shows up in the
+     *  generated document type (as `any`) instead of silently vanishing from it. */
+    generateType() {
+        return `${this.field.name}${this.get.required ? '' : '?'}: any`;
+    }
 }

package/dist/core/fields/util.js

@@ -56,7 +56,7 @@ export const emptyValuesFromFieldConfig = (arr) => {
         }
         // Handle default values
         else {
-            emptyValue = config.run.defaultValue();
+            emptyValue = config.use.defaultValue();
         }
         return [config.name, emptyValue];
     }));