@rizom/brain 0.2.0-alpha.47 → 0.2.0-alpha.48

package/dist/templates.d.ts

@@ -1,62 +1,302 @@
-import type { z } from "zod";
+import { z } from 'zod';
+import { VNode } from 'preact';
 
-export type ComponentType<P = Record<string, unknown>> = (props: P) => unknown;
-export interface RuntimeScript {
-  src: string;
-  type?: "module" | "text/javascript";
-  defer?: boolean;
+/**
+ * Progress notification for long-running operations
+ */
+interface ProgressNotification {
+    progress: number;
+    total?: number;
+    message?: string;
+    rate?: number;
+    eta?: number;
 }
-export interface TemplateInput<T = unknown> {
-  name: string;
-  schema?: z.ZodType<T>;
-  formatter?: (data: T) => string;
-  parser?: (content: string) => T;
-  component?: ComponentType<{ data: T }>;
-  runtimeScripts?: RuntimeScript[];
-}
-export interface Template<T = unknown> extends TemplateInput<T> {
-  name: string;
+/**
+ * Progress callback type
+ */
+type ProgressCallback = (notification: ProgressNotification) => Promise<void>;
+
+/**
+ * Interface for content formatters (human-editable content formatting)
+ *
+ * ContentFormatters handle bidirectional transformation between structured data
+ * and human-editable markdown templates. Unlike SchemaFormatters which are for
+ * one-way API response formatting, ContentFormatters support parsing edited
+ * content back into structured data.
+ */
+interface ContentFormatter<T = unknown> {
+    /**
+     * Format structured data into human-editable markdown
+     * @param data - The structured data to format
+     * @returns Human-editable markdown representation
+     */
+    format(data: T): string;
+    /**
+     * Parse human-editable markdown back into structured data
+     * @param content - The markdown content to parse
+     * @returns Structured data parsed from the markdown
+     * @throws Error if the content cannot be parsed
+     */
+    parse(content: string): T;
 }
-export const TemplateSchema: z.ZodSchema<Template>;
-export function createTemplate<T = unknown>(
-  input: TemplateInput<T>,
-): Template<T>;
-export function createTypedComponent<P>(
-  component: ComponentType<P>,
-): ComponentType<P>;
 
-export type OutputFormat = "html" | "markdown" | "text" | string;
-export type WebRenderer<T = unknown> = (props: {
-  data: T;
-  [key: string]: unknown;
-}) => unknown;
-export interface ViewTemplate<T = unknown> {
-  name: string;
-  schema?: z.ZodType<T>;
-  renderers?: Record<string, WebRenderer<T>>;
-  runtimeScripts?: RuntimeScript[];
+/**
+ * Component type for layouts - using Preact
+ * Returns a Preact VNode
+ */
+type ComponentType<P = unknown> = (props: P) => VNode;
+/**
+ * A runtime script that a template depends on. Site-builder collects
+ * these per route across all templates rendered on the page, dedupes
+ * by `src`, and injects them as <script> tags.
+ *
+ * Use this for non-hydration runtime scripts (background canvases,
+ * scroll observers, decorative animations) that should ONLY load on
+ * pages where the template actually renders — unlike the plugin-level
+ * head-script registration which fires on every page.
+ */
+interface RuntimeScript {
+    src: string;
+    defer?: boolean;
+    module?: boolean;
 }
-export interface ViewTemplateRegistry {
-  get<T = unknown>(name: string): ViewTemplate<T> | undefined;
-  list(): ViewTemplate[];
+/**
+ * Helper function to create a type-safe component that automatically parses props
+ * using the provided Zod schema
+ *
+ * Supports transformation between schema type and component type (e.g., enrichment)
+ * @param TSchema - Type validated by schema (e.g., with optional url/typeLabel)
+ * @param TComponent - Type expected by component (e.g., with required url/typeLabel)
+ */
+declare function createTypedComponent<TSchema, TComponent = TSchema>(schema: z.ZodType<TSchema>, component: ComponentType<TComponent>): ComponentType<unknown>;
+/**
+ * Unified template interface that bundles content generation and view rendering
+ * This is the single source of truth for what constitutes a template
+ */
+interface Template extends Omit<z.infer<typeof TemplateSchema>, "schema" | "layout" | "formatter"> {
+    schema: z.ZodSchema;
+    layout?: {
+        component?: ComponentType<unknown>;
+        fullscreen?: boolean;
+    };
+    formatter?: ContentFormatter<unknown>;
+    /**
+     * Whether to retrieve relevant entities from the knowledge base
+     * and inject them as context before AI generation. Default: false.
+     */
+    useKnowledgeContext?: boolean;
+    /**
+     * Runtime script dependencies. Loaded only on routes where this
+     * template actually renders — site-builder collects from all
+     * templates on a route, dedupes by src, and injects into <head>.
+     */
+    runtimeScripts?: RuntimeScript[];
 }
-export const ViewTemplateSchema: z.ZodSchema<ViewTemplate>;
+/**
+ * Helper to create a template with automatic component wrapping
+ *
+ * Supports transformation between schema type and component type (e.g., enrichment)
+ * @param TSchema - Type validated by schema (datasource output)
+ * @param TComponent - Type expected by component (after enrichment)
+ */
+declare function createTemplate<TSchema = unknown, TComponent = TSchema>(template: Omit<Template, "layout" | "schema"> & {
+    schema: z.ZodType<TSchema>;
+    layout?: {
+        component?: ComponentType<TComponent>;
+        fullscreen?: boolean;
+    };
+    runtimeScripts?: RuntimeScript[];
+}): Template;
+/**
+ * Template schema for validation
+ */
+declare const TemplateSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    schema: z.ZodAny;
+    basePrompt: z.ZodOptional<z.ZodString>;
+    useKnowledgeContext: z.ZodOptional<z.ZodBoolean>;
+    requiredPermission: z.ZodEnum<["anchor", "trusted", "public"]>;
+    formatter: z.ZodOptional<z.ZodAny>;
+    layout: z.ZodOptional<z.ZodObject<{
+        component: z.ZodAny;
+        fullscreen: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        component?: any;
+        fullscreen?: boolean | undefined;
+    }, {
+        component?: any;
+        fullscreen?: boolean | undefined;
+    }>>;
+    dataSourceId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    requiredPermission: "anchor" | "trusted" | "public";
+    schema?: any;
+    basePrompt?: string | undefined;
+    useKnowledgeContext?: boolean | undefined;
+    formatter?: any;
+    layout?: {
+        component?: any;
+        fullscreen?: boolean | undefined;
+    } | undefined;
+    dataSourceId?: string | undefined;
+}, {
+    name: string;
+    description: string;
+    requiredPermission: "anchor" | "trusted" | "public";
+    schema?: any;
+    basePrompt?: string | undefined;
+    useKnowledgeContext?: boolean | undefined;
+    formatter?: any;
+    layout?: {
+        component?: any;
+        fullscreen?: boolean | undefined;
+    } | undefined;
+    dataSourceId?: string | undefined;
+}>;
+type TemplateInput = z.infer<typeof TemplateSchema>;
 
-export interface SiteBuilderOptions {
-  outputDir?: string;
-  baseUrl?: string;
-  [key: string]: unknown;
+/**
+ * Site content entity types
+ */
+declare const SiteContentEntityTypeSchema: z.ZodEnum<["site-content-preview", "site-content-production"]>;
+type SiteContentEntityType = z.infer<typeof SiteContentEntityTypeSchema>;
+/**
+ * View template schema
+ */
+declare const ViewTemplateSchema: z.ZodObject<{
+    name: z.ZodString;
+    schema: z.ZodAny;
+    description: z.ZodOptional<z.ZodString>;
+    pluginId: z.ZodString;
+    renderers: z.ZodObject<{
+        web: z.ZodOptional<z.ZodUnion<[z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>, z.ZodString]>>;
+    }, "strip", z.ZodTypeAny, {
+        web?: string | ((...args: unknown[]) => unknown) | undefined;
+    }, {
+        web?: string | ((...args: unknown[]) => unknown) | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    pluginId: string;
+    renderers: {
+        web?: string | ((...args: unknown[]) => unknown) | undefined;
+    };
+    description?: string | undefined;
+    schema?: any;
+}, {
+    name: string;
+    pluginId: string;
+    renderers: {
+        web?: string | ((...args: unknown[]) => unknown) | undefined;
+    };
+    description?: string | undefined;
+    schema?: any;
+}>;
+/**
+ * Renderer types for different output formats
+ */
+type WebRenderer<T = unknown> = ComponentType<T> | string;
+/**
+ * Output format types
+ */
+type OutputFormat = "web";
+/**
+ * View template with support for multiple output formats
+ */
+interface ViewTemplate<T = unknown> {
+    name: string;
+    schema: z.ZodType<T>;
+    description?: string;
+    pluginId: string;
+    renderers: {
+        web?: WebRenderer<T>;
+    };
+    fullscreen?: boolean;
+    providerId?: string;
+    formatter?: ContentFormatter<T>;
+    /** Runtime script dependencies (see Template.runtimeScripts). */
+    runtimeScripts?: RuntimeScript[];
 }
-export interface BuildResult {
-  success: boolean;
-  outputDir?: string;
-  pages?: number;
-  errors?: string[];
+/**
+ * View template registry interface
+ */
+interface ViewTemplateRegistry {
+    get(name: string): ViewTemplate<unknown> | undefined;
+    list(): ViewTemplate<unknown>[];
+    validate(templateName: string, content: unknown): boolean;
 }
-export type SiteContentEntityType = string;
-export interface SiteBuilder {
-  build(options?: SiteBuilderOptions): Promise<BuildResult>;
+/**
+ * Site builder options
+ */
+declare const SiteBuilderOptionsSchema: z.ZodObject<{
+    enableContentGeneration: z.ZodDefault<z.ZodBoolean>;
+    outputDir: z.ZodString;
+    workingDir: z.ZodOptional<z.ZodString>;
+    environment: z.ZodDefault<z.ZodEnum<["preview", "production"]>>;
+    siteConfig: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+        title: string;
+        url?: string | undefined;
+    }, {
+        description: string;
+        title: string;
+        url?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    enableContentGeneration: boolean;
+    outputDir: string;
+    environment: "preview" | "production";
+    workingDir?: string | undefined;
+    siteConfig?: {
+        description: string;
+        title: string;
+        url?: string | undefined;
+    } | undefined;
+}, {
+    outputDir: string;
+    enableContentGeneration?: boolean | undefined;
+    workingDir?: string | undefined;
+    environment?: "preview" | "production" | undefined;
+    siteConfig?: {
+        description: string;
+        title: string;
+        url?: string | undefined;
+    } | undefined;
+}>;
+type SiteBuilderOptions = z.infer<typeof SiteBuilderOptionsSchema>;
+/**
+ * Build result schema
+ */
+declare const BuildResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    routesBuilt: z.ZodNumber;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    routesBuilt: number;
+    errors?: string[] | undefined;
+    warnings?: string[] | undefined;
+}, {
+    success: boolean;
+    routesBuilt: number;
+    errors?: string[] | undefined;
+    warnings?: string[] | undefined;
+}>;
+type BuildResult = z.infer<typeof BuildResultSchema>;
+/**
+ * Site builder interface
+ */
+interface SiteBuilder {
+    build(options: SiteBuilderOptions, progress?: ProgressCallback): Promise<BuildResult>;
 }
-export const SiteBuilderOptionsSchema: z.ZodSchema<SiteBuilderOptions>;
-export const BuildResultSchema: z.ZodSchema<BuildResult>;
-export const SiteContentEntityTypeSchema: z.ZodSchema<SiteContentEntityType>;
+
+export { BuildResultSchema, SiteBuilderOptionsSchema, SiteContentEntityTypeSchema, TemplateSchema, ViewTemplateSchema, createTemplate, createTypedComponent };
+export type { BuildResult, ComponentType, OutputFormat, RuntimeScript, SiteBuilder, SiteBuilderOptions, SiteContentEntityType, Template, TemplateInput, ViewTemplate, ViewTemplateRegistry, WebRenderer };

package/dist/themes.d.ts

@@ -1,48 +1,9 @@
 /**
- * ⚠️ TEMPORARY HAND-WRITTEN PUBLIC API SURFACE ⚠️
+ * Compose a complete theme by prepending shared base utilities.
  *
- * Public API contract for `@rizom/brain/themes`. Hand-maintained
- * as a stopgap because the auto-bundlers choke on the size and
- * edge cases of the `@brains/*` type graph. See
- * `docs/plans/external-plugin-api.md` for the replacement plan.
- *
- * **Sync rules:**
- * - When `composeTheme`'s signature changes in `@brains/theme-base`,
- *   update this file in the same commit.
- * - The runtime side (`../entries/themes.ts`) re-exports the real
- *   implementation from `@brains/theme-base`. The .js bundle
- *   produced by `scripts/build.ts` is what consumers execute.
- *   This .d.ts file is what their tsc sees.
+ * Base utilities live in @layer theme-base; theme-specific styles
+ * should use @layer theme-override to guarantee correct cascade order.
  */
+declare function composeTheme(themeCSS: string): string;
 
-/**
- * Prepend the shared base theme utilities to a raw theme CSS string
- * and return the combined result.
- *
- * The base utilities layer contains:
- *
- * - Palette tokens (`--palette-*`) for neutral colors, status colors,
- *   and universal UI signals
- * - `@theme inline` declarations that expose the semantic color
- *   tokens (`--color-brand`, `--color-bg`, `--color-text`, etc.) to
- *   Tailwind v4's JIT so utilities like `bg-brand`, `text-brand`,
- *   `border-brand`, `focus-visible:ring-brand` auto-generate
- * - Layer ordering (`@layer theme-base, theme-override`) so theme
- *   overrides cascade correctly regardless of concat order
- * - Universal gradient, status, selection, and warning utilities
- * - Prose color slots for `@tailwindcss/typography`
- *
- * The framework resolver uses this helper when it loads a raw theme
- * package or inline theme CSS. Advanced consumers can use the same
- * helper when they need a fully composed CSS string outside the
- * resolver.
- *
- * @example
- * ```ts
- * import { composeTheme } from "@rizom/brain/themes";
- * import themeCSS from "./theme.css" with { type: "text" };
- *
- * const fullThemeCSS = composeTheme(themeCSS);
- * ```
- */
-export function composeTheme(themeCSS: string): string;
+export { composeTheme };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rizom/brain",
-  "version": "0.2.0-alpha.47",
+  "version": "0.2.0-alpha.48",
   "description": "Brain runtime + CLI — scaffold, run, and manage AI brain instances",
   "type": "module",
   "bin": {
@@ -95,6 +95,8 @@
     "@brains/typescript-config": "workspace:*",
     "@brains/utils": "workspace:*",
     "@types/bun": "latest",
+    "rollup": "^4.60.2",
+    "rollup-plugin-dts": "^6.4.1",
     "typescript": "^5.3.3"
   },
   "publishConfig": {