@svadmin/core 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Core SDK — hooks, types, context, i18n, permissions, router",
   "type": "module",
   "sideEffects": false,

package/src/chatProvider.svelte.ts

@@ -1,4 +1,10 @@
-// Chat provider — headless interface for AI chat integration
+// Chat & Agent provider — headless interface for AI integration
+//
+// Two abstraction levels:
+//   1. ChatProvider  — simple message-in / text-out  (backward compatible)
+//   2. AgentProvider — tool calling, approval gates, generative UI events
+//
+// Inspired by Vercel AI SDK 6 agent abstractions.
 
 /** Describes an actionable button rendered in assistant messages (tool-call UX). */
 export interface ChatAction {
@@ -40,6 +46,117 @@ export interface ChatProvider {
   ): Promise<string> | AsyncGenerator<string, void, unknown>;
 }
 
+// ─── Agent Provider (extends ChatProvider concept) ─────────────
+//
+// An AgentProvider emits typed events instead of raw strings, enabling:
+//   • Tool calling — Agent invokes admin operations (CRUD, custom)
+//   • Approval gates — Dangerous tools require user confirmation before execution
+//   • Generative UI — Agent returns component name + props for dynamic rendering
+
+/** JSON-Schema-compatible parameter definition for an admin tool. */
+export interface AdminToolParameter {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+  enum?: string[];
+  required?: boolean;
+}
+
+/**
+ * A tool that the Agent can invoke within the admin panel.
+ *
+ * @example
+ * ```ts
+ * const deletePostTool: AdminTool = {
+ *   name: 'deletePosts',
+ *   description: 'Delete posts matching a filter',
+ *   parameters: {
+ *     status: { type: 'string', description: 'Filter by status', enum: ['draft', 'archived'] },
+ *   },
+ *   needsApproval: true,
+ *   execute: async (params) => {
+ *     const result = await dataProvider.deleteMany({ resource: 'posts', ids: params.ids });
+ *     return { success: true, data: result };
+ *   },
+ * };
+ * ```
+ */
+export interface AdminTool {
+  /** Unique tool name (e.g. 'getList', 'deleteRecords', 'generateReport') */
+  name: string;
+  /** Human-readable description for LLM tool-use prompting */
+  description: string;
+  /** JSON-Schema-style parameter definitions */
+  parameters: Record<string, AdminToolParameter>;
+  /**
+   * When `true`, execution is paused until the user explicitly approves.
+   * The agent emits an `approval_request` event and waits for `approveToolCall()`.
+   */
+  needsApproval?: boolean;
+  /** Execute the tool with the given arguments. */
+  execute(args: Record<string, unknown>): Promise<ToolResult>;
+}
+
+/** Result returned by a tool execution. */
+export interface ToolResult {
+  success: boolean;
+  data?: unknown;
+  error?: string;
+}
+
+/** Discriminated union of events emitted by an AgentProvider. */
+export type AgentEvent =
+  /** Streaming text chunk */
+  | { type: 'text'; content: string }
+  /** Agent wants to call a tool (informational — execution is handled internally) */
+  | { type: 'tool_call'; tool: string; args: Record<string, unknown> }
+  /** Agent wants to call a tool that requires user approval before execution */
+  | { type: 'approval_request'; id: string; tool: string; args: Record<string, unknown>; description: string }
+  /** Tool execution completed */
+  | { type: 'tool_result'; tool: string; result: ToolResult }
+  /** Agent wants to render a named component (Generative UI) */
+  | { type: 'component'; name: string; props: Record<string, unknown> }
+  /** Stream finished */
+  | { type: 'done' };
+
+/** Options passed to AgentProvider.chat() */
+export interface AgentOptions {
+  signal?: AbortSignal;
+  /** Admin context is injected automatically by the framework */
+  context?: ChatContext;
+}
+
+/**
+ * AgentProvider — advanced AI integration with tool calling and approval gates.
+ *
+ * Implement this interface to connect to agentic AI backends that support
+ * function calling (OpenAI, Anthropic, Google Gemini, etc.).
+ *
+ * For simpler chat-only use cases, use `ChatProvider` instead.
+ *
+ * @example
+ * ```ts
+ * const agentProvider: AgentProvider = {
+ *   tools: [deletePostTool, getStatsTool],
+ *   async *chat(messages, options) {
+ *     // Stream events from your AI backend
+ *     yield { type: 'text', content: 'Looking up draft posts...' };
+ *     yield { type: 'tool_call', tool: 'getList', args: { resource: 'posts', filter: { status: 'draft' } } };
+ *     yield { type: 'approval_request', id: 'req-1', tool: 'deletePosts', args: { ids: ['1', '2'] }, description: 'Delete 2 draft posts' };
+ *     yield { type: 'done' };
+ *   },
+ * };
+ * ```
+ */
+export interface AgentProvider {
+  /** Available tools the agent can invoke */
+  tools?: AdminTool[];
+  /** Send messages and receive a stream of typed agent events */
+  chat(
+    messages: ChatMessage[],
+    options?: AgentOptions,
+  ): AsyncGenerator<AgentEvent, void, unknown>;
+}
+
 // ─── Chat Provider singleton ───────────────────────────────────
 
 let chatProvider: ChatProvider | null = $state(null);
@@ -52,6 +169,53 @@ export function getChatProvider(): ChatProvider | null {
   return chatProvider;
 }
 
+// ─── Agent Provider singleton ──────────────────────────────────
+
+let agentProvider: AgentProvider | null = $state(null);
+
+export function setAgentProvider(provider: AgentProvider): void {
+  agentProvider = provider;
+}
+
+export function getAgentProvider(): AgentProvider | null {
+  return agentProvider;
+}
+
+// ─── Tool Approval ─────────────────────────────────────────────
+
+type ApprovalCallback = (approved: boolean) => void;
+const pendingApprovals = new Map<string, ApprovalCallback>();
+
+/**
+ * Register a pending approval request. Called internally by the framework
+ * when an `approval_request` event is received from the agent.
+ */
+export function registerApproval(id: string, callback: ApprovalCallback): void {
+  pendingApprovals.set(id, callback);
+}
+
+/**
+ * Approve or reject a pending tool call.
+ *
+ * @example
+ * ```svelte
+ * <button onclick={() => resolveApproval('req-1', true)}>Approve</button>
+ * <button onclick={() => resolveApproval('req-1', false)}>Reject</button>
+ * ```
+ */
+export function resolveApproval(id: string, approved: boolean): boolean {
+  const cb = pendingApprovals.get(id);
+  if (!cb) return false;
+  cb(approved);
+  pendingApprovals.delete(id);
+  return true;
+}
+
+/** Check if there are any pending approval requests. */
+export function hasPendingApprovals(): boolean {
+  return pendingApprovals.size > 0;
+}
+
 // ─── Chat Context singleton ────────────────────────────────────
 
 let chatContext = $state<ChatContext>({});

package/src/chatProvider.test.ts

@@ -166,3 +166,223 @@ describe('localStorage persistence simulation', () => {
     expect(restored[1].actions![0].label).toBe('Create Post');
   });
 });
+
+// ─── AgentProvider Types ───────────────────────────────────────
+
+/** Mirror of AdminToolParameter from chatProvider.svelte.ts */
+interface AdminToolParameter {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description?: string;
+  enum?: string[];
+  required?: boolean;
+}
+
+/** Mirror of AdminTool from chatProvider.svelte.ts */
+interface AdminTool {
+  name: string;
+  description: string;
+  parameters: Record<string, AdminToolParameter>;
+  needsApproval?: boolean;
+  execute(args: Record<string, unknown>): Promise<{ success: boolean; data?: unknown; error?: string }>;
+}
+
+/** Mirror of AgentEvent from chatProvider.svelte.ts */
+type AgentEvent =
+  | { type: 'text'; content: string }
+  | { type: 'tool_call'; tool: string; args: Record<string, unknown> }
+  | { type: 'approval_request'; id: string; tool: string; args: Record<string, unknown>; description: string }
+  | { type: 'tool_result'; tool: string; result: { success: boolean; data?: unknown; error?: string } }
+  | { type: 'component'; name: string; props: Record<string, unknown> }
+  | { type: 'done' };
+
+describe('AdminTool shape', () => {
+  test('tool with needsApproval serializes correctly', () => {
+    const tool: AdminTool = {
+      name: 'deletePosts',
+      description: 'Delete posts matching a filter',
+      parameters: {
+        status: { type: 'string', description: 'Filter by status', enum: ['draft', 'archived'] },
+      },
+      needsApproval: true,
+      execute: async (args) => ({ success: true, data: { deleted: args.ids } }),
+    };
+
+    expect(tool.name).toBe('deletePosts');
+    expect(tool.needsApproval).toBe(true);
+    expect(tool.parameters.status.enum).toEqual(['draft', 'archived']);
+  });
+
+  test('tool without approval defaults to undefined', () => {
+    const tool: AdminTool = {
+      name: 'getStats',
+      description: 'Fetch dashboard statistics',
+      parameters: {},
+      execute: async () => ({ success: true, data: { users: 100 } }),
+    };
+
+    expect(tool.needsApproval).toBeUndefined();
+  });
+
+  test('tool execute returns ToolResult', async () => {
+    const tool: AdminTool = {
+      name: 'createPost',
+      description: 'Create a new post',
+      parameters: {
+        title: { type: 'string', required: true },
+      },
+      execute: async (args) => ({
+        success: true,
+        data: { id: '1', title: args.title },
+      }),
+    };
+
+    const result = await tool.execute({ title: 'Hello World' });
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({ id: '1', title: 'Hello World' });
+  });
+
+  test('tool execute can return error', async () => {
+    const tool: AdminTool = {
+      name: 'failingTool',
+      description: 'A tool that fails',
+      parameters: {},
+      execute: async () => ({
+        success: false,
+        error: 'Permission denied',
+      }),
+    };
+
+    const result = await tool.execute({});
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Permission denied');
+  });
+});
+
+describe('AgentEvent stream', () => {
+  test('events can be collected from async generator', async () => {
+    async function* mockAgent(): AsyncGenerator<AgentEvent, void, unknown> {
+      yield { type: 'text', content: 'Searching...' };
+      yield { type: 'tool_call', tool: 'getList', args: { resource: 'posts' } };
+      yield { type: 'tool_result', tool: 'getList', result: { success: true, data: [{ id: 1 }] } };
+      yield { type: 'text', content: 'Found 1 post.' };
+      yield { type: 'done' };
+    }
+
+    const events: AgentEvent[] = [];
+    for await (const event of mockAgent()) {
+      events.push(event);
+    }
+
+    expect(events).toHaveLength(5);
+    expect(events[0].type).toBe('text');
+    expect(events[1].type).toBe('tool_call');
+    expect(events[2].type).toBe('tool_result');
+    expect(events[4].type).toBe('done');
+  });
+
+  test('approval_request event serializes correctly', () => {
+    const event: AgentEvent = {
+      type: 'approval_request',
+      id: 'req-42',
+      tool: 'deletePosts',
+      args: { ids: ['1', '2', '3'] },
+      description: 'Delete 3 draft posts',
+    };
+
+    const serialized = JSON.stringify(event);
+    const parsed = JSON.parse(serialized) as AgentEvent;
+
+    expect(parsed.type).toBe('approval_request');
+    if (parsed.type === 'approval_request') {
+      expect(parsed.id).toBe('req-42');
+      expect(parsed.tool).toBe('deletePosts');
+      expect(parsed.description).toBe('Delete 3 draft posts');
+    }
+  });
+
+  test('component event carries name and props', () => {
+    const event: AgentEvent = {
+      type: 'component',
+      name: 'SalesChart',
+      props: { period: 'monthly', data: [100, 200, 150] },
+    };
+
+    expect(event.type).toBe('component');
+    if (event.type === 'component') {
+      expect(event.name).toBe('SalesChart');
+      expect(event.props.period).toBe('monthly');
+    }
+  });
+});
+
+describe('Approval flow', () => {
+  test('registerApproval and resolveApproval work together', () => {
+    // Simulate the approval flow without importing rune-based module
+    const pending = new Map<string, (approved: boolean) => void>();
+
+    function register(id: string, cb: (approved: boolean) => void) {
+      pending.set(id, cb);
+    }
+
+    function resolve(id: string, approved: boolean): boolean {
+      const cb = pending.get(id);
+      if (!cb) return false;
+      cb(approved);
+      pending.delete(id);
+      return true;
+    }
+
+    let approvalResult = false;
+
+    register('req-1', (approved) => {
+      approvalResult = approved;
+    });
+
+    expect(pending.size).toBe(1);
+
+    // Resolve with approval
+    const resolved = resolve('req-1', true);
+    expect(resolved).toBe(true);
+    expect(approvalResult).toEqual(true);
+    expect(pending.size).toBe(0);
+  });
+
+  test('resolveApproval returns false for unknown id', () => {
+    const pending = new Map<string, (approved: boolean) => void>();
+
+    function resolve(id: string, approved: boolean): boolean {
+      const cb = pending.get(id);
+      if (!cb) return false;
+      cb(approved);
+      pending.delete(id);
+      return true;
+    }
+
+    expect(resolve('nonexistent', true)).toBe(false);
+  });
+
+  test('rejection flow works', () => {
+    const pending = new Map<string, (approved: boolean) => void>();
+
+    function register(id: string, cb: (approved: boolean) => void) {
+      pending.set(id, cb);
+    }
+
+    function resolve(id: string, approved: boolean): boolean {
+      const cb = pending.get(id);
+      if (!cb) return false;
+      cb(approved);
+      pending.delete(id);
+      return true;
+    }
+
+    let wasApproved = true;
+
+    register('req-2', (approved) => {
+      wasApproved = approved;
+    });
+
+    resolve('req-2', false);
+    expect(wasApproved).toEqual(false);
+  });
+});

package/src/context.svelte.ts

@@ -8,7 +8,7 @@ import type { RouterProvider } from './router-provider';
 
 /**
  * Accepts either:
- *   - A single DataProvider (backwards compatible)
+ *   - A single DataProvider
  *   - A record of named providers: { default: rest, cms: graphql }
  */
 export type DataProviderInput = DataProvider | Record<string, DataProvider>;

package/src/form-hooks.svelte.ts

@@ -125,8 +125,8 @@ export interface UseFormReturn<
   readonly autoSave: { status: 'idle' | 'saving' | 'saved' | 'error'; data: unknown; error: unknown };
 
   // ─── Raw query/mutation (escape hatch) ────────────────────────
-  readonly query: ReturnType<typeof createQuery> | null;
-  readonly mutation: ReturnType<typeof createMutation>;
+  readonly query: unknown;
+  readonly mutation: unknown;
 }
 
 // ─── Implementation ──────────────────────────────────────────────────
@@ -423,6 +423,6 @@ export function useForm<
 
     // Raw escape hatches
     query,
-    mutation: (action === 'edit' ? updateMut : createMut) as unknown as ReturnType<typeof createMutation>,
+    mutation: action === 'edit' ? updateMut : createMut,
   };
 }

package/src/hook-utils.svelte.ts

@@ -97,6 +97,7 @@ export function fireSuccessNotification(
   resource?: string,
 ): void {
   if (config === false) return;
+  if (!config && !defaultMessage) return;
   if (typeof config === 'function') {
     const result = config(data, values, resource);
     toast.success(result.message);

package/src/i18n.svelte.ts

@@ -163,6 +163,72 @@ const locales: Record<string, Locale> = {
     'settings.dataProvider': '数据源',
     'settings.currentEnvironment': '当前环境',
     'settings.settingsDescription': '管理您的账户和界面偏好。',
+    'settings.rolesAndPermissions': '角色与权限',
+    'settings.roles': '角色',
+    'settings.rolesDescription': '管理系统访问控制与资源权限。',
+    'settings.rbacNotSupported': '当前数据源不支持 RBAC 管理',
+    'settings.selectRoleHint': '请在左侧选择一个角色以查看权限',
+    'settings.resource': '资源',
+    'resource.posts': '文章',
+    'resource.users': '用户',
+    'resource.categories': '分类',
+    // Audit
+    'settings.auditLogs': '操作日志',
+    'settings.auditDescription': '追踪和审查所有系统操作，用于合规与调试。',
+    'settings.auditNotSupported': '当前数据源不支持操作日志',
+    'settings.searchLogs': '搜索用户、操作或资源...',
+    'settings.auditTime': '时间',
+    'settings.auditUser': '操作人',
+    'settings.auditAction': '操作',
+    'settings.auditResource': '资源',
+    'settings.auditIp': 'IP 地址',
+    'settings.auditTotal': '条记录',
+    'settings.auditSnapshot': '变更快照',
+    // Editor
+    'editor.bold': '加粗',
+    'editor.italic': '斜体',
+    'editor.underline': '下划线',
+    'editor.strikethrough': '删除线',
+    'editor.code': '行内代码',
+    'editor.codeBlock': '代码块',
+    'editor.h1': '一级标题',
+    'editor.h2': '二级标题',
+    'editor.h3': '三级标题',
+    'editor.h4': '四级标题',
+    'editor.bulletList': '无序列表',
+    'editor.orderedList': '有序列表',
+    'editor.taskList': '任务列表',
+    'editor.blockquote': '引用',
+    'editor.alignLeft': '左对齐',
+    'editor.alignCenter': '居中对齐',
+    'editor.alignRight': '右对齐',
+    'editor.alignJustify': '两端对齐',
+    'editor.link': '插入链接',
+    'editor.image': '插入图片',
+    'editor.table': '插入表格',
+    'editor.color': '文本颜色',
+    'editor.highlight': '高亮',
+    'editor.clearFormat': '清除格式',
+    'editor.undo': '撤销',
+    'editor.redo': '重做',
+    'editor.startWriting': '开始写作...',
+    'editor.typeSlash': '输入 / 唤出菜单',
+    // Editor - Popovers
+    'editor.link.url': '链接地址',
+    'editor.link.openInNewTab': '在新标签页打开',
+    'editor.link.apply': '应用',
+    'editor.link.remove': '移除链接',
+    'editor.image.url': '图片链接 (URL)',
+    'editor.image.upload': '点击或拖拽图片到此处上传',
+    'editor.image.uploading': '上传中...',
+    'editor.table.insertRowAbove': '在上方插入行',
+    'editor.table.insertRowBelow': '在下方插入行',
+    'editor.table.deleteRow': '删除行',
+    'editor.table.insertColumnLeft': '在左侧插入列',
+    'editor.table.insertColumnRight': '在右侧插入列',
+    'editor.table.deleteColumn': '删除列',
+    'editor.table.deleteTable': '删除表格',
+    'editor.table.mergeCells': '合并/拆分单元格',
     // Profile
     'profile.title': '个人资料',
     'profile.name': '姓名',
@@ -332,6 +398,72 @@ const locales: Record<string, Locale> = {
     'settings.dataProvider': 'Data Provider',
     'settings.currentEnvironment': 'Current Environment',
     'settings.settingsDescription': 'Manage your account and interface preferences.',
+    'settings.rolesAndPermissions': 'Roles & Permissions',
+    'settings.roles': 'Roles',
+    'settings.rolesDescription': 'Manage system access control and resource permissions.',
+    'settings.rbacNotSupported': 'RBAC management is not supported by the current data provider',
+    'settings.selectRoleHint': 'Select a role on the left to view permissions',
+    'settings.resource': 'Resource',
+    'resource.posts': 'Posts',
+    'resource.users': 'Users',
+    'resource.categories': 'Categories',
+    // Audit
+    'settings.auditLogs': 'Audit Logs',
+    'settings.auditDescription': 'Track and review all system operations for compliance and debugging.',
+    'settings.auditNotSupported': 'Audit logs are not supported by the current data provider',
+    'settings.searchLogs': 'Search by user, action, or resource...',
+    'settings.auditTime': 'Time',
+    'settings.auditUser': 'User',
+    'settings.auditAction': 'Action',
+    'settings.auditResource': 'Resource',
+    'settings.auditIp': 'IP Address',
+    'settings.auditTotal': 'total records',
+    'settings.auditSnapshot': 'Change Snapshot',
+    // Editor
+    'editor.bold': 'Bold',
+    'editor.italic': 'Italic',
+    'editor.underline': 'Underline',
+    'editor.strikethrough': 'Strikethrough',
+    'editor.code': 'Inline Code',
+    'editor.codeBlock': 'Code Block',
+    'editor.h1': 'Heading 1',
+    'editor.h2': 'Heading 2',
+    'editor.h3': 'Heading 3',
+    'editor.h4': 'Heading 4',
+    'editor.bulletList': 'Bullet List',
+    'editor.orderedList': 'Ordered List',
+    'editor.taskList': 'Task List',
+    'editor.blockquote': 'Blockquote',
+    'editor.alignLeft': 'Align Left',
+    'editor.alignCenter': 'Align Center',
+    'editor.alignRight': 'Align Right',
+    'editor.alignJustify': 'Justify',
+    'editor.link': 'Insert Link',
+    'editor.image': 'Insert Image',
+    'editor.table': 'Insert Table',
+    'editor.color': 'Text Color',
+    'editor.highlight': 'Highlight',
+    'editor.clearFormat': 'Clear Formatting',
+    'editor.undo': 'Undo',
+    'editor.redo': 'Redo',
+    'editor.startWriting': 'Start writing...',
+    'editor.typeSlash': 'Type / for commands',
+    // Editor - Popovers
+    'editor.link.url': 'Link URL',
+    'editor.link.openInNewTab': 'Open in new tab',
+    'editor.link.apply': 'Apply',
+    'editor.link.remove': 'Remove Link',
+    'editor.image.url': 'Image URL',
+    'editor.image.upload': 'Click or drag image here to upload',
+    'editor.image.uploading': 'Uploading...',
+    'editor.table.insertRowAbove': 'Insert row above',
+    'editor.table.insertRowBelow': 'Insert row below',
+    'editor.table.deleteRow': 'Delete row',
+    'editor.table.insertColumnLeft': 'Insert column left',
+    'editor.table.insertColumnRight': 'Insert column right',
+    'editor.table.deleteColumn': 'Delete column',
+    'editor.table.deleteTable': 'Delete table',
+    'editor.table.mergeCells': 'Toggle merge cells',
     // Profile
     'profile.title': 'Profile',
     'profile.name': 'Name',

package/src/index.ts

@@ -27,15 +27,15 @@ export {
 } from './hooks.svelte';
 export { matchRoute, navigate, currentPath, setActiveRouterProvider } from './router';
 export { readURLState, writeURLState } from './url-sync';
-export { setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccess, canAccessAsync } from './permissions';
+export { setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccessAsync } from './permissions';
 export { useLive, useSubscription, usePublish } from './live.svelte';
 export { toast } from './toast.svelte';
 export { notify, closeNotification, setNotificationProvider, getNotificationProvider } from './notification.svelte';
 export { t, setLocale, getLocale, getAvailableLocales, addTranslations, useTranslation } from './i18n.svelte';
 export { audit, setAuditHandler, setAuditLogProvider, getAuditLogProvider } from './audit';
 export type { AuditLogProvider } from './audit';
-export { setChatProvider, getChatProvider, setChatContext, getChatContext } from './chatProvider.svelte';
-export type { ChatProvider, ChatMessage, ChatContext, ChatAction } from './chatProvider.svelte';
+export { setChatProvider, getChatProvider, setChatContext, getChatContext, setAgentProvider, getAgentProvider, registerApproval, resolveApproval, hasPendingApprovals } from './chatProvider.svelte';
+export type { ChatProvider, ChatMessage, ChatContext, ChatAction, AgentProvider, AgentEvent, AgentOptions, AdminTool, AdminToolParameter, ToolResult } from './chatProvider.svelte';
 export { getTheme, setTheme, toggleTheme, getResolvedTheme, getColorTheme, setColorTheme, colorThemes, configureTheme, getThemeConfig, clearCssOverrides, builtinPresets, registerColorPreset, getColorPresets } from './theme.svelte';
 export type { ThemeMode, ColorTheme, ThemeStrategy, ThemeConfig, ColorPreset } from './theme.svelte';
 export { setUnsavedChanges, getUnsavedChanges, initUnsavedChangesNotifier } from './unsaved-changes.svelte';
@@ -61,7 +61,7 @@ export type {
   ResourceDefinition, FieldDefinition, MenuItem,
   AuthActionResult, CheckResult,
   ResourceTypeMap, KnownResources, InferData,
-  BaseRecord,
+  BaseRecord, Role, AuditLog
 } from './types';
 export type { InvalidateScope } from './options.svelte';
 export type { LiveProvider, LiveEvent, LiveMode } from './live.svelte';

package/src/permissions.test.ts

@@ -1,6 +1,6 @@
 // Unit tests for permissions module
 import { describe, test, expect, beforeEach } from 'bun:test';
-import { setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccess, canAccessAsync } from './permissions';
+import { setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccessAsync } from './permissions';
 import type { Action, AccessControlProvider } from './permissions';
 
 describe('permissions', () => {
@@ -11,12 +11,6 @@ describe('permissions', () => {
     });
   });
 
-  test('canAccess returns { can: true } when provider is async (warns)', () => {
-    // canAccess is sync but provider.can() is async — should default to { can: true }
-    const result = canAccess('posts', 'list' as Action);
-    expect(result.can).toBe(true);
-  });
-
   test('canAccessAsync respects deny rule', async () => {
     setAccessControlProvider({
       can: async ({ action }) => {

package/src/permissions.ts

@@ -73,17 +73,7 @@ export function getAccessControlOptions() {
 }
 
 /**
- * Synchronous access check. Returns `{ can: true }` if no provider is set.
- * When a provider is registered, this warns since provider.can() is always async.
- */
-export function canAccess(resource: string, action: Action, params?: Record<string, unknown>): CanResult {
-  if (!provider) return { can: true };
-  console.warn('[permissions] canAccess called synchronously but provider.can() is async. Defaulting to { can: true }. Use canAccessAsync() instead.');
-  return { can: true };
-}
-
-/**
- * Async access check. Preferred over `canAccess()`.
+ * Async access check. Returns `{ can: true }` if no provider is registered.
  */
 export async function canAccessAsync(resource: string, action: Action, params?: Record<string, unknown>): Promise<CanResult> {
   if (!provider) return { can: true };

package/src/query-hooks.svelte.ts

@@ -75,7 +75,7 @@ export function useList<TData extends BaseRecord = BaseRecord, TError = HttpErro
   });
 
   $effect(() => {
-    if (query.isSuccess) {
+    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.ts

@@ -53,9 +53,9 @@ export function matchRoute(
 /**
  * Navigate to a path. Uses RouterProvider if available, falls back to hash.
  */
-export function navigate(path: string): void {
+export function navigate(path: string, options?: { replaceState?: boolean }): void {
   if (_routerProvider) {
-    _routerProvider.go({ to: path });
+    _routerProvider.go({ to: path, type: options?.replaceState ? 'replace' : 'push' });
   } else {
     window.location.hash = '#' + path.replace(/^#/, '');
   }

package/src/routing-hooks.svelte.ts

@@ -42,7 +42,6 @@ export function useGo() {
     if (routerProvider?.go) {
       routerProvider.go({ to: targetUrl, type: options.type });
     } else {
-      // @ts-expect-error SvelteKit / internal navigate might only take 1 arg or options obj
       navigate(targetUrl, options.type === 'replace' ? { replaceState: true } : undefined);
     }
   };

package/src/table-hooks.svelte.ts

@@ -69,15 +69,15 @@ export function useTable<
 
   const querySorters = $derived(sortersMode === 'server' ? effectiveSorters : []);
   const queryFilters = $derived(filtersMode === 'server' ? effectiveFilters : []);
-  const queryPagination = paginationMode === 'server'
+  const queryPagination = $derived(paginationMode === 'server'
     ? pagination
-    : { current: 1, pageSize: 999999, mode: paginationMode as 'client' | 'off' };
+    : { current: 1, pageSize: 999999, mode: paginationMode as 'client' | 'off' });
 
   const tableQueryInfo = useList<TQueryFnData, TError>({
     resource,
-    pagination: queryPagination,
-    sorters: querySorters,
-    filters: queryFilters,
+    get pagination() { return queryPagination; },
+    get sorters() { return querySorters; },
+    get filters() { return queryFilters; },
     meta,
     dataProviderName,
     ...restOptions

package/src/types.ts

@@ -213,6 +213,13 @@ export interface CheckResult {
   logout?: boolean;
 }
 
+export interface Role {
+  id: string;
+  name: string;
+  description?: string;
+  [key: string]: unknown;
+}
+
 export interface AuthProvider {
   login: (params: Record<string, unknown>) => Promise<AuthActionResult>;
   logout: (params?: Record<string, unknown>) => Promise<AuthActionResult>;
@@ -224,9 +231,28 @@ export interface AuthProvider {
   updatePassword?: (params: Record<string, unknown>) => Promise<AuthActionResult>;
   /** Update user profile (name, avatar, etc.) */
   updateProfile?: (params: { name?: string; avatar?: string | File; [key: string]: unknown }) => Promise<AuthActionResult>;
+  /** Get list of system roles for RBAC mapping */
+  getRoles?: () => Promise<Role[]>;
+  /** Get specific role permissions as a matrix map, e.g. { "users": ["create", "read"] } */
+  getRolePermissions?: (roleId: string) => Promise<Record<string, string[]>>;
+  /** Update permissions for a specific role */
+  updateRolePermissions?: (roleId: string, permissions: Record<string, string[]>) => Promise<AuthActionResult>;
+  /** Get recent audit logs */
+  getAuditLogs?: (params?: { page?: number; pageSize?: number }) => Promise<{ data: AuditLog[]; total: number }>;
   onError?: (error: unknown) => Promise<{ redirectTo?: string; logout?: boolean }>;
 }
 
+export interface AuditLog {
+  id: string | number;
+  userId?: string | number;
+  userName?: string;
+  action: string;
+  resource?: string;
+  createdAt: string | Date;
+  ipAddress?: string;
+  details?: Record<string, unknown> | string;
+}
+
 // ─── NotificationProvider ─────────────────────────────────────
 
 export interface NotificationProvider {
@@ -291,7 +317,7 @@ export interface FieldDefinition {
   label: string;
   type: 'text' | 'number' | 'boolean' | 'date' | 'select' | 'multiselect' | 'tags'
     | 'textarea' | 'richtext' | 'image' | 'images' | 'json' | 'relation' | 'color'
-    | 'url' | 'email' | 'phone' | 'file' | 'markdown' | 'password';
+    | 'url' | 'email' | 'phone' | 'file' | 'markdown' | 'password' | 'array';
   required?: boolean;
   searchable?: boolean;
   sortable?: boolean;
@@ -308,6 +334,8 @@ export interface FieldDefinition {
   resource?: string;       // related resource name
   optionLabel?: string;    // field to use as label
   optionValue?: string;    // field to use as value
+  // Array support
+  subFields?: FieldDefinition[]; // nested fields for array types
   // Validation
   validate?: (value: unknown) => string | null;
   // Grouping
@@ -336,7 +364,7 @@ export interface FieldDefinition {
  */
 export interface ResourceTypeMap {}
 
-/** When ResourceTypeMap is empty → string (backward compatible); otherwise → registered keys */
+/** When ResourceTypeMap is empty → string; otherwise → registered keys */
 export type KnownResources = keyof ResourceTypeMap extends never
   ? string
   : Extract<keyof ResourceTypeMap, string>

package/src/useCan.ts

@@ -22,36 +22,28 @@ export interface UseCanResult {
 
 /**
  * Reactive permission check backed by TanStack Query for caching and deduplication.
+ * Accepts a getter function for Svelte 5 fine-grained reactivity.
  *
  * @example
  * ```ts
- * // Simple usage (backward compatible)
- * const can = useCan('posts', 'delete');
+ * const can = useCan(() => ({ resource: 'posts', action: 'delete', params: { id: 1 } }));
  * if (can.allowed) { ... }
- *
- * // With options object
- * const can = useCan({ resource: 'posts', action: 'delete', params: { id: 1 } });
  * ```
  */
-export function useCan(resourceOrOptions: string | UseCanOptions, action?: Action, params?: Record<string, unknown>): UseCanResult {
-  // Normalize arguments: support both (resource, action, params) and (options) signatures
-  const options: UseCanOptions = typeof resourceOrOptions === 'string'
-    ? { resource: resourceOrOptions, action: action ?? 'list', params }
-    : resourceOrOptions;
-
-  // @tanstack/svelte-query v6 Accessor pattern
-  const query = createQuery<CanResult>(() => ({
-    queryKey: ['useCan', options.resource, options.action, options.params] as const,
-    queryFn: () => canAccessAsync(options.resource, options.action, options.params),
-    enabled: options.queryOptions?.enabled ?? true,
-    staleTime: options.queryOptions?.staleTime ?? 5 * 60 * 1000, // 5 min default cache
-  }));
+export function useCan(options: () => UseCanOptions): UseCanResult {
+  const query = createQuery<CanResult>(() => {
+    const opts = options();
+    return {
+      queryKey: ['useCan', opts.resource, opts.action, opts.params] as const,
+      queryFn: () => canAccessAsync(opts.resource, opts.action, opts.params),
+      enabled: opts.queryOptions?.enabled ?? true,
+      staleTime: opts.queryOptions?.staleTime ?? 5 * 60 * 1000,
+    };
+  });
 
-  // Access via query store — use safe property access with fallbacks
   return {
     get allowed() { return (query.data as CanResult | undefined)?.can ?? true; },
     get reason() { return (query.data as CanResult | undefined)?.reason; },
     get isLoading() { return query.isLoading; },
   };
 }
-