@frontlit/page-builder 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -2,6 +2,12 @@
 
 Block-based page builder and renderer for React. Self-contained — no backend and no framework lock-in. Themes, blocks, and the WYSIWYG builder all run client-side.
 
+**You and your agents can collaborate on the same pages.** People edit visually in the WYSIWYG builder. AI agents edit the same page data, which is plain JSON (blocks plus their settings), with no screenshots or browser automation involved. Both kinds of edit go through the same draft and publish flow, so you can review an agent's changes in the builder before they go live, and an agent can pick up where you left off.
+
+- **In FrontLit**, agents use the MCP server's page and theme tools: `list_pages`, `get_page`, `create_page`, `update_page`, `publish_page`, `discard_page_draft`, `list_themes`, `create_theme`, `update_theme` and the matching delete tools.
+- **To teach a coding agent to write good FrontLit pages**, install [frontlit-skills](https://github.com/codelitdev/frontlit-skills).
+- **In your own app**, the layout the builder emits through `onChange` is the same JSON your agent reads and writes. See [`docs/ai-editing.md`](./docs/ai-editing.md) for the planned in-builder AI editing design.
+
 Rich text editing and rendering live in [`@frontlit/text-editor`](https://www.npmjs.com/package/@frontlit/text-editor), which this package depends on and installs automatically.
 
 ## Installation
@@ -20,6 +26,8 @@ import "@frontlit/page-builder/styles.css";
 
 That file includes the utilities, default tokens, the theme-picker fonts (Inter, Playfair, and the rest), and the TipTap prose styles from `@frontlit/text-editor`. Hosts that already inject those faces via `next/font` keep working: `--font-inter` on the document still wins.
 
+**Future:** split the theme-picker faces out of `styles.css` into an opt-in `@frontlit/page-builder/fonts.css`. Hosts that already load Inter, Playfair, and the rest (for example via `next/font`) can skip that file; everyone else imports it next to `styles.css`. `--font-*` on the document and the system-font fallbacks in `theme.css` stay as they are.
+
 If the host already runs Tailwind CSS v4, you can skip `styles.css` and scan the packages instead. Import the prose sheet so rich-text lists and code blocks survive Tailwind preflight:
 
 ```css
@@ -40,7 +48,6 @@ import {
 } from "@frontlit/page-builder";
 import "@frontlit/page-builder/styles.css";
 
-
 // Read-only rendering (a published page, a marketing site, a preview):
 <PageRenderer
     layout={createDefaultLayout()}
@@ -64,7 +71,10 @@ Internal `/...` links render as native `<a>` tags by default, so the package wor
 
 ```tsx
 import Link from "next/link";
-import { PageRenderer, type PageBuilderLinkProps } from "@frontlit/page-builder";
+import {
+    PageRenderer,
+    type PageBuilderLinkProps,
+} from "@frontlit/page-builder";
 
 function AppLink(props: PageBuilderLinkProps) {
     return <Link {...props} />;
@@ -75,6 +85,28 @@ function AppLink(props: PageBuilderLinkProps) {
 
 `PageBuilder` accepts the same `linkComponent` prop and forwards it to the live preview.
 
+### Server rendering (React Server Components)
+
+`PageRenderer` is a client component. To render published pages on the server, use `ServerPageRenderer` from `@frontlit/page-builder/server`: static blocks render on the server and ship no JavaScript; only the interactive parts (mobile menu, marquee, email/support forms, copy buttons, links) are client islands.
+
+```tsx
+import { ServerPageRenderer } from "@frontlit/page-builder/server";
+import { resolveTheme } from "@frontlit/page-builder/theme";
+
+const theme = resolveTheme(themeId, themeStyle);
+
+<ServerPageRenderer layout={layout} theme={theme} pageData={pageData} />;
+```
+
+Because nothing crosses the server/client boundary as a function, it takes no callbacks. Instead:
+
+- **Links** — wrap the page in a client component that renders `PageBuilderLinkProvider` (from `@frontlit/page-builder/islands/nav-link`) with your router's link.
+- **Light/dark control** — pass a ready client element as `themeSwitcher` (e.g. one built on `@frontlit/page-builder/islands/theme-mode-switcher`); it is shown in the footer.
+- **Images** — call `setImageAttributesResolver` once at start-up to swap an image's `src`/`srcSet` for your optimizer's URLs (the sites app uses Next's `getImageProps`).
+- **Dark mode** — section backgrounds switch with the `dark` class on an ancestor, so the server needs no colour mode.
+
+The server build is separate from the main bundle (`tsup.server.config.ts`): its client islands are listed in `tsup.islands.ts`, built on their own with a `"use client"` banner, and imported — not bundled — by the server entry. A block that needs state or effects must either live in that list or be split so only its interactive part does. The block lookup used by the server renderer is `src/server/registry.ts`; keep it in step with `src/registry.ts` when adding a block.
+
 ## What's inside
 
 | Subpath                             | What it exports                                                                                                             |
@@ -87,6 +119,10 @@ function AppLink(props: PageBuilderLinkProps) {
 | `@frontlit/page-builder/renderer`   | `PageRenderer` — renders a page's `WidgetInstance[]` layout, with an `editing` mode for use inside the builder              |
 | `@frontlit/page-builder/builder`    | `PageBuilder` — the full WYSIWYG editor (add/remove/reorder blocks, edit settings, switch themes)                           |
 | `@frontlit/page-builder/data-slots` | Server-safe helper for hosts to resolve named data slots before rendering                                                   |
+| `@frontlit/page-builder/server`     | `ServerPageRenderer`, `setImageAttributesResolver` — server-component page rendering (see above)                            |
+| `@frontlit/page-builder/theme`      | `resolveTheme`, `themes`, `generateThemeStyles` — server-callable and light enough for client components                    |
+| `@frontlit/page-builder/primitives/server` | The hook-free primitives, callable from server components                                                            |
+| `@frontlit/page-builder/islands/*`  | Small client islands (`nav-link`, `theme-mode-switcher`) hosts can import without the full client bundle                    |
 
 `createDefaultLayout()` / `getDefaultTheme()` (exported from the root) build a ready-to-render starter landing page.
 

package/dist/blocks/index.d.ts

@@ -1,11 +1,11 @@
-import { b as WidgetDefaultSettings, W as Widget } from '../widget--uEOpdq3.js';
-import { M as Media } from '../media-Njv378j7.js';
-import { A as Alignment, H as HorizontalAlignment } from '../alignment-dZDzN96G.js';
+import { a as WidgetDefaultSettings, W as Widget } from '../widget-CpE2HdgU.js';
+import { M as Media } from '../media-CnLImjVC.js';
+import { T as TitleSettings, A as Alignment, a as HorizontalAlignment } from '../heading-DQCxQt38.js';
 import { TextEditorContent } from '@frontlit/text-editor';
-import { A as AspectRatio, a as ImageObjectFit } from '../image-D7GlnOio.js';
+import { A as AspectRatio, c as ImageObjectFit } from '../image-Bk8kPXwP.js';
 import 'react';
-import '../section-background-BgOCp5l3.js';
-import '../theme-style-39nxXQy0.js';
+import '../section-background-6V_LCi5e.js';
+import '../theme-style-BVd5tOsc.js';
 
 interface HeaderNavLink {
     id: string;
@@ -14,20 +14,18 @@ interface HeaderNavLink {
     isButton?: boolean;
 }
 interface HeaderSettings extends WidgetDefaultSettings {
-    logoText?: string;
-    logoImage?: string;
+    logoCorners?: number;
     links?: HeaderNavLink[];
     ctaLabel?: string;
     ctaHref?: string;
     linkAlignment?: "left" | "center" | "right";
     layout?: "fixed" | "floating" | "centered";
     backdropBlur?: boolean;
-    showThemeSwitcher?: boolean;
 }
 
 declare const Header: Widget<HeaderSettings>;
 
-interface HeroSettings extends WidgetDefaultSettings {
+interface HeroSettings extends WidgetDefaultSettings, TitleSettings {
     /** Small label rendered above the title, e.g. a section eyebrow like "Careers". */
     preTitle?: string;
     title?: string;
@@ -36,6 +34,10 @@ interface HeroSettings extends WidgetDefaultSettings {
     buttonAction?: string;
     secondaryButtonCaption?: string;
     secondaryButtonAction?: string;
+    /** Optional line of small print under the buttons, e.g. "No credit card required". */
+    smallPrint?: string;
+    /** Optional install command shown in a copyable code box under the buttons. */
+    command?: string;
     media?: Media;
     youtubeLink?: string;
     alignment?: Alignment | "right";
@@ -46,7 +48,7 @@ interface HeroSettings extends WidgetDefaultSettings {
 
 declare const Hero: Widget<HeroSettings>;
 
-interface ContentSettings extends WidgetDefaultSettings {
+interface ContentSettings extends WidgetDefaultSettings, TitleSettings {
     title?: string;
     body?: TextEditorContent;
     media?: Media;
@@ -64,7 +66,7 @@ interface FeatureItem {
     /** Name of a lucide-react icon, e.g. "Globe" or "Mail". */
     icon?: string;
 }
-interface FeaturedSettings extends WidgetDefaultSettings {
+interface FeaturedSettings extends WidgetDefaultSettings, TitleSettings {
     title?: string;
     description?: TextEditorContent;
     headerAlignment?: Alignment;
@@ -79,7 +81,7 @@ interface FaqItem {
     question: string;
     answer: string;
 }
-interface FaqSettings extends WidgetDefaultSettings {
+interface FaqSettings extends WidgetDefaultSettings, TitleSettings {
     title?: string;
     headerAlignment?: Alignment;
     items?: FaqItem[];
@@ -98,7 +100,7 @@ interface PricingTier {
     buttonAction?: string;
     highlighted?: boolean;
 }
-interface PricingSettings extends WidgetDefaultSettings {
+interface PricingSettings extends WidgetDefaultSettings, TitleSettings {
     title?: string;
     description?: TextEditorContent;
     headerAlignment?: Alignment;
@@ -108,7 +110,7 @@ interface PricingSettings extends WidgetDefaultSettings {
 
 declare const Pricing: Widget<PricingSettings>;
 
-interface BannerSettings extends WidgetDefaultSettings {
+interface BannerSettings extends WidgetDefaultSettings, TitleSettings {
     title?: string;
     description?: TextEditorContent;
     buttonCaption?: string;
@@ -121,7 +123,7 @@ interface BannerSettings extends WidgetDefaultSettings {
 
 declare const Banner: Widget<BannerSettings>;
 
-interface EmailFormSettings extends WidgetDefaultSettings {
+interface EmailFormSettings extends WidgetDefaultSettings, TitleSettings {
     title?: string;
     description?: TextEditorContent;
     buttonCaption?: string;
@@ -132,7 +134,7 @@ interface EmailFormSettings extends WidgetDefaultSettings {
 
 declare const EmailForm: Widget<EmailFormSettings>;
 
-interface SupportFormSettings extends WidgetDefaultSettings {
+interface SupportFormSettings extends WidgetDefaultSettings, TitleSettings {
     title?: string;
     description?: TextEditorContent;
     buttonCaption?: string;
@@ -153,11 +155,11 @@ interface FooterColumn {
     links: FooterLink[];
 }
 interface FooterSettings extends WidgetDefaultSettings {
-    logoText?: string;
     tagline?: string;
     columns?: FooterColumn[];
     copyrightText?: string;
     layout?: "columns" | "centered" | "minimal";
+    showThemeSwitcher?: boolean;
 }
 
 declare const Footer: Widget<FooterSettings>;
@@ -185,7 +187,7 @@ interface GridItem {
     /** Card destination. In the "overlay" layout the whole card becomes a link when this is set, even without a caption. */
     buttonAction?: string;
 }
-interface GridSettings extends WidgetDefaultSettings {
+interface GridSettings extends WidgetDefaultSettings, TitleSettings {
     title?: string;
     description?: TextEditorContent;
     headerAlignment?: Alignment;
@@ -239,12 +241,24 @@ interface EmbedSettings extends WidgetDefaultSettings {
     content?: string;
     /** Colon-separated, matching common video-embed aspect ratio labels. */
     aspectRatio?: "16:9" | "4:3" | "1:1" | "default";
-    /** Fixed height in px, used only when `aspectRatio` is "default". */
+    /** Fixed height in px for URL embeds, used only when `aspectRatio` is "default". */
     height?: number;
 }
 
 declare const Embed: Widget<EmbedSettings>;
 
+interface CodeSnippetSettings extends WidgetDefaultSettings {
+    /** The command or code to show and copy. */
+    code?: string;
+    /** Show a "$" prompt before the first line. */
+    showPrompt?: boolean;
+    /** Small line under the snippet, e.g. "macOS · Linux · Windows". */
+    caption?: string;
+    contentAlignment?: Alignment;
+}
+
+declare const CodeSnippetBlock: Widget<CodeSnippetSettings>;
+
 interface DataSlotSettings extends WidgetDefaultSettings {
     /** Name matched against the host application's data-slot loaders. */
     slot: string;
@@ -252,4 +266,4 @@ interface DataSlotSettings extends WidgetDefaultSettings {
 
 declare const DataSlot: Widget<DataSlotSettings>;
 
-export { Banner, type BannerSettings, Content, type ContentSettings, DataSlot, type DataSlotSettings, EmailForm, type EmailFormSettings, Embed, type EmbedSettings, Faq, type FaqItem, type FaqSettings, type FeatureItem, Featured, type FeaturedSettings, Footer, type FooterColumn, type FooterLink, type FooterSettings, Grid, type GridItem, type GridSettings, Header, type HeaderNavLink, type HeaderSettings, Hero, type HeroSettings, Marquee, type MarqueeItem, type MarqueeSettings, MediaBlock, type MediaSettings, Pricing, type PricingSettings, type PricingTier, RichText, type RichTextSettings, SupportForm, type SupportFormSettings };
+export { Banner, type BannerSettings, CodeSnippetBlock, type CodeSnippetSettings, Content, type ContentSettings, DataSlot, type DataSlotSettings, EmailForm, type EmailFormSettings, Embed, type EmbedSettings, Faq, type FaqItem, type FaqSettings, type FeatureItem, Featured, type FeaturedSettings, Footer, type FooterColumn, type FooterLink, type FooterSettings, Grid, type GridItem, type GridSettings, Header, type HeaderNavLink, type HeaderSettings, Hero, type HeroSettings, Marquee, type MarqueeItem, type MarqueeSettings, MediaBlock, type MediaSettings, Pricing, type PricingSettings, type PricingTier, RichText, type RichTextSettings, SupportForm, type SupportFormSettings };

package/dist/blocks/index.js

@@ -1,6 +1,7 @@
 "use client";
-export { Banner, Content, DataSlot, EmailForm, Embed, Faq, Featured, Footer, Grid, Header, Hero, Marquee, MediaBlock, Pricing, RichText, SupportForm } from '../chunk-7KIX4WAO.js';
-import '../chunk-7W6Q4WA7.js';
-import '../chunk-RBJBODQP.js';
+export { Banner, CodeSnippetBlock, Content, DataSlot, EmailForm, Embed, Faq, Featured, Footer, Grid, Header, Hero, Marquee, MediaBlock, Pricing, RichText, SupportForm } from '../chunk-K4WCLHMS.js';
+import '../chunk-36QHCIPM.js';
+import '../chunk-J7Z4UW45.js';
+import '../chunk-XU7ALPGQ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/builder/index.d.ts

@@ -1,12 +1,12 @@
 import React__default from 'react';
-import { T as Theme, S as SectionBackground } from '../section-background-BgOCp5l3.js';
-import { d as WidgetInstance, P as PageData, W as Widget } from '../widget--uEOpdq3.js';
-import { a as PageSeo } from '../page-DfVl_aHX.js';
+import { T as Theme, S as SectionBackground } from '../section-background-6V_LCi5e.js';
+import { c as WidgetInstance, P as PageData, W as Widget } from '../widget-CpE2HdgU.js';
+import { a as PageSeo } from '../page-B5Gmm-Ys.js';
 import { P as PageBuilderLinkComponent } from '../nav-link-BfxvQ1s6.js';
 import { LucideIcon } from 'lucide-react';
 import { R as ResolvedColorMode } from '../color-mode-DIEEt9WP.js';
-import { T as ThemeStyle } from '../theme-style-39nxXQy0.js';
-import '../media-Njv378j7.js';
+import { T as ThemeStyle } from '../theme-style-BVd5tOsc.js';
+import '../media-CnLImjVC.js';
 
 interface PageBuilderState {
     layout: WidgetInstance[];
@@ -30,7 +30,7 @@ interface PageBuilderProps {
         system?: Theme[];
         custom?: Theme[];
     };
-    pageData?: PageData;
+    pageData: PageData;
     onChange?: (state: PageBuilderState) => void;
     /** Whether the editor may alter team-wide theme data. */
     allowThemeEditing?: boolean;
@@ -91,15 +91,14 @@ declare function PageBuilderPropertyHeader({ label, tooltip, }: {
  * PageBuilderSlider. Uses a native range input instead of Radix Slider so it
  * adds no dependencies.
  */
-declare function PageBuilderSlider({ title, min, max, value, onChange, tooltip, className, allowsReset, unit, }: {
+declare function PageBuilderSlider({ title, min, max, value, onChange, tooltip, className, unit, }: {
     title: string;
     min: number;
     max: number;
     value: number;
-    onChange: (value?: number) => void;
+    onChange: (value: number) => void;
     tooltip?: string;
     className?: string;
-    allowsReset?: boolean;
     unit?: string;
 }): React__default.JSX.Element;
 
@@ -229,8 +228,6 @@ declare function ThemeEditor({ theme, appliedThemeId, systemThemes, customThemes
 /**
  * Page-level SEO settings panel. Like the block and theme editors, changes
  * apply live — the host app persists them via the builder's `onChange`.
- * Adapted from CourseLit's SeoEditor, minus the media library (images are
- * referenced by URL, matching the rest of this package).
  */
 declare function SeoEditor({ seo, onChange, }: {
     seo: PageSeo;

package/dist/builder/index.js

@@ -1,8 +1,10 @@
 "use client";
-export { BlockPicker, BuilderTopBar, ColorSelector, ContentPaddingSelector, MaxWidthSelector, PATTERN_PRESETS, PageBuilder, PageBuilderPropertyHeader, PageBuilderSlider, SectionBackgroundPanel, SeoEditor, SettingsPanel, ThemeEditor, VerticalPaddingSelector, getMaxWidthTWClass, getVerticalPaddingTWClass } from '../chunk-MO76KZY2.js';
-import '../chunk-SSQWYMQR.js';
-import '../chunk-7KIX4WAO.js';
-import '../chunk-7W6Q4WA7.js';
-import '../chunk-RBJBODQP.js';
+export { BlockPicker, BuilderTopBar, ColorSelector, ContentPaddingSelector, MaxWidthSelector, PATTERN_PRESETS, PageBuilder, PageBuilderPropertyHeader, PageBuilderSlider, SectionBackgroundPanel, SeoEditor, SettingsPanel, ThemeEditor, VerticalPaddingSelector, getMaxWidthTWClass, getVerticalPaddingTWClass } from '../chunk-GIKTOAQS.js';
+import '../chunk-IU4KATI2.js';
+import '../chunk-BBI7UHOA.js';
+import '../chunk-K4WCLHMS.js';
+import '../chunk-36QHCIPM.js';
+import '../chunk-J7Z4UW45.js';
+import '../chunk-XU7ALPGQ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{button-C3VrMJkr.d.ts → button-OLKN3wPf.d.ts}

@@ -1,12 +1,12 @@
 import * as React from 'react';
 import React__default from 'react';
+import { T as ThemeStyle } from './theme-style-BVd5tOsc.js';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
-import { T as ThemeStyle } from './theme-style-39nxXQy0.js';
 
 declare const buttonVariants: (props?: {
-    variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost";
-    size?: "default" | "icon" | "sm" | "lg";
+    variant?: "link" | "default" | "secondary" | "destructive" | "outline" | "ghost";
+    size?: "default" | "sm" | "lg" | "icon";
 } & class_variance_authority_types.ClassProp) => string;
 interface ButtonProps$1 extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     asChild?: boolean;