@svadmin/core 0.21.1 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",

package/src/context.svelte.ts

@@ -72,8 +72,10 @@ export function setAuthProvider(provider: AuthProvider): void {
   authProvider = provider;
 }
 
-export function getAuthProvider(): AuthProvider {
-  if (!authProvider) throw new Error('AuthProvider not found. Did you call setAuthProvider in App.svelte?');
+export function getAuthProvider(): AuthProvider;
+export function getAuthProvider(options: { optional: true }): AuthProvider | null;
+export function getAuthProvider(options?: { optional?: boolean }): AuthProvider | null {
+  if (!authProvider && !options?.optional) throw new Error('AuthProvider not found. Did you call setAuthProvider in App.svelte?');
   return authProvider;
 }
 

package/src/data-transfer.svelte.ts

@@ -21,7 +21,7 @@ export interface UseExportOptions<TData extends BaseRecord = BaseRecord> {
  */
 export function useExport<TData extends BaseRecord = BaseRecord>(options: UseExportOptions<TData> = {}) {
   const parsed = useParsed();
-  const resource = options.resource ?? parsed.resource ?? '';
+  const resource = $derived(options.resource ?? parsed.resource ?? '');
   let isLoading = $state(false);
 
   async function triggerExport() {
@@ -55,7 +55,7 @@ export function useExport<TData extends BaseRecord = BaseRecord>(options: UseExp
         ? allRecords.map(options.mapData)
         : allRecords.map(r => r as unknown as Record<string, unknown>);
 
-      if (options.download !== false) {
+      if (options.download !== false && typeof document !== 'undefined') {
         const fields = Object.keys(mapped[0]);
         const header = fields.join(',');
         const rows = mapped.map(record =>
@@ -109,7 +109,7 @@ export interface UseImportOptions<TData = Record<string, unknown>> {
  */
 export function useImport<TData = Record<string, unknown>>(options: UseImportOptions<TData> = {}) {
   const parsed = useParsed();
-  const resource = options.resource ?? parsed.resource ?? '';
+  const resource = $derived(options.resource ?? parsed.resource ?? '');
   let isLoading = $state(false);
   let mutationResult = $state<{ succeeded: unknown[]; errored: { request: unknown; error: unknown }[] } | null>(null);
 

package/src/form-hooks.svelte.ts

@@ -1,12 +1,12 @@
 import { useQueryClient } from '@tanstack/svelte-query';
 import { useParsed } from './useParsed.svelte';
 import { getAdminOptions } from './options.svelte';
-import { getDataProviderForResource } from './context.svelte';
+import { getDataProviderForResource, getResource } from './context.svelte';
 import { createQuery, createMutation } from '@tanstack/svelte-query';
 import { notify } from './notification.svelte';
 import { t } from './i18n.svelte';
 import { audit } from './audit';
-import { navigate } from './router';
+import { navigate, currentPath } from './router';
 import { HttpError } from './types';
 import type { BaseRecord, MutationMode, KnownResources } from './types';
 
@@ -110,14 +110,16 @@ export interface UseFormReturn<
   /** Reset form to initial/query values. Clears tainted and errors. */
   reset: () => void;
 
-  // ─── State ────────────────────────────────────────────────────
+  // ─── State ──────────────────────────────────────────────────────
   readonly loading: boolean;
   readonly submitting: boolean;
-  readonly resource: string;
   readonly action: 'create' | 'edit' | 'clone';
+  readonly resource: string;
   readonly id: string | number | undefined;
-  setId: (newId: string | number) => void;
-  readonly mutationMode: MutationMode;
+  readonly isDirty: boolean;
+  setId: (id: string | number | undefined) => void;
+  setAction: (action: 'create' | 'edit' | 'clone') => void;
+  mutationMode: MutationMode;
   redirect: (to: 'list' | 'edit' | 'show' | false) => void;
 
   // ─── AutoSave ─────────────────────────────────────────────────
@@ -140,13 +142,13 @@ export function useForm<
   const parsed = useParsed();
   const adminOptions = getAdminOptions();
 
-  const resource = options.resource ?? parsed.resource ?? '';
-  const action = options.action ?? (parsed.action === 'list' ? 'create' : parsed.action as 'create' | 'edit' | 'clone') ?? 'create';
+  const resource = $derived(options.resource ?? parsed.resource ?? '');
+  let action = $state<'create' | 'edit' | 'clone'>(options.action ?? (parsed.action === 'list' ? 'create' : parsed.action as 'create' | 'edit' | 'clone') ?? 'create');
   let currentId = $state<string | number | undefined>(options.id ?? parsed.id);
 
-  const defaultRedirectOpt = action === 'clone' ? adminOptions.redirect?.afterClone : action === 'edit' ? adminOptions.redirect?.afterEdit : adminOptions.redirect?.afterCreate;
+  const defaultRedirectOpt = $derived(action === 'clone' ? adminOptions.redirect?.afterClone : action === 'edit' ? adminOptions.redirect?.afterEdit : adminOptions.redirect?.afterCreate);
   const {
-    redirect: redirectDefault = defaultRedirectOpt ?? 'list',
+    redirect: redirectOption,
     successNotification, errorNotification,
     onMutationSuccess, onMutationError,
     meta: hookMeta, queryMeta: hookQueryMeta, mutationMeta: hookMutationMeta,
@@ -159,13 +161,17 @@ export function useForm<
     onChange: onChangeFn,
     onSubmit: onSubmitFn,
   } = options;
+  // Reactive redirect: uses $derived `defaultRedirectOpt` so redirect target
+  // updates when `action` changes at runtime (e.g., via `setAction`).
+  const redirectDefault = $derived(redirectOption ?? defaultRedirectOpt ?? 'list');
 
-  const provider = getDataProviderForResource(resource, dataProviderName);
-  const parsedMeta = typeof window !== 'undefined' ? Object.fromEntries(new URLSearchParams(window.location.search).entries()) : {};
+  const provider = $derived(getDataProviderForResource(resource, dataProviderName));
+  const parsedMeta = useParsed().params || {};
   const queryMeta = { ...parsedMeta, ...hookMeta, ...hookQueryMeta };
   const mutationMeta = { ...parsedMeta, ...hookMeta, ...hookMutationMeta };
 
-  function setId(newId: string | number) { currentId = newId; }
+  function setId(newId: string | number | undefined) { currentId = newId; }
+  function setAction(newAction: 'create' | 'edit' | 'clone') { action = newAction; }
 
   // ─── Form values (single source of truth) ───────────────────────
   let values = $state<TVariables>((options.defaultValues ?? {}) as TVariables);
@@ -253,28 +259,29 @@ export function useForm<
   }
 
   // ─── Query (edit/clone mode) ────────────────────────────────────
-  const query = (action === 'edit' || action === 'clone')
-    ? createQuery(() => ({
-        queryKey: [resource, 'one', currentId],
-        queryFn: async () => {
-          const result = await provider.getOne<BaseRecord>({ resource, id: currentId!, meta: queryMeta });
-          return result.data;
-        },
-        enabled: (queryOptions?.enabled ?? true) && currentId != null,
-        staleTime: queryOptions?.staleTime,
-      }))
-    : null;
+  // Always create the query — use `enabled` to conditionally activate.
+  // This ensures setAction('edit') at runtime will trigger a fetch.
+  const query = createQuery(() => ({
+    queryKey: [resource, 'one', currentId],
+    queryFn: async () => {
+      const result = await provider.getOne<BaseRecord>({ resource, id: currentId!, meta: queryMeta });
+      return result.data;
+    },
+    enabled: (queryOptions?.enabled ?? true) && (action === 'edit' || action === 'clone') && currentId != null,
+    staleTime: queryOptions?.staleTime,
+  }));
 
   // Auto-populate values from query data
   let queryInitializedId: string | number | undefined = undefined;
-  if (query) {
+  {
     $effect.pre(() => {
       if (queryInitializedId === currentId) return;
       const data = query.data as Record<string, unknown> | undefined;
-      if (data && (currentId == null || String(data.id) === String(currentId) || !data.id)) {
+      const pk = getResource(resource).primaryKey ?? 'id';
+      if (data && (currentId == null || String(data[pk]) === String(currentId) || !data[pk])) {
         // In clone mode, strip out identifiers
         const targetData = action === 'clone' 
-          ? Object.fromEntries(Object.entries(data).filter(([k]) => k !== 'id' && k !== '_id'))
+          ? Object.fromEntries(Object.entries(data).filter(([k]) => k !== 'id' && k !== '_id' && k !== pk))
           : data;
         // Merge: defaultValues < query data
         const merged = { ...(options.defaultValues ?? {}), ...targetData } as TVariables;
@@ -294,10 +301,11 @@ export function useForm<
     onSuccess: (data: { data: TData }) => {
       if (invalidateScopes !== false) queryClient.invalidateQueries({ queryKey: [resource] });
       if (successNotification !== false) notify({ type: 'success', message: typeof successNotification === 'string' ? successNotification : t('common.createSuccess') });
-      audit({ action: 'create', resource, recordId: String((data.data as Record<string, unknown>).id) });
+      const pk = getResource(resource).primaryKey ?? 'id';
+      audit({ action: 'create', resource, recordId: String((data.data as Record<string, unknown>)[pk]) });
       onMutationSuccess?.(data);
       if (redirectOverride !== false) {
-        const newId = (data.data as Record<string, unknown>).id;
+        const newId = (data.data as Record<string, unknown>)[pk];
         if (newId != null) currentId = newId as string | number;
         doRedirect(redirectOverride ?? redirectDefault);
       }
@@ -319,9 +327,14 @@ export function useForm<
   }));
 
   function doRedirect(to: 'list' | 'edit' | 'show' | false) {
-    if (to === 'list') navigate(`/${resource}`);
-    else if (to === 'edit' && currentId) navigate(`/${resource}/edit/${currentId}`);
-    else if (to === 'show' && currentId) navigate(`/${resource}/show/${currentId}`);
+    const path = currentPath().split('?')[0];
+    const parts = path.split('/');
+    const resIdx = parts.lastIndexOf(String(resource));
+    const base = resIdx >= 0 ? parts.slice(0, resIdx + 1).join('/') : `/${resource}`;
+
+    if (to === 'list') navigate(base);
+    else if (to === 'edit' && currentId) navigate(`${base}/edit/${currentId}`);
+    else if (to === 'show' && currentId) navigate(`${base}/show/${currentId}`);
   }
 
   // ─── Submit ─────────────────────────────────────────────────────
@@ -353,7 +366,8 @@ export function useForm<
   let lastAutoSaveError = $state<unknown>(null);
 
   function triggerAutoSave() {
-    if (!autoSaveOpts?.enabled || action === 'create' || action === 'clone') return;
+    const currentAction = action; // read $state reactively at call time
+    if (!autoSaveOpts?.enabled || currentAction === 'create' || currentAction === 'clone') return;
     if (autoSaveTimer) clearTimeout(autoSaveTimer);
 
     autoSaveTimer = setTimeout(async () => {
@@ -419,11 +433,16 @@ export function useForm<
     reset,
 
     // State
-    get loading() { return query?.isLoading ?? false; },
+    get loading() { return query.isLoading ?? false; },
     get submitting() { return createMut.isPending || updateMut.isPending; },
-    resource, action,
+    get action() { return action; },
+    get resource() { return resource; },
     get id() { return currentId; },
-    setId, mutationMode, redirect: doRedirect,
+    get isDirty() { return Object.keys(tainted).length > 0; },
+    setId,
+    setAction,
+    mutationMode,
+    redirect: doRedirect,
 
     // AutoSave
     triggerAutoSave,
@@ -437,6 +456,6 @@ export function useForm<
 
     // Raw escape hatches
     query,
-    mutation: action === 'edit' ? updateMut : createMut,
+    get mutation() { return action === 'edit' ? updateMut : createMut; },
   };
 }

package/src/hook-utils.svelte.ts

@@ -54,26 +54,24 @@ export interface LiveSubscriptionParams {
   enabled?: boolean;
 }
 
-export function createLiveSubscription(params: LiveSubscriptionParams): void {
-  const {
-    resource,
-    liveProvider,
-    liveMode = 'off',
-    onLiveEvent,
-    enabled = true,
-  } = params;
-
-  if (!liveProvider || liveMode === 'off' || !enabled) return;
-
+export function createLiveSubscription(paramsFn: () => LiveSubscriptionParams): void {
   const queryClient = useQueryClient();
 
   $effect(() => {
+    const params = paramsFn();
+    const liveProvider = params.liveProvider;
+    const liveMode = params.liveMode ?? 'off';
+    const enabled = params.enabled ?? true;
+
+    if (!liveProvider || liveMode === 'off' || !enabled) return;
+
     const unsubscribe = liveProvider.subscribe({
-      resource,
+      resource: params.resource,
+      liveParams: params.liveParams,
       callback: (event: LiveEvent) => {
-        onLiveEvent?.(event);
+        params.onLiveEvent?.(event);
         if (liveMode === 'auto') {
-          queryClient.invalidateQueries({ queryKey: [resource] });
+          queryClient.invalidateQueries({ queryKey: [params.resource] });
         }
       },
     });

package/src/hooks.svelte.ts

@@ -54,9 +54,10 @@ export function useInfiniteList<TData extends BaseRecord = BaseRecord, TError =
   const parsed = useParsed();
   const resource = options.resource ?? parsed.resource ?? '';
   const adminOptions = getAdminOptions();
-  const provider = getDataProviderForResource(resource, options.dataProviderName);
 
-  const query = createInfiniteQuery<{ data: TData[]; total: number }, TError>(() => ({
+  const query = createInfiniteQuery<{ data: TData[]; total: number }, TError>(() => {
+    const provider = getDataProviderForResource(resource, options.dataProviderName);
+    return {
     queryKey: [resource, 'infiniteList', options.sorters, options.filters, options.meta],
     queryFn: async ({ pageParam = 1 }) => {
       const result = await provider.getList<TData>({
@@ -76,7 +77,8 @@ export function useInfiniteList<TData extends BaseRecord = BaseRecord, TError =
     },
     enabled: options.queryOptions?.enabled ?? true,
     staleTime: options.queryOptions?.staleTime ?? adminOptions.reactQuery?.staleTime,
-  }));
+    };
+  });
 
   const overtime = createOvertimeTracker(() => query.isLoading, options.overtimeOptions ?? adminOptions.overtime);
 
@@ -108,7 +110,6 @@ export interface UseSelectOptions<TData extends BaseRecord = BaseRecord, TOption
 export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { label: string; value: string | number }>(options: UseSelectOptions<TData, TOption>) {
   const { resource, optionLabel = 'title', optionValue = 'id', sorters, filters, pagination, meta, dataProviderName, onSearch, debounce: debounceMs = 300 } = options;
   const adminOptions = getAdminOptions();
-  const provider = getDataProviderForResource(resource, dataProviderName);
 
   let searchText = $state('');
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
@@ -122,26 +123,32 @@ export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { lab
 
   const effectivePageSize = options.fetchSize ?? pagination?.pageSize ?? 999;
 
-  const query = createQuery<{ data: TData[]; total: number }>(() => ({
+  const query = createQuery<{ data: TData[]; total: number }>(() => {
+    const provider = getDataProviderForResource(resource, dataProviderName);
+    return {
     queryKey: [resource, 'select', allFilters, sorters, pagination, meta],
     queryFn: () => provider.getList<TData>({ resource, sorters, filters: allFilters, pagination: { current: 1, pageSize: effectivePageSize }, meta }),
     enabled: options.queryOptions?.enabled ?? true,
     staleTime: options.queryOptions?.staleTime ?? adminOptions.reactQuery?.staleTime,
-  }));
+    };
+  });
 
   // Parallel query to ensure default values are always available in options
   const defaultValueIds = options.defaultValue ?? [];
   const defaultValueQuery = defaultValueIds.length > 0
-    ? createQuery<{ data: TData[] }>(() => ({
-        queryKey: [resource, 'select-defaults', defaultValueIds],
-        queryFn: async () => {
-          if (provider.getMany) return provider.getMany<TData>({ resource, ids: defaultValueIds, meta });
-          const results = await Promise.all(defaultValueIds.map(id => provider.getOne<TData>({ resource, id, meta })));
-          return { data: results.map(r => r.data) };
-        },
-        enabled: (options.defaultValueQueryOptions?.enabled ?? true) && defaultValueIds.length > 0,
-        staleTime: options.defaultValueQueryOptions?.staleTime ?? Infinity,
-      }))
+    ? createQuery<{ data: TData[] }>(() => {
+        const provider = getDataProviderForResource(resource, dataProviderName);
+        return {
+          queryKey: [resource, 'select-defaults', defaultValueIds],
+          queryFn: async () => {
+            if (provider.getMany) return provider.getMany<TData>({ resource, ids: defaultValueIds, meta });
+            const results = await Promise.all(defaultValueIds.map(id => provider.getOne<TData>({ resource, id, meta })));
+            return { data: results.map(r => r.data) };
+          },
+          enabled: (options.defaultValueQueryOptions?.enabled ?? true) && defaultValueIds.length > 0,
+          staleTime: options.defaultValueQueryOptions?.staleTime ?? Infinity,
+        };
+      })
     : null;
 
   const selectOptions = $derived.by(() => {
@@ -151,14 +158,14 @@ export function useSelect<TData extends BaseRecord = BaseRecord, TOption = { lab
     const defaultQueryResult = defaultValueQuery as { data: { data: TData[] } | undefined } | null;
     const defaultData: TData[] = defaultQueryResult?.data?.data ?? [];
     const allData: TData[] = [...data];
-    const existingIds = new Set(data.map((d: TData) => String((d as Record<string, unknown>)[typeof optionValue === 'string' ? optionValue : 'id'])));
+    const resolveValue = (item: TData) => typeof optionValue === 'function' ? optionValue(item) : (item as Record<string, unknown>)[optionValue];
+    const existingIds = new Set(data.map((d: TData) => String(resolveValue(d))));
     for (const item of defaultData) {
-      const itemId = String((item as Record<string, unknown>)[typeof optionValue === 'string' ? optionValue : 'id']);
-      if (!existingIds.has(itemId)) allData.push(item);
+      if (!existingIds.has(String(resolveValue(item)))) allData.push(item);
     }
     return allData.map((item: TData) => {
       const label = typeof optionLabel === 'function' ? optionLabel(item) : String((item as Record<string, unknown>)[optionLabel] ?? '');
-      const value = typeof optionValue === 'function' ? optionValue(item) : (item as Record<string, unknown>)[optionValue];
+      const value = resolveValue(item);
       return { label, value } as unknown as TOption;
     });
   });
@@ -199,9 +206,10 @@ export interface UseCustomOptions<TData = unknown, TError = HttpError> {
 
 export function useCustom<TData = unknown, TError = HttpError>(options: UseCustomOptions<TData, TError>) {
   const adminOptions = getAdminOptions();
-  const provider = getDataProvider(options.dataProviderName);
 
-  const query = createQuery<{ data: TData }, TError>(() => ({
+  const query = createQuery<{ data: TData }, TError>(() => {
+    const provider = getDataProvider(options.dataProviderName);
+    return {
     queryKey: ['custom', options.url, options.method, options.config, options.meta],
     queryFn: async () => {
       if (!provider.custom) throw new Error('DataProvider does not support custom method');
@@ -218,7 +226,8 @@ export function useCustom<TData = unknown, TError = HttpError>(options: UseCusto
     },
     enabled: options.queryOptions?.enabled ?? true,
     staleTime: options.queryOptions?.staleTime ?? adminOptions.reactQuery?.staleTime,
-  }));
+    };
+  });
 
   const overtime = createOvertimeTracker(() => query.isLoading, options.overtimeOptions ?? adminOptions.overtime);
 
@@ -228,11 +237,11 @@ export function useCustom<TData = unknown, TError = HttpError>(options: UseCusto
 // ─── useCustomMutation ──────────────────────────────────────────────
 
 export function useCustomMutation<TData = unknown, TError = HttpError, TVariables = unknown>(dataProviderName?: string) {
-  const provider = getDataProvider(dataProviderName);
   const queryClient = useQueryClient();
 
   const mutation = createMutation<{ data: TData }, TError, { url: string; method: 'get' | 'post' | 'put' | 'patch' | 'delete'; values?: TVariables; meta?: Record<string, unknown> }>(() => ({
     mutationFn: async (params) => {
+      const provider = getDataProvider(dataProviderName);
       if (!provider.custom) throw new Error('DataProvider does not support custom method');
       return provider.custom<TData>({ url: params.url, method: params.method, payload: params.values, meta: params.meta });
     },
@@ -331,8 +340,10 @@ export function useInvalidate() {
     const scopes = params.invalidates || ['resourceAll'];
     for (const scope of scopes) {
       if (scope === 'resourceAll') queryClient.invalidateQueries({ queryKey: [params.resource] });
-      else if (scope === 'detail' && params.id) queryClient.invalidateQueries({ queryKey: [params.resource, 'one', params.id] });
+      else if ((scope === 'detail' || scope === 'one') && params.id) queryClient.invalidateQueries({ queryKey: [params.resource, 'one', params.id] });
+      else if (scope === 'one') queryClient.invalidateQueries({ queryKey: [params.resource, 'one'] });
       else if (scope === 'list') queryClient.invalidateQueries({ queryKey: [params.resource, 'list'] });
+      else if (scope === 'many') queryClient.invalidateQueries({ queryKey: [params.resource, 'many'] });
     }
   };
 }

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   setAuthProvider, getAuthProvider,
   setResources, getResources, getResource,
   setRouterProvider, getRouterProvider,
+  setLiveProvider, getLiveProvider,
 } from './context.svelte';
 export type { DataProviderInput } from './context.svelte';
 export {

package/src/live.svelte.ts

@@ -13,8 +13,8 @@ export interface LiveEvent {
 }
 
 export interface LiveProvider {
-  subscribe(params: { resource: string; callback: (event: LiveEvent) => void }): () => void;
-  unsubscribe?(params: { resource: string }): void;
+  subscribe(params: { resource: string; liveParams?: Record<string, unknown>; callback: (event: LiveEvent) => void }): () => void;
+  unsubscribe?(params: { resource: string; liveParams?: Record<string, unknown> }): void;
   publish?(event: LiveEvent): void;
 }
 

package/src/mutation-hooks.svelte.ts

@@ -1,6 +1,6 @@
 import { createMutation, useQueryClient } from '@tanstack/svelte-query';
 import { getAdminOptions } from './options.svelte';
-import { getDataProviderForResource } from './context.svelte';
+import { getDataProviderForResource, getResource } from './context.svelte';
 import { useParsed } from './useParsed.svelte';
 import { audit } from './audit';
 import { UndoError } from './types';
@@ -63,7 +63,9 @@ export function useCreate<TData extends BaseRecord = BaseRecord, TError = HttpEr
         queryClient.invalidateQueries({ queryKey: [resName] });
       }
       fireSuccessNotification(params.successNotification, 'Created successfully', data.data, params.variables, resName);
-      audit({ action: 'create', resource: resName, recordId: String((data.data as Record<string, unknown>).id) });
+      const res = getResource(resName);
+      const pk = res.primaryKey ?? 'id';
+      audit({ action: 'create', resource: resName, recordId: String((data.data as Record<string, unknown>)[pk]) });
       if (typeof options.mutationOptions?.onSuccess === 'function') {
         (options.mutationOptions.onSuccess as Function)(data, params, context);
       }
@@ -152,7 +154,10 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       }
     },
     onMutate: async (params) => {
-      if (mutationMode === 'pessimistic') return undefined;
+      const userOnMutate = (options.mutationOptions as any)?.onMutate;
+      const userContext = typeof userOnMutate === 'function' ? await userOnMutate(params) : undefined;
+      
+      if (mutationMode === 'pessimistic') return { _svadmin_ctx: true, userContext };
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
       
@@ -160,7 +165,9 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       const previousDetail = queryClient.getQueryData([resName, 'one', targetId]);
       const previousList = queryClient.getQueriesData({ queryKey: [resName, 'list'] });
       
+      const pk = getResource(resName).primaryKey ?? 'id';
       const updater = params.optimisticUpdateMap;
+      
       if (updater?.detail) {
         queryClient.setQueryData([resName, 'one', targetId], (old: unknown) => updater.detail!(old, params.variables, targetId));
       } else {
@@ -173,13 +180,14 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
         queryClient.setQueriesData({ queryKey: [resName, 'list'] }, (old: unknown) => {
           if (!old || typeof old !== 'object' || !('data' in old)) return old;
           const o = old as { data: Record<string, unknown>[] };
-          return { ...o, data: o.data.map((item) => String(item.id) === String(targetId) ? { ...item, ...params.variables } : item) };
+          return { ...o, data: o.data.map((item) => String(item[pk]) === String(targetId) ? { ...item, ...params.variables } : item) };
         });
       }
 
-      return { previousDetail, previousList };
+      return { _svadmin_ctx: true, userContext, previousDetail, previousList };
     },
     onSuccess: (data, params, context) => {
+      const extractedCtx = (context as any)?._svadmin_ctx ? (context as any).userContext : context;
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
       if (params.invalidates !== false) {
@@ -188,10 +196,11 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       fireSuccessNotification(params.successNotification, 'Updated successfully', data.data, params.variables, resName);
       audit({ action: 'update', resource: resName, recordId: String(targetId) });
       if (typeof options.mutationOptions?.onSuccess === 'function') {
-        (options.mutationOptions.onSuccess as Function)(data, params, context);
+        (options.mutationOptions.onSuccess as Function)(data, params, extractedCtx);
       }
     },
     onError: (error, params, context: unknown) => {
+      const extractedCtx = (context as any)?._svadmin_ctx ? (context as any).userContext : context;
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
       const ctx = context as { previousDetail?: unknown; previousList?: [unknown, unknown][] } | undefined;
@@ -202,7 +211,7 @@ export function useUpdate<TData extends BaseRecord = BaseRecord, TError = HttpEr
       if (error instanceof UndoError) return;
       fireErrorNotification(params.errorNotification, 'Update failed', error);
       if (typeof options.mutationOptions?.onError === 'function') {
-        (options.mutationOptions.onError as Function)(error, params, context);
+        (options.mutationOptions.onError as Function)(error, params, extractedCtx);
       }
     },
   }));
@@ -279,22 +288,28 @@ export function useDelete<TData extends BaseRecord = BaseRecord, TError = HttpEr
       }
     },
     onMutate: async (params) => {
-      if (mutationMode === 'pessimistic') return undefined;
+      const userOnMutate = (options.mutationOptions as any)?.onMutate;
+      const userContext = typeof userOnMutate === 'function' ? await userOnMutate(params) : undefined;
+      
+      if (mutationMode === 'pessimistic') return { _svadmin_ctx: true, userContext };
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
       
       await queryClient.cancelQueries({ queryKey: [resName] });
       const previousList = queryClient.getQueriesData({ queryKey: [resName, 'list'] });
       
+      const pk = getResource(resName).primaryKey ?? 'id';
+      
       queryClient.setQueriesData({ queryKey: [resName, 'list'] }, (old: unknown) => {
         if (!old || typeof old !== 'object' || !('data' in old)) return old;
         const o = old as { data: Record<string, unknown>[] };
-        return { ...o, data: o.data.filter((item) => String(item.id) !== String(targetId)) };
+        return { ...o, data: o.data.filter((item) => String(item[pk]) !== String(targetId)) };
       });
 
-      return { previousList };
+      return { _svadmin_ctx: true, userContext, previousList };
     },
     onSuccess: (data, params, context) => {
+      const extractedCtx = (context as any)?._svadmin_ctx ? (context as any).userContext : context;
       const resName = params.resource ?? defaultResource;
       const targetId = params.id ?? defaultId;
       if (params.invalidates !== false) {
@@ -303,10 +318,11 @@ export function useDelete<TData extends BaseRecord = BaseRecord, TError = HttpEr
       fireSuccessNotification(params.successNotification, 'Deleted successfully', data.data, params.variables, resName);
       audit({ action: 'delete', resource: resName, recordId: String(targetId) });
       if (typeof options.mutationOptions?.onSuccess === 'function') {
-        (options.mutationOptions.onSuccess as Function)(data, params, context);
+        (options.mutationOptions.onSuccess as Function)(data, params, extractedCtx);
       }
     },
     onError: (error, params, context: unknown) => {
+      const extractedCtx = (context as any)?._svadmin_ctx ? (context as any).userContext : context;
       const ctx = context as { previousList?: [unknown, unknown][] } | undefined;
       if (ctx?.previousList) {
         ctx.previousList.forEach(([qk, data]) => queryClient.setQueryData(qk as string[], data));
@@ -314,7 +330,7 @@ export function useDelete<TData extends BaseRecord = BaseRecord, TError = HttpEr
       if (error instanceof UndoError) return;
       fireErrorNotification(params.errorNotification, 'Delete failed', error);
       if (typeof options.mutationOptions?.onError === 'function') {
-        (options.mutationOptions.onError as Function)(error, params, context);
+        (options.mutationOptions.onError as Function)(error, params, extractedCtx);
       }
     },
   }));

package/src/query-hooks.svelte.ts

@@ -25,13 +25,16 @@ function extendQuery<Q extends object, E extends Record<string, unknown>>(
   extensions: () => E,
 ): Q & E {
   return new Proxy(query, {
-    get(target, prop, receiver) {
-      const ext = extensions();
-      if (prop in ext) return ext[prop as keyof E];
-      return Reflect.get(target, prop, receiver);
+    get(target, prop) {
+      if (typeof prop === 'string') {
+        const ext = extensions();
+        if (prop in ext) return ext[prop as keyof E];
+      }
+      return target[prop as keyof Q];
     },
     has(target, prop) {
-      return prop in extensions() || Reflect.has(target, prop);
+      if (typeof prop === 'string' && prop in extensions()) return true;
+      return prop in target;
     },
   }) as Q & E;
 }
@@ -82,17 +85,17 @@ export function useList<TData extends BaseRecord = BaseRecord, TError = HttpErro
 
   const overtime = createOvertimeTracker(() => query.isLoading, options.overtimeOptions ?? adminOptions.overtime);
 
-  createLiveSubscription({
+  createLiveSubscription((): LiveSubscriptionParams => ({
     resource,
     liveProvider: getLiveProvider(),
     liveMode: options.liveMode ?? adminOptions.liveMode,
-    onLiveEvent: (e) => {
+    onLiveEvent: (e: LiveEvent) => {
       options.onLiveEvent?.(e);
       adminOptions.onLiveEvent?.(e);
     },
     liveParams: options.liveParams,
     enabled: queryOptions?.enabled ?? true,
-  });
+  }));
 
   $effect(() => {
     if (query.isSuccess && options.successNotification) {
@@ -148,18 +151,6 @@ export function useOne<TData extends BaseRecord = BaseRecord, TError = HttpError
 
   const overtime = createOvertimeTracker(() => query.isLoading, options.overtimeOptions ?? adminOptions.overtime);
 
-  createLiveSubscription({
-    resource,
-    liveProvider: getLiveProvider(),
-    liveMode: options.liveMode ?? adminOptions.liveMode,
-    onLiveEvent: (e) => {
-      options.onLiveEvent?.(e);
-      adminOptions.onLiveEvent?.(e);
-    },
-    liveParams: options.liveParams,
-    enabled: (queryOptions?.enabled ?? true) && id != null,
-  });
-
   $effect(() => {
     if (query.isSuccess && options.successNotification) {
       fireSuccessNotification(options.successNotification, '', query.data, undefined, resource);
@@ -225,18 +216,6 @@ export function useMany<TData extends BaseRecord = BaseRecord, TError = HttpErro
 
   const overtime = createOvertimeTracker(() => query.isLoading, options.overtimeOptions ?? adminOptions.overtime);
 
-  createLiveSubscription({
-    resource,
-    liveProvider: getLiveProvider(),
-    liveMode: options.liveMode ?? adminOptions.liveMode,
-    onLiveEvent: (e) => {
-      options.onLiveEvent?.(e);
-      adminOptions.onLiveEvent?.(e);
-    },
-    liveParams: options.liveParams,
-    enabled: (queryOptions?.enabled ?? true) && ids.length > 0,
-  });
-
   $effect(() => {
     if (query.isSuccess && options.successNotification) fireSuccessNotification(options.successNotification, '', query.data, undefined, resource);
     else if (query.isError) fireErrorNotification(options.errorNotification, 'Fetch failed', query.error);

package/src/router-provider.ts

@@ -18,6 +18,8 @@ export interface RouterProvider {
     params: Record<string, string>;
     pathname: string;
   };
+  /** Formats an internal path into an href string for <a> tags */
+  formatLink?: (path: string) => string;
 }
 
 // ─── Hash Router (default) ──────────────────────────────────
@@ -25,6 +27,7 @@ export interface RouterProvider {
 export function createHashRouterProvider(): RouterProvider {
   return {
     go({ to, query, type = 'push' }) {
+      if (typeof window === 'undefined') return;
       let url = to;
       if (query) {
         const params = new URLSearchParams(query).toString();
@@ -34,14 +37,19 @@ export function createHashRouterProvider(): RouterProvider {
         const urlObj = new URL(window.location.href);
         urlObj.hash = url;
         window.history.replaceState(null, '', urlObj.href);
+        window.dispatchEvent(new HashChangeEvent('hashchange'));
       } else {
         window.location.hash = url;
       }
     },
     back() {
+      if (typeof window === 'undefined') return;
       history.back();
     },
     parse() {
+      if (typeof window === 'undefined') {
+        return { resource: undefined, action: undefined, id: undefined, params: {}, pathname: '/' };
+      }
       const hash = window.location.hash.slice(1) || '/';
       const [pathname, queryString] = hash.split('?');
       const params: Record<string, string> = {};
@@ -59,6 +67,9 @@ export function createHashRouterProvider(): RouterProvider {
         pathname,
       };
     },
+    formatLink(path) {
+      return '#' + path.replace(/^#/, '');
+    },
   };
 }
 
@@ -67,6 +78,7 @@ export function createHashRouterProvider(): RouterProvider {
 export function createHistoryRouterProvider(basePath = ''): RouterProvider {
   return {
     go({ to, query, type = 'push' }) {
+      if (typeof window === 'undefined') return;
       let url = `${basePath}${to}`;
       if (query) {
         const params = new URLSearchParams(query).toString();
@@ -81,9 +93,13 @@ export function createHistoryRouterProvider(basePath = ''): RouterProvider {
       window.dispatchEvent(new PopStateEvent('popstate'));
     },
     back() {
+      if (typeof window === 'undefined') return;
       history.back();
     },
     parse() {
+      if (typeof window === 'undefined') {
+        return { resource: undefined, action: undefined, id: undefined, params: {}, pathname: '/' };
+      }
       const pathname = window.location.pathname.replace(basePath, '') || '/';
       const params: Record<string, string> = {};
       for (const [k, v] of new URLSearchParams(window.location.search).entries()) {
@@ -98,5 +114,8 @@ export function createHistoryRouterProvider(basePath = ''): RouterProvider {
         pathname,
       };
     },
+    formatLink(path) {
+      return basePath + path;
+    },
   };
 }

package/src/router.ts

@@ -50,9 +50,6 @@ export function matchRoute(
   return null;
 }
 
-/**
- * Navigate to a path. Uses RouterProvider if available, falls back to hash.
- */
 export function navigate(path: string, options?: { replaceState?: boolean }): void {
   if (_routerProvider) {
     _routerProvider.go({ to: path, type: options?.replaceState ? 'replace' : 'push' });
@@ -61,6 +58,16 @@ export function navigate(path: string, options?: { replaceState?: boolean }): vo
   }
 }
 
+/**
+ * Format a path into an href suitable for <a> tags.
+ */
+export function formatLink(path: string): string {
+  if (_routerProvider?.formatLink) {
+    return _routerProvider.formatLink(path);
+  }
+  return '#' + path.replace(/^#/, '');
+}
+
 export function currentPath(): string {
   if (_routerProvider) {
     const parsed = _routerProvider.parse();

package/src/table-state.svelte.ts

@@ -94,12 +94,13 @@ export class TableState<TData extends BaseRecord = BaseRecord, TError = HttpErro
     this.currentFilters = initFilters;
 
     // Create query
+    const _this = this;
     const { meta, syncWithLocation: _s, dataProviderName, pagination: _p, sorters: _sr, filters: _f, ...restOptions } = options;
     this._queryResult = useList<TData, TError>({
       resource,
-      pagination: this.queryPagination,
-      sorters: this.effectiveSorters,
-      filters: this.effectiveFilters,
+      get pagination() { return _this.queryPagination; },
+      get sorters() { return _this.effectiveSorters; },
+      get filters() { return _this.effectiveFilters; },
       meta,
       dataProviderName,
       ...restOptions,

package/src/theme.svelte.ts

@@ -335,8 +335,10 @@ function applyTheme(m: ThemeMode): void {
   }
 }
 
-// Apply on init
-applyTheme(getStoredTheme());
+// Apply on init (browser only)
+if (typeof window !== 'undefined') {
+  applyTheme(getStoredTheme());
+}
 
 // Listen for system preference changes
 if (typeof window !== 'undefined') {
@@ -390,9 +392,9 @@ function applyColorTheme(ct: ColorTheme): void {
   }
 }
 
-// Apply on init
-applyColorTheme(getStoredColorTheme());
-{
+// Apply on init (browser only)
+if (typeof window !== 'undefined') {
+  applyColorTheme(getStoredColorTheme());
   const initPreset = builtinPresets[getStoredColorTheme()];
   if (initPreset) applyColorPreset(initPreset);
 }

package/src/url-sync.ts

@@ -1,6 +1,5 @@
-// URL state sync — sync pagination/sort/filters with hash params
-
 import type { Filter } from './types';
+import { getRouterProvider } from './context.svelte';
 
 export interface URLState {
   page?: number;
@@ -13,29 +12,28 @@ export interface URLState {
 
 export function readURLState(): URLState {
   if (typeof window === 'undefined') return {};
-  const hash = window.location.hash;
-  const queryIdx = hash.indexOf('?');
-  if (queryIdx === -1) return {};
+  const rp = getRouterProvider();
+  if (!rp) return {};
 
-  const params = new URLSearchParams(hash.slice(queryIdx + 1));
+  const { params } = rp.parse();
   const state: URLState = {};
 
-  const page = params.get('page');
+  const page = params['page'];
   if (page) state.page = parseInt(page, 10);
 
-  const pageSize = params.get('pageSize');
+  const pageSize = params['pageSize'];
   if (pageSize) state.pageSize = parseInt(pageSize, 10);
 
-  const sortField = params.get('sort');
+  const sortField = params['sort'];
   if (sortField) state.sortField = sortField;
 
-  const sortOrder = params.get('order');
+  const sortOrder = params['order'];
   if (sortOrder === 'asc' || sortOrder === 'desc') state.sortOrder = sortOrder;
 
-  const search = params.get('q');
+  const search = params['q'];
   if (search) state.search = search;
 
-  const filtersRaw = params.get('filters');
+  const filtersRaw = params['filters'];
   if (filtersRaw) {
     try {
       state.filters = JSON.parse(filtersRaw);
@@ -47,24 +45,42 @@ export function readURLState(): URLState {
 
 export function writeURLState(state: URLState): void {
   if (typeof window === 'undefined') return;
-  const hash = window.location.hash;
-  const pathIdx = hash.indexOf('?');
-  const basePath = pathIdx === -1 ? hash : hash.slice(0, pathIdx);
-
-  const params = new URLSearchParams();
-  if (state.page && state.page > 1) params.set('page', String(state.page));
-  if (state.pageSize && state.pageSize !== 10) params.set('pageSize', String(state.pageSize));
-  if (state.sortField) params.set('sort', state.sortField);
-  if (state.sortOrder) params.set('order', state.sortOrder);
-  if (state.search) params.set('q', state.search);
+  const rp = getRouterProvider();
+  if (!rp) return;
+
+  const current = rp.parse();
+  const params: Record<string, string> = { ...current.params };
+
+  if (state.page && state.page > 1) params['page'] = String(state.page);
+  else delete params['page'];
+
+  if (state.pageSize && state.pageSize !== 10) params['pageSize'] = String(state.pageSize);
+  else delete params['pageSize'];
+
+  if (state.sortField) params['sort'] = state.sortField;
+  else delete params['sort'];
+
+  if (state.sortOrder) params['order'] = state.sortOrder;
+  else delete params['order'];
+
+  if (state.search) params['q'] = state.search;
+  else delete params['q'];
+
   if (state.filters && state.filters.length > 0) {
-    params.set('filters', JSON.stringify(state.filters));
+    params['filters'] = JSON.stringify(state.filters);
+  } else {
+    delete params['filters'];
   }
 
-  const qs = params.toString();
-  const newHash = qs ? `${basePath}?${qs}` : basePath;
-
-  if (window.location.hash !== newHash) {
-    history.replaceState(null, '', newHash);
+  // Prevent redundant navigation if nothing actually changed
+  const qsOld = new URLSearchParams(current.params).toString();
+  const qsNew = new URLSearchParams(params).toString();
+  
+  if (qsOld !== qsNew) {
+    rp.go({
+      to: current.pathname,
+      query: params,
+      type: 'replace'
+    });
   }
 }

package/src/useParsed.svelte.ts

@@ -10,6 +10,15 @@ interface ParsedRoute {
   params: Record<string, string>;
 }
 
+let globalPath = $state('/');
+if (typeof window !== 'undefined') {
+  // Initialize
+  globalPath = currentPath();
+  // Listen to navigation events
+  window.addEventListener('hashchange', () => { globalPath = currentPath(); });
+  window.addEventListener('popstate', () => { globalPath = currentPath(); });
+}
+
 /**
  * Parse the current hash URL into a structured route object.
  * Returns reactive properties that update when the URL changes.
@@ -21,11 +30,10 @@ interface ParsedRoute {
  *   // parsed.id === '123'
  */
 export function useParsed(): ParsedRoute {
-  const path = $derived(currentPath());
   const resources = $derived((() => { try { return getResources(); } catch { return []; } })());
 
   const parsed = $derived.by(() => {
-    const p = path;
+    const p = globalPath;
     const result: ParsedRoute = { params: {} };
 
     // Parse query params from hash

package/src/utility-hooks.svelte.ts

@@ -42,7 +42,13 @@ export function useModalForm<
   let visible = $state(options.defaultVisible ?? false);
 
   function show(id?: string | number) {
-    if (id !== undefined) formState.setId(id);
+    if (id !== undefined) {
+      formState.setAction('edit');
+      formState.setId(id);
+    } else {
+      formState.setAction('create');
+      formState.setId(undefined);
+    }
     visible = true;
   }