@byline/core 3.21.0 → 4.1.0

package/dist/codegen/index.test.node.js

@@ -28,13 +28,31 @@ describe('emitCollectionTypes', () => {
     it('emits a versioned header, verifiable body hash, and canonical formatting', () => {
         const { source, hash } = emitCollectionTypes([collection('plain', [])]);
         const body = source.split('\n').slice(4).join('\n');
-        expect(source).toMatch(/^\/\/ Generated by @byline\/core\/codegen\n\/\/ Format version: 1\n\/\/ Hash: [a-f0-9]{64}\n\n/);
-        expect(hash).toBe(createHash('sha256').update(`@byline/core/codegen:collection-types:v1\n${body}`).digest('hex'));
+        expect(source).toMatch(/^\/\/ Generated by @byline\/core\/codegen\n\/\/ Format version: 2\n\/\/ Hash: [a-f0-9]{64}\n\n/);
+        expect(hash).toBe(createHash('sha256').update(`@byline/core/codegen:collection-types:v2\n${body}`).digest('hex'));
         expect(source).toContain(`// Hash: ${hash}`);
         expect(source.endsWith('\n')).toBe(true);
         expect(source).not.toContain('\r');
         expect(source).not.toContain(';');
     });
+    it('declares every type inside the @byline/generated-types augmentation block', () => {
+        const { source } = emitCollectionTypes([collection('plain', [{ name: 'title', type: 'text' }])]);
+        expect(source).toContain("declare module '@byline/generated-types' {");
+        expect(source).toContain('  export type PlainFields = {');
+        expect(source).toContain('  export type CollectionPath = keyof CollectionFieldsByPath');
+        // No module-level type exports outside the augmentation blocks.
+        expect(source).not.toMatch(/^export /m);
+    });
+    it('emits the @byline/client Register augmentation referencing the generated registry', () => {
+        const { source } = emitCollectionTypes([collection('plain', [])]);
+        expect(source).toContain([
+            "declare module '@byline/client' {",
+            '  interface Register {',
+            "    collections: import('@byline/generated-types').CollectionFieldsByPath",
+            '  }',
+            '}',
+        ].join('\n'));
+    });
     it('sorts collections and declarations without changing field, select, or block union order', () => {
         const alpha = collection('alpha', [
             {

package/dist/config/attach-hooks.d.ts

@@ -0,0 +1,25 @@
+import type { CollectionDefinition, CollectionHooks, CollectionHooksLoader, FileField, ImageField, ServerHooksConfig, UploadHooks, UploadHooksLoader } from '../@types/index.js';
+type CollectionHookValue = CollectionHooks | CollectionHooksLoader;
+type UploadHookValue = UploadHooks | UploadHooksLoader;
+type UploadField = ImageField | FileField;
+export type HookAttachmentOperation = {
+    kind: 'collection';
+    target: CollectionDefinition;
+    hooks: CollectionHookValue | undefined;
+} | {
+    kind: 'upload';
+    target: UploadField;
+    hooks: UploadHookValue | undefined;
+};
+/**
+ * Validate a server hook registry and prepare its in-place definition updates.
+ * This phase never mutates definitions, so callers may safely abandon the plan
+ * when later initialization work fails.
+ */
+export declare function prepareHookAttachment(config: {
+    collections: readonly CollectionDefinition[];
+    hooks?: ServerHooksConfig;
+}): HookAttachmentOperation[];
+/** Commit a previously validated attachment plan synchronously. */
+export declare function commitHookAttachment(operations: readonly HookAttachmentOperation[]): void;
+export {};

package/dist/config/attach-hooks.js

@@ -0,0 +1,130 @@
+const registryCollectionHooks = new WeakMap();
+const registryUploadHooks = new WeakMap();
+/**
+ * Validate a server hook registry and prepare its in-place definition updates.
+ * This phase never mutates definitions, so callers may safely abandon the plan
+ * when later initialization work fails.
+ */
+export function prepareHookAttachment(config) {
+    const collections = new Map();
+    const uploadFields = new Map();
+    for (const collection of config.collections) {
+        assertDotFreeSegment(collection.path, `collection path "${collection.path}"`);
+        collections.set(collection.path, collection);
+        indexUploadFields(collection, uploadFields);
+    }
+    const requestedCollections = new Map(Object.entries(config.hooks?.collections ?? {}));
+    const requestedUploads = new Map(Object.entries(config.hooks?.uploads ?? {}));
+    for (const path of requestedCollections.keys()) {
+        if (!collections.has(path)) {
+            throw new Error(`ServerConfig.hooks.collections references unknown collection "${path}".`);
+        }
+    }
+    for (const path of requestedUploads.keys()) {
+        if (!uploadFields.has(path)) {
+            throw new Error(`ServerConfig.hooks.uploads references unknown or non-upload field "${path}".`);
+        }
+    }
+    const operations = [];
+    for (const collection of config.collections) {
+        const requested = requestedCollections.get(collection.path);
+        planCollectionAttachment(collection, requested, operations);
+    }
+    for (const [path, field] of uploadFields) {
+        const requested = requestedUploads.get(path);
+        planUploadAttachment(path, field, requested, operations);
+    }
+    return operations;
+}
+/** Commit a previously validated attachment plan synchronously. */
+export function commitHookAttachment(operations) {
+    for (const operation of operations) {
+        if (operation.kind === 'collection') {
+            operation.target.hooks = operation.hooks;
+            if (operation.hooks === undefined)
+                registryCollectionHooks.delete(operation.target);
+            else
+                registryCollectionHooks.set(operation.target, operation.hooks);
+            continue;
+        }
+        // Upload operations are prepared only for upload-capable fields.
+        const upload = operation.target.upload;
+        if (!upload)
+            continue;
+        upload.hooks = operation.hooks;
+        if (operation.hooks === undefined)
+            registryUploadHooks.delete(operation.target);
+        else
+            registryUploadHooks.set(operation.target, operation.hooks);
+    }
+}
+function planCollectionAttachment(collection, requested, operations) {
+    const owned = registryCollectionHooks.get(collection);
+    assertOwnershipIntact(`collection "${collection.path}"`, collection.hooks, owned);
+    if (requested === undefined) {
+        if (owned !== undefined) {
+            operations.push({ kind: 'collection', target: collection, hooks: undefined });
+        }
+        return;
+    }
+    if (owned === undefined && collection.hooks !== undefined) {
+        throw new Error(`ServerConfig.hooks.collections cannot replace definition-authored hooks on collection "${collection.path}".`);
+    }
+    if (requested !== collection.hooks) {
+        operations.push({ kind: 'collection', target: collection, hooks: requested });
+    }
+}
+function planUploadAttachment(path, field, requested, operations) {
+    const owned = registryUploadHooks.get(field);
+    assertOwnershipIntact(`upload field "${path}"`, field.upload?.hooks, owned);
+    if (requested === undefined) {
+        if (owned !== undefined) {
+            operations.push({ kind: 'upload', target: field, hooks: undefined });
+        }
+        return;
+    }
+    if (owned === undefined && field.upload?.hooks !== undefined) {
+        throw new Error(`ServerConfig.hooks.uploads cannot replace definition-authored hooks on upload field "${path}".`);
+    }
+    if (requested !== field.upload?.hooks) {
+        operations.push({ kind: 'upload', target: field, hooks: requested });
+    }
+}
+function assertOwnershipIntact(label, current, owned) {
+    if (owned !== undefined && current !== owned) {
+        throw new Error(`Registry-owned hooks on ${label} changed outside ServerConfig.hooks; refusing to overwrite definition state.`);
+    }
+}
+function indexUploadFields(collection, uploadFields) {
+    const leafPaths = new Map();
+    const walk = (fields, prefix) => {
+        for (const field of fields) {
+            assertDotFreeSegment(field.name, `field name "${field.name}" in collection "${collection.path}"`);
+            const path = [...prefix, field.name];
+            if ((field.type === 'file' || field.type === 'image') && field.upload !== undefined) {
+                const canonical = [collection.path, ...path].join('.');
+                const previous = leafPaths.get(field.name);
+                if (previous !== undefined) {
+                    throw new Error(`Collection "${collection.path}" has duplicate upload-capable leaf name "${field.name}" at "${previous}" and "${canonical}". Upload leaf names must be unique within a collection.`);
+                }
+                leafPaths.set(field.name, canonical);
+                uploadFields.set(canonical, field);
+            }
+            if (field.type === 'group' || field.type === 'array') {
+                walk(field.fields, path);
+            }
+            else if (field.type === 'blocks') {
+                for (const block of field.blocks) {
+                    assertDotFreeSegment(block.blockType, `block type "${block.blockType}" in collection "${collection.path}"`);
+                    walk(block.fields, [...path, block.blockType]);
+                }
+            }
+        }
+    };
+    walk(collection.fields, []);
+}
+function assertDotFreeSegment(segment, label) {
+    if (segment.length === 0 || segment.includes('.')) {
+        throw new Error(`${label} must be a non-empty, dot-free hook registry path segment.`);
+    }
+}

package/dist/config/attach-hooks.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/attach-hooks.test.node.js

@@ -0,0 +1,173 @@
+import { describe, expect, it, vi } from 'vitest';
+import { resolveHooks, resolveUploadHooks } from '../@types/collection-types.js';
+import { initBylineCore } from '../core.js';
+import { commitHookAttachment, prepareHookAttachment } from './attach-hooks.js';
+function collection(path = 'documents') {
+    return {
+        path,
+        labels: { singular: 'Document', plural: 'Documents' },
+        fields: [{ name: 'title', type: 'text' }],
+    };
+}
+function nestedUploadCollection() {
+    const nested = { name: 'asset', type: 'file', upload: {} };
+    const arrayFile = { name: 'publicationFile', type: 'file', upload: {} };
+    const blockFile = { name: 'backgroundImage', type: 'file', upload: {} };
+    return {
+        definition: {
+            path: 'documents',
+            labels: { singular: 'Document', plural: 'Documents' },
+            fields: [
+                { name: 'metadata', type: 'group', fields: [nested] },
+                {
+                    name: 'files',
+                    type: 'array',
+                    fields: [{ name: 'filesGroup', type: 'group', fields: [arrayFile] }],
+                },
+                {
+                    name: 'content',
+                    type: 'blocks',
+                    blocks: [{ blockType: 'hero', fields: [blockFile] }],
+                },
+            ],
+        },
+        nested,
+        arrayFile,
+        blockFile,
+    };
+}
+describe('server hook attachment', () => {
+    it('prepares without mutation, then attaches collection and canonical nested upload hooks', async () => {
+        const { definition, nested, arrayFile, blockFile } = nestedUploadCollection();
+        const collectionHooks = {};
+        const nestedHooks = {};
+        const arrayLoader = vi.fn(() => Promise.resolve({}));
+        const blockHooks = {};
+        const operations = prepareHookAttachment({
+            collections: [definition],
+            hooks: {
+                collections: { documents: collectionHooks },
+                uploads: {
+                    'documents.metadata.asset': nestedHooks,
+                    'documents.files.filesGroup.publicationFile': arrayLoader,
+                    'documents.content.hero.backgroundImage': blockHooks,
+                },
+            },
+        });
+        expect(definition.hooks).toBeUndefined();
+        expect(nested.upload?.hooks).toBeUndefined();
+        expect(arrayFile.upload?.hooks).toBeUndefined();
+        expect(blockFile.upload?.hooks).toBeUndefined();
+        commitHookAttachment(operations);
+        expect(await resolveHooks(definition)).toBe(collectionHooks);
+        expect(await resolveUploadHooks(nested.upload?.hooks)).toBe(nestedHooks);
+        expect(await resolveUploadHooks(arrayFile.upload?.hooks)).toEqual({});
+        expect(arrayLoader).toHaveBeenCalledOnce();
+        expect(await resolveUploadHooks(blockFile.upload?.hooks)).toBe(blockHooks);
+    });
+    it('rejects unknown collection, field, block, and non-upload targets', () => {
+        const { definition } = nestedUploadCollection();
+        const cases = [
+            { collections: { missing: {} } },
+            { uploads: { 'missing.asset': {} } },
+            { uploads: { 'documents.metadata.missing': {} } },
+            { uploads: { 'documents.content.missing.backgroundImage': {} } },
+            { uploads: { 'documents.metadata': {} } },
+        ];
+        for (const hooks of cases) {
+            expect(() => prepareHookAttachment({ collections: [definition], hooks })).toThrow(/unknown|non-upload/);
+        }
+    });
+    it('rejects definition-authored hooks and ownership drift', () => {
+        const definition = collection();
+        const authored = {};
+        definition.hooks = authored;
+        expect(prepareHookAttachment({ collections: [definition] })).toEqual([]);
+        expect(definition.hooks).toBe(authored);
+        expect(() => prepareHookAttachment({
+            collections: [definition],
+            hooks: { collections: { documents: {} } },
+        })).toThrow(/definition-authored/);
+        definition.hooks = undefined;
+        const first = {};
+        commitHookAttachment(prepareHookAttachment({
+            collections: [definition],
+            hooks: { collections: { documents: first } },
+        }));
+        definition.hooks = authored;
+        expect(() => prepareHookAttachment({
+            collections: [definition],
+            hooks: { collections: { documents: {} } },
+        })).toThrow(/changed outside ServerConfig\.hooks/);
+        const { definition: uploadDefinition, nested } = nestedUploadCollection();
+        if (!nested.upload)
+            throw new Error('test fixture must be upload-capable');
+        const authoredUpload = {};
+        nested.upload.hooks = authoredUpload;
+        expect(prepareHookAttachment({ collections: [uploadDefinition] })).toEqual([]);
+        expect(nested.upload.hooks).toBe(authoredUpload);
+        expect(() => prepareHookAttachment({
+            collections: [uploadDefinition],
+            hooks: { uploads: { 'documents.metadata.asset': {} } },
+        })).toThrow(/definition-authored/);
+    });
+    it('replaces and removes registry-owned hooks across successful reinitialization', () => {
+        const definition = collection();
+        const first = vi.fn(() => Promise.resolve({}));
+        const second = vi.fn(() => Promise.resolve({}));
+        commitHookAttachment(prepareHookAttachment({
+            collections: [definition],
+            hooks: { collections: { documents: first } },
+        }));
+        expect(definition.hooks).toBe(first);
+        commitHookAttachment(prepareHookAttachment({
+            collections: [definition],
+            hooks: { collections: { documents: second } },
+        }));
+        expect(definition.hooks).toBe(second);
+        commitHookAttachment(prepareHookAttachment({ collections: [definition] }));
+        expect(definition.hooks).toBeUndefined();
+    });
+    it('leaves prior registry hooks intact when init fails after preparation', async () => {
+        const definition = collection();
+        const stable = {};
+        const replacement = {};
+        commitHookAttachment(prepareHookAttachment({
+            collections: [definition],
+            hooks: { collections: { documents: stable } },
+        }));
+        const invalid = {
+            serverURL: 'https://example.test',
+            collections: [definition],
+            db: {},
+            hooks: { collections: { documents: replacement } },
+            i18n: {
+                interface: { defaultLocale: 'en', locales: ['en'] },
+                content: { defaultLocale: 'en', locales: [] },
+            },
+        };
+        await expect(initBylineCore(invalid, {})).rejects.toThrow(/translations bundle/i);
+        expect(definition.hooks).toBe(stable);
+    });
+    it('rejects dotted registry segments and duplicate upload leaf names at boot', () => {
+        expect(() => prepareHookAttachment({ collections: [collection('docs.archive')] })).toThrow(/dot-free/);
+        const dottedField = collection();
+        dottedField.fields = [{ name: 'meta.asset', type: 'file', upload: {} }];
+        expect(() => prepareHookAttachment({ collections: [dottedField] })).toThrow(/dot-free/);
+        const dottedBlock = collection();
+        dottedBlock.fields = [
+            {
+                name: 'content',
+                type: 'blocks',
+                blocks: [{ blockType: 'hero.large', fields: [] }],
+            },
+        ];
+        expect(() => prepareHookAttachment({ collections: [dottedBlock] })).toThrow(/dot-free/);
+        const duplicate = collection();
+        duplicate.fields = [
+            { name: 'primary', type: 'group', fields: [{ name: 'asset', type: 'file', upload: {} }] },
+            { name: 'secondary', type: 'group', fields: [{ name: 'asset', type: 'image', upload: {} }] },
+        ];
+        expect(() => prepareHookAttachment({ collections: [duplicate] })).toThrow(/duplicate upload-capable leaf name/);
+    });
+});

package/dist/config/config-hooks.test.node.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/config-hooks.test.node.js

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { defineClientConfig, defineServerConfig, getCollectionDefinition } from './config.js';
+const SERVER_CONFIG = Symbol.for('__byline_server_config__');
+const CLIENT_CONFIG = Symbol.for('__byline_client_config__');
+const previousServer = globalThis[SERVER_CONFIG];
+const previousClient = globalThis[CLIENT_CONFIG];
+afterEach(() => {
+    const globals = globalThis;
+    if (previousServer === undefined)
+        delete globals[SERVER_CONFIG];
+    else
+        globals[SERVER_CONFIG] = previousServer;
+    if (previousClient === undefined)
+        delete globals[CLIENT_CONFIG];
+    else
+        globals[CLIENT_CONFIG] = previousClient;
+});
+function definition(path) {
+    return {
+        path,
+        labels: { singular: path, plural: path },
+        fields: [{ name: 'title', type: 'text' }],
+    };
+}
+const i18n = {
+    interface: { defaultLocale: 'en', locales: [] },
+    content: { defaultLocale: 'en', locales: [] },
+};
+describe('collection definition config preference', () => {
+    it('uses client definitions when only client config is registered', () => {
+        const globals = globalThis;
+        delete globals[SERVER_CONFIG];
+        delete globals[CLIENT_CONFIG];
+        const client = definition('client-only');
+        defineClientConfig({ serverURL: 'https://example.test', collections: [client], i18n });
+        expect(getCollectionDefinition('client-only')).toBe(client);
+    });
+    it('prefers hook-attached server definitions when both configs are registered', () => {
+        const globals = globalThis;
+        delete globals[SERVER_CONFIG];
+        delete globals[CLIENT_CONFIG];
+        const client = definition('docs');
+        const server = definition('docs');
+        const hooks = {};
+        defineClientConfig({ serverURL: 'https://example.test', collections: [client], i18n });
+        defineServerConfig({
+            serverURL: 'https://example.test',
+            collections: [server],
+            db: {},
+            hooks: { collections: { docs: hooks } },
+            i18n,
+        });
+        expect(getCollectionDefinition('docs')).toBe(server);
+        expect(getCollectionDefinition('docs')?.hooks).toBe(hooks);
+    });
+});

package/dist/config/config.d.ts

@@ -1,4 +1,4 @@
-import type { ClientConfig, CollectionAdminConfig, CollectionDefinition, ColumnDefinition, ServerConfig } from '../@types/index.js';
+import type { ClientConfig, CollectionAdminConfig, CollectionDefinition, ColumnDefinition, ResolvedClientConfig, ResolvedServerConfig, ServerConfig } from '../@types/index.js';
 /**
  * Resolve a collection definition by `path`. Returns `null` either when
  * no config has been registered (e.g. unit tests, isolated tooling) or
@@ -23,10 +23,14 @@ export declare const getCollectionAdminConfig: (slug: string) => CollectionAdmin
  * working until it is removed.
  */
 export declare const resolveItemViewColumns: (config: CollectionAdminConfig | null | undefined) => ColumnDefinition[] | undefined;
-export declare function defineClientConfig(config: ClientConfig): void;
-export declare function defineServerConfig(config: ServerConfig): void;
-export declare function getClientConfig(): ClientConfig;
-export declare function getServerConfig(): ServerConfig;
+export declare function defineClientConfig(config: ClientConfig): ResolvedClientConfig;
+export declare function defineServerConfig<TAdminStore = unknown>(config: ServerConfig<TAdminStore>): ResolvedServerConfig<TAdminStore>;
+/** Resolve and validate server config without replacing the registered singleton. */
+export declare function resolveServerConfig<TAdminStore = unknown>(config: ServerConfig<TAdminStore>): ResolvedServerConfig<TAdminStore>;
+/** Internal commit step used after initialization has completed successfully. */
+export declare function registerServerConfig<TAdminStore = unknown>(config: ResolvedServerConfig<TAdminStore>): ResolvedServerConfig<TAdminStore>;
+export declare function getClientConfig(): ResolvedClientConfig;
+export declare function getServerConfig(): ResolvedServerConfig;
 /**
  * Order a set of locale codes by their position in the configured content
  * locale list. The order source is `i18n.content.locales` — the authoritative,

package/dist/config/config.js

@@ -1,3 +1,5 @@
+import { commitHookAttachment, prepareHookAttachment, } from './attach-hooks.js';
+import { resolveRoutes } from './routes.js';
 import { validateAdminConfigs } from './validate-admin-configs.js';
 import { validateCollections } from './validate-collections.js';
 // ---------------------------------------------------------------------------
@@ -10,6 +12,7 @@ import { validateCollections } from './validate-collections.js';
 const BYLINE_SERVER_CONFIG = Symbol.for('__byline_server_config__');
 const BYLINE_CLIENT_CONFIG = Symbol.for('__byline_client_config__');
 const BYLINE_CORE = Symbol.for('__byline_core__');
+const preparedHookAttachments = new WeakMap();
 function getServerConfigInstance() {
     return globalThis[BYLINE_SERVER_CONFIG] ?? null;
 }
@@ -43,7 +46,7 @@ function setBylineCoreInstance(core) {
  * still throw the loud "Byline has not been configured" error.
  */
 export const getCollectionDefinition = (path) => {
-    const config = getClientConfigInstance() ?? getServerConfigInstance();
+    const config = getServerConfigInstance() ?? getClientConfigInstance();
     if (config == null)
         return null;
     return config.collections.find((collection) => collection.path === path) ?? null;
@@ -68,11 +71,26 @@ export const resolveItemViewColumns = (config) => config?.itemView ?? config?.pi
 export function defineClientConfig(config) {
     validateCollections(config.collections);
     validateAdminConfigs(config.admin, config.collections);
-    setClientConfigInstance(config);
+    const resolved = { ...config, routes: resolveRoutes(config.routes) };
+    setClientConfigInstance(resolved);
+    return resolved;
 }
 export function defineServerConfig(config) {
+    return registerServerConfig(resolveServerConfig(config));
+}
+/** Resolve and validate server config without replacing the registered singleton. */
+export function resolveServerConfig(config) {
     validateCollections(config.collections);
+    const resolved = { ...config, routes: resolveRoutes(config.routes) };
+    preparedHookAttachments.set(resolved, prepareHookAttachment(resolved));
+    return resolved;
+}
+/** Internal commit step used after initialization has completed successfully. */
+export function registerServerConfig(config) {
+    const attachments = preparedHookAttachments.get(config) ?? prepareHookAttachment(config);
+    commitHookAttachment(attachments);
     setServerConfigInstance(config);
+    return config;
 }
 export function getClientConfig() {
     const clientConfig = getClientConfigInstance();

package/dist/config/routes.d.ts

@@ -5,11 +5,11 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { RoutesConfig } from '../@types/site-config.js';
+import type { RoutesConfig, RoutesConfigInput } from '../@types/site-config.js';
 /**
  * Merge a user-supplied (potentially partial) routes config with the
- * built-in defaults. Empty / unset keys fall back to `'/admin'` and
- * `'/api'`. Returns a fully-populated `RoutesConfig` so consumers don't
- * need null checks at every call site.
+ * built-in defaults. Empty / unset keys fall back to `'/admin'`, `'/api'`,
+ * and `'/sign-in'`. Returns a fully-populated `RoutesConfig` so consumers
+ * don't need null checks at every call site.
  */
-export declare function resolveRoutes(routes?: Partial<RoutesConfig>): RoutesConfig;
+export declare function resolveRoutes(routes?: RoutesConfigInput): RoutesConfig;

package/dist/config/routes.js

@@ -5,21 +5,54 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-/** Default route segments. Installations override either key on the
- * config object; callers read the merged shape via `resolveRoutes()`. */
+import { normalizeRootRelativeRedirect } from '../utils/root-relative-redirect.js';
+/** Default route paths resolved at an explicit configuration boundary. */
 const DEFAULT_ROUTES = {
     admin: '/admin',
     api: '/api',
+    signIn: '/sign-in',
 };
+function normalizeRoutePath(value, fallback, name) {
+    const input = value?.trim() || fallback;
+    if (input.includes('\\') ||
+        input.includes('?') ||
+        input.includes('#') ||
+        input.includes('%') ||
+        input.includes(':') ||
+        /\s/.test(input)) {
+        throw new Error(`routes.${name} must be an unencoded URL path without query, hash, whitespace, backslashes, or control characters`);
+    }
+    const segments = input.split('/').filter(Boolean);
+    if (segments.length === 0 || segments.some((segment) => segment === '.' || segment === '..')) {
+        throw new Error(`routes.${name} must contain at least one URL path segment`);
+    }
+    const normalized = `/${segments.join('/')}`;
+    if (normalizeRootRelativeRedirect(normalized) !== normalized) {
+        throw new Error(`routes.${name} contains an unsafe URL code point`);
+    }
+    return normalized;
+}
 /**
  * Merge a user-supplied (potentially partial) routes config with the
- * built-in defaults. Empty / unset keys fall back to `'/admin'` and
- * `'/api'`. Returns a fully-populated `RoutesConfig` so consumers don't
- * need null checks at every call site.
+ * built-in defaults. Empty / unset keys fall back to `'/admin'`, `'/api'`,
+ * and `'/sign-in'`. Returns a fully-populated `RoutesConfig` so consumers
+ * don't need null checks at every call site.
  */
 export function resolveRoutes(routes) {
-    return {
-        admin: routes?.admin ?? DEFAULT_ROUTES.admin,
-        api: routes?.api ?? DEFAULT_ROUTES.api,
-    };
+    const admin = normalizeRoutePath(routes?.admin, DEFAULT_ROUTES.admin, 'admin');
+    const api = normalizeRoutePath(routes?.api, DEFAULT_ROUTES.api, 'api');
+    if (routes?.signIn?.trim().startsWith('//')) {
+        throw new Error('routes.signIn must not be a protocol-relative URL');
+    }
+    const signIn = normalizeRoutePath(routes?.signIn, DEFAULT_ROUTES.signIn, 'signIn');
+    if (pathsOverlap(admin, api)) {
+        throw new Error('routes.admin and routes.api must use separate URL path trees');
+    }
+    if (pathsOverlap(signIn, admin) || pathsOverlap(signIn, api)) {
+        throw new Error('routes.signIn must be outside the admin and API route trees');
+    }
+    return Object.freeze({ admin, api, signIn });
+}
+function pathsOverlap(left, right) {
+    return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
 }

package/dist/config/routes.test.node.d.ts

@@ -0,0 +1 @@
+export {};