@byline/core 3.1.1 → 3.2.0

package/dist/@types/collection-types.d.ts

@@ -123,9 +123,14 @@ export interface UploadConfig {
      * have been written to the storage provider, before the document
      * version is created.
      *
+     * Accepts an inline object, or — because the schema is isomorphic — a
+     * **loader** (`hooks: () => import('./media.hooks.js')`) that defers the
+     * hooks module so server-only code (storage SDKs, `sharp`, AV scanners)
+     * never enters the client bundle. See {@link UploadHooksLoader}.
+     *
      * @see UploadHooks
      */
-    hooks?: UploadHooks;
+    hooks?: UploadHooks | UploadHooksLoader;
 }
 /**
  * The three status names that every workflow must contain.
@@ -569,6 +574,52 @@ export interface UploadHooks {
     beforeStore?: BeforeStoreHookFn | BeforeStoreHookFn[];
     afterStore?: AfterStoreHookFn | AfterStoreHookFn[];
 }
+/**
+ * A lazy loader for a field's upload hooks — the function form of
+ * `field.upload.hooks`. Returns the `UploadHooks` object, or a module
+ * namespace whose `default` export is the `UploadHooks` object (so
+ * `() => import('./media.hooks.js')` works directly against an
+ * `export default { … } satisfies UploadHooks`).
+ *
+ * Same rationale as {@link CollectionHooksLoader}: upload hooks are declared
+ * on a field *inside the collection schema*, which is **isomorphic** (bundled
+ * into the client admin). `beforeStore` / `afterStore` bodies typically reach
+ * for server-only code — storage SDKs, `sharp`, AV scanners, `node:crypto` —
+ * so declaring them inline drags that graph into the client bundle. The
+ * loader form defers the hooks module behind a dynamic `import()`, keeping it
+ * structurally absent from the client.
+ *
+ * @example
+ * // media.schema.ts — isomorphic, client-safe by construction
+ * {
+ *   name: 'image',
+ *   type: 'image',
+ *   upload: {
+ *     mimeTypes: ['image/*'],
+ *     hooks: () => import('./media.hooks.js'),
+ *   },
+ * }
+ *
+ * // media.hooks.ts — server-only; may import any server-only module freely
+ * export default { afterStore: (ctx) => { … } } satisfies UploadHooks
+ */
+export type UploadHooksLoader = () => Promise<UploadHooks | {
+    default: UploadHooks;
+}>;
+/**
+ * Resolve a field's `upload.hooks` to a concrete `UploadHooks` object.
+ *
+ * - The inline-object form (`hooks: { … }`) is returned as-is.
+ * - The loader form (`hooks: () => import('./media.hooks.js')`) is invoked
+ *   once and its result (unwrapping a module `default` export) memoized,
+ *   keyed on the loader's function identity. The upload pipeline resolves
+ *   through here, so a loader's dynamic `import()` runs at most once per
+ *   process.
+ *
+ * Returns `undefined` when no upload hooks are declared. The counterpart to
+ * {@link resolveHooks} for the field-upload surface.
+ */
+export declare function resolveUploadHooks(hooks: UploadHooks | UploadHooksLoader | undefined): Promise<UploadHooks | undefined>;
 /**
  * Context passed to `afterRead` hooks.
  *
@@ -716,6 +767,71 @@ export interface CollectionHooks {
      */
     afterRead?: CollectionHookSlot<AfterReadContext>;
 }
+/**
+ * A lazy loader for a collection's hooks — the function form of
+ * `CollectionDefinition.hooks`. Returns the `CollectionHooks` object, or a
+ * module namespace whose `default` export is the `CollectionHooks` object
+ * (so `() => import('./docs.hooks.js')` works directly against an
+ * `export default { … } satisfies CollectionHooks`).
+ *
+ * Why this exists: a `CollectionDefinition` is **isomorphic** — the same
+ * schema module is bundled into the *client* admin as well as the server.
+ * Any module the schema *statically imports* is dragged into the client
+ * bundle, so a hook body that imports server-only code (cache invalidation,
+ * queue clients, Node built-ins) leaks that entire graph into the browser.
+ * The loader form defers the hooks module behind a dynamic `import()`, so
+ * the hooks module and its server-only graph are *structurally absent* from
+ * the client — no per-call-site SSR guards required.
+ *
+ * @example
+ * // docs.schema.ts — isomorphic, client-safe by construction
+ * export const Docs = defineCollection({
+ *   // …declarative field config…
+ *   hooks: () => import('./docs.hooks.js'),
+ * })
+ *
+ * // docs.hooks.ts — server-only; may import any server-only module freely
+ * import { invalidateDocument } from '@/lib/cache/with-cache'
+ * export default {
+ *   afterCreate: ({ collectionPath, path }) => invalidateDocument(collectionPath, path),
+ * } satisfies CollectionHooks
+ */
+export type CollectionHooksLoader = () => Promise<CollectionHooks | {
+    default: CollectionHooks;
+}>;
+/**
+ * Resolve a collection's `hooks` to a concrete `CollectionHooks` object.
+ *
+ * - The inline-object form (`hooks: { … }`) is returned as-is.
+ * - The loader form (`hooks: () => import('./docs.hooks.js')`) is invoked
+ *   once and its result (unwrapping a module `default` export) memoized,
+ *   keyed on the loader's function identity. Every read/write path resolves
+ *   through here, so a loader's dynamic `import()` runs at most once per
+ *   process regardless of how many documents flow through it.
+ *
+ * Returns `undefined` when no hooks are declared.
+ */
+export declare function resolveHooks(definition: CollectionDefinition): Promise<CollectionHooks | undefined>;
+/**
+ * Type-safe factory for authoring a collection's hooks in a separate
+ * module (the loader form: `hooks: () => import('./docs.hooks.js')`).
+ * Returns the object as-is — the counterpart to `defineCollection` /
+ * `defineBlock` for the sibling hooks file.
+ *
+ * Note: hook contexts currently type `data` as `Record<string, any>`, so
+ * this provides the same checking as `satisfies CollectionHooks` (a named
+ * factory + a stable place to hang docs), not per-collection field-data
+ * narrowing. Threading `CollectionFieldData<C>` into hook contexts is a
+ * separate future enhancement; when it lands it can be added here without
+ * authors changing call sites.
+ *
+ * @example
+ * // docs.hooks.ts
+ * export default defineHooks({
+ *   afterCreate: ({ collectionPath, path }) => invalidateDocument(collectionPath, path),
+ * })
+ */
+export declare function defineHooks(hooks: CollectionHooks): CollectionHooks;
 export interface CollectionDefinition {
     labels: {
         singular: string;
@@ -725,8 +841,17 @@ export interface CollectionDefinition {
     fields: Field[];
     /** Sequential workflow configuration. Falls back to DEFAULT_WORKFLOW if omitted. */
     workflow?: WorkflowConfig;
-    /** Lifecycle hooks for server-side document operations. */
-    hooks?: CollectionHooks;
+    /**
+     * Lifecycle hooks for server-side document operations.
+     *
+     * Two forms:
+     * - **Inline** (`hooks: { afterCreate, … }`) — valid for hooks whose
+     *   bodies only touch isomorphic / declarative code.
+     * - **Loader** (`hooks: () => import('./docs.hooks.js')`) — defers the
+     *   hooks module behind a dynamic `import()` so server-only code never
+     *   enters the client bundle. See {@link CollectionHooksLoader}.
+     */
+    hooks?: CollectionHooks | CollectionHooksLoader;
     /**
      * Configures which text fields are searched when the admin list view's
      * search box is used. Only `store_text` fields are supported for now.

package/dist/@types/collection-types.js

@@ -143,12 +143,84 @@ export function defineWorkflow(input = {}) {
         ...(input.defaultStatus ? { defaultStatus: input.defaultStatus } : {}),
     };
 }
+const resolvedUploadHooksCache = new WeakMap();
+/**
+ * Resolve a field's `upload.hooks` to a concrete `UploadHooks` object.
+ *
+ * - The inline-object form (`hooks: { … }`) is returned as-is.
+ * - The loader form (`hooks: () => import('./media.hooks.js')`) is invoked
+ *   once and its result (unwrapping a module `default` export) memoized,
+ *   keyed on the loader's function identity. The upload pipeline resolves
+ *   through here, so a loader's dynamic `import()` runs at most once per
+ *   process.
+ *
+ * Returns `undefined` when no upload hooks are declared. The counterpart to
+ * {@link resolveHooks} for the field-upload surface.
+ */
+export async function resolveUploadHooks(hooks) {
+    if (typeof hooks !== 'function')
+        return hooks;
+    const cached = resolvedUploadHooksCache.get(hooks);
+    if (cached)
+        return cached;
+    const loaded = await hooks();
+    const resolved = 'default' in loaded ? loaded.default : loaded;
+    resolvedUploadHooksCache.set(hooks, resolved);
+    return resolved;
+}
 /** Normalise a collection-hook slot (single function or array) into a flat array. */
 export function normalizeCollectionHook(hook) {
     if (!hook)
         return [];
     return Array.isArray(hook) ? hook : [hook];
 }
+const resolvedHooksCache = new WeakMap();
+/**
+ * Resolve a collection's `hooks` to a concrete `CollectionHooks` object.
+ *
+ * - The inline-object form (`hooks: { … }`) is returned as-is.
+ * - The loader form (`hooks: () => import('./docs.hooks.js')`) is invoked
+ *   once and its result (unwrapping a module `default` export) memoized,
+ *   keyed on the loader's function identity. Every read/write path resolves
+ *   through here, so a loader's dynamic `import()` runs at most once per
+ *   process regardless of how many documents flow through it.
+ *
+ * Returns `undefined` when no hooks are declared.
+ */
+export async function resolveHooks(definition) {
+    const hooks = definition.hooks;
+    if (typeof hooks !== 'function')
+        return hooks;
+    const cached = resolvedHooksCache.get(hooks);
+    if (cached)
+        return cached;
+    const loaded = await hooks();
+    const resolved = 'default' in loaded ? loaded.default : loaded;
+    resolvedHooksCache.set(hooks, resolved);
+    return resolved;
+}
+/**
+ * Type-safe factory for authoring a collection's hooks in a separate
+ * module (the loader form: `hooks: () => import('./docs.hooks.js')`).
+ * Returns the object as-is — the counterpart to `defineCollection` /
+ * `defineBlock` for the sibling hooks file.
+ *
+ * Note: hook contexts currently type `data` as `Record<string, any>`, so
+ * this provides the same checking as `satisfies CollectionHooks` (a named
+ * factory + a stable place to hang docs), not per-collection field-data
+ * narrowing. Threading `CollectionFieldData<C>` into hook contexts is a
+ * separate future enhancement; when it lands it can be added here without
+ * authors changing call sites.
+ *
+ * @example
+ * // docs.hooks.ts
+ * export default defineHooks({
+ *   afterCreate: ({ collectionPath, path }) => invalidateDocument(collectionPath, path),
+ * })
+ */
+export function defineHooks(hooks) {
+    return hooks;
+}
 /**
  * Type-safe factory for creating a CollectionDefinition.
  * Returns the definition as-is but provides type checking.

package/dist/@types/resolve-hooks.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/@types/resolve-hooks.test.node.js

@@ -0,0 +1,106 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { defineHooks, resolveHooks, resolveUploadHooks } from './collection-types.js';
+function baseCollection() {
+    return {
+        path: 'docs',
+        labels: { singular: 'Doc', plural: 'Docs' },
+        fields: [{ name: 'title', type: 'text' }],
+    };
+}
+describe('resolveHooks', () => {
+    it('returns undefined when no hooks are declared', async () => {
+        const def = baseCollection();
+        expect(await resolveHooks(def)).toBeUndefined();
+    });
+    it('returns the inline-object form as-is', async () => {
+        const hooks = { afterCreate: () => { } };
+        const def = { ...baseCollection(), hooks };
+        expect(await resolveHooks(def)).toBe(hooks);
+    });
+    it('invokes a loader returning a bare CollectionHooks object', async () => {
+        const hooks = { afterCreate: () => { } };
+        const def = {
+            ...baseCollection(),
+            hooks: () => Promise.resolve(hooks),
+        };
+        expect(await resolveHooks(def)).toBe(hooks);
+    });
+    it('unwraps a loader returning a module namespace with a default export', async () => {
+        const hooks = { afterCreate: () => { } };
+        const def = {
+            ...baseCollection(),
+            // Mirrors `() => import('./docs.hooks.js')` against `export default …`.
+            hooks: () => Promise.resolve({ default: hooks }),
+        };
+        expect(await resolveHooks(def)).toBe(hooks);
+    });
+    it('invokes the loader at most once and memoizes the result', async () => {
+        const hooks = { afterCreate: () => { } };
+        const loader = vi.fn(() => Promise.resolve({ default: hooks }));
+        const def = { ...baseCollection(), hooks: loader };
+        const first = await resolveHooks(def);
+        const second = await resolveHooks(def);
+        expect(first).toBe(hooks);
+        expect(second).toBe(hooks);
+        expect(loader).toHaveBeenCalledTimes(1);
+    });
+    it('caches per loader identity — distinct loaders each run once', async () => {
+        const a = { afterCreate: () => { } };
+        const b = { afterUpdate: () => { } };
+        const loaderA = vi.fn(() => Promise.resolve(a));
+        const loaderB = vi.fn(() => Promise.resolve(b));
+        expect(await resolveHooks({ ...baseCollection(), hooks: loaderA })).toBe(a);
+        expect(await resolveHooks({ ...baseCollection(), hooks: loaderB })).toBe(b);
+        expect(await resolveHooks({ ...baseCollection(), hooks: loaderA })).toBe(a);
+        expect(loaderA).toHaveBeenCalledTimes(1);
+        expect(loaderB).toHaveBeenCalledTimes(1);
+    });
+});
+describe('resolveUploadHooks', () => {
+    it('returns undefined when no upload hooks are declared', async () => {
+        expect(await resolveUploadHooks(undefined)).toBeUndefined();
+    });
+    it('returns the inline-object form as-is', async () => {
+        const hooks = { afterStore: () => { } };
+        expect(await resolveUploadHooks(hooks)).toBe(hooks);
+    });
+    it('invokes a loader returning a bare UploadHooks object', async () => {
+        const hooks = { beforeStore: () => { } };
+        expect(await resolveUploadHooks(() => Promise.resolve(hooks))).toBe(hooks);
+    });
+    it('unwraps a loader returning a module namespace with a default export', async () => {
+        const hooks = { afterStore: () => { } };
+        // Mirrors `() => import('./media.hooks.js')` against `export default …`.
+        expect(await resolveUploadHooks(() => Promise.resolve({ default: hooks }))).toBe(hooks);
+    });
+    it('invokes the loader at most once and memoizes the result', async () => {
+        const hooks = { afterStore: () => { } };
+        const loader = vi.fn(() => Promise.resolve({ default: hooks }));
+        const first = await resolveUploadHooks(loader);
+        const second = await resolveUploadHooks(loader);
+        expect(first).toBe(hooks);
+        expect(second).toBe(hooks);
+        expect(loader).toHaveBeenCalledTimes(1);
+    });
+});
+describe('defineHooks', () => {
+    it('returns the hooks object unchanged (identity factory)', () => {
+        const hooks = { afterCreate: () => { } };
+        expect(defineHooks(hooks)).toBe(hooks);
+    });
+    it('produces a value a loader can resolve through', async () => {
+        const hooks = defineHooks({ beforeCreate: () => { } });
+        const def = {
+            ...baseCollection(),
+            hooks: () => Promise.resolve({ default: hooks }),
+        };
+        expect(await resolveHooks(def)).toBe(hooks);
+    });
+});

package/dist/auth/apply-before-read.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
-import type { CollectionDefinition } from '../@types/collection-types.js';
+import { type CollectionDefinition } from '../@types/collection-types.js';
 import type { ReadContext } from '../@types/db-types.js';
 import type { QueryPredicate } from '../@types/query-predicate.js';
 /**

package/dist/auth/apply-before-read.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { resolveHooks, } from '../@types/collection-types.js';
 /**
  * Resolve the per-collection `beforeRead` hook predicate for the current
  * request, with caching across populate fanout.
@@ -30,7 +31,8 @@ export async function applyBeforeRead(params) {
     if (readContext.beforeReadCache.has(collectionPath)) {
         return readContext.beforeReadCache.get(collectionPath) ?? null;
     }
-    const hooks = normalizeBeforeReadHook(definition.hooks?.beforeRead);
+    const resolved = await resolveHooks(definition);
+    const hooks = normalizeBeforeReadHook(resolved?.beforeRead);
     if (hooks.length === 0) {
         readContext.beforeReadCache.set(collectionPath, null);
         return null;

package/dist/services/document-lifecycle.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { isArrayField, isBlocksField, isGroupField, normalizeCollectionHook, } from '../@types/index.js';
+import { isArrayField, isBlocksField, isGroupField, normalizeCollectionHook, resolveHooks, } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { getCollectionDefinition, getServerConfig } from '../config/config.js';
 import { ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_PATCH_FAILED, ERR_PATH_CONFLICT, ERR_VALIDATION, ErrorCodes, } from '../lib/errors.js';
@@ -204,7 +204,7 @@ export async function createDocument(ctx, params) {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
         const slugifier = ctx.slugifier ?? slugify;
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         const data = params.data;
         if (params.locale != null && params.locale !== defaultLocale) {
             throw ERR_VALIDATION({
@@ -277,7 +277,7 @@ export async function updateDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocument' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         const data = params.data;
         // Fetch the real original so hooks get accurate originalData (fixes the
         // PUT handler bug where originalData === data).
@@ -365,7 +365,7 @@ export async function updateDocumentWithPatches(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocumentWithPatches' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         // 1. Fetch current document.
         const latest = await db.queries.documents.getDocumentById({
             collection_id: collectionId,
@@ -493,7 +493,7 @@ export async function changeDocumentStatus(ctx, params) {
                 details: { collectionPath, nextStatus: params.nextStatus },
             }).log(ctx.logger);
         }
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         // 1. Fetch current version metadata. No field reconstruction needed —
         //    status transitions only touch the document_versions.status column.
         const latest = await db.queries.documents.getCurrentVersionMetadata({
@@ -573,7 +573,7 @@ export async function unpublishDocument(ctx, params) {
                 details: { collectionPath },
             }).log(ctx.logger);
         }
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         // Resolve the document's canonical path so the hooks can target the
         // specific document/URL (CDN purge, cache-key drop).
         const path = (await db.queries.documents.getCurrentPath({
@@ -641,7 +641,7 @@ export async function restoreDocumentVersion(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'restoreDocumentVersion' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         // 1. Read source version (full multi-locale tree).
         const source = await db.queries.documents.getDocumentByVersion({
             document_version_id: params.sourceVersionId,
@@ -773,7 +773,7 @@ export async function deleteDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteDocument' }, async () => {
         const { db, collectionPath, definition, logger } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'delete');
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         // 1. Verify the document exists.
         //    For collections that have any upload-capable image/file field
         //    AND a storage provider, fetch with reconstruct: true so we
@@ -964,7 +964,7 @@ export async function duplicateDocument(ctx, params) {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
         assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
         const slugifier = ctx.slugifier ?? slugify;
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         // 1. Read source with locale='all' — single read, full multi-locale tree.
         const source = await db.queries.documents.getDocumentById({
             collection_id: collectionId,
@@ -1322,7 +1322,7 @@ export async function copyToLocale(ctx, params) {
         // 4. Hooks see the target-locale view as originalData (consistent
         //    with how updateDocument scopes originalData to the active
         //    locale) and the merged payload as the next `data`.
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         const copyToLocaleMarker = {
             sourceLocale: params.sourceLocale,
             targetLocale: params.targetLocale,
@@ -1440,7 +1440,7 @@ export async function deleteLocale(ctx, params) {
                 details: { documentId: params.documentId, locale: params.locale, collectionPath },
             }).log(ctx.logger);
         }
-        const hooks = definition.hooks;
+        const hooks = await resolveHooks(definition);
         const deleteLocaleMarker = { locale: params.locale };
         const originalData = targetRecord.fields ?? {};
         await invokeHook(hooks?.beforeUpdate, {

package/dist/services/document-read.js

@@ -20,7 +20,7 @@
  * using `db.commands.documents.createDocumentVersion` directly skips the
  * `beforeCreate` / `afterCreate` hooks.
  */
-import { normalizeCollectionHook } from '../@types/index.js';
+import { normalizeCollectionHook, resolveHooks } from '../@types/index.js';
 async function invokeHook(hook, ctx) {
     const fns = normalizeCollectionHook(hook);
     for (const fn of fns) {
@@ -40,7 +40,8 @@ async function invokeHook(hook, ctx) {
  * nested `client.collection(...).findById(id, { _readContext })` calls.
  */
 export async function applyAfterRead(params) {
-    const hook = params.definition.hooks?.afterRead;
+    const resolved = await resolveHooks(params.definition);
+    const hook = resolved?.afterRead;
     if (!hook)
         return;
     const docId = params.doc?.document_id;

package/dist/services/field-upload.js

@@ -5,6 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
+import { resolveUploadHooks } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { ERR_DATABASE, ERR_STORAGE, ERR_VALIDATION } from '../lib/errors.js';
 import { withLogContext } from '../lib/logger.js';
@@ -157,7 +158,11 @@ export async function uploadField(ctx, params) {
         //    rather than throw — `assertActorCanPerform` is the auth gate
         //    for whether the upload should run at all, not the hook layer.
         const sanitised = sanitiseFilename(originalFilename || 'upload');
-        const beforeStoreHooks = normalizeUploadHook(upload.hooks?.beforeStore);
+        // Resolve the field's upload hooks once. The loader form
+        // (`hooks: () => import('./media.hooks.js')`) keeps server-only hook
+        // graphs out of the client bundle; the inline form returns as-is.
+        const uploadHooks = await resolveUploadHooks(upload.hooks);
+        const beforeStoreHooks = normalizeUploadHook(uploadHooks?.beforeStore);
         const effectiveFilename = await runBeforeStoreChain(beforeStoreHooks, {
             fieldName,
             field,
@@ -242,7 +247,7 @@ export async function uploadField(ctx, params) {
         };
         // -- afterStore chain. Failures are logged but do not roll back
         //    the storage write (consistent with `afterCreate` etc.).
-        const afterStoreHooks = normalizeUploadHook(upload.hooks?.afterStore);
+        const afterStoreHooks = normalizeUploadHook(uploadHooks?.afterStore);
         for (const fn of afterStoreHooks) {
             try {
                 const afterCtx = {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.1.1"
+    "@byline/auth": "3.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",