create-vexcms 0.0.20 → 0.1.0-alpha.3

package/templates/base-nextjs/src/app/globals.css

@@ -1,123 +1,243 @@
+/* ============================================================================
+   VexCMS · globals.css — Stark × Ember (shadcn-faithful translation)
+   ----------------------------------------------------------------------------
+   Source of design intent: .agent/docs/design/claude-design/admin.css (Claude Design
+   export). That file uses bespoke tokens (--page, --fg-muted, --line-bold,
+   --accent / --accent-tint / --accent-ink, …); this file translates them
+   into shadcn-named tokens so every React component in @vexcms/react keeps
+   working with no per-component overrides.
+
+   Read .agent/docs/design/claude-design/README.md before editing.
+
+   Key semantic decisions (different from naive shadcn):
+   - Brand CTA  → --primary       (admin.css `--accent`)        ember solid
+   - Highlight  → --accent        (admin.css `--accent-tint`)   ember tint
+   - Ink/active → --accent-fg     (admin.css `--accent-ink`)    deep ember
+   - Default surfaces (--card, --popover) = SAME tone (admin.css `--surface`)
+   - --muted / --raised = third elevation level (admin.css `--raised`)
+     used for table headers, modal foots, hover bgs, badge.muted.
+
+   All values are oklch.
+   ============================================================================ */
+
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "shadcn/tailwind.css";
+@import "@vexcms/next/styles";
 
-@source "../../node_modules/@vexcms/ui/dist/**/*.js";
-@source "../../node_modules/@vexcms/admin-next/dist/**/*.js";
-@source "../../node_modules/@vexcms/admin-next/src/**/*.tsx";
+/* Workspace source scan (belt-and-suspenders — normal dev relies on tsup
+   watchers rebuilding each package dist/, which Tailwind already scans via
+   @vexcms/next/styles). These two lines also point Tailwind at the raw
+   .tsx so classes appear immediately even if a tsup watcher dies. They
+   are workspace-relative and resolve only inside this monorepo. */
+@source "../../../../packages/react/src/**/*.ts";
+@source "../../../../packages/react/src/**/*.tsx";
+@source "../../../../packages/next/src/**/*.ts";
+@source "../../../../packages/next/src/**/*.tsx";
 
 @custom-variant dark (&:is(.dark *));
 
 @theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --font-sans: var(--font-sans);
-  --font-mono: var(--font-geist-mono);
-  --color-sidebar-ring: var(--sidebar-ring);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
+  /* ── Surfaces ─────────────────────────────────────────────────────────── */
+  --color-background:                 var(--background);
+  --color-foreground:                 var(--foreground);
+  --color-card:                       var(--card);
+  --color-card-foreground:            var(--card-foreground);
+  --color-popover:                    var(--popover);
+  --color-popover-foreground:         var(--popover-foreground);
+
+  /* ── Brand / accents ──────────────────────────────────────────────────── */
+  --color-primary:                    var(--primary);            /* ember solid */
+  --color-primary-foreground:         var(--primary-foreground);
+  --color-secondary:                  var(--secondary);
+  --color-secondary-foreground:       var(--secondary-foreground);
+  --color-accent:                     var(--accent);             /* ember tint */
+  --color-accent-foreground:          var(--accent-foreground);  /* ember ink */
+
+  /* ── Neutral hover & muted ────────────────────────────────────────────── */
+  --color-muted:                      var(--muted);              /* = --raised */
+  --color-muted-foreground:           var(--muted-foreground);
+
+  /* ── Borders & inputs ─────────────────────────────────────────────────── */
+  --color-border:                     var(--border);             /* default separators */
+  --color-input:                      var(--input);              /* input borders */
+  --color-ring:                       var(--ring);               /* solid ember focus */
+
+  /* ── Status ───────────────────────────────────────────────────────────── */
+  --color-destructive:                var(--destructive);
+  --color-destructive-foreground:     var(--destructive-foreground);
+
+  /* ── Sidebar ──────────────────────────────────────────────────────────── */
+  --color-sidebar:                    var(--sidebar);
+  --color-sidebar-foreground:         var(--sidebar-foreground);
+  --color-sidebar-primary:            var(--sidebar-primary);
   --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar: var(--sidebar);
-  --color-chart-5: var(--chart-5);
-  --color-chart-4: var(--chart-4);
-  --color-chart-3: var(--chart-3);
-  --color-chart-2: var(--chart-2);
+  --color-sidebar-accent:             var(--sidebar-accent);
+  --color-sidebar-accent-foreground:  var(--sidebar-accent-foreground);
+  --color-sidebar-border:             var(--sidebar-border);
+  --color-sidebar-ring:               var(--sidebar-ring);
+
+  /* ── Charts ───────────────────────────────────────────────────────────── */
   --color-chart-1: var(--chart-1);
-  --color-ring: var(--ring);
-  --color-input: var(--input);
-  --color-border: var(--border);
-  --color-destructive: var(--destructive);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-accent: var(--accent);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-muted: var(--muted);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-secondary: var(--secondary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-primary: var(--primary);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-popover: var(--popover);
-  --color-card-foreground: var(--card-foreground);
-  --color-card: var(--card);
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-  --radius-2xl: calc(var(--radius) + 8px);
-  --radius-3xl: calc(var(--radius) + 12px);
-  --radius-4xl: calc(var(--radius) + 16px);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+
+  /* ── Fonts ────────────────────────────────────────────────────────────── */
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-geist-mono);
+
+  /* ── Radii — Vex is sharp ─────────────────────────────────────────────── */
+  --radius-sm:  2px;   /* controls: buttons, inputs, menu items, type chips */
+  --radius-md:  4px;   /* cards, popovers, table wraps */
+  --radius-lg:  8px;   /* modals, dialogs */
+  --radius-xl:  12px;
+  --radius-2xl: 16px;
+  --radius-3xl: 20px;
+  --radius-4xl: 9999px; /* pill badges & avatars */
+
+  /* ── Shadows ──────────────────────────────────────────────────────────── */
+  --shadow-xs:  var(--shadow-xs-val);
+  --shadow-sm:  var(--shadow-sm-val);
+  --shadow-md:  var(--shadow-md-val);
+  --shadow-lg:  var(--shadow-lg-val);
+  --shadow-pop: var(--shadow-pop-val);
+
+  /* ── Motion ───────────────────────────────────────────────────────────── */
+  --ease-emphasized: cubic-bezier(.2, .8, .2, 1);
 }
 
+/* ────────────────────────────────────────────────────────────────────────────
+   LIGHT — Stark × Ember
+   page #F5F5F5 · surface #FFFFFF · raised #FAFAFA · fg #0A0A0A
+   ──────────────────────────────────────────────────────────────────────────── */
 :root {
-  --radius: 0.5rem;
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0.004 240);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0.004 240);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0.004 240);
-  --primary: oklch(0.205 0.003 240);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.965 0.002 240);
-  --secondary-foreground: oklch(0.205 0.003 240);
-  --muted: oklch(0.965 0.002 240);
-  --muted-foreground: oklch(0.556 0.002 240);
-  --accent: oklch(0.965 0.002 240);
-  --accent-foreground: oklch(0.205 0.003 240);
-  --destructive: oklch(0.577 0.184 27.3);
-  --border: oklch(0.922 0.003 240);
-  --input: oklch(0.922 0.003 240);
-  --ring: oklch(0.708 0.003 240);
-  --chart-1: oklch(0.646 0.222 41.116);
-  --chart-2: oklch(0.6 0.118 184.714);
-  --chart-3: oklch(0.398 0.07 227.392);
-  --chart-4: oklch(0.828 0.189 84.429);
-  --chart-5: oklch(0.769 0.188 70.08);
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0.004 240);
-  --sidebar-primary: oklch(0.205 0.003 240);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.965 0.002 240);
-  --sidebar-accent-foreground: oklch(0.205 0.003 240);
-  --sidebar-border: oklch(0.922 0.003 240);
-  --sidebar-ring: oklch(0.708 0.003 240);
+  /* Surfaces — three elevation levels */
+  --background:                  oklch(96.1% 0    0);            /* #F5F5F5 */
+  --foreground:                  oklch(13.7% 0    0);            /* #0A0A0A */
+  --card:                        oklch(100%  0    0);            /* #FFFFFF */
+  --card-foreground:             oklch(13.7% 0    0);
+  --popover:                     oklch(100%  0    0);            /* same as card */
+  --popover-foreground:          oklch(13.7% 0    0);
+
+  /* Brand — ember on --primary */
+  --primary:                     oklch(60.5% 0.175 42);          /* #E8622A */
+  --primary-foreground:          oklch(100%  0    0);
+
+  /* Neutral secondary */
+  --secondary:                   oklch(98%   0    0);            /* #FAFAFA */
+  --secondary-foreground:        oklch(13.7% 0    0);
+
+  /* Highlight = ember TINT (matches admin.css --accent-tint) */
+  --accent:                      oklch(96%   0.025 42);          /* #FEF0E8 */
+  --accent-foreground:           oklch(52%   0.180 40);          /* ember ink */
+
+  /* Neutral hover & muted (= admin.css --hover / --raised) */
+  --muted:                       oklch(98%   0    0);            /* #FAFAFA = raised */
+  --muted-foreground:            oklch(50.5% 0    0);            /* #717171 */
+
+  /* Borders */
+  --border:                      oklch(85%   0    0);            /* #D4D4D4 — default */
+  --input:                       oklch(54.6% 0    0);            /* #6B6B6B — inputs */
+  --ring:                        oklch(60.5% 0.175 42);          /* solid ember */
+
+  /* Status */
+  --destructive:                 oklch(57.7% 0.198 27);          /* #DC2626 */
+  --destructive-foreground:      oklch(98%   0    0);
+
+  /* Base radius — used by anything reading var(--radius) directly */
+  --radius: 4px;
+
+  /* Sidebar */
+  --sidebar:                     oklch(98%   0     0);           /* #FAFAFA */
+  --sidebar-foreground:          oklch(13.7% 0     0);
+  --sidebar-primary:             oklch(60.5% 0.175 42);          /* ember */
+  --sidebar-primary-foreground:  oklch(100%  0     0);
+  --sidebar-accent:              oklch(96.1% 0     0);
+  --sidebar-accent-foreground:   oklch(13.7% 0     0);
+  --sidebar-border:              oklch(85%   0     0);
+  --sidebar-ring:                oklch(60.5% 0.175 42);
+
+  /* Charts */
+  --chart-1: oklch(60.5% 0.175 42);
+  --chart-2: oklch(45%   0     0);
+  --chart-3: oklch(72%   0.100 60);
+  --chart-4: oklch(60%   0.040 30);
+  --chart-5: oklch(78%   0     0);
+
+  /* Shadows — soft elevation in light */
+  --shadow-xs-val:  0 1px 2px  rgba(10, 10, 10, 0.04);
+  --shadow-sm-val:  0 1px 3px  rgba(10, 10, 10, 0.08);
+  --shadow-md-val:  0 4px 12px rgba(10, 10, 10, 0.08);
+  --shadow-lg-val:  0 12px 32px rgba(10, 10, 10, 0.12);
+  --shadow-pop-val: 0 12px 28px rgba(10, 10, 10, 0.14),
+                    0 1px 3px   rgba(10, 10, 10, 0.06);
 }
 
+/* ────────────────────────────────────────────────────────────────────────────
+   DARK — Stark × Ember dark
+   page #0A0A0A · surface #141414 · raised #1E1E1E · fg #F4F4F4
+   Hotter ember (#F07040) for contrast. No flat shadows.
+   ──────────────────────────────────────────────────────────────────────────── */
 .dark {
-  --background: oklch(0.145 0.004 240);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.145 0.004 240);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.145 0.004 240);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.985 0 0);
-  --primary-foreground: oklch(0.205 0.003 240);
-  --secondary: oklch(0.269 0.006 240);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0.006 240);
-  --muted-foreground: oklch(0.708 0.003 240);
-  --accent: oklch(0.269 0.006 240);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.396 0.141 25.768);
-  --border: oklch(0.269 0.006 240);
-  --input: oklch(0.269 0.006 240);
-  --ring: oklch(0.439 0.003 240);
-  --chart-1: oklch(0.488 0.243 264.376);
-  --chart-2: oklch(0.696 0.17 162.48);
-  --chart-3: oklch(0.769 0.188 70.08);
-  --chart-4: oklch(0.627 0.265 303.9);
-  --chart-5: oklch(0.645 0.246 16.439);
-  --sidebar: oklch(0.205 0.003 240);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.269 0.006 240);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(0.269 0.006 240);
-  --sidebar-ring: oklch(0.439 0.003 240);
+  /* Surfaces */
+  --background:                  oklch(13.7% 0     0);           /* #0A0A0A */
+  --foreground:                  oklch(95%   0     0);           /* #F4F4F4 */
+  --card:                        oklch(17.4% 0     0);           /* #141414 */
+  --card-foreground:             oklch(95%   0     0);
+  --popover:                     oklch(17.4% 0     0);           /* same as card */
+  --popover-foreground:          oklch(95%   0     0);
+
+  /* Brand */
+  --primary:                     oklch(72%   0.175 50);          /* #F07040 */
+  --primary-foreground:          oklch(13.7% 0     0);
+
+  /* Secondary */
+  --secondary:                   oklch(20%   0     0);           /* #1E1E1E */
+  --secondary-foreground:        oklch(95%   0     0);
+
+  /* Highlight — translucent ember tint */
+  --accent:                      oklch(72%   0.175 50 / 0.12);
+  --accent-foreground:           oklch(72%   0.175 50);          /* ember itself in dark */
+
+  /* Neutral hover & muted */
+  --muted:                       oklch(20%   0     0);           /* = raised in dark */
+  --muted-foreground:            oklch(70%   0     0);           /* #A0A0A0 */
+
+  /* Borders */
+  --border:                      oklch(25%   0     0);           /* #2A2A2A */
+  --input:                       oklch(40%   0     0);           /* #5A5A5A */
+  --ring:                        oklch(72%   0.175 50);
+
+  /* Status */
+  --destructive:                 oklch(63%   0.210 27);          /* #EF4444 */
+  --destructive-foreground:      oklch(95%   0     0);
+
+  /* Sidebar */
+  --sidebar:                     oklch(7%    0     0);           /* #050505 */
+  --sidebar-foreground:          oklch(95%   0     0);
+  --sidebar-primary:             oklch(72%   0.175 50);
+  --sidebar-primary-foreground:  oklch(13.7% 0     0);
+  --sidebar-accent:              oklch(20%   0     0);
+  --sidebar-accent-foreground:   oklch(95%   0     0);
+  --sidebar-border:              oklch(25%   0     0);
+  --sidebar-ring:                oklch(72%   0.175 50);
+
+  /* Charts */
+  --chart-1: oklch(72%   0.175 50);
+  --chart-2: oklch(78%   0     0);
+  --chart-3: oklch(78%   0.120 65);
+  --chart-4: oklch(60%   0.060 30);
+  --chart-5: oklch(45%   0     0);
+
+  /* Shadows — flat in dark; only overlays use --shadow-pop */
+  --shadow-xs-val:  none;
+  --shadow-sm-val:  none;
+  --shadow-md-val:  none;
+  --shadow-lg-val:  none;
+  --shadow-pop-val: 0 18px 40px rgba(0, 0, 0, 0.55),
+                    0 1px 0 var(--border) inset;
 }
 
 @layer base {
@@ -126,5 +246,21 @@
   }
   body {
     @apply bg-background text-foreground;
+    font-feature-settings:
+      "ss01" 1,
+      "cv11" 1;
+    -webkit-font-smoothing: antialiased;
   }
 }
+
+/* Pangea dnd placeholder — thin dashed line instead of full-height gap */
+[data-rfd-placeholder] {
+  height: 3px !important;
+  min-height: 3px !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  background: transparent !important;
+  border-radius: 0 !important;
+  border-top: 2px dashed var(--border) !important;
+}
+

package/templates/base-nextjs/src/app/layout.tsx

@@ -1,28 +1,38 @@
 import type { Metadata } from "next"
-import { Geist, Geist_Mono, Inter } from "next/font/google"
+
+import "./globals.css"
+
+import { Geist, Geist_Mono } from "next/font/google"
 
 import ClientProviders from "~/components/providers/client"
 import ServerProviders from "~/components/providers/server"
 
-import "./globals.css"
+const geistSans = Geist({
+  subsets: ["latin"],
+  variable: "--font-sans",
+})
 
-const inter = Inter({ subsets: ["latin"], variable: "--font-sans" })
-const geistSans = Geist({ subsets: ["latin"], variable: "--font-geist-sans" })
-const geistMono = Geist_Mono({ subsets: ["latin"], variable: "--font-geist-mono" })
+const geistMono = Geist_Mono({
+  subsets: ["latin"],
+  variable: "--font-geist-mono",
+})
 
 export const metadata: Metadata = {
-  description: "Test application for Vex CMS development",
-  title: "Vex CMS Test App",
+  description: "Built with VexCMS",
+  icons: { icon: "/favicons/favicon.ico" },
+  title: "VexCMS",
 }
 
-export default function RootLayout({ children }: { children: React.ReactNode }) {
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode
+}>) {
   return (
-    <html lang="en" suppressHydrationWarning className={`${inter.variable} ${geistSans.variable} ${geistMono.variable}`}>
-      <body className="antialiased">
+    <html className={`${geistSans.variable} ${geistMono.variable} antialiased`} lang="en" suppressHydrationWarning>
+      <body>
         <ServerProviders>
-          <ClientProviders>
-            {children}
-          </ClientProviders>
+          <ClientProviders>{children}</ClientProviders>
         </ServerProviders>
       </body>
     </html>

package/templates/base-nextjs/src/app/unauthorized/page.tsx

@@ -0,0 +1,24 @@
+import { UnauthorizedView } from "@vexcms/react";
+import Link from "next/link";
+
+export const metadata = {
+  title: "Access denied",
+};
+
+/**
+ * Landing page for callers who are signed in but fail the `adminPanel.access`
+ * check in the access matrix.
+ *
+ * Deliberately lives OUTSIDE the `(vexcms)/admin` segment: that segment's layout
+ * mounts the admin shell and redirects unauthorized callers here, so rendering
+ * this inside it would loop.
+ */
+export default function UnauthorizedPage() {
+  return (
+    <UnauthorizedView>
+      <Link className="text-primary underline" href="/">
+        Return to site
+      </Link>
+    </UnauthorizedView>
+  );
+}

package/templates/base-nextjs/src/auth/access.ts

@@ -0,0 +1,46 @@
+import { defineAccess } from "@vexcms/core"
+
+import {
+  TABLE_SLUG_ORGANIZATIONS,
+  TABLE_SLUG_USERS,
+  USER_ROLES,
+} from "~/db/constants"
+import { images, users } from "~/vexcms/collections"
+
+/**
+ * Access control (RBAC) for the admin panel and every registered collection.
+ *
+ * `admin` gets unrestricted access. `user` can read and update only their own
+ * profile row and cannot reach the admin panel. Add a resource here whenever
+ * you register a new collection in `vex.config.ts`.
+ *
+ * @see https://vexcms.dev/docs/access-control
+ */
+export const access = defineAccess({
+  anonRole: USER_ROLES.user,
+  roles: Object.values(USER_ROLES),
+  userRolesField: "roles",
+  userCollectionSlug: TABLE_SLUG_USERS,
+  orgCollectionSlug: TABLE_SLUG_ORGANIZATIONS,
+  resources: [images, users],
+  permissions: {
+    [USER_ROLES.admin]: {
+      "*": true,
+    },
+    [USER_ROLES.user]: {
+      "*": false,
+      adminPanel: {
+        access: false,
+      },
+      user: {
+        "*": false,
+        read: {
+          constraints: ({ user, q }) => q.withIndex("by_email", (fq) => fq.eq("email", user.email)),
+        },
+        update: {
+          constraints: ({ user, q }) => q.filter((fq) => fq.eq("email", user.email)),
+        },
+      },
+    },
+  },
+})

package/templates/base-nextjs/src/auth/client.tsx

@@ -1,25 +1,37 @@
 import type { ReactNode } from "react"
 
+import { apiKeyClient } from "@better-auth/api-key/client"
 import { convexClient } from "@convex-dev/better-auth/client/plugins"
 import { AuthUIProvider } from "@daveyplate/better-auth-ui"
-import { adminClient, apiKeyClient } from "better-auth/client/plugins"
+import { adminClient, anonymousClient } from "better-auth/client/plugins"
 import { createAuthClient } from "better-auth/react"
 import Link from "next/link"
 import { useRouter } from "next/navigation"
 
 import { env } from "~/env.mjs"
 
+/**
+ * Global Better Auth client for this project.
+ *
+ * Configured with the site's auth base URL and plugins for admin roles,
+ * anonymous access, API key auth, and Convex session storage. Add
+ * `organizationClient()` from `better-auth/client/plugins` here if you enable
+ * organizations (`--orgs`, or by hand later) — the server-side `organization()`
+ * plugin alone does not surface org UI on the client.
+ *
+ * @see signIn, signOut, useSession — destructured from this client
+ * @see BetterAuthClientProvider — wraps the app with this client
+ */
 export const authClient = createAuthClient({
   basePath: "/api/auth",
   baseURL: env.NEXT_PUBLIC_SITE_URL,
-  plugins: [adminClient(), apiKeyClient(), convexClient()],
+  plugins: [adminClient(), anonymousClient(), apiKeyClient(), convexClient()],
 })
 
 export const { signIn, signOut, useSession } = authClient
 
-// copied from code example, unsure if this is actually useful or not
-// eslint-disable-next-line @typescript-eslint/no-misused-promises, @typescript-eslint/no-empty-function
-authClient.$store.listen("$sessionSignal", async () => { })
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+authClient.$store.listen("$sessionSignal", () => {})
 
 export default function BetterAuthClientProvider({ children }: { children: ReactNode }) {
   const router = useRouter()

package/templates/base-nextjs/src/auth/hasPermission.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import { hasPermission as hasPermissionCore, type HasPermissionProps } from "@vexcms/core";
+
+import { useAuth } from "~/context/AuthContext";
+
+import { access } from "./access";
+
+type Subjects = NonNullable<typeof access.__subjects>;
+/**
+ * Client-side permission check for UI affordances (advisory — server guards enforce).
+ *
+ * Kept alongside `@vexcms/react`'s `usePermission` deliberately: the frontend tree is
+ * not wrapped in the Vex providers, so this reads the app's own `AuthContext` and
+ * imports the access config directly instead of resolving both from context.
+ *
+ * @param props.resource - Subject slug (collection/global/media/`adminPanel`).
+ * @param props.action - Action to check.
+ * @param props.data - The concrete document for an exact per-doc check (edit views).
+ * @param props.scope - How to answer when a check needs the document and `data` was
+ *   not supplied: `"all"` (the default) → false, `"any"` → true (sidebar/list
+ *   gating), `"doc"` → throws (edit views — pass `data`). No effect when `data` is
+ *   given. See `PERMISSION_SCOPES`.
+ * @returns The permission boolean. `false` for a signed-out user; `true` when no
+ *   `access` config exists at all — the access system being absent is the documented
+ *   open-by-default escape hatch, not a denial.
+ */
+export function hasPermission<TSubject extends keyof Subjects, TData extends object = object>(
+  props: Omit<HasPermissionProps<Subjects, TSubject, TData>, "access" | "organization" | "user">,
+): boolean {
+  // eslint-disable-next-line react-hooks/rules-of-hooks
+  const { user, organization } = useAuth();
+  return hasPermissionCore({
+    access,
+    user,
+    organization,
+    ...props,
+  });
+}