@opensite/ui 3.5.6 → 3.5.8

package/dist/navbar-animated-preview.cjs

@@ -1132,16 +1132,22 @@ var FeaturedCardsGridDropdown = ({
   optixFlowConfig
 }) => {
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { children: [
-    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex gap-4 pb-8", children: featuredLinks?.map((link, index) => /* @__PURE__ */ jsxRuntime.jsx(
+    featuredLinks && featuredLinks?.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex gap-4 pb-8", children: featuredLinks?.map((link, index) => /* @__PURE__ */ jsxRuntime.jsx(
       FeaturedLink,
       {
         link,
         optixFlowConfig
       },
       `desktop-featured-link-${index}`
-    )) }),
-    /* @__PURE__ */ jsxRuntime.jsx(Separator, {}),
-    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "grid grid-cols-4 pt-8", children: links?.map((link, index) => /* @__PURE__ */ jsxRuntime.jsx(NavLink, { link }, `default-nav-link-${index}`)) })
+    )) }) : null,
+    featuredLinks && featuredLinks?.length > 0 && links && links?.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx(Separator, {}) : null,
+    links && links?.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        className: `grid grid-cols-4 pt-${featuredLinks && featuredLinks?.length > 0 ? 8 : 0} gap-4`,
+        children: links?.map((link, index) => /* @__PURE__ */ jsxRuntime.jsx(NavLink, { link }, `default-nav-link-${index}`))
+      }
+    ) : null
   ] });
 };
 var GroupedLinksImageDropdown = ({

package/dist/navbar-animated-preview.d.cts

@@ -39,16 +39,16 @@ interface IMenuLink {
  */
 interface NavbarAnimatedPreviewProps {
     /**
-       * Logo configuration
-       */
+     * Logo configuration
+     */
     logo?: LogoConfig;
     /**
-       * Navigation menu links with optional dropdown groups
-       */
+     * Navigation menu links with optional dropdown groups
+     */
     menuLinks?: IMenuLink[];
     /**
-       * Action configurations (e.g., Sign In, Get Started buttons)
-       */
+     * Action configurations (e.g., Sign In, Get Started buttons)
+     */
     actions?: ActionConfig[];
 }
 interface NavbarAnimatedPreviewRuntimeProps {

package/dist/navbar-animated-preview.d.ts

@@ -39,16 +39,16 @@ interface IMenuLink {
  */
 interface NavbarAnimatedPreviewProps {
     /**
-       * Logo configuration
-       */
+     * Logo configuration
+     */
     logo?: LogoConfig;
     /**
-       * Navigation menu links with optional dropdown groups
-       */
+     * Navigation menu links with optional dropdown groups
+     */
     menuLinks?: IMenuLink[];
     /**
-       * Action configurations (e.g., Sign In, Get Started buttons)
-       */
+     * Action configurations (e.g., Sign In, Get Started buttons)
+     */
     actions?: ActionConfig[];
 }
 interface NavbarAnimatedPreviewRuntimeProps {

package/dist/navbar-animated-preview.js

@@ -1107,16 +1107,22 @@ var FeaturedCardsGridDropdown = ({
   optixFlowConfig
 }) => {
   return /* @__PURE__ */ jsxs("div", { children: [
-    /* @__PURE__ */ jsx("div", { className: "flex gap-4 pb-8", children: featuredLinks?.map((link, index) => /* @__PURE__ */ jsx(
+    featuredLinks && featuredLinks?.length > 0 ? /* @__PURE__ */ jsx("div", { className: "flex gap-4 pb-8", children: featuredLinks?.map((link, index) => /* @__PURE__ */ jsx(
       FeaturedLink,
       {
         link,
         optixFlowConfig
       },
       `desktop-featured-link-${index}`
-    )) }),
-    /* @__PURE__ */ jsx(Separator, {}),
-    /* @__PURE__ */ jsx("div", { className: "grid grid-cols-4 pt-8", children: links?.map((link, index) => /* @__PURE__ */ jsx(NavLink, { link }, `default-nav-link-${index}`)) })
+    )) }) : null,
+    featuredLinks && featuredLinks?.length > 0 && links && links?.length > 0 ? /* @__PURE__ */ jsx(Separator, {}) : null,
+    links && links?.length > 0 ? /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: `grid grid-cols-4 pt-${featuredLinks && featuredLinks?.length > 0 ? 8 : 0} gap-4`,
+        children: links?.map((link, index) => /* @__PURE__ */ jsx(NavLink, { link }, `default-nav-link-${index}`))
+      }
+    ) : null
   ] });
 };
 var GroupedLinksImageDropdown = ({

package/dist/registry.cjs

@@ -66975,16 +66975,22 @@ var FeaturedCardsGridDropdown = ({
   optixFlowConfig
 }) => {
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { children: [
-    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex gap-4 pb-8", children: featuredLinks?.map((link, index) => /* @__PURE__ */ jsxRuntime.jsx(
+    featuredLinks && featuredLinks?.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "flex gap-4 pb-8", children: featuredLinks?.map((link, index) => /* @__PURE__ */ jsxRuntime.jsx(
       FeaturedLink,
       {
         link,
         optixFlowConfig
       },
       `desktop-featured-link-${index}`
-    )) }),
-    /* @__PURE__ */ jsxRuntime.jsx(Separator, {}),
-    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "grid grid-cols-4 pt-8", children: links?.map((link, index) => /* @__PURE__ */ jsxRuntime.jsx(NavLink, { link }, `default-nav-link-${index}`)) })
+    )) }) : null,
+    featuredLinks && featuredLinks?.length > 0 && links && links?.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx(Separator, {}) : null,
+    links && links?.length > 0 ? /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        className: `grid grid-cols-4 pt-${featuredLinks && featuredLinks?.length > 0 ? 8 : 0} gap-4`,
+        children: links?.map((link, index) => /* @__PURE__ */ jsxRuntime.jsx(NavLink, { link }, `default-nav-link-${index}`))
+      }
+    ) : null
   ] });
 };
 var GroupedLinksImageDropdown = ({
@@ -112060,7 +112066,106 @@ var BLOCK_REGISTRY = {
     category: "hero",
     component: HeroMentalHealthTeam,
     props: "HeroMentalHealthTeamProps",
-    exampleUsage: `<HeroMentalHealthTeam />`.trim()
+    exampleUsage: `
+<HeroMentalHealthTeam
+  heading="Compassionate care for your mental wellbeing"
+  description="Our team of experienced mental health professionals is dedicated to providing compassionate care and support to individuals in need."
+  smallImages={[
+    { src: "/images/team-1.jpg", alt: "Dr. Smith" },
+    { src: "/images/team-2.jpg", alt: "Dr. Johnson" },
+  ]}
+  testimonial={{
+    quote:
+      "The support I received changed my life. I'm so grateful for the compassionate care.",
+    author: "Sarah M.",
+    role: "Client",
+    avatarSrc: "/images/avatar.jpg",
+  }}
+  featureImage={{ src: "/images/feature.jpg", alt: "Mental health support" }}
+  actions={[
+    { label: "Get Started", href: "#", variant: "default" },
+    { label: "Talk to Sales", href: "#", variant: "outline" },
+  ]}
+  background="gray"
+/>
+    `.trim(),
+    importantUsageNotes: "Only use if you have a valid testimonial - DO NOT MAKE UP A TESTIMONIAL/REVIEW. Supply exactly 2 images to the 'smallImages' prop and ensure you supply a 'featureImage' prop object. Do not exceed 40 characters for the 'heading' prop. Do not exceed 130 characters for the 'description' prop. If you supply multiple 'actions', ensure to use a variant of 'default' for the first action, and 'outline' for the second action to ensure proper visual distinction between the two CTAs. Follow the example props closely for this block.",
+    usageRequirements: {
+      requiredProps: ["heading", "smallImages", "featureImage", "testimonial"],
+      propConstraints: {
+        heading: { required: true, maxLength: 40 },
+        description: { maxLength: 130 },
+        smallImages: { required: true, count: 2, minItems: 2, maxItems: 2 },
+        featureImage: { required: true },
+        testimonial: {
+          required: true,
+          note: "Must be a real, sourced testimonial. Do not fabricate."
+        },
+        actions: {
+          maxItems: 2,
+          pinnedValues: {
+            "0.variant": "default",
+            "1.variant": "outline"
+          }
+        }
+      },
+      mediaSlots: {
+        featureImage: {
+          path: "featureImage",
+          roles: ["feature", "hero"],
+          disallowedRoles: ["logo", "favicon"],
+          minPixelClass: "large",
+          required: true,
+          note: "Large feature image. Must not be a logo or favicon."
+        },
+        "smallImages[]": {
+          path: "smallImages[]",
+          roles: ["thumbnail", "profile", "feature"],
+          disallowedRoles: ["logo", "favicon"],
+          minPixelClass: "small",
+          required: true,
+          note: "Two team / supporting images. Must not be logos."
+        },
+        "testimonial.avatarSrc": {
+          path: "testimonial.avatarSrc",
+          roles: ["profile", "avatar"],
+          disallowedRoles: ["logo", "favicon"],
+          minPixelClass: "small",
+          preferredAspect: "1:1",
+          note: "Headshot/avatar for the testimonial author."
+        }
+      },
+      requiresSiteCapabilities: ["reviews_or_testimonials", "media_library"]
+    },
+    exampleProps: {
+      heading: "Compassionate care for your mental wellbeing",
+      description: "Our team of experienced mental health professionals is dedicated to providing compassionate care and support to individuals in need.",
+      smallImages: [
+        {
+          src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+          alt: "Dr. Smith"
+        },
+        {
+          src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+          alt: "Dr. Johnson"
+        }
+      ],
+      testimonial: {
+        quote: "The support I received changed my life. I'm so grateful for the compassionate care.",
+        author: "Sarah M.",
+        role: "Client",
+        avatarSrc: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp"
+      },
+      featureImage: {
+        src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+        alt: "Mental health support"
+      },
+      actions: [
+        { label: "Get Started", href: "#", variant: "default" },
+        { label: "Talk to Sales", href: "#", variant: "outline" }
+      ],
+      background: "gray"
+    }
   },
   "hero-mentorship-video-split": {
     id: "hero-mentorship-video-split",
@@ -112079,7 +112184,101 @@ var BLOCK_REGISTRY = {
     category: "hero",
     component: HeroMentorshipVideoSplit,
     props: "HeroMentorshipVideoSplitProps",
-    exampleUsage: `<HeroMentorshipVideoSplit />`.trim()
+    exampleUsage: `
+<HeroMentorshipVideoSplit
+  heading="Reclaim Your Peace. Scale Sustainably."
+  description="Somatic mindset coaching for high-achieving entrepreneurs ready to lead from strength \u2014 not survival mode."
+  action={{ label: "Book Your Discovery Call", href: "/contact", variant: "default", size: "lg" }}
+  videoLabel="Watch the Overview"
+  videoTitle="Coaching Overview"
+  modalVideo={{
+    image: {
+      src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+      alt: "Coaching overview poster",
+    },
+    video: {
+      src: "https://toastability-production.s3.amazonaws.com/4kox2ux0ye1wlqkdwg03s08a67i1",
+    },
+  }}
+  image={{
+    src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+    alt: "Coach portrait",
+  }}
+  background="dark"
+/>
+    `.trim(),
+    importantUsageNotes: "The 'image' prop is the main hero image and MUST be an image asset (poster/photo). The 'modalVideo' prop's nested 'video.src' MUST be a video asset (HLS playlist or MP4) and 'modalVideo.image.src' MUST be an image asset (video poster). NEVER swap these: do not put a video URL into the 'image' prop and do not put an image URL into 'modalVideo.video.src'. All media src values must be absolute URLs to real CDN assets \u2014 never relative paths or placeholder strings. Keep 'heading' concise (under 60 characters) for visual balance.",
+    usageRequirements: {
+      requiredProps: ["heading", "image"],
+      propConstraints: {
+        heading: { required: true, maxLength: 60 },
+        description: { maxLength: 220 },
+        image: {
+          required: true,
+          note: "Main hero image. Must be an image asset (jpg/png/webp), NOT a video URL."
+        },
+        "modalVideo.video.src": {
+          note: "Must be a video asset URL (HLS .m3u8 master playlist or .mp4). Must NOT be an image URL."
+        },
+        "modalVideo.image.src": {
+          note: "Video poster image. Must be an image asset, NOT a video URL."
+        }
+      },
+      mediaSlots: {
+        image: {
+          path: "image",
+          roles: ["hero", "feature", "profile"],
+          disallowedRoles: ["logo", "favicon", "video-thumbnail"],
+          minPixelClass: "large",
+          required: true,
+          note: "Main hero image slot. IMAGE MEDIA ONLY. Do not assign a video URL here."
+        },
+        "modalVideo.video.src": {
+          path: "modalVideo.video.src",
+          roles: [],
+          disallowedRoles: ["logo", "favicon", "hero", "feature", "profile"],
+          note: "VIDEO MEDIA ONLY (HLS master playlist or MP4). Do not assign an image URL here."
+        },
+        "modalVideo.image.src": {
+          path: "modalVideo.image.src",
+          roles: ["video-thumbnail", "hero", "feature"],
+          disallowedRoles: ["logo", "favicon"],
+          minPixelClass: "medium",
+          note: "Poster image shown before the video plays. IMAGE MEDIA ONLY."
+        }
+      },
+      requiresSiteCapabilities: ["media_library"],
+      notes: [
+        "Image and video media must never be swapped between the 'image' prop and the 'modalVideo' prop.",
+        "All media src values must be absolute URLs to real assets; relative paths are not allowed."
+      ]
+    },
+    exampleProps: {
+      heading: "Reclaim Your Peace. Scale Sustainably.",
+      description: "Somatic mindset coaching for high-achieving entrepreneurs ready to lead from strength \u2014 not survival mode.",
+      action: {
+        label: "Book Your Discovery Call",
+        href: "/contact",
+        variant: "default",
+        size: "lg"
+      },
+      videoLabel: "Watch the Overview",
+      videoTitle: "Coaching Overview",
+      modalVideo: {
+        image: {
+          src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+          alt: "Coaching overview poster"
+        },
+        video: {
+          src: "https://toastability-production.s3.amazonaws.com/4kox2ux0ye1wlqkdwg03s08a67i1"
+        }
+      },
+      image: {
+        src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+        alt: "Coach portrait"
+      },
+      background: "dark"
+    }
   },
   "hero-business-operations-mosaic": {
     id: "hero-business-operations-mosaic",
@@ -120360,9 +120559,11 @@ function normalizeBlock(block, source) {
     },
     examples: {
       exampleUsage: block.exampleUsage || null,
-      defaultData: null
+      exampleProps: block.exampleProps ? JSON.parse(JSON.stringify(block.exampleProps)) : null
     },
-    source: source ?? null
+    source: source ?? null,
+    importantUsageNotes: block.importantUsageNotes ?? null,
+    usageRequirements: block.usageRequirements ? JSON.parse(JSON.stringify(block.usageRequirements)) : null
   };
 }
 function createBuilderContractBundle({

package/dist/registry.d.cts

@@ -1,68 +1,131 @@
 /**
- * Semantic Block Registry
+ * Block Registry Types
  *
- * This registry maps semantic concepts to available UI blocks for AI-driven
- * site generation. Each block entry contains:
- * - id: Unique identifier for the block
- * - name: Human-readable name
- * - description: What the block does and when to use it
- * - semanticTags: Array of semantic concepts this block represents
- * - category: Block category (about, features, cta, testimonials, etc.)
- * - component: Reference to the actual component
- * - props: TypeScript type for the component's props
- * - exampleUsage: Code example showing how to use the block
- */
-interface BlockRegistryEntry$1<T = any> {
-    id: string;
-    name: string;
-    description: string;
-    semanticTags: string[];
-    category: BlockCategory$1;
-    component: React.ComponentType<T>;
-    props: string;
-    exampleUsage: string;
-}
-type BlockCategory$1 = "about" | "features" | "cta" | "testimonials" | "services" | "hero" | "footer" | "header" | "pricing" | "team" | "stats" | "faq" | "contact" | "carousel" | "gallery" | "timeline" | "process" | "benefits" | "comparison" | "background-pattern-hero" | "blog" | "article" | "case-studies-list" | "case-study-detail" | "navbar" | "logos" | "project-list" | "project-detail" | "list" | "offer-modal" | "banner" | "industries" | "resource-detail" | "service-detail" | "services-list" | "resource-list" | "link-page";
-/**
- * Block Registry - Central registry of all available UI blocks
- */
-declare const BLOCK_REGISTRY: Record<string, BlockRegistryEntry$1>;
-/**
- * Get blocks by semantic tag
+ * Shared type definitions for the block registry system.
  */
-declare function getBlocksBySemanticTag(tag: string): BlockRegistryEntry$1[];
+type BlockCategory = "about" | "features" | "cta" | "testimonials" | "services" | "hero" | "footer" | "header" | "pricing" | "team" | "stats" | "faq" | "contact" | "carousel" | "gallery" | "timeline" | "process" | "benefits" | "comparison" | "background-pattern-hero" | "blog" | "article" | "case-studies-list" | "case-study-detail" | "navbar" | "logos" | "project-list" | "project-detail" | "list" | "offer-modal" | "banner" | "industries" | "resource-detail" | "service-detail" | "services-list" | "resource-list" | "link-page";
 /**
- * Get blocks by category
+ * Semantic role hints for a media slot. Consumers (semantic site builders,
+ * media classifiers) use these to scope which assets are eligible for a slot.
+ *
+ * - `logo`: brand logos / wordmarks (small, transparent backgrounds).
+ * - `favicon`: tiny brand icon.
+ * - `hero`: large hero/banner imagery.
+ * - `feature`: large feature/marketing imagery (non-logo).
+ * - `thumbnail`: small supporting imagery (e.g. card images, team thumbs).
+ * - `profile`: portrait/headshot of a person.
+ * - `avatar`: small profile / testimonial avatar.
+ * - `gallery`: imagery suited for galleries / grids.
+ * - `background`: large background imagery, often photographic.
+ * - `screenshot`: product screenshots / UI captures.
+ * - `illustration`: vector / illustrative art.
+ * - `video-thumbnail`: poster image for a video slot.
  */
-declare function getBlocksByCategory(category: BlockCategory$1): BlockRegistryEntry$1[];
+type MediaRole = "logo" | "favicon" | "hero" | "feature" | "thumbnail" | "profile" | "avatar" | "gallery" | "background" | "screenshot" | "illustration" | "video-thumbnail";
+/** Minimum pixel class expected for a media asset. */
+type MediaPixelClass = "tiny" | "small" | "medium" | "large" | "xlarge";
 /**
- * Get block by ID
+ * Structured description of a single media slot inside a block's prop tree.
+ * The `path` is dot/bracket notation, e.g. `featureImage`, `smallImages[]`,
+ * `testimonial.avatarSrc`.
  */
-declare function getBlockById(id: string): BlockRegistryEntry$1 | undefined;
+interface BlockMediaSlot {
+    path: string;
+    /** Allowed/expected semantic roles for this slot, in priority order. */
+    roles: MediaRole[];
+    /** Roles that must NOT be assigned to this slot. */
+    disallowedRoles?: MediaRole[];
+    /** Minimum acceptable pixel class for this slot. */
+    minPixelClass?: MediaPixelClass;
+    /** Preferred aspect ratio, e.g. "16:9", "1:1", "4:5". */
+    preferredAspect?: string;
+    /** Whether the block visually requires this slot to render correctly. */
+    required?: boolean;
+    /** Short note explaining the slot's intent (consumed by AI prompts). */
+    note?: string;
+}
 /**
- * Get all available blocks
+ * Per-prop content constraints. Additive – consumers should treat missing
+ * fields as "no constraint declared" rather than rejecting payloads.
  */
-declare function getAllBlocks(): BlockRegistryEntry$1[];
+interface BlockPropConstraint {
+    /** Whether the block requires this prop to render correctly. */
+    required?: boolean;
+    /** Maximum string length for text-shaped props. */
+    maxLength?: number;
+    /** Exact item count for array props (shorthand for minItems = maxItems). */
+    count?: number;
+    /** Minimum array length. */
+    minItems?: number;
+    /** Maximum array length. */
+    maxItems?: number;
+    /**
+     * Pinned values, by index for array props or as a single value for scalars.
+     * Used for the `actions[0].variant = "default"` / `actions[1].variant = "outline"` pattern.
+     */
+    pinnedValues?: Record<string, string | number | boolean>;
+    /** Free-form note about this prop (for AI prompts). */
+    note?: string;
+}
 /**
- * Get all categories
+ * Capabilities the host site / data source must satisfy for the block to be
+ * suitable. Consumers (e.g. Octane) gate block selection on these BEFORE the
+ * block is offered to the model, so it cannot fabricate the missing input.
  */
-declare function getAllCategories(): BlockCategory$1[];
+type SiteCapability = "reviews_or_testimonials" | "pricing_data" | "team_members" | "blog_posts" | "case_studies" | "metrics_or_stats" | "product_catalog" | "media_library" | "contact_info";
 /**
- * Search blocks by query (searches name, description, and semantic tags)
+ * Structured usage requirements for a block. This is the executable
+ * complement to `importantUsageNotes` (which remains for human-readable
+ * prompt context). When present, downstream consumers SHOULD enforce these
+ * at selection time and during post-generation validation.
  */
-declare function searchBlocks(query: string): BlockRegistryEntry$1[];
-
+interface BlockUsageRequirements {
+    /** Names of props that are required for the block to render correctly. */
+    requiredProps?: string[];
+    /** Per-prop content/cardinality constraints, keyed by prop name/path. */
+    propConstraints?: Record<string, BlockPropConstraint>;
+    /** Media slot metadata, keyed by slot path. */
+    mediaSlots?: Record<string, BlockMediaSlot>;
+    /** Site capabilities required to safely select this block. */
+    requiresSiteCapabilities?: SiteCapability[];
+    /**
+     * Free-form structured rules that don't fit other fields. Consumers should
+     * treat unknown keys as advisory.
+     */
+    notes?: string[];
+}
 /**
- * Block Registry Types
- *
- * Shared type definitions for the block registry system.
+ * Shared metadata fields that describe a block's contract. Used both by
+ * {@link BlockMetadata} (no component) and {@link BlockRegistryEntry}
+ * (with component).
  */
-type BlockCategory = "about" | "features" | "cta" | "testimonials" | "services" | "hero" | "footer" | "header" | "pricing" | "team" | "stats" | "faq" | "contact" | "carousel" | "gallery" | "timeline" | "process" | "benefits" | "comparison" | "background-pattern-hero" | "blog" | "article" | "case-studies-list" | "case-study-detail" | "navbar" | "logos" | "project-list" | "project-detail" | "list" | "offer-modal" | "banner" | "industries" | "resource-detail" | "service-detail" | "services-list" | "resource-list" | "link-page";
+interface BlockContractFields {
+    /**
+     * Human-readable usage guidance for AI prompts. This remains advisory.
+     * For executable rules use {@link BlockContractFields.usageRequirements}.
+     */
+    importantUsageNotes?: string;
+    /** Structured, machine-readable usage requirements. */
+    usageRequirements?: BlockUsageRequirements;
+    /**
+     * Canonical example payload for the block, matching the prop shape.
+     * Optional. When supplied, consumers should prefer this over parsing
+     * `exampleUsage` JSX.
+     *
+     * IMPORTANT: These are reference examples for AI prompting / preview
+     * tooling only. They are NOT runtime defaults — consumers MUST NOT
+     * substitute these values as fallback content on a real client site.
+     * The previous name (`defaultProps`) was renamed to make this explicit:
+     * AI agents had begun treating "default" values as safe runtime
+     * fallbacks for missing client data, which is incorrect.
+     */
+    exampleProps?: Record<string, unknown>;
+}
 /**
  * Metadata-only block registry entry (no component import)
  * Used for AI-driven component discovery without bundling all components
  */
-interface BlockMetadata {
+interface BlockMetadata extends BlockContractFields {
     id: string;
     name: string;
     description: string;
@@ -81,7 +144,7 @@ interface BlockMetadata {
  * Full block registry entry with component reference
  * @deprecated Use BlockMetadata for new code - this type causes all components to be bundled
  */
-interface BlockRegistryEntry<T = any> {
+interface BlockRegistryEntry<T = any> extends BlockContractFields {
     id: string;
     name: string;
     description: string;
@@ -107,7 +170,17 @@ interface BuilderContractPropsContract {
 }
 interface BuilderContractExamples {
     exampleUsage: string | null;
-    defaultData: null;
+    /**
+     * Canonical example props payload. Populated from
+     * BlockRegistryEntry.exampleProps when declared, otherwise null.
+     *
+     * IMPORTANT: This is reference example data only, not a runtime
+     * fallback. Consumers MUST NOT substitute these values for missing
+     * client content. The previous name (`defaultData`) was renamed
+     * because downstream AI agents were treating it as safe runtime
+     * default content.
+     */
+    exampleProps: Record<string, unknown> | null;
 }
 interface BuilderContractBlock {
     componentId: string;
@@ -121,6 +194,16 @@ interface BuilderContractBlock {
     propsContract: BuilderContractPropsContract;
     examples: BuilderContractExamples;
     source: BuilderContractBlockSource | null;
+    /**
+     * Human-readable usage guidance for AI prompts. Mirrors
+     * BlockRegistryEntry.importantUsageNotes when declared, otherwise null.
+     */
+    importantUsageNotes: string | null;
+    /**
+     * Structured, machine-readable usage requirements. Null when the
+     * registry entry does not declare any.
+     */
+    usageRequirements: BlockUsageRequirements | null;
 }
 interface BuilderContractMetadata {
     contractVersion: string;
@@ -195,6 +278,50 @@ interface BuilderContractBundle {
     pageRules: BuilderContractPageRules;
 }
 
+/**
+ * Semantic Block Registry
+ *
+ * This registry maps semantic concepts to available UI blocks for AI-driven
+ * site generation. Each block entry contains:
+ * - id: Unique identifier for the block
+ * - name: Human-readable name
+ * - description: What the block does and when to use it
+ * - semanticTags: Array of semantic concepts this block represents
+ * - category: Block category (about, features, cta, testimonials, etc.)
+ * - component: Reference to the actual component
+ * - props: TypeScript type for the component's props
+ * - exampleUsage: Code example showing how to use the block
+ */
+
+/**
+ * Block Registry - Central registry of all available UI blocks
+ */
+declare const BLOCK_REGISTRY: Record<string, BlockRegistryEntry>;
+/**
+ * Get blocks by semantic tag
+ */
+declare function getBlocksBySemanticTag(tag: string): BlockRegistryEntry[];
+/**
+ * Get blocks by category
+ */
+declare function getBlocksByCategory(category: BlockCategory): BlockRegistryEntry[];
+/**
+ * Get block by ID
+ */
+declare function getBlockById(id: string): BlockRegistryEntry | undefined;
+/**
+ * Get all available blocks
+ */
+declare function getAllBlocks(): BlockRegistryEntry[];
+/**
+ * Get all categories
+ */
+declare function getAllCategories(): BlockCategory[];
+/**
+ * Search blocks by query (searches name, description, and semantic tags)
+ */
+declare function searchBlocks(query: string): BlockRegistryEntry[];
+
 declare const BUILDER_CONTRACT_VERSION = "v1";
 interface CreateBuilderContractBundleOptions {
     blocks: BlockRegistryEntry[];
@@ -205,4 +332,4 @@ interface CreateBuilderContractBundleOptions {
 }
 declare function createBuilderContractBundle({ blocks, uiVersion, exportedAt, source, blockSources, }: CreateBuilderContractBundleOptions): BuilderContractBundle;
 
-export { BLOCK_REGISTRY, BUILDER_CONTRACT_VERSION, type BlockCategory, type BlockMetadata, type BlockRegistryEntry, type BuilderContractBlock, type BuilderContractBlockSource, type BuilderContractBundle, type BuilderContractDesignTokens, type BuilderContractDynamicSourceDefinition, type BuilderContractDynamicSources, type BuilderContractExamples, type BuilderContractLayoutRole, type BuilderContractMetadata, type BuilderContractPageRules, type BuilderContractPropsContract, type BuilderContractSharedLayout, type BuilderContractSharedLayoutSection, createBuilderContractBundle, getAllBlocks, getAllCategories, getBlockById, getBlocksByCategory, getBlocksBySemanticTag, searchBlocks };
+export { BLOCK_REGISTRY, BUILDER_CONTRACT_VERSION, type BlockCategory, type BlockContractFields, type BlockMediaSlot, type BlockMetadata, type BlockPropConstraint, type BlockRegistryEntry, type BlockUsageRequirements, type BuilderContractBlock, type BuilderContractBlockSource, type BuilderContractBundle, type BuilderContractDesignTokens, type BuilderContractDynamicSourceDefinition, type BuilderContractDynamicSources, type BuilderContractExamples, type BuilderContractLayoutRole, type BuilderContractMetadata, type BuilderContractPageRules, type BuilderContractPropsContract, type BuilderContractSharedLayout, type BuilderContractSharedLayoutSection, type MediaPixelClass, type MediaRole, type SiteCapability, createBuilderContractBundle, getAllBlocks, getAllCategories, getBlockById, getBlocksByCategory, getBlocksBySemanticTag, searchBlocks };

package/dist/registry.d.ts

@@ -1,68 +1,131 @@
 /**
- * Semantic Block Registry
+ * Block Registry Types
  *
- * This registry maps semantic concepts to available UI blocks for AI-driven
- * site generation. Each block entry contains:
- * - id: Unique identifier for the block
- * - name: Human-readable name
- * - description: What the block does and when to use it
- * - semanticTags: Array of semantic concepts this block represents
- * - category: Block category (about, features, cta, testimonials, etc.)
- * - component: Reference to the actual component
- * - props: TypeScript type for the component's props
- * - exampleUsage: Code example showing how to use the block
- */
-interface BlockRegistryEntry$1<T = any> {
-    id: string;
-    name: string;
-    description: string;
-    semanticTags: string[];
-    category: BlockCategory$1;
-    component: React.ComponentType<T>;
-    props: string;
-    exampleUsage: string;
-}
-type BlockCategory$1 = "about" | "features" | "cta" | "testimonials" | "services" | "hero" | "footer" | "header" | "pricing" | "team" | "stats" | "faq" | "contact" | "carousel" | "gallery" | "timeline" | "process" | "benefits" | "comparison" | "background-pattern-hero" | "blog" | "article" | "case-studies-list" | "case-study-detail" | "navbar" | "logos" | "project-list" | "project-detail" | "list" | "offer-modal" | "banner" | "industries" | "resource-detail" | "service-detail" | "services-list" | "resource-list" | "link-page";
-/**
- * Block Registry - Central registry of all available UI blocks
- */
-declare const BLOCK_REGISTRY: Record<string, BlockRegistryEntry$1>;
-/**
- * Get blocks by semantic tag
+ * Shared type definitions for the block registry system.
  */
-declare function getBlocksBySemanticTag(tag: string): BlockRegistryEntry$1[];
+type BlockCategory = "about" | "features" | "cta" | "testimonials" | "services" | "hero" | "footer" | "header" | "pricing" | "team" | "stats" | "faq" | "contact" | "carousel" | "gallery" | "timeline" | "process" | "benefits" | "comparison" | "background-pattern-hero" | "blog" | "article" | "case-studies-list" | "case-study-detail" | "navbar" | "logos" | "project-list" | "project-detail" | "list" | "offer-modal" | "banner" | "industries" | "resource-detail" | "service-detail" | "services-list" | "resource-list" | "link-page";
 /**
- * Get blocks by category
+ * Semantic role hints for a media slot. Consumers (semantic site builders,
+ * media classifiers) use these to scope which assets are eligible for a slot.
+ *
+ * - `logo`: brand logos / wordmarks (small, transparent backgrounds).
+ * - `favicon`: tiny brand icon.
+ * - `hero`: large hero/banner imagery.
+ * - `feature`: large feature/marketing imagery (non-logo).
+ * - `thumbnail`: small supporting imagery (e.g. card images, team thumbs).
+ * - `profile`: portrait/headshot of a person.
+ * - `avatar`: small profile / testimonial avatar.
+ * - `gallery`: imagery suited for galleries / grids.
+ * - `background`: large background imagery, often photographic.
+ * - `screenshot`: product screenshots / UI captures.
+ * - `illustration`: vector / illustrative art.
+ * - `video-thumbnail`: poster image for a video slot.
  */
-declare function getBlocksByCategory(category: BlockCategory$1): BlockRegistryEntry$1[];
+type MediaRole = "logo" | "favicon" | "hero" | "feature" | "thumbnail" | "profile" | "avatar" | "gallery" | "background" | "screenshot" | "illustration" | "video-thumbnail";
+/** Minimum pixel class expected for a media asset. */
+type MediaPixelClass = "tiny" | "small" | "medium" | "large" | "xlarge";
 /**
- * Get block by ID
+ * Structured description of a single media slot inside a block's prop tree.
+ * The `path` is dot/bracket notation, e.g. `featureImage`, `smallImages[]`,
+ * `testimonial.avatarSrc`.
  */
-declare function getBlockById(id: string): BlockRegistryEntry$1 | undefined;
+interface BlockMediaSlot {
+    path: string;
+    /** Allowed/expected semantic roles for this slot, in priority order. */
+    roles: MediaRole[];
+    /** Roles that must NOT be assigned to this slot. */
+    disallowedRoles?: MediaRole[];
+    /** Minimum acceptable pixel class for this slot. */
+    minPixelClass?: MediaPixelClass;
+    /** Preferred aspect ratio, e.g. "16:9", "1:1", "4:5". */
+    preferredAspect?: string;
+    /** Whether the block visually requires this slot to render correctly. */
+    required?: boolean;
+    /** Short note explaining the slot's intent (consumed by AI prompts). */
+    note?: string;
+}
 /**
- * Get all available blocks
+ * Per-prop content constraints. Additive – consumers should treat missing
+ * fields as "no constraint declared" rather than rejecting payloads.
  */
-declare function getAllBlocks(): BlockRegistryEntry$1[];
+interface BlockPropConstraint {
+    /** Whether the block requires this prop to render correctly. */
+    required?: boolean;
+    /** Maximum string length for text-shaped props. */
+    maxLength?: number;
+    /** Exact item count for array props (shorthand for minItems = maxItems). */
+    count?: number;
+    /** Minimum array length. */
+    minItems?: number;
+    /** Maximum array length. */
+    maxItems?: number;
+    /**
+     * Pinned values, by index for array props or as a single value for scalars.
+     * Used for the `actions[0].variant = "default"` / `actions[1].variant = "outline"` pattern.
+     */
+    pinnedValues?: Record<string, string | number | boolean>;
+    /** Free-form note about this prop (for AI prompts). */
+    note?: string;
+}
 /**
- * Get all categories
+ * Capabilities the host site / data source must satisfy for the block to be
+ * suitable. Consumers (e.g. Octane) gate block selection on these BEFORE the
+ * block is offered to the model, so it cannot fabricate the missing input.
  */
-declare function getAllCategories(): BlockCategory$1[];
+type SiteCapability = "reviews_or_testimonials" | "pricing_data" | "team_members" | "blog_posts" | "case_studies" | "metrics_or_stats" | "product_catalog" | "media_library" | "contact_info";
 /**
- * Search blocks by query (searches name, description, and semantic tags)
+ * Structured usage requirements for a block. This is the executable
+ * complement to `importantUsageNotes` (which remains for human-readable
+ * prompt context). When present, downstream consumers SHOULD enforce these
+ * at selection time and during post-generation validation.
  */
-declare function searchBlocks(query: string): BlockRegistryEntry$1[];
-
+interface BlockUsageRequirements {
+    /** Names of props that are required for the block to render correctly. */
+    requiredProps?: string[];
+    /** Per-prop content/cardinality constraints, keyed by prop name/path. */
+    propConstraints?: Record<string, BlockPropConstraint>;
+    /** Media slot metadata, keyed by slot path. */
+    mediaSlots?: Record<string, BlockMediaSlot>;
+    /** Site capabilities required to safely select this block. */
+    requiresSiteCapabilities?: SiteCapability[];
+    /**
+     * Free-form structured rules that don't fit other fields. Consumers should
+     * treat unknown keys as advisory.
+     */
+    notes?: string[];
+}
 /**
- * Block Registry Types
- *
- * Shared type definitions for the block registry system.
+ * Shared metadata fields that describe a block's contract. Used both by
+ * {@link BlockMetadata} (no component) and {@link BlockRegistryEntry}
+ * (with component).
  */
-type BlockCategory = "about" | "features" | "cta" | "testimonials" | "services" | "hero" | "footer" | "header" | "pricing" | "team" | "stats" | "faq" | "contact" | "carousel" | "gallery" | "timeline" | "process" | "benefits" | "comparison" | "background-pattern-hero" | "blog" | "article" | "case-studies-list" | "case-study-detail" | "navbar" | "logos" | "project-list" | "project-detail" | "list" | "offer-modal" | "banner" | "industries" | "resource-detail" | "service-detail" | "services-list" | "resource-list" | "link-page";
+interface BlockContractFields {
+    /**
+     * Human-readable usage guidance for AI prompts. This remains advisory.
+     * For executable rules use {@link BlockContractFields.usageRequirements}.
+     */
+    importantUsageNotes?: string;
+    /** Structured, machine-readable usage requirements. */
+    usageRequirements?: BlockUsageRequirements;
+    /**
+     * Canonical example payload for the block, matching the prop shape.
+     * Optional. When supplied, consumers should prefer this over parsing
+     * `exampleUsage` JSX.
+     *
+     * IMPORTANT: These are reference examples for AI prompting / preview
+     * tooling only. They are NOT runtime defaults — consumers MUST NOT
+     * substitute these values as fallback content on a real client site.
+     * The previous name (`defaultProps`) was renamed to make this explicit:
+     * AI agents had begun treating "default" values as safe runtime
+     * fallbacks for missing client data, which is incorrect.
+     */
+    exampleProps?: Record<string, unknown>;
+}
 /**
  * Metadata-only block registry entry (no component import)
  * Used for AI-driven component discovery without bundling all components
  */
-interface BlockMetadata {
+interface BlockMetadata extends BlockContractFields {
     id: string;
     name: string;
     description: string;
@@ -81,7 +144,7 @@ interface BlockMetadata {
  * Full block registry entry with component reference
  * @deprecated Use BlockMetadata for new code - this type causes all components to be bundled
  */
-interface BlockRegistryEntry<T = any> {
+interface BlockRegistryEntry<T = any> extends BlockContractFields {
     id: string;
     name: string;
     description: string;
@@ -107,7 +170,17 @@ interface BuilderContractPropsContract {
 }
 interface BuilderContractExamples {
     exampleUsage: string | null;
-    defaultData: null;
+    /**
+     * Canonical example props payload. Populated from
+     * BlockRegistryEntry.exampleProps when declared, otherwise null.
+     *
+     * IMPORTANT: This is reference example data only, not a runtime
+     * fallback. Consumers MUST NOT substitute these values for missing
+     * client content. The previous name (`defaultData`) was renamed
+     * because downstream AI agents were treating it as safe runtime
+     * default content.
+     */
+    exampleProps: Record<string, unknown> | null;
 }
 interface BuilderContractBlock {
     componentId: string;
@@ -121,6 +194,16 @@ interface BuilderContractBlock {
     propsContract: BuilderContractPropsContract;
     examples: BuilderContractExamples;
     source: BuilderContractBlockSource | null;
+    /**
+     * Human-readable usage guidance for AI prompts. Mirrors
+     * BlockRegistryEntry.importantUsageNotes when declared, otherwise null.
+     */
+    importantUsageNotes: string | null;
+    /**
+     * Structured, machine-readable usage requirements. Null when the
+     * registry entry does not declare any.
+     */
+    usageRequirements: BlockUsageRequirements | null;
 }
 interface BuilderContractMetadata {
     contractVersion: string;
@@ -195,6 +278,50 @@ interface BuilderContractBundle {
     pageRules: BuilderContractPageRules;
 }
 
+/**
+ * Semantic Block Registry
+ *
+ * This registry maps semantic concepts to available UI blocks for AI-driven
+ * site generation. Each block entry contains:
+ * - id: Unique identifier for the block
+ * - name: Human-readable name
+ * - description: What the block does and when to use it
+ * - semanticTags: Array of semantic concepts this block represents
+ * - category: Block category (about, features, cta, testimonials, etc.)
+ * - component: Reference to the actual component
+ * - props: TypeScript type for the component's props
+ * - exampleUsage: Code example showing how to use the block
+ */
+
+/**
+ * Block Registry - Central registry of all available UI blocks
+ */
+declare const BLOCK_REGISTRY: Record<string, BlockRegistryEntry>;
+/**
+ * Get blocks by semantic tag
+ */
+declare function getBlocksBySemanticTag(tag: string): BlockRegistryEntry[];
+/**
+ * Get blocks by category
+ */
+declare function getBlocksByCategory(category: BlockCategory): BlockRegistryEntry[];
+/**
+ * Get block by ID
+ */
+declare function getBlockById(id: string): BlockRegistryEntry | undefined;
+/**
+ * Get all available blocks
+ */
+declare function getAllBlocks(): BlockRegistryEntry[];
+/**
+ * Get all categories
+ */
+declare function getAllCategories(): BlockCategory[];
+/**
+ * Search blocks by query (searches name, description, and semantic tags)
+ */
+declare function searchBlocks(query: string): BlockRegistryEntry[];
+
 declare const BUILDER_CONTRACT_VERSION = "v1";
 interface CreateBuilderContractBundleOptions {
     blocks: BlockRegistryEntry[];
@@ -205,4 +332,4 @@ interface CreateBuilderContractBundleOptions {
 }
 declare function createBuilderContractBundle({ blocks, uiVersion, exportedAt, source, blockSources, }: CreateBuilderContractBundleOptions): BuilderContractBundle;
 
-export { BLOCK_REGISTRY, BUILDER_CONTRACT_VERSION, type BlockCategory, type BlockMetadata, type BlockRegistryEntry, type BuilderContractBlock, type BuilderContractBlockSource, type BuilderContractBundle, type BuilderContractDesignTokens, type BuilderContractDynamicSourceDefinition, type BuilderContractDynamicSources, type BuilderContractExamples, type BuilderContractLayoutRole, type BuilderContractMetadata, type BuilderContractPageRules, type BuilderContractPropsContract, type BuilderContractSharedLayout, type BuilderContractSharedLayoutSection, createBuilderContractBundle, getAllBlocks, getAllCategories, getBlockById, getBlocksByCategory, getBlocksBySemanticTag, searchBlocks };
+export { BLOCK_REGISTRY, BUILDER_CONTRACT_VERSION, type BlockCategory, type BlockContractFields, type BlockMediaSlot, type BlockMetadata, type BlockPropConstraint, type BlockRegistryEntry, type BlockUsageRequirements, type BuilderContractBlock, type BuilderContractBlockSource, type BuilderContractBundle, type BuilderContractDesignTokens, type BuilderContractDynamicSourceDefinition, type BuilderContractDynamicSources, type BuilderContractExamples, type BuilderContractLayoutRole, type BuilderContractMetadata, type BuilderContractPageRules, type BuilderContractPropsContract, type BuilderContractSharedLayout, type BuilderContractSharedLayoutSection, type MediaPixelClass, type MediaRole, type SiteCapability, createBuilderContractBundle, getAllBlocks, getAllCategories, getBlockById, getBlocksByCategory, getBlocksBySemanticTag, searchBlocks };

package/dist/registry.js

@@ -66935,16 +66935,22 @@ var FeaturedCardsGridDropdown = ({
   optixFlowConfig
 }) => {
   return /* @__PURE__ */ jsxs("div", { children: [
-    /* @__PURE__ */ jsx("div", { className: "flex gap-4 pb-8", children: featuredLinks?.map((link, index) => /* @__PURE__ */ jsx(
+    featuredLinks && featuredLinks?.length > 0 ? /* @__PURE__ */ jsx("div", { className: "flex gap-4 pb-8", children: featuredLinks?.map((link, index) => /* @__PURE__ */ jsx(
       FeaturedLink,
       {
         link,
         optixFlowConfig
       },
       `desktop-featured-link-${index}`
-    )) }),
-    /* @__PURE__ */ jsx(Separator, {}),
-    /* @__PURE__ */ jsx("div", { className: "grid grid-cols-4 pt-8", children: links?.map((link, index) => /* @__PURE__ */ jsx(NavLink, { link }, `default-nav-link-${index}`)) })
+    )) }) : null,
+    featuredLinks && featuredLinks?.length > 0 && links && links?.length > 0 ? /* @__PURE__ */ jsx(Separator, {}) : null,
+    links && links?.length > 0 ? /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: `grid grid-cols-4 pt-${featuredLinks && featuredLinks?.length > 0 ? 8 : 0} gap-4`,
+        children: links?.map((link, index) => /* @__PURE__ */ jsx(NavLink, { link }, `default-nav-link-${index}`))
+      }
+    ) : null
   ] });
 };
 var GroupedLinksImageDropdown = ({
@@ -112020,7 +112026,106 @@ var BLOCK_REGISTRY = {
     category: "hero",
     component: HeroMentalHealthTeam,
     props: "HeroMentalHealthTeamProps",
-    exampleUsage: `<HeroMentalHealthTeam />`.trim()
+    exampleUsage: `
+<HeroMentalHealthTeam
+  heading="Compassionate care for your mental wellbeing"
+  description="Our team of experienced mental health professionals is dedicated to providing compassionate care and support to individuals in need."
+  smallImages={[
+    { src: "/images/team-1.jpg", alt: "Dr. Smith" },
+    { src: "/images/team-2.jpg", alt: "Dr. Johnson" },
+  ]}
+  testimonial={{
+    quote:
+      "The support I received changed my life. I'm so grateful for the compassionate care.",
+    author: "Sarah M.",
+    role: "Client",
+    avatarSrc: "/images/avatar.jpg",
+  }}
+  featureImage={{ src: "/images/feature.jpg", alt: "Mental health support" }}
+  actions={[
+    { label: "Get Started", href: "#", variant: "default" },
+    { label: "Talk to Sales", href: "#", variant: "outline" },
+  ]}
+  background="gray"
+/>
+    `.trim(),
+    importantUsageNotes: "Only use if you have a valid testimonial - DO NOT MAKE UP A TESTIMONIAL/REVIEW. Supply exactly 2 images to the 'smallImages' prop and ensure you supply a 'featureImage' prop object. Do not exceed 40 characters for the 'heading' prop. Do not exceed 130 characters for the 'description' prop. If you supply multiple 'actions', ensure to use a variant of 'default' for the first action, and 'outline' for the second action to ensure proper visual distinction between the two CTAs. Follow the example props closely for this block.",
+    usageRequirements: {
+      requiredProps: ["heading", "smallImages", "featureImage", "testimonial"],
+      propConstraints: {
+        heading: { required: true, maxLength: 40 },
+        description: { maxLength: 130 },
+        smallImages: { required: true, count: 2, minItems: 2, maxItems: 2 },
+        featureImage: { required: true },
+        testimonial: {
+          required: true,
+          note: "Must be a real, sourced testimonial. Do not fabricate."
+        },
+        actions: {
+          maxItems: 2,
+          pinnedValues: {
+            "0.variant": "default",
+            "1.variant": "outline"
+          }
+        }
+      },
+      mediaSlots: {
+        featureImage: {
+          path: "featureImage",
+          roles: ["feature", "hero"],
+          disallowedRoles: ["logo", "favicon"],
+          minPixelClass: "large",
+          required: true,
+          note: "Large feature image. Must not be a logo or favicon."
+        },
+        "smallImages[]": {
+          path: "smallImages[]",
+          roles: ["thumbnail", "profile", "feature"],
+          disallowedRoles: ["logo", "favicon"],
+          minPixelClass: "small",
+          required: true,
+          note: "Two team / supporting images. Must not be logos."
+        },
+        "testimonial.avatarSrc": {
+          path: "testimonial.avatarSrc",
+          roles: ["profile", "avatar"],
+          disallowedRoles: ["logo", "favicon"],
+          minPixelClass: "small",
+          preferredAspect: "1:1",
+          note: "Headshot/avatar for the testimonial author."
+        }
+      },
+      requiresSiteCapabilities: ["reviews_or_testimonials", "media_library"]
+    },
+    exampleProps: {
+      heading: "Compassionate care for your mental wellbeing",
+      description: "Our team of experienced mental health professionals is dedicated to providing compassionate care and support to individuals in need.",
+      smallImages: [
+        {
+          src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+          alt: "Dr. Smith"
+        },
+        {
+          src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+          alt: "Dr. Johnson"
+        }
+      ],
+      testimonial: {
+        quote: "The support I received changed my life. I'm so grateful for the compassionate care.",
+        author: "Sarah M.",
+        role: "Client",
+        avatarSrc: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp"
+      },
+      featureImage: {
+        src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+        alt: "Mental health support"
+      },
+      actions: [
+        { label: "Get Started", href: "#", variant: "default" },
+        { label: "Talk to Sales", href: "#", variant: "outline" }
+      ],
+      background: "gray"
+    }
   },
   "hero-mentorship-video-split": {
     id: "hero-mentorship-video-split",
@@ -112039,7 +112144,101 @@ var BLOCK_REGISTRY = {
     category: "hero",
     component: HeroMentorshipVideoSplit,
     props: "HeroMentorshipVideoSplitProps",
-    exampleUsage: `<HeroMentorshipVideoSplit />`.trim()
+    exampleUsage: `
+<HeroMentorshipVideoSplit
+  heading="Reclaim Your Peace. Scale Sustainably."
+  description="Somatic mindset coaching for high-achieving entrepreneurs ready to lead from strength \u2014 not survival mode."
+  action={{ label: "Book Your Discovery Call", href: "/contact", variant: "default", size: "lg" }}
+  videoLabel="Watch the Overview"
+  videoTitle="Coaching Overview"
+  modalVideo={{
+    image: {
+      src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+      alt: "Coaching overview poster",
+    },
+    video: {
+      src: "https://toastability-production.s3.amazonaws.com/4kox2ux0ye1wlqkdwg03s08a67i1",
+    },
+  }}
+  image={{
+    src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+    alt: "Coach portrait",
+  }}
+  background="dark"
+/>
+    `.trim(),
+    importantUsageNotes: "The 'image' prop is the main hero image and MUST be an image asset (poster/photo). The 'modalVideo' prop's nested 'video.src' MUST be a video asset (HLS playlist or MP4) and 'modalVideo.image.src' MUST be an image asset (video poster). NEVER swap these: do not put a video URL into the 'image' prop and do not put an image URL into 'modalVideo.video.src'. All media src values must be absolute URLs to real CDN assets \u2014 never relative paths or placeholder strings. Keep 'heading' concise (under 60 characters) for visual balance.",
+    usageRequirements: {
+      requiredProps: ["heading", "image"],
+      propConstraints: {
+        heading: { required: true, maxLength: 60 },
+        description: { maxLength: 220 },
+        image: {
+          required: true,
+          note: "Main hero image. Must be an image asset (jpg/png/webp), NOT a video URL."
+        },
+        "modalVideo.video.src": {
+          note: "Must be a video asset URL (HLS .m3u8 master playlist or .mp4). Must NOT be an image URL."
+        },
+        "modalVideo.image.src": {
+          note: "Video poster image. Must be an image asset, NOT a video URL."
+        }
+      },
+      mediaSlots: {
+        image: {
+          path: "image",
+          roles: ["hero", "feature", "profile"],
+          disallowedRoles: ["logo", "favicon", "video-thumbnail"],
+          minPixelClass: "large",
+          required: true,
+          note: "Main hero image slot. IMAGE MEDIA ONLY. Do not assign a video URL here."
+        },
+        "modalVideo.video.src": {
+          path: "modalVideo.video.src",
+          roles: [],
+          disallowedRoles: ["logo", "favicon", "hero", "feature", "profile"],
+          note: "VIDEO MEDIA ONLY (HLS master playlist or MP4). Do not assign an image URL here."
+        },
+        "modalVideo.image.src": {
+          path: "modalVideo.image.src",
+          roles: ["video-thumbnail", "hero", "feature"],
+          disallowedRoles: ["logo", "favicon"],
+          minPixelClass: "medium",
+          note: "Poster image shown before the video plays. IMAGE MEDIA ONLY."
+        }
+      },
+      requiresSiteCapabilities: ["media_library"],
+      notes: [
+        "Image and video media must never be swapped between the 'image' prop and the 'modalVideo' prop.",
+        "All media src values must be absolute URLs to real assets; relative paths are not allowed."
+      ]
+    },
+    exampleProps: {
+      heading: "Reclaim Your Peace. Scale Sustainably.",
+      description: "Somatic mindset coaching for high-achieving entrepreneurs ready to lead from strength \u2014 not survival mode.",
+      action: {
+        label: "Book Your Discovery Call",
+        href: "/contact",
+        variant: "default",
+        size: "lg"
+      },
+      videoLabel: "Watch the Overview",
+      videoTitle: "Coaching Overview",
+      modalVideo: {
+        image: {
+          src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+          alt: "Coaching overview poster"
+        },
+        video: {
+          src: "https://toastability-production.s3.amazonaws.com/4kox2ux0ye1wlqkdwg03s08a67i1"
+        }
+      },
+      image: {
+        src: "https://cdn.ing/assets/i/r/308196/g6bbn73f7gxal82uu49m9prfd0u8/workplace-in-cafe.webp",
+        alt: "Coach portrait"
+      },
+      background: "dark"
+    }
   },
   "hero-business-operations-mosaic": {
     id: "hero-business-operations-mosaic",
@@ -120320,9 +120519,11 @@ function normalizeBlock(block, source) {
     },
     examples: {
       exampleUsage: block.exampleUsage || null,
-      defaultData: null
+      exampleProps: block.exampleProps ? JSON.parse(JSON.stringify(block.exampleProps)) : null
     },
-    source: source ?? null
+    source: source ?? null,
+    importantUsageNotes: block.importantUsageNotes ?? null,
+    usageRequirements: block.usageRequirements ? JSON.parse(JSON.stringify(block.usageRequirements)) : null
   };
 }
 function createBuilderContractBundle({

package/dist/social-link-icon.d.cts

@@ -77,6 +77,6 @@ interface SocialLinkIconProps extends Omit<PressableProps, "children">, SocialLi
  * />
  * ```
  */
-declare const SocialLinkIcon: React.ForwardRefExoticComponent<SocialLinkIconProps & React.RefAttributes<HTMLAnchorElement | HTMLButtonElement | HTMLSpanElement>>;
+declare const SocialLinkIcon: React.ForwardRefExoticComponent<SocialLinkIconProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement | HTMLSpanElement>>;
 
 export { SocialLinkIcon, type SocialLinkIconDynamicIconProps, type SocialLinkIconProps };

package/dist/social-link-icon.d.ts

@@ -77,6 +77,6 @@ interface SocialLinkIconProps extends Omit<PressableProps, "children">, SocialLi
  * />
  * ```
  */
-declare const SocialLinkIcon: React.ForwardRefExoticComponent<SocialLinkIconProps & React.RefAttributes<HTMLAnchorElement | HTMLButtonElement | HTMLSpanElement>>;
+declare const SocialLinkIcon: React.ForwardRefExoticComponent<SocialLinkIconProps & React.RefAttributes<HTMLButtonElement | HTMLAnchorElement | HTMLSpanElement>>;
 
 export { SocialLinkIcon, type SocialLinkIconDynamicIconProps, type SocialLinkIconProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensite/ui",
-  "version": "3.5.6",
+  "version": "3.5.8",
   "description": "Foundational UI component library for OpenSite Semantic Site Builder with tree-shakable exports and abstract styling",
   "keywords": [
     "react",