@zerotal/admin 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-08-29
+
+### Documented
+
+- **Every promised export is documented.** The `docs-coverage` gate reads `maturity: stable` as a
+  promise about a package's exports, and measures how much of that promise is written down. It
+  was 798 gaps across the suite; it is now zero. This package's share is covered on its own
+  pages — types named, options shapes described, and the decisions behind them recorded where
+  somebody looking for them will find them.
+
+### Changed
+
+- **INTERNAL: the panel's own page machinery is marked `@internal`.** The `make*Page` factories,
+  the page classes they produce (`ResourceListPage`, `RecordViewPage`, `ResourceFormPage`,
+  `RolesPage`, `MediaPage`, `NotificationsPage`, `ConsolePage`, …), the action and widget
+  renderers, and `AdminPanelHost`.
+
+  **Nothing is removed and nothing breaks** — they are still exported and still work. An app
+  declares a `Resource` and the panel builds these pages from it; none of them has a caller
+  outside `@zerotal/admin` or a line in the guide, because writing one was never the way to use
+  this package.
+
 ## [1.6.0] — 2026-08-15
 
 ### Fixed

package/api-surface.md

@@ -1114,38 +1114,32 @@ interface ActionContext = {
   slug: string
 }
 
-interface ActionPage = {
-  download?: (filename: string, content: string | Uint8Array, mime?: string) => unknown
-  flash: (message: string, level?: string) => unknown
-  redirect: (url: string) => {    withSuccess(message: string): unknown;}
-}
-
 interface AdminAuthConfig = {
-  authMiddleware?: MiddlewareClass[]
-  authenticateWhen?: (user: unknown) => boolean | Promise<boolean>
-  emailVerification?: {    isVerified(user: unknown): boolean;    resend(user: unknown): Promise<void> | void;}
-  enabled?: boolean
-  guestMiddleware?: MiddlewareClass[]
-  heading?: string
-  identifier?: string
-  loginPath?: string
-  passwordReset?: {    sendResetLink(email: string): Promise<boolean> | boolean;    reset(input: {        email: string;        token: string;        password: string;    }): Promise<boolean> | boolean;}
-  profilePath?: string
-  redirectTo?: string
-  remember?: boolean
-  updateProfile?: (user: unknown, data: Record<string, unknown>) => Promise<void> | void
+  authMiddleware?: MiddlewareClass[] | undefined
+  authenticateWhen?: ((user: unknown) => boolean | Promise<boolean>) | undefined
+  emailVerification?: {    isVerified(user: unknown): boolean;    resend(user: unknown): Promise<void> | void;} | undefined
+  enabled?: boolean | undefined
+  guestMiddleware?: MiddlewareClass[] | undefined
+  heading?: string | undefined
+  identifier?: string | undefined
+  loginPath?: string | undefined
+  passwordReset?: {    sendResetLink(email: string): Promise<boolean> | boolean;    reset(input: {        email: string;        token: string;        password: string;    }): Promise<boolean> | boolean;} | undefined
+  profilePath?: string | undefined
+  redirectTo?: string | undefined
+  remember?: boolean | undefined
+  updateProfile?: ((user: unknown, data: Record<string, unknown>) => Promise<void> | void) | undefined
 }
 
 interface AdminConfigShape = {
-  auth?: AdminAuthConfig
-  authorize?: AdminAuthorizer
+  auth?: AdminAuthConfig | undefined
+  authorize?: AdminAuthorizer | undefined
   brand: string
-  middleware?: MiddlewareClass[]
+  middleware?: MiddlewareClass[] | undefined
   path: string
-  plugins?: Record<string, boolean>
-  tagline?: string
-  theme?: AdminThemeConfig
-  userMenu?: UserMenu
+  plugins?: Record<string, boolean> | undefined
+  tagline?: string | undefined
+  theme?: AdminThemeConfig | undefined
+  userMenu?: UserMenu | undefined
 }
 
 interface AdminModel = {
@@ -1170,18 +1164,6 @@ interface AdminNotification = {
   title: string
 }
 
-interface AdminPanelHost = {
-  console: (contribution: ConsoleContribution) => void
-  enabled: (id: string) => boolean
-  navItem: (contribution: NavContribution) => void
-  page: (contribution: PageContribution) => void
-  renderHook: (name: string, hook: (context: RenderHookContext) => HtmlNode | string | null) => void
-  searchProvider: (provider: PanelSearchProvider) => void
-  topbarSlot: (slot: TopbarSlot) => void
-  userMenuItem: (item: UserMenuContribution) => void
-  widget: (contribution: WidgetContribution) => void
-}
-
 interface AdminPlugin = {
   id: string
   install: (panel: AdminPanelHost) => void | Promise<void>
@@ -1220,15 +1202,15 @@ interface AdminRecord = {
 }
 
 interface AdminThemeConfig = {
-  cdn?: boolean
-  noFonts?: boolean
-  stylesheet?: string
-  tokensCss?: string
+  cdn?: boolean | undefined
+  noFonts?: boolean | undefined
+  stylesheet?: string | undefined
+  tokensCss?: string | undefined
 }
 
 interface AuthRolesOptions = {
-  guard?: string
-  superusers?: string[]
+  guard?: string | undefined
+  superusers?: string[] | undefined
 }
 
 interface ChartData = {
@@ -1330,15 +1312,15 @@ interface DashboardLayoutStore = {
 }
 
 interface DatabaseMediaOptions = {
-  columns?: Partial<Record<keyof MediaItem, string>>
-  table?: string
+  columns?: Partial<Record<keyof MediaItem, string>> | undefined
+  table?: string | undefined
 }
 
 interface DatabaseNotificationOptions = {
-  limit?: number
-  notifiable?: () => Promise<unknown> | unknown
-  present?: (row: StoredNotification, data: Record<string, unknown>) => AdminNotification
-  table?: string
+  limit?: number | undefined
+  notifiable?: (() => Promise<unknown> | unknown) | undefined
+  present?: ((row: StoredNotification, data: Record<string, unknown>) => AdminNotification) | undefined
+  table?: string | undefined
 }
 
 interface EmptyState = {
@@ -1396,8 +1378,8 @@ interface HistoryEntry = {
 
 interface HistoryOptions = {
   id: unknown
-  limit?: number
-  resolveActor?: (id: number) => Promise<string | null> | string | null
+  limit?: number | undefined
+  resolveActor?: ((id: number) => Promise<string | null> | string | null) | undefined
   type: string
 }
 
@@ -1414,12 +1396,12 @@ interface ImportResult = {
 }
 
 interface ListOptions = {
-  modifyQuery?: QueryModifier
-  page?: number
-  perPage?: number
+  modifyQuery?: QueryModifier | undefined
+  page?: number | undefined
+  perPage?: number | undefined
   search?: string | undefined
   sortBy?: string | undefined
-  sortDir?: 'asc' | 'desc'
+  sortDir?: 'asc' | 'desc' | undefined
   thenSort?: readonly {    column: string;    direction: 'asc' | 'desc';}[] | undefined
   trashed?: 'with' | 'only' | undefined
 }
@@ -1492,22 +1474,6 @@ interface PageContribution = {
   title: string
 }
 
-interface PanelPage = {
-  ability: string | undefined
-  cluster?: typeof Cluster | undefined
-  navigationBadge?: (() => Promise<string | number | null> | string | number | null) | undefined
-  navigationBadgeColor?: BadgeTone | undefined
-  navigationGroup: string | undefined
-  navigationIcon: string
-  navigationLabel: string
-  navigationSort: number
-  page: PanelPageClass
-  routeParams: string[]
-  showInNavigation: boolean
-  slug: string
-  title: string
-}
-
 interface PanelSearchProvider = {
   ability: string
   icon?: string
@@ -1527,19 +1493,6 @@ interface PivotColumn = {
   label?: string
 }
 
-interface RecordPage = {
-  lastPage: number
-  page: number
-  perPage: number
-  rows: Record<string, unknown>[]
-  total: number
-}
-
-interface RenderableCell = {
-  badge?: BadgeTone | undefined
-  text: string
-}
-
 interface RenderHookContext = {
   page?: 'list' | 'record' | 'form' | 'dashboard' | undefined
   recordId?: string | undefined
@@ -1597,10 +1550,10 @@ interface StoredNotification = {
 }
 
 interface StoreMediaOptions = {
-  accept?: string[]
-  disk?: string
-  folder?: string
-  maxBytes?: number
+  accept?: string[] | undefined
+  disk?: string | undefined
+  folder?: string | undefined
+  maxBytes?: number | undefined
   provider: MediaProvider
 }
 
@@ -1663,8 +1616,6 @@ type ActionVisible = (record: AdminRecord | undefined, ctx: ActionContext) => bo
 
 type AdminAuthorizer = (ability: string) => boolean | Promise<boolean>
 
-type AdminPageClass = typeof AdminPage & (new () => AdminPage)
-
 type BadgeTone = 'default' | 'primary' | 'success' | 'muted' | 'destructive'
 
 type CalloutTone = 'default' | 'primary' | 'success' | 'warning' | 'destructive'
@@ -1675,8 +1626,6 @@ type ChartResolver = () => Promise<ChartData> | ChartData
 
 type ChartType = 'line' | 'bar' | 'doughnut' | 'pie'
 
-type ClusterClass = typeof Cluster
-
 type ColumnKind = 'text' | 'toggle' | 'select' | 'input' | 'image' | 'color' | 'icon'
 
 type Conjunction = 'and' | 'or'
@@ -1711,8 +1660,6 @@ type FormComponent = FormSection | FormTabs | Wizard | FormSplit | Callout | Pri
 
 type InfolistComponent = Section | Entry
 
-type PanelPageClass = new () => object
-
 type PrimeKind = 'text' | 'html' | 'image'
 
 type QueryModifier = (query: AdminQuery) => AdminQuery
@@ -1727,8 +1674,6 @@ type RenderHookName = 'body.start' | 'body.end' | 'sidebar.start' | 'sidebar.end
 
 type ResourceClass = typeof Resource
 
-type ResourceFormClass = new () => Form & Record<string, unknown>
-
 type StatsResolver = () => Promise<Stat[]> | Stat[]
 
 type SummaryKind = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'range'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/admin",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -32,16 +32,16 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/cache": "1.8.1",
-    "@zerotal/core": "1.8.1",
-    "@zerotal/flow": "1.8.1",
-    "@zerotal/flow-ui": "1.8.1",
-    "@zerotal/validator": "1.8.1"
+    "@zerotal/cache": "1.10.0",
+    "@zerotal/core": "1.10.0",
+    "@zerotal/flow": "1.10.0",
+    "@zerotal/flow-ui": "1.10.0",
+    "@zerotal/validator": "1.10.0"
   },
   "devDependencies": {
-    "@zerotal/orm": "1.8.1",
-    "@zerotal/auth": "1.8.1",
-    "@zerotal/queue": "1.8.1"
+    "@zerotal/orm": "1.10.0",
+    "@zerotal/auth": "1.10.0",
+    "@zerotal/queue": "1.10.0"
   },
   "peerDependencies": {
     "@zerotal/orm": "^1.0.0",

package/src/Cluster.ts

@@ -46,5 +46,9 @@ export abstract class Cluster {
   }
 }
 
-/** A Cluster subclass (used by its static surface — never instantiated). */
+/**
+ * A Cluster subclass (used by its static surface — never instantiated).
+ *
+ * @internal
+ */
 export type ClusterClass = typeof Cluster;

package/src/PanelInstance.ts

@@ -72,6 +72,8 @@ export interface NavGroup {
  * A registered custom page, normalized from either door — an {@link AdminPage}
  * subclass registered by the app, or a {@link PageContribution} pushed in by a
  * package.
+ *
+ * @internal
  */
 export interface PanelPage {
   slug: string;

package/src/Resource.ts

@@ -114,6 +114,7 @@ export interface EmptyState {
   actions?: ActionItem[];
 }
 
+/** @internal */
 export interface RecordPage {
   rows: Record<string, unknown>[];
   total: number;
@@ -123,13 +124,13 @@ export interface RecordPage {
 }
 
 export interface ListOptions {
-  page?: number;
-  perPage?: number;
+  page?: number | undefined;
+  perPage?: number | undefined;
   search?: string | undefined;
   sortBy?: string | undefined;
-  sortDir?: "asc" | "desc";
+  sortDir?: "asc" | "desc" | undefined;
   /** Scope the base query before search/sort/pagination (e.g. the active tab). */
-  modifyQuery?: QueryModifier;
+  modifyQuery?: QueryModifier | undefined;
   /** Soft-delete scope: include trashed (`with`) or only trashed (`only`). */
   trashed?: "with" | "only" | undefined;
   /**

package/src/actions/Action.ts

@@ -25,7 +25,11 @@ import { flattenFields } from "../form/index.ts";
 
 export type ActionColor = "default" | "primary" | "success" | "muted" | "destructive";
 
-/** Minimal view of the host page an action handler can drive (flash/redirect). */
+/**
+ * Minimal view of the host page an action handler can drive (flash/redirect).
+ *
+ * @internal
+ */
 export interface ActionPage {
   flash(message: string, level?: string): unknown;
   redirect(url: string): { withSuccess(message: string): unknown };

package/src/actions/render.tsx

@@ -27,7 +27,11 @@ export interface RenderActionOptions {
   args?: unknown[];
 }
 
-/** Render a single action. Link actions become `<a navigate>`, callbacks `<button>`. */
+/**
+ * Render a single action. Link actions become `<a navigate>`, callbacks `<button>`.
+ *
+ * @internal
+ */
 export function renderAction(
   a: Action,
   ctx: ActionContext,
@@ -92,6 +96,8 @@ export function renderAction(
  * Returns `null` when nothing inside is visible, so an empty menu never appears.
  * `argsFor` builds each member's handler arguments, since those carry the
  * action's own key.
+ *
+ * @internal
  */
 export function renderActionGroup(
   group: ActionGroup,
@@ -128,6 +134,8 @@ export function renderActionGroup(
 /**
  * Render an action as a full-width dropdown menu row (icon + label). Used by the
  * row-action overflow menu when a row has more actions than fit inline.
+ *
+ * @internal
  */
 export function renderActionMenuItem(
   a: Action,

package/src/auth/AuthLayout.tsx

@@ -7,6 +7,7 @@ import type { HtmlNode } from "@zerotal/flow";
 import { Panel } from "../Panel.ts";
 import { adminHead } from "../theme.ts";
 
+/** @internal */
 export class AuthLayout extends Layout {
   static override get head(): string {
     const cfg = Panel.config();

package/src/authRoles.ts

@@ -24,7 +24,7 @@ export interface AuthRolesOptions {
    * Guard the roles belong to. Defaults to `"web"`, matching the framework's
    * own default, so most apps need not think about it.
    */
-  guard?: string;
+  guard?: string | undefined;
   /**
    * Role names that hold every permission.
    *
@@ -32,7 +32,7 @@ export interface AuthRolesOptions {
    * something the data can tell you. A superuser role is shown as holding
    * everything and cannot be edited or deleted from the panel.
    */
-  superusers?: string[];
+  superusers?: string[] | undefined;
 }
 
 /** The role surface this needs, kept structural so `auth` stays optional. */

package/src/config.ts

@@ -26,37 +26,46 @@ export interface UserMenu {
  */
 export interface AdminAuthConfig {
   /** Mount the auth pages. */
-  enabled?: boolean;
+  enabled?: boolean | undefined;
   /** Login route (relative to the panel path). Default `/login`. */
-  loginPath?: string;
+  loginPath?: string | undefined;
   /** Profile route (relative to the panel path). Default `/profile`. */
-  profilePath?: string;
+  profilePath?: string | undefined;
   /** Where to send the user after a successful login. Default the panel root. */
-  redirectTo?: string;
+  redirectTo?: string | undefined;
   /** The credential column users log in with. Default `"email"`. */
-  identifier?: string;
+  identifier?: string | undefined;
   /** Show a "remember me" checkbox. Default `true`. */
-  remember?: boolean;
+  remember?: boolean | undefined;
   /** Heading on the auth screens. Defaults to the panel brand. */
-  heading?: string;
+  heading?: string | undefined;
   /** Extra gate after the password check (e.g. "is the account active?"). */
-  authenticateWhen?: (user: unknown) => boolean | Promise<boolean>;
+  authenticateWhen?: ((user: unknown) => boolean | Promise<boolean>) | undefined;
   /** Persist profile edits (name/email). Defaults to `user.fill(data); user.save()`. */
-  updateProfile?: (user: unknown, data: Record<string, unknown>) => Promise<void> | void;
+  updateProfile?:
+    ((user: unknown, data: Record<string, unknown>) => Promise<void> | void) | undefined;
   /** Middleware guarding the guest screens (login/forgot/reset). Default none. */
-  guestMiddleware?: MiddlewareClass[];
+  guestMiddleware?: MiddlewareClass[] | undefined;
   /** Middleware guarding the profile/verify screens. Defaults to the panel guard. */
-  authMiddleware?: MiddlewareClass[];
+  authMiddleware?: MiddlewareClass[] | undefined;
   /** Password-reset broker — mounting the forgot/reset pages when provided. */
-  passwordReset?: {
-    sendResetLink(email: string): Promise<boolean> | boolean;
-    reset(input: { email: string; token: string; password: string }): Promise<boolean> | boolean;
-  };
+  passwordReset?:
+    | {
+        sendResetLink(email: string): Promise<boolean> | boolean;
+        reset(input: {
+          email: string;
+          token: string;
+          password: string;
+        }): Promise<boolean> | boolean;
+      }
+    | undefined;
   /** Email-verification hooks — mounting the verify page when provided. */
-  emailVerification?: {
-    isVerified(user: unknown): boolean;
-    resend(user: unknown): Promise<void> | void;
-  };
+  emailVerification?:
+    | {
+        isVerified(user: unknown): boolean;
+        resend(user: unknown): Promise<void> | void;
+      }
+    | undefined;
 }
 
 /** Admin panel configuration (read from `config/admin.ts`, with defaults). */
@@ -66,7 +75,7 @@ export interface AdminConfigShape {
   /** Brand name shown in the sidebar. */
   brand: string;
   /** Optional short tagline under the brand. */
-  tagline?: string;
+  tagline?: string | undefined;
   /**
    * Middleware guarding every panel route. When left empty, the panel is
    * default-denied in production-like environments (fail closed) and open only
@@ -75,13 +84,13 @@ export interface AdminConfigShape {
    * `[AuthMiddleware.with({ ... })]`. To deliberately expose it without auth,
    * pass an explicit pass-through middleware.
    */
-  middleware?: MiddlewareClass[];
+  middleware?: MiddlewareClass[] | undefined;
   /** Optional top-bar user menu (Profile / Logout / …). */
-  userMenu?: UserMenu;
+  userMenu?: UserMenu | undefined;
   /** Styling source — Tailwind Play CDN (default) or a prebuilt stylesheet. */
-  theme?: AdminThemeConfig;
+  theme?: AdminThemeConfig | undefined;
   /** Auth pages (login / profile / password-reset / email-verification). */
-  auth?: AdminAuthConfig;
+  auth?: AdminAuthConfig | undefined;
   /**
    * Decide the abilities named by pages, widgets, nav entries and search
    * providers. Set this when the app models permissions itself; leave it unset to
@@ -90,13 +99,13 @@ export interface AdminConfigShape {
    * With neither configured, every ability is denied outside a development
    * environment — a panel with no authorization wired stays closed in production.
    */
-  authorize?: AdminAuthorizer;
+  authorize?: AdminAuthorizer | undefined;
   /**
    * Switch contributing packages off by id — `{ monitor: false }` keeps the
    * monitor provider installed but drops its pages, widgets and nav entries from
    * the panel. Anything absent here is on.
    */
-  plugins?: Record<string, boolean>;
+  plugins?: Record<string, boolean> | undefined;
 }
 
 /**

package/src/databaseMedia.ts

@@ -21,9 +21,9 @@ import type { MediaItem, MediaProvider } from "./media.ts";
 
 export interface DatabaseMediaOptions {
   /** Table holding the catalogue. Defaults to `"media"`. */
-  table?: string;
+  table?: string | undefined;
   /** Map the panel's fields onto your column names. */
-  columns?: Partial<Record<keyof MediaItem, string>>;
+  columns?: Partial<Record<keyof MediaItem, string>> | undefined;
 }
 
 const DEFAULT_COLUMNS: Record<keyof MediaItem, string> = {

package/src/databaseNotifications.ts

@@ -32,21 +32,22 @@ export interface StoredNotification {
 
 export interface DatabaseNotificationOptions {
   /** Table holding the notifications. Defaults to `"notifications"`. */
-  table?: string;
+  table?: string | undefined;
   /**
    * Who the bell is showing. Defaults to the signed-in user from
    * `@zerotal/auth`; returning `null` shows nothing, which is the right answer
    * for a guest.
    */
-  notifiable?: () => Promise<unknown> | unknown;
+  notifiable?: (() => Promise<unknown> | unknown) | undefined;
   /** How many to show. Defaults to 20 — a bell is not an archive. */
-  limit?: number;
+  limit?: number | undefined;
   /**
    * Turn a stored row into what the panel renders. The default reads `title`,
    * `body`/`message`, `url`/`href` and `icon` out of the payload, which is what
    * most notifications carry.
    */
-  present?: (row: StoredNotification, data: Record<string, unknown>) => AdminNotification;
+  present?:
+    ((row: StoredNotification, data: Record<string, unknown>) => AdminNotification) | undefined;
 }
 
 /** Parse a row's JSON payload, tolerating a payload that was never JSON. */

package/src/form/ResourceForm.ts

@@ -16,6 +16,7 @@ import type { RuleBuilder, FieldRule } from "@zerotal/validator";
 import type { Field, FieldMode } from "./Field.ts";
 import { type FormComponent, flattenFields } from "./Section.ts";
 
+/** @internal */
 export type ResourceFormClass = new () => Form & Record<string, unknown>;
 
 /** @internal */

package/src/history.ts

@@ -50,9 +50,9 @@ export interface HistoryOptions {
   type: string;
   id: unknown;
   /** How many entries to show. Defaults to 25 — a record page is not an archive. */
-  limit?: number;
+  limit?: number | undefined;
   /** Turn an actor id into a name. Defaults to `#<id>`. */
-  resolveActor?: (id: number) => Promise<string | null> | string | null;
+  resolveActor?: ((id: number) => Promise<string | null> | string | null) | undefined;
 }
 
 /** Fields that change on every write and say nothing about intent. */

package/src/media.ts

@@ -220,12 +220,12 @@ export function isUpload(value: unknown): value is UploadedFileLike {
 export interface StoreMediaOptions {
   provider: MediaProvider;
   /** Disk to write to; the default disk when omitted. */
-  disk?: string;
-  folder?: string;
+  disk?: string | undefined;
+  folder?: string | undefined;
   /** Refuse anything larger, in bytes. */
-  maxBytes?: number;
+  maxBytes?: number | undefined;
   /** Accepted MIME types; anything goes when omitted. */
-  accept?: string[];
+  accept?: string[] | undefined;
 }
 
 /**

package/src/pages/AdminPage.ts

@@ -96,5 +96,7 @@ export abstract class AdminPage extends Component {
 /**
  * A concrete {@link AdminPage} subclass — the static metadata above, plus the
  * zero-argument constructor Flow builds the page with.
+ *
+ * @internal
  */
 export type AdminPageClass = typeof AdminPage & (new () => AdminPage);

package/src/pages/ConsolePage.tsx

@@ -36,6 +36,7 @@ const ALIGN: Record<string, string> = {
   end: "text-right tabular-nums",
 };
 
+/** @internal */
 export class ConsolePage extends Component {
   static layout = AdminLayout;
 
@@ -304,6 +305,8 @@ function cell(c: ConsoleColumn, row: ConsoleRow): HtmlNode | string {
  * shared class resolving itself from the route — keeps the console on a static
  * and matches how resource list pages are generated. The explicit name matters:
  * Flow's component registry is keyed by constructor name.
+ *
+ * @internal
  */
 export function makeConsolePage(
   console: ConsoleContribution,

package/src/pages/DashboardPage.tsx

@@ -253,7 +253,11 @@ export class DashboardPage extends Component {
   }
 }
 
-/** The dashboard for one panel, showing only that panel's resources and widgets. */
+/**
+ * The dashboard for one panel, showing only that panel's resources and widgets.
+ *
+ * @internal
+ */
 export function makeDashboardPage(panel: PanelInstance = Panel.default()): typeof DashboardPage {
   const Page = class extends DashboardPage {
     static override panel = panel;

package/src/pages/MediaPage.tsx

@@ -15,6 +15,7 @@ import { deleteMedia, formatSize, isImage, isUpload, mediaUrl, storeMedia } from
 /** How many files the grid shows before the "load more" step. */
 const PAGE_SIZE = 60;
 
+/** @internal */
 export class MediaPage extends Component {
   static layout = AdminLayout;
   /** The panel this page belongs to — set by each generated subclass. */
@@ -338,7 +339,11 @@ export class MediaPage extends Component {
   }
 }
 
-/** Build a MediaPage bound to one panel. */
+/**
+ * Build a MediaPage bound to one panel.
+ *
+ * @internal
+ */
 export function makeMediaPage(panel: PanelInstance = Panel.default()): typeof MediaPage {
   return class BoundMediaPage extends MediaPage {
     static override panel = panel;

package/src/pages/NotificationsPage.tsx

@@ -10,6 +10,7 @@ import { Icon } from "../ui/icons.tsx";
 import { Panel } from "../Panel.ts";
 import type { PanelInstance } from "../PanelInstance.ts";
 
+/** @internal */
 export class NotificationsPage extends Component {
   static layout = AdminLayout;
   /** The panel this page belongs to — set by each generated subclass. */
@@ -142,7 +143,11 @@ export class NotificationsPage extends Component {
   }
 }
 
-/** The notification centre for one panel, reading that panel's provider. */
+/**
+ * The notification centre for one panel, reading that panel's provider.
+ *
+ * @internal
+ */
 export function makeNotificationsPage(
   panel: PanelInstance = Panel.default(),
 ): typeof NotificationsPage {

package/src/pages/RecordViewPage.tsx

@@ -95,6 +95,7 @@ interface PivotProxy {
   all?: () => unknown;
 }
 
+/** @internal */
 export class RecordViewPage extends Component {
   static layout = AdminLayout;
   /** Set by each generated subclass. */
@@ -925,6 +926,8 @@ export class RecordViewPage extends Component {
 /**
  * Build a uniquely-named View page subclass bound to a resource — mirrors
  * {@link makeResourceListPage} so Flow keeps component identity stable.
+ *
+ * @internal
  */
 export function makeRecordViewPage(
   resource: ResourceClass,

package/src/pages/ResourceFormPage.tsx

@@ -63,7 +63,11 @@ const _formRegistry = new Map<string, FormMeta>();
 
 const formKey = (panelId: string, slug: string): string => `${panelId}:${slug}`;
 
-/** Register a resource's form config so the shared page can resolve it. */
+/**
+ * Register a resource's form config so the shared page can resolve it.
+ *
+ * @internal
+ */
 export function registerResourceForm(panelId: string, slug: string, meta: FormMeta): void {
   _formRegistry.set(formKey(panelId, slug), meta);
 }
@@ -72,6 +76,7 @@ const SPAN_CLASS = ["", "", "sm:col-span-2", "sm:col-span-3", "sm:col-span-4"];
 const INPUT_CLASS =
   "mt-1.5 block w-full rounded-lg border border-input bg-background px-3 py-2 text-sm text-foreground shadow-sm outline-none transition placeholder:text-muted-foreground focus:ring-2 focus:ring-ring focus:ring-offset-2 focus:ring-offset-background disabled:cursor-not-allowed disabled:opacity-60";
 
+/** @internal */
 export class ResourceFormPage extends Component {
   @locked slug = "";
   @locked mode: FieldMode = "create";

package/src/pages/ResourceListPage.tsx

@@ -104,6 +104,7 @@ function parseFilters(s: string): Record<string, string> {
   }
 }
 
+/** @internal */
 export class ResourceListPage extends Component {
   static layout = AdminLayout;
   /** Set by each generated subclass. */
@@ -2535,6 +2536,8 @@ export class ResourceListPage extends Component {
 /**
  * Build a uniquely-named List page subclass bound to a resource. The distinct
  * class name keeps Flow's snapshot/component identity stable per resource.
+ *
+ * @internal
  */
 export function makeResourceListPage(
   resource: ResourceClass,

package/src/pages/RolesPage.tsx

@@ -12,6 +12,7 @@ import type { PanelInstance } from "../PanelInstance.ts";
 import type { Permission, Role } from "../roles.ts";
 import { groupPermissions, panelPermissions, roleHas } from "../roles.ts";
 
+/** @internal */
 export class RolesPage extends Component {
   static layout = AdminLayout;
   /** The panel this page belongs to — set by each generated subclass. */
@@ -317,7 +318,11 @@ export class RolesPage extends Component {
   }
 }
 
-/** Build a RolesPage bound to one panel. */
+/**
+ * Build a RolesPage bound to one panel.
+ *
+ * @internal
+ */
 export function makeRolesPage(panel: PanelInstance = Panel.default()): typeof RolesPage {
   return class BoundRolesPage extends RolesPage {
     static override panel = panel;

package/src/pages/SearchPage.tsx

@@ -158,7 +158,11 @@ export class SearchPage extends Component {
   }
 }
 
-/** The search page for one panel, searching only that panel's resources. */
+/**
+ * The search page for one panel, searching only that panel's resources.
+ *
+ * @internal
+ */
 export function makeSearchPage(panel: PanelInstance = Panel.default()): typeof SearchPage {
   const Page = class extends SearchPage {
     static override panel = panel;

package/src/plugin.ts

@@ -40,6 +40,8 @@ import type { RenderHookContext } from "./renderHooks.ts";
  * over without importing anything from `@zerotal/admin`. The panel gives the page
  * its own layout when it mounts the route, so a contributed page renders only its
  * content and inherits the panel's chrome.
+ *
+ * @internal
  */
 export type PanelPageClass = new () => object;
 
@@ -245,6 +247,8 @@ export interface UserMenuContribution {
  * Contributors should declare their own minimal copy of the members they use
  * rather than importing this type, so they depend on the admin package at build
  * time not at all.
+ *
+ * @internal
  */
 export interface AdminPanelHost {
   /**

package/src/table/Column.ts

@@ -37,6 +37,7 @@ export interface SummaryResult {
   text: string;
 }
 
+/** @internal */
 export interface RenderableCell {
   /** Pre-escaped/plain text, or a badge descriptor. */
   text: string;

package/src/theme.ts

@@ -38,13 +38,13 @@ export const THEME_TOGGLE_SCRIPT = FLOW_THEME_TOGGLE_SCRIPT;
  */
 export interface AdminThemeConfig {
   /** A prebuilt stylesheet URL/path to link instead of (or alongside) the CDN. */
-  stylesheet?: string;
+  stylesheet?: string | undefined;
   /** Keep loading the Tailwind Play CDN. Defaults to `true` unless `stylesheet` is set. */
-  cdn?: boolean;
+  cdn?: boolean | undefined;
   /** Extra design-token CSS appended after the defaults (override `:root` / `.dark`). */
-  tokensCss?: string;
+  tokensCss?: string | undefined;
   /** Skip the bundled Google Fonts links (e.g. you self-host Inter). */
-  noFonts?: boolean;
+  noFonts?: boolean | undefined;
 }
 
 /** The design-token CSS (`:root` + `.dark` custom properties + base styles). */

package/src/ui/AdminLayout.tsx

@@ -15,6 +15,7 @@ import { Icon } from "./icons.tsx";
 import { Command, Toaster, Sidebar } from "@zerotal/flow-ui";
 import type { CommandItem, SidebarItem, SidebarGroup } from "@zerotal/flow-ui";
 
+/** @internal */
 export class AdminLayout extends Layout {
   /**
    * The panel this shell belongs to. The base class serves whichever panel owns
@@ -335,6 +336,8 @@ export class AdminLayout extends Layout {
  * The router keys shell persistence on the layout class name, so each panel needs
  * a class of its own: without that, navigating from one panel to another would
  * swap the content while leaving the previous panel's sidebar in place.
+ *
+ * @internal
  */
 export function makeAdminLayout(panel: PanelInstance): typeof AdminLayout {
   const cached = LAYOUTS.get(panel);

package/src/widgets/render.tsx

@@ -45,6 +45,8 @@ export function chartInitScript(configs: unknown[]): string {
  *
  * Returns `null` when there is nothing to draw, so a caller can drop the whole
  * block rather than leaving an empty gap above its table.
+ *
+ * @internal
  */
 export async function renderWidgets(
   widgets: DashboardWidget[],