@pylonsync/sdk 0.3.292 → 0.3.293

package/dist/studio.d.ts

@@ -0,0 +1,360 @@
+export interface BrandConfig {
+    /** Display name in the sidebar header. Defaults to manifest.name. */
+    name?: string;
+    /**
+     * Logo source. One of:
+     *   - data URL (`data:image/svg+xml;base64,...`)
+     *   - absolute URL (`https://...`)
+     *   - path served by your app (`/assets/logo.svg`)
+     *   - emoji or single grapheme rendered as a glyph (`"⚡"`)
+     * Omit to fall back to the bolt icon.
+     */
+    logo?: string;
+    /** Optional subtitle shown under the brand name (e.g. "v1.2.3"). */
+    subtitle?: string;
+}
+/** Built-in accent palettes. The Studio ships CSS variables for each. */
+export type ThemeAccent = "emerald" | "blue" | "violet" | "rose" | "amber";
+/** Initial appearance — the user can still toggle via the UI (next-themes). */
+export type ThemeAppearance = "dark" | "light" | "system";
+export interface ThemeConfig {
+    accent?: ThemeAccent;
+    appearance?: ThemeAppearance;
+    /**
+     * Override the accent's primary color with a custom hex. When set, the
+     * accent CSS variables are derived from this value instead of the
+     * built-in palette. Use sparingly — the built-in palettes are tuned for
+     * AA contrast in both dark and light.
+     */
+    primary?: string;
+}
+/** Lucide icon name (kebab-case). Validated client-side. */
+export type IconName = string;
+export interface SidebarPageItem {
+    type: "page";
+    /**
+     * Built-in page id (`overview`, `users`, `roles`, `health`, `sync`,
+     * `manifest`, `functions`, `policies`, `routes`, `settings`) OR a key
+     * registered by `studio.entry.tsx` via `defineStudioExtensions({ pages })`.
+     */
+    id: string;
+    label: string;
+    icon?: IconName;
+    /** Hide unless the current viewer is_admin. */
+    requiresAdmin?: boolean;
+    /** Hide unless the current viewer has at least one of these roles. */
+    requiresRoles?: string[];
+}
+export interface SidebarResourceItem {
+    type: "resource";
+    /** Manifest entity name. The list page is auto-generated. */
+    entity: string;
+    /** Override the sidebar label. Defaults to entity name. */
+    label?: string;
+    icon?: IconName;
+    requiresAdmin?: boolean;
+    requiresRoles?: string[];
+}
+export interface SidebarLinkItem {
+    type: "link";
+    label: string;
+    href: string;
+    icon?: IconName;
+    /** Open in a new tab. Defaults to true for absolute URLs. */
+    external?: boolean;
+}
+export interface SidebarHeadingItem {
+    type: "heading";
+    label: string;
+}
+export type SidebarItem = SidebarPageItem | SidebarResourceItem | SidebarLinkItem | SidebarHeadingItem;
+export interface SidebarSection {
+    /** Uppercase label rendered above the items. Pass empty string to omit. */
+    label: string;
+    items: SidebarItem[];
+    /** Default open state for the collapse toggle. Defaults to true. */
+    defaultOpen?: boolean;
+}
+export interface SidebarFooterCard {
+    type: "card";
+    title: string;
+    description: string;
+    /** Optional CTA at the bottom of the card. */
+    action?: {
+        label: string;
+        href: string;
+    };
+    /** Optional progress bar (0..1). Useful for "used space" cards. */
+    progress?: number;
+}
+export interface SidebarFooterCustom {
+    type: "custom";
+    /** Component id registered via `defineStudioExtensions({ layouts: { footer: { id: ... }}})`. */
+    componentId: string;
+}
+export type SidebarFooter = SidebarFooterCard | SidebarFooterCustom | null;
+export interface SidebarConfig {
+    sections: SidebarSection[];
+    footer?: SidebarFooter;
+    /** Org switcher button at the top. Pass `null` to hide. */
+    orgSwitcher?: {
+        items: {
+            id: string;
+            label: string;
+        }[];
+    } | null;
+    /** Show the collapse-to-icons toggle. Defaults to true. */
+    collapsible?: boolean;
+}
+/** Built-in cell renderer kinds. Custom renderers register an id under `componentId`. */
+export type RendererKind = "text" | "avatar" | "badge" | "date" | "link" | "boolean" | "number" | "json" | "custom";
+export interface RendererText {
+    kind: "text";
+    /** Truncate long strings to this many chars. Default 80. */
+    truncate?: number;
+    /** Render as monospace. */
+    mono?: boolean;
+}
+export interface RendererAvatar {
+    kind: "avatar";
+    /** Field on the row holding the image URL. If omitted, initials only. */
+    imageField?: string;
+    /** Field holding the secondary line under the name. */
+    subtitleField?: string;
+    /** Source field for the displayed name. Defaults to the column field. */
+    nameField?: string;
+}
+export interface RendererBadge {
+    kind: "badge";
+    /**
+     * Map of value → variant. Variants: green, red, amber, blue, gray.
+     * Unknown values render gray. Use `*` as a fallback key.
+     */
+    variants?: Record<string, "green" | "red" | "amber" | "blue" | "gray">;
+    /** Render a leading dot before the label. Defaults to true. */
+    dot?: boolean;
+}
+export interface RendererDate {
+    kind: "date";
+    /** "relative" → "3 days ago"; "absolute" → "May 3, 2026"; "iso" → raw. */
+    format?: "relative" | "absolute" | "iso";
+}
+export interface RendererLink {
+    kind: "link";
+    /**
+     * Template for the href. `{value}` and `{row.field}` are interpolated.
+     * Example: `"mailto:{value}"` or `"/users/{row.id}"`.
+     */
+    href: string;
+    external?: boolean;
+}
+export interface RendererBoolean {
+    kind: "boolean";
+    trueLabel?: string;
+    falseLabel?: string;
+}
+export interface RendererNumber {
+    kind: "number";
+    /** "decimal" | "percent" | "currency" | "bytes". Default "decimal". */
+    style?: "decimal" | "percent" | "currency" | "bytes";
+    /** ISO currency code when style="currency". */
+    currency?: string;
+    /** Locale for Intl.NumberFormat. Default browser locale. */
+    locale?: string;
+}
+export interface RendererJson {
+    kind: "json";
+    /** Truncate JSON preview length. Default 60. */
+    truncate?: number;
+}
+export interface RendererCustom {
+    kind: "custom";
+    /** Id registered via `defineStudioExtensions({ renderers: { ... } })`. */
+    componentId: string;
+}
+export type ColumnRenderer = RendererText | RendererAvatar | RendererBadge | RendererDate | RendererLink | RendererBoolean | RendererNumber | RendererJson | RendererCustom;
+export interface ColumnConfig {
+    /** Field name on the row. Supports dotted paths (`profile.name`). */
+    field: string;
+    /** Header label. Defaults to humanized field name. */
+    label?: string;
+    /** Display order in the table. Lower = earlier. Defaults to definition order. */
+    order?: number;
+    /** Hide column by default; user can toggle in the column picker. */
+    hidden?: boolean;
+    /** Server-side sort supported. */
+    sortable?: boolean;
+    /** Include in the search input's matched fields. */
+    searchable?: boolean;
+    /** Show a filter chip in the toolbar. */
+    filterable?: boolean | {
+        options?: {
+            label: string;
+            value: unknown;
+        }[];
+    };
+    /** Cell renderer config. Defaults to text. */
+    renderer?: ColumnRenderer;
+    /** Width hint (CSS, e.g. "200px" or "30%"). */
+    width?: string;
+    /** Right-align the column (good for numbers). */
+    align?: "left" | "center" | "right";
+}
+export interface BulkAction {
+    id: string;
+    label: string;
+    icon?: IconName;
+    /** Built-in action ids: "delete" | "export". Otherwise resolved against extensions. */
+    kind?: "delete" | "export" | "custom";
+    /** Confirmation dialog message. */
+    confirm?: string;
+    /** Hide unless viewer is_admin. */
+    requiresAdmin?: boolean;
+}
+export interface RowAction {
+    id: string;
+    label: string;
+    icon?: IconName;
+    kind?: "delete" | "edit" | "view" | "custom";
+    confirm?: string;
+    requiresAdmin?: boolean;
+}
+export interface ResourceListConfig {
+    /** Columns. If omitted, columns are inferred from the manifest entity fields. */
+    columns?: ColumnConfig[];
+    /** Search box in the toolbar. Defaults to true if any column is searchable. */
+    searchable?: boolean;
+    /** Filters dropdown in the toolbar. Defaults to true if any column is filterable. */
+    filterable?: boolean;
+    /** Bulk action menu (shown when rows are selected). */
+    bulkActions?: BulkAction[];
+    /** Per-row trailing action menu. */
+    rowActions?: RowAction[];
+    /** Default sort: field + direction. */
+    defaultSort?: {
+        field: string;
+        order: "asc" | "desc";
+    };
+    /** Page size options. Default [10, 25, 50, 100]. */
+    pageSizes?: number[];
+    /** Initial page size. Default 10. */
+    defaultPageSize?: number;
+}
+export interface ResourceConfig {
+    /** Sidebar / breadcrumb label override. Defaults to entity name. */
+    label?: string;
+    /** Plural label for headings ("Users" vs "User"). Defaults to label + "s". */
+    pluralLabel?: string;
+    icon?: IconName;
+    /** Hide from the auto-derived sidebar. The user's explicit sidebar config still wins. */
+    hidden?: boolean;
+    list?: ResourceListConfig;
+}
+export interface PageConfig {
+    /** Optional subtitle under the page header. */
+    subtitle?: string;
+    /** Custom component id (extensions). Required for non-built-in ids. */
+    componentId?: string;
+}
+export interface StudioConfig {
+    brand?: BrandConfig;
+    theme?: ThemeConfig;
+    sidebar?: SidebarConfig;
+    resources?: Record<string, ResourceConfig>;
+    pages?: Record<string, PageConfig>;
+    /**
+     * When true, the Studio will dynamic-import `/studio/extensions.js` at
+     * boot. The CLI sets this automatically when `studio.entry.tsx` is
+     * present in the project, so users rarely set it explicitly.
+     */
+    hasExtensions?: boolean;
+    /**
+     * URL to send unauthenticated callers to when they hit `/studio`.
+     * Lets a host app (Pylon Cloud, an enterprise dashboard) point the
+     * Studio gate at its own email/password login page instead of the
+     * built-in `/studio/login` admin-token form.
+     *
+     * The framework appends `?next=/studio` so the host app can redirect
+     * back after sign-in. Authenticated-but-not-admin users still see
+     * the framework's "access denied" page (no point sending them back
+     * to a login they're already past).
+     *
+     * Example: `loginUrl: "/login"` — www.pylonsync.com handles `/login`
+     * at the dashboard, and the user's existing session cookie lifts
+     * them to admin via `auth.user.adminField` on the way back.
+     */
+    loginUrl?: string;
+}
+/**
+ * Identity helper for `studio.config.ts`. Provides type checking + lets
+ * the SDK evolve the shape under one declaration. The returned object is
+ * what the CLI serializes to JSON.
+ *
+ * ```ts
+ * // studio.config.ts
+ * import { defineStudioConfig } from "@pylon/sdk";
+ * export default defineStudioConfig({
+ *   brand: { name: "Acme" },
+ *   theme: { accent: "emerald", appearance: "dark" },
+ *   sidebar: { sections: [...] },
+ *   resources: { User: { list: { columns: [...] } } },
+ * });
+ * ```
+ *
+ * The CLI's bun runner expects the file's *default export* to be the
+ * config object, OR the module to print it via `console.log`. The
+ * recommended pattern is `console.log(JSON.stringify(defineStudioConfig({...})))`
+ * — the `pylon-studio-config.mjs` shim added by `pylon dev` does this
+ * automatically when you `export default`.
+ */
+export declare function defineStudioConfig(config: StudioConfig): StudioConfig;
+/**
+ * Component shape for column renderers. The Studio passes the cell value
+ * + the full row + the column config; the renderer returns a React node.
+ *
+ * Kept as `unknown` here (rather than the actual React types) so this
+ * module stays usable from non-React contexts — `studio.config.ts`
+ * doesn't import React. The web shell narrows these to the right
+ * function signatures at registration time.
+ */
+export interface StudioCellRendererProps {
+    value: unknown;
+    row: Record<string, unknown>;
+    column: ColumnConfig;
+}
+export interface StudioPageProps {
+    /** Manifest passed to every custom page so they can introspect entities. */
+    manifest: unknown;
+    /** Auth context — `me`, `is_admin`, etc. */
+    auth: unknown;
+    /** Imperative `api()` helper, same one built-in pages use. */
+    api: <T = unknown>(path: string, opts?: unknown) => Promise<T>;
+}
+/** Registry shape — what `studio.entry.tsx` exports / registers. */
+export interface StudioExtensions {
+    renderers?: Record<string, unknown>;
+    pages?: Record<string, unknown>;
+    layouts?: {
+        footer?: unknown;
+        headerActions?: unknown;
+    };
+}
+/**
+ * Identity helper for `studio.entry.tsx`. The user passes their component
+ * map and exports the result as default. The Studio shell imports the
+ * bundle and reads either `default` or the `registerStudioExtensions`
+ * global, whichever the user used.
+ *
+ * ```tsx
+ * // studio.entry.tsx
+ * import { defineStudioExtensions } from "@pylon/sdk";
+ * import { CurrencyCell } from "./renderers/currency";
+ * import { Dashboard } from "./pages/dashboard";
+ *
+ * export default defineStudioExtensions({
+ *   renderers: { currency: CurrencyCell },
+ *   pages: { dashboard: Dashboard },
+ * });
+ * ```
+ */
+export declare function defineStudioExtensions(ext: StudioExtensions): StudioExtensions;

package/package.json

@@ -3,12 +3,17 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.292",
+  "version": "0.3.293",
   "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "tsc -p tsconfig.json --noEmit",
-    "check": "tsc -p tsconfig.json --noEmit"
-  }
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepack": "bun run build"
+  },
+  "files": [
+    "src",
+    "dist"
+  ]
 }

package/src/index.ts

@@ -665,6 +665,39 @@ export interface ManifestCron {
   description?: string;
 }
 
+/** A self-hosted web font. Declared via `font({...})`; at build the runtime
+ *  fetches the family from Google Fonts, self-hosts the woff2 same-origin,
+ *  generates `@font-face` + a size-adjusted fallback face (zero layout shift),
+ *  and auto-injects the preload + faces into every SSR page's `<head>`. The app
+ *  references the font through the CSS `variable`. */
+export interface ManifestFont {
+  /** Google Fonts family name, e.g. "Geist" or "Inter". */
+  family: string;
+  /** CSS custom property the app uses to apply the font, e.g. "--font-geist".
+   *  Set `font-family: var(--font-geist)` (it resolves to the family + the
+   *  size-adjusted fallback + your `fallback` stack). */
+  variable: string;
+  /** Weights to load — specific (`["400","500","700"]`) or a CSS2 range
+   *  (`["300..700"]`). Defaults to `["400"]`. */
+  weights?: string[];
+  /** Styles to load. Defaults to `["normal"]`. */
+  styles?: ("normal" | "italic")[];
+  /** Unicode subsets, e.g. `["latin"]`. Defaults to `["latin"]`. */
+  subsets?: string[];
+  /** CSS `font-display`. Defaults to `"swap"`. */
+  display?: "auto" | "block" | "swap" | "fallback" | "optional";
+  /** Emit `<link rel="preload">` for the font files so the browser fetches
+   *  them early. Defaults to `true`. */
+  preload?: boolean;
+  /** Fallback stack appended after the family + the adjusted fallback face,
+   *  e.g. `["system-ui", "sans-serif"]`. Defaults to `["sans-serif"]`. */
+  fallback?: string[];
+  /** Generate a size-adjusted fallback `@font-face` (matching x-height +
+   *  metrics) so there's no layout shift when the web font swaps in. Defaults
+   *  to `true`. Serialized snake_case to match the kernel manifest wire shape. */
+  adjust_font_fallback?: boolean;
+}
+
 export interface AppManifest {
   manifest_version: number;
   name: string;
@@ -682,6 +715,9 @@ export interface AppManifest {
   connections?: ManifestConnection[];
   /** Recurring jobs — run a function on a cron schedule. */
   crons?: ManifestCron[];
+  /** Self-hosted web fonts. Fetched + self-hosted at build; preload +
+   *  `@font-face` auto-injected into the SSR `<head>`. */
+  fonts?: ManifestFont[];
 }
 
 /**
@@ -725,6 +761,49 @@ export function cron(
   };
 }
 
+/**
+ * Declare a self-hosted web font (Google Fonts). At build, Pylon fetches the
+ * family, self-hosts the woff2 same-origin, generates `@font-face` + a
+ * size-adjusted fallback face, and auto-injects the preload + faces into every
+ * SSR page's `<head>` — no render-blocking third-party request, no layout shift.
+ *
+ * ```ts
+ * buildManifest({
+ *   // ...
+ *   fonts: [
+ *     font({ family: "Geist", variable: "--font-sans", weights: ["300..700"], subsets: ["latin"] }),
+ *     font({ family: "Geist Mono", variable: "--font-mono", weights: ["400..600"] }),
+ *   ],
+ * });
+ * ```
+ *
+ * Then use it in CSS: `font-family: var(--font-sans);` (resolves to the family,
+ * the zero-CLS fallback, then your `fallback` stack).
+ */
+export function font(opts: {
+  family: string;
+  variable: string;
+  weights?: string[];
+  styles?: ("normal" | "italic")[];
+  subsets?: string[];
+  display?: "auto" | "block" | "swap" | "fallback" | "optional";
+  preload?: boolean;
+  fallback?: string[];
+  adjustFontFallback?: boolean;
+}): ManifestFont {
+  return {
+    family: opts.family,
+    variable: opts.variable,
+    weights: opts.weights ?? ["400"],
+    styles: opts.styles ?? ["normal"],
+    subsets: opts.subsets ?? ["latin"],
+    display: opts.display ?? "swap",
+    preload: opts.preload ?? true,
+    ...(opts.fallback ? { fallback: opts.fallback } : {}),
+    adjust_font_fallback: opts.adjustFontFallback ?? true,
+  };
+}
+
 export function entitiesToManifest(
   entities: EntityDefinition[]
 ): ManifestEntity[] {
@@ -1411,6 +1490,7 @@ export function buildManifest(options: {
   llm?: ManifestLlmConfig;
   connections?: ManifestConnection[];
   crons?: ManifestCron[];
+  fonts?: ManifestFont[];
 }): AppManifest {
   // Pull policies attached via the fluent `e.entity().policies(...)`
   // chain onto the top-level policies list. Without this, fluent
@@ -1458,6 +1538,9 @@ export function buildManifest(options: {
     ...(options.crons && options.crons.length > 0
       ? { crons: options.crons }
       : {}),
+    ...(options.fonts && options.fonts.length > 0
+      ? { fonts: options.fonts }
+      : {}),
   };
 }
 

package/tsconfig.json

@@ -1,7 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "include": [
-    "src"
-  ]
-}
-