@fayz-ai/core 0.1.6

package/dist/types/plugins.d.ts

@@ -0,0 +1,314 @@
+import type React from 'react';
+import type { EntityDef } from './crud';
+import type { FeatureDeclaration, PermissionAction } from './permissions';
+export type VerticalId = 'beauty' | 'food' | 'health' | 'services' | 'retail' | 'education' | (string & {});
+export type PluginScope = 'core' | 'vertical' | 'universal' | 'addon' | 'tenant';
+export type PluginStatus = 'pending_setup' | 'active' | 'disabled' | 'removed';
+/**
+ * Scaffold type this plugin targets.
+ * Plugins can declare which scaffolds they work with.
+ * If omitted, the plugin works with all scaffold types.
+ */
+export type ScaffoldType = 'saas' | 'ecommerce' | 'landing_page' | 'website' | (string & {});
+export interface PluginPermissionRequirement {
+    feature: string;
+    action: PermissionAction;
+}
+export interface PluginNavigationEntry {
+    id?: string;
+    section: 'main' | 'secondary' | 'settings';
+    position: number;
+    label: string;
+    route: string;
+    icon?: string;
+    badge?: string | number;
+    permission?: PluginPermissionRequirement;
+}
+export interface PluginSettingsTab {
+    id: string;
+    label: string;
+    icon?: string;
+    /** Provide the component directly, or reference a registered component by id
+     *  (resolvePluginComponent resolves componentId → the component registry).
+     *  Exactly one is required. */
+    component?: React.ComponentType<unknown>;
+    componentId?: string;
+    pluginId?: string;
+    order?: number;
+    permission?: PluginPermissionRequirement;
+}
+export interface PluginRouteDefinition {
+    path: string;
+    /** Component or a registered component id — exactly one is required. */
+    component?: React.ComponentType<unknown>;
+    componentId?: string;
+    guard?: 'authenticated' | 'role' | 'public' | 'share-token';
+    roles?: string[];
+    permission?: PluginPermissionRequirement;
+    /** Render edge-to-edge with no page padding/animation wrapper (chat, kanban, canvas). */
+    fullBleed?: boolean;
+}
+export type PluginWidgetZone = 'shell.sidebar.before-nav' | 'shell.sidebar.footer' | 'shell.topbar.start' | 'shell.topbar.end' | 'page.before' | 'page.after' | 'settings.before' | 'settings.after' | 'shell.floating' | (string & {});
+export declare const WidgetZone: {
+    readonly SIDEBAR_BEFORE_NAV: "shell.sidebar.before-nav";
+    readonly SIDEBAR_FOOTER: "shell.sidebar.footer";
+    readonly TOPBAR_START: "shell.topbar.start";
+    readonly TOPBAR_END: "shell.topbar.end";
+    readonly PAGE_BEFORE: "page.before";
+    readonly PAGE_AFTER: "page.after";
+    readonly SETTINGS_BEFORE: "settings.before";
+    readonly SETTINGS_AFTER: "settings.after";
+    readonly FLOATING: "shell.floating";
+};
+export interface PluginRuntimeTenant {
+    id?: string;
+    slug?: string;
+    verticalId?: string;
+    plan?: string;
+}
+export interface PluginRuntimeUser {
+    id?: string;
+    role?: string;
+}
+export interface PluginWidgetVisibility {
+    routes?: string[];
+    excludeRoutes?: string[];
+    layouts?: string[];
+    roles?: string[];
+    plans?: string[];
+    permissions?: PluginPermissionRequirement[];
+    when?: (context: PluginRuntimeContext) => boolean;
+}
+export interface PluginRuntimeContext {
+    tenant: PluginRuntimeTenant | null;
+    user: PluginRuntimeUser | null;
+    currentPath: string;
+    matchedPath?: string;
+    layout: string;
+    hasPermission?: (req: PluginPermissionRequirement) => boolean;
+}
+export interface PluginWidgetDefinition<TConfig extends Record<string, unknown> = Record<string, unknown>> {
+    id: string;
+    zone: PluginWidgetZone;
+    /** Component or a registered component id — exactly one is required. */
+    component?: React.ComponentType<unknown>;
+    componentId?: string;
+    title?: string;
+    order?: number;
+    permission?: PluginPermissionRequirement;
+    visibility?: PluginWidgetVisibility;
+    props?: TConfig;
+}
+export type DashboardWidgetKind = 'kpi' | 'chart' | 'table' | 'onboarding' | 'custom';
+/** Surfaces a widget can appear on. 'home' = global app home; 'plugin-home' =
+ *  the owning plugin's own overview page. */
+export type DashboardSurface = 'home' | 'plugin-home';
+export interface DashboardWidgetDef<TProps extends Record<string, unknown> = Record<string, unknown>> {
+    /** Globally unique id, e.g. 'crm.kpi.total-leads'. */
+    id: string;
+    /** i18n key or plain label. */
+    title: string;
+    description?: string;
+    icon?: string;
+    /** Owning domain used to scope plugin-home vs global home. Defaults to plugin.id. */
+    domain?: string;
+    kind: DashboardWidgetKind;
+    /** Column span on the 4-col grid. Defaults by kind (kpi→1, chart→2, table→4). */
+    span?: 1 | 2 | 3 | 4;
+    /** Visible before any app/user customization. Default: true. */
+    defaultVisible?: boolean;
+    /** Default order within the surface (lower = first). */
+    defaultOrder?: number;
+    /** Surfaces this widget appears on. Default: both. */
+    surfaces?: DashboardSurface[];
+    verticalId?: VerticalId;
+    permission?: PluginPermissionRequirement;
+    /** Component or a registered component id — exactly one is required. */
+    component?: React.ComponentType<unknown>;
+    componentId?: string;
+    props?: TProps;
+}
+/** App- or user-level overrides applied on top of the registered defaults. */
+export interface DashboardLayoutConfig {
+    widgets?: Array<{
+        id: string;
+        visible?: boolean;
+        order?: number;
+        span?: number;
+    }>;
+}
+export interface ResolvedDashboardWidget extends DashboardWidgetDef {
+    /** Resolved owning domain (plugin.id when not explicitly set). */
+    domain: string;
+    order: number;
+    plugin: ResolvedPluginManifest;
+}
+/** An event a plugin emits onto the event bus — declared for platform
+ *  introspection and so the AppManifest can bind event→action as data. */
+export interface PluginEventDefinition {
+    /** Namespaced event name, e.g. 'agenda.booking.confirmed'. */
+    name: string;
+    description?: string;
+    /** JSON Schema for the payload (editor / AI / validation). */
+    payloadSchema?: Record<string, unknown>;
+}
+export interface PluginCapability {
+    id: string;
+    label: string;
+    description?: string;
+    kind?: 'page' | 'widget' | 'data' | 'integration';
+}
+export interface PluginQuickAction {
+    id: string;
+    label: string;
+    icon?: string;
+    description?: string;
+    /** Action handler — typically navigates to a view. */
+    action: () => void;
+}
+export type AIToolMode = 'read' | 'persist';
+export interface AIToolParameterProperty {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    description?: string;
+    enum?: string[];
+    items?: AIToolParameterProperty;
+    default?: unknown;
+}
+export interface AIToolParameters {
+    type: 'object';
+    properties: Record<string, AIToolParameterProperty>;
+    required?: string[];
+}
+export interface AIToolSuggestion {
+    label: string;
+    prompt?: string;
+    icon?: string;
+    verticalId?: VerticalId;
+}
+export interface PluginAITool {
+    id: string;
+    name: string;
+    description: string;
+    icon?: string;
+    mode: AIToolMode;
+    parameters?: AIToolParameters;
+    permission?: PluginPermissionRequirement;
+    suggestions?: AIToolSuggestion[];
+    category?: string;
+    tags?: string[];
+}
+export interface PluginRegistryDef {
+    id: string;
+    entity: EntityDef;
+    icon?: string;
+    description?: string;
+    display?: 'table' | 'cards' | 'tree';
+    seedData?: Record<string, unknown>[];
+    mockData?: Record<string, unknown>[];
+    readOnly?: boolean;
+}
+export interface PluginMigration {
+    id: string;
+    version: string;
+    sql: string;
+    description?: string;
+}
+export interface PluginOnboarding {
+    /** Component or a registered component id — exactly one is required. */
+    component?: React.ComponentType<{
+        onComplete: () => void;
+    }>;
+    componentId?: string;
+    title?: string;
+    description?: string;
+}
+export interface PluginManifest {
+    id: string;
+    name: string;
+    icon: string;
+    version: string;
+    /** Plugin contract version. The runtime refuses plugins built for a newer
+     *  contract than it supports (see PLUGIN_API_VERSION). Omit = legacy/compatible. */
+    apiVersion?: number;
+    description?: string;
+    scope?: PluginScope;
+    verticalId?: VerticalId;
+    /** Events this plugin emits onto the bus (declared for introspection/automation). */
+    events?: PluginEventDefinition[];
+    /** Which scaffold types this plugin targets. Omit for universal plugins. */
+    scaffolds?: ScaffoldType[];
+    tenantId?: string;
+    defaultEnabled?: boolean;
+    schema?: string;
+    dependencies?: string[];
+    navigation: PluginNavigationEntry[];
+    settings?: PluginSettingsTab[];
+    routes: PluginRouteDefinition[];
+    widgets?: PluginWidgetDefinition[];
+    /** Dashboard widgets this plugin contributes to the dashboard registry. */
+    dashboardWidgets?: DashboardWidgetDef[];
+    capabilities?: PluginCapability[];
+    aiTools?: PluginAITool[];
+    entities?: string[];
+    permissions?: string[];
+    declaredFeatures?: FeatureDeclaration[];
+    registries?: PluginRegistryDef[];
+    migrations?: PluginMigration[];
+    onboarding?: PluginOnboarding;
+    locales?: Record<string, Record<string, string>>;
+    /** Marketplace metadata for npm discovery */
+    marketplace?: {
+        category: string;
+        tags: string[];
+        author: string;
+        license: string;
+        repository?: string;
+    };
+}
+export interface TenantPluginBinding {
+    pluginId: string;
+    status: PluginStatus;
+    tenantId?: string;
+    config?: Record<string, unknown>;
+}
+export interface PluginRuntimeIssue {
+    type: 'duplicate_plugin' | 'missing_dependency' | 'circular_dependency' | 'vertical_mismatch' | 'incompatible_api_version';
+    pluginId: string;
+    dependencyId?: string;
+    message: string;
+}
+export interface ResolvedPluginManifest extends PluginManifest {
+    status: PluginStatus;
+    isActive: boolean;
+    activationReason: 'default' | 'tenant' | 'dependency' | 'inactive';
+    config: Record<string, unknown>;
+    missingDependencies: string[];
+    settingsTabs: PluginSettingsTab[];
+    widgets: PluginWidgetDefinition[];
+    resolvedRegistries: PluginRegistryDef[];
+    resolvedAITools: PluginAITool[];
+}
+export interface ResolvedPluginWidget<TConfig extends Record<string, unknown> = Record<string, unknown>> extends PluginWidgetDefinition<TConfig> {
+    order: number;
+    config: TConfig;
+    plugin: ResolvedPluginManifest;
+}
+export interface PluginRuntimeRoute extends PluginRouteDefinition {
+    plugin: ResolvedPluginManifest;
+}
+export interface PluginRuntime {
+    context: PluginRuntimeContext;
+    plugins: ResolvedPluginManifest[];
+    activePlugins: ResolvedPluginManifest[];
+    routes: PluginRuntimeRoute[];
+    navigation: PluginNavigationEntry[];
+    settingsTabs: PluginSettingsTab[];
+    widgets: ResolvedPluginWidget[];
+    dashboardWidgets: ResolvedDashboardWidget[];
+    capabilities: PluginCapability[];
+    aiTools: PluginAITool[];
+    issues: PluginRuntimeIssue[];
+    registries: Map<string, PluginRegistryDef[]>;
+    pluginFeatures: FeatureDeclaration[];
+}
+//# sourceMappingURL=plugins.d.ts.map

package/dist/types/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/types/plugins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEzE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAC3G,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAA;AAChF,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;AAE9E;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,GAAG,cAAc,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAE5F,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,gBAAgB,CAAA;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,CAAA;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,2BAA2B,CAAA;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;mCAE+B;IAC/B,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,2BAA2B,CAAA;CACzC;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,aAAa,CAAA;IAC3D,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,UAAU,CAAC,EAAE,2BAA2B,CAAA;IACxC,yFAAyF;IACzF,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,MAAM,gBAAgB,GACxB,0BAA0B,GAC1B,sBAAsB,GACtB,oBAAoB,GACpB,kBAAkB,GAClB,aAAa,GACb,YAAY,GACZ,iBAAiB,GACjB,gBAAgB,GAChB,gBAAgB,GAChB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEjB,eAAO,MAAM,UAAU;;;;;;;;;;CAUb,CAAA;AAEV,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,CAAC,EAAE,2BAA2B,EAAE,CAAA;IAC3C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAA;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAA;IAClC,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,2BAA2B,KAAK,OAAO,CAAA;CAC9D;AAED,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACvG,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,gBAAgB,CAAA;IACtB,wEAAwE;IACxE,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,2BAA2B,CAAA;IACxC,UAAU,CAAC,EAAE,sBAAsB,CAAA;IACnC,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAOD,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,QAAQ,CAAA;AAErF;6CAC6C;AAC7C,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,aAAa,CAAA;AAErD,MAAM,WAAW,kBAAkB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClG,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAA;IACV,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,mBAAmB,CAAA;IACzB,iFAAiF;IACjF,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACpB,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAC7B,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,UAAU,CAAC,EAAE,2BAA2B,CAAA;IACxC,wEAAwE;IACxE,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;IACxC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAClF;AAED,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,sBAAsB,CAAA;CAC/B;AAED;0EAC0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,aAAa,CAAA;CAClD;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sDAAsD;IACtD,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,CAAA;AAE3C,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,KAAK,CAAC,EAAE,uBAAuB,CAAA;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,CAAA;IACd,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAA;IACnD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,UAAU,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,UAAU,CAAA;IAChB,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAC7B,UAAU,CAAC,EAAE,2BAA2B,CAAA;IACxC,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;IACpC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,SAAS,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;QAAE,UAAU,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC,CAAA;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf;wFACoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,qFAAqF;IACrF,MAAM,CAAC,EAAE,qBAAqB,EAAE,CAAA;IAChC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,YAAY,EAAE,CAAA;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,UAAU,EAAE,qBAAqB,EAAE,CAAA;IACnC,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC9B,MAAM,EAAE,qBAAqB,EAAE,CAAA;IAC/B,OAAO,CAAC,EAAE,sBAAsB,EAAE,CAAA;IAClC,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,kBAAkB,EAAE,CAAA;IACvC,YAAY,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACjC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,gBAAgB,CAAC,EAAE,kBAAkB,EAAE,CAAA;IACvC,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAChC,UAAU,CAAC,EAAE,eAAe,EAAE,CAAA;IAC9B,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAChD,6CAA6C;IAC7C,WAAW,CAAC,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,EAAE,MAAM,EAAE,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;QACf,UAAU,CAAC,EAAE,MAAM,CAAA;KACpB,CAAA;CACF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EACA,kBAAkB,GAClB,oBAAoB,GACpB,qBAAqB,GACrB,mBAAmB,GACnB,0BAA0B,CAAA;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAuB,SAAQ,cAAc;IAC5D,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,OAAO,CAAA;IACjB,gBAAgB,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,UAAU,CAAA;IAClE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,YAAY,EAAE,iBAAiB,EAAE,CAAA;IACjC,OAAO,EAAE,sBAAsB,EAAE,CAAA;IACjC,kBAAkB,EAAE,iBAAiB,EAAE,CAAA;IACvC,eAAe,EAAE,YAAY,EAAE,CAAA;CAChC;AAED,MAAM,WAAW,oBAAoB,CAAC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CACrG,SAAQ,sBAAsB,CAAC,OAAO,CAAC;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,sBAAsB,CAAA;CAC/B;AAED,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,MAAM,EAAE,sBAAsB,CAAA;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,oBAAoB,CAAA;IAC7B,OAAO,EAAE,sBAAsB,EAAE,CAAA;IACjC,aAAa,EAAE,sBAAsB,EAAE,CAAA;IACvC,MAAM,EAAE,kBAAkB,EAAE,CAAA;IAC5B,UAAU,EAAE,qBAAqB,EAAE,CAAA;IACnC,YAAY,EAAE,iBAAiB,EAAE,CAAA;IACjC,OAAO,EAAE,oBAAoB,EAAE,CAAA;IAC/B,gBAAgB,EAAE,uBAAuB,EAAE,CAAA;IAC3C,YAAY,EAAE,gBAAgB,EAAE,CAAA;IAChC,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,MAAM,EAAE,kBAAkB,EAAE,CAAA;IAC5B,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAA;IAC5C,cAAc,EAAE,kBAAkB,EAAE,CAAA;CACrC"}

package/dist/types/theme.d.ts

@@ -0,0 +1,16 @@
+export type ThemeBrand = 'blue' | 'violet' | 'green' | 'orange' | 'red' | 'pink' | 'teal' | (string & {});
+export type ThemeRadius = 'none' | 'sm' | 'md' | 'lg' | 'full';
+export type ThemeMode = 'light' | 'dark' | 'system';
+export interface SaasTheme {
+    brand?: ThemeBrand;
+    radius?: ThemeRadius;
+    /** Custom primary color as HSL string, e.g. '220 70% 50%' */
+    primaryHsl?: string;
+    /** Custom secondary color as HSL string */
+    secondaryHsl?: string;
+}
+export interface ThemeConfig {
+    theme?: SaasTheme;
+    defaultMode?: ThemeMode;
+}
+//# sourceMappingURL=theme.d.ts.map

package/dist/types/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/types/theme.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AACzG,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAA;AAC9D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAA;AAEnD,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,WAAW,CAAC,EAAE,SAAS,CAAA;CACxB"}

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@fayz-ai/core",
+  "version": "0.1.6",
+  "description": "Fayz SDK core — data providers, entity system, plugin runtime, i18n, routing",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./data": {
+      "source": "./src/data/index.ts",
+      "types": "./dist/data/index.d.ts",
+      "import": "./dist/data/index.js",
+      "require": "./dist/data/index.cjs"
+    },
+    "./entity": {
+      "source": "./src/entity/index.ts",
+      "types": "./dist/entity/index.d.ts",
+      "import": "./dist/entity/index.js",
+      "require": "./dist/entity/index.cjs"
+    },
+    "./plugin": {
+      "source": "./src/plugin/index.ts",
+      "types": "./dist/plugin/index.d.ts",
+      "import": "./dist/plugin/index.js",
+      "require": "./dist/plugin/index.cjs"
+    },
+    "./i18n": {
+      "source": "./src/i18n/index.ts",
+      "types": "./dist/i18n/index.d.ts",
+      "import": "./dist/i18n/index.js",
+      "require": "./dist/i18n/index.cjs"
+    },
+    "./router": {
+      "source": "./src/router/index.ts",
+      "types": "./dist/router/index.d.ts",
+      "import": "./dist/router/index.js",
+      "require": "./dist/router/index.cjs"
+    },
+    "./runtime": {
+      "source": "./src/runtime/index.ts",
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "require": "./dist/runtime/index.cjs"
+    },
+    "./types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js",
+      "require": "./dist/types/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.45.0",
+    "zustand": "^4.5.0",
+    "@fayz-ai/sdk": "^0.1.5"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsup": "^8.2.0",
+    "typescript": "^5.5.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "fayz",
+    "fayz-sdk",
+    "plugin-system",
+    "data-provider",
+    "entity"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationMap --noEmit false",
+    "check:manifest": "node ./scripts/check-manifest-contract.mjs",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/app/render.tsx

@@ -0,0 +1,69 @@
+import * as React from 'react'
+import { getScaffold } from '../registry'
+import { migrateManifest, validateManifest, CURRENT_MANIFEST_VERSION } from '../manifest'
+import type { AppManifest } from '../manifest'
+
+// ---------------------------------------------------------------------------
+// defineApp / renderApp — the entry points that turn an AppManifest into a
+// running app. Scaffolds (admin, storefront, portal) self-register into the
+// scaffold registry when their package is imported, so core never depends on
+// them: a generated app imports the scaffold package(s) it needs, then calls
+// renderApp(manifest). createSaasApp / createStorefrontApp become sugar that
+// builds a manifest and hands it here.
+// ---------------------------------------------------------------------------
+
+const ManifestContext = React.createContext<AppManifest | null>(null)
+
+/** Access the active app manifest from any component under renderApp. */
+export function useManifest(): AppManifest | null {
+  return React.useContext(ManifestContext)
+}
+
+/** Stamp + validate a manifest authored in code (the sugar path). */
+export function defineApp(
+  manifest: Omit<AppManifest, 'manifestVersion'> & { manifestVersion?: number },
+): AppManifest {
+  const full = {
+    ...manifest,
+    manifestVersion: manifest.manifestVersion ?? CURRENT_MANIFEST_VERSION,
+  } as AppManifest
+  const problems = validateManifest(full)
+  if (problems.length) {
+    throw new Error(`Invalid AppManifest:\n - ${problems.join('\n - ')}`)
+  }
+  return full
+}
+
+export interface RenderAppOptions {
+  /** Which surface to mount; defaults to the first declared surface. */
+  surface?: string
+}
+
+/** Resolve, migrate and validate a manifest, then mount the scaffold for the
+ *  chosen surface. Accepts a raw object (e.g. parsed app.manifest.json). */
+export function renderApp(
+  input: AppManifest | Record<string, unknown>,
+  opts: RenderAppOptions = {},
+): React.ReactElement {
+  const manifest = migrateManifest(input as Record<string, unknown>)
+  const problems = validateManifest(manifest)
+  if (problems.length) {
+    throw new Error(`Invalid AppManifest:\n - ${problems.join('\n - ')}`)
+  }
+  const surfaceName = opts.surface ?? Object.keys(manifest.surfaces)[0]
+  const surface = surfaceName ? manifest.surfaces[surfaceName] : undefined
+  if (!surface) {
+    throw new Error(`Surface "${surfaceName}" not found in manifest.`)
+  }
+  const Scaffold = getScaffold(surface.scaffold)
+  if (!Scaffold) {
+    throw new Error(
+      `Scaffold "${surface.scaffold}" is not registered. Import the package that provides it (e.g. @fayz-ai/saas or @fayz-ai/shop) before calling renderApp.`,
+    )
+  }
+  return React.createElement(
+    ManifestContext.Provider,
+    { value: manifest },
+    React.createElement(Scaffold, { manifest, surface: surfaceName }),
+  )
+}

package/src/blocks/index.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react'
+import { getBlock } from '../registry'
+
+// ---------------------------------------------------------------------------
+// Block tree — the universal page primitive. A page (admin or storefront) is an
+// ordered tree of typed blocks. Block `type`s are resolved against the block
+// registry, so a page is pure data: `{ type, props, children }`. This
+// generalizes the storefront's HomeSection switch to every surface.
+// ---------------------------------------------------------------------------
+
+export interface BlockNode {
+  /** Registered block id, e.g. 'hero', 'products', 'kpi-grid', 'custom:foo'. */
+  type: string
+  /** Stable id for keys / editing; optional. */
+  id?: string
+  props?: Record<string, unknown>
+  children?: BlockNode[]
+}
+
+/** A block component receives its declared props plus the raw node (so a block
+ *  can render its own children via <BlockChildren>). */
+export type BlockComponentProps = Record<string, unknown> & {
+  node?: BlockNode
+  children?: React.ReactNode
+}
+
+// Rendered in place of an unresolved block type. Unknown blocks are caught
+// ahead of production by `fayz doctor` / the conformance kit, so this visible
+// marker is a development aid rather than a production concern.
+function UnknownBlock({ type }: { type: string }): React.ReactElement | null {
+  return React.createElement(
+    'div',
+    {
+      style: {
+        border: '1px dashed #c026d3',
+        color: '#a21caf',
+        padding: '8px 12px',
+        font: '12px ui-monospace, monospace',
+        borderRadius: 6,
+      },
+    },
+    `Unknown block: "${type}"`,
+  )
+}
+
+export function BlockRenderer({ node }: { node: BlockNode }): React.ReactElement | null {
+  const Comp = getBlock(node.type)
+  const childEls = node.children?.length
+    ? node.children.map((child, i) =>
+        React.createElement(BlockRenderer, { key: child.id ?? `${child.type}-${i}`, node: child }),
+      )
+    : null
+  if (!Comp) return React.createElement(UnknownBlock, { type: node.type })
+  return React.createElement(Comp, { ...(node.props ?? {}), node }, childEls)
+}
+
+/** Render an ordered list of blocks (a page body). */
+export function renderBlocks(nodes: BlockNode[]): React.ReactNode {
+  return nodes.map((node, i) =>
+    React.createElement(BlockRenderer, { key: node.id ?? `${node.type}-${i}`, node }),
+  )
+}
+
+/** Convenience for block components that render their own children. */
+export function BlockChildren({ node }: { node?: BlockNode }): React.ReactNode {
+  if (!node?.children?.length) return null
+  return renderBlocks(node.children)
+}