@opensite/ui 3.5.6 → 3.5.7

package/dist/registry.cjs

@@ -112060,7 +112060,97 @@ 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"]
+    },
+    defaultProps: {
+      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"
+    }
   },
   "hero-mentorship-video-split": {
     id: "hero-mentorship-video-split",
@@ -120360,9 +120450,11 @@ function normalizeBlock(block, source) {
     },
     examples: {
       exampleUsage: block.exampleUsage || null,
-      defaultData: null
+      defaultData: block.defaultProps ? JSON.parse(JSON.stringify(block.defaultProps)) : 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,124 @@
 /**
- * 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 default / example payload for the block, matching the prop
+     * shape. Optional. When supplied, consumers should prefer this over
+     * parsing `exampleUsage` JSX.
+     */
+    defaultProps?: 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 +137,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 +163,13 @@ interface BuilderContractPropsContract {
 }
 interface BuilderContractExamples {
     exampleUsage: string | null;
-    defaultData: null;
+    /**
+     * Canonical default / example props payload. Populated from
+     * BlockRegistryEntry.defaultProps when declared, otherwise null.
+     * Older consumers that expected this to always be null should treat
+     * an object value as advisory example data, not as a schema.
+     */
+    defaultData: Record<string, unknown> | null;
 }
 interface BuilderContractBlock {
     componentId: string;
@@ -121,6 +183,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 +267,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 +321,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,124 @@
 /**
- * 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 default / example payload for the block, matching the prop
+     * shape. Optional. When supplied, consumers should prefer this over
+     * parsing `exampleUsage` JSX.
+     */
+    defaultProps?: 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 +137,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 +163,13 @@ interface BuilderContractPropsContract {
 }
 interface BuilderContractExamples {
     exampleUsage: string | null;
-    defaultData: null;
+    /**
+     * Canonical default / example props payload. Populated from
+     * BlockRegistryEntry.defaultProps when declared, otherwise null.
+     * Older consumers that expected this to always be null should treat
+     * an object value as advisory example data, not as a schema.
+     */
+    defaultData: Record<string, unknown> | null;
 }
 interface BuilderContractBlock {
     componentId: string;
@@ -121,6 +183,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 +267,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 +321,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

@@ -112020,7 +112020,97 @@ 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"]
+    },
+    defaultProps: {
+      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"
+    }
   },
   "hero-mentorship-video-split": {
     id: "hero-mentorship-video-split",
@@ -120320,9 +120410,11 @@ function normalizeBlock(block, source) {
     },
     examples: {
       exampleUsage: block.exampleUsage || null,
-      defaultData: null
+      defaultData: block.defaultProps ? JSON.parse(JSON.stringify(block.defaultProps)) : null
     },
-    source: source ?? null
+    source: source ?? null,
+    importantUsageNotes: block.importantUsageNotes ?? null,
+    usageRequirements: block.usageRequirements ? JSON.parse(JSON.stringify(block.usageRequirements)) : null
   };
 }
 function createBuilderContractBundle({

package/package.json

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