@object-ui/app-shell 7.0.0 → 7.2.0

package/dist/environment/EnvironmentEntitlementDialog.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * EnvironmentEntitlementDialog — a friendly upgrade / limit dialog shown instead
+ * of a raw red error toast when an environment-create is gated by plan or
+ * capacity (DEV_ENV_PLAN_LOCKED / DEV_ENV_LIMIT / PRODUCTION_ENV_LIMIT).
+ *
+ * Driven by a single {@link EntitlementDialogSpec}, opened from two places:
+ *   • proactively, from the env-list toolbar (a free-plan org clicking
+ *     "Add environment" — see EnvironmentListToolbar), and
+ *   • reactively, from the action runtime's apiHandler when the create POST
+ *     comes back with an entitlement 403 (the safety net).
+ *
+ * The CTA renders as an anchor (not an SPA navigation) so a control-plane URL
+ * like `/settings/billing` always lands on the real page regardless of the
+ * console's own router. Relative URLs resolve against the control-plane origin
+ * (`apiBase`); absolute / mailto URLs are used as-is.
+ */
+import { AlertDialog, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogCancel, Button, } from '@object-ui/components';
+/** Resolve a CTA URL to a concrete href + whether it should open in a new tab. */
+export function resolveCtaHref(url, apiBase) {
+    if (/^https?:\/\//i.test(url) || url.startsWith('mailto:')) {
+        return { href: url, external: !url.startsWith('mailto:') };
+    }
+    const base = (apiBase || '').replace(/\/+$/, '');
+    // A control-plane-relative path: prefix the API origin when we have one (dev:
+    // split SPA + backend). Empty base → same-origin relative (prod).
+    return { href: `${base}${url}`, external: Boolean(base) };
+}
+function CtaButton({ cta, apiBase, primary, onNavigate, }) {
+    const { href, external } = resolveCtaHref(cta.url, apiBase);
+    return (_jsx(Button, { asChild: true, variant: primary ? 'default' : 'outline', size: "sm", children: _jsx("a", { href: href, onClick: onNavigate, ...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {}), "data-testid": `entitlement-cta-${primary ? 'primary' : 'secondary'}`, children: cta.label }) }));
+}
+export function EnvironmentEntitlementDialog({ state, apiBase, onOpenChange }) {
+    const spec = state.spec;
+    return (_jsx(AlertDialog, { open: state.open, onOpenChange: (open) => { if (!open)
+            onOpenChange(false); }, children: _jsxs(AlertDialogContent, { "data-testid": "environment-entitlement-dialog", children: [_jsxs(AlertDialogHeader, { children: [_jsx(AlertDialogTitle, { children: spec?.title }), _jsx(AlertDialogDescription, { children: spec?.message })] }), _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, { children: "Close" }), spec?.secondaryCta && (_jsx(CtaButton, { cta: spec.secondaryCta, apiBase: apiBase, primary: false, onNavigate: () => onOpenChange(false) })), spec?.cta && (_jsx(CtaButton, { cta: spec.cta, apiBase: apiBase, primary: true, onNavigate: () => onOpenChange(false) }))] })] }) }));
+}

package/dist/environment/EnvironmentListToolbar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * EnvironmentListToolbar — the state-aware replacement for the generic
+ * `list_toolbar` action bar on the `sys_environment` list.
+ *
+ * The cloud serves ONE `create_environment` action; born-with-env makes its
+ * meaning depend on org state (which the action metadata can't express). This
+ * component reads the resolved entitlement state and renders the right
+ * affordance:
+ *   • no production env          → "Set up your production environment" (primary);
+ *                                  the create POST provisions the org's one
+ *                                  production env — the historical-data path that
+ *                                  must never error.
+ *   • has prod + dev allowed     → "Add development environment" (the create POST
+ *                                  makes a dev env).
+ *   • has prod + dev NOT allowed → "Add environment" that opens an UPGRADE prompt
+ *                                  instead of POST-ing into a 403.
+ *   • still resolving / unknown  → the action's default label (neutral), with the
+ *                                  apiHandler entitlement dialog as the safety net.
+ *
+ * Create flows reuse the standard `action:bar` runner (name modal → apiHandler),
+ * so only the label/variant changes — no duplicate POST logic here.
+ */
+import { type EntitlementDialogSpec, type EnvironmentEntitlementsState } from './entitlements';
+interface Props {
+    /** Toolbar actions already localized by the caller (ObjectView). */
+    actions: any[];
+    /** Resolved entitlement state, or null while still loading. */
+    entitlements: EnvironmentEntitlementsState | null;
+    /** Open the shared entitlement dialog (proactive upgrade prompt). */
+    onUpgrade: (spec: EntitlementDialogSpec) => void;
+}
+export declare function EnvironmentListToolbar({ actions, entitlements, onUpgrade }: Props): import("react").JSX.Element | null;
+export {};

package/dist/environment/EnvironmentListToolbar.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * EnvironmentListToolbar — the state-aware replacement for the generic
+ * `list_toolbar` action bar on the `sys_environment` list.
+ *
+ * The cloud serves ONE `create_environment` action; born-with-env makes its
+ * meaning depend on org state (which the action metadata can't express). This
+ * component reads the resolved entitlement state and renders the right
+ * affordance:
+ *   • no production env          → "Set up your production environment" (primary);
+ *                                  the create POST provisions the org's one
+ *                                  production env — the historical-data path that
+ *                                  must never error.
+ *   • has prod + dev allowed     → "Add development environment" (the create POST
+ *                                  makes a dev env).
+ *   • has prod + dev NOT allowed → "Add environment" that opens an UPGRADE prompt
+ *                                  instead of POST-ing into a 403.
+ *   • still resolving / unknown  → the action's default label (neutral), with the
+ *                                  apiHandler entitlement dialog as the safety net.
+ *
+ * Create flows reuse the standard `action:bar` runner (name modal → apiHandler),
+ * so only the label/variant changes — no duplicate POST logic here.
+ */
+import { SchemaRenderer } from '@object-ui/react';
+import { Button } from '@object-ui/components';
+import { Plus } from 'lucide-react';
+import { decideEnvironmentCta, upgradeDialogSpec, } from './entitlements';
+const CREATE_ACTION = 'create_environment';
+export function EnvironmentListToolbar({ actions, entitlements, onUpgrade }) {
+    const toolbarActions = (actions || []).filter((a) => a?.locations?.includes('list_toolbar'));
+    if (toolbarActions.length === 0)
+        return null;
+    const ctaKind = entitlements?.ready ? decideEnvironmentCta(entitlements) : null;
+    // Upgrade state: a free-plan org clicking "create" must NOT POST-then-403.
+    // Render a primary button that opens the upgrade prompt, plus any other
+    // (non-create) toolbar actions through the normal bar.
+    if (ctaKind === 'upgrade_for_development') {
+        const others = toolbarActions.filter((a) => a?.name !== CREATE_ACTION);
+        return (_jsxs(_Fragment, { children: [others.length > 0 && (_jsx(SchemaRenderer, { schema: { type: 'action:bar', location: 'list_toolbar', actions: others, size: 'sm', variant: 'outline' } })), _jsxs(Button, { size: "sm", onClick: () => onUpgrade(upgradeDialogSpec(entitlements)), className: "shadow-none gap-1.5 sm:gap-2 h-8 sm:h-9", "data-testid": "environment-add-upgrade", children: [_jsx(Plus, { className: "h-4 w-4" }), _jsx("span", { children: "Add environment" })] })] }));
+    }
+    // setup_production / add_development / loading: render the bar, overriding only
+    // the create action's label (and promoting production setup to a primary CTA).
+    const renderedActions = toolbarActions.map((a) => {
+        if (a?.name !== CREATE_ACTION || ctaKind == null)
+            return a;
+        if (ctaKind === 'setup_production') {
+            return { ...a, label: 'Set up your production environment', variant: 'primary' };
+        }
+        // add_development
+        return { ...a, label: 'Add development environment' };
+    });
+    return (_jsx(SchemaRenderer, { schema: {
+            type: 'action:bar',
+            location: 'list_toolbar',
+            actions: renderedActions,
+            size: 'sm',
+            variant: 'outline',
+        } }));
+}

package/dist/environment/entitlements.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Environment entitlement logic — the React-free decision layer behind the
+ * state-aware "create environment" affordance and the entitlement-error dialog.
+ *
+ * The Console environment list (`sys_environment`) renders a single
+ * `create_environment` toolbar action. Whether that should read "Set up your
+ * production environment", "Add development environment", or open an upgrade
+ * prompt depends on org state the action metadata can't express (does the org
+ * already own its one production env? is its plan allowed development envs?).
+ * This module turns the org-scoped capacity summary
+ * (GET /cloud/environment-entitlements) — with a row-derived fallback — into
+ * that decision, and maps the cloud env-create 403 bodies to a friendly dialog
+ * so a confused user never sees a raw red error toast.
+ *
+ * Kept dependency-free so it is trivially unit-testable.
+ */
+export type EntitlementErrorCode = 'DEV_ENV_PLAN_LOCKED' | 'DEV_ENV_LIMIT' | 'PRODUCTION_ENV_LIMIT';
+export declare function isEntitlementErrorCode(code: unknown): code is EntitlementErrorCode;
+/** A CTA link rendered in the entitlement dialog. */
+export interface EntitlementCta {
+    label: string;
+    /** Absolute (http/mailto) or a control-plane-relative path (e.g. `/settings/billing`). */
+    url: string;
+}
+/** Declarative spec the {@link EnvironmentEntitlementDialog} renders. */
+export interface EntitlementDialogSpec {
+    code: string;
+    title: string;
+    message: string;
+    /** Primary CTA (e.g. Upgrade plan). */
+    cta?: EntitlementCta;
+    /** Secondary CTA (e.g. Contact sales). */
+    secondaryCta?: EntitlementCta;
+}
+export declare const DEFAULT_UPGRADE_URL = "/settings/billing";
+/**
+ * Map a cloud env-create 403 body
+ * (`{ error, code, upgrade_url, contact_url, plan, current, limit }`) to a
+ * dialog spec. Returns `null` for any non-entitlement error so the caller falls
+ * back to its normal error handling (a red toast). This is the safety net: it
+ * fires regardless of whether the up-front state-aware presentation was right.
+ */
+export declare function entitlementDialogFromError(body: any): EntitlementDialogSpec | null;
+/** Server summary shape (GET /cloud/environment-entitlements → `data`). */
+export interface EnvironmentEntitlementsSummary {
+    plan?: string;
+    hasProductionEnv?: boolean;
+    production?: {
+        used: number;
+        limit: number;
+        canCreate: boolean;
+    };
+    development?: {
+        used: number;
+        limit: number;
+        canCreate: boolean;
+    };
+    seatCount?: number;
+    upgradeUrl?: string;
+    contactSalesUrl?: string;
+}
+/** Combined client state (authoritative summary, or a row-derived fallback). */
+export interface EnvironmentEntitlementsState {
+    /** True once a usable signal exists (summary OR derived rows). */
+    ready: boolean;
+    hasProductionEnv: boolean;
+    /** Authoritative dev-create capability; `undefined` when unknown (no summary). */
+    canCreateDevelopmentEnv?: boolean;
+    plan?: string;
+    upgradeUrl: string;
+    contactSalesUrl?: string;
+    /** Where the signal came from — telemetry + degradation note + tests. */
+    source: 'summary' | 'derived' | 'unknown';
+}
+export type EnvironmentCtaKind = 'setup_production' | 'add_development' | 'upgrade_for_development';
+/**
+ * Decide which toolbar affordance to present:
+ *   • no production env          → set up production (the create POST makes one;
+ *                                  the critical historical-data path — never errors)
+ *   • has prod + dev allowed     → add development (POST makes a dev env)
+ *   • has prod + dev NOT allowed → upgrade prompt (no POST)
+ *   • has prod + dev unknown     → add development (let the POST + dialog decide)
+ */
+export declare function decideEnvironmentCta(state: EnvironmentEntitlementsState): EnvironmentCtaKind;
+/**
+ * The proactive (pre-POST) upgrade dialog shown when a free-plan org clicks
+ * "Add environment" but development envs aren't in its plan. Mirrors the copy
+ * of the reactive DEV_ENV_PLAN_LOCKED error so both paths read identically.
+ */
+export declare function upgradeDialogSpec(state: EnvironmentEntitlementsState): EntitlementDialogSpec;

package/dist/environment/entitlements.js

@@ -0,0 +1,91 @@
+/**
+ * Environment entitlement logic — the React-free decision layer behind the
+ * state-aware "create environment" affordance and the entitlement-error dialog.
+ *
+ * The Console environment list (`sys_environment`) renders a single
+ * `create_environment` toolbar action. Whether that should read "Set up your
+ * production environment", "Add development environment", or open an upgrade
+ * prompt depends on org state the action metadata can't express (does the org
+ * already own its one production env? is its plan allowed development envs?).
+ * This module turns the org-scoped capacity summary
+ * (GET /cloud/environment-entitlements) — with a row-derived fallback — into
+ * that decision, and maps the cloud env-create 403 bodies to a friendly dialog
+ * so a confused user never sees a raw red error toast.
+ *
+ * Kept dependency-free so it is trivially unit-testable.
+ */
+const ENTITLEMENT_ERROR_CODES = new Set([
+    'DEV_ENV_PLAN_LOCKED',
+    'DEV_ENV_LIMIT',
+    'PRODUCTION_ENV_LIMIT',
+]);
+export function isEntitlementErrorCode(code) {
+    return typeof code === 'string' && ENTITLEMENT_ERROR_CODES.has(code);
+}
+export const DEFAULT_UPGRADE_URL = '/settings/billing';
+/**
+ * Map a cloud env-create 403 body
+ * (`{ error, code, upgrade_url, contact_url, plan, current, limit }`) to a
+ * dialog spec. Returns `null` for any non-entitlement error so the caller falls
+ * back to its normal error handling (a red toast). This is the safety net: it
+ * fires regardless of whether the up-front state-aware presentation was right.
+ */
+export function entitlementDialogFromError(body) {
+    const code = body?.code;
+    if (!isEntitlementErrorCode(code))
+        return null;
+    const serverMessage = typeof body?.error === 'string' && body.error ? body.error
+        : typeof body?.message === 'string' ? body.message : '';
+    const upgradeUrl = typeof body?.upgrade_url === 'string' && body.upgrade_url ? body.upgrade_url : DEFAULT_UPGRADE_URL;
+    const contactUrl = typeof body?.contact_url === 'string' && body.contact_url ? body.contact_url : '';
+    if (code === 'PRODUCTION_ENV_LIMIT') {
+        return {
+            code,
+            title: 'You already have your production environment',
+            message: serverMessage ||
+                'Each organization includes exactly one production environment. Create a separate organization for another, or contact us about an Enterprise arrangement.',
+            cta: contactUrl ? { label: 'Contact sales', url: contactUrl } : undefined,
+        };
+    }
+    // DEV_ENV_PLAN_LOCKED / DEV_ENV_LIMIT — both resolve via an upgrade CTA.
+    return {
+        code,
+        title: code === 'DEV_ENV_PLAN_LOCKED'
+            ? 'Development environments are a paid feature'
+            : 'Development environment limit reached',
+        message: serverMessage ||
+            (code === 'DEV_ENV_PLAN_LOCKED'
+                ? 'Your free plan includes one production environment. Upgrade to add development environments — build in dev, then publish to production.'
+                : 'Capacity scales with AI seats. Add an AI seat, or archive an unused development environment to free one up.'),
+        cta: { label: 'Upgrade plan', url: upgradeUrl },
+    };
+}
+/**
+ * Decide which toolbar affordance to present:
+ *   • no production env          → set up production (the create POST makes one;
+ *                                  the critical historical-data path — never errors)
+ *   • has prod + dev allowed     → add development (POST makes a dev env)
+ *   • has prod + dev NOT allowed → upgrade prompt (no POST)
+ *   • has prod + dev unknown     → add development (let the POST + dialog decide)
+ */
+export function decideEnvironmentCta(state) {
+    if (!state.hasProductionEnv)
+        return 'setup_production';
+    if (state.canCreateDevelopmentEnv === false)
+        return 'upgrade_for_development';
+    return 'add_development';
+}
+/**
+ * The proactive (pre-POST) upgrade dialog shown when a free-plan org clicks
+ * "Add environment" but development envs aren't in its plan. Mirrors the copy
+ * of the reactive DEV_ENV_PLAN_LOCKED error so both paths read identically.
+ */
+export function upgradeDialogSpec(state) {
+    const planLabel = state.plan && state.plan !== 'free' ? `your ${state.plan} plan` : 'your free plan';
+    return {
+        code: 'DEV_ENV_PLAN_LOCKED',
+        title: 'Development environments are a paid feature',
+        message: `${planLabel} includes one production environment. Upgrade to add development environments — build in dev, then publish to production.`,
+        cta: { label: 'Upgrade plan', url: state.upgradeUrl || DEFAULT_UPGRADE_URL },
+    };
+}

package/dist/environment/useEnvironmentEntitlements.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useEnvironmentEntitlements — resolve the org's environment-capacity state so
+ * the `sys_environment` list can present the right "create" affordance up front.
+ *
+ * Two signals, in priority order:
+ *   1. AUTHORITATIVE — GET /cloud/environment-entitlements (org-scoped, computed
+ *      by the same helper the create guard uses). Gives plan + dev-create
+ *      capability precisely, including the seat-scaled / subscription cases the
+ *      client can't derive from rows.
+ *   2. FALLBACK — when that endpoint is unavailable (older control plane / error),
+ *      derive `hasProductionEnv` from the org's env rows via the data API (which
+ *      is org-scoped on the control plane). This keeps the critical
+ *      "set up your production environment" path working without a backend deploy;
+ *      free-vs-paid is left unknown, and a stray create POST is caught by the
+ *      entitlement dialog safety net.
+ *
+ * Returns `null` when disabled (not the environment list) so callers can cheaply
+ * branch. Re-resolves when `refreshKey` changes (e.g. after a create).
+ */
+import { type EnvironmentEntitlementsState } from './entitlements';
+export interface UseEnvironmentEntitlementsOptions {
+    /** Only fetch when this is the environment list (objectName === 'sys_environment'). */
+    enabled: boolean;
+    dataSource: any;
+    /** Authenticated fetch (Bearer + tenant + cookies) — from the action runtime. */
+    authFetch: (url: string, init?: any) => Promise<Response>;
+    /** Control-plane origin (VITE_SERVER_URL); '' in same-origin production. */
+    apiBase: string;
+    /** Bump to re-resolve (e.g. the list's refreshKey after a successful create). */
+    refreshKey?: unknown;
+}
+export declare function useEnvironmentEntitlements(opts: UseEnvironmentEntitlementsOptions): EnvironmentEntitlementsState | null;

package/dist/environment/useEnvironmentEntitlements.js

@@ -0,0 +1,108 @@
+/**
+ * useEnvironmentEntitlements — resolve the org's environment-capacity state so
+ * the `sys_environment` list can present the right "create" affordance up front.
+ *
+ * Two signals, in priority order:
+ *   1. AUTHORITATIVE — GET /cloud/environment-entitlements (org-scoped, computed
+ *      by the same helper the create guard uses). Gives plan + dev-create
+ *      capability precisely, including the seat-scaled / subscription cases the
+ *      client can't derive from rows.
+ *   2. FALLBACK — when that endpoint is unavailable (older control plane / error),
+ *      derive `hasProductionEnv` from the org's env rows via the data API (which
+ *      is org-scoped on the control plane). This keeps the critical
+ *      "set up your production environment" path working without a backend deploy;
+ *      free-vs-paid is left unknown, and a stray create POST is caught by the
+ *      entitlement dialog safety net.
+ *
+ * Returns `null` when disabled (not the environment list) so callers can cheaply
+ * branch. Re-resolves when `refreshKey` changes (e.g. after a create).
+ */
+import { useEffect, useState } from 'react';
+import { useAuth } from '@object-ui/auth';
+import { DEFAULT_UPGRADE_URL, } from './entitlements';
+const TERMINAL_STATUSES = new Set(['archived', 'failed']);
+/** Mirror of the server `classifyEnvironmentType`: explicit type, else default→prod. */
+function classifyEnvironmentType(row) {
+    const t = String(row?.environment_type ?? '').trim().toLowerCase();
+    if (t === 'production' || t === 'prod')
+        return 'production';
+    if (t)
+        return 'development';
+    return row?.is_default === true || row?.is_default === 1 ? 'production' : 'development';
+}
+export function useEnvironmentEntitlements(opts) {
+    const { enabled, dataSource, authFetch, apiBase, refreshKey } = opts;
+    const { activeOrganization } = useAuth();
+    const orgId = activeOrganization?.id;
+    const [state, setState] = useState(null);
+    useEffect(() => {
+        if (!enabled) {
+            setState(null);
+            return;
+        }
+        let cancelled = false;
+        const fromSummary = async () => {
+            try {
+                const base = (apiBase || '').replace(/\/+$/, '');
+                const qs = orgId ? `?organizationId=${encodeURIComponent(orgId)}` : '';
+                const res = await authFetch(`${base}/api/v1/cloud/environment-entitlements${qs}`, {
+                    method: 'GET',
+                    credentials: 'include',
+                });
+                if (!res.ok)
+                    return null;
+                const json = await res.json().catch(() => null);
+                const data = (json?.data ?? json);
+                if (!data || typeof data !== 'object')
+                    return null;
+                return {
+                    ready: true,
+                    hasProductionEnv: data.hasProductionEnv === true,
+                    canCreateDevelopmentEnv: data.development?.canCreate,
+                    plan: data.plan,
+                    upgradeUrl: data.upgradeUrl || DEFAULT_UPGRADE_URL,
+                    contactSalesUrl: data.contactSalesUrl,
+                    source: 'summary',
+                };
+            }
+            catch {
+                return null;
+            }
+        };
+        const fromRows = async () => {
+            try {
+                const params = { $top: 200 };
+                if (orgId)
+                    params.$filter = { organization_id: orgId };
+                const res = await dataSource.find('sys_environment', params);
+                const rows = Array.isArray(res) ? res : res?.data ?? [];
+                const active = rows.filter((r) => !TERMINAL_STATUSES.has(String(r?.status ?? '')));
+                const hasProductionEnv = active.some((r) => classifyEnvironmentType(r) === 'production');
+                return {
+                    ready: true,
+                    hasProductionEnv,
+                    canCreateDevelopmentEnv: undefined,
+                    upgradeUrl: DEFAULT_UPGRADE_URL,
+                    source: 'derived',
+                };
+            }
+            catch {
+                return {
+                    ready: false,
+                    hasProductionEnv: false,
+                    canCreateDevelopmentEnv: undefined,
+                    upgradeUrl: DEFAULT_UPGRADE_URL,
+                    source: 'unknown',
+                };
+            }
+        };
+        (async () => {
+            const summary = await fromSummary();
+            const next = summary ?? (await fromRows());
+            if (!cancelled)
+                setState(next);
+        })();
+        return () => { cancelled = true; };
+    }, [enabled, orgId, apiBase, authFetch, dataSource, refreshKey]);
+    return state;
+}

package/dist/hooks/useActionModal.js

@@ -23,8 +23,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useCallback, useState } from 'react';
 import { Button, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, cn, } from '@object-ui/components';
-import { SchemaRenderer } from '@object-ui/react';
+import { SchemaRenderer, useMetadata } from '@object-ui/react';
 import { ModalForm } from '@object-ui/plugin-form';
+import { resolveFormViewLayout } from '../utils/recordFormNavigation';
 const SIZE_CLASS = {
     sm: 'sm:max-w-sm',
     default: 'sm:max-w-lg',
@@ -56,6 +57,10 @@ export function normalizeModalSchema(schema) {
 }
 export function useActionModal(dataSource) {
     const [state, setState] = useState(null);
+    // Object metadata — degrades to an empty list outside a MetadataProvider
+    // (see useMetadata). Used to resolve the object's default form view so the
+    // create/edit modal honors its curated sections + field selection/order.
+    const { objects } = useMetadata();
     const close = useCallback((r) => {
         setState((s) => {
             s?.resolve(r);
@@ -73,6 +78,14 @@ export function useActionModal(dataSource) {
                 close({ success: false });
         };
         if (d.objectName && !d.content) {
+            // Honor the object's default FORM VIEW (curated sections + field
+            // selection/order + master-detail subforms) unless the action descriptor
+            // passed an explicit field list. Without this the modal falls back to the
+            // raw object schema — every field, in schema order. Mirrors the global
+            // New/Edit modal in AppContent so action-opened forms stay consistent.
+            const viewLayout = (d.fields || d.sections)
+                ? {}
+                : resolveFormViewLayout(objects.find((o) => o?.name === d.objectName));
             modalElement = (_jsx(ModalForm, { schema: {
                     type: 'object-form',
                     formType: 'modal',
@@ -82,6 +95,7 @@ export function useActionModal(dataSource) {
                     title: d.title,
                     description: d.description,
                     fields: d.fields,
+                    ...viewLayout,
                     modalSize: d.size,
                     open: true,
                     onOpenChange,

package/dist/hooks/useAiSurface.d.ts

@@ -0,0 +1,59 @@
+/**
+ * useAiSurfaceEnabled
+ *
+ * Single source of truth for "should the in-UI AI surface be shown — for THIS
+ * user, on this deployment?". The console ships under MIT and is edition- and
+ * seat-agnostic at build time; it decides purely at runtime from what the
+ * server reports — no `VITE_EDITION` flag, no tree-shake.
+ *
+ * The signal is **the agent catalog** (`GET /api/v1/ai/agents`): the surface
+ * shows iff that returns >= 1 agent. The catalog is the right signal because it
+ * is the ONLY one that is BOTH edition- AND user-aware:
+ *
+ *   • The route is access-filtered server-side (ADR-0049 / ADR-0068): it returns
+ *     only the agents the CALLER may chat. A user WITHOUT the per-user AI seat
+ *     (the `ai_seat` permission) gets an EMPTY catalog -> the whole AI surface
+ *     hides for them, instead of showing a button that 403s on click. The
+ *     deployment-wide discovery `services.ai` flag CANNOT express this — it is
+ *     identical for every user — which is exactly why we do NOT gate on it.
+ *   • It is ALSO the honest edition signal: a Community-Edition runtime that
+ *     ships no `@objectstack/service-ai` registers no AI service and persists no
+ *     agents -> empty catalog -> hidden. (The old "headless service reports
+ *     available in CE" worry is moot: empty catalog hides the surface either way.)
+ *
+ * ⚠️  Do NOT "simplify" this back to `discovery.services.ai` (isAiEnabled): that
+ * reintroduces the per-user gap — seat-less users would see the FAB / links and
+ * hit 403 on click. The per-user AI-seat gate (ADR-0068) DEPENDS on this catalog
+ * signal. (This reverts objectui#1992, which dropped the per-user dimension.)
+ *
+ * The `VITE_AI_BASE_URL` opt-in flows through naturally: {@link resolveAiApiBase}
+ * points the catalog fetch at the configured server, so an external AI server
+ * with reachable agents lights the surface up and an agent-less one keeps it hidden.
+ *
+ * `isLoading` is surfaced so the `/ai` route guard can wait for the catalog to
+ * resolve before redirecting — otherwise a stale bookmark would flash a redirect
+ * to home before the fetch even starts. Entry-point buttons (FAB, top-bar link,
+ * designer "Ask AI") ignore it: staying hidden during the brief load is the
+ * correct, flash-free behaviour for a control that must not appear unless AI can
+ * actually answer.
+ *
+ * @module
+ */
+/**
+ * Resolve the AI service base URL, mirroring AiChatPage / the Home CTAs:
+ * an explicit `VITE_AI_BASE_URL` wins, otherwise `${VITE_SERVER_URL}/api/v1/ai`.
+ * Shared so every catalog fetch (route guard, layouts, Home) hits the same URL.
+ */
+export declare function resolveAiApiBase(): string;
+export interface AiSurfaceState {
+    /** True when the AI UI should render — the CALLER can reach >= 1 agent (access-filtered). */
+    enabled: boolean;
+    /** True until the agent catalog has resolved; route guards wait on this. */
+    isLoading: boolean;
+}
+/**
+ * Whether the console's AI surface (FAB, `/ai` routes, "Ask AI" affordances)
+ * should be shown FOR THE CURRENT USER, driven off the access-filtered agent
+ * catalog (empty for seat-less users -> AI hidden; ADR-0068).
+ */
+export declare function useAiSurfaceEnabled(): AiSurfaceState;

package/dist/hooks/useAiSurface.js

@@ -0,0 +1,78 @@
+/**
+ * useAiSurfaceEnabled
+ *
+ * Single source of truth for "should the in-UI AI surface be shown — for THIS
+ * user, on this deployment?". The console ships under MIT and is edition- and
+ * seat-agnostic at build time; it decides purely at runtime from what the
+ * server reports — no `VITE_EDITION` flag, no tree-shake.
+ *
+ * The signal is **the agent catalog** (`GET /api/v1/ai/agents`): the surface
+ * shows iff that returns >= 1 agent. The catalog is the right signal because it
+ * is the ONLY one that is BOTH edition- AND user-aware:
+ *
+ *   • The route is access-filtered server-side (ADR-0049 / ADR-0068): it returns
+ *     only the agents the CALLER may chat. A user WITHOUT the per-user AI seat
+ *     (the `ai_seat` permission) gets an EMPTY catalog -> the whole AI surface
+ *     hides for them, instead of showing a button that 403s on click. The
+ *     deployment-wide discovery `services.ai` flag CANNOT express this — it is
+ *     identical for every user — which is exactly why we do NOT gate on it.
+ *   • It is ALSO the honest edition signal: a Community-Edition runtime that
+ *     ships no `@objectstack/service-ai` registers no AI service and persists no
+ *     agents -> empty catalog -> hidden. (The old "headless service reports
+ *     available in CE" worry is moot: empty catalog hides the surface either way.)
+ *
+ * ⚠️  Do NOT "simplify" this back to `discovery.services.ai` (isAiEnabled): that
+ * reintroduces the per-user gap — seat-less users would see the FAB / links and
+ * hit 403 on click. The per-user AI-seat gate (ADR-0068) DEPENDS on this catalog
+ * signal. (This reverts objectui#1992, which dropped the per-user dimension.)
+ *
+ * The `VITE_AI_BASE_URL` opt-in flows through naturally: {@link resolveAiApiBase}
+ * points the catalog fetch at the configured server, so an external AI server
+ * with reachable agents lights the surface up and an agent-less one keeps it hidden.
+ *
+ * `isLoading` is surfaced so the `/ai` route guard can wait for the catalog to
+ * resolve before redirecting — otherwise a stale bookmark would flash a redirect
+ * to home before the fetch even starts. Entry-point buttons (FAB, top-bar link,
+ * designer "Ask AI") ignore it: staying hidden during the brief load is the
+ * correct, flash-free behaviour for a control that must not appear unless AI can
+ * actually answer.
+ *
+ * @module
+ */
+import { useRef } from 'react';
+import { useAgents } from '@object-ui/plugin-chatbot';
+/**
+ * Resolve the AI service base URL, mirroring AiChatPage / the Home CTAs:
+ * an explicit `VITE_AI_BASE_URL` wins, otherwise `${VITE_SERVER_URL}/api/v1/ai`.
+ * Shared so every catalog fetch (route guard, layouts, Home) hits the same URL.
+ */
+export function resolveAiApiBase() {
+    const env = import.meta.env ?? {};
+    const fromEnv = env.VITE_AI_BASE_URL;
+    if (fromEnv)
+        return fromEnv.replace(/\/$/, '');
+    const serverUrl = env.VITE_SERVER_URL ?? '';
+    return `${serverUrl.replace(/\/$/, '')}/api/v1/ai`;
+}
+/**
+ * Whether the console's AI surface (FAB, `/ai` routes, "Ask AI" affordances)
+ * should be shown FOR THE CURRENT USER, driven off the access-filtered agent
+ * catalog (empty for seat-less users -> AI hidden; ADR-0068).
+ */
+export function useAiSurfaceEnabled() {
+    const { agents, isLoading } = useAgents({ apiBase: resolveAiApiBase() });
+    // useAgents starts `isLoading=false` and only kicks off the fetch in an effect
+    // a tick later, so the first render's empty list means "not fetched yet", not
+    // "no agents". Latch whether a fetch has actually been in flight so the route
+    // guard treats that initial frame as loading (not a definitive empty → redirect).
+    const fetchStartedRef = useRef(false);
+    if (isLoading)
+        fetchStartedRef.current = true;
+    const enabled = agents.length > 0;
+    return {
+        enabled,
+        // Agents present → resolved/available. Otherwise we're loading until a fetch
+        // has both started and finished with an empty result.
+        isLoading: enabled ? false : isLoading || !fetchStartedRef.current,
+    };
+}