@opensite/ui 3.2.1 → 3.2.3

package/README.md

@@ -445,6 +445,18 @@ const results = searchBlocks("alternating");
 - `getAllCategories()` - Get all available categories
 - `searchBlocks(query: string)` - Search blocks by name/description/tags
 
+### Builder Contract Bundle
+
+`builder-contract-bundle.json` is the versioned machine-readable contract for the semantic builder pipeline. It is generated from the same registry/export path as `registry-export.json`, but adds the structural rules that downstream services enforce:
+
+- `blocks` expose stable `blockRef` values derived from public `@opensite/ui/blocks/*` exports.
+- `sharedLayout` declares the canonical `_layout.header` and `_layout.footer` sources.
+- `dynamicSources` keeps symbolic sources such as `blog_feed` in canonical page JSON until `dashtrack-ai` hydrates them at routing-build time.
+- `designTokens` treats `theme_config` as canonical and `tailwind_css` as derived.
+- `pageRules` documents the route-centric payload shape (`block_name`, `block_ref`, `data`) that rendering must follow exactly.
+
+If you change a block's public export path, ID, category, semantic tags, or registry description, rebuild the package so the contract bundle stays authoritative.
+
 **Block Categories:**
 
 - about, features, cta, testimonials, services, hero, footer, header, pricing, team, stats, faq, contact, gallery, timeline, process, benefits, comparison
@@ -558,9 +570,10 @@ pnpm build
 
 - `package.json` export maps (via `generate:exports`)
 - `registry-export.json` (via `scripts/export-registry.js`)
+- `builder-contract-bundle.json` (via `scripts/export-registry.js`)
 
 If you change a block's design/intent, update its registry metadata in
-`src/registry/blocks.ts` before building so the exported JSON stays accurate.
+`src/registry/blocks.ts` before building so the exported JSON and builder contract stay accurate.
 
 ### Testing
 

package/dist/registry.cjs

@@ -119879,7 +119879,169 @@ function searchBlocks(query) {
   );
 }
 
+// src/registry/builder-contract.ts
+var BUILDER_CONTRACT_VERSION = "v1";
+var REQUIRED_TOKEN_FAMILIES = [
+  "color",
+  "typography",
+  "spacing",
+  "radius",
+  "shadow"
+];
+var REQUIRED_SEMANTIC_COLOR_ROLES = [
+  "background",
+  "foreground",
+  "card",
+  "card-foreground",
+  "popover",
+  "popover-foreground",
+  "primary",
+  "primary-foreground",
+  "secondary",
+  "secondary-foreground",
+  "muted",
+  "muted-foreground",
+  "accent",
+  "accent-foreground",
+  "destructive",
+  "destructive-foreground",
+  "border",
+  "input",
+  "ring"
+];
+function toPascalCase(value) {
+  return value.split(/[-_\/]/).filter(Boolean).map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join("");
+}
+function normalizeCategorySegment(category) {
+  if (category === "navbar") {
+    return "navbars";
+  }
+  if (category === "footer") {
+    return "footers";
+  }
+  return category;
+}
+function inferLayoutRole(blockRef, category) {
+  if (blockRef.startsWith("navbars/") || category === "navbar") {
+    return "header";
+  }
+  if (blockRef.startsWith("footers/") || category === "footer") {
+    return "footer";
+  }
+  return "page";
+}
+function normalizeBlock(block, source) {
+  const blockRef = source?.exportPath.replace(/^\.\/blocks\//, "") ?? `${normalizeCategorySegment(block.category)}/${block.id}`;
+  const component = block.component;
+  const blockName = component.displayName || component.name || toPascalCase(block.id);
+  return {
+    componentId: block.id,
+    blockName,
+    blockRef,
+    displayName: block.name,
+    description: block.description,
+    category: block.category,
+    semanticTags: [...block.semanticTags],
+    layoutRole: inferLayoutRole(blockRef, block.category),
+    propsContract: {
+      type: "typescript-type-reference",
+      reference: block.props,
+      runtimeSchema: null,
+      runtimeSchemaStatus: "missing"
+    },
+    examples: {
+      exampleUsage: block.exampleUsage || null,
+      defaultData: null
+    },
+    source: source ?? null
+  };
+}
+function createBuilderContractBundle({
+  blocks,
+  uiVersion,
+  exportedAt = (/* @__PURE__ */ new Date()).toISOString(),
+  source = "@opensite/ui",
+  blockSources = {}
+}) {
+  const normalizedBlocks = blocks.map((block) => normalizeBlock(block, blockSources[block.id])).sort((left, right) => left.blockRef.localeCompare(right.blockRef));
+  const headerBlockRefs = normalizedBlocks.filter((block) => block.layoutRole === "header").map((block) => block.blockRef);
+  const footerBlockRefs = normalizedBlocks.filter((block) => block.layoutRole === "footer").map((block) => block.blockRef);
+  return {
+    metadata: {
+      contractVersion: BUILDER_CONTRACT_VERSION,
+      uiVersion,
+      exportedAt,
+      source,
+      totalBlocks: normalizedBlocks.length
+    },
+    blocks: normalizedBlocks,
+    sharedLayout: {
+      canonicalLayoutKey: "_layout",
+      sections: {
+        header: {
+          sourceType: "website_navbar",
+          sourceOfTruth: "WebsiteNavBar",
+          aiAuthoring: "variant_request_only",
+          canonicalPayloadKey: "header",
+          allowedBlockRefs: headerBlockRefs
+        },
+        footer: {
+          sourceType: "shared_footer_page",
+          sourceOfTruth: "aliased/shared footer pages",
+          aiAuthoring: "variant_request_only",
+          canonicalPayloadKey: "footer",
+          allowedBlockRefs: footerBlockRefs
+        }
+      }
+    },
+    dynamicSources: {
+      blog_feed: {
+        sourceType: "blog_feed",
+        symbolic: true,
+        hydrationOwner: "dashtrack-ai",
+        hydrationPhase: "routing-build",
+        canonicalPayloadExpectation: "Keep blog feed requests symbolic in canonical page JSON until routing-build hydration resolves them.",
+        requiredFields: ["type"],
+        optionalFields: ["limit", "offset", "category", "tag", "featuredOnly"]
+      }
+    },
+    designTokens: {
+      canonicalSource: "theme_config",
+      derivedArtifacts: ["tailwind_css"],
+      requiredTokenFamilies: [...REQUIRED_TOKEN_FAMILIES],
+      requiredSemanticColorRoles: [...REQUIRED_SEMANTIC_COLOR_ROLES],
+      policy: "theme_config is canonical and tailwind_css must be derived from it; blocks should consume semantic tokens rather than hardcoded theme values."
+    },
+    pageRules: {
+      outputFormat: "route-map",
+      routeKeyPattern: "^/$|^/.+",
+      sharedLayoutKey: "_layout",
+      routeEntry: {
+        requiredKeys: ["pageId", "pageIds", "blocks"],
+        blocksKey: "blocks"
+      },
+      blockEntry: {
+        requiredKeys: ["block_name", "block_ref", "data"],
+        blockRefSource: "BuilderContractBundle.blocks[].blockRef",
+        blockNameSource: "BuilderContractBundle.blocks[].blockName"
+      },
+      sharedLayoutComposition: {
+        owner: "dashtrack-ai",
+        headerSource: "WebsiteNavBar",
+        footerSource: "aliased/shared footer pages"
+      },
+      dynamicHydration: {
+        symbolicInCanonicalPageJson: true,
+        owner: "dashtrack-ai",
+        phase: "routing-build"
+      }
+    }
+  };
+}
+
 exports.BLOCK_REGISTRY = BLOCK_REGISTRY;
+exports.BUILDER_CONTRACT_VERSION = BUILDER_CONTRACT_VERSION;
+exports.createBuilderContractBundle = createBuilderContractBundle;
 exports.getAllBlocks = getAllBlocks;
 exports.getAllCategories = getAllCategories;
 exports.getBlockById = getBlockById;

package/dist/registry.d.cts

@@ -12,44 +12,197 @@
  * - props: TypeScript type for the component's props
  * - exampleUsage: Code example showing how to use the block
  */
-interface BlockRegistryEntry<T = any> {
+interface BlockRegistryEntry$1<T = any> {
     id: string;
     name: string;
     description: string;
     semanticTags: string[];
-    category: BlockCategory;
+    category: BlockCategory$1;
     component: React.ComponentType<T>;
     props: string;
     exampleUsage: string;
 }
-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";
+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>;
+declare const BLOCK_REGISTRY: Record<string, BlockRegistryEntry$1>;
 /**
  * Get blocks by semantic tag
  */
-declare function getBlocksBySemanticTag(tag: string): BlockRegistryEntry[];
+declare function getBlocksBySemanticTag(tag: string): BlockRegistryEntry$1[];
 /**
  * Get blocks by category
  */
-declare function getBlocksByCategory(category: BlockCategory): BlockRegistryEntry[];
+declare function getBlocksByCategory(category: BlockCategory$1): BlockRegistryEntry$1[];
 /**
  * Get block by ID
  */
-declare function getBlockById(id: string): BlockRegistryEntry | undefined;
+declare function getBlockById(id: string): BlockRegistryEntry$1 | undefined;
 /**
  * Get all available blocks
  */
-declare function getAllBlocks(): BlockRegistryEntry[];
+declare function getAllBlocks(): BlockRegistryEntry$1[];
 /**
  * Get all categories
  */
-declare function getAllCategories(): BlockCategory[];
+declare function getAllCategories(): BlockCategory$1[];
 /**
  * Search blocks by query (searches name, description, and semantic tags)
  */
-declare function searchBlocks(query: string): BlockRegistryEntry[];
+declare function searchBlocks(query: string): BlockRegistryEntry$1[];
+
+/**
+ * Block Registry Types
+ *
+ * Shared type definitions for the block registry system.
+ */
+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";
+/**
+ * Metadata-only block registry entry (no component import)
+ * Used for AI-driven component discovery without bundling all components
+ */
+interface BlockMetadata {
+    id: string;
+    name: string;
+    description: string;
+    semanticTags: string[];
+    category: BlockCategory;
+    /** Module path for dynamic import, e.g., "@opensite/ui/blocks/about/alternating-blocks" */
+    modulePath: string;
+    /** Export name from the module */
+    exportName: string;
+    /** TypeScript props type name */
+    props: string;
+    /** Example usage code */
+    exampleUsage: string;
+}
+/**
+ * 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> {
+    id: string;
+    name: string;
+    description: string;
+    semanticTags: string[];
+    category: BlockCategory;
+    component: React.ComponentType<T>;
+    props: string;
+    exampleUsage: string;
+}
+type BuilderContractLayoutRole = "page" | "header" | "footer";
+interface BuilderContractBlockSource {
+    exportPath: string;
+    modulePath: string;
+    typesPath?: string;
+    importPath?: string;
+    requirePath?: string;
+}
+interface BuilderContractPropsContract {
+    type: "typescript-type-reference";
+    reference: string;
+    runtimeSchema: null;
+    runtimeSchemaStatus: "missing";
+}
+interface BuilderContractExamples {
+    exampleUsage: string | null;
+    defaultData: null;
+}
+interface BuilderContractBlock {
+    componentId: string;
+    blockName: string;
+    blockRef: string;
+    displayName: string;
+    description: string;
+    category: BlockCategory;
+    semanticTags: string[];
+    layoutRole: BuilderContractLayoutRole;
+    propsContract: BuilderContractPropsContract;
+    examples: BuilderContractExamples;
+    source: BuilderContractBlockSource | null;
+}
+interface BuilderContractMetadata {
+    contractVersion: string;
+    uiVersion: string;
+    exportedAt: string;
+    source: string;
+    totalBlocks: number;
+}
+interface BuilderContractSharedLayoutSection {
+    sourceType: string;
+    sourceOfTruth: string;
+    aiAuthoring: "variant_request_only";
+    canonicalPayloadKey: "header" | "footer";
+    allowedBlockRefs: string[];
+}
+interface BuilderContractSharedLayout {
+    canonicalLayoutKey: "_layout";
+    sections: {
+        header: BuilderContractSharedLayoutSection;
+        footer: BuilderContractSharedLayoutSection;
+    };
+}
+interface BuilderContractDynamicSourceDefinition {
+    sourceType: string;
+    symbolic: true;
+    hydrationOwner: string;
+    hydrationPhase: string;
+    canonicalPayloadExpectation: string;
+    requiredFields: string[];
+    optionalFields: string[];
+}
+interface BuilderContractDynamicSources {
+    blog_feed: BuilderContractDynamicSourceDefinition;
+}
+interface BuilderContractDesignTokens {
+    canonicalSource: "theme_config";
+    derivedArtifacts: ["tailwind_css"];
+    requiredTokenFamilies: string[];
+    requiredSemanticColorRoles: string[];
+    policy: string;
+}
+interface BuilderContractPageRules {
+    outputFormat: "route-map";
+    routeKeyPattern: string;
+    sharedLayoutKey: "_layout";
+    routeEntry: {
+        requiredKeys: string[];
+        blocksKey: "blocks";
+    };
+    blockEntry: {
+        requiredKeys: string[];
+        blockRefSource: string;
+        blockNameSource: string;
+    };
+    sharedLayoutComposition: {
+        owner: string;
+        headerSource: string;
+        footerSource: string;
+    };
+    dynamicHydration: {
+        symbolicInCanonicalPageJson: true;
+        owner: string;
+        phase: string;
+    };
+}
+interface BuilderContractBundle {
+    metadata: BuilderContractMetadata;
+    blocks: BuilderContractBlock[];
+    sharedLayout: BuilderContractSharedLayout;
+    dynamicSources: BuilderContractDynamicSources;
+    designTokens: BuilderContractDesignTokens;
+    pageRules: BuilderContractPageRules;
+}
+
+declare const BUILDER_CONTRACT_VERSION = "v1";
+interface CreateBuilderContractBundleOptions {
+    blocks: BlockRegistryEntry[];
+    uiVersion: string;
+    exportedAt?: string;
+    source?: string;
+    blockSources?: Record<string, BuilderContractBlockSource>;
+}
+declare function createBuilderContractBundle({ blocks, uiVersion, exportedAt, source, blockSources, }: CreateBuilderContractBundleOptions): BuilderContractBundle;
 
-export { BLOCK_REGISTRY, type BlockCategory, type BlockRegistryEntry, getAllBlocks, getAllCategories, getBlockById, getBlocksByCategory, getBlocksBySemanticTag, searchBlocks };
+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 };

package/dist/registry.d.ts

@@ -12,44 +12,197 @@
  * - props: TypeScript type for the component's props
  * - exampleUsage: Code example showing how to use the block
  */
-interface BlockRegistryEntry<T = any> {
+interface BlockRegistryEntry$1<T = any> {
     id: string;
     name: string;
     description: string;
     semanticTags: string[];
-    category: BlockCategory;
+    category: BlockCategory$1;
     component: React.ComponentType<T>;
     props: string;
     exampleUsage: string;
 }
-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";
+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>;
+declare const BLOCK_REGISTRY: Record<string, BlockRegistryEntry$1>;
 /**
  * Get blocks by semantic tag
  */
-declare function getBlocksBySemanticTag(tag: string): BlockRegistryEntry[];
+declare function getBlocksBySemanticTag(tag: string): BlockRegistryEntry$1[];
 /**
  * Get blocks by category
  */
-declare function getBlocksByCategory(category: BlockCategory): BlockRegistryEntry[];
+declare function getBlocksByCategory(category: BlockCategory$1): BlockRegistryEntry$1[];
 /**
  * Get block by ID
  */
-declare function getBlockById(id: string): BlockRegistryEntry | undefined;
+declare function getBlockById(id: string): BlockRegistryEntry$1 | undefined;
 /**
  * Get all available blocks
  */
-declare function getAllBlocks(): BlockRegistryEntry[];
+declare function getAllBlocks(): BlockRegistryEntry$1[];
 /**
  * Get all categories
  */
-declare function getAllCategories(): BlockCategory[];
+declare function getAllCategories(): BlockCategory$1[];
 /**
  * Search blocks by query (searches name, description, and semantic tags)
  */
-declare function searchBlocks(query: string): BlockRegistryEntry[];
+declare function searchBlocks(query: string): BlockRegistryEntry$1[];
+
+/**
+ * Block Registry Types
+ *
+ * Shared type definitions for the block registry system.
+ */
+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";
+/**
+ * Metadata-only block registry entry (no component import)
+ * Used for AI-driven component discovery without bundling all components
+ */
+interface BlockMetadata {
+    id: string;
+    name: string;
+    description: string;
+    semanticTags: string[];
+    category: BlockCategory;
+    /** Module path for dynamic import, e.g., "@opensite/ui/blocks/about/alternating-blocks" */
+    modulePath: string;
+    /** Export name from the module */
+    exportName: string;
+    /** TypeScript props type name */
+    props: string;
+    /** Example usage code */
+    exampleUsage: string;
+}
+/**
+ * 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> {
+    id: string;
+    name: string;
+    description: string;
+    semanticTags: string[];
+    category: BlockCategory;
+    component: React.ComponentType<T>;
+    props: string;
+    exampleUsage: string;
+}
+type BuilderContractLayoutRole = "page" | "header" | "footer";
+interface BuilderContractBlockSource {
+    exportPath: string;
+    modulePath: string;
+    typesPath?: string;
+    importPath?: string;
+    requirePath?: string;
+}
+interface BuilderContractPropsContract {
+    type: "typescript-type-reference";
+    reference: string;
+    runtimeSchema: null;
+    runtimeSchemaStatus: "missing";
+}
+interface BuilderContractExamples {
+    exampleUsage: string | null;
+    defaultData: null;
+}
+interface BuilderContractBlock {
+    componentId: string;
+    blockName: string;
+    blockRef: string;
+    displayName: string;
+    description: string;
+    category: BlockCategory;
+    semanticTags: string[];
+    layoutRole: BuilderContractLayoutRole;
+    propsContract: BuilderContractPropsContract;
+    examples: BuilderContractExamples;
+    source: BuilderContractBlockSource | null;
+}
+interface BuilderContractMetadata {
+    contractVersion: string;
+    uiVersion: string;
+    exportedAt: string;
+    source: string;
+    totalBlocks: number;
+}
+interface BuilderContractSharedLayoutSection {
+    sourceType: string;
+    sourceOfTruth: string;
+    aiAuthoring: "variant_request_only";
+    canonicalPayloadKey: "header" | "footer";
+    allowedBlockRefs: string[];
+}
+interface BuilderContractSharedLayout {
+    canonicalLayoutKey: "_layout";
+    sections: {
+        header: BuilderContractSharedLayoutSection;
+        footer: BuilderContractSharedLayoutSection;
+    };
+}
+interface BuilderContractDynamicSourceDefinition {
+    sourceType: string;
+    symbolic: true;
+    hydrationOwner: string;
+    hydrationPhase: string;
+    canonicalPayloadExpectation: string;
+    requiredFields: string[];
+    optionalFields: string[];
+}
+interface BuilderContractDynamicSources {
+    blog_feed: BuilderContractDynamicSourceDefinition;
+}
+interface BuilderContractDesignTokens {
+    canonicalSource: "theme_config";
+    derivedArtifacts: ["tailwind_css"];
+    requiredTokenFamilies: string[];
+    requiredSemanticColorRoles: string[];
+    policy: string;
+}
+interface BuilderContractPageRules {
+    outputFormat: "route-map";
+    routeKeyPattern: string;
+    sharedLayoutKey: "_layout";
+    routeEntry: {
+        requiredKeys: string[];
+        blocksKey: "blocks";
+    };
+    blockEntry: {
+        requiredKeys: string[];
+        blockRefSource: string;
+        blockNameSource: string;
+    };
+    sharedLayoutComposition: {
+        owner: string;
+        headerSource: string;
+        footerSource: string;
+    };
+    dynamicHydration: {
+        symbolicInCanonicalPageJson: true;
+        owner: string;
+        phase: string;
+    };
+}
+interface BuilderContractBundle {
+    metadata: BuilderContractMetadata;
+    blocks: BuilderContractBlock[];
+    sharedLayout: BuilderContractSharedLayout;
+    dynamicSources: BuilderContractDynamicSources;
+    designTokens: BuilderContractDesignTokens;
+    pageRules: BuilderContractPageRules;
+}
+
+declare const BUILDER_CONTRACT_VERSION = "v1";
+interface CreateBuilderContractBundleOptions {
+    blocks: BlockRegistryEntry[];
+    uiVersion: string;
+    exportedAt?: string;
+    source?: string;
+    blockSources?: Record<string, BuilderContractBlockSource>;
+}
+declare function createBuilderContractBundle({ blocks, uiVersion, exportedAt, source, blockSources, }: CreateBuilderContractBundleOptions): BuilderContractBundle;
 
-export { BLOCK_REGISTRY, type BlockCategory, type BlockRegistryEntry, getAllBlocks, getAllCategories, getBlockById, getBlocksByCategory, getBlocksBySemanticTag, searchBlocks };
+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 };

package/dist/registry.js

@@ -119839,4 +119839,164 @@ function searchBlocks(query) {
   );
 }
 
-export { BLOCK_REGISTRY, getAllBlocks, getAllCategories, getBlockById, getBlocksByCategory, getBlocksBySemanticTag, searchBlocks };
+// src/registry/builder-contract.ts
+var BUILDER_CONTRACT_VERSION = "v1";
+var REQUIRED_TOKEN_FAMILIES = [
+  "color",
+  "typography",
+  "spacing",
+  "radius",
+  "shadow"
+];
+var REQUIRED_SEMANTIC_COLOR_ROLES = [
+  "background",
+  "foreground",
+  "card",
+  "card-foreground",
+  "popover",
+  "popover-foreground",
+  "primary",
+  "primary-foreground",
+  "secondary",
+  "secondary-foreground",
+  "muted",
+  "muted-foreground",
+  "accent",
+  "accent-foreground",
+  "destructive",
+  "destructive-foreground",
+  "border",
+  "input",
+  "ring"
+];
+function toPascalCase(value) {
+  return value.split(/[-_\/]/).filter(Boolean).map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join("");
+}
+function normalizeCategorySegment(category) {
+  if (category === "navbar") {
+    return "navbars";
+  }
+  if (category === "footer") {
+    return "footers";
+  }
+  return category;
+}
+function inferLayoutRole(blockRef, category) {
+  if (blockRef.startsWith("navbars/") || category === "navbar") {
+    return "header";
+  }
+  if (blockRef.startsWith("footers/") || category === "footer") {
+    return "footer";
+  }
+  return "page";
+}
+function normalizeBlock(block, source) {
+  const blockRef = source?.exportPath.replace(/^\.\/blocks\//, "") ?? `${normalizeCategorySegment(block.category)}/${block.id}`;
+  const component = block.component;
+  const blockName = component.displayName || component.name || toPascalCase(block.id);
+  return {
+    componentId: block.id,
+    blockName,
+    blockRef,
+    displayName: block.name,
+    description: block.description,
+    category: block.category,
+    semanticTags: [...block.semanticTags],
+    layoutRole: inferLayoutRole(blockRef, block.category),
+    propsContract: {
+      type: "typescript-type-reference",
+      reference: block.props,
+      runtimeSchema: null,
+      runtimeSchemaStatus: "missing"
+    },
+    examples: {
+      exampleUsage: block.exampleUsage || null,
+      defaultData: null
+    },
+    source: source ?? null
+  };
+}
+function createBuilderContractBundle({
+  blocks,
+  uiVersion,
+  exportedAt = (/* @__PURE__ */ new Date()).toISOString(),
+  source = "@opensite/ui",
+  blockSources = {}
+}) {
+  const normalizedBlocks = blocks.map((block) => normalizeBlock(block, blockSources[block.id])).sort((left, right) => left.blockRef.localeCompare(right.blockRef));
+  const headerBlockRefs = normalizedBlocks.filter((block) => block.layoutRole === "header").map((block) => block.blockRef);
+  const footerBlockRefs = normalizedBlocks.filter((block) => block.layoutRole === "footer").map((block) => block.blockRef);
+  return {
+    metadata: {
+      contractVersion: BUILDER_CONTRACT_VERSION,
+      uiVersion,
+      exportedAt,
+      source,
+      totalBlocks: normalizedBlocks.length
+    },
+    blocks: normalizedBlocks,
+    sharedLayout: {
+      canonicalLayoutKey: "_layout",
+      sections: {
+        header: {
+          sourceType: "website_navbar",
+          sourceOfTruth: "WebsiteNavBar",
+          aiAuthoring: "variant_request_only",
+          canonicalPayloadKey: "header",
+          allowedBlockRefs: headerBlockRefs
+        },
+        footer: {
+          sourceType: "shared_footer_page",
+          sourceOfTruth: "aliased/shared footer pages",
+          aiAuthoring: "variant_request_only",
+          canonicalPayloadKey: "footer",
+          allowedBlockRefs: footerBlockRefs
+        }
+      }
+    },
+    dynamicSources: {
+      blog_feed: {
+        sourceType: "blog_feed",
+        symbolic: true,
+        hydrationOwner: "dashtrack-ai",
+        hydrationPhase: "routing-build",
+        canonicalPayloadExpectation: "Keep blog feed requests symbolic in canonical page JSON until routing-build hydration resolves them.",
+        requiredFields: ["type"],
+        optionalFields: ["limit", "offset", "category", "tag", "featuredOnly"]
+      }
+    },
+    designTokens: {
+      canonicalSource: "theme_config",
+      derivedArtifacts: ["tailwind_css"],
+      requiredTokenFamilies: [...REQUIRED_TOKEN_FAMILIES],
+      requiredSemanticColorRoles: [...REQUIRED_SEMANTIC_COLOR_ROLES],
+      policy: "theme_config is canonical and tailwind_css must be derived from it; blocks should consume semantic tokens rather than hardcoded theme values."
+    },
+    pageRules: {
+      outputFormat: "route-map",
+      routeKeyPattern: "^/$|^/.+",
+      sharedLayoutKey: "_layout",
+      routeEntry: {
+        requiredKeys: ["pageId", "pageIds", "blocks"],
+        blocksKey: "blocks"
+      },
+      blockEntry: {
+        requiredKeys: ["block_name", "block_ref", "data"],
+        blockRefSource: "BuilderContractBundle.blocks[].blockRef",
+        blockNameSource: "BuilderContractBundle.blocks[].blockName"
+      },
+      sharedLayoutComposition: {
+        owner: "dashtrack-ai",
+        headerSource: "WebsiteNavBar",
+        footerSource: "aliased/shared footer pages"
+      },
+      dynamicHydration: {
+        symbolicInCanonicalPageJson: true,
+        owner: "dashtrack-ai",
+        phase: "routing-build"
+      }
+    }
+  };
+}
+
+export { BLOCK_REGISTRY, BUILDER_CONTRACT_VERSION, createBuilderContractBundle, getAllBlocks, getAllCategories, getBlockById, getBlocksByCategory, getBlocksBySemanticTag, searchBlocks };

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<HTMLButtonElement | HTMLAnchorElement | HTMLSpanElement>>;
+declare const SocialLinkIcon: React.ForwardRefExoticComponent<SocialLinkIconProps & React.RefAttributes<HTMLAnchorElement | HTMLButtonElement | 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<HTMLButtonElement | HTMLAnchorElement | HTMLSpanElement>>;
+declare const SocialLinkIcon: React.ForwardRefExoticComponent<SocialLinkIconProps & React.RefAttributes<HTMLAnchorElement | HTMLButtonElement | HTMLSpanElement>>;
 
 export { SocialLinkIcon, type SocialLinkIconDynamicIconProps, type SocialLinkIconProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensite/ui",
-  "version": "3.2.1",
+  "version": "3.2.3",
   "description": "Foundational UI component library for OpenSite Semantic Site Builder with tree-shakable exports and abstract styling",
   "keywords": [
     "react",
@@ -3422,10 +3422,10 @@
     "@page-speed/forms": "0.8.2",
     "@page-speed/icon": "0.1.2",
     "@page-speed/img": "0.4.9",
-    "@page-speed/lightbox": "0.2.1",
+    "@page-speed/lightbox": "^0.2.1",
     "@page-speed/maps": "0.2.4",
-    "@page-speed/markdown-to-jsx": "0.0.6",
-    "@page-speed/pdf-viewer": "0.1.9",
+    "@page-speed/markdown-to-jsx": "^0.0.7",
+    "@page-speed/pdf-viewer": "^0.1.9",
     "@page-speed/pressable": "0.0.7",
     "@page-speed/router": "1.0.2",
     "@page-speed/skins": "0.1.2",