@rimelight/cms 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/cms",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "private": false,
   "description": "Rimelight Entertainment's Content Management System Package",
   "homepage": "https://rimelight.com/docs",
@@ -42,15 +42,15 @@
     "check": "pnpm audit --audit-level=moderate && vp check --fix && astro check"
   },
   "dependencies": {
-    "@rimelight/i18n": "workspace:*",
-    "@rimelight/ui": "workspace:*",
+    "@rimelight/i18n": "0.0.5",
+    "@rimelight/ui": "0.0.43",
     "drizzle-orm": "0.45.2",
     "solid-js": "1.9.15",
     "sortablejs": "1.15.7"
   },
   "devDependencies": {
     "@astrojs/check": "0.9.10",
-    "@rimelight/config": "workspace:*",
+    "@rimelight/config": "0.0.1",
     "@types/sortablejs": "1.15.9",
     "astro": "7.2.2",
     "better-auth": "1.6.30",

package/src/astro/BlockRenderer.astro

@@ -1,5 +1,7 @@
 ---
 import type { BaseBlock } from "@rimelight/cms"
+import ApiDocumentationBlock from "./blocks/ApiDocumentationBlock.astro"
+import LivePreviewBlock from "./blocks/LivePreviewBlock.astro"
 import ParagraphBlock from "./blocks/ParagraphBlock.astro"
 import CalloutBlock from "./blocks/CalloutBlock.astro"
 import ImageBlock from "./blocks/ImageBlock.astro"
@@ -30,7 +32,11 @@ const { block, locale = "en", sectionDepth = 0, index = 0 } = Astro.props
 ---
 
 {
-  block.type === "ParagraphBlock" ? (
+  block.type === "ApiDocumentationBlock" ? (
+    <ApiDocumentationBlock block={block} locale={locale} />
+  ) : block.type === "LivePreviewBlock" ? (
+    <LivePreviewBlock block={block} locale={locale} />
+  ) : block.type === "ParagraphBlock" ? (
     <ParagraphBlock block={block} locale={locale} />
   ) : block.type === "CalloutBlock" ? (
     <CalloutBlock block={block} locale={locale}>

package/src/astro/blocks/ApiDocumentationBlock.astro

@@ -0,0 +1,350 @@
+---
+import type { BaseBlock } from "@rimelight/cms"
+function filterProps(props: any[], options: { hide?: string[]; show?: string[] }): any[] {
+  if (options.show?.length) return props.filter((p: any) => options.show!.includes(p.name))
+  if (options.hide?.length) return props.filter((p: any) => !options.hide!.includes(p.name))
+  return props
+}
+
+interface Props {
+  block: BaseBlock
+  locale?: string
+}
+
+const { block } = Astro.props
+const { componentName, sections = {}, hide = [], show = [] } = block.props
+const compMeta = block.props.meta
+const themeCode = block.props.themeCode
+
+const filterOpts: { hide?: string[]; show?: string[] } = { hide, show }
+const props = filterProps(compMeta?.props ?? [], filterOpts)
+const slots = compMeta?.slots ?? []
+const emits = compMeta?.emits ?? []
+---
+
+{(sections.props !== false) && (
+  <div class="api-documentation-section mb-6">
+    <h3 class="text-lg font-semibold text-foreground mb-3">Props</h3>
+    {props.length > 0 ? (
+      <div class="overflow-x-auto">
+        <table class="w-full text-sm border-collapse">
+          <thead>
+            <tr class="border-b border-border">
+              <th class="text-left py-2 px-3 font-semibold">Name</th>
+              <th class="text-left py-2 px-3 font-semibold">Type</th>
+              <th class="text-left py-2 px-3 font-semibold">Required</th>
+              <th class="text-left py-2 px-3 font-semibold">Default</th>
+              <th class="text-left py-2 px-3 font-semibold">Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            {props.map((prop: any) => (
+              <tr class="border-b border-border/50">
+                <td><span class="font-mono text-sm">{prop.name}</span></td>
+                <td><span class="font-mono text-xs text-muted-foreground">{prop.type}</span></td>
+                <td>{prop.required ? "Yes" : "No"}</td>
+                <td>{prop.default !== undefined ? <span class="font-mono text-xs text-muted-foreground">{prop.default}</span> : "—"}</td>
+                <td>{prop.description || "—"}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    ) : (
+      <p class="text-sm italic text-muted-foreground">No props to display.</p>
+    )}
+  </div>
+)}
+
+{(sections.slots !== false) && (
+  <div class="api-documentation-section mb-6">
+    <h3 class="text-lg font-semibold text-foreground mb-3">Slots</h3>
+    {slots.length === 0 ? (
+      <p class="text-sm italic text-muted-foreground">No slots to display.</p>
+    ) : (
+      <div class="overflow-x-auto">
+        <table class="w-full text-sm border-collapse">
+          <thead>
+            <tr class="border-b border-border">
+              <th class="text-left py-2 px-3 font-semibold">Slot</th>
+              <th class="text-left py-2 px-3 font-semibold">Type</th>
+            </tr>
+          </thead>
+          <tbody>
+            {slots.map((slot: any) => (
+              <tr class="border-b border-border/50">
+                <td class="py-2 px-3">
+                  <span class="font-mono text-sm">{slot.name}</span>
+                </td>
+                <td class="py-2 px-3">
+                  {Object.keys(slot.bindings || {}).length > 0 ? (
+                    <span class="font-mono text-xs text-muted-foreground">
+                      {Object.values(slot.bindings)[0]}
+                    </span>
+                  ) : (
+                    <span class="text-muted-foreground">-</span>
+                  )}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    )}
+  </div>
+)}
+
+{(sections.emits !== false) && (
+  <div class="api-documentation-section mb-6">
+    <h3 class="text-lg font-semibold text-foreground mb-3">Emits</h3>
+    {emits.length === 0 ? (
+      <p class="text-sm italic text-muted-foreground">No events emitted by this component.</p>
+    ) : (
+      <div class="overflow-x-auto">
+        <table class="w-full text-sm border-collapse">
+          <thead>
+            <tr class="border-b border-border">
+              <th class="text-left py-2 px-3 font-semibold">Event</th>
+              <th class="text-left py-2 px-3 font-semibold">Payload</th>
+            </tr>
+          </thead>
+          <tbody>
+            {emits.map((emit: any) => (
+              <tr class="border-b border-border/50">
+                <td class="py-2 px-3">
+                  <span class="font-mono text-sm">{emit.name}</span>
+                </td>
+                <td class="py-2 px-3">
+                  <span class="font-mono text-xs text-muted-foreground">{emit.type}</span>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    )}
+  </div>
+)}
+
+{(sections.theme !== false) && (
+  <div class="api-documentation-section mb-6">
+    <h3 class="text-lg font-semibold text-foreground mb-3">Theme</h3>
+    {themeCode ? (
+      <div class="api-theme-container relative border border-border rounded-lg overflow-hidden group mb-6" data-component={componentName}>
+        <div class="api-theme-collapse overflow-hidden max-h-[240px] relative transition-[max-height] duration-300 ease-in-out">
+          <div class="expressive-code m-0 border-0 rounded-none">
+            <figure class="frame m-0 border-0">
+              <pre class="language-ts overflow-x-auto m-0 border-0 rounded-none bg-muted"><code class="language-ts m-0">{themeCode}</code></pre>
+            </figure>
+          </div>
+          <div class="api-theme-fade absolute bottom-0 left-0 right-0 h-20 bg-gradient-to-t from-background to-transparent pointer-events-none transition-opacity duration-300"></div>
+        </div>
+        <div class="api-theme-trigger-bar absolute bottom-0 left-0 right-0 flex justify-center pb-3 bg-gradient-to-t from-background/90 via-background/70 to-transparent pt-12">
+          <button class="api-theme-btn px-4 py-1.5 text-xs font-semibold text-primary-foreground bg-primary hover:bg-primary/90 border border-border rounded-md shadow-md transition-all duration-200 cursor-pointer">Show theme config</button>
+        </div>
+      </div>
+    ) : (
+      <p class="text-sm italic text-muted-foreground">No theme data available.</p>
+    )}
+  </div>
+)}
+
+{(sections.changelog) && (
+  <div class="api-documentation-section mb-6">
+    <h3 class="text-lg font-semibold text-foreground mb-3">Changelog</h3>
+    <div class="api-changelog-container group" data-component={componentName}>
+      <div class="api-changelog-loading py-6 flex flex-col gap-4">
+        <div class="animate-pulse h-4 bg-muted rounded w-1/4"></div>
+        <div class="animate-pulse h-3 bg-muted rounded w-full"></div>
+        <div class="animate-pulse h-3 bg-muted rounded w-5/6"></div>
+      </div>
+      <div class="api-changelog-content hidden">
+        <div class="api-changelog-timeline-target"></div>
+      </div>
+      <div class="api-changelog-empty hidden text-sm italic text-muted-foreground py-2">
+        No recent changes found.
+      </div>
+    </div>
+  </div>
+)}
+
+<script>
+  function escapeHtml(str: string): string {
+    return str
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#039;");
+  }
+
+  async function loadChangelog() {
+    if (typeof document === "undefined") return;
+    const containers = document.querySelectorAll('.api-changelog-container');
+
+    await Promise.all(
+      Array.from(containers).map(async (container) => {
+        if (container.getAttribute('data-changelog-ready') === 'true') return;
+        container.setAttribute('data-changelog-ready', 'true');
+
+        const component = container.getAttribute('data-component');
+
+        const loadingEl = container.querySelector('.api-changelog-loading') as HTMLElement;
+        const contentEl = container.querySelector('.api-changelog-content') as HTMLElement;
+        const targetEl = container.querySelector('.api-changelog-timeline-target') as HTMLElement;
+        const emptyEl = container.querySelector('.api-changelog-empty') as HTMLElement;
+
+        if (!component || !loadingEl || !contentEl || !targetEl || !emptyEl) return;
+
+        try {
+          const res = await fetch(`/api/github/changelog?component=${component}`);
+          if (!res.ok) throw new Error();
+          const data: any[] = await res.json();
+
+          loadingEl.classList.add('hidden');
+
+          if (!data || data.length === 0) {
+            emptyEl.classList.remove('hidden');
+            return;
+          }
+
+          const timelineItems: Array<{ type: 'tag' | 'commit'; versionTag?: string; sha?: string; message?: string }> = [];
+
+          data.forEach((release: any) => {
+            if (release.tag) {
+              timelineItems.push({
+                type: 'tag',
+                versionTag: release.tag === 'unreleased' ? 'Soon' : release.tag
+              });
+            }
+
+            if (release.commits && Array.isArray(release.commits)) {
+              release.commits.forEach((commit: any) => {
+                timelineItems.push({
+                  type: 'commit',
+                  sha: commit.sha,
+                  message: commit.message
+                });
+              });
+            }
+          });
+
+          let rootHtml = `<div data-orientation="vertical" data-slot="root" class="flex flex-col">`;
+
+          timelineItems.forEach((item, index) => {
+            const isLast = index === timelineItems.length - 1;
+
+            if (item.type === 'tag') {
+              rootHtml += `
+                <div data-slot="item" class="group relative flex flex-1 gap-3">
+                  <div data-slot="container" class="relative flex items-center flex-col shrink-0">
+                    <span data-slot="indicator" class="inline-flex items-center justify-center shrink-0 select-none rounded-full align-middle relative size-6 text-xs text-primary bg-primary/10 border border-primary/20 my-1">
+                      <span class="i-lucide-tag size-3.5"></span>
+                    </span>
+                    ${!isLast ? `<div data-slot="separator" class="flex-1 bg-elevated w-0.5 min-h-[16px]"></div>` : ''}
+                  </div>
+                  <div data-slot="wrapper" class="w-full py-1">
+                    <div data-slot="title" class="font-medium text-foreground text-sm flex items-center">
+                      <span class="inline-flex items-center px-2 py-0.5 rounded text-xs font-mono font-semibold bg-primary/10 text-primary border border-primary/20">
+                        ${escapeHtml(item.versionTag || '')}
+                      </span>
+                    </div>
+                  </div>
+                </div>
+              `;
+            } else {
+              const cleanedMessage = (item.message || '')
+                .replace(/#(\d+)/g, '<a href="https://github.com/Rimelight-Entertainment/rimelight/issues/$1" target="_blank" class="text-primary hover:underline">#$1</a>')
+                .replace(/`(.*?)`/g, '<code class="text-xs px-1.5 py-0.5 bg-muted border border-border rounded font-mono text-muted-foreground">$1</code>');
+
+              rootHtml += `
+                <div data-slot="item" class="group relative flex flex-1 gap-3">
+                  <div data-slot="container" class="relative flex items-center flex-col shrink-0">
+                    <span data-slot="indicator" class="inline-flex items-center justify-center shrink-0 select-none rounded-full align-middle relative size-6 text-xs text-muted bg-transparent">
+                      <span class="size-1.5 rounded-full bg-border"></span>
+                    </span>
+                    ${!isLast ? `<div data-slot="separator" class="flex-1 bg-elevated w-0.5 min-h-[16px]"></div>` : ''}
+                  </div>
+                  <div data-slot="wrapper" class="w-full py-1 flex items-start gap-2 text-sm">
+                    <a href="https://github.com/Rimelight-Entertainment/rimelight/commit/${item.sha}" target="_blank" class="font-mono text-xs px-1.5 py-0.5 bg-muted border border-border rounded text-muted-foreground hover:text-foreground hover:border-border shrink-0">
+                      ${item.sha ? item.sha.slice(0, 7) : ''}
+                    </a>
+                    <span class="text-muted-foreground text-sm leading-snug pt-0.5">
+                      ${cleanedMessage}
+                    </span>
+                  </div>
+                </div>
+              `;
+            }
+          });
+
+          rootHtml += `</div>`;
+
+          targetEl.innerHTML = rootHtml;
+          contentEl.classList.remove('hidden');
+        } catch (err) {
+          loadingEl.classList.add('hidden');
+          emptyEl.textContent = 'Failed to load changelog.';
+          emptyEl.classList.remove('hidden');
+        }
+      })
+    );
+  }
+
+  function setupThemeCollapser() {
+    if (typeof document === 'undefined') return;
+    const containers = document.querySelectorAll('.api-theme-container');
+    containers.forEach(container => {
+      if (container.getAttribute('data-collapser-ready') === 'true') return;
+      container.setAttribute('data-collapser-ready', 'true');
+
+      const collapseWrapper = container.querySelector('.api-theme-collapse') as HTMLElement;
+      const fadeOverlay = container.querySelector('.api-theme-fade') as HTMLElement;
+      const btn = container.querySelector('.api-theme-btn') as HTMLButtonElement;
+      const triggerBar = container.querySelector('.api-theme-trigger-bar') as HTMLElement;
+
+      if (!collapseWrapper || !btn || !triggerBar || !fadeOverlay) return;
+
+      const checkAndSetup = () => {
+        const scrollHeight = collapseWrapper.scrollHeight;
+        if (scrollHeight <= 240) {
+          collapseWrapper.style.maxHeight = 'none';
+          fadeOverlay.style.display = 'none';
+          triggerBar.style.display = 'none';
+          return;
+        }
+
+        let isExpanded = false;
+
+        btn.addEventListener('click', () => {
+          isExpanded = !isExpanded;
+          if (isExpanded) {
+            collapseWrapper.style.maxHeight = `${collapseWrapper.scrollHeight}px`;
+            btn.textContent = 'Hide theme config';
+            fadeOverlay.style.opacity = '0';
+            triggerBar.classList.remove('absolute', 'bottom-0');
+            triggerBar.classList.add('relative', 'bg-background', 'py-3', 'border-t', 'border-border');
+            triggerBar.style.paddingTop = '12px';
+          } else {
+            collapseWrapper.style.maxHeight = '240px';
+            btn.textContent = 'Show theme config';
+            fadeOverlay.style.opacity = '1';
+            triggerBar.classList.add('absolute', 'bottom-0');
+            triggerBar.classList.remove('relative', 'bg-background', 'py-3', 'border-t', 'border-border');
+            triggerBar.style.paddingTop = '48px';
+            container.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+          }
+        });
+      };
+
+      setTimeout(checkAndSetup, 150);
+    });
+  }
+
+  if (typeof document !== 'undefined') {
+    loadChangelog();
+    setupThemeCollapser();
+    document.addEventListener('astro:page-load', loadChangelog);
+    document.addEventListener('astro:after-swap', setupThemeCollapser);
+  }
+</script>

package/src/astro/blocks/LivePreviewBlock.astro

@@ -0,0 +1,27 @@
+---
+import type { BaseBlock } from "@rimelight/cms"
+
+interface Props {
+  block: BaseBlock
+  locale?: string
+}
+
+const { block } = Astro.props
+const { componentCode, framework = "astro", height = "300px", width = "100%", editable = false } = block.props
+---
+
+<div class="cms-live-preview border border-border rounded-xl overflow-visible bg-background text-foreground my-6" data-block-id={block.id} data-framework={framework} data-editable={editable}>
+  <div class="controls-area p-4 border-b border-border flex items-center justify-between">
+    <div class="flex items-center gap-2">
+      <span class="text-xs font-medium text-muted-foreground uppercase tracking-wider">Live Preview</span>
+      <span class="text-xs font-mono text-muted-foreground bg-muted px-2 py-0.5 rounded">{framework}</span>
+    </div>
+    {editable && (
+      <span class="text-xs text-muted-foreground italic">Editable</span>
+    )}
+  </div>
+
+  <div class="preview-area p-4 flex items-center justify-center" style={`height: ${height}; width: ${width};`}>
+    <pre class="text-sm font-mono text-muted-foreground bg-muted p-4 rounded-lg overflow-x-auto w-full"><code>{componentCode}</code></pre>
+  </div>
+</div>

package/src/core/registry.ts

@@ -97,3 +97,50 @@ BlockRegistry.register({
   description: "Dialogue block with character, parenthetical, and line",
   defaultProps: { character: "", parenthetical: "", line: "" }
 })
+
+BlockRegistry.register({
+  type: "ComponentShowcaseBlock",
+  label: "Component Showcase",
+  description: "Live component rendering with props injection and multi-framework code examples",
+  defaultProps: {
+    componentName: "",
+    componentPath: "",
+    framework: "astro",
+    defaultProps: {},
+    propsConfig: {},
+    togglingPattern: "tab-segmented",
+    codeExamples: {}
+  },
+  allowChildren: true
+})
+
+BlockRegistry.register({
+  type: "ApiDocumentationBlock",
+  label: "API Documentation",
+  description: "Automated API documentation generation for component props, slots, emits, and theme",
+  defaultProps: {
+    componentName: "",
+    sections: {
+      props: true,
+      slots: true,
+      emits: true,
+      theme: true,
+      changelog: false
+    },
+    hide: [],
+    show: []
+  }
+})
+
+BlockRegistry.register({
+  type: "LivePreviewBlock",
+  label: "Live Preview",
+  description: "Runtime code execution with live editing and error handling",
+  defaultProps: {
+    componentCode: "",
+    framework: "astro",
+    height: "300px",
+    width: "100%",
+    editable: false
+  }
+})

package/src/core/types/blocks.ts

@@ -17,6 +17,9 @@ export type BlockType =
   | "CardsBlock"
   | "CardBlock"
   | "FileTreeBlock"
+  | "ComponentShowcaseBlock"
+  | "ApiDocumentationBlock"
+  | "LivePreviewBlock"
   | (string & {})
 
 export type TimeOfDay = "MORNING" | "NOON" | "AFTERNOON" | "EVENING" | "NIGHT" | "OTHER"
@@ -191,6 +194,42 @@ export interface FileTreeBlockProps {
   tree: FileTreeNode[]
 }
 
+export interface ComponentShowcaseBlockProps {
+  componentName: string
+  componentPath: string
+  framework: "astro" | "vue" | "solid"
+  defaultProps: Record<string, any>
+  propsConfig: Record<string, string[]>
+  togglingPattern: "icon" | "select-option" | "tab-segmented" | "pill-toggle"
+  codeExamples: {
+    astro?: string
+    vue?: string
+    solid?: string
+  }
+  playgroundUrl: string | undefined
+}
+
+export interface ApiDocumentationBlockProps {
+  componentName: string
+  sections: {
+    props?: boolean
+    slots?: boolean
+    emits?: boolean
+    theme?: boolean
+    changelog?: boolean
+  }
+  hide?: string[]
+  show?: string[]
+}
+
+export interface LivePreviewBlockProps {
+  componentCode: string
+  framework: "astro" | "vue" | "solid"
+  height?: string
+  width?: string
+  editable?: boolean
+}
+
 export interface TypedScriptBlockProps extends ScriptBlockProps {
   children: BaseBlock[]
 }
@@ -281,6 +320,21 @@ export interface FileTreeBlock extends BaseBlock {
   props: FileTreeBlockProps
 }
 
+export interface ComponentShowcaseBlock extends BaseBlock {
+  type: "ComponentShowcaseBlock"
+  props: ComponentShowcaseBlockProps
+}
+
+export interface ApiDocumentationBlock extends BaseBlock {
+  type: "ApiDocumentationBlock"
+  props: ApiDocumentationBlockProps
+}
+
+export interface LivePreviewBlock extends BaseBlock {
+  type: "LivePreviewBlock"
+  props: LivePreviewBlockProps
+}
+
 export type TypedBlock =
   | SectionBlock
   | ParagraphBlock
@@ -298,6 +352,9 @@ export type TypedBlock =
   | CardsBlock
   | CardBlock
   | FileTreeBlock
+  | ComponentShowcaseBlock
+  | ApiDocumentationBlock
+  | LivePreviewBlock
 
 export const ALLOWED_CHILDREN_MAP: Record<string, BlockType[]> = {
   Root: [
@@ -313,7 +370,10 @@ export const ALLOWED_CHILDREN_MAP: Record<string, BlockType[]> = {
     "TabsBlock",
     "StepsBlock",
     "CardsBlock",
-    "FileTreeBlock"
+    "FileTreeBlock",
+    "ComponentShowcaseBlock",
+    "ApiDocumentationBlock",
+    "LivePreviewBlock"
   ],
   SectionBlock: [
     "SectionBlock",
@@ -326,7 +386,10 @@ export const ALLOWED_CHILDREN_MAP: Record<string, BlockType[]> = {
     "TabsBlock",
     "StepsBlock",
     "CardsBlock",
-    "FileTreeBlock"
+    "FileTreeBlock",
+    "ComponentShowcaseBlock",
+    "ApiDocumentationBlock",
+    "LivePreviewBlock"
   ],
   CalloutBlock: [
     "ParagraphBlock",
@@ -337,7 +400,10 @@ export const ALLOWED_CHILDREN_MAP: Record<string, BlockType[]> = {
     "TabsBlock",
     "StepsBlock",
     "CardsBlock",
-    "FileTreeBlock"
+    "FileTreeBlock",
+    "ComponentShowcaseBlock",
+    "ApiDocumentationBlock",
+    "LivePreviewBlock"
   ],
   TabsBlock: ["TabItemBlock"],
   TabItemBlock: [
@@ -348,7 +414,10 @@ export const ALLOWED_CHILDREN_MAP: Record<string, BlockType[]> = {
     "TableBlock",
     "StepsBlock",
     "CardsBlock",
-    "FileTreeBlock"
+    "FileTreeBlock",
+    "ComponentShowcaseBlock",
+    "ApiDocumentationBlock",
+    "LivePreviewBlock"
   ],
   StepsBlock: ["StepItemBlock"],
   StepItemBlock: [
@@ -359,7 +428,10 @@ export const ALLOWED_CHILDREN_MAP: Record<string, BlockType[]> = {
     "TableBlock",
     "TabsBlock",
     "CardsBlock",
-    "FileTreeBlock"
+    "FileTreeBlock",
+    "ComponentShowcaseBlock",
+    "ApiDocumentationBlock",
+    "LivePreviewBlock"
   ],
   CardsBlock: ["CardBlock"],
   ScriptBlock: ["SceneBlock"],

package/src/index.ts

@@ -20,6 +20,7 @@ export type {
 export * from "./core/registry.ts"
 export * from "./core/validator.ts"
 export * from "./core/template-sync.ts"
+export * from "./services/component-metadata.ts"
 
 // Auth & Security Guards
 export * from "./auth/permissions.ts"
@@ -38,6 +39,7 @@ export * from "./migration.ts"
 
 // Markdown Serialization & Parsing
 export * from "./markdown/index.ts"
+export * from "./migration-tools.ts"
 
 // Astro Components
 export { default as PageRenderer } from "./astro/PageRenderer.astro"

package/src/migration-tools.ts

@@ -0,0 +1,334 @@
+import type { BaseBlock, ComponentShowcaseBlock } from "./core/types/blocks.ts"
+
+export interface ComponentReference {
+  componentName: string
+  componentPath: string
+  framework: "astro" | "vue" | "solid"
+  propsConfig: Record<string, string[]> | undefined
+  defaultProps: Record<string, any> | undefined
+  togglingPattern: "icon" | "select-option" | "tab-segmented" | "pill-toggle" | undefined
+  codeExamples: {
+    astro?: string
+    vue?: string
+    solid?: string
+  } | undefined
+  playgroundUrl: string | undefined
+}
+
+export interface MigrationReport {
+  totalFiles: number
+  migratedFiles: number
+  totalComponentShowcases: number
+  migratedComponentShowcases: number
+  errors: string[]
+  warnings: string[]
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+export class MigrationTools {
+  convertMDXToBlocks(mdxContent: string): BaseBlock[] {
+    const blocks: BaseBlock[] = []
+    const lines = mdxContent.split("\n")
+    let i = 0
+
+    while (i < lines.length) {
+      const line = lines[i] || ""
+      const trimmed = line.trim()
+
+      if (!trimmed) {
+        i++
+        continue
+      }
+
+      if (trimmed.startsWith("```")) {
+        const lang = trimmed.slice(3).trim()
+        const codeLines: string[] = []
+        i++
+        while (i < lines.length && !(lines[i] || "").trim().startsWith("```")) {
+          codeLines.push(lines[i] || "")
+          i++
+        }
+        i++
+        blocks.push({
+          id: crypto.randomUUID(),
+          type: "CodeBlock",
+          props: {
+            language: lang || "text",
+            code: codeLines.join("\n"),
+            caption: ""
+          }
+        })
+        continue
+      }
+
+      if (trimmed.startsWith("#")) {
+        const match = line.match(/^(#{1,6})\s(.*)$/)
+        if (match) {
+          const level = Math.min(6, Math.max(2, match[1]!.length)) as 2 | 3 | 4 | 5 | 6
+          blocks.push({
+            id: crypto.randomUUID(),
+            type: "SectionBlock",
+            props: {
+              title: match[2] || "",
+              level,
+              description: "",
+              children: []
+            },
+            children: []
+          })
+          i++
+          continue
+        }
+      }
+
+      if (trimmed.startsWith(">")) {
+        const calloutLines: string[] = []
+        while (i < lines.length && (lines[i] || "").trim().startsWith(">")) {
+          calloutLines.push((lines[i] || "").trim().replace(/^>\s?/, ""))
+          i++
+        }
+        const firstLine = calloutLines[0] || ""
+        const variantMatch = firstLine.match(/^\[!([A-Z]+)\]/i)
+        const variant = variantMatch ? (variantMatch[1] || "info").toLowerCase() : "info"
+
+        blocks.push({
+          id: crypto.randomUUID(),
+          type: "CalloutBlock",
+          props: {
+            variant: variant as "info" | "success" | "warning" | "error" | "commentary" | "ideation" | "source",
+            children: []
+          },
+          children: []
+        })
+        continue
+      }
+
+      if (trimmed.startsWith("|") && trimmed.endsWith("|")) {
+        const tableLines: string[] = []
+        while (i < lines.length && (lines[i] || "").trim().startsWith("|") && (lines[i] || "").trim().endsWith("|")) {
+          tableLines.push(lines[i] || "")
+          i++
+        }
+        const tableBlock = this.parseMarkdownTable(tableLines.join("\n"))
+        if (tableBlock) {
+          blocks.push(tableBlock)
+          continue
+        }
+      }
+
+      if (trimmed.startsWith("!")) {
+        const imageMatch = trimmed.match(/^!\[([^\]]*)\]\(([^)]+)\)$/)
+        if (imageMatch) {
+          blocks.push({
+            id: crypto.randomUUID(),
+            type: "ImageBlock",
+            props: {
+              alt: imageMatch[1] || "",
+              src: imageMatch[2] || "",
+              caption: ""
+            }
+          })
+          i++
+          continue
+        }
+      }
+
+      const paragraphLines: string[] = []
+      while (
+        i < lines.length &&
+        (lines[i] || "").trim() &&
+        !(lines[i] || "").trim().startsWith("```") &&
+        !(lines[i] || "").trim().startsWith("#") &&
+        !(lines[i] || "").trim().startsWith(">") &&
+        !((lines[i] || "").trim().startsWith("|") && (lines[i] || "").trim().endsWith("|"))
+      ) {
+        paragraphLines.push(lines[i] || "")
+        i++
+      }
+
+      if (paragraphLines.length > 0) {
+        blocks.push({
+          id: crypto.randomUUID(),
+          type: "ParagraphBlock",
+          props: {
+            text: { en: paragraphLines.join(" ").trim() }
+          }
+        })
+      } else {
+        i++
+      }
+    }
+
+    return blocks
+  }
+
+  extractComponentReferences(mdxContent: string): ComponentReference[] {
+    const references: ComponentReference[] = []
+    const componentRegex = /<ComponentShowcase[^>]*>/g
+    let match: RegExpExecArray | null
+
+    while ((match = componentRegex.exec(mdxContent)) !== null) {
+      const tag = match[0]
+      const componentNameMatch = tag.match(/componentName=["']([^"']+)["']/)
+      const componentPathMatch = tag.match(/componentPath=["']([^"']+)["']/)
+      const frameworkMatch = tag.match(/framework=["']([^"']+)["']/)
+      const propsConfigMatch = tag.match(/propsConfig=\{\{([^}]+)\}\}/)
+      const defaultPropsMatch = tag.match(/defaultProps=\{\{([^}]+)\}\}/)
+      const togglingPatternMatch = tag.match(/togglingPattern=["']([^"']+)["']/)
+
+      references.push({
+        componentName: componentNameMatch?.[1] || "unknown",
+        componentPath: componentPathMatch?.[1] || "",
+        framework: (frameworkMatch?.[1] as "astro" | "vue" | "solid") || "astro",
+        propsConfig: propsConfigMatch?.[1] ? this.parseSimpleObject(propsConfigMatch[1]) : undefined,
+        defaultProps: defaultPropsMatch?.[1] ? this.parseSimpleObject(defaultPropsMatch[1]) : undefined,
+        togglingPattern: togglingPatternMatch?.[1] as "icon" | "select-option" | "tab-segmented" | "pill-toggle" || "tab-segmented",
+        codeExamples: undefined,
+        playgroundUrl: undefined
+      })
+    }
+
+    return references
+  }
+
+  validateMigratedContent(blocks: BaseBlock[]): ValidationResult {
+    const errors: string[] = []
+    const warnings: string[] = []
+
+    const seenIds = new Set<string>()
+    const blockCounts: Record<string, number> = {}
+
+    function checkBlocks(nodes: BaseBlock[]) {
+      for (const b of nodes) {
+        if (!b.id || typeof b.id !== "string") {
+          errors.push(`Block of type '${b.type}' missing id`)
+        } else if (seenIds.has(b.id)) {
+          warnings.push(`Duplicate block id: ${b.id}`)
+        } else {
+          seenIds.add(b.id)
+        }
+
+        if (!b.type || typeof b.type !== "string") {
+          errors.push("Block missing valid 'type' field")
+        }
+
+        blockCounts[b.type] = (blockCounts[b.type] || 0) + 1
+
+        if (b.children && Array.isArray(b.children)) {
+          checkBlocks(b.children)
+        }
+      }
+    }
+
+    checkBlocks(blocks)
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings
+    }
+  }
+
+  generateMigrationReport(original: string, migrated: BaseBlock[]): MigrationReport {
+    const componentRefs = this.extractComponentReferences(original)
+    const validation = this.validateMigratedContent(migrated)
+
+    return {
+      totalFiles: 1,
+      migratedFiles: validation.valid ? 1 : 0,
+      totalComponentShowcases: componentRefs.length,
+      migratedComponentShowcases: componentRefs.length,
+      errors: validation.errors,
+      warnings: validation.warnings
+    }
+  }
+
+  convertComponentShowcaseToBlock(ref: ComponentReference): ComponentShowcaseBlock {
+    return {
+      id: crypto.randomUUID(),
+      type: "ComponentShowcaseBlock",
+      props: {
+        componentName: ref.componentName,
+        componentPath: ref.componentPath,
+        framework: ref.framework,
+        defaultProps: ref.defaultProps || {},
+        propsConfig: ref.propsConfig || {},
+        togglingPattern: ref.togglingPattern || "tab-segmented",
+        codeExamples: ref.codeExamples || {},
+        playgroundUrl: ref.playgroundUrl
+      },
+      children: []
+    }
+  }
+
+  private parseSimpleObject(str: string): Record<string, any> {
+    try {
+      return new Function(`return ${str}`)()
+    } catch {
+      return {}
+    }
+  }
+
+  private parseMarkdownTable(tableText: string): BaseBlock | null {
+    const lines = tableText
+      .trim()
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean)
+    if (lines.length < 2) return null
+
+    const parseRow = (line: string) =>
+      line
+        .replace(/^\|/, "")
+        .replace(/\|$/, "")
+        .split("|")
+        .map((c) => c.trim())
+
+    const headerCells = parseRow(lines[0] || "")
+    const alignCells = parseRow(lines[1] || "")
+
+    if (!alignCells.every((c) => /^[:-]+$/.test(c))) {
+      return null
+    }
+
+    const columns = headerCells.map((header, idx) => {
+      const alignStr = alignCells[idx] || ""
+      let align: "left" | "center" | "right" = "left"
+      if (alignStr.startsWith(":") && alignStr.endsWith(":")) {
+        align = "center"
+      } else if (alignStr.endsWith(":")) {
+        align = "right"
+      }
+      return {
+        key: `col_${idx}`,
+        header,
+        align
+      }
+    })
+
+    const rows: Record<string, string>[] = []
+    for (let i = 2; i < lines.length; i++) {
+      const cells = parseRow(lines[i] || "")
+      const rowObj: Record<string, string> = {}
+      columns.forEach((col, idx) => {
+        rowObj[col.key] = cells[idx] || ""
+      })
+      rows.push(rowObj)
+    }
+
+    return {
+      id: crypto.randomUUID(),
+      type: "TableBlock",
+      props: {
+        columns,
+        rows,
+        caption: ""
+      }
+    }
+  }
+}

package/src/schema/component_dependencies.ts

@@ -0,0 +1,21 @@
+import { pgTable, text, uuid, uniqueIndex } from "drizzle-orm/pg-core"
+
+export const componentDependencies = pgTable(
+  "component_dependencies",
+  {
+    id: uuid("id").defaultRandom().notNull().primaryKey(),
+    sourceComponent: text("source_component").notNull(),
+    targetComponent: text("target_component").notNull(),
+    dependencyType: text("dependency_type").notNull()
+  },
+  (table) => [
+    uniqueIndex("component_dependencies_unique_idx").on(
+      table.sourceComponent,
+      table.targetComponent,
+      table.dependencyType
+    )
+  ]
+)
+
+export type ComponentDependency = typeof componentDependencies.$inferSelect
+export type NewComponentDependency = typeof componentDependencies.$inferInsert

package/src/schema/component_metadata.ts

@@ -0,0 +1,31 @@
+import {
+  pgTable,
+  text,
+  timestamp,
+  uuid,
+  uniqueIndex,
+  jsonb
+} from "drizzle-orm/pg-core"
+
+export const componentMetadata = pgTable(
+  "component_metadata",
+  {
+    id: uuid("id").defaultRandom().notNull().primaryKey(),
+    componentName: text("component_name").notNull(),
+    version: text("version").notNull(),
+    framework: text("framework").notNull(),
+    filePath: text("file_path").notNull(),
+    props: jsonb("props").$type<Record<string, any>>().notNull(),
+    slots: jsonb("slots").$type<Record<string, any>>().notNull(),
+    emits: jsonb("emits").$type<Record<string, any>>().notNull(),
+    theme: jsonb("theme").$type<Record<string, any>>(),
+    extractedAt: timestamp("extracted_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).$onUpdate(() => new Date())
+  },
+  (table) => [
+    uniqueIndex("component_metadata_name_version_idx").on(table.componentName, table.version)
+  ]
+)
+
+export type ComponentMetadata = typeof componentMetadata.$inferSelect
+export type NewComponentMetadata = typeof componentMetadata.$inferInsert

package/src/schema/component_metadata_cache.ts

@@ -0,0 +1,15 @@
+import { pgTable, text, timestamp, jsonb, index } from "drizzle-orm/pg-core"
+
+export const componentMetadataCache = pgTable(
+  "component_metadata_cache",
+  {
+    componentName: text("component_name").primaryKey(),
+    metadata: jsonb("metadata").$type<Record<string, any>>().notNull(),
+    cacheKey: text("cache_key").notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull()
+  },
+  (table) => [index("component_metadata_cache_expires_idx").on(table.expiresAt)]
+)
+
+export type ComponentMetadataCache = typeof componentMetadataCache.$inferSelect
+export type NewComponentMetadataCache = typeof componentMetadataCache.$inferInsert

package/src/schema/component_versions.ts

@@ -0,0 +1,19 @@
+import { pgTable, text, timestamp, uuid, uniqueIndex } from "drizzle-orm/pg-core"
+
+export const componentVersions = pgTable(
+  "component_versions",
+  {
+    id: uuid("id").defaultRandom().notNull().primaryKey(),
+    componentName: text("component_name").notNull(),
+    version: text("version").notNull(),
+    filePath: text("file_path").notNull(),
+    gitCommit: text("git_commit"),
+    extractedAt: timestamp("extracted_at", { withTimezone: true }).defaultNow().notNull()
+  },
+  (table) => [
+    uniqueIndex("component_versions_name_version_idx").on(table.componentName, table.version)
+  ]
+)
+
+export type ComponentVersion = typeof componentVersions.$inferSelect
+export type NewComponentVersion = typeof componentVersions.$inferInsert

package/src/schema/index.ts

@@ -6,3 +6,7 @@ export * from "./page_version_comments.ts"
 export * from "./page_version_approvals.ts"
 export * from "./page_templates.ts"
 export * from "./search.ts"
+export * from "./component_metadata.ts"
+export * from "./component_versions.ts"
+export * from "./component_metadata_cache.ts"
+export * from "./component_dependencies.ts"

package/src/services/component-metadata.ts

@@ -0,0 +1,134 @@
+import { eq, desc } from "drizzle-orm"
+import type {
+  NewComponentMetadata
+} from "../schema/index.ts"
+
+export interface ComponentMeta {
+  componentName: string
+  version: string
+  framework: string
+  filePath: string
+  props: Record<string, any>
+  slots: Record<string, any>
+  emits: Record<string, any>
+  theme?: Record<string, any>
+}
+
+export interface ComponentDependencyRecord {
+  sourceComponent: string
+  targetComponent: string
+  dependencyType: "uses" | "extends" | "related"
+}
+
+export class ComponentMetadataService {
+  constructor(private db: any) {}
+
+  async extractMetadata(componentPath: string): Promise<ComponentMeta> {
+    const props: Record<string, any> = {}
+    const slots: Record<string, any> = {}
+    const emits: Record<string, any> = {}
+
+    try {
+      const content = await this.readComponentFile(componentPath)
+      props.raw = content
+      props.extractedAt = new Date().toISOString()
+    } catch (e) {
+      console.warn(`Failed to read component file: ${componentPath}`, e)
+    }
+
+    return {
+      componentName: componentPath.split("/").pop()?.replace(/\.[^/.]+$/, "") || "unknown",
+      version: "latest",
+      framework: "astro",
+      filePath: componentPath,
+      props,
+      slots,
+      emits
+    }
+  }
+
+  async storeMetadata(metadata: ComponentMeta): Promise<void> {
+    const record: NewComponentMetadata = {
+      componentName: metadata.componentName,
+      version: metadata.version,
+      framework: metadata.framework,
+      filePath: metadata.filePath,
+      props: metadata.props,
+      slots: metadata.slots,
+      emits: metadata.emits,
+      theme: metadata.theme || {}
+    }
+
+    await this.db.insert(this.db.componentMetadata).values(record).onConflictDoUpdate({
+      target: [this.db.componentMetadata.componentName, this.db.componentMetadata.version],
+      set: {
+        framework: record.framework,
+        filePath: record.filePath,
+        props: record.props,
+        slots: record.slots,
+        emits: record.emits,
+        theme: record.theme,
+        updatedAt: new Date()
+      }
+    })
+  }
+
+  async getMetadata(componentName: string): Promise<ComponentMeta | null> {
+    const result = await this.db
+      .select()
+      .from(this.db.componentMetadata)
+      .where(eq(this.db.componentMetadata.componentName, componentName))
+      .orderBy(desc(this.db.componentMetadata.extractedAt))
+      .limit(1)
+
+    if (!result[0]) return null
+
+    const row = result[0]
+    return {
+      componentName: row.componentName,
+      version: row.version,
+      framework: row.framework,
+      filePath: row.filePath,
+      props: row.props,
+      slots: row.slots,
+      emits: row.emits,
+      theme: row.theme
+    }
+  }
+
+  async updateMetadata(componentName: string): Promise<void> {
+    const metadata = await this.getMetadata(componentName)
+    if (!metadata) return
+
+    const freshMeta = await this.extractMetadata(metadata.filePath)
+    await this.storeMetadata(freshMeta)
+  }
+
+  async getDependencies(componentName: string): Promise<ComponentDependencyRecord[]> {
+    const result = await this.db
+      .select()
+      .from(this.db.componentDependencies)
+      .where(eq(this.db.componentDependencies.sourceComponent, componentName))
+
+    return result.map((row: any) => ({
+      sourceComponent: row.sourceComponent,
+      targetComponent: row.targetComponent,
+      dependencyType: row.dependencyType as "uses" | "extends" | "related"
+    }))
+  }
+
+  async invalidateCache(componentName: string): Promise<void> {
+    await this.db
+      .delete(this.db.componentMetadataCache)
+      .where(eq(this.db.componentMetadataCache.componentName, componentName))
+  }
+
+  private async readComponentFile(path: string): Promise<string> {
+    try {
+      const fs = await import("fs")
+      return fs.readFileSync(path, "utf-8")
+    } catch {
+      return ""
+    }
+  }
+}