@zveltio/sdk 2.0.8 → 3.0.0-beta.2

package/dist/studio/index.js

@@ -0,0 +1,180 @@
+/**
+ * Studio SDK surface (S3-02 + S3-03 + early S4-07 prep).
+ *
+ * Pure helpers for Studio extension authors:
+ *   - `makeFormProxy` / `applyFormAlterHooks` — form-alter pipeline that
+ *     `<Form>` renderers in core Studio call before render. Hooks add
+ *     fields, hide fields, reorder, attach validators.
+ *   - `sortSlotContributions` — stable priority-asc sort used by
+ *     `<Slot name>` to order extension contributions.
+ *
+ * The reactive registries themselves (Svelte 5 `$state`) live in
+ * `packages/studio/src/lib/extension-api.svelte.ts`. They import this
+ * module so the algorithm is one source of truth, while the studio side
+ * owns the runtime state.
+ *
+ * Exported via `@zveltio/sdk/studio`. Extension Svelte bundles can
+ * import-and-call too — useful for advanced authors who want to apply
+ * alters against their own custom forms.
+ */
+export function makeFormProxy(initial) {
+    // Deep-copy fields so hooks can mutate without leaking to the original.
+    const fields = initial.fields.map((f) => ({
+        ...f,
+        validators: [...(f.validators ?? [])],
+    }));
+    const hiddenSet = new Set();
+    return {
+        get fields() {
+            return fields;
+        },
+        addField({ after, before, field }) {
+            if (!field?.name) {
+                console.warn('[form-alter] addField: field.name is required');
+                return;
+            }
+            if (fields.some((f) => f.name === field.name)) {
+                console.warn(`[form-alter] addField: field "${field.name}" already exists — use mutate-by-name instead`);
+                return;
+            }
+            const target = after ?? before;
+            const cloned = { ...field, validators: [...(field.validators ?? [])] };
+            if (target) {
+                const idx = fields.findIndex((f) => f.name === target);
+                if (idx < 0) {
+                    // Anchor not found → push to end. Warn so the author knows.
+                    console.warn(`[form-alter] addField: anchor "${target}" not found; appending "${field.name}" at end`);
+                    fields.push(cloned);
+                }
+                else {
+                    const at = after ? idx + 1 : idx;
+                    fields.splice(at, 0, cloned);
+                }
+            }
+            else {
+                fields.push(cloned);
+            }
+        },
+        hideField(name) {
+            hiddenSet.add(name);
+        },
+        reorder(order) {
+            // Reorder only what's in `order`. Fields not mentioned keep their
+            // original relative order, appended after the reordered block.
+            const byName = new Map(fields.map((f) => [f.name, f]));
+            const reorderedKnown = order.map((n) => byName.get(n)).filter(Boolean);
+            const remaining = fields.filter((f) => !order.includes(f.name));
+            fields.length = 0;
+            fields.push(...reorderedKnown, ...remaining);
+        },
+        addValidator(fieldName, validator) {
+            const f = fields.find((x) => x.name === fieldName);
+            if (!f) {
+                console.warn(`[form-alter] addValidator: field "${fieldName}" not found`);
+                return;
+            }
+            f.validators = [...(f.validators ?? []), validator];
+        },
+        commit() {
+            // Materialize hidden state. `hidden: true` keeps the field in the
+            // schema so server-side defaults still apply; renderers skip rendering.
+            const out = fields.map((f) => (hiddenSet.has(f.name) ? { ...f, hidden: true } : f));
+            return { ...initial, fields: out };
+        },
+    };
+}
+/**
+ * Run every registered hook against the schema and return the result.
+ * Exception-safe: a throwing hook is logged and skipped, the rest still run.
+ */
+export function applyFormAlterHooks(hooks, schema, ctx = {}) {
+    if (hooks.length === 0)
+        return schema;
+    const proxy = makeFormProxy(schema);
+    for (const hook of hooks) {
+        try {
+            hook(proxy, ctx);
+        }
+        catch (err) {
+            console.error('[form-alter] hook threw:', err);
+        }
+    }
+    return proxy.commit();
+}
+/**
+ * Sort slot contributions deterministically: priority asc (lower first),
+ * then registration order (stable sort).
+ */
+export function sortSlotContributions(items) {
+    // We rely on Array.prototype.sort being stable (TC39 since 2019).
+    return items.slice().sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+}
+function getStudioGlobal() {
+    if (typeof window === 'undefined')
+        return null;
+    const g = window.__zveltio;
+    if (!g) {
+        console.warn('[zveltio/sdk/studio] window.__zveltio is not installed. Is the bundle running inside Studio?');
+        return null;
+    }
+    return g;
+}
+/** Register a top-level Studio page contributed by this extension. */
+export function registerRoute(route) {
+    getStudioGlobal()?.registerRoute(route);
+}
+/**
+ * Register a Svelte component into a named composition slot (S3-03).
+ *
+ * @example
+ *   import { registerSlot } from '@zveltio/sdk/studio';
+ *   import RevenueWidget from './widgets/RevenueWidget.svelte';
+ *
+ *   registerSlot('dashboard.widgets', {
+ *     component: RevenueWidget,
+ *     priority: 10,
+ *     visible: (ctx) => (ctx.user as any)?.roles?.includes('finance'),
+ *   });
+ */
+export function registerSlot(name, contribution) {
+    getStudioGlobal()?.registerSlot(name, contribution);
+}
+/**
+ * Register a Drupal-style form-alter hook (S3-02).
+ *
+ * @example
+ *   import { registerFormAlter } from '@zveltio/sdk/studio';
+ *
+ *   registerFormAlter('core:user-edit', (form) => {
+ *     form.addField({ after: 'email', field: { name: 'phone', type: 'tel' } });
+ *     form.hideField('legacy_pin');
+ *   });
+ */
+export function registerFormAlter(formId, hook) {
+    getStudioGlobal()?.registerFormAlter(formId, hook);
+}
+/** Register a custom Studio field type contributed by this extension. */
+export function registerFieldType(ft) {
+    getStudioGlobal()?.registerFieldType(ft);
+}
+/**
+ * Register a custom preview handler for asset URLs / MIME types.
+ *
+ * @example
+ *   import { registerAssetPreview } from '@zveltio/sdk/studio';
+ *   import PdfPreview from './PdfPreview.svelte';
+ *
+ *   registerAssetPreview({
+ *     match: (a) => a.mimeType === 'application/pdf',
+ *     component: PdfPreview,
+ *   });
+ */
+export function registerAssetPreview(handler) {
+    getStudioGlobal()?.registerAssetPreview(handler);
+}
+/** Engine base URL — pre-installed by Studio for cross-origin fetches. */
+export function getEngineUrl() {
+    if (typeof window === 'undefined')
+        return '';
+    return window.__ZVELTIO_ENGINE_URL__ || getStudioGlobal()?.engineUrl || '';
+}

package/dist/svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"svelte.d.ts","sourceRoot":"","sources":["../src/svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,IAAI,GAC/B,MAAM,IAAI,CAGZ;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,CAAC,MAAM,EAAE;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB,KAAK,IAAI,EACV,UAAU,SAAO,GAChB,MAAM,IAAI,CAeZ"}
+{"version":3,"file":"svelte.d.ts","sourceRoot":"","sources":["../src/svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,IAAI,GAC/B,MAAM,IAAI,CAGZ;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,KAAK,IAAI,EACnF,UAAU,SAAO,GAChB,MAAM,IAAI,CAeZ"}

package/dist/sync-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-manager.d.ts","sourceRoot":"","sources":["../src/sync-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;IAC9C,mHAAmH;IACnH,kBAAkB,CAAC,EAAE,sBAAsB,CAAC;CAC7C;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,SAAS,CAAyD;gBAE9D,MAAM,EAAE,aAAa,EAAE,MAAM,GAAE,iBAAsB;IAY3D,KAAK,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiChD;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM;QAEnB,2CAA2C;;;;;QAU3C,6CAA6C;kBAC7B,MAAM;;;;QAUtB,0CAA0C;uBACrB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;QAYxC,0CAA0C;qBACvB,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;QAapD,+CAA+C;qBAC5B,MAAM;QAMzB,qDAAqD;8BAC/B,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,IAAI;QAoD9C,8CAA8C;;QAK9C,kCAAkC;8BAE5B,MAAM,gBACI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;IASvC,oCAAoC;IAC9B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YA8GhB,eAAe;IAmB7B,wDAAwD;IAClD,SAAS,IAAI,OAAO,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IAUI,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}
+{"version":3,"file":"sync-manager.d.ts","sourceRoot":"","sources":["../src/sync-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;IAC9C,mHAAmH;IACnH,kBAAkB,CAAC,EAAE,sBAAsB,CAAC;CAC7C;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,SAAS,CAAyD;gBAE9D,MAAM,EAAE,aAAa,EAAE,MAAM,GAAE,iBAAsB;IAY3D,KAAK,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BhD;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM;QAEnB,2CAA2C;;;;;QAU3C,6CAA6C;kBAC7B,MAAM;;;;QAUtB,0CAA0C;uBACrB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;QAYxC,0CAA0C;qBACvB,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;;;QAapD,+CAA+C;qBAC5B,MAAM;QAMzB,qDAAqD;8BAC/B,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,IAAI;QA0C9C,8CAA8C;;QAK9C,kCAAkC;8BACN,MAAM,gBAAgB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;;IAQzE,oCAAoC;IAC9B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YA8FhB,eAAe;IAmB7B,wDAAwD;IAClD,SAAS,IAAI,OAAO,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IAUI,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}

package/dist/sync-manager.js

@@ -115,12 +115,9 @@ export class SyncManager {
                 if (this.realtime) {
                     unsubRealtime = this.realtime.subscribe(name, async (event) => {
                         // Apply update from server to local store
-                        if (event.event === 'record.created' ||
-                            event.event === 'record.updated') {
+                        if (event.event === 'record.created' || event.event === 'record.updated') {
                             try {
-                                const serverRecord = await this.client
-                                    .collection(name)
-                                    .get(event.record_id);
+                                const serverRecord = await this.client.collection(name).get(event.record_id);
                                 await this.store.applyServerUpdate(name, event.record_id, serverRecord, Date.now());
                                 this.notifyListeners(name);
                             }
@@ -209,9 +206,7 @@ export class SyncManager {
                                 .create({ id: op.recordId, ...crdtPayload });
                             break;
                         case 'update':
-                            await this.client
-                                .collection(op.collection)
-                                .update(op.recordId, crdtPayload);
+                            await this.client.collection(op.collection).update(op.recordId, crdtPayload);
                             break;
                         case 'delete':
                             await this.client.collection(op.collection).delete(op.recordId);
@@ -224,9 +219,7 @@ export class SyncManager {
                     // Conflict from server (409) — apply conflict resolution
                     if (err.message?.includes('409')) {
                         try {
-                            const serverRecord = await this.client
-                                .collection(op.collection)
-                                .get(op.recordId);
+                            const serverRecord = await this.client.collection(op.collection).get(op.recordId);
                             const localRecord = await this.store.get(op.collection, op.recordId);
                             // CRDT LWW merge if both sides have CRDT docs and strategy is 'lww'
                             if (this.config.conflictResolution === 'lww' &&

package/dist/testing/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Testing helpers for Zveltio extensions (S4-06).
+ *
+ * Goal: give extension authors a one-liner to spin up a fake
+ * `ExtensionContext` and a Hono test app, so unit tests run without a
+ * real database or auth setup. For integration tests against a real
+ * Postgres + engine, use Bun's `testcontainers` directly — this module
+ * is the offline-fast path.
+ *
+ * Three primitives:
+ *   - `createTestContext(overrides?)` — minimal `ExtensionContext` with
+ *     no-op stubs for everything (db, auth, events, services,
+ *     queryAlter, entityAccess, registerPublicRoute). Override per-test.
+ *   - `createTestApp(extension, ctx?)` — runs `extension.register()`
+ *     against a fresh Hono and returns the app, ready for `.request()`.
+ *   - `mockDb(presets?)` — records query-builder calls; returns presets
+ *     when an `.execute()` / `.executeTakeFirst()` lands. Enough to
+ *     fake CRUD paths; falls back to empty arrays / undefined.
+ */
+import { Hono } from 'hono';
+import type { ZveltioExtension, ExtensionContext } from '../extension/index.js';
+export interface MockCall {
+    /** Method name chain, e.g. `'selectFrom.where.execute'`. */
+    chain: string;
+    /** Args of the terminal call. */
+    args: unknown[];
+}
+export interface MockDbPresets {
+    /**
+     * Preset a return value for a specific chain. Match is by suffix —
+     * `'selectFrom.zvd_users.execute'` matches the chain ending in that.
+     * Use exact chains for precision.
+     *
+     * @example
+     *   mockDb({
+     *     'selectFrom.zvd_users.selectAll.execute': [{ id: '1', name: 'A' }],
+     *     'selectFrom.zvd_users.executeTakeFirst': { id: '1', name: 'A' },
+     *   })
+     */
+    [chain: string]: unknown;
+}
+export interface MockDb {
+    /** Recorded calls, oldest first. Reset between tests. */
+    readonly calls: MockCall[];
+    /** Reset call history (presets stay). */
+    reset(): void;
+    /** Add or override a preset after construction. */
+    preset(chain: string, value: unknown): void;
+}
+/**
+ * Build a recording mock Kysely-shaped object. Any method chain is
+ * accepted; the terminal `.execute()` / `.executeTakeFirst()` /
+ * `.executeTakeFirstOrThrow()` returns a preset if matched, otherwise
+ * an empty list (for execute) or undefined.
+ */
+export declare function mockDb(presets?: MockDbPresets): any & MockDb;
+export interface MockEventBus {
+    emit(event: string, payload: unknown): void;
+    on(event: string, handler: (payload: any) => void): () => void;
+    onBefore(event: string, handler: (payload: any) => any): () => void;
+    runBefore(event: string, seed: Record<string, unknown>): Promise<any>;
+    /** Recorded emits, oldest first. */
+    readonly emitted: Array<{
+        event: string;
+        payload: unknown;
+    }>;
+    /** Reset emit log. */
+    reset(): void;
+}
+export declare function mockEventBus(): MockEventBus;
+export declare function mockServiceRegistry(): {
+    register(name: string, value: unknown): void;
+    unregister(name: string): void;
+    get<T = unknown>(name: string): T | null;
+    has(name: string): boolean;
+    list(): string[];
+    waitFor<T = unknown>(name: string, timeoutMs?: number): Promise<T>;
+};
+export interface MockAuthOptions {
+    /** If set, getSession returns `{ user: this }`. If null, getSession returns null. */
+    user?: {
+        id: string;
+        email?: string;
+        name?: string;
+        roles?: string[];
+    } | null;
+}
+export declare function mockAuth(opts?: MockAuthOptions): any;
+export interface CreateTestContextOptions {
+    /** Override the mocked db. Default: `mockDb()`. */
+    db?: any;
+    /** Override the mocked auth. Default: signed-in test user. */
+    auth?: any;
+    /** Override the mocked event bus. Default: in-memory. */
+    events?: MockEventBus;
+    /** Provide additional fields. They go onto the returned ctx as-is. */
+    extra?: Partial<ExtensionContext<any>>;
+}
+export declare function createTestContext(opts?: CreateTestContextOptions): ExtensionContext<any>;
+export interface CreateTestAppOptions {
+    /** Override the context handed to register(). Default: `createTestContext()`. */
+    ctx?: ExtensionContext<any>;
+    /**
+     * When the extension uses `mountStrategy: 'subapp'`, the engine normally
+     * mounts the sub-app at `/ext/<name>`. For tests we replicate that so
+     * `.request('/ext/<name>/...')` works. Pass `false` to skip the wrapper
+     * and mount the sub-app at root for cleaner test URLs.
+     */
+    mountSubappAt?: string | false;
+}
+/**
+ * Spin up a Hono test app with the extension's routes registered. Returns
+ * the outer Hono so callers can use `.request(path, init)` for assertions.
+ *
+ * Honors the extension's `mountStrategy`. For `'subapp'`, the outer app
+ * mounts the sub-app at `/ext/<extension.name>` by default — same shape
+ * the engine produces in production.
+ */
+export declare function createTestApp(extension: ZveltioExtension<any>, opts?: CreateTestAppOptions): Promise<Hono>;
+export { withTestDb, startTestDb, applyMigrationStrings, applyMigrationFiles, stopReusedTestDb, splitStatements, type TestDb, type WithTestDbOptions, } from './with-test-db.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.js

@@ -0,0 +1,283 @@
+/**
+ * Testing helpers for Zveltio extensions (S4-06).
+ *
+ * Goal: give extension authors a one-liner to spin up a fake
+ * `ExtensionContext` and a Hono test app, so unit tests run without a
+ * real database or auth setup. For integration tests against a real
+ * Postgres + engine, use Bun's `testcontainers` directly — this module
+ * is the offline-fast path.
+ *
+ * Three primitives:
+ *   - `createTestContext(overrides?)` — minimal `ExtensionContext` with
+ *     no-op stubs for everything (db, auth, events, services,
+ *     queryAlter, entityAccess, registerPublicRoute). Override per-test.
+ *   - `createTestApp(extension, ctx?)` — runs `extension.register()`
+ *     against a fresh Hono and returns the app, ready for `.request()`.
+ *   - `mockDb(presets?)` — records query-builder calls; returns presets
+ *     when an `.execute()` / `.executeTakeFirst()` lands. Enough to
+ *     fake CRUD paths; falls back to empty arrays / undefined.
+ */
+import { Hono } from 'hono';
+/**
+ * Build a recording mock Kysely-shaped object. Any method chain is
+ * accepted; the terminal `.execute()` / `.executeTakeFirst()` /
+ * `.executeTakeFirstOrThrow()` returns a preset if matched, otherwise
+ * an empty list (for execute) or undefined.
+ */
+export function mockDb(presets = {}) {
+    const calls = [];
+    const presetMap = new Map(Object.entries(presets));
+    function buildChain(prefix) {
+        const proxy = new Proxy(() => { }, {
+            get(_, prop) {
+                if (typeof prop === 'symbol')
+                    return undefined;
+                if (prop === 'calls')
+                    return calls;
+                if (prop === 'reset')
+                    return () => {
+                        calls.length = 0;
+                    };
+                if (prop === 'preset')
+                    return (chain, value) => {
+                        presetMap.set(chain, value);
+                    };
+                if (prop === 'then')
+                    return undefined;
+                // Build next link in the chain.
+                return buildChain([...prefix, prop]);
+            },
+            // NOTE: synchronous apply. Terminal calls return a Promise; non-
+            // terminal calls return the proxy itself so further chaining works
+            // without awaiting. (Async apply would wrap every step in a Promise
+            // and break `.selectFrom().selectAll().execute()` chains.)
+            apply(_t, _this, args) {
+                const chain = prefix.join('.');
+                calls.push({ chain, args });
+                const terminal = prefix[prefix.length - 1];
+                const isTerminal = terminal === 'execute' ||
+                    terminal === 'executeTakeFirst' ||
+                    terminal === 'executeTakeFirstOrThrow';
+                if (isTerminal) {
+                    const preset = matchPreset(chain, presetMap);
+                    if (preset !== undefined) {
+                        const resolved = typeof preset === 'function' ? preset(...args) : preset;
+                        return Promise.resolve(resolved);
+                    }
+                    if (terminal === 'execute')
+                        return Promise.resolve([]);
+                    if (terminal === 'executeTakeFirst')
+                        return Promise.resolve(undefined);
+                    // executeTakeFirstOrThrow with no preset → reject
+                    return Promise.reject(new Error(`mockDb: no preset for chain "${chain}" and executeTakeFirstOrThrow has no fallback`));
+                }
+                // Non-terminal: keep chaining on the same proxy (its prefix is
+                // unchanged; the next property access will extend via get()).
+                return proxy;
+            },
+        });
+        return proxy;
+    }
+    return buildChain([]);
+}
+function matchPreset(chain, presets) {
+    // Exact match wins.
+    if (presets.has(chain))
+        return presets.get(chain);
+    // Suffix match: preset 'foo.execute' matches 'selectFrom.x.foo.execute'.
+    for (const [key, val] of presets) {
+        if (chain.endsWith(key))
+            return val;
+    }
+    return undefined;
+}
+export function mockEventBus() {
+    const emitted = [];
+    const listeners = new Map();
+    const beforeHandlers = new Map();
+    return {
+        emit(event, payload) {
+            emitted.push({ event, payload });
+            for (const h of listeners.get(event) ?? [])
+                h(payload);
+        },
+        on(event, handler) {
+            const list = listeners.get(event) ?? [];
+            list.push(handler);
+            listeners.set(event, list);
+            return () => {
+                const cur = listeners.get(event);
+                if (cur) {
+                    const idx = cur.indexOf(handler);
+                    if (idx >= 0)
+                        cur.splice(idx, 1);
+                }
+            };
+        },
+        onBefore(event, handler) {
+            const list = beforeHandlers.get(event) ?? [];
+            list.push(handler);
+            beforeHandlers.set(event, list);
+            return () => {
+                const cur = beforeHandlers.get(event);
+                if (cur) {
+                    const idx = cur.indexOf(handler);
+                    if (idx >= 0)
+                        cur.splice(idx, 1);
+                }
+            };
+        },
+        async runBefore(event, seed) {
+            const payload = { ...seed };
+            let aborted = false;
+            let abortReason = '';
+            payload.abort = (reason) => {
+                aborted = true;
+                abortReason = reason;
+                const err = new Error(`Aborted: ${reason}`);
+                err.name = 'AbortHookError';
+                err.reason = reason;
+                throw err;
+            };
+            payload.mutate = (patch) => {
+                const key = event === 'record.beforeUpdate' ? 'patch' : 'data';
+                payload[key] = { ...payload[key], ...patch };
+            };
+            for (const h of beforeHandlers.get(event) ?? []) {
+                await h(payload);
+            }
+            return payload;
+        },
+        get emitted() {
+            return emitted;
+        },
+        reset() {
+            emitted.length = 0;
+            listeners.clear();
+            beforeHandlers.clear();
+        },
+    };
+}
+// ─── Mock service registry ─────────────────────────────────────────────────
+export function mockServiceRegistry() {
+    const services = new Map();
+    return {
+        register(name, value) {
+            services.set(name, value);
+        },
+        unregister(name) {
+            services.delete(name);
+        },
+        get(name) {
+            return services.get(name) ?? null;
+        },
+        has(name) {
+            return services.has(name);
+        },
+        list() {
+            return [...services.keys()];
+        },
+        async waitFor(name) {
+            const v = services.get(name);
+            if (v === undefined)
+                throw new Error(`mockServiceRegistry: no service "${name}" registered`);
+            return v;
+        },
+    };
+}
+// ─── Mock queryAlter / entityAccess scoped registries ──────────────────────
+function mockQueryAlterScope() {
+    const entries = [];
+    return {
+        register(def) {
+            entries.push(def);
+        },
+        list() {
+            return entries.map((e) => ({ table: e.table }));
+        },
+        unregisterAll() {
+            entries.length = 0;
+        },
+    };
+}
+function mockEntityAccessScope() {
+    const entries = [];
+    return {
+        register(def) {
+            entries.push(def);
+        },
+        list() {
+            return entries.map((e) => ({ table: e.table }));
+        },
+        unregisterAll() {
+            entries.length = 0;
+        },
+    };
+}
+export function mockAuth(opts = {}) {
+    const user = opts.user === undefined ? { id: 'test-user', email: 'test@example.com', roles: [] } : opts.user;
+    return {
+        api: {
+            async getSession() {
+                return user === null ? null : { user };
+            },
+        },
+    };
+}
+export function createTestContext(opts = {}) {
+    const db = opts.db ?? mockDb();
+    const events = opts.events ?? mockEventBus();
+    return {
+        db,
+        auth: opts.auth ?? mockAuth(),
+        fieldTypeRegistry: {
+            register: () => { },
+            get: () => undefined,
+            has: () => false,
+            list: () => [],
+            getAll: () => [],
+            deserialize: (_t, v) => v,
+            serialize: (_t, v) => v,
+        },
+        events: events,
+        checkPermission: async () => true,
+        getUserRoles: async () => ['admin'],
+        DDLManager: {},
+        services: mockServiceRegistry(),
+        queryAlter: mockQueryAlterScope(),
+        entityAccess: mockEntityAccessScope(),
+        registerPublicRoute: () => { },
+        internals: {},
+        ...(opts.extra ?? {}),
+    };
+}
+/**
+ * Spin up a Hono test app with the extension's routes registered. Returns
+ * the outer Hono so callers can use `.request(path, init)` for assertions.
+ *
+ * Honors the extension's `mountStrategy`. For `'subapp'`, the outer app
+ * mounts the sub-app at `/ext/<extension.name>` by default — same shape
+ * the engine produces in production.
+ */
+export async function createTestApp(extension, opts = {}) {
+    const ctx = opts.ctx ?? createTestContext();
+    const strategy = extension.mountStrategy ?? 'global';
+    if (strategy === 'subapp') {
+        const outer = new Hono();
+        const sub = new Hono();
+        await extension.register(sub, ctx);
+        const mountPath = opts.mountSubappAt === false ? '/' : (opts.mountSubappAt ?? `/ext/${extension.name}`);
+        outer.route(mountPath, sub);
+        return outer;
+    }
+    const app = new Hono();
+    await extension.register(app, ctx);
+    return app;
+}
+// ─── Integration test helpers (Postgres) ─────────────────────────────────
+//
+// `withTestDb` + friends live in a separate module so the testcontainers
+// dynamic import doesn't fan out on every consumer of `mockDb` /
+// `createTestContext`. Re-exported here for the
+// `import { withTestDb } from '@zveltio/sdk/testing'` ergonomics.
+export { withTestDb, startTestDb, applyMigrationStrings, applyMigrationFiles, stopReusedTestDb, splitStatements, } from './with-test-db.js';