refactor: reorganize package exports under namespaced paths

- Prefix feature exports with `features/` (auth, admin, provider)
- Prefix shared exports with `shared/` (components, icons, lib, config, logger, rate-limit)
- Add new explicit exports for `shared/logger`, `shared/config`, and `shared/rate-limit`
- Update internal imports to use package self-referencing (`@zen/core/shared/*`) instead of relative paths

package.json

@@ -49,36 +49,39 @@
     ".": {
       "import": "./dist/index.js"
     },
-    "./auth": {
+    "./features/auth": {
       "import": "./dist/features/auth/index.js"
     },
-    "./auth/actions": {
+    "./features/auth/actions": {
       "import": "./dist/features/auth/actions.js"
     },
-    "./auth/pages": {
+    "./features/auth/pages": {
       "import": "./dist/features/auth/pages.js"
     },
-    "./auth/page": {
+    "./features/auth/page": {
       "import": "./dist/features/auth/page.js"
     },
-    "./auth/components": {
+    "./features/auth/components": {
       "import": "./dist/features/auth/components/index.js"
     },
-    "./admin": {
+    "./features/admin": {
       "import": "./dist/features/admin/index.js"
     },
-    "./admin/actions": {
+    "./features/admin/actions": {
       "import": "./dist/features/admin/actions.js"
     },
-    "./admin/navigation": {
+    "./features/admin/navigation": {
       "import": "./dist/features/admin/navigation.server.js"
     },
-    "./admin/pages": {
+    "./features/admin/pages": {
       "import": "./dist/features/admin/pages.js"
     },
-    "./admin/page": {
+    "./features/admin/page": {
       "import": "./dist/features/admin/page.js"
     },
+    "./features/provider": {
+      "import": "./dist/features/provider/index.js"
+    },
     "./api": {
       "import": "./dist/core/api/index.js"
     },
@@ -112,18 +115,24 @@
     "./toast": {
       "import": "./dist/core/toast/index.js"
     },
-    "./provider": {
+    "./shared/components": {
-      "import": "./dist/features/provider/index.js"
-    },
-    "./lib/metadata": {
-      "import": "./dist/shared/lib/metadata/index.js"
-    },
-    "./components": {
       "import": "./dist/shared/components/index.js"
     },
-    "./icons": {
+    "./shared/icons": {
       "import": "./dist/shared/Icons.js"
     },
+    "./shared/lib/metadata": {
+      "import": "./dist/shared/lib/metadata/index.js"
+    },
+    "./shared/logger": {
+      "import": "./dist/shared/lib/logger.js"
+    },
+    "./shared/config": {
+      "import": "./dist/shared/lib/appConfig.js"
+    },
+    "./shared/rate-limit": {
+      "import": "./dist/shared/lib/rateLimit.js"
+    },
     "./styles/zen.css": {
       "default": "./dist/shared/styles/zen.css"
     }

src/core/api/route-handler.js

@@ -12,7 +12,7 @@ import { NextResponse } from 'next/server';
 import { routeRequest } from './router.js';
 import { apiError, getStatusCode } from './respond.js';
 import { buildFileResponse } from './file-response.js';
-import { fail } from '../../shared/lib/logger.js';
+import { fail } from '@zen/core/shared/logger';
 
 const GENERIC_ERROR_MSG = 'An unexpected error occurred. Please try again later.';
 

src/core/api/router.js

@@ -19,9 +19,9 @@
  */
 
 import { cookies } from 'next/headers';
-import { getSessionCookieName } from '../../shared/lib/appConfig.js';
+import { getSessionCookieName } from '@zen/core/shared/config';
-import { checkRateLimit, getIpFromRequest, formatRetryAfter } from '../../shared/lib/rateLimit.js';
+import { checkRateLimit, getIpFromRequest, formatRetryAfter } from '@zen/core/shared/rate-limit';
-import { fail } from '../../shared/lib/logger.js';
+import { fail } from '@zen/core/shared/logger';
 import { getCoreRoutes } from './core-routes.js';
 import { getFeatureRoutes, getSessionResolver } from './runtime.js';
 import { apiError } from './respond.js';

src/core/cron/index.js

@@ -7,7 +7,7 @@
  */
 
 import cron from 'node-cron';
-import { done, fail, info } from '../../shared/lib/logger.js';
+import { done, fail, info } from '@zen/core/shared/logger';
 
 // Shared store — survives Next.js hot-reload and module-cache invalidation
 const CRON_JOBS_KEY = Symbol.for('__ZEN_CRON_JOBS__');

src/core/database/cli.js

@@ -18,7 +18,7 @@ process.env.NODE_ENV = process.env.NODE_ENV || 'development';
 
 import { testConnection, closePool } from './index.js';
 import readline from 'readline';
-import { step, done, warn, fail } from '../../shared/lib/logger.js';
+import { step, done, warn, fail } from '@zen/core/shared/logger';
 
 function printHelp() {
   console.log(`

src/core/database/db.js

@@ -5,7 +5,7 @@
 
 import pkg from 'pg';
 const { Pool } = pkg;
-import { fail } from '../../shared/lib/logger.js';
+import { fail } from '@zen/core/shared/logger';
 
 /**
  * Opaque error type thrown by all database operations.

src/core/email/index.js

@@ -1,5 +1,5 @@
 import { Resend } from 'resend';
-import { done, fail, info } from '../../shared/lib/logger.js';
+import { done, fail, info } from '@zen/core/shared/logger';
 
 let resendClient = null;
 

src/core/storage/api.js

@@ -16,10 +16,10 @@
  */
 
 import { cookies } from 'next/headers';
-import { getSessionCookieName } from '../../shared/lib/appConfig.js';
+import { getSessionCookieName } from '@zen/core/shared/config';
 import { getSessionResolver } from '../api/router.js';
 import { getFile } from './index.js';
-import { fail } from '../../shared/lib/logger.js';
+import { fail } from '@zen/core/shared/logger';
 import { defineApiRoutes } from '../api/define.js';
 import { apiError } from '../api/respond.js';
 import { getStoragePublicPrefixes, getStorageAccessPolicies } from './storage-config.js';

src/core/storage/index.js

@@ -1,5 +1,5 @@
 import { createHash } from 'crypto';
-import { fail, warn, info } from '../../shared/lib/logger.js';
+import { fail, warn, info } from '@zen/core/shared/logger';
 import {
   signRequest,
   buildPresignedUrl,

src/core/toast/Toast.js

@@ -7,7 +7,7 @@ import {
     AlertCircleIcon,
     InformationCircleIcon,
     CancelCircleIcon
-} from '../../shared/Icons.js';
+} from '@zen/core/shared/icons';
 
 const Toast = ({ 
     id, 

src/features/admin/actions.js

@@ -4,7 +4,7 @@
  * Exported separately from admin/index.js to avoid bundling
  * server-side code (which includes database imports) into client components.
  *
- * Usage: import { getDashboardStats } from '@zen/core/admin/actions';
+ * Usage: import { getDashboardStats } from '@zen/core/features/admin/actions';
  */
 
 export { getDashboardStats } from './actions/statsActions.js';

src/features/admin/actions/statsActions.js

@@ -6,9 +6,9 @@
  *
  * ```javascript
  * // app/(admin)/admin/[...admin]/page.js
- * import { protectAdmin } from '@zen/core/admin';
+ * import { protectAdmin } from '@zen/core/features/admin';
- * import { getDashboardStats } from '@zen/core/admin/actions';
+ * import { getDashboardStats } from '@zen/core/features/admin/actions';
- * import { AdminPagesClient } from '@zen/core/admin/pages';
+ * import { AdminPagesClient } from '@zen/core/features/admin/pages';
  *
  * export default async function AdminPage({ params }) {
  *   const { user } = await protectAdmin();
@@ -30,7 +30,7 @@
 'use server';
 
 import { query } from '@zen/core/database';
-import { fail } from '../../../shared/lib/logger.js';
+import { fail } from '@zen/core/shared/logger';
 
 /**
  * Get total number of users

src/features/admin/components/AdminHeader.js

@@ -3,7 +3,7 @@
 import React from 'react';
 import { Menu, Transition } from '@headlessui/react';
 import { Fragment } from 'react';
-import { ChevronDownIcon } from '../../../shared/Icons.js';
+import { ChevronDownIcon } from '@zen/core/shared/icons';
 import { useRouter } from 'next/navigation';
 import ThemeToggle from './ThemeToggle';
 

src/features/admin/components/AdminSidebar.js

@@ -3,8 +3,8 @@
 import React, { useState, useEffect } from 'react';
 import Link from 'next/link';
 import { usePathname } from 'next/navigation';
-import * as Icons from '../../../shared/Icons.js';
+import * as Icons from '@zen/core/shared/icons';
-import { ChevronDownIcon } from '../../../shared/Icons.js';
+import { ChevronDownIcon } from '@zen/core/shared/icons';
 
 /**
  * Resolve icon name (string) to icon component

src/features/admin/components/ThemeToggle.js

@@ -1,7 +1,7 @@
 'use client';
 
 import { useState, useEffect } from 'react';
-import { Sun01Icon, Moon02Icon, SunCloud02Icon, MoonCloudIcon } from '../../../shared/Icons.js';
+import { Sun01Icon, Moon02Icon, SunCloud02Icon, MoonCloudIcon } from '@zen/core/shared/icons';
 
 function getNextTheme(current) {
     const systemIsDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

src/features/admin/components/pages/DashboardPage.js

@@ -1,7 +1,7 @@
 'use client';
 
-import { StatCard } from '../../../../shared/components';
+import { StatCard } from '@zen/core/shared/components';
-import { UserMultiple02Icon } from '../../../../shared/Icons.js';
+import { UserMultiple02Icon } from '@zen/core/shared/icons';
 
 export default function DashboardPage({ user, stats }) {
   const loading = !stats;

src/features/admin/components/pages/ProfilePage.js

@@ -1,7 +1,7 @@
 'use client';
 
 import React, { useState, useEffect, useRef } from 'react';
-import { Card, Input, Button } from '../../../../shared/components';
+import { Card, Input, Button } from '@zen/core/shared/components';
 import { useToast } from '@zen/core/toast';
 
 const ProfilePage = ({ user: initialUser }) => {

src/features/admin/components/pages/UserEditPage.js

@@ -2,7 +2,7 @@
 
 import React, { useState, useEffect } from 'react';
 import { useRouter } from 'next/navigation';
-import { Button, Card, Input, Select, Loading } from '../../../../shared/components';
+import { Button, Card, Input, Select, Loading } from '@zen/core/shared/components';
 import { useToast } from '@zen/core/toast';
 
 /**

src/features/admin/components/pages/UsersPage.js

@@ -2,8 +2,8 @@
 
 import React, { useState, useEffect } from 'react';
 import { useRouter } from 'next/navigation';
-import { Card, Table, StatusBadge, Pagination, Button } from '../../../../shared/components';
+import { Card, Table, StatusBadge, Pagination, Button } from '@zen/core/shared/components';
-import { PencilEdit01Icon } from '../../../../shared/Icons.js';
+import { PencilEdit01Icon } from '@zen/core/shared/icons';
 import { useToast } from '@zen/core/toast';
 
 const UsersPageClient = () => {

src/features/admin/middleware/protect.js

@@ -3,7 +3,7 @@
  * Utilities to protect admin routes and require admin role
  */
 
-import { getSession } from '../../auth/actions/authActions.js';
+import { getSession } from '@zen/core/features/auth/actions';
 import { redirect } from 'next/navigation';
 
 /**
@@ -17,7 +17,7 @@ import { redirect } from 'next/navigation';
  * 
  * @example
  * // In a server component:
- * import { protectAdmin } from '@zen/core/admin';
+ * import { protectAdmin } from '@zen/core/features/admin';
  * 
  * export default async function AdminPage() {
  *   const session = await protectAdmin();
@@ -47,7 +47,7 @@ async function protectAdmin(options = {}) {
  * @returns {Promise<boolean>} True if user is admin
  * 
  * @example
- * import { isAdmin } from '@zen/core/admin';
+ * import { isAdmin } from '@zen/core/features/admin';
  * 
  * export default async function Page() {
  *   const admin = await isAdmin();

src/features/admin/page.js

@@ -2,14 +2,14 @@
  * Admin Page - Server Component Wrapper for Next.js App Router
  *
  * Re-export this in your app/admin/[...admin]/page.js:
- * export { default } from '@zen/core/admin/page';
+ * export { default } from '@zen/core/features/admin/page';
  */
 
-import { AdminPagesLayout, AdminPagesClient } from '@zen/core/admin/pages';
+import { AdminPagesLayout, AdminPagesClient } from '@zen/core/features/admin/pages';
-import { protectAdmin } from '@zen/core/admin';
+import { protectAdmin } from '@zen/core/features/admin';
-import { buildNavigationSections } from '@zen/core/admin/navigation';
+import { buildNavigationSections } from '@zen/core/features/admin/navigation';
-import { getDashboardStats } from '@zen/core/admin/actions';
+import { getDashboardStats } from '@zen/core/features/admin/actions';
-import { logoutAction } from '@zen/core/auth/actions';
+import { logoutAction } from '@zen/core/features/auth/actions';
 import { getAppName } from '@zen/core';
 
 export default async function AdminPage({ params }) {

src/features/auth/actions/authActions.js

@@ -8,10 +8,10 @@
 import { register, login, requestPasswordReset, resetPassword, verifyUserEmail } from '../lib/auth.js';
 import { validateSession, deleteSession } from '../lib/session.js';
 import { verifyEmailToken, verifyResetToken, sendVerificationEmail, sendPasswordResetEmail } from '../lib/email.js';
-import { fail } from '../../../shared/lib/logger.js';
+import { fail } from '@zen/core/shared/logger';
 import { cookies, headers } from 'next/headers';
-import { getSessionCookieName, getPublicBaseUrl } from '../../../shared/lib/appConfig.js';
+import { getSessionCookieName, getPublicBaseUrl } from '@zen/core/shared/config';
-import { checkRateLimit, getIpFromHeaders, formatRetryAfter } from '../../../shared/lib/rateLimit.js';
+import { checkRateLimit, getIpFromHeaders, formatRetryAfter } from '@zen/core/shared/rate-limit';
 
 /**
  * Errors that are safe to surface verbatim to the client (e.g. "token expired").

src/features/auth/api.js

@@ -12,9 +12,8 @@ import { updateUser } from './lib/auth.js';
 import { uploadImage, deleteFile, generateUniqueFilename, getFileExtension, FILE_TYPE_PRESETS, FILE_SIZE_LIMITS, validateUpload } from '@zen/core/storage';
 
 const generateUserFilePath = (userId, category, filename) => `users/${userId}/${category}/${filename}`;
-import { fail, info } from '../../shared/lib/logger.js';
+import { fail, info } from '@zen/core/shared/logger';
-import { defineApiRoutes } from '../../core/api/define.js';
+import { defineApiRoutes, apiSuccess, apiError } from '@zen/core/api';
-import { apiSuccess, apiError } from '../../core/api/respond.js';
 
 /** Maximum number of users returned per paginated request */
 const MAX_PAGE_LIMIT = 100;

src/features/auth/components/AccountSection.js

@@ -10,7 +10,7 @@
  */
 
 import React, { useState, useEffect, useRef } from 'react';
-import { Card, Input, Button } from '../../../shared/components/index.js';
+import { Card, Input, Button } from '@zen/core/shared/components';
 import { useToast } from '@zen/core/toast';
 import { useCurrentUser } from './useCurrentUser.js';
 import UserAvatar from './UserAvatar.js';

src/features/auth/components/index.js

@@ -3,8 +3,8 @@
  *
  * Use these components to build custom auth pages for every flow (login, register, forgot,
  * reset, confirm, logout) so they match your site's style.
- * For a ready-made catch-all auth UI, use AuthPagesClient from '@zen/core/auth/pages'.
+ * For a ready-made catch-all auth UI, use AuthPagesClient from '@zen/core/features/auth/pages'.
- * For the default full-page auth (no custom layout), re-export from '@zen/core/auth/page'.
+ * For the default full-page auth (no custom layout), re-export from '@zen/core/features/auth/page'.
  *
  * --- Custom auth pages (all types) ---
  *
@@ -21,7 +21,7 @@
  *
  * onNavigate receives 'login' | 'register' | 'forgot' | 'reset'. Map to your routes (e.g. /auth/${page}).
  * For reset/confirm, pass email and token from searchParams. Full guide: see README-custom-login.md in this package.
- * Protect routes with protect() from '@zen/core/auth', redirectTo your login path.
+ * Protect routes with protect() from '@zen/core/features/auth', redirectTo your login path.
  *
  * --- Dashboard / user display ---
  *

src/features/auth/components/pages/RegisterPage.js

@@ -5,7 +5,7 @@
  */
 
 import { useState, useEffect } from 'react';
-import { PasswordStrengthIndicator } from '../../../../shared/components';
+import { PasswordStrengthIndicator } from '@zen/core/shared/components';
 
 export default function RegisterPage({ onSubmit, onNavigate, currentUser = null }) {
   const [error, setError] = useState('');

src/features/auth/components/pages/ResetPasswordPage.js

@@ -5,7 +5,7 @@
  */
 
 import { useState } from 'react';
-import { PasswordStrengthIndicator } from '../../../../shared/components';
+import { PasswordStrengthIndicator } from '@zen/core/shared/components';
 
 export default function ResetPasswordPage({ onSubmit, onNavigate, email, token }) {
   const [error, setError] = useState('');

src/features/auth/db.js

@@ -4,7 +4,7 @@
  */
 
 import { query, tableExists } from '@zen/core/database';
-import { done, warn } from '../../shared/lib/logger.js';
+import { done, warn } from '@zen/core/shared/logger';
 
 const AUTH_TABLES = [
   {

src/features/auth/lib/auth.js

@@ -3,10 +3,10 @@
  * Main authentication functions for user registration, login, and password management
  */
 
-import { create, findOne, updateById, count } from '../../../core/database/crud.js';
+import { create, findOne, updateById, count } from '@zen/core/database';
 import { hashPassword, verifyPassword, generateId } from './password.js';
 import { createSession } from './session.js';
-import { fail } from '../../../shared/lib/logger.js';
+import { fail } from '@zen/core/shared/logger';
 import { createEmailVerification, createPasswordReset, verifyResetToken, deleteResetToken, sendPasswordChangedEmail } from './email.js';
 
 /**

src/features/auth/lib/email.js

@@ -1,9 +1,9 @@
 import crypto from 'crypto';
 import { render } from '@react-email/components';
-import { create, findOne, deleteWhere } from '../../../core/database/crud.js';
+import { create, findOne, deleteWhere } from '@zen/core/database';
 import { generateToken, generateId } from './password.js';
-import { fail, info } from '../../../shared/lib/logger.js';
+import { fail, info } from '@zen/core/shared/logger';
-import { sendEmail } from '../../../core/email/index.js';
+import { sendEmail } from '@zen/core/email';
 import { VerificationEmail } from '../templates/VerificationEmail.jsx';
 import { PasswordResetEmail } from '../templates/PasswordResetEmail.jsx';
 import { PasswordChangedEmail } from '../templates/PasswordChangedEmail.jsx';

src/features/auth/lib/session.js

@@ -3,7 +3,7 @@
  * Handles user session creation, validation, and deletion
  */
 
-import { create, findOne, deleteWhere, updateById } from '../../../core/database/crud.js';
+import { create, findOne, deleteWhere, updateById } from '@zen/core/database';
 import { generateToken, generateId } from './password.js';
 
 /**

src/features/auth/middleware/protect.js

@@ -16,7 +16,7 @@ import { redirect } from 'next/navigation';
  * 
  * @example
  * // In a server component:
- * import { protect } from '@zen/core/auth';
+ * import { protect } from '@zen/core/features/auth';
  * 
  * export default async function ProtectedPage() {
  *   const session = await protect();
@@ -42,7 +42,7 @@ async function protect(options = {}) {
  * @returns {Promise<Object|null>} Session object or null if not authenticated
  * 
  * @example
- * import { checkAuth } from '@zen/core/auth';
+ * import { checkAuth } from '@zen/core/features/auth';
  * 
  * export default async function Page() {
  *   const session = await checkAuth();

src/features/auth/page.js

@@ -2,14 +2,14 @@
  * Auth Page - Server Component Wrapper for Next.js App Router
  *
  * Default auth UI: login, register, forgot, reset, confirm, logout at /auth/[...auth].
- * Re-export in your app: export { default } from '@zen/core/auth/page';
+ * Re-export in your app: export { default } from '@zen/core/features/auth/page';
  *
  * For custom auth pages (all flows) that match your site style, use components from
- * '@zen/core/auth/components' and actions from '@zen/core/auth/actions'.
+ * '@zen/core/features/auth/components' and actions from '@zen/core/features/auth/actions'.
  * See README-custom-login.md in this package. Basic sites can keep using this default page.
  */
 
-import { AuthPagesClient } from '@zen/core/auth/pages';
+import { AuthPagesClient } from '@zen/core/features/auth/pages';
 import {
   registerAction,
   loginAction,
@@ -19,7 +19,7 @@ import {
   verifyEmailAction,
   setSessionCookie,
   getSession
-} from '@zen/core/auth/actions';
+} from '@zen/core/features/auth/actions';
 
 export default async function AuthPage({ params, searchParams }) {
   const session = await getSession();

src/features/init.js

@@ -7,7 +7,7 @@
  */
 
 import { CORE_FEATURES } from './features.registry.js';
-import { done, fail, info, step } from '../shared/lib/logger.js';
+import { done, fail, info, step } from '@zen/core/shared/logger';
 
 /**
  * Initialize all core feature databases.

src/shared/lib/init.js

@@ -14,7 +14,7 @@
  * }
  */
 
-import { configureRouter, registerFeatureRoutes, clearRouterConfig, clearFeatureRoutes } from '../../core/api/index.js';
+import { configureRouter, registerFeatureRoutes, clearRouterConfig, clearFeatureRoutes } from '@zen/core/api';
 import { validateSession } from '../../features/auth/lib/session.js';
 import { routes as authRoutes } from '../../features/auth/api.js';
 import { done, warn } from './logger.js';

tsup.config.js

@@ -23,15 +23,19 @@ export default defineConfig([
       'src/core/storage/index.js',
       'src/core/toast/index.js',
       'src/features/provider/index.js',
+      'src/shared/components/index.js',
+      'src/shared/Icons.js',
       'src/shared/lib/metadata/index.js',
       'src/shared/lib/logger.js',
+      'src/shared/lib/appConfig.js',
+      'src/shared/lib/rateLimit.js',
     ],
     format: ['esm'],
     dts: false,
     splitting: false,
     sourcemap: false,
     clean: true,
-    external: ['react', 'react-dom', 'next', 'pg', 'dotenv', 'dotenv/config', 'resend', '@react-email/components', 'node-cron', 'readline', 'crypto', 'url', 'fs', 'path', 'net', 'dns', 'tls', '@zen/core/api', '@zen/core/cron', '@zen/core/database', '@zen/core/email', '@zen/core/email/templates', '@zen/core/storage', '@zen/core/toast', '@aws-sdk/client-s3', '@aws-sdk/s3-request-presigner'],
+    external: ['react', 'react-dom', 'next', 'pg', 'dotenv', 'dotenv/config', 'resend', '@react-email/components', 'node-cron', 'readline', 'crypto', 'url', 'fs', 'path', 'net', 'dns', 'tls', '@zen/core/api', '@zen/core/cron', '@zen/core/database', '@zen/core/email', '@zen/core/email/templates', '@zen/core/storage', '@zen/core/toast', '@zen/core/features/auth', '@zen/core/features/auth/actions', '@zen/core/features/auth/components', '@zen/core/shared/components', '@zen/core/shared/icons', '@zen/core/shared/logger', '@zen/core/shared/config', '@zen/core/shared/rate-limit', '@aws-sdk/client-s3', '@aws-sdk/s3-request-presigner'],
     noExternal: [],
     bundle: true,
     banner: {
@@ -64,12 +68,12 @@ export default defineConfig([
       'react-dom',
       'next',
       '@zen/core',
-      '@zen/core/auth/pages',
+      '@zen/core/features/auth/pages',
-      '@zen/core/auth/actions',
+      '@zen/core/features/auth/actions',
-      '@zen/core/admin',
+      '@zen/core/features/admin',
-      '@zen/core/admin/pages',
+      '@zen/core/features/admin/pages',
-      '@zen/core/admin/actions',
+      '@zen/core/features/admin/actions',
-      '@zen/core/admin/navigation',
+      '@zen/core/features/admin/navigation',
       '@zen/core/toast',
     ],
     bundle: false, // Don't bundle these files